@erclx/canon 4.0.0

package/docs/target-projects.md

@@ -0,0 +1,258 @@
+---
+title: Target projects
+description: Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
+category: Agent surface
+---
+
+# Target projects
+
+How a project outside this repo consumes the toolkit across its lifecycle. Three phases: scaffold once, add a domain later when a new need appears, and sync when the upstream toolkit moves.
+
+This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents/index.md). For per-domain mechanics, see each `.claude/context/<domain>.md`.
+
+## Getting the skills
+
+The skills reach a session through a marketplace install, once per machine. Every session on that machine carries them afterward, and the installed copy stays at the version it was installed at. Claude Code ships auto-update off for third-party marketplaces, so neither a push nor a release reaches that copy until someone refreshes it with `claude plugin marketplace update canon` followed by `claude plugin update canon@canon`, or turns auto-update on once under `/plugin`. The `canon` CLI moves on its own schedule through the registry, so a machine can hold current skills against a stale CLI or the reverse.
+
+```bash
+claude plugin marketplace add https://github.com/erclx/canon
+claude plugin install canon@canon
+```
+
+The URL form clones over HTTPS. The `erclx/canon` shorthand resolves to SSH and fails on a machine with no key configured.
+
+A machine that installed the plugin under its previous name re-registers by hand, once. The marketplace and the plugin both moved, so the old `enabledPlugins` entry and the old marketplace key name things that no longer resolve, and the plugin stops loading without reporting anything. `canon migrate rename` does not reach this: it takes a `--root` and rewrites inside one project, where the plugin registration is machine-level state outside every project.
+
+Both stale keys come out explicitly, since installing under the new name writes a new entry and leaves the old one sitting there. Uninstall before removing the marketplace, so the plugin is cleared while the marketplace it came from still resolves.
+
+```bash
+claude plugin uninstall aitk@aitk
+claude plugin marketplace remove aitk
+claude plugin marketplace add https://github.com/erclx/canon
+claude plugin install canon@canon
+```
+
+The `canon` CLI is separate. Twenty skills invoke it in a command position, and a marketplace install does not put it on `PATH`, so it installs from the registry as its own step.
+
+```bash
+bun install --global @erclx/canon
+```
+
+The package ships the catalogs the CLI reads, not only `src/`, so `canon init` resolves governance, tooling, and the seeds from wherever the package landed, and `canon standards <name>` reads the corpus from there too.
+
+Pointing Claude Code at a checkout stays the development path, where a local skill edit overrides the installed copy for that session.
+
+```bash
+claude --plugin-dir <toolkit>/claude
+```
+
+## Scaffold
+
+Two steps, in order:
+
+1. Run the framework's own scaffold if the project needs one, such as `bun init`, `npm create vite`, or `npm create astro`. The toolkit does not wrap framework scaffolding.
+2. Invoke `canon:setup-init` in Claude Code. The skill detects the stack, resolves flags, previews the full chain, and runs it end-to-end.
+
+The chain is:
+
+- `canon init` installs base tooling, Claude seeds, and governance rules into `.claude/rules/` in the same pass
+- `canon tooling sync <stack> --write` adds stack-specific deps, scripts, and gitignore entries
+- The agent reads `canon tooling reference <stack>` (plus parents) as its audit context, follows it to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations: .claude/context/development.md -->
+- `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
+
+The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `canon:canon-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `canon claude init` for the seed docs and then `canon:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
+
+Keep the `## Scripts` table in `.claude/context/development.md` current as scripts are added. Base tooling seeds that entry with the commands it installs, and each stack reference extends the table. `project-commands` reads it to start the app or run a check on request, so a command missing from the table cannot be run that way. A project whose entry outgrew one file and split into `.claude/context/development/` keeps the table in `overview.md`, which is where the skill looks next. <!-- audit-ignore-citations: .claude/context/development.md -->
+
+### From scaffold to first feature
+
+Scaffold installs tooling and seeds. It does not fill the planning docs or the design system. Complete those before the first feature session:
+
+1. Fill `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
+2. For a UI project, invoke `canon:claude-design-extract` to draft `.claude/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
+3. Optionally invoke `canon:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
+4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
+
+A machine without a renderer still gets the diagrams and is told which check was skipped.
+
+Each diagram entry records the commit and date it was last verified against, and nothing maintains that record for you. The folder is redrawn on demand rather than swept on every ship, so `verified` carries the whole signal: an entry whose date sits far behind your branch is due a read, and no pass will name which one. Run `canon:claude-diagram` again when the code a kind is drawn from moves.
+
+`.claude/ARCHITECTURE.md` carries the same mechanism on the same ship. `canon:claude-docs` anchors a decision it amends to the paths that decision cites, and reports an anchored decision whose cited path the branch touched.
+
+### Stack decision
+
+The default path is `base`. `canon init` on `base` installs base tooling configs, Claude seeds, and governance core rules, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
+
+Escalate only for real web apps. The `setup-init` skill reads `package.json` and root configs, then picks the matching tooling stack (`vite-react` today) and the matching governance stack (`react`, `astro`, `node`).
+
+`node-server` is named rather than detected. It carries the server-side security and persistence rules for a project writing request handlers or a persistence layer in TypeScript, and the detect step matches a runtime or a framework against stack names, so nothing there marks a project as a backend. Pass it deliberately with `canon init --stack node-server` or `canon gov install node-server <target>`.
+
+Markdown-heavy projects, CLI tools, docs sites, research notebooks, and scripting repos stay on `base`. Escalation is a ceiling move, not a default.
+
+A project the toolkit ships no stack for lands on `base` the same way, and the skill marks that resolution as a fallback in its preview rather than reporting it as a match. Configs, seeds, and gitignore entries land either way, and the JavaScript development dependencies, scripts, and hook activation land only where a `package.json` exists to carry them. A project outside that ecosystem declines at the preview and takes `canon:setup-gov` for the governance layer alone, which is language-neutral.
+
+Run `canon tooling list --json` and `canon gov list --json` to see the current catalogs. Never hardcode stack names.
+
+### Core domains and skips
+
+`canon init` installs base tooling, Claude workflow, and governance, and scaffolds `.claude/wiki/`. Governance defaults to the `base` stack, so a bare init carries the rules that route a project. Pass `--stack <name>` to install a framework stack instead.
+
+No standard is written into the project. Each governance rule's authority line names `canon standards <name>`, which answers from the corpus inside the CLI's own package, and every toolkit skill names the copy in its own plugin root. `canon markdown audit` needs no standard at all, its ban sets and checkpoints shipping with the package as data.
+
+No snippet is written into the project either. `claude/snippets` in the plugin cache symlinks to the toolkit's own `snippets/`, so a session reaches one at its `@` reference with no install step, the same live resolution `claude/standards` gives a rule's authority line.
+
+`governance` and `wiki` are skippable:
+
+- `--skip governance`: leave `.claude/rules/` empty, so no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `canon gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
+- `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
+
+The plugin corpus carries runtime behavior rather than reference prose alone, because the pre-publish scan and the branch-slug transform each have a standard of their own, `publish.md` and `slug.md`, cited by the skills that run them.
+
+## Add a domain later
+
+When a new need appears after scaffold, install the one domain without re-running `canon init`.
+
+- Governance rule for a newly adopted library: invoke `canon:setup-gov`, or run `canon gov install <stack> --add <rule> <path>`
+- Project-specific rule the toolkit does not ship: invoke `canon:create-rule`. It scaffolds a rule into `.claude/rules/` with a non-colliding number, and `canon gov sync` leaves it untouched.
+- Index.md system for a markdown-heavy folder that emerged: invoke `canon:setup-indexes`
+
+Standards and snippets are not on that list, and there is nothing to add for either. Neither installs into a project, by default or by flag, so a session reads a standard with `canon standards <name>` and a snippet through its `@` reference off the live plugin symlink, both resolving against the toolkit rather than a project copy. A project holding a `.claude/standards/` or `.claude/snippets/` folder from an older toolkit is carrying a stale artifact nothing reads, and deleting it is safe.
+
+Per-domain mechanics live in the corresponding `docs/<domain>.md`. The skill body in `claude/skills/<skill>/SKILL.md` covers detection and preview.
+
+## Sync upstream drift
+
+When the toolkit updates, target projects pull changes per domain. There is one catch-all and several targeted entry points.
+
+### Check first
+
+`canon sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.
+
+#### The binary first
+
+The report opens by naming the binary running it. The installed version reads against the newest published one, and a version behind that points you at `canon upgrade`, since every section under it is a reading taken by whichever toolkit you happen to have. An unreachable registry reports unknown with its reason rather than failing, so `--exit-code` still gates on the drift the check measured locally and an offline machine stays green.
+
+#### Then the causes
+
+A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `canon:claude-seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is a relocation the report names but no command runs.
+
+That attribution comes from `.claude/canon/config.json`, a stamp every install and sync writes. A target stamped before that path shipped is read from the retired `.claude/canon.json` instead, reported rather than migrated. Governance records a hash per installed file, plus the stack `canon gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
+
+Each domain holds its own toolkit commit, so syncing governance today does not move the revision tooling measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
+
+A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
+
+Further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `canon:claude-seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.claude/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated`, and no command moves it either. The project moves the content itself.
+
+`unmigrated` currently names no domain, since standards and snippets are the two the toolkit ever installed at the project root and both closed their install channel. A target still holding a root `standards/` or `snippets/` folder from an older toolkit is carrying its own authoring surface now, not an unfinished install, and nothing proposes moving either.
+
+#### Rules you never received
+
+A sync refreshes the files you already hold and adds none, so your rule set is frozen at the date you installed governance while every file in it reports as current. `newRules` names a rule you could receive that your tree does not hold, which is the one section that reads your absence rather than your contents. `canon gov sync` reports the same rules per file, marked `missing`, so you see them either way you check.
+
+Take a clean section as reporting rather than as delivering. Nothing here installs, and it counts toward nothing, so pick the rules up with `canon gov install <stack>` or take one with `--add <rule>`. That separation is deliberate: adopting a rule changes what your project is governed by, which is a choice a sync has no business making for you.
+
+Since `canon gov install` records the stack you gave it, the list is read by comparing that stack's current rules against what you hold right now, with no date involved at all. That is what lets it name a rule the toolkit shipped before you last synced: nothing here depends on when you installed. A target stamped before this recording shipped falls back to the older read below.
+
+The fallback filters to what your stack can receive, read off the rule folders you already carry plus the folders the base stack takes whole. A rule under `lang/` or `ui/` belongs to some stacks and not others, so an unfiltered list would name rules you can never install. A target with neither a recorded stack nor a governance anchor reports nothing at all, since there is no date to measure against either.
+
+In the fallback, an empty section is not proof either way when the toolkit running the check is not a full git clone. The read needs history to reach your anchor, and an install from the registry ships none, so the section goes quiet rather than saying it could not measure. Run the check from a clone before reading a clean result as a complete one. The stack-based read above is untouched by this, since it consults no history.
+
+This also closes the case where a rule arrives citing a sibling you do not have. A sync refreshing a rule can land a version pointing at a file it never installs, and the section names the missing sibling rather than the broken citation, which is enough to act on.
+
+#### What the toolkit stopped shipping
+
+The last cause runs backwards. Every one above starts from what the toolkit ships and asks whether the target matches, so a folder the toolkit dropped appears in none of them. `reverse` walks the target instead and reports a folder sitting at a top-level path the toolkit once shipped and has since deleted.
+
+Each entry carries a verdict, since a dropped folder and one the project wrote are the same bytes at the same path.
+
+- `dropped` names the commit that published the content
+- `unattributed` means the toolkit shipped that path and the content matches no version it published
+- `project` means the folder only shares a retired name
+
+Nothing acts on any of them, and the verdict is what makes the list safe to read.
+
+The same field names a proposal-only skill with a live case here under `migrations`, which is how `canon:migration-claude-md` and `canon:migration-context` become reachable. Each entry carries the measurement behind the proposal rather than the proposal alone.
+
+Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code, and neither do superseded artifacts, seed drift, tooling, or anything the reverse walk reports, since each names content the project is expected to edit or place itself. An unmigrated domain does count, because running the relocation closes it.
+
+Tooling reports under a section of its own, and `measured` there says whether the target ever recorded a chain. One that never ran a tooling sync reports unmeasured rather than clean, which is what separates tooling nobody has looked at from tooling that is current. A workspace root records nothing either way, since each package resolves its own chain.
+
+Reconcile the configs with `canon tooling sync <stack> <path> --check` to read which files differ, then re-run it with `--write` to apply them. The drift report counts categories and the sync names paths, which is the difference worth knowing before a golden config the project edited is replaced.
+
+### Catch-all
+
+`canon sync <path>` runs every installed domain's sync in sequence. Safe to run on a cadence.
+
+It never touches user-owned seed files. Governance rules in `.claude/rules/` and tooling configs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
+
+Standards take no part in that run. Nothing installed them, so there is no copy to reconcile and no `canon standards sync` to reach for.
+
+### Targeted
+
+- Claude seed docs such as `CLAUDE.md` and `.claude/REQUIREMENTS.md`: invoke `canon:claude-seed-sync`. The skill splits each file into a preamble (between the H1 and the first H2) plus one part per `##` section, then diffs part by part and proposes per-part edits. User customizations are preserved.
+- Governance rules already installed: `canon gov sync <path>` diffs and applies, and never adds new rules. A rule your recorded stack lists reports as `missing` instead.
+- Tooling configs and seeds: `canon tooling <stack> <path>` overwrites golden configs and merges seeds
+- Reference docs for a stack: `canon tooling reference <stack>` reads and never writes, so there is nothing to sync
+- Index regeneration after markdown edits: `canon indexes regen`
+
+Use a targeted entry point when only one surface moved upstream. Use the catch-all when the toolkit lands a bundled release.
+
+## Verify a sync
+
+Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../.claude/context/sandbox/index.md) for the scenario catalog and routing patterns.
+
+## Scenarios
+
+### Markdown-heavy project
+
+```bash
+cd <your-project>
+claude
+```
+
+In the session, invoke `canon:setup-init`. The skill detects no framework and resolves tooling to `base` and governance to `base`. The preview marks both stacks as fallbacks, since neither came from a match, then the chain runs `canon init`.
+
+Ongoing: run `canon sync --check .` to see what has drifted, then invoke `canon:claude-seed-sync` for seed drift or `canon sync .` for a catch-all refresh.
+
+### Web application
+
+```bash
+bun create vite my-app && cd my-app
+claude
+```
+
+Invoke `canon:setup-init`. The skill reads `package.json` and the Vite config, resolves tooling to `vite-react` and governance to `react`, and runs `canon init` with the resolved flags.
+
+Ongoing maintenance:
+
+- What has drifted: `canon sync --check .`
+- Seed drift: invoke `canon:claude-seed-sync`
+- Catch-all sync: `canon sync .`
+- Governance rule refresh only: `canon gov sync .`
+- Layer a new rule on top, for example `260-shadcn` after adopting shadcn: `canon gov install react --add 260-shadcn .`
+
+### Monorepo with multiple language roots
+
+The repo root owns the shared `base` layer, and each language lives in its own subfolder.
+
+```bash
+canon init --stack react .
+canon tooling sync vite-react ./frontend --skip base --write
+canon tooling sync python ./backend --skip base --write
+```
+
+`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, cspell, commitlint, and CI stay single at the repo root. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite), and its own stack reference reads through `canon tooling reference <stack>`.
+
+## Running sync from an agent session
+
+`canon sync .` applies every installed domain sync, then offers to commit the result and open a pull request. That last step needs a terminal. Under `CANON_NON_INTERACTIVE=1`, which is how an agent runs it, the domain syncs still apply and the git workflow is refused: the command reports the branch and commit it would have created, writes nothing to git, and exits 0. Review the working tree and commit it yourself, or rerun interactively to reach the commit and pull request options.
+
+Sync also refuses a target whose working tree is dirty, so commit or stash before running it. `canon sync --check .` has neither restriction, since it writes nothing.
+
+## Related
+
+- [agents](agents/index.md): CLI flags, exit codes, and JSON output shapes
+- [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
+- [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance/index.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards/index.md): per-domain mechanics
+- [sandbox](../.claude/context/sandbox/index.md): scenario catalog for verifying domain flows

package/docs/visual-design-workflow.md

@@ -0,0 +1,151 @@
+---
+title: Visual design workflow
+description: Tiered guide for design and wireframe authoring with Claude Code
+category: Workflow
+---
+
+# Visual design workflow
+
+Three tiers cover the range from prose-only design docs to a fully graphical design source of truth. Pick one per project based on how UI-heavy the work is, whether stakeholders review visuals, and whether a designer is involved. Tiers stack, so moving up does not invalidate work done at a lower tier.
+
+The tier framework sits alongside [Claude Design](../wiki/claude/claude-design.md), [visual wireframes](../wiki/tools/visual-wireframes.md), [community skills and plugins](../wiki/tools/community-skills.md), and [community MCP servers](../wiki/tools/community-mcp-servers.md). Those pages catalog the tooling. This page decides when to reach for what.
+
+Two tools anchor tier 1 and tier 2. [Stitch](../wiki/tools/stitch.md) is the agent-addressable default through its MCP server at `stitch.googleapis.com/mcp`, with a free tier of 400 daily credits that covers daily iteration. [Claude Design](../wiki/claude/claude-design.md), released 2026-04-17 and priced inside Claude subscriptions, is the ceiling tool reserved for codebase extraction and the richly annotated handoff bundle. Each covers a different job, they are not swappable.
+
+## Tier 0: prose only
+
+The default. `.claude/DESIGN.md` holds visual intent as prose plus token tables for color, typography, spacing, borders, motion, and iconography. `.claude/WIREFRAMES.md` holds ASCII layouts.
+
+Claude Code reads both and writes the implementation. Works for CLI tools, internal dashboards, admin panels, and backend-focused projects.
+
+### Seed shape
+
+The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table template with a starting set of roles, and `standards/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the renderer parses, so they stay verbatim in either, while the rows and values are the project's own.
+
+The `canon:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `canon design render` writes an HTML plus CSS preview to `.claude/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
+
+A cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
+
+### Tools
+
+- None beyond Claude Code itself
+- Playwright CLI optional for verifying form submissions and interactive surfaces. See [`claude-ui-test`](../claude/skills/claude-ui-test/SKILL.md).
+
+### Skills
+
+- `canon:claude-design-extract` to draft `.claude/DESIGN.md`, from existing project signals or from requirements alone on day one
+- `canon:claude-ui-test` for e2e test generation after UI changes
+- `canon:claude-ux-audit` for UX gap detection on existing surfaces
+- `canon:claude-ux-measure` for what a running surface costs to paint, read against published thresholds
+- Anthropic's `frontend-design` plugin optional for light visual steering
+
+### When to pick
+
+- UI is not the core product
+- Design decisions are few and can be written as sentences
+- No designer on the project
+- Stakeholders review code or behavior rather than mockups
+
+## Tier 1: visual companion
+
+ASCII and prose stay as source of truth. Add a visual render as a feedback surface for the agent and for human review.
+
+- Stitch via MCP handles agent-driven generation of prototypes and design systems
+- Excalidraw handles agent-driven wireframes when the round-trip canvas loop matters
+- Claude Design joins only when codebase extraction or the annotated handoff bundle is worth the ceiling cost
+
+All three produce derived artifacts, so human edits are review annotations rather than source changes.
+
+### Seed shape
+
+Same as tier 0 with two additions. `WIREFRAMES.md` opts into Excalidraw rendering via a top-of-file marker like `<!-- excalidraw: WIREFRAMES.excalidraw -->`. `DESIGN.md` stays human-maintained, and its content is what the toolkit provisions into Stitch via `create_design_system` when visual generation is needed.
+
+Impeccable, if installed, keeps its own root `DESIGN.md` and `PRODUCT.md` in the Stitch DESIGN.md spec format. These are separate files from the toolkit's `.claude/DESIGN.md` and are not synced with it. Treat impeccable's pair as its own source of truth for its commands, and the toolkit's `.claude/DESIGN.md` as the source other toolkit skills read.
+
+### Tools
+
+- Stitch via MCP at `stitch.googleapis.com/mcp`. Default pick for agent-driven visual generation. Free tier of 400 daily credits. See [Stitch](../wiki/tools/stitch.md).
+- Excalidraw canvas server on localhost plus the `yctimlin/mcp_excalidraw` MCP shim, for projects that need an agent to draw, read back, and revise a canvas. See [visual wireframes](../wiki/tools/visual-wireframes.md) for setup and footguns.
+- Playwright MCP for browser-side verification. See [Playwright](../wiki/tools/community-mcp-servers.md#playwright-microsoft).
+- Chrome DevTools MCP for live frontend debugging. See [Chrome DevTools](../wiki/tools/community-mcp-servers.md#chrome-devtools-google).
+- Claude Design as the ceiling option for codebase extraction or polished handoff bundles. See [Claude Design](../wiki/claude/claude-design.md).
+
+### Skills
+
+- Everything from tier 0
+- A frontend design skill to steer visual quality. Pick one of [Impeccable](../wiki/tools/community-skills.md#pbakausimpeccable), [UI/UX Pro Max](../wiki/tools/community-skills.md#nextlevelbuilderui-ux-pro-max-skill), or Anthropic's `frontend-design` plugin. Impeccable is the strongest default because of its curated anti-patterns.
+
+### When to pick
+
+- UI is a meaningful part of the product but not the entire product
+- Stakeholders want to see layout proposals before code exists
+- Design decisions benefit from visual inspection
+- A single contributor owns both design and implementation
+
+### Stitch vs Excalidraw vs Claude Design in tier 1
+
+The three tools solve non-overlapping halves of the visual companion problem.
+
+Stitch via MCP generates polished prototypes from text and a provisioned design system, scripted from a Claude Code session. Output is human-facing and lives in Stitch. Free daily quota makes it the right pick for frequent iteration.
+
+Excalidraw gives the agent a canvas it can read back over MCP. Output is agent-facing and persists as a JSON file in the repo. Pick it when Claude Code needs to iterate on wireframes autonomously, not when a human needs polished review artifacts.
+
+Claude Design reads the raw codebase without prose curation and produces a polished handoff bundle with chat history. Weekly quota makes it expensive, so reserve it for the extraction pass or the final handoff moment, not daily iteration.
+
+Most tier 1 projects pick one. Projects with a messy codebase and no curated `DESIGN.md` may want Claude Design once for the initial extraction, then move to Stitch for ongoing work.
+
+## Tier 2: visual as source of truth
+
+Design happens in a graphical tool. `.claude/DESIGN.md` either regenerates from the graphical source or takes a secondary role as agent-facing summary. Implementation follows the graphical source, either through an MCP round-trip or a one-way handoff bundle. Fits teams with a dedicated designer or projects where design iteration outpaces code changes.
+
+### Seed shape
+
+`.claude/DESIGN.md` becomes a generated artifact. A top-of-file note identifies the upstream source, either a Claude Design project ID or a Figma file URL. Manual edits in the seed carry a warning tag because they will not survive regeneration.
+
+### Tools
+
+- Figma desktop app with the [Figma Dev Mode MCP](../wiki/tools/community-skills.md#figma-mcp-and-code-to-canvas) for teams with a dedicated designer already on Figma. Bidirectional sync and Code to Canvas capture.
+- Claude Design with its Claude Code handoff bundle for teams without an existing Figma investment and for solo founders or PMs driving design themselves. One-way handoff, no bidirectional sync. See [Claude Design](../wiki/claude/claude-design.md).
+- Stitch via MCP as a low-cost complement to either, used for bulk screen generation driven by Claude Code. See [Stitch](../wiki/tools/stitch.md).
+- Playwright and Chrome DevTools MCPs as in tier 1
+
+### Skills
+
+- Everything from tier 1
+
+### When to pick
+
+- UI is the product or a major differentiator
+- A dedicated designer is on the project or will join
+- Design review happens in the graphical tool rather than in code
+- Design changes more often than implementation
+
+### Figma vs Claude Design in tier 2
+
+Figma wins when a dedicated designer already owns a Figma file, external collaborators expect Figma for review, or the workflow needs the agent to capture a running Claude Code UI and push it back as editable frames via Code to Canvas. Figma's MCP is bidirectional.
+
+Claude Design wins when nobody on the team has a Figma workflow yet and the handoff bundle with chat history is the intended implementation path. Claude Design's handoff is one-way, and its quota limits daily iteration, so it is most useful for the initial extraction pass and the final handoff moment rather than day-to-day design work.
+
+Either of the above pairs cleanly with Stitch via MCP for agent-driven screen generation between the two anchor moments.
+
+## Decision guide
+
+Four questions. Each yes weighs toward a higher tier.
+
+- Is the UI the product rather than a thin interface over a backend?
+- Do non-engineers review visual proposals before code exists?
+- Is there a dedicated designer, or will there be one?
+- Does design iterate independently of code?
+
+Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2.
+
+Resist over-tiering early. Moving up is cheap because tiers stack. Moving down means abandoning tooling and confusing collaborators.
+
+## References
+
+- [Stitch](../wiki/tools/stitch.md): Gemini-powered design product with the MCP server that anchors tier 1
+- [Claude Design](../wiki/claude/claude-design.md): first-party hosted design product and handoff bundle
+- `.claude/context/claude-plugin/skill-strategy.md`: how to decide between workflow and domain-knowledge skills
+- [Visual wireframes](../wiki/tools/visual-wireframes.md): Excalidraw research and setup for the tier 1 wireframe companion
+- [Community skills and plugins](../wiki/tools/community-skills.md): catalog of frontend design skills and integrations
+- [Community MCP servers](../wiki/tools/community-mcp-servers.md): catalog of MCPs referenced across all tiers

package/docs/zshrc-aliases.md

@@ -0,0 +1,65 @@
+---
+title: Zshrc aliases for Claude Code
+description: Shell aliases that shorten common Claude Code invocations
+category: Workflow
+---
+
+# Zshrc aliases for Claude Code
+
+Claude Code auto-discovers the toolkit plugin from `claude/.claude-plugin/plugin.json` when run inside the toolkit repository. Outside the toolkit, that discovery does not fire, so a separate set of aliases bakes in `--plugin-dir` explicitly. Two parallel sets cover both cases.
+
+## The aliases
+
+`bun run bootstrap` installs this block. It owns the canonical copy in `scripts/core/bootstrap.sh`, appends it to `~/.zshrc` wrapped in the two marker comments below, and sets `TOOLKIT` to the cloned path. The markers are how a re-run recognizes its own block and skips.
+
+A block installed by hand before the managed one has no markers. Bootstrap detects that case through the `alias clp=` line instead, warns, and leaves the block untouched rather than appending a second copy. To switch over, delete the hand-rolled block and re-run the bootstrap.
+
+```zsh
+# >>> canon aliases >>>
+TOOLKIT="/path/to/toolkit"
+
+alias cl='claude'
+alias clr='cl -r'
+alias clc='cl -c'
+alias clw='cl -w'
+alias cls='cl --model sonnet'
+
+alias clp='claude --plugin-dir $TOOLKIT/claude'
+alias clpc='clp -c'
+alias clps='clp --model sonnet'
+# <<< canon aliases <<<
+```
+
+The block sits after any `PATH` mutations and the `claude` CLI install. Zsh expands aliases recursively on the first word, so `clr`, `clc`, `clw`, and `cls` inherit their base through `cl`, and `clpc` and `clps` inherit `--plugin-dir` through `clp`. `$TOOLKIT` expands at invocation time, so updating the variable and re-sourcing reroutes all `clp` calls without touching the alias definitions.
+
+## What each one does
+
+`cl` through `cls` carry no explicit plugin dir. Use them inside the toolkit repository, where Claude Code auto-discovers the plugin from `claude/.claude-plugin/plugin.json`. Loading `--plugin-dir` on top of auto-discovery registers every skill twice and produces duplicate entries in the slash command list.
+
+- `cl`: plain session in the current directory
+- `clr`: opens the `/resume` picker scoped to the current directory. Trailing arguments filter by name. `clr auth` limits results to sessions containing "auth".
+- `clc`: jumps straight into the most recent session for the current directory. No picker. Faster than `clr` when the terminal closed and you want back into the same session.
+- `clw`: creates a worktree under `.claude/worktrees/<name>/` on a fresh branch and starts a Claude Code session in it. Pass the worktree name as the trailing arg: `clw feat-auth`.
+- `cls`: pins the session to Sonnet instead of the default Opus. Use for routine work where Opus cost is not justified.
+
+`clp`, `clpc`, and `clps` bake in `--plugin-dir`. Use them outside the toolkit repository, where auto-discovery does not fire.
+
+- `clp`: session with the toolkit plugin loaded explicitly
+- `clpc`: jumps straight into the most recent session for the current directory with the plugin loaded. The `clp` mirror of `clc`.
+- `clps`: `clp` pinned to Sonnet
+
+## When to use which
+
+Use `cl` by default when working in the toolkit repository. Auto-discovery loads the plugin and the two-key alias keeps it short.
+
+Use `clp` in any other repository where you want the toolkit skills available. Without the flag, those repos do not load the plugin.
+
+Use `cls` or `clps` to save Opus usage on routine sessions. Switch mid-session with `/model` to avoid restarting.
+
+Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for fan-out rules.
+
+Use `clc` to resume the last session without a picker. Use `clr` when you have several sessions and need to pick by name or recency. Outside the toolkit repo, `clpc` is the same shortcut as `clc` with the plugin loaded.
+
+## Why not a function
+
+A function with subcommand dispatch (`cl r`, `cl c`, `cl w foo`) was considered and rejected. It loses shell completion and adds a layer of indirection. Separate aliases are self-contained and the shared `cl`/`clp` prefixes make them easy to recall.

package/governance/rules/ci/700-ci-workflow.md

@@ -0,0 +1,44 @@
+---
+description: Enforce GitHub Actions job naming, granularity, dependency wiring, and bun pinning
+paths:
+  - '.github/workflows/**'
+---
+
+# CI workflow standards
+
+## Triggers and pinning
+
+- Include `workflow_dispatch` alongside the primary trigger on every workflow.
+- Pin every action to a major version tag. Never `@latest` or `@main`.
+- Run every job on `ubuntu-latest`.
+
+## Job naming
+
+- Name every job as an emoji followed by a title, such as `🛡️ Checks`, `🧪 Unit Tests`, `📦 Build Check`, `🎭 E2E Tests`, or `🚀 Deploy`.
+
+## Job granularity
+
+- Fold static analysis, unit tests, and build into one job while the gate runs under two minutes end to end.
+- Split them into parallel jobs once a run log puts the gate past two minutes.
+- Give E2E, release, and deploy a job each from the start.
+
+## Job dependencies
+
+- Use `needs` for a data dependency, where a job consumes another job's artifact, or for a job whose cost is prohibitive against the gate in front of it. Leave every other job unwired so it runs in parallel.
+- Gate E2E on the job that uploads the build artifact.
+- Gate release and deploy on E2E.
+- Emit a deploy, publish, or release job with a placeholder step and name what the caller fills in. Never guess a deploy command.
+
+## Artifacts
+
+- Upload an artifact on `if: failure()` alone, with `retention-days: 7`.
+
+## Bun stack
+
+- Use `oven-sh/setup-bun@v2` with `bun-version: latest`.
+- Install with `bun install --frozen-lockfile`.
+- Key the Playwright browser cache on the Playwright version string, never a static key.
+
+## Authority
+
+- Load the `canon:ci-workflow` skill for the workflow template and the per-project adaptation. Report it rather than proceeding silently when the skill does not resolve.

package/governance/rules/claude/500-prose.md

@@ -0,0 +1,15 @@
+---
+description: Route markdown edits to the write-human skill for voice, rhythm, sentence construction, and information density
+paths:
+  - '**/*.md'
+---
+
+# Markdown voice standards
+
+## Authority
+
+- Load the `canon:write-human` skill for voice, rhythm, sentence construction, and information density. It is the single source for all four.
+- Load it before drafting a passage, not after revising one.
+- Report it rather than proceeding silently when the skill does not resolve.
+- Do not work these rules from memory.
+- Banned words, spellings, punctuation, formatting, and file references are a separate topic. `501-markdown` routes them.

package/governance/rules/claude/501-markdown.md

@@ -0,0 +1,14 @@
+---
+description: Route markdown edits to the markdown standard for headings, lists, punctuation, banned words, and frontmatter wording
+paths:
+  - '**/*.md'
+---
+
+# Markdown mechanics standards
+
+## Authority
+
+- Follow the markdown standard for headings, paragraph and list structure, code spans, punctuation, emphasis, file references, the banned words and spellings, and the wording of a `title` or `description`. It is the single source. Read it with `canon standards markdown`.
+- Read it before a substantial markdown edit. Do not work the banned words or characters from memory.
+- Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+- Voice, rhythm, and sentence construction are a separate topic. `500-prose` routes them.

package/governance/rules/claude/510-context.md

@@ -0,0 +1,28 @@
+---
+description: Route .claude/context edits to the context-entry standard and the consult-first workflow
+paths:
+  - '.claude/context/**'
+---
+
+# Context entry standards
+
+## Before editing
+
+- Before non-trivial work in a domain, read its `.claude/context/<domain>.md` entry. Use `.claude/context/index.md` to find it.
+- Leave the entry conforming when work in its domain changes what it describes.
+
+## Narration pronouns
+
+Do not open a bullet with one of these where the antecedent is the bullet above it.
+
+- `It`, `That`, `This`, `These`, `Those`, `They`
+
+## Narration verbs
+
+Do not put a sibling bullet's design in the past with one of these.
+
+- `was`, `were`, `became`, `replaced`, `superseded`, `used to`
+
+## Authority
+
+- Follow the context standard for entry shape: frontmatter, sections, length, and what goes in. It is the single source. Read it with `canon standards context`.

package/governance/rules/claude/511-indexes.md

@@ -0,0 +1,14 @@
+---
+description: Route index.md edits to the regeneration verb, its frontmatter contract, and the hand-edit opt-out
+paths:
+  - '**/index.md'
+---
+
+# Index standards
+
+## Generation
+
+- Do not hand-edit an `index.md` that an agent browses to pick a document. Run `canon indexes regen` instead.
+- Preserve an `index.md`'s own frontmatter (`title`, `subtitle`). The regen walker keeps it.
+- Add `auto: false` to an `index.md`'s frontmatter to keep that folder's index hand-edited.
+- Skip `index.md` in a code folder or a scratch folder. Neither needs one.

package/governance/rules/claude/520-wireframes.md

@@ -0,0 +1,12 @@
+---
+description: Route .claude/wireframes edits to the wireframe standard for layout and interaction intent
+paths:
+  - '.claude/wireframes/**'
+---
+
+# Wireframe standards
+
+## Authority
+
+- Follow the wireframes standard for layout and interaction intent: ASCII layout, region labels, variants, copy, and what moves to `.claude/context/`. It is the single source. Read it with `canon standards wireframes`.
+- Read it before adding or revising a surface.

package/governance/rules/claude/530-requirements.md

@@ -0,0 +1,11 @@
+---
+description: Route .claude/REQUIREMENTS.md edits to the requirements standard for product scope and goals
+paths:
+  - '.claude/REQUIREMENTS.md'
+---
+
+# Requirements standards
+
+## Authority
+
+- Follow the requirements standard for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source. Read it with `canon standards requirements`.