division-ds 0.2.0 → 0.3.0

package/public/manifest/tokens.json

@@ -564,7 +564,11 @@
       "name": "--color-accent-signal-fill",
       "layer": "semantic",
       "value": "#f2550f",
-      "use": "A solid block in the brand orange: the primary Button, a solid signal Badge. Put accent.signal.ink on it, never text.primary."
+      "use": "A solid block in the brand colour, exactly as chosen: the primary Button, IconButton, a solid signal Badge. Put accent.signal.ink on it, never text.primary. Never use it as the only sign of a state; use accent.signal.indicator.",
+      "measured": {
+        "dark": "The brand colour, exactly as chosen: Button, IconButton and solid Badge backgrounds, and brand decoration. Text on it is accent.signal.ink. Never the only sign of a state; that is accent.signal.indicator. The theme builder never moves it.",
+        "light": "The brand colour, exactly as chosen: Button, IconButton and solid Badge backgrounds, and brand decoration. Text on it is accent.signal.ink. Never the only sign of a state; that is accent.signal.indicator. The theme builder never moves it."
+      }
     },
     {
       "name": "--color-accent-signal-text",
@@ -585,7 +589,28 @@
       "value": "#0a0602",
       "use": "Text and icons on accent.signal.fill.",
       "measured": {
-        "dark": "5.85:1 on accent.signal.fill"
+        "dark": "5.85:1 on accent.signal.fill",
+        "light": "5.85:1 on accent.signal.fill"
+      }
+    },
+    {
+      "name": "--color-accent-signal-indicator",
+      "layer": "semantic",
+      "value": "#f2550f",
+      "use": "The accent where colour alone shows a state or value: a checked control, Switch on, Progress, Slider, Rating stars, the current item in Sidebar, Navbar, Tabs, SegmentedControl, Stepper and highlighted menu rows. Put accent.signal.indicator-ink on it.",
+      "measured": {
+        "dark": "The accent where colour alone marks a state or a value: checked controls, Switch on, Progress, Slider, Rating stars, the current item of Sidebar, Navbar, Tabs, SegmentedControl, Stepper and highlighted menu rows, and the hero numerals. 5.80:1 on surface.base. Same stop as accent.signal.fill here; the theme builder moves it to a nearby stop when a chosen accent is too pale or too dark to reach 3:1, and leaves accent.signal.fill alone.",
+        "light": "The accent where colour alone marks a state or a value: checked controls, Switch on, Progress, Slider, Rating stars, the current item of Sidebar, Navbar, Tabs, SegmentedControl, Stepper and highlighted menu rows, and the hero numerals. 3.14:1 on surface.base. Same stop as accent.signal.fill here; the theme builder moves it to a nearby stop when a chosen accent is too pale or too dark to reach 3:1, and leaves accent.signal.fill alone."
+      }
+    },
+    {
+      "name": "--color-accent-signal-indicator-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text and icons on accent.signal.indicator.",
+      "measured": {
+        "dark": "Text and icons on accent.signal.indicator. 5.85:1. The theme builder picks white or this dark ink, whichever reaches 4.5:1.",
+        "light": "Text and icons on accent.signal.indicator. 5.85:1. The theme builder picks white or this dark ink, whichever reaches 4.5:1."
       }
     },
     {
@@ -595,7 +620,7 @@
       "use": "The faint orange hover wash under a nav item or an inactive tab.",
       "measured": {
         "dark": "Hover wash under a nav item or an inactive tab. Text on it is text.primary and gated. The focus ring and a checked control's fill drop under 3:1 on it in light theme, so neither is ever drawn on it.",
-        "light": "Hover wash under a nav item or an inactive tab. Text on it is text.primary and gated. The focus ring and a checked control's fill drop under 3:1 on it in light theme, so neither is ever drawn on it."
+        "light": "Hover wash under a nav item or an inactive tab. Text on it is text.primary and gated. A checked control's indicator drops under 3:1 on it in light theme and the focus ring is not gated on it, so neither is ever drawn on it."
       }
     },
     {
@@ -782,8 +807,14 @@
     {
       "name": "--color-focus-ring",
       "layer": "semantic",
-      "value": "#f2550f",
-      "use": "The keyboard focus outline. Use it only in focus-visible:outline-[var(--color-focus-ring)], with a 2px outline and a 2px offset."
+      "value": {
+        "dark": "#f2550f",
+        "light": "#c6440b"
+      },
+      "use": "The keyboard focus outline. Use it only in focus-visible:outline-[var(--color-focus-ring)], with a 2px outline and a 2px offset.",
+      "measured": {
+        "light": "4.51:1 on surface.base. A step darker than accent.signal.fill, which reaches only 3.14:1 on the light page: the ring is the one mark every keyboard user depends on, so it gets a margin."
+      }
     },
     {
       "name": "--color-chart-series-1",

package/scripts/division-ds.mjs

@@ -19,7 +19,7 @@
 import { existsSync, globSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { extractRules } from './lib/agent-docs.mjs'
+import { DOCS_SITE, extractRules, SKILL_SOURCE } from './lib/agent-docs.mjs'
 import { checkText } from './lib/check-text.mjs'
 import { createServer } from './lib/mcp-server.mjs'
 import { createTools } from './lib/mcp-tools.mjs'
@@ -28,14 +28,14 @@ import { applyPlan, diff, planRules, planSkill, SKILL_TARGETS, TARGETS } from '.
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
 const DEFAULT_MANIFEST = join(ROOT, 'public/manifest/components.json')
-const CHECKED = /\.(tsx|jsx|ts)$/
+const CHECKED = /\.(tsx|jsx|ts|css)$/
 const SKIPPED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage'])
 
 const HELP = `division-ds: Division DS gates and agent rules for a project that uses the components.
 
 Usage:
   division-ds check [paths...] [--manifest <path|url>] [--tokens <path|url>] [--json]
-      Checks .tsx, .jsx and .ts files (default: ./src). A path may be a file, a directory or a
+      Checks .tsx, .jsx, .ts and .css files (default: ./src; a .css file gets the colour gate only). A path may be a file, a directory or a
       glob ("src/**/*.tsx"). Runs five gates and exits 1 on any finding:
         token-discipline   raw colours, Tailwind palette classes, token names that do not exist
         button-spacing     two Buttons/IconButtons side by side with no gap on their parent
@@ -149,12 +149,12 @@ async function check(options) {
       if (gate === 'button-spacing') console.error(`      ${ofGate[0].fix}`)
       console.error('')
     }
-    console.error('Each component\'s props, values and examples: /docs/components/<slug>.md. Tokens: public/manifest/tokens.json.')
+    console.error(`Each component's props, values and examples: ${DOCS_SITE}docs/components/<slug>.md. Tokens: ${DOCS_SITE}llms-tokens.txt.`)
   } else {
     console.log(`division-ds check passed: ${files.length} file(s), ${index.size} components, ${tokenNames.length} tokens, 0 findings.`)
     // It reads code, not the running page: say so, or a pass reads as "the screen works" (the
     // 2026-10-20 outside test shipped three runtime bugs past a clean check).
-    console.log('Checked: colours, tokens, button spacing, inline host cards, props and AI copy. Not checked: how the screen behaves; run the review checklist (commands/review.md) in a browser.')
+    console.log(`Checked: colours, tokens, button spacing, inline host cards, props and AI copy. Not checked: how the screen behaves; run the review checklist in a browser (commands/review.md from \`npx division-ds skill\`, or ${SKILL_SOURCE}commands/review.md).`)
   }
   process.exit(findings.length > 0 ? 1 : 0)
 }

package/scripts/lib/agent-docs.mjs

@@ -8,6 +8,8 @@ const TIER_NOUN = { atoms: 'Atom', molecules: 'Molecule', organisms: 'Organism'
 export const DOCS_SITE = 'https://victor-ilioiu.vercel.app/systems/division-ds/'
 /** Where shadcn downloads the components from: public/r/ in the public GitHub repository. */
 export const REGISTRY = 'https://raw.githubusercontent.com/Victor-Ilioiu/division-ds/main/public/r'
+/** The skill's files in the public repository, for a reader who has the package but not the skill. */
+export const SKILL_SOURCE = 'https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/'
 
 /** A table cell: one line, with the pipes that would end the cell escaped. */
 const cell = text => String(text ?? '').replace(/\s*\n\s*/g, ' ').replace(/\|/g, '\\|')
@@ -19,14 +21,50 @@ export function importLines(entry) {
   return entry.imports.map(({ names, from }) => `import { ${names.join(', ')} } from '${from}'`).join('\n')
 }
 
+/** The other components a page documents, by export name: ChatMessage's ResponseFeedback,
+ *  ProductCard's ProductGrid. Parts named after the component (CardBody, RadioGroup) and helpers
+ *  (lower case) are left out. The 2026-10-29 outside test could not find ResponseFeedback because
+ *  only its parent was listed anywhere an agent looks first. */
+export function alsoExports(entry) {
+  return entry.imports
+    .flatMap(({ names }) => names)
+    .filter(name => /^[A-Z][a-z]/.test(name) && !name.startsWith(entry.name) && !name.endsWith('Provider'))
+}
+
+/** The docs site's top-bar search reads this, fetched the first time search opens. Slim on purpose:
+ *  the names, the one-line summaries and the prop names and descriptions the shared scorer
+ *  (search-score.mjs) ranks on, and the screen-facing tokens. Primitives are left out, as in the
+ *  MCP search: they are never the answer for a screen. */
+export function searchIndex(entries, tokens) {
+  const index = {
+    generatedBy: 'scripts/build-agent-docs.mjs',
+    components: entries.map(entry => ({
+      name: entry.name,
+      slug: entry.slug,
+      tier: entry.tier,
+      summary: entry.summary,
+      useWhen: entry.useWhen,
+      also: alsoExports(entry),
+      props: entry.props.map(prop => ({ name: prop.name, description: prop.description ?? '' })),
+    })),
+    tokens: tokens.tokens.filter(token => token.layer !== 'primitive').map(token => ({ name: token.name, layer: token.layer, use: token.use ?? '' })),
+  }
+  return JSON.stringify(index) + '\n'
+}
+
+/** Said under every Import block: the paths are the repository's, not an installed project's. */
+export const INSTALLED_PATHS = 'Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.'
+
 /** One component as a markdown page. `entry` is a manifest entry (see `manifestEntry`). */
 export function componentMarkdown(entry) {
   const out = [`# ${entry.name}`, '', `> ${entry.summary}`, '']
   out.push(`- **Best for:** ${entry.useWhen}`, `- **Not for:** ${entry.notFor}`)
+  const also = alsoExports(entry)
+  if (also.length) out.push(`- **Also on this page:** ${also.map(code).join(', ')}`)
   out.push(`- ${TIER_NOUN[entry.tier]}. Source: \`${entry.source}\``)
   out.push(`- Rendered docs page: \`/components/${entry.slug}\``, '')
 
-  out.push('## Import', '', fence(importLines(entry)), '')
+  out.push('## Import', '', fence(importLines(entry)), '', INSTALLED_PATHS, '')
 
   if (entry.requires?.length) {
     out.push('## Requires', '', ...entry.requires.map(item => `- ${item}`), '')
@@ -108,8 +146,10 @@ const byTier = entries =>
 export const firstSentence = text => text.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? text
 
 /** One component's line in llms.txt: what it is, then best for and not for. */
-export const indexLine = entry =>
-  `- [${entry.name}](${entry.docs.replace(/^\//, '')}): ${firstSentence(entry.summary)} Best for: ${entry.useWhen} Not for: ${entry.notFor}`
+export const indexLine = entry => {
+  const also = alsoExports(entry)
+  return `- [${entry.name}](${entry.docs.replace(/^\//, '')}): ${firstSentence(entry.summary)} Best for: ${entry.useWhen} Not for: ${entry.notFor}${also.length ? ` Also: ${also.join(', ')}.` : ''}`
+}
 
 /** llms.txt, in the llmstxt.org shape: a title, a summary, then sections of links. */
 export function llmsIndex(entries, { rules }) {
@@ -245,7 +285,10 @@ export function designFile(entries, manifest, { fonts, rules }) {
   ]
   for (const [tier, group] of byTier(entries)) {
     out.push(`## ${tier[0].toUpperCase()}${tier.slice(1)}`, '')
-    for (const entry of group) out.push(`- [${entry.name}](${entry.docs.replace(/^\//, '')}): ${firstSentence(entry.summary)}`)
+    for (const entry of group) {
+      const also = alsoExports(entry)
+      out.push(`- [${entry.name}](${entry.docs.replace(/^\//, '')}): ${firstSentence(entry.summary)}${also.length ? ` Also: ${also.join(', ')}.` : ''}`)
+    }
     out.push('')
   }
   out.push('## Rules', '', 'In full: [llms-guidelines.txt](llms-guidelines.txt).', '', ...ruleHeadlines(rules).map(line => `- ${line}`), '')
@@ -462,7 +505,7 @@ const SKILL_COMMANDS = {
     body: [
       'Go through every line. A line that does not hold is a change to make, not a note to leave.',
       '',
-      '- [ ] **States.** Every region has its empty, loading, error, success and disabled or no-permission state, as planned in `commands/build.md`. An empty list says what is empty and offers the action that fills it.',
+      '- [ ] **States.** Every region has its empty, loading, error, success and disabled or no-permission state, as planned before the code (the regions-and-states plan of `commands/build.md`). An empty list says what is empty and offers the action that fills it.',
       '- [ ] **Headings.** One `PageHeader`, so one `h1`. Section headings continue the outline: `h2` under the `h1`, `h3` inside an `h2`, no level skipped. `SectionHeading` is given the level.',
       '- [ ] **Tokens only.** No hex, `rgb()`, palette class or invented token name. `division-ds check` passes.',
       '- [ ] **Buttons.** Two or more side by side share a parent with a gap. One primary button per view. A busy button takes `loading`; a disabled one says why nearby. Icon-only actions are `IconButton` with a `label`.',
@@ -557,7 +600,7 @@ export function skillFiles(split, componentCount) {
       '',
       // A project that installed the components has no public/ folder of ours (the 2026-10-20
       // outside test followed these steps to files that did not exist).
-      `Paths starting \`public/\` are in the Division DS repository. In a project that uses the components, read them online: \`public/llms.txt\` is \`${DOCS_SITE}llms.txt\`, and so on.`,
+      `Paths starting \`public/\` are in the Division DS repository. In a project that uses the components, read them online: \`public/llms.txt\` is \`${DOCS_SITE}llms.txt\`, and so on. The other procedures named here (\`commands/build.md\` and the rest) are in the skill: \`${SKILL_SOURCE}commands/<name>.md\`, or \`npx division-ds skill\` to install them.`,
       '',
       ...command.body,
       '',

package/scripts/lib/ai-copy.mjs

@@ -16,7 +16,9 @@
 // - `assistant-copy`: "answer", "please" or "!" in the interface text of the assistant components
 //   (ChatThread, ChatMessage, PromptInput, ApprovalRequest, ToolCall): their label-like string
 //   props only. Message bodies, a ToolCall's input and output and PromptInput's suggestions are
-//   content written by the person or the model, not the interface, and are never read.
+//   content written by the person or the model, not the interface, and are never read. A button
+//   placed inside one of them (a Button in ChatMessage's `actions`) is its interface too: its label
+//   and aria-label are checked the same way (missed by the 2026-10-29 outside test's probe).
 // Only literals are read (a string attribute, JSX text, a ternary of two literals). A variable is
 // not judged, the same as the props gate.
 import ts from 'typescript'
@@ -63,11 +65,22 @@ export function findAiCopyViolations(text, path) {
     const at = source.getLineAndCharacterOfPosition(node.getStart(source))
     violations.push({ path, line: at.line + 1, column: at.character + 1, rule, found, fix })
   }
+  // How many assistant components the walk is inside: a button in there speaks for the assistant.
+  let insideAssistant = 0
   const checkCta = (node, value, where) => {
     if (AI_WORD.test(value)) add(node, 'ai-in-cta', `${where}: "${value.trim()}"`, AI_FIX)
+    if (insideAssistant > 0) {
+      for (const word of ASSISTANT_WORDS) {
+        if (word.pattern.test(value)) add(node, 'assistant-copy', `${where} in an assistant component: "${value.trim()}"`, word.fix)
+      }
+    }
   }
+  const tagOf = node =>
+    ts.isJsxElement(node) ? node.openingElement.tagName.getText(source) : ts.isJsxSelfClosingElement(node) ? node.tagName.getText(source) : undefined
 
   const visit = node => {
+    const opensAssistant = tagOf(node) in ASSISTANT_COPY
+    if (opensAssistant) insideAssistant++
     if (ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) {
       const tag = node.tagName.getText(source)
       for (const attribute of node.attributes.properties) {
@@ -96,6 +109,7 @@ export function findAiCopyViolations(text, path) {
       if (label.trim()) checkCta(node, label, `<${tag}> label`)
     }
     ts.forEachChild(node, visit)
+    if (opensAssistant) insideAssistant--
   }
   visit(source)
   return violations.sort((a, b) => a.line - b.line || a.column - b.column)

package/scripts/lib/check-text.mjs

@@ -10,10 +10,23 @@ import { findViolations as tokenDiscipline, formatViolation as formatTokenDiscip
 export const BUTTON_SPACING_FIX =
   'Wrap the buttons in one parent with a flex/grid class and a gap- utility (flex flex-wrap items-center gap-3), and move any margin from the buttons onto it.'
 
+/** A stylesheet with the value of every declaration of a real token blanked, newlines kept so line
+ *  numbers hold. Setting a token is how a project themes the system (the theme builder writes
+ *  exactly that into index.css), so a literal colour there is the point; anywhere else in the file,
+ *  or on a custom property the system does not have, it is reported as in any other file. */
+export function blankTokenOverrides(text, tokenNames) {
+  const known = new Set(tokenNames)
+  return text.replace(/(--[a-z0-9-]+)(\s*:)([^;}]*)/g, (match, name, colon, value) =>
+    // The var() references stay, so a token set from a name that does not exist is still caught.
+    known.has(name) ? name + colon + value.replace(/var\([^)]*\)|[^\n]/g, part => (part.length > 1 ? part : ' ')) : match
+  )
+}
+
 /** Every finding in `text`. `path` decides which gates apply (button spacing and AI copy need JSX) and is
  *  echoed into each finding. `index` is buildIndex(manifest); `tokenNames` the token names. */
 export function checkText(text, path, index, tokenNames) {
   const findings = []
+  if (/\.css$/.test(path)) text = blankTokenOverrides(text, tokenNames)
   for (const v of tokenDiscipline(text, path, tokenNames)) {
     findings.push({ gate: 'token-discipline', path, line: v.line, rule: v.rule, found: v.found, fix: v.fix, text: formatTokenDiscipline(v) })
   }

package/scripts/lib/mcp-server.mjs

@@ -12,7 +12,8 @@ export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '202
 
 const INSTRUCTIONS = `Division DS: a React 19, Tailwind 4 and Radix design system.
 Before writing a component, call get_component for its props and examples. Use only tokens from get_tokens or search, as var(--name).
-Before saying a screen is done, call validate_code on each file you wrote and fix every finding, then go through get_review_checklist.`
+Before saying a screen is done, call validate_code on each file you wrote (.css too) and fix every finding, then go through get_review_checklist.
+Shared helpers (theme toggle, form errors, money, links): https://victor-ilioiu.vercel.app/systems/division-ds/docs/helpers.md`
 
 /** A JSON-RPC error reply. */
 const failure = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } })

package/scripts/lib/mcp-tools.mjs

@@ -5,9 +5,11 @@
 // Most design-system MCP servers stop at list / search / get docs (shadcn, Chakra, Dialtone,
 // Blade, Vibe; surveyed 2026-10-25). `validate_code` is the one they lack: it runs the same gates
 // as `division-ds check` on the code the agent has just written, before the agent says it is done.
+import { alsoExports, INSTALLED_PATHS } from './agent-docs.mjs'
 import { checkText } from './check-text.mjs'
 import { contrastRatio } from './contrast.mjs'
 import { buildIndex, closest } from './props-validator.mjs'
+import { scorer, words } from './search-score.mjs'
 
 export const REGISTRY_BASE = 'https://raw.githubusercontent.com/Victor-Ilioiu/division-ds/main/public/r'
 const TIERS = ['atoms', 'molecules', 'organisms']
@@ -15,7 +17,6 @@ const LAYERS = ['primitive', 'spacing', 'motion', 'semantic', 'component']
 // WCAG 2.2 minimums: SC 1.4.3 for text, SC 1.4.11 for the boundary of a control or a graphic.
 const MINIMUMS = { normal: 4.5, large: 3, ui: 3 }
 
-const words = text => String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
 
 /** `context`: { manifest, tokens, version, readDoc(slug) -> string|undefined, readChecklist() -> string|undefined } */
 export function createTools(context) {
@@ -30,7 +31,11 @@ export function createTools(context) {
 
   function findComponent(name) {
     const wanted = String(name ?? '').trim().toLowerCase()
-    return components.find(c => c.name.toLowerCase() === wanted || c.slug === wanted)
+    return (
+      components.find(c => c.name.toLowerCase() === wanted || c.slug === wanted) ??
+      // A component documented on another's page (ResponseFeedback on ChatMessage's) opens that page.
+      components.find(c => alsoExports(c).some(other => other.toLowerCase() === wanted))
+    )
   }
 
   function unknownComponent(name) {
@@ -66,7 +71,12 @@ export function createTools(context) {
       run({ tier } = {}) {
         if (tier !== undefined && !TIERS.includes(tier)) throw new ToolError(`tier is one of ${TIERS.join(', ')}.`)
         const rows = components.filter(c => !tier || c.tier === tier)
-        return rows.map(c => `- ${c.name} (${c.tier}): ${c.useWhen}${c.notFor ? ` Not for: ${c.notFor}` : ''}`).join('\n')
+        return rows
+          .map(c => {
+            const also = alsoExports(c)
+            return `- ${c.name} (${c.tier}): ${c.useWhen}${c.notFor ? ` Not for: ${c.notFor}` : ''}${also.length ? ` Also on its page: ${also.join(', ')}.` : ''}`
+          })
+          .join('\n')
       },
     },
     {
@@ -85,7 +95,7 @@ export function createTools(context) {
         const c = findComponent(name) ?? unknownComponent(name)
         const imports = c.imports.map(i => `import { ${i.names.join(', ')} } from '${i.from}'`).join('\n')
         const props = c.props.map(p => `- ${p.name}: ${p.type}${p.default ? ` = ${p.default}` : ''}. ${p.description ?? ''}`.trimEnd()).join('\n')
-        const head = `# ${c.name} (${c.tier})\n\n${c.summary}\n\n${imports}\n\nPaths are from the Division DS repository root; installed with shadcn they start src/division-ds/.\n\n## Props\n\n${props}`
+        const head = `# ${c.name} (${c.tier})\n\n${c.summary}\n\n${imports}\n\n${INSTALLED_PATHS}\n\n## Props\n\n${props}`
         if (section === 'props') return head
         const page = context.readDoc?.(c.slug)
         // The page is the full contract (examples, keyboard, do and don't, written for agents).
@@ -112,13 +122,16 @@ export function createTools(context) {
       run({ query, limit = 10 }) {
         const terms = words(query)
         if (terms.length === 0) throw new ToolError('query has no words to search for.')
-        const score = (title, body) => {
-          const t = words(title).join(' ')
-          const b = words(body)
-          return terms.reduce((sum, term) => sum + (t.includes(term) ? 3 : 0) + b.filter(w => w.startsWith(term)).length, 0)
-        }
+        const score = scorer(query)
         const hits = [
-          ...components.map(c => ({ kind: 'component', name: c.name, line: c.useWhen, score: score(c.name, `${c.summary} ${c.useWhen}`) })),
+          // The title holds every name on the page (ChatMessage and ResponseFeedback); the body adds
+          // the prop descriptions, where what a part does is written ("helpful", "thumbs up").
+          ...components.map(c => {
+            const also = alsoExports(c)
+            const props = c.props.map(p => `${p.name} ${p.description ?? ''}`).join(' ')
+            const line = `${c.useWhen}${also.length ? ` Also on its page: ${also.join(', ')}.` : ''}`
+            return { kind: 'component', name: c.name, line, score: score(`${c.name} ${also.join(' ')}`, `${c.summary} ${c.useWhen}`, props, c.props.map(p => p.name).join(' ')) }
+          }),
           // Primitives are not for screens (tokens.json's rule), so they never come up as an answer.
           ...tokens.tokens.filter(t => t.layer !== 'primitive').map(t => ({ kind: `${t.layer} token`, name: t.name, line: t.use ?? '', score: score(t.name, t.use ?? '') })),
         ]
@@ -158,13 +171,13 @@ export function createTools(context) {
         type: 'object',
         properties: {
           code: { type: 'string', description: 'The whole file, imports included: props are matched through the imports.' },
-          filename: { type: 'string', description: 'Its name, e.g. "src/pages/Settings.tsx". The extension decides which gates run. Default "Screen.tsx".' },
+          filename: { type: 'string', description: 'Its name, e.g. "src/pages/Settings.tsx". The extension decides which gates run: a .css file gets the colour and token checks, and setting a real token (--color-surface-base: ...) is allowed there, since that is how a project themes the system. Default "Screen.tsx".' },
         },
         required: ['code'],
         additionalProperties: false,
       },
       run({ code, filename = 'Screen.tsx' }) {
-        if (!/\.(tsx|jsx|ts)$/.test(filename)) throw new ToolError('filename ends in .tsx, .jsx or .ts.')
+        if (!/\.(tsx|jsx|ts|css)$/.test(filename)) throw new ToolError('filename ends in .tsx, .jsx, .ts or .css.')
         const findings = checkText(String(code), filename, index, tokenNames)
         if (findings.length === 0) {
           return `No findings in ${filename}: colours, tokens, button spacing, props and AI copy are clean.\nNot checked: how the screen behaves. Run get_review_checklist, in a browser.`

package/scripts/lib/props-validator.mjs

@@ -28,6 +28,7 @@
 //   accepted; one the rest type names in its Omit<> is not. With a `...rest` row of a Radix
 //   component's props, any other prop is accepted (the Radix surface is not in the manifest).
 import ts from 'typescript'
+import { DOCS_SITE } from './agent-docs.mjs'
 import { parseRowName, resolvePart } from './component-props.mjs'
 
 /** Always accepted on any component: React's own props, and attributes every DOM wrapper takes. */
@@ -125,7 +126,7 @@ export function buildIndex(manifest) {
     if (exportNames.length === 0) continue
     const components = Object.fromEntries(exportNames.map(name => [name, true]))
     const specs = Object.fromEntries(
-      exportNames.map(name => [name, { entry: entry.name, docs: entry.docs, props: new Map(), rest: null }])
+      exportNames.map(name => [name, { entry: entry.name, docs: entry.docs && `${DOCS_SITE}${entry.docs.replace(/^\//, '')}`, props: new Map(), rest: null }])
     )
     let unresolved = false
     for (const row of entry.props ?? []) {

package/scripts/lib/search-score.mjs

@@ -0,0 +1,24 @@
+// The one ranking for "find me the thing for X". The MCP server's `search` tool and the docs site's
+// top-bar search both call it, so an agent and a person typing the same words get the same order.
+// Pure and dependency-free: it runs in Node and in the browser.
+
+export const words = text => String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+
+/** A scorer for one query. `title` is the names, `body` the summary; `props` (descriptions) and
+ *  `propNames` count once each, as hints, so a long prop table does not outrank a component or
+ *  token whose own summary is about the query. 0 means no match. */
+export function scorer(query) {
+  const terms = words(query)
+  return (title, body, props = '', propNames = '') => {
+    if (terms.length === 0) return 0
+    const t = words(title).join(' ')
+    const b = words(body)
+    const p = words(props)
+    const n = words(propNames)
+    const inMain = term => t.includes(term) || b.some(w => w.startsWith(term))
+    // Every word of the query in the name or summary beats one word found often: "page
+    // background" is the surface token, not PageHeader, whose name matches "page" alone.
+    const all = terms.length > 1 && terms.every(inMain) ? 5 : 0
+    return all + terms.reduce((sum, term) => sum + (t.includes(term) ? 3 : 0) + Math.min(b.filter(w => w.startsWith(term)).length, 3) + (inMain(term) ? 0 : n.some(w => w.startsWith(term)) ? 2 : p.some(w => w.startsWith(term)) ? 1 : 0), 0)
+  }
+}

package/scripts/lib/token-discipline.mjs

@@ -9,6 +9,12 @@
 // Colour only, on purpose. Spacing is not gated: enforcing it before the scale is complete makes
 // an author (or an agent) invent a token name to satisfy the rule, which is the worse failure.
 
+import { DOCS_SITE } from './agent-docs.mjs'
+
+/** Where a token list lives for whoever reads the finding: the MCP tool, or the docs site. A
+ *  repository path meant nothing in a project that installed the components (2026-10-29 test). */
+const TOKEN_LIST = `get_tokens over MCP, or ${DOCS_SITE}llms-tokens.txt`
+
 export const SCANNED_ROOTS = ['src']
 export const SCANNED_EXTENSIONS = /\.(tsx?|css)$/
 
@@ -16,6 +22,7 @@ export const SCANNED_EXTENSIONS = /\.(tsx?|css)$/
  *  A new entry needs a reason as good as these; "it was easier" is the case the gate exists for. */
 export const EXEMPT = [
   { pattern: /^src\/styles\/tokens\.css$/, why: 'generated from tokens/: this is where the literals are meant to be' },
+  { pattern: /(^|\/)division-ds\/styles\/tokens\.css$/, why: 'the same file, installed into a project by shadcn; it also names the MCP Apps host\'s own variables' },
   { pattern: /\.test\.tsx?$/, why: 'tests assert on literal values and on deliberately wrong input' },
   { pattern: /^src\/demo\/(scene|blob|terrain)\//, why: 'WebGL materials: three.js takes colours as numbers, not CSS variables' },
   { pattern: /^src\/components\/atoms\/loading-animation\/(palette|scene|kit|variants)\.ts$/, why: 'WebGL materials, read from the tokens at runtime where they can be' },
@@ -98,9 +105,9 @@ export function findViolations(text, path, tokenNames) {
       if (name.endsWith('-')) continue
       if (!known.has(name)) {
         const near = suggest(name, tokenNames)
-        add('unknown-token', `var(${name})`, near.length ? `No such token. Did you mean ${near.join(', ')}?` : 'No such token. The full list is public/manifest/tokens.json.')
+        add('unknown-token', `var(${name})`, near.length ? `No such token. Did you mean ${near.join(', ')}?` : `No such token. The full list: ${TOKEN_LIST}.`)
       } else if (PRIMITIVE_RAMP.test(name) && inComponents(path)) {
-        add('primitive-in-component', `var(${name})`, 'A component reads semantic tokens, not a ramp step. Pick one by intent from public/manifest/tokens.json (accent.<state>.text, .fill or .ink).')
+        add('primitive-in-component', `var(${name})`, `A component reads semantic tokens, not a ramp step. Pick one by intent (accent.<state>.text, .fill or .ink): ${TOKEN_LIST}.`)
       }
     }
 
@@ -108,7 +115,7 @@ export function findViolations(text, path, tokenNames) {
     // where a literal colour would be.
     const rest = line.replace(/var\([^)]*\)/g, '')
     for (const match of rest.matchAll(HEX)) {
-      add('raw-colour', match[0], 'Use a semantic token: text-[var(--color-text-primary)], bg-[var(--color-surface-base)]. Tokens and what each is for: public/manifest/tokens.json.')
+      add('raw-colour', match[0], `Use a semantic token: text-[var(--color-text-primary)], bg-[var(--color-surface-base)]. Tokens and what each is for: ${TOKEN_LIST}.`)
     }
     for (const match of rest.matchAll(COLOR_FUNCTION)) {
       add('raw-colour', match[0] + '…)', 'Use a semantic token. If no token fits, the colour is a change to the system: add it under tokens/ with a contrast pair.')

package/skills/division-ds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: division-ds
-description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 68 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
+description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 72 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
 ---
 
 # Division DS
@@ -82,7 +82,7 @@ provider. A project that uses the components mounts both itself (step 4 of `inst
 `src/demo/states/` files are not part of the system.
 
 **What the system does not have.** No Popover, no Combobox (single value: use `Select`; several:
-`MultiSelect`), no date picker. Do not reach into `src/demo/` from a component.
+`MultiSelect`). Do not reach into `src/demo/` from a component.
 
 **Vocabulary.** Inside this repository, `npm run check:vocabulary` bans a list of words in `src/`,
 `scripts/` and `e2e/` (the list is `scripts/lib/vocabulary.mjs`; it is not published with the

package/skills/division-ds/commands/add.md

@@ -2,7 +2,7 @@
 
 > Load when adding one component to a screen that already exists. Generated by `npm run agent-docs`; the procedure lives in scripts/lib/agent-docs.mjs.
 
-Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on.
+Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on. The other procedures named here (`commands/build.md` and the rest) are in the skill: `https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/<name>.md`, or `npx division-ds skill` to install them.
 
 1. Find it in `public/llms.txt`. Its "Best for" should describe your case and its "Not for"
    should not; if "Not for" names your case, use the component it names instead.

package/skills/division-ds/commands/build.md

@@ -2,7 +2,7 @@
 
 > Load when building a new screen or page. Plans the regions and their states before any code. Generated by `npm run agent-docs`; the procedure lives in scripts/lib/agent-docs.mjs.
 
-Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on.
+Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on. The other procedures named here (`commands/build.md` and the rest) are in the skill: `https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/<name>.md`, or `npx division-ds skill` to install them.
 
 Plan before code. The states a screen gets wrong are the ones nobody planned: an empty list
 with no message, a load that fails into a blank panel, a button that is disabled with no reason.

package/skills/division-ds/commands/fix.md

@@ -2,7 +2,7 @@
 
 > Load when a gate, `division-ds check` or a test has failed and named a rule. What each message means and the fix. Generated by `npm run agent-docs`; the procedure lives in scripts/lib/agent-docs.mjs.
 
-Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on.
+Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on. The other procedures named here (`commands/build.md` and the rest) are in the skill: `https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/<name>.md`, or `npx division-ds skill` to install them.
 
 Every finding prints `path:line [rule] what was found` and a line saying what to write instead.
 Do what that line says. Never silence a gate: no new EXEMPT entry, no `token-discipline: allow`

package/skills/division-ds/commands/review.md

@@ -2,11 +2,11 @@
 
 > Load when a screen is written and you are about to say it is done. The checklist to run over it. Generated by `npm run agent-docs`; the procedure lives in scripts/lib/agent-docs.mjs.
 
-Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on.
+Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on. The other procedures named here (`commands/build.md` and the rest) are in the skill: `https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/<name>.md`, or `npx division-ds skill` to install them.
 
 Go through every line. A line that does not hold is a change to make, not a note to leave.
 
-- [ ] **States.** Every region has its empty, loading, error, success and disabled or no-permission state, as planned in `commands/build.md`. An empty list says what is empty and offers the action that fills it.
+- [ ] **States.** Every region has its empty, loading, error, success and disabled or no-permission state, as planned before the code (the regions-and-states plan of `commands/build.md`). An empty list says what is empty and offers the action that fills it.
 - [ ] **Headings.** One `PageHeader`, so one `h1`. Section headings continue the outline: `h2` under the `h1`, `h3` inside an `h2`, no level skipped. `SectionHeading` is given the level.
 - [ ] **Tokens only.** No hex, `rgb()`, palette class or invented token name. `division-ds check` passes.
 - [ ] **Buttons.** Two or more side by side share a parent with a gap. One primary button per view. A busy button takes `loading`; a disabled one says why nearby. Icon-only actions are `IconButton` with a `label`.

package/skills/division-ds/topics/ai.md

@@ -4,4 +4,5 @@
 
 **Assistant copy.** A button names the action ("Summarize"), never "AI". Say "response", not
 "answer". No "please" or "!" in assistant labels. The interface says "Assistant"; only its own
-messages say "I".
+messages say "I". Response feedback: `ResponseFeedback` in `actions`.
+A value the assistant filled is `aiValue` on that `Input` or `Textarea` only; leaving it accepts it.

package/skills/division-ds/topics/forms.md

@@ -10,6 +10,9 @@ bare and name it through its own `label` prop ("Role for Ilse Varga"). `Switch`,
 renders `ErrorSummary` at the top and focuses it; `useFieldErrors` holds the state (signature in
 `public/docs/helpers.md`).
 
+A `RadioGroup` in a form sits in a `<fieldset>` whose `<legend>` names it (code on the Radio
+page). A date is `DatePicker` in a `FormField`; its value is 'YYYY-MM-DD'.
+
 **Buttons.** Two or more buttons side by side need a parent with a gap
 (`flex flex-wrap gap-3`); `DialogFooter` and `CardFooter` already are one. A `Button` is
 `type="button"` unless you say `type="submit"`. A busy button takes `loading`, not `disabled`.

package/skills/division-ds/topics/layout.md

@@ -8,7 +8,9 @@ The shell paints the page background (`surface.base`) and supplies the gutter; a
 own `max-w-*` and vertical spacing, and no page background. A form or an overlay is the
 exception: it paints `surface.base` on itself, so its field colours never depend on what is
 behind it. In a project that uses the components, your own root does this
-(step 4 of `install.md`).
+(step 4 of `install.md`). Toggle it with `setTheme()` from `src/lib/theme.ts`.
+
+**App navigation.** A few views: `Navbar` (`current: true` on the open one). Many: `Sidebar`.
 
 **Type.** Three families, as utilities: `font-display` (headings, figures), `font-body` (the
 default, set by the shell), `font-mono` (labels, code, tabular numbers). A page title is