docs: teach the SemanticAnnotation object form (unit, intrinsicDomain)

[zl190]

What

semantic_types accepts Record<string, string | SemanticAnnotation>, and unit / intrinsicDomain are what gate currency and percent axis formatting. But the skill, the MCP tool schema, and the docs all show only the bare-string form — so agents (the primary authors) never find the annotation object, and charts fall back to plain number formatting.

Verified against flint-chart@0.2.2 (Vega-Lite backend):

Input	Axis labels
"revenue": "Price"	,.12~g (plain numbers)
"revenue": { "semanticType": "Price", "unit": "USD" }	'$' + format(datum.value, ',.2f')
"share": { "semanticType": "Percentage", "intrinsicDomain": [0, 1] }	.0~% + domainMax: 1
"rating": { "semanticType": "Score", "intrinsicDomain": [1, 5] }	scale.domain: [1, 5]

Changes

• agent-skills/flint-chart-author/SKILL.md — type semantic_types as Record<string, string | SemanticAnnotation> to match types.ts; adjust the two Price / Percentage bullets that imply bare strings already produce this formatting; add an "Annotation objects" section with the verified effects and when to use them; extend the validation checklist.
• packages/flint-mcp/src/tools/schemas.ts — describe the annotation object form in the semantic_types schema, so MCP agents can find it from the tool schema alone.
• packages/flint-mcp/assets/flint-chart-author.SKILL.md — synced (enforced by server.test.ts).
• README.md — "70+ semantic types" → "40+" (the registry currently ships 44). If "70+" counts planned types, happy to revert this hunk.
• docs/api-reference.md — short note on the formatting unit / intrinsicDomain enable.

Verification

• npm run typecheck — clean
• npm run test — 423 + 50 passing (includes the bundled-skill sync test)

Happy to adjust wording or scope.

🤖 Generated with Claude Code

[zl190]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

This PR updates Flint’s authoring guidance and MCP tool schema documentation to clearly teach that semantic_types supports both bare semantic type strings and SemanticAnnotation objects, and that unit / intrinsicDomain are the inputs that unlock currency and percent axis formatting (rather than relying on semantic type strings alone).

Changes:

• Documented semantic_types as Record<string, string | SemanticAnnotation> across the agent skill docs and bundled skill asset, including a new “Annotation objects” section with concrete examples and effects.
• Expanded the MCP tool schema description for semantic_types to mention the annotation object form and its formatting impact.
• Updated top-level docs/README wording to reflect the current semantic type registry size and to mention unit / intrinsicDomain annotations.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Updates feature text to reflect current semantic type count and introduces unit / intrinsicDomain as formatting annotations.
packages/flint-mcp/src/tools/schemas.ts	Extends the semantic_types schema description to document annotation objects and examples.
packages/flint-mcp/assets/flint-chart-author.SKILL.md	Syncs the bundled skill doc with the updated SemanticAnnotation guidance and checklist.
docs/api-reference.md	Adds a concise note that unit / intrinsicDomain drive axis formatting behavior.
agent-skills/flint-chart-author/SKILL.md	Updates authoring guidance to include annotation objects, their effects, and validation checklist updates.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.