altitude-design 0.3.2 → 0.4.1

package/dist/guidance/llms.txt

@@ -1,6 +1,17 @@
-# Altitude 0.3.2
+# Altitude 0.4.1
 
-Read README.md, then only the relevant contract.
+> Altitude's guidance for this installed version of altitude-design: the design rules, the task patterns and every component's guide. Height is the interface: settled content sits on the ground, anything live rises above it, anything waiting to receive sinks below it.
+
+Read README.md first, then only what the task needs: the matching pattern, the design guide before composing a screen, and the guide of each component you use.
+
+## Design
+
+- [Design guide](visual/README.md): the laws, content and honesty rules, focus and states.
+- [Elevation](visual/Elevation.md): the tiers and levels, and every signal height carries.
+- [Charts](visual/Charts.md): read before any chart, stat or meter.
+- [Motion](visual/Motion.md): read before animating anything.
+
+## Task patterns
 
 - [Agent action](patterns/agent-action.md): Let an agent propose, wait for approval, run, recover and leave provenance, with each state drawn as one reading.
 - [Assistant conversation](patterns/assistant-conversation.md): Send, stream, stop, retry and recover in a conversation with an assistant, without losing the person's words or claiming an answer is complete before it is.
@@ -18,3 +29,143 @@ Read README.md, then only the relevant contract.
 - [Screen layout](patterns/screen-layout.md): Choose a screen's frame from the person's task, the one thing that leads and the one primary action, instead of inheriting a sidebar, a top bar and a grid of cards.
 - [Settings](patterns/settings.md): Change how a workspace or account behaves, deciding per section whether changes apply now or save together.
 - [Sync](patterns/sync.md): Say truthfully what has reached the server, through offline queues, conflicts and expiring sessions.
+
+## Components: Foundations
+
+- [AltitudeProvider](components/AltitudeProvider/README.md): Sets the color scheme, accent and motion preference for everything inside it, and hosts the layers that rise above the page.
+- [Surface](components/Surface/README.md): The primitive every component is built from: a box placed on one rung of the elevation ladder.
+
+## Components: Layout
+
+- [AppShell](components/AppShell/README.md): The frame of an app: a sidebar of destinations (grouped, collapsible), a top bar with search and the user's menu, and the page.
+- [Artifact](components/Artifact/README.md): What an agent is making (a document, a component, a page, a chart, a config) in its own pane beside the conversation, with its versions.
+- [Board](components/Board/README.md): Columns of cards you move between, a kanban: columns are receptacles that open when you carry a card, and the card floats in your hand until it lands.
+- [Resizable](components/Resizable/README.md): Panes side by side, with a divider you drag: an inbox, a ticket queue, a file browser, a record beside its list, an agent's chat beside its artifact.
+- [ScrollArea](components/ScrollArea/README.md): A scrolling region whose edges show where content continues, so it never looks finished when it isn't.
+- [Separator](components/Separator/README.md): A divider: between sections in a card, groups in a toolbar, items in a sidebar, or "or" between two ways to sign in.
+- [SortableList](components/SortableList/README.md): Reorders a list by picking items up: the item you hold floats in your hand, the slot it will land in opens, and it lands.
+- [ThreadList](components/ThreadList/README.md): Conversations with an assistant, beside the thread: new conversation, grouped by date, search, rename, delete, and for agents that run in the background, which ones are still working, which finished while you were away and which are waiting for you.
+
+## Components: Navigation
+
+- [Accordion](components/Accordion/README.md): Reveals sections one at a time.
+- [Breadcrumb](components/Breadcrumb/README.md): Where you are in an app with routes: Settings › Members › Jane Doe, or Projects › Atlas › Issues.
+- [Drilldown](components/Drilldown/README.md): Navigates a hierarchy as a stack.
+- [Link](components/Link/README.md): Navigation: a link in prose, "Learn more" after a hint, "View all invoices →" at the end of a card, an external link to docs.
+- [PageHeader](components/PageHeader/README.md): The block every page opens with: breadcrumb, title, a line of description, the page's actions, and sometimes tabs.
+- [Pagination](components/Pagination/README.md): Moves through pages of a collection the server pages: invoices, members, audit events.
+- [Stepper](components/Stepper/README.md): Shows where you are in a process of a few steps: done steps settle into the record, the current one stands raised, and steps to come are imprints.
+- [Tabs](components/Tabs/README.md): Switches between views of the same content.
+- [Tree](components/Tree/README.md): A hierarchy you see all at once and change in place: rename a node (F2), add a sibling or a child, carry a node to a new place (Space, or drag), collapse and expand, remove.
+
+## Components: Inputs
+
+- [Checkbox](components/Checkbox/README.md): Toggles one independent option.
+- [Checklist](components/Checklist/README.md): A list you write into, one line per item: to-dos, acceptance criteria, a packing list, a runbook's steps.
+- [ColorPicker](components/ColorPicker/README.md): A brand colour for a white-label portal, a label or tag colour, a calendar colour.
+- [Combobox](components/Combobox/README.md): An editable Select: type to narrow a long list, then choose.
+- [DatePicker](components/DatePicker/README.md): Choose a date in a field, by typing it or by picking it from a month calendar.
+- [DropZone](components/DropZone/README.md): A receptacle that opens only when there's something to receive: flush at rest, sunk while a file is in flight, deeper under the pointer.
+- [EditRegion](components/EditRegion/README.md): Edit several fields of one record where the record is shown, and save them together as one write.
+- [Field](components/Field/README.md): Pairs one control with its label, an optional hint and an error message that emerges beneath it.
+- [InlineEdit](components/InlineEdit/README.md): Edit one value where its committed value already appears: by default a single-line string, a paragraph with `multiline`, or any value with a custom `editor`.
+- [Input](components/Input/README.md): A single-line text field.
+- [InputOTP](components/InputOTP/README.md): A one-time code: two-factor sign-in, email verification, device approval.
+- [NumberInput](components/NumberInput/README.md): A number field: seats on a plan, rate limits, retention days, prices, quantities.
+- [PasswordInput](components/PasswordInput/README.md): A password field: signing in, signing up, a reset, "change password" in settings.
+- [PermissionMatrix](components/PermissionMatrix/README.md): Roles against permissions: "Admins can manage billing, Members can invite, Viewers can only read".
+- [PlanPicker](components/PlanPicker/README.md): Choose a plan (Free, Pro, Business) in sign-up, upgrade and downgrade flows, with a Monthly / Annually switch, prices, and what each plan includes.
+- [PromptInput](components/PromptInput/README.md): Where a person writes to an assistant or agent: a textarea that grows, attachments as chips, optional tools or a model picker, Send, and Stop while a response is generating.
+- [RadioGroup](components/RadioGroup/README.md): Chooses exactly one option.
+- [SaveBar](components/SaveBar/README.md): Unsaved changes on a settings page or a long record form, held above the page until they're saved or discarded.
+- [SecretField](components/SecretField/README.md): A key or token: an API key, a webhook signing secret, a personal access token.
+- [Select](components/Select/README.md): Chooses one value from a list: an opening you fill by choosing, with the list rising from its edge at level 3.
+- [Slider](components/Slider/README.md): Picks a number from a range by dragging a raised thumb along a trench.
+- [Suggestions](components/Suggestions/README.md): Prompts to start from or follow up with.
+- [Switch](components/Switch/README.md): Turns a setting on or off immediately: a raised thumb riding in a trench.
+- [TagInput](components/TagInput/README.md): Edit a set of short values in one field: labels on an issue, recipients, skills, keywords, allowed domains.
+- [TimeInput](components/TimeInput/README.md): A time of day: when a scheduled report is sent, quiet hours, business hours, a maintenance window.
+
+## Components: Actions
+
+- [Button](components/Button/README.md): Triggers an action.
+- [CopyButton](components/CopyButton/README.md): Copies a value and says so: API keys, install commands, invite links, IDs, webhook URLs.
+- [FeatureGate](components/FeatureGate/README.md): A feature that needs another plan, shown to people on a plan that doesn't include it: "Export to CSV · Business", "SAML SSO · Enterprise", a menu item with a lock.
+- [HoldButton](components/HoldButton/README.md): Commits a consequential action by pushing it through the ground: hold until it sinks into a trench.
+- [SplitButton](components/SplitButton/README.md): One action with its alternatives: "Save changes ▾" (Save as draft, Save and close), "Merge ▾" (squash, rebase), "Deploy ▾" (to staging, to production).
+- [Toggle](components/Toggle/README.md): Buttons that stay on: bold and italic in a formatting bar, a list/board/calendar view switch, "Show archived", thumbs up or down on an AI answer.
+- [Toolbar](components/Toolbar/README.md): A row of small actions with one tab stop: a formatting bar, a table's tools, a comment composer, a canvas's tools.
+
+## Components: Display
+
+- [AILabel](components/AILabel/README.md): Says when content was generated or changed by AI, and explains how when asked: for trust, and under transparency rules such as the EU AI Act.
+- [Alert](components/Alert/README.md): Tells the person something about the current context.
+- [Avatar](components/Avatar/README.md): Represents a person.
+- [Await](components/Await/README.md): Components that bring their own loading state.
+- [Badge](components/Badge/README.md): Labels status or metadata.
+- [Card](components/Card/README.md): A raised surface that groups related content; it moves only if the whole card is one action.
+- [CodeBlock](components/CodeBlock/README.md): Code to read and copy: install commands, API examples in several languages, webhook payloads, config, code an agent wrote.
+- [CommentThread](components/CommentThread/README.md): Comments on a task, a document, a design or a deal: write with @mentions, post, retry a failed post, delete your own, and resolve the thread.
+- [Conversation](components/Conversation/README.md): The thread between a person and an assistant: their messages, the assistant's answers (often streamed), copy, regenerate, feedback, versions, and "Jump to latest" once you've scrolled up.
+- [DataGrid](components/DataGrid/README.md): A table whose cells you edit one by one, with spreadsheet keys: arrows to move, type to replace, Enter or F2 to edit, Enter and Tab to save and move on, Escape to back out, a block pasted from a spreadsheet.
+- [DiffView](components/DiffView/README.md): What changed between two versions: version history, audit-log detail ("Plan: Pro → Business"), config changes before a deploy, and edits an AI proposes to a document or record.
+- [EmptyState](components/EmptyState/README.md): What a list, board, search or page shows when it has nothing to show: a statement of what's empty, why, and one obvious next step.
+- [FilterBar](components/FilterBar/README.md): Build and change a query as a row of conditions, each edited in place: “Status is In review”, “Assignee is Mara Quist”, “Updated between 1 Oct and 20 Oct”.
+- [FormattedNumber](components/FormattedNumber/README.md): A number in a sentence or a table cell, formatted once: invoices, usage ("4.5 GB of 10 GB"), latency ("128 ms"), seats, error rates.
+- [InlineCitation](components/InlineCitation/README.md): Numbered source markers in a grounded answer ("…renews monthly [2]"), with a preview of each source on hover or focus, and `Sources`, the list at the end.
+- [ItemGroup](components/ItemGroup/README.md): A list of records shown as slats (media, title, description, actions), changed in the list itself: edit a slat in place, add one at the end, reorder by picking one up, remove one with real recovery.
+- [Kbd](components/Kbd/README.md): Shows a keyboard key as a keycap: a tiny slab with a 2px wall that presses down when the person presses that key.
+- [Markdown](components/Markdown/README.md): An answer's Markdown, set as Altitude prose, as it streams.
+- [Pile](components/Pile/README.md): Shows a group of items as a stack.
+- [Progress](components/Progress/README.md): Shows how far along a task is: a raised fill rising out of a trench.
+- [PropertyList](components/PropertyList/README.md): One record's properties as label–value pairs, each editable where it sits: an issue's sidebar (status, assignee, priority, estimate), a customer's details, a settings summary, a “Check your answers” page.
+- [RelativeTime](components/RelativeTime/README.md): A moment shown as "3 minutes ago", for activity feeds, audit logs, comments and "last edited".
+- [RemovalReceipt](components/RemovalReceipt/README.md): The slot of an item that can leave its list: a file archived, a webhook removed, an invitation revoked.
+- [SavedViews](components/SavedViews/README.md): Named combinations of a filter, a sort and the columns, kept as tabs above a table: "My open deals", "Enterprise churn risk", "Unassigned this week".
+- [Schedule](components/Schedule/README.md): A day or week of time whose events you handle directly: drag across empty time to create one, carry an event to move it, pull its bottom edge to change its length, rename it in place.
+- [Skeleton](components/Skeleton/README.md): Stands in for loading content as an imprint: the shape of what's coming, pressed into the page.
+- [SyncIndicator](components/SyncIndicator/README.md): One honest answer to "is my work saved?", for autosaving editors, optimistic UIs and local-first apps: "Saved", "Saving…", "Offline · 3 changes waiting", "Couldn't sync", "1 conflict to resolve".
+- [Table](components/Table/README.md): Rows and columns of records: the rows sit on the ground with `line` dividers, and only the ones that are selected, matching, in hand or under your pointer rise.
+- [Terminal](components/Terminal/README.md): A command's output as it runs, with how it ended.
+- [Timeline](components/Timeline/README.md): Events in order: activity on a record ("Maya changed status to Done"), workspace activity, version history, webhook delivery attempts, an order's history, background agent runs.
+- [Trace](components/Trace/README.md): The steps an agent takes (searching, calling tools, reasoning, waiting for approval), so people can see what it did, what it's doing, what it plans, and where it failed.
+
+## Components: Feedback
+
+- [AgentFleet](components/AgentFleet/README.md): Every agent working on one job, as a roster: grouped by what they need from you (needs you, working, done), each row saying the agent's state in words, what it's doing in one line, how long it has waited or run, where it is in its plan and what it has spent, with warnings for trouble that's coming (two agents changing one file, an agent making no progress).
+- [AgentRequests](components/AgentRequests/README.md): Every decision your agents are waiting on, in one queue: approvals, questions, reviews and failures, oldest first, each answerable where it is.
+- [Confirmation](components/Confirmation/README.md): Approve or reject an action an agent proposes, before anything happens: "Send 214 emails to Pro customers", "Delete 3 stale branches".
+- [Question](components/Question/README.md): An agent asks the person something before it carries on: "Which environment should I deploy to?", "Keep the old column or drop it?".
+
+## Components: Overlays
+
+- [CommandPalette](components/CommandPalette/README.md): Finds and runs anything in the product from one field: the summit, at level 5, opened with ⌘K or Ctrl+K.
+- [ContextMenu](components/ContextMenu/README.md): Actions on a thing (a file, a row, a board card, a tree node, a canvas object), opened where you right-click or long-press it, or at it with Shift+F10 or the Menu key.
+- [Dialog](components/Dialog/README.md): Asks for a decision or a focused task at level 5, the summit.
+- [DropdownMenu](components/DropdownMenu/README.md): Lists actions for a trigger; one highlight glides between items, which arrive in quick sequence.
+- [HoverCard](components/HoverCard/README.md): A richer preview of what a link or a face points to: who someone is, what a project holds.
+- [NotificationCenter](components/NotificationCenter/README.md): An inbox of what happened: mentions, assignments, approvals waiting, failed jobs, billing notices.
+- [Popover](components/Popover/README.md): Shows rich, interactive content anchored to a trigger, floating at level 3.
+- [Sheet](components/Sheet/README.md): A large panel laid over the page at level 4, anchored to an edge, for a task that needs more room than a popover and less commitment than a page.
+- [Toaster](components/Toaster/README.md): Confirms what just happened, in a depth stack: the newest toast floats in front at level 4 and older ones sink behind it.
+- [Tooltip](components/Tooltip/README.md): Names an icon-only control or adds a short hint; it floats at level 3 above its anchor.
+- [Tour](components/Tour/README.md): A few steps pointing at parts of the interface, for onboarding or a feature launch: "Projects moved here", "New: filter by owner".
+
+## Components: Charts
+
+- [AgentLanes](components/AgentLanes/README.md): Where each agent's time went, one lane per agent on a shared clock: working, waiting on you, waiting on another agent, failed.
+- [AreaChart](components/AreaChart/README.md): A total over time and the parts that make it up (requests by region, storage by type), or a single volume over time.
+- [BarChart](components/BarChart/README.md): Amounts compared across categories or periods: deploys per team, signups per month, cost per region.
+- [BarList](components/BarList/README.md): Top pages, top referrers, top customers by spend: a ranked list where each row is its own bar, the label is readable at any length, and the exact value sits at the end.
+- [ChartBrush](components/ChartBrush/README.md): Picks a time window on an overview of the whole series, under the plot: look at a year and read a fortnight without losing where you are (overview + detail; Cockburn, Karlson & Bederson, 2009).
+- [ChartContainer](components/ChartContainer/README.md): The frame every chart shares.
+- [ChartLegend](components/ChartLegend/README.md): Names each series, and optionally lets people hide and show series.
+- [ChartReference](components/ChartReference/README.md): Reading a chart against something: an SLO target, a budget, a normal range, the average, the day you shipped v2.
+- [ChartTooltip](components/ChartTooltip/README.md): Reading exact values off a chart.
+- [DotPlot](components/DotPlot/README.md): Values compared across categories where zero isn't part of the story: ten services' p95, all between 180 and 240 ms; scores by team with their spread; last quarter against this one.
+- [Heatmap](components/Heatmap/README.md): A value per cell across two dimensions: load by hour and weekday, error rate by service and region, or activity by day over a year (`variant="calendar"`, as in GitHub's contributions).
+- [LineChart](components/LineChart/README.md): Change over time: latency over a day, revenue over a year, one series or a few compared.
+- [Meter](components/Meter/README.md): Where a reading sits in a known range: storage used of a quota, seats used of a plan, CPU, a score.
+- [ScatterChart](components/ScatterChart/README.md): Two measures per record, to see whether they move together and to spot the ones that don't: response time against payload per endpoint, spend against seats per customer.
+- [Sparkline](components/Sparkline/README.md): A trend the size of a word: the last 30 days of a metric in a `DataTable` cell, a `PropertyList` value, a `Stat`, or a sentence.
+- [Stat](components/Stat/README.md): The tile at the top of a dashboard: a label, a big number, how it changed and against what ("Active users · 12,480 · Up 8% vs last month: 11,556").

package/dist/guidance/manifest.json

@@ -1,12 +1,125 @@
 {
   "schemaVersion": 1,
-  "version": "0.3.2",
+  "version": "0.4.1",
   "files": {
-    "agent-setup.md": "5b300079b150d6416b6dd00280a42110559c85d50b84a13ac6cf9e0329be9a21",
+    "agent-setup.md": "57b4ba98719fce472e08226a5c784ed4b9eb20241904445825cb2287a84a0162",
     "app-skeleton.md": "bc70896a86f4c1dbd3467620562eec62ccf99a9356ff72a7eab8621f492554d9",
-    "evidence.json": "ac99cfcca61219a4a25c75adf84c89f6c3e47b3713a8fb8209180c824d565b1b",
-    "index.json": "89e288fa695298246a835c1ba434b3cd5eb0e0a33d553e51413a027c768c0ca7",
-    "llms.txt": "4371205db0d38e06044fb819b04fc3edfa3c86cd7a1d984eb3b22580164232e2",
+    "components/Accordion/README.md": "b166e499eb3604ef84a375818db3aec91c5459870b5d6cd3133ecbdf36e145d6",
+    "components/AgentFleet/README.md": "1535639f82b1d5fc767e41b833cb1f29494a59cd6979c545e45587f6657f3daf",
+    "components/AgentLanes/README.md": "247eb6e0ead0de5f15da920f083dbaa4150673723b081acf70e19026f982cd16",
+    "components/AgentRequests/README.md": "e7ac986cef68b09b5a7df7d1c11cf44ef8d417a3d22f9436f7cea1d8b4190c18",
+    "components/AILabel/README.md": "0002447d340029fe28652ed26c474c91edf89a0e23be300d24c198afb7086646",
+    "components/Alert/README.md": "aa2d4e3dd2d7143e1c422cbe9d531b0622a9441827df95631f88fd4cd4f33657",
+    "components/AltitudeProvider/README.md": "c07a90669fd328adfd6b567cfccaccf5ef58bc7a7023f7058bb646571556c586",
+    "components/AppShell/README.md": "9363def66ebd650300b940c71f716653b4960932836fd123aee25a6562fdf88f",
+    "components/AreaChart/README.md": "e0c4bbe8e94cc860732fe78ffbf808dfb31dc324f0c75fcd1c71872c7748ed56",
+    "components/Artifact/README.md": "37e3fe7e2d7dc20979f17c77b939e73b329a3a981dbe46a7ec480f2a072a5662",
+    "components/Avatar/README.md": "dc833eff628d6b850a82c910299dc29b6341ad51ee37566c1f9ed116447c45d6",
+    "components/Await/README.md": "bde547bfebfe8407e6bdeea68f4c8e5b228fd38189355cdaff485c0ec8a4c94f",
+    "components/Badge/README.md": "118520cbd5dca26aa4d048a429c1574467c25321e376f60e073daed0be875ea3",
+    "components/BarChart/README.md": "80370de4bc1bc6864577bcb0c9163a748bcd6bbd95eee789723d64cc2fada9b1",
+    "components/BarList/README.md": "96ec0d5cae26ce7bdeb995652cc4147d64caea14771f82e92dd0f56f002eed61",
+    "components/Board/README.md": "95402d7e6f4c76111a88e19f6dd7b762c900b7c5e7aa1ab14faf27ef870162e0",
+    "components/Breadcrumb/README.md": "fe28cfe23113fcfaf8842181bfa9f9274e192dd9421ec9ce992a53e7ebdf80c9",
+    "components/Button/README.md": "46ee13103d00c0435c00496fbcc25b909b63388e05f2a76b483d43e7619c74f3",
+    "components/Card/README.md": "74fe7bcd95c8600a506751f9ab7f6ebfa8691d7c207fd2e3c87c84a8b5292cb0",
+    "components/ChartBrush/README.md": "1cd4aaac37c5969e51b01d7d9a2f81a1ca6478229396a190743b1bbbc46279c8",
+    "components/ChartContainer/README.md": "66b52dfac7008ca9d44fa51ffd0f1d2c833c3b4f3a76103b080847a77da4d319",
+    "components/ChartLegend/README.md": "34a3671b7c8ed97475d9b13ed5cfee67feff0b84f7360db570eee72bd62a73d8",
+    "components/ChartReference/README.md": "9179034c6fafc92be70f68a238bdd16e86d2d4504f726f89e42814c661ec6277",
+    "components/ChartTooltip/README.md": "f886a0a48b02504650c538926fbe55f763ff84122f0d3deee62cd8f1317f53e5",
+    "components/Checkbox/README.md": "14e1a4f795393a728ce0cb37949413ba30a480bbff583bcf3c0899544928c26d",
+    "components/Checklist/README.md": "3c61aacf437512760cc16b21aa9b54e7c1e1296b447743c1860a3bedb977c8bb",
+    "components/CodeBlock/README.md": "61789d26b28d6da47e566683d01bae3012d05ffe67e4bbf35ea784d5d359d12c",
+    "components/ColorPicker/README.md": "24a0f90b86d7b246976d8a41dc047c25bb4b6ccb80717f388783723f15497018",
+    "components/Combobox/README.md": "f19169c7453cba104859b28eb54e8ec0224bd6ab9263a28bca8bbb4be0c67151",
+    "components/CommandPalette/README.md": "a6bf308a4d791873cfedeaf190b422cd67ed4e6dbb7273f3b340f93432d7e741",
+    "components/CommentThread/README.md": "54134a30be5ac1d82f2036345869205d5d6003ca198e1d982c72bb2ef856806e",
+    "components/Confirmation/README.md": "c6ed60c3ae6c563da1a5473546d14986ecfe5ecf691794ee3e6d89e39f4e3ed4",
+    "components/ContextMenu/README.md": "ab86dfa366dd2bacc98e6b01b45cc6e9919301e680a1d19798a0902b1b23475a",
+    "components/Conversation/README.md": "13ad68c8d4c5a5687245d64136f413d3edc62ce06efcaa0a5771004157ec04f0",
+    "components/CopyButton/README.md": "edac13d1acbd4fe4d72f440ed62e5eb943c33545d3e6faac2d1368b6f8bab00c",
+    "components/DataGrid/README.md": "ff20e0a9b7408048cd3cb50a51e7c3f3a6f89956ce0696e310232e06f3060f9b",
+    "components/DatePicker/README.md": "6ffccef22967b52791d9f95e72058c0b78696253ceeec27ae067344313b4fda7",
+    "components/Dialog/README.md": "ea8292e64ff7a026e08851a337e88cb7260944786b6cba70ffb0771da4560117",
+    "components/DiffView/README.md": "da741f44cbe1a5fdc658eb5cb646b72b47fe03ea800f842fd80e7f8f074448bb",
+    "components/DotPlot/README.md": "2d8f7a05497ba960292f3eaa9bbb771b50fc6bf71e114be7f4056355d4071c8a",
+    "components/Drilldown/README.md": "55e4ba22622faa579d5fa48229326aeb3516dca10898a71c9b7e0849bb86271b",
+    "components/DropdownMenu/README.md": "258867ad981fbeffd7d6e5eb95d0c298c49e8e2f5b5fc127709a23610152dc65",
+    "components/DropZone/README.md": "698ff35d2b385a3a52f70709943a42055f3c8e4d90e6c4f9e9caa90ea9df9912",
+    "components/EditRegion/README.md": "747a5dbe65b441f7930bab3cefd6360b11a6f46e19f7a7da526dec282629a196",
+    "components/EmptyState/README.md": "f616d8545c10c13c88d1f2e0afd9b7cad9bd60c4cc3491f632e0969b887813dd",
+    "components/FeatureGate/README.md": "c1a46ba656b5102cf7018d376f227e662dd48b8b224a1215056a60beee44b3c5",
+    "components/Field/README.md": "cfa5b963b00a8796b9ea22eae8856bd74a87be3cf4d4ceb6341b538c411138e1",
+    "components/FilterBar/README.md": "b861538ae1f2b778547547d4b6491ddb28b69d850ed1672960c143ef6b341bf1",
+    "components/FormattedNumber/README.md": "9b9e315986e913f7cb995ce82831ac1bc8148ca5b2cbf94e7aa3d2f941e649a0",
+    "components/Heatmap/README.md": "b239a7a7914e634c4bcea47dda84b51633399890dfecb4839740d45c0ab344ba",
+    "components/HoldButton/README.md": "bb81a002a2d37701a84a04123fbabd8cb820c52befaacaaf881de48d12f733f5",
+    "components/HoverCard/README.md": "23e6de1b79fa302b2ce168431fd15339b33132663911521594882f338c1ca366",
+    "components/InlineCitation/README.md": "b3f66c18bdf054f818525fbcf5f5db36535d121289f6d0451413ac0803bf8edd",
+    "components/InlineEdit/README.md": "202f4f93fa2301a90cf1175bc1450bc0e60f40b2d13e868928de44fcff691379",
+    "components/Input/README.md": "8b7df74399ce471bead1c81967e63ca1bb249aebd827abefd4fbf1a6a2a13e26",
+    "components/InputOTP/README.md": "e1a17bca55de012b26f25dca299d7ffe01b21248efde19bea63ebeac4e2625aa",
+    "components/ItemGroup/README.md": "87a1e6c3e124aec1012ef71dc69c3e5ab85feeb4735fa0b77db449a22692f6e8",
+    "components/Kbd/README.md": "05560bba1e4177115f7e23eb1e9103625be645ce0b87df64c46adaeea9fc1512",
+    "components/LineChart/README.md": "dfb95b99af894837f76d36fca78bbd842c7e76914cd0fbd0fa4d8d3725c3ec8c",
+    "components/Link/README.md": "13f72832bd509b9b6ef3c91f79df2dc6919d5c34346772c73e8c63fb9cb99fc3",
+    "components/Markdown/README.md": "9d1d5a8ea10cd4f8765d0a21c0f8bd7bbf150643820761dd5fb3dcc52e224616",
+    "components/Meter/README.md": "11b8c4a7b5d24aa63feaa2920ed149a41102a3f948b813c0b1ee439e1990daa3",
+    "components/NotificationCenter/README.md": "1c2043460b688347daa214e15d2c83925c2e272dd6655efaf3074f3594214b80",
+    "components/NumberInput/README.md": "6c8d196acac254243b16090a8d80c41731d88c170f0b1a7eaf6d00a05c09d195",
+    "components/PageHeader/README.md": "eaa286d9c7c758b904df9a70aba802bdd405c3d49de788334992b40dc5451934",
+    "components/Pagination/README.md": "775a3d85740b66ca932a5e04deb17e922e4819d8318503edc3e54c6ed0ca0542",
+    "components/PasswordInput/README.md": "3ac48a94e32493521fea101bf679d94c78e818be322c06d46292cada61ab1275",
+    "components/PermissionMatrix/README.md": "3f5ca4cf91ec2c9e3803104052c4dedd7778646b2d7d5afd8389b3c9385df4f8",
+    "components/Pile/README.md": "7ba9aa587158b68816f8317917b6e22d39cce2e42f26aa53247496fc38d7fb09",
+    "components/PlanPicker/README.md": "d8f9d7d80d7bbba959de64e7f18496945ef73b17c388ee0f639f203470acec58",
+    "components/Popover/README.md": "5666b43b85c453ec4315572e9c15d2868674d7d7686ec118cbce64ae16fe53ac",
+    "components/Progress/README.md": "e5f98ebfe662db89d568111880bede453acc2e976ebe74185a9f3d73e71ce323",
+    "components/PromptInput/README.md": "f412dee8e40a650914e2c835cef003365dd41e483cfcd743df826c4682c8a532",
+    "components/PropertyList/README.md": "168872db3bd96e0b432a1f6b931f1330bad401dccfc94cc219b64cc9a64446a5",
+    "components/Question/README.md": "94ece55de57e9cc358bbbd34dbe7a7329eba451a7f2c22aa02fa4f1f1b8ed199",
+    "components/RadioGroup/README.md": "c0242621ae36b104d574a2df6ee650527bdcb64d37642f0cf4dd86cf16ec5ae9",
+    "components/RelativeTime/README.md": "5b1a7f716825233b457319c2398ba574419a757c2c92c11223dac5d64a9990a2",
+    "components/RemovalReceipt/README.md": "30ab65617692614d846298cb103d7737a5ba464610f44cda64bd0d737cefbc88",
+    "components/Resizable/README.md": "c166d0af35119ec622919a7c274696deee465beb3b3a999e263d5ea9d248c1f1",
+    "components/SaveBar/README.md": "87661cb5efda0d3aadac7d89f503368ab54080faf902464af9f6d7ce31752aff",
+    "components/SavedViews/README.md": "1eb6996c7ba7b6fe2f680603f66c4dcb0b2e98b5901dfa1ad405fd967a2e3fab",
+    "components/ScatterChart/README.md": "ff9a5f079a75dabeb2df15d2c8db7282f280aae159ad618dfbaa5d25c8a77150",
+    "components/Schedule/README.md": "cab13327ec2b8ff9c317dc19ac12390705f15f9f9d61b94c3bc52810cb54ce82",
+    "components/ScrollArea/README.md": "937763fcbccf2398129499fb092d12cedecd67fcc42d619bfb5c918491f4214c",
+    "components/SecretField/README.md": "5cd6cf1baa5e05b697e0c9a6adf46ef75dca8baee13a5922ecc18cd058ae9c12",
+    "components/Select/README.md": "7100be945a087376144b36d5011ae1802ad4c09775508b738266a3b2bf4ff3cb",
+    "components/Separator/README.md": "3e1ea97e6f94b61b9238d0574af5c3b89dc98739038685d47a2ec900b06f9b04",
+    "components/Sheet/README.md": "6ae67731f739ddf3252d8379d5abb1593841c5539025e79ab7503ec338d2ee3b",
+    "components/Skeleton/README.md": "1dfb1c66fb09ab7fa9cb1c215d3d23ec64f80426429a30208965c7926aac5ac6",
+    "components/Slider/README.md": "83d151670641cfa52bd575ad14539a5d28ba6fa0d53a6dfcbacd5653bb0a27a6",
+    "components/SortableList/README.md": "82895ed1a93de818ebf294886056e038060a159a44ae909b7ccd4c1ec5a9e463",
+    "components/Sparkline/README.md": "1b5955eac19ba5d13061c8ed94f687347d37a7d8d25e8f9def6a47cdc302f51b",
+    "components/SplitButton/README.md": "e31e9de4502d843ae073d708d6dcf0692f1cf18cace8fe4dbc76f001b0535546",
+    "components/Stat/README.md": "ea503b7e12456695a7d70e1d07bb2943e766e1a41e537f5e9215bc4d960d907f",
+    "components/Stepper/README.md": "6a836faca42ccc7549ac86da1639280af8f19e880685258e3df937c6e17d4981",
+    "components/Suggestions/README.md": "de81a3988cf3233ca80332c099fca06381a9ab6416df0a560bc1ce5f5e976489",
+    "components/Surface/README.md": "1e14fd015df7aeceaacccf8b94cdfebbc821ef30b98f11c5e8fbeb30744a9721",
+    "components/Switch/README.md": "42402b1097acd4b84192d7ae9e7e4813d3a09d6c0fa76f8922e2ffa4f8abc66a",
+    "components/SyncIndicator/README.md": "55f1c197d822a97903a5590a72a4006b371a41fe5ac876f66ac395493ac4b0f8",
+    "components/Table/README.md": "e29d07664e06255add18ae88851a9fcd6f65f490d3dcbb62759109a384bf3aee",
+    "components/Tabs/README.md": "67ac2cff922ad2834a4dbc34255233c86106cb4db4757a3af485cc320e74dccd",
+    "components/TagInput/README.md": "767384532997c2d20b8e545d5a7f34ed8c33605a4167d22fff2eef38ef4db139",
+    "components/Terminal/README.md": "78921ce1351076df794075b563c3be6b5e36d4e0d0dea29d7bfa4e4414905ace",
+    "components/ThreadList/README.md": "d80cae5c14607e62edde48ccc281857c511c010c2393e1b5ad3b1a01ea20eae2",
+    "components/TimeInput/README.md": "38cefa3218caf4b1e327ef94e167e62834f07ac43a80aeeb522ed1630ab015fd",
+    "components/Timeline/README.md": "95daf26d1e2f1072f74ed0e3a3b6792468824cf1135dfa132dcce0081094aba8",
+    "components/Toaster/README.md": "b6c1950c47d2e2296f3f731705acff60b2e47b7c8f62c76b11eac02791f9699d",
+    "components/Toggle/README.md": "58031d770c80ef39a43d53d9b1b86802a3249efdb12c8451e115a6e3f0f04d9c",
+    "components/Toolbar/README.md": "b40dea791d70f301a8b62317473a6f40962707164e57ecd41b6e46514925911d",
+    "components/Tooltip/README.md": "851245aab0a9f6e7b8aa111a7000b783a9656637bac5b50f332feb2c6a69e72b",
+    "components/Tour/README.md": "ecb436c7753b2d5d5d44255f04a833cea73041cf91287aac50c7519520ca2747",
+    "components/Trace/README.md": "62c571b2d96a83e5515988eacecd47de3e2c1a2452476d00645d1a26d3cbae3d",
+    "components/Tree/README.md": "9fadf66c7d223653bd299362e997c814f06baf2a9c59f8ebc15ef9a0a24235e4",
+    "evidence.json": "71e9602167286fb714419d0e89a80d4765b632c910d51875d1b167fd1ee499d9",
+    "index.json": "0eaad07f3af1228397a764fb5abf78bb1023c337ebcef7fcb4f6ef510aac466a",
+    "llms.txt": "bc833cedeb16081db4904ce3f8b715aa951ba6655e3d2ac56ceaf7e70aa526c5",
     "pattern.schema.json": "abcb37bd5de4a74f27ac079e587e5d288b23e491569a73971f1a31131a37d309",
     "patterns/agent-action.json": "532915c25183d1a6093d9e14b929f3e49d29e400b116ef0612d933d70d49b09a",
     "patterns/agent-action.md": "a11e9d98a84d8a0fae755bae3e618e7daa2608f1f853cfe88e2e58ee74cc01e7",
@@ -35,21 +148,21 @@
     "patterns/review-submit.json": "79b15332acc57fb48b0b99ba98a195d5f913e7875293b0acb6aa42f5425a982b",
     "patterns/review-submit.md": "6a9d1886a48cad9e82da5c8b04d179425ec4fa925105d6f9ee50d4605dab3d87",
     "patterns/screen-layout.json": "199ca3f20a7af1983bc7211406bbf87e43328e3d57c48d29524191de86507782",
-    "patterns/screen-layout.md": "7a6dd92249e1b8acbb5ab16afb15f5d3aa25e46fedf8d59eb40a4d892b22310e",
+    "patterns/screen-layout.md": "7fc8bc278fd63950c5148fbf46c2896f2b8e3ff75c289db480d93ac9124a5b79",
     "patterns/settings.json": "9ae72e95cb61b5f41a22053d408c2a634c18746661fa1c2e41e98a5ef2b6e08f",
     "patterns/settings.md": "dea76175e2b1b4347414c3716f0ff61fd584bf10b8fd45548449694c86027bbf",
     "patterns/sync.json": "e127992aaba5ad797a0c27ff0f7903619511e9a02379b6932c66084d3690660e",
     "patterns/sync.md": "9b6c6928fe19c6f28b88bd092997c0c0645aedddf02a25327a1c7c60969e3729",
     "principles.md": "1c57c684c4b0029012a79d6a38b26b8821abf75852b14db2b18b7e7f6d364b32",
-    "README.md": "2b37096e2c13fbff4578c53ebbc38329f49a4050b9d1757125a42ab778785125",
+    "README.md": "bde7983588a9fd0f7bbcc0d282dc110ecb4811cd5753a4ea835399c7ea7ff520",
     "references/build/checks/agent-action-pattern.mjs": "166f5765839d2f60e7bd84cda2a834100306b3d5a80b4b45b79f2c2d33fce1e7",
-    "references/build/checks/agent-setup.mjs": "670c0786bdfc5739fceae14bd234a2a2c9c6672fbe6fd4e72b15f85647f4a1dd",
+    "references/build/checks/agent-setup.mjs": "173dac8125bf1201db023d42a862d3c6f226ee3886efe40079fbd87e4fc53e8b",
     "references/build/checks/assistant-conversation-pattern.mjs": "f289529c2ee594ad28269337da762f00ae1143f8bb217cf36b1596a5a5363618",
     "references/build/checks/audit-log-pattern.mjs": "af7770e7bf08caa9e1875161e4fc39509e4f0a84e612cdf79cb547cb6046af74",
     "references/build/checks/auth-pattern.mjs": "7406cfa7c29c3bb3ac9075c8af079c6f7fd0bc296e81fef1c62667ec245c660b",
     "references/build/checks/billing-pattern.mjs": "75e1809769420bc4c714ba0ddb1298489af7152603018d980182e6131182edc2",
     "references/build/checks/developer-settings-pattern.mjs": "946cf163177db4aa4dfa30dac754d0229bc4b703ef1eac17a17dc35d19e2f093",
-    "references/build/checks/guidance.mjs": "65bca118879294288c14f296db3ba225ed953fb295e4010487fb7bae16c1bf51",
+    "references/build/checks/guidance.mjs": "ccbf3f1138a99106b3811a41304752be012c1a2a16fede1469271f7235b08636",
     "references/build/checks/import-pattern.mjs": "6b98c0533bb0d8584ba0d677e579a0fdfdbdb5bd4663f261ecbdfb39181c45f6",
     "references/build/checks/members-pattern.mjs": "bd550c7315dd6298efc1d524364dcfb505884a2e32bb9ed7c4995b53cc61a2a5",
     "references/build/checks/onboarding-pattern.mjs": "721ef5a202365d3597985bff9ade68bf3312c309687e846ce9a1669dcc00cae2",
@@ -60,6 +173,7 @@
     "references/build/checks/screen-layout-pattern.mjs": "c744bb32b29da50e2a1d852c1005b42addc0e1d7a98297e168f8ce7d51e4ad93",
     "references/build/checks/semantics.mjs": "2ee7689b0472dba2e782ff19304e01018ca470b252fe7137e82bb36a3e0042c0",
     "references/build/checks/settings-pattern.mjs": "77a8d8e431e5e25e4f4af5c92e7be1e664dbab5aac9f587b7819bd9c196b3907",
+    "references/build/checks/source-check.mjs": "07a22ce606b28e788ff501ff10da06ec66c2f947cf671d0cd57cb71e629007e0",
     "references/build/checks/sync-pattern.mjs": "2cf9f1ac96be6c48948dea0ffab0fda0a909b5ff19e3e3f9835b6d8bcdd7fbef",
     "references/build/checks/tells-lint.mjs": "f254fa9166f65a085d78cecf7ca66145151cd8b7868c732c25c44bbec2c2deac",
     "references/build/fixtures/pattern-workflows.tsx": "6781938d83aa85f48c63fff98f9eb5b45fcb5531b6a49f902ec9d497f6e65265",
@@ -84,9 +198,16 @@
     "references/project/components/src/pattern-review-submit.tsx": "b452f90e7a160774678aa886626aa48dea535211bc367a17d628ac84bed5ee58",
     "references/project/components/src/settings.tsx": "957a04e37936746f2b6b4086d8e2f866ce71f7fb9dded8ba81fff56840206e01",
     "references/scripts/build-framework-fixture.mjs": "1b4a2d7ece0459d2c4df2ec067d8d3b9d00110f2af1cef3be6042ab8f9ea90c9",
-    "rules.json": "607eed605aa834ab2e6557b44df0899a3851b684060566c73fbe1639df4575ae",
-    "visual/Elevation.md": "100532c631803e9a97018b9da5ffff60acf7d80559f9f162ba9e371f5510371f",
+    "rules.json": "552c8328f60adc9eef4aa9aeed098e3a5c617e993bd300781389da8ad0e402c9",
+    "visual/ActionsInPlace.md": "53642e27b528b56b4c0c8d331ee8f5118525119f4d69eb63e04a3a174d2be73b",
+    "visual/Charts.md": "9439a024d8123088f90bb49844f922ce50ba4f255d85e7e6324bb55eee07f287",
+    "visual/Distinctiveness.md": "1a5e5b15ffcb3956641e0bfc3ec83e89721a756a4ee2498a79a47dfb3c0a9fe1",
+    "visual/Elevation.md": "50f2aeefd457e1a329cc80578b196c48cbf0c019a5f43d75901d92b4b4632c44",
     "visual/Fundamentals.md": "65120fd170ff8ea9f50b1498bfedc8c45dbe1a616bfccc32664213e5404d3a32",
-    "visual/Research.md": "ca9931eb15547b86cff525126cba2a09e6e0751ad2739a60f453c83ed8d84216"
+    "visual/Mobile.md": "511db58119a1653c2c00e2ccb34c6cf943de93f2184dec0faf3228f563e0b1b7",
+    "visual/Motion.md": "7fa4e7501b710a5599c7a8c99e531f2b9b1b4dfeba6a6a4d9716685d45f33d31",
+    "visual/README.md": "08c3a9ef3ff53a0fb8f9f873240022edefc67739a16d1f50c3a47367f72fc9f9",
+    "visual/Research.md": "41dd014a568e1d4a8da700550d413e54b78836a920531955acaaf491e9d1b7d1",
+    "visual/Theming.md": "250b4a710d0b94854430d59d7700c86a0c55e8d99a5c325580d8a4cae4f9c9aa"
   }
 }

package/dist/guidance/patterns/screen-layout.md

@@ -17,7 +17,7 @@ Name the task, choose the frame from the table, build it, then check the build a
 | Focused editor | make or change one thing | the thing being made | `Breadcrumb` back, `PageHeader` with one primary action, the editor, `SyncIndicator` or `SaveBar` |
 | Guided flow | set something up in order | the current step | `Stepper` and the [review and submit](review-submit.md) contract |
 | Decision | approve, choose or confirm | the choice and its consequence | the [consequential action](consequential-action.md) contract, `PlanPicker`, `Confirmation` |
-| Report | read and understand | a chart with a `takeaway`, or one `Stat size="hero"` | `ChartContainer`, `Stat`, `StatGroup` for the secondary numbers ([Charts](../../Charts.md)) |
+| Report | read and understand | a chart with a `takeaway`, or one `Stat size="hero"` | `ChartContainer`, `Stat`, `StatGroup` for the secondary numbers ([Charts](../visual/Charts.md)) |
 
 **Focused editor.** No navigation sidebar: a breadcrumb back is enough. The thing being made fills the column; details about it sit beside it, narrower and quieter. The one primary action (Publish, Send) is in the page header; saving is a status, not a second button.
 

package/dist/guidance/references/build/checks/agent-setup.mjs

@@ -21,6 +21,13 @@ try {
     writeFileSync(p,original);
     const preview=run(['init','--client',client]);assert.equal(preview.mode,'preview');assert.equal(readFileSync(p,'utf8'),original);
     assert.ok(preview.changes[0].after.includes(`Altitude framework (${version})`));
+    // The block is read on every turn: a compact index plus the rules, under 8 KB, naming only paths that exist.
+    {const body=preview.changes[0].after.match(/<!-- altitude:start[^>]*-->\n([\s\S]*?)<!-- altitude:end -->/)[1];
+     assert.ok(Buffer.byteLength(body)<=8192,`instruction block is ${Buffer.byteLength(body)} bytes, over the 8 KB budget`);
+     const index=JSON.parse(readFileSync(resolve(dir,'node_modules/altitude-design/dist/guidance/index.json'),'utf8'));
+     for(const c of index.components)assert.ok(new RegExp(`[|,]${c.name}(,|\\n)`).test(body),`block indexes ${c.name}`);
+     for(const p of body.match(/node_modules\/altitude-design\/[^\s,;]+[^\s,;.]/g))if(!p.includes('<Name>'))assert.ok(existsSync(resolve(dir,p)),`block names ${p}, which isn't installed`);
+     assert.ok(existsSync(resolve(dir,'node_modules/altitude-design/dist/guidance/components',index.components[0].name,'README.md')),'component guide path pattern resolves');}
     run(['init','--client',client,'--apply']);const installed=readFileSync(p,'utf8');assert.ok(installed.startsWith(original));
     const again=run(['init','--client',client,'--apply']);assert.equal(again.changes[0].action,'unchanged');assert.equal(readFileSync(p,'utf8'),installed);
     assert.ok(run(['doctor','--json']).ok);

package/dist/guidance/references/build/checks/guidance.mjs

@@ -2,8 +2,8 @@
 import assert from 'node:assert/strict';
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { resolve, relative } from 'node:path';
-import { buildGuidance, inputs, listFiles, root } from '../../scripts/build-guidance.mjs';
+import { dirname, resolve, relative } from 'node:path';
+import { buildGuidance, inputs, listFiles, relativeLinks, root } from '../../scripts/build-guidance.mjs';
 const {base,patterns,refs,version}=inputs();
 const read=p=>JSON.parse(readFileSync(p,'utf8'));
 const schema=read(resolve(base,'pattern.schema.json'));
@@ -61,6 +61,12 @@ try {
   const expected=listFiles(temp).map(p=>relative(temp,p)).sort(),actual=listFiles(dist).map(p=>relative(dist,p)).sort();
   assert.deepEqual(actual,expected,'distributed file inventory is fresh');
   for(const p of expected)assert.deepEqual(readFileSync(resolve(dist,p)),readFileSync(resolve(temp,p)),`stale generated guidance: ${p}`);
+  // An agent reads these from node_modules: every relative link has to land on a file the package ships.
+  let links=0;
+  for(const p of expected.filter(p=>p.endsWith('.md')))for(const {target} of relativeLinks(readFileSync(resolve(temp,p),'utf8'))){
+    links++;assert.ok(existsSync(resolve(temp,dirname(p),target.split('#')[0])),`${p}: link to ${target} doesn't resolve in the package`);
+  }
+  assert.ok(links>0,'the link check found links to check');
   assert.equal(read(resolve(dist,'index.json')).version,version);
   const pkg=read(resolve(root,'package.json'));
   assert.ok(existsSync(resolve(root,pkg.bin.altitude)),'shipped binary exists');

package/dist/guidance/references/build/checks/source-check.mjs

@@ -0,0 +1,101 @@
+// `altitude check`'s rules (scripts/source-check.mjs), each proven active: it catches its example and passes its
+// counter-example. Then the CLI is run on a small fixture app, to check exit codes and that every rule it reports has
+// an entry in project/framework/rules.json, so `altitude explain` resolves it. No browser, no network.
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RULES, scan } from '../../scripts/source-check.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const app = (body) => `import 'altitude-design/altitude.css';\nimport { AltitudeProvider, Button, Input } from 'altitude-design';\nexport function App() { return <AltitudeProvider>${body}</AltitudeProvider>; }\n`;
+const tokenNames = new Set([...readFileSync(resolve(root, 'project/tokens.json'), 'utf8').matchAll(/"(ink|accent|surface-[\w-]+|line)"/g)].map((m) => m[1]).concat(['ink', 'accent']));
+
+// [rule, files that must produce it, files that must not]
+const cases = [
+  ['ALT-TOKEN-001',
+    { 'App.tsx': app('<p style={{ color: "#6b7280" }}>Hi</p>') },
+    { 'App.tsx': app('<p style={{ color: "var(--ink-muted)" }}>Hi</p>'), 'theme.ts': "export const paper = { name: 'paper', tokens: { ink: '#1b1b1b' } };", 'brand.tsx': "<AltitudeProvider accent=\"#0f8a6b\" />", 'a.css': ':root { --brand: #0f8a6b; }\n.x { color: var(--brand); }\n/* color: #fff */'}],
+  ['ALT-TOKEN-001', { 'a.css': '.title { color: #6b7280; }' }, { 'a.css': '.title { color: var(--ink-muted); } /* was #6b7280 */' }],
+  ['ALT-TOKEN-001',
+    { 'App.tsx': app('<p className="text-sm text-zinc-500">Hi</p>') },
+    { 'App.tsx': app('<p className="text-sm text-muted-foreground border-b">Hi</p>') }],
+  ['ALT-TOKEN-001',
+    { 'index.html': '<style>\n  .card { background: #fafafa; }\n</style>\n<p style="color: #333">Hi</p>' },
+    { 'index.html': '<style>\n  :root { --brand: #0f8a6b; }\n  .card { background: var(--surface-raised); }\n</style>\n<a href="#main">Skip to content</a>' }],
+  ['ALT-TOKEN-001', { 'App.tsx': app('<p style={{ color: "#6b7280" }}>Hi</p>') }, { 'App.tsx': app('{/* altitude-ignore: ALT-TOKEN-001 partner logo colour */}\n<p style={{ color: "#6b7280" }}>Hi</p>') }],
+  ['ALT-SETUP-002',
+    { 'App.tsx': "import { Button } from 'altitude-design';\nexport const A = () => <AltitudeProvider><Button>Save changes</Button></AltitudeProvider>;" },
+    { 'App.tsx': app('<Button>Save changes</Button>'), 'other.ts': 'export const x = 1;' }],
+  ['ALT-SETUP-003',
+    { 'App.tsx': "import 'altitude-design/altitude.css';\nimport { Button } from 'altitude-design';\nexport const A = () => <Button>Save changes</Button>;" },
+    { 'App.tsx': app('<Button>Save changes</Button>') }],
+  ['ALT-CHART-001',
+    { 'Chart.tsx': "import { PieChart, Pie } from 'recharts';" },
+    { 'Chart.tsx': "import { BarChart } from 'altitude-design';" }],
+  ['ALT-CHART-001', { 'chart.ts': "new Chart(el, { type: 'doughnut', data });" }, { 'chart.ts': "new Chart(el, { type: 'bar', data });" }],
+  // A namespace import (import * as A from 'altitude-design') is as common in generated apps as named imports.
+  ['ALT-SETUP-003',
+    { 'main.tsx': "import 'altitude-design/altitude.css';\nimport * as A from 'altitude-design';\nexport const App = () => <A.Button>Save changes</A.Button>;" },
+    { 'main.tsx': "import 'altitude-design/altitude.css';\nimport * as A from 'altitude-design';\nroot.render(<A.AltitudeProvider><App/></A.AltitudeProvider>);" }],
+  ['ALT-COPY-001', { 'App.tsx': app('<Button variant="primary">Submit</Button>') }, { 'App.tsx': app('<Button variant="primary">Send invite</Button>') }],
+  ['ALT-COPY-001', { 'App.tsx': app('<A.Button variant="primary">OK</A.Button>') }, { 'App.tsx': app('<A.Button variant="primary">Save changes</A.Button>') }],
+  ['ALT-PRIMARY-001',
+    { 'App.tsx': app('<Button variant="primary">Save changes</Button><Button variant="primary">Publish</Button>') },
+    { 'App.tsx': app('<Button variant="primary">Save changes</Button><Button variant="ghost">Cancel</Button>') }],
+  ['ALT-VISUAL-004',
+    { 'App.tsx': app('<Input className="shadow-lg" aria-label="Search" />') },
+    { 'App.tsx': app('<Input aria-label="Search" />') }],
+];
+
+const write = (files) => {
+  const dir = mkdtempSync(join(tmpdir(), 'altitude-source-check-'));
+  for (const [name, text] of Object.entries(files)) { mkdirSync(dirname(join(dir, name)), { recursive: true }); writeFileSync(join(dir, name), text); }
+  return dir;
+};
+const covered = new Set();
+for (const [id, bad, good] of cases) {
+  for (const [files, expect] of [[bad, true], [good, false]]) {
+    const dir = write(files);
+    try {
+      const { findings } = scan(dir, { tokenNames });
+      const hit = findings.some((f) => f.ruleId === id && (id !== 'ALT-SETUP-003' || f.kind === 'deterministic'));
+      assert.equal(hit, expect, `${id} ${expect ? 'should catch' : 'should pass'}: ${JSON.stringify(files)}\n${JSON.stringify(findings, null, 1)}`);
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  }
+  covered.add(id);
+}
+assert.deepEqual([...covered].sort(), Object.keys(RULES).sort(), 'every rule has a case');
+
+// Every rule the scanner can report is explained in rules.json, with the same kind.
+const rules = JSON.parse(readFileSync(resolve(root, 'project/framework/rules.json'), 'utf8')).rules;
+for (const [id, { kind }] of Object.entries(RULES)) {
+  const r = rules.find((x) => x.id === id);
+  assert.ok(r, `${id} has an entry in rules.json`);
+  assert.equal(r.diagnosticClass, kind, `${id}: rules.json diagnosticClass matches the scanner`);
+}
+
+// The CLI on a fixture app: exit 1 with a deterministic finding, 0 with only reviews; JSON states its scope.
+const cli = resolve(root, 'scripts/altitude-cli.mjs');
+const project = write({ 'package.json': '{"name":"fixture","private":true}', 'src/App.tsx': app('<Button variant="primary">OK</Button>') });
+try {
+  // A minimal installed package: what the CLI reads to locate itself. CI's checks jobs don't build dist/, and this
+  // tests the command from source (the packed consumer check runs the built one).
+  const pkg = join(project, 'node_modules/altitude-design');
+  mkdirSync(join(pkg, 'dist/guidance'), { recursive: true });
+  writeFileSync(join(pkg, 'package.json'), JSON.stringify({ name: 'altitude-design', version: '0.0.0' }));
+  writeFileSync(join(pkg, 'dist/guidance/index.json'), JSON.stringify({ version: '0.0.0', patterns: [], components: [] }));
+  writeFileSync(join(pkg, 'dist/tokens.css'), ':root { --ink: #12161f; --accent: #2b56d6; }');
+  let failed;
+  try { execFileSync(process.execPath, [cli, 'check', '--json', '--cwd', project], { encoding: 'utf8' }); failed = false; }
+  catch (e) { failed = true; const out = JSON.parse(e.stdout); assert.equal(out.ok, false); assert.ok(out.findings.some((f) => f.ruleId === 'ALT-COPY-001' && f.file === 'App.tsx' && f.line === 3)); assert.match(out.scope, /Not checked/); }
+  assert.ok(failed, 'check exits non-zero on a deterministic finding');
+  writeFileSync(join(project, 'src/App.tsx'), app('<Button variant="primary">Save changes</Button><Button variant="primary">Publish</Button>'));
+  const out = JSON.parse(execFileSync(process.execPath, [cli, 'check', '--json', '--cwd', project], { encoding: 'utf8' }));
+  assert.equal(out.ok, true, 'reviews alone pass');
+  assert.ok(out.findings.every((f) => f.kind === 'contextual-review'));
+} finally { rmSync(project, { recursive: true, force: true }); }
+
+console.log(`source check: ${Object.keys(RULES).length} rules each catch their example and pass their counter-example; CLI exit codes and rules.json entries pass`);