@misoto22/folio 0.0.0 → 0.17.0

package/AGENTS.md

@@ -0,0 +1,88 @@
+# @misoto22/folio — for agents
+
+Pointers, not content. Everything below is generated from the source in this
+same tarball, so nothing here can describe a version that is not installed.
+
+## You have installed this package
+
+You are probably reading this because you searched `node_modules` for a filename
+you recognise. The three commands are what you came for:
+
+```bash
+npx @misoto22/folio docs Button        # one component, in full
+npx @misoto22/folio docs --installed   # this version, and every component in it
+npx @misoto22/folio init --agents-md   # install the skill into this project
+```
+
+`docs` resolves parts and types as well as components, so `docs CardBody`,
+`docs TH` and `docs ButtonVariant` all land on the right file. When an import
+fails, ask it about the identifier you tried.
+
+Read `skills/folio-design/SKILL.md` in this package before writing components
+against it. The names diverge from shadcn/ui in several places, and colour is
+never written as a raw class; the skill leads with both.
+
+`init` writes it to `.agents/skills/` — the path Codex, Cursor, Copilot, Gemini
+CLI, OpenCode, Cline, Zed and Warp share — and to `.claude/skills/` when the
+project already has one. For anything else, `npx skills add
+Misoto22/folio` finds this skill with no configuration.
+
+Some misuse fails silently, so the components say so in development:
+`FIELD_CONTROL_NOT_LABELLABLE` when a wrapper takes the label instead of the
+control, `BUTTON_ICON_ONLY_UNNAMED` when an icon-only button has no accessible
+name, `REQUIRED_NAME_BLANK` when a required name is an empty string. Each prints
+the field and an imperative fix, once per problem, and none reaches a production
+bundle.
+
+Nineteen codes in all. Eight on the primitives —
+`ARTICLE_HTML_AND_CHILDREN`, `BREADCRUMB_CRUMB_NOT_LINKED`,
+`BUTTON_ICON_ONLY_UNNAMED`, `DIALOG_TITLE_MISSING`,
+`FIELD_CONTROL_NOT_LABELLABLE`, `FIELD_CONTROL_NOT_WIRED`,
+`REQUIRED_NAME_BLANK`, `SEARCHABLE_MENU_LABEL_UNREADABLE`. Five on `Diagram`,
+which checks the spec it was handed because a figure that ignores an edge still
+renders beautifully — `DIAGRAM_ACCENT_ON_CONTAINER`, `DIAGRAM_DIRECTION_ON_LEAF`,
+`DIAGRAM_DUPLICATE_ID`, `DIAGRAM_EDGE_NOT_ADJACENT`,
+`DIAGRAM_EDGE_UNKNOWN_NODE`. And six on the figures in
+`@misoto22/folio/diagrams` — `DIAGRAM_CELL_COLLISION`, `DIAGRAM_EDGE_DANGLING`,
+`DIAGRAM_LANE_UNKNOWN`, `DIAGRAM_REF_UNKNOWN`, `DIAGRAM_SPEC_MUTATED`,
+`DIAGRAM_STAGE_OUT_OF_RANGE`. `skills/folio-design/rules/a11y.md` tables what
+each one fires on; `src/lib/warn.ts` is where they are printed.
+
+Four entry points, and importing from the wrong one throws rather than renders
+blank. Each `docs` file names its own on the `Import:` line.
+
+| Specifier | What ships from it |
+| --- | --- |
+| `@misoto22/folio` | The primitives |
+| `@misoto22/folio/charts` | Charts — needs the `recharts` and `motion` peers |
+| `@misoto22/folio/diagrams` | Figures with routed edges |
+| `@misoto22/folio/website` | Website compositions, with data and routes supplied by the host — styled by `website.css`, which `styles.css` does not include |
+
+## You are working ON this package, in its repository
+
+The repository root `AGENTS.md` still applies in full — this file is additive,
+not a replacement, and the Harness rules there (`HAR-*`, `DESIGN-*`) govern this
+directory as much as any other. Read it first.
+
+What is specific to here:
+
+- **`dist/` is generated.** `dist/agent/**` included — it is written by
+  `scripts/emit-agent.mjs` at build time. Edit the source, then rebuild.
+- **`agent/catalog.mjs` is the one hand-written description** of what each
+  component IS: its group, summary, when to reach for it, accessibility
+  promises and keyboard contract. Everything mechanical is parsed out of
+  `src/**` by `scripts/extract-props.mjs`. `src/__tests__/catalog.test.ts`
+  fails when the two disagree.
+- **The skill is tested.** `src/__tests__/skill.test.ts` asserts every claim in
+  `skills/` against the extracted source, in both directions — an identifier the
+  rules tell an agent to write must exist, and one they say to avoid must not.
+  Renaming an export without updating the rules fails the build, on purpose.
+- **Gates:** `pnpm lint && pnpm typecheck && pnpm test && pnpm build`, from the
+  repository root.
+
+## On the web
+
+`https://ui.misoto22.com` — and `/llms.txt`, `/llms-full.txt`, and
+`/components/<slug>/llms.txt` for the same content without the CSS. Prefer the
+CLI above when the package is installed: it is version-locked and needs no
+network.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,210 @@
 # @misoto22/folio
 
-Placeholder reserving the name for the Folio design system (formerly `@misoto22/design`).
-Install `@misoto22/folio@^0.16.0` once it is released.
+A monochrome design system for software, writing and photography: portable CSS
+tokens and accessible React 19 primitives. Paper ground, near-black mark, and
+status is the only chroma in the file.
+
+Components ship compiled — you import them, you do not copy them into your
+project.
+
+**[ui.misoto22.com](https://ui.misoto22.com)** · [Changelog](./CHANGELOG.md)
+
+## Install
+
+```bash
+npm install @misoto22/folio
+```
+
+```tsx
+import { Button, Field, Input } from '@misoto22/folio'
+import '@misoto22/folio/styles.css'
+```
+
+`styles.css` is the whole compiled sheet — tokens, roles, themes, motion and
+the vendored faces. An app that compiles its own Tailwind can take the portable
+layers instead:
+
+```tsx
+import '@misoto22/folio/tokens.css'    // primitives, plus data-mode and data-density
+import '@misoto22/folio/semantic.css'  // roles
+import '@misoto22/folio/themes.css'    // the other six theming axes
+import '@misoto22/folio/keyframes.css' // motion
+```
+
+All four, or the theming table below is a table of attributes that do nothing.
+`data-mode` and `data-density` are declared in `tokens.css`; every other axis
+lives only in `themes.css`, and an app that skips it writes `data-radius="sharp"`
+and gets no error, no warning, and no corner. Two more layers are opt-in rather
+than missing: `@misoto22/folio/fonts.css` carries the vendored faces, and
+`@misoto22/folio/article.css` styles long-form prose.
+
+Diagrams ship from their own specifier, so a page that renders a `Badge` does
+not pay for a routing engine:
+
+```tsx
+import { ArchitectureFigure, DiagramCanvas } from '@misoto22/folio/diagrams'
+import { SiteShell, Portfolio, CollectionIntro, SearchPalette } from '@misoto22/folio/website'
+```
+
+Five server-rendered figures — architecture, workflow, sequence, data-flow and
+lifecycle — plus the chrome to explore one. They read the JSON schemas
+published by [archify](https://github.com/tt-a1i/archify), so a specification
+authored for that tool renders here with no translation step.
+
+## Theming
+
+Eight independent axes, each an attribute, each working on **any** element
+rather than only on the root. An unset axis is the default.
+
+| Attribute | Values |
+| --- | --- |
+| `data-mode` | `light` `dark` |
+| `data-surface` | `warm` `cool` `glass` |
+| `data-radius` | `sharp` `round` |
+| `data-rules` | `quiet` `firm` |
+| `data-type` | `grotesk` `bookish` |
+| `data-motion` | `still` `snappy` |
+| `data-density` | `compact` |
+| `data-chart-palette` | `chroma` |
+
+```tsx
+<section data-surface="warm" data-radius="sharp">…</section>
+```
+
+No component reads any of them, and none of them introduces a token. To
+re-accent the system, re-point one custom property:
+
+```css
+:root { --accent: var(--ok); }
+```
+
+## For agents
+
+This package is documented for the reader that installed it, not only for the
+one that can open a browser — and the two need different things. Everything
+below is generated from the source in this same tarball, so it describes the
+version you actually have rather than whatever the website shipped last.
+
+**One component, in full** — every prop with its type and default, the exported
+unions, the keyboard contract, the accessibility promises, the examples:
+
+```bash
+npx @misoto22/folio docs Button
+```
+
+The median component is about 500 tokens. It resolves parts and types too, so
+`docs CardBody`, `docs TH` and `docs ButtonVariant` all land on the right file —
+useful when an import just failed.
+
+**What is installed here**, as a few hundred tokens rather than fifty prop
+tables:
+
+```bash
+npx @misoto22/folio docs --installed
+```
+
+**Install the skill** into your project, so a coding agent picks up the
+conventions without being told each time:
+
+```bash
+npx @misoto22/folio init --agents-md
+```
+
+That writes the skill to `.agents/skills/` — the path Codex, Cursor, GitHub
+Copilot, Gemini CLI, OpenCode, Cline, Zed and Warp all read — and to
+`.claude/skills/` as well when the project already has a `.claude/`. Use
+`--agent agents` or `--agent claude` to pick one. For any other agent,
+[`skills`](https://github.com/vercel-labs/skills) covers around seventy of them
+and finds this one without any configuration:
+
+```bash
+npx skills add Misoto22/folio
+```
+
+The skill is progressive: its name and description are about 110 tokens and are
+all that sits in a session until something actually touches this package. The
+body is around 2,200, and the five rule files load one at a time, only when the
+work reaches them.
+
+An agent that explores `node_modules` by filename rather than by command finds
+`AGENTS.md`, `CLAUDE.md` and `llms.txt` at the package root. They are pointers
+to the above and nothing else, so they cannot go stale between releases.
+
+The names diverge from shadcn/ui in a handful of places that a model writing
+from habit gets wrong — `CardBody` not `CardContent`, `THead`/`TBody`/`TR`/`TH`/`TD`
+not `TableHeader`/…, and `title` as a prop on `DialogContent` rather than a
+`DialogTitle` child. The skill leads with that table, and
+`src/__tests__/skill.test.ts` fails the build if any of it stops being true.
+
+On the web, the same content is at
+[`/llms.txt`](https://ui.misoto22.com/llms.txt) (index),
+[`/llms-full.txt`](https://ui.misoto22.com/llms-full.txt) (everything inline),
+and `/components/<slug>/llms.txt` (one component).
+
+### It tells you when you get it wrong
+
+Some ways of misusing a component fail silently — a `Field` whose child is a
+wrapper wires the label onto the box, an icon-only `Button` with no accessible
+name renders perfectly and is invisible to a screen reader. Development warns on
+those where it happens, with a stable code, the offending field and an
+imperative fix:
+
+```
+[@misoto22/folio] FIELD_CONTROL_NOT_LABELLABLE
+  Field's child is a <div>, which cannot take a label — so the id,
+  aria-describedby, aria-required and aria-invalid were applied to it rather
+  than to a control.
+  field: children
+  fix:   Put the control itself directly inside Field, with no wrapper. For a
+         row of controls, give each its own Field and lay them out around it.
+  docs:  npx @misoto22/folio docs Field
+```
+
+Every call site is behind `process.env.NODE_ENV`, so none of it reaches a
+production bundle.
+
+## Accessibility
+
+Every component is tested against `axe-core` best-practice rules, keyboard
+contracts are asserted key by key, and a prop that is required for
+accessibility is required in the type — `Table.caption`, `Progress.label`,
+`Avatar.alt`, `FloatingIconButton.label`. If it can be forgotten, it will be.
+
+Logical properties throughout, so the system is RTL-correct; motion is gated
+behind `prefers-reduced-motion`.
+
+## Requirements
+
+React 19, Node 24+. ESM only.
+
+## Licence
+
+MIT © Henry Chen
+
+## Website compositions
+
+Import page composition families from `@misoto22/folio/website`. They include
+navigation, portfolios, content collections, reading layouts, media browsing,
+contact forms, listening views, metrics, search and conversations. Pass localized
+labels, router link elements and plain view data; keep backend requests, routing
+and authentication in the application.
+
+`styles.css` does not include these compositions, so an application that renders
+only the primitives receives none of their rules. Import `website.css` beside it —
+or beside the portable token, semantic, theme and keyframe layers in an
+application that already builds Tailwind, scanning the package's `dist`
+directory. A host whose whole page is a website also imports `website-base.css`,
+which sets the body type, heading and paragraph margins and a site-wide focus
+ring; an application that embeds a composition in its own chrome leaves it out.
+
+```tsx
+import '@misoto22/folio/styles.css'
+import '@misoto22/folio/website.css'
+import '@misoto22/folio/website-base.css' // only when the whole page is a website
+```
+
+`npx @misoto22/folio docs SiteShell` and `docs SearchPalette` explain the contracts.
+
+For metadata and build scripts, `import { BRAND } from '@misoto22/folio/brand'`
+loads the token mirror without loading React components. This data-only entry
+also supports Node's native ESM loading from CommonJS on the supported Node versions.

package/bin/folio-design.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * The package's own documentation, for the reader that installed it.
+ *
+ * A website is the wrong source for an agent writing against a pinned version:
+ * it documents whatever shipped last, the agent is holding whatever is in
+ * `node_modules`, and neither side can see the disagreement. Everything printed
+ * here is generated at build time from the source in the same tarball, so the
+ * answer is always about the version actually installed.
+ *
+ * It is also the cheap half of the deal. `docs --installed` is a few hundred
+ * tokens and says what exists; `docs <Component>` is under a thousand and says
+ * everything about one of them. The alternative an agent reaches for otherwise
+ * is the whole of `llms-full.txt`, which is fifty times that and mostly about
+ * components it is not using.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { migrateLegacySkills, replaceLegacyAgentsBlock } from './migrate-legacy.mjs'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const AGENT = join(ROOT, 'dist', 'agent')
+const SKILL_NAME = 'folio-design'
+const SKILL = join(ROOT, 'skills', SKILL_NAME)
+
+const { version } = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+
+const USAGE = `@misoto22/folio ${version}
+
+  folio-design docs <Component>    One component, in full — props, types,
+                                   keyboard, accessibility, examples.
+  folio-design docs --list         Every component, one line each.
+  folio-design docs --installed    This package's version and what it ships.
+                    [--json]
+  folio-design init                Install the agent skill into this project.
+                   [--agents-md]   Also point AGENTS.md at it.
+                   [--agent <id>]  Write only to one agent's directory:
+                                   "agents" (the shared path) or "claude".
+
+Docs on the web: https://ui.misoto22.com`
+
+function fail(message) {
+  process.stderr.write(`${message}\n`)
+  process.exit(1)
+}
+
+/** The emitted docs are a build artifact; a source checkout may not have them. */
+function requireBuilt() {
+  if (!existsSync(AGENT)) {
+    fail(
+      'No generated docs found. This package ships them in dist/agent/;\n' +
+        'in a source checkout, run `pnpm build:agent` first.',
+    )
+  }
+}
+
+function componentNames() {
+  return readdirSync(AGENT)
+    .filter((file) => file.endsWith('.md') && file !== 'index.md')
+    .map((file) => file.replace(/\.md$/, ''))
+    .sort()
+}
+
+function catalog() {
+  return JSON.parse(readFileSync(join(AGENT, 'catalog.json'), 'utf8'))
+}
+
+/**
+ * What a skill injects at the top of a session: the version in this project and
+ * the names it can ask about. Deliberately names-only — the point is that the
+ * agent then fetches the one component it needs, rather than being handed all
+ * fifty-two prop tables it does not.
+ */
+function installed(asJson) {
+  requireBuilt()
+  const { groups, components } = catalog()
+  if (asJson) {
+    const byGroup = Object.fromEntries(
+      groups
+        .map((group) => [group, components.filter((c) => c.group === group).map((c) => c.name)])
+        .filter(([, names]) => names.length > 0),
+    )
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          package: '@misoto22/folio',
+          version,
+          components: byGroup,
+          styles: [
+            '@misoto22/folio/styles.css',
+            '@misoto22/folio/tokens.css',
+            '@misoto22/folio/semantic.css',
+            '@misoto22/folio/keyframes.css',
+          ],
+          detail: 'npx @misoto22/folio docs <Component>',
+        },
+        null,
+        2,
+      )}\n`,
+    )
+    return
+  }
+  const lines = [`@misoto22/folio ${version} — ${components.length} components`, '']
+  for (const group of groups) {
+    const names = components.filter((c) => c.group === group).map((c) => c.name)
+    if (names.length > 0) lines.push(`${group}: ${names.join(', ')}`)
+  }
+  lines.push('', 'One in full: npx @misoto22/folio docs <Component>')
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
+
+function docs(args) {
+  if (args.includes('--installed')) return installed(args.includes('--json'))
+  requireBuilt()
+  if (args.includes('--list')) {
+    process.stdout.write(readFileSync(join(AGENT, 'index.md'), 'utf8'))
+    return
+  }
+
+  const name = args.find((arg) => !arg.startsWith('-'))
+  if (!name) fail(`Which component? Try one of:\n\n  ${componentNames().join(', ')}`)
+
+  // What the caller holds is usually the identifier it just failed to import —
+  // a part (`CardBody`, `TH`) or a type (`ButtonVariant`) rather than the
+  // component that owns it. Resolve those rather than making it guess again.
+  const owner = catalog().exports?.[name]
+  const file = join(AGENT, `${owner ?? name}.md`)
+  if (existsSync(file)) {
+    if (owner && owner !== name) {
+      process.stderr.write(`\`${name}\` is part of ${owner}.\n`)
+    }
+    process.stdout.write(readFileSync(file, 'utf8'))
+    return
+  }
+
+  // A miss is usually a near miss — a habit from another library, or a part
+  // name rather than the component that owns it. Say what exists instead.
+  const wanted = name.toLowerCase()
+  const near = componentNames().filter(
+    (candidate) =>
+      candidate.toLowerCase().startsWith(wanted.slice(0, 3)) ||
+      wanted.startsWith(candidate.toLowerCase()),
+  )
+  fail(
+    near.length > 0
+      ? `No component named "${name}". Did you mean: ${near.join(', ')}?`
+      : `No component named "${name}". Run \`folio-design docs --list\` for all ${componentNames().length}.`,
+  )
+}
+
+const AGENTS_BLOCK = `
+## @misoto22/folio
+
+UI comes from \`@misoto22/folio\`. Read \`SKILL.md\` in the installed skill
+directory before writing components against it — the names diverge from
+shadcn/ui in several places, and colour is never written as a raw class.
+
+- One component in full: \`npx @misoto22/folio docs <Component>\`
+- Everything it ships: \`npx @misoto22/folio docs --installed\`
+`
+
+/**
+ * Where a skill goes, for the agents worth covering directly.
+ *
+ * `.agents/skills/` is the shared path — Codex, Cursor, GitHub Copilot, Gemini
+ * CLI, OpenCode, Cline, Zed, Warp, Amp and Replit all read it — and Claude Code
+ * is the one common agent with its own. Writing only to `.claude/` handed every
+ * other agent nothing, which was the bug.
+ *
+ * Deliberately two entries rather than the whole ecosystem. `npx skills` tracks
+ * around seventy directories and is one command away; a copy of that table kept
+ * here would be stale within a release, and this package's own rules are about
+ * not keeping copies of things that move.
+ */
+const AGENT_DIRS = {
+  agents: '.agents/skills',
+  claude: '.claude/skills',
+}
+
+/**
+ * Which directories to write, given the flags and what the project already has.
+ *
+ * The shared path is unconditional — it is the one an unknown agent is most
+ * likely to read. Claude's is added when the project already has a `.claude/`,
+ * so a project that does not use it does not grow a directory it will never
+ * open.
+ */
+function initTargets(args) {
+  const wanted = args[args.indexOf('--agent') + 1]
+  if (args.includes('--agent')) {
+    if (!wanted || !AGENT_DIRS[wanted]) {
+      fail(
+        `Unknown --agent "${wanted ?? ''}". Known: ${Object.keys(AGENT_DIRS).join(', ')}.\n` +
+          'For any other agent, `npx skills add Misoto22/folio` covers ~70 of them.',
+      )
+    }
+    return [AGENT_DIRS[wanted]]
+  }
+
+  const targets = [AGENT_DIRS.agents]
+  if (existsSync(join(process.cwd(), '.claude'))) targets.push(AGENT_DIRS.claude)
+  return targets
+}
+
+function init(args) {
+  if (!existsSync(SKILL)) fail('This build has no skills/ directory.')
+
+  const cwd = process.cwd()
+  const requested = initTargets(args)
+  // A directory that held the pre-rename skill is written whatever the flags
+  // say: the migration moved the old copy to the new name, and it still holds
+  // the old content until it is refreshed here.
+  const migrated = migrateLegacySkills(cwd, Object.values(AGENT_DIRS), SKILL_NAME)
+  const written = migrated.map(({ from, to }) => `  migrated  ${resolve(from)} -> ${resolve(to)}`)
+  for (const dir of new Set([...requested, ...migrated.map((entry) => entry.dir)])) {
+    const target = join(cwd, dir, SKILL_NAME)
+    const existed = existsSync(target)
+    mkdirSync(dirname(target), { recursive: true })
+    cpSync(SKILL, target, { recursive: true })
+    written.push(`  ${existed ? 'updated' : 'installed'}  ${resolve(target)}`)
+  }
+  process.stdout.write(`${written.join('\n')}\n`)
+  pointAgentsMd(cwd, args)
+}
+
+/**
+ * Append the AGENTS.md section when asked, and replace the pre-rename one
+ * whether asked or not — it names a bin this package no longer ships, so
+ * leaving it is leaving an instruction that fails.
+ */
+function pointAgentsMd(cwd, args) {
+  const agentsFile = join(cwd, 'AGENTS.md')
+  const existing = existsSync(agentsFile) ? readFileSync(agentsFile, 'utf8') : null
+  if (existing !== null) {
+    const rewritten = replaceLegacyAgentsBlock(existing, AGENTS_BLOCK)
+    if (rewritten !== existing) {
+      writeFileSync(agentsFile, rewritten)
+      process.stdout.write(`Replaced the pre-rename section in ${resolve(agentsFile)}\n`)
+      return
+    }
+  }
+
+  if (!args.includes('--agents-md')) {
+    process.stdout.write('Pass --agents-md to also point AGENTS.md at it.\n')
+    return
+  }
+
+  const current = existing ?? '# AGENTS.md\n'
+  if (current.includes('@misoto22/folio')) {
+    process.stdout.write('AGENTS.md already mentions the package; left alone.\n')
+    return
+  }
+  writeFileSync(agentsFile, `${current.trimEnd()}\n${AGENTS_BLOCK}`)
+  process.stdout.write(`Appended a section to ${resolve(agentsFile)}\n`)
+}
+
+const [command, ...args] = process.argv.slice(2)
+switch (command) {
+  case 'docs':
+    docs(args)
+    break
+  case 'init':
+    init(args)
+    break
+  case undefined:
+  case '--help':
+  case '-h':
+    process.stdout.write(`${USAGE}\n`)
+    break
+  case '--version':
+  case '-v':
+    process.stdout.write(`${version}\n`)
+    break
+  default:
+    fail(`Unknown command "${command}".\n\n${USAGE}`)
+}

package/bin/migrate-legacy.mjs

@@ -0,0 +1,81 @@
+/**
+ * What `init` cleans up from before the Folio rename.
+ *
+ * Up to 0.15.0 this package was `@misoto22/design`: `init` installed its skill
+ * as `misoto22-design`, and `--agents-md` appended a section naming that bin. A
+ * project upgraded to `@misoto22/folio` would otherwise keep the old copy next
+ * to the new one — two skills describing one package, the older one telling an
+ * agent to run a command the package no longer ships.
+ *
+ * The old names below are literal ON PURPOSE. The rename codemod skips this file
+ * and its guard test (`src/__tests__/bin-init.test.ts`): rewritten to the new
+ * names, the migration would look for the new skill and migrate nothing.
+ */
+import { existsSync, readFileSync, renameSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The skill's directory and frontmatter name before the rename. */
+export const LEGACY_SKILL_NAME = 'misoto22-design'
+
+/** The section `init --agents-md` appended to AGENTS.md before the rename, verbatim. */
+export const LEGACY_AGENTS_BLOCK = `
+## @misoto22/design
+
+UI comes from \`@misoto22/design\`. Read \`SKILL.md\` in the installed skill
+directory before writing components against it — the names diverge from
+shadcn/ui in several places, and colour is never written as a raw class.
+
+- One component in full: \`npx misoto22-design docs <Component>\`
+- Everything it ships: \`npx misoto22-design docs --installed\`
+`
+
+const LEGACY_NAME_LINE = new RegExp(`^name:\\s*['"]?${LEGACY_SKILL_NAME}['"]?\\s*$`, 'm')
+
+/**
+ * Whether `dir` holds the old skill, judged by the name in its frontmatter
+ * rather than by the directory name — a directory someone else called
+ * `misoto22-design` is not ours to move.
+ */
+export function isLegacySkill(dir) {
+  const file = join(dir, 'SKILL.md')
+  if (!existsSync(file)) return false
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(file, 'utf8'))
+  return Boolean(frontmatter && LEGACY_NAME_LINE.test(frontmatter[1]))
+}
+
+/**
+ * Move the old skill in each agent directory to `skillName`.
+ *
+ * Renamed rather than deleted when nothing sits at the new path, so anything a
+ * project added beside the skill survives. When the new skill is already there
+ * the old copy is only a duplicate, and is removed.
+ *
+ * @param {string} cwd the project root
+ * @param {string[]} agentDirs skill directories relative to it, e.g. `.claude/skills`
+ * @param {string} skillName the skill's current directory name
+ * @returns {{ dir: string, from: string, to: string }[]} one entry per directory migrated
+ */
+export function migrateLegacySkills(cwd, agentDirs, skillName) {
+  const migrated = []
+  for (const dir of agentDirs) {
+    const from = join(cwd, dir, LEGACY_SKILL_NAME)
+    if (!isLegacySkill(from)) continue
+    const to = join(cwd, dir, skillName)
+    if (existsSync(to)) rmSync(from, { recursive: true, force: true })
+    else renameSync(from, to)
+    migrated.push({ dir, from, to })
+  }
+  return migrated
+}
+
+/**
+ * `text` with the old AGENTS.md section replaced by `block`.
+ *
+ * Only the exact section `init` wrote is replaced: a hand-edited one is the
+ * project's own prose, and is returned unchanged along with everything else.
+ */
+export function replaceLegacyAgentsBlock(text, block) {
+  const legacy = LEGACY_AGENTS_BLOCK.trim()
+  if (!text.includes(legacy)) return text
+  return text.replace(legacy, () => block.trim())
+}