@erclx/canon 5.39.0 → 5.41.0

package/README.md

@@ -12,7 +12,6 @@
 [![License MIT](https://img.shields.io/npm/l/@erclx/canon)](LICENSE)
 
 canon is a CLI and Claude Code plugin that runs your agent's work from plan to merge, holds it to the practices that make code worth keeping, and installs the same setup in every repository.
-
 **[See it run at canon.erclx.dev](https://canon.erclx.dev)**
 
 </div>
@@ -21,9 +20,13 @@ That page is one real session the toolkit ran on itself, and every count on it i
 
 ## Why
 
-If an agent writes code for you in more than one repository, this is for you. canon runs that work from plan to merge. A planner writes the plan, a worker builds it on its own branch, and a separate session reviews the pull request. It holds the work to a practice, with rules that load when a matching path is edited and checks that fail when a rule is ignored. Both run on one setup, installed the same way in every repository you keep.
+If an agent writes code for you in more than one repository, this is for you. canon runs that work from plan to merge. A planner writes the plan, a worker builds it on its own branch, and a separate session reviews the pull request.
+
+It holds the work to a practice, with rules that load when a matching path is edited and checks that fail when a rule is ignored. Both run on one setup, installed the same way in every repository you keep.
 
-That shared setup is what the rest of this page describes, and it is the part that drifts without a source. Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.
+### The shared setup
+
+That shared setup is what the rest of this page describes, and it drifts without a source. Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.
 
 Three design choices shape the toolkit.
 
@@ -61,17 +64,21 @@ bun install --global @erclx/canon
 
 Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The domains split on one line: some are copied into your project and become yours to edit, and some are never copied at all.
 
-| Domain         | What it is                                                                                                                                                                   | How it reaches you                                              |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain                                                                                    | Loaded live from the plugin, never copied                       |
-| Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                                                                                    | Installed per project by `canon gov install`, refreshed by sync |
-| Tooling stacks | Golden configs, seeds, and a reference per framework                                                                                                                         | Laid down by `canon init`, reconciled by `canon tooling sync`   |
-| Design system  | Ships a `DESIGN.md` intent format that points at the project's stylesheet for values, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
-| Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                                                                               | `canon slides render` writes PowerPoint                         |
-| Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                                                                                  | `canon teach`                                                   |
-| Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                                                                             | `canon canvas serve`                                            |
-| Transcripts    | A YouTube transcript with metadata frontmatter                                                                                                                               | `canon transcripts <url>` writes it into any repo               |
-| Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                                                                                   | `canon sandbox`                                                 |
+### Domain catalog
+
+| Domain         | What it is                                                                                                              | How it reaches you                                              |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain                               | Loaded live from the plugin, never copied                       |
+| Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                               | Installed per project by `canon gov install`, refreshed by sync |
+| Tooling stacks | Golden configs, seeds, and a reference per framework                                                                    | Laid down by `canon init`, reconciled by `canon tooling sync`   |
+| Design system  | Ships a `DESIGN.md` intent format pointing at your stylesheet for values, a skill that drafts one, and a render command | `canon design render`                                           |
+| Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                          | `canon slides render` writes PowerPoint                         |
+| Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                             | `canon teach`                                                   |
+| Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                        | `canon canvas serve`                                            |
+| Transcripts    | A YouTube transcript with metadata frontmatter                                                                          | `canon transcripts <url>` writes it into any repo               |
+| Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                              | `canon sandbox`                                                 |
+
+### How domains reach you
 
 Those domains reach you in three shapes. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A plugin skill and the references it carries are never copied, so there is no copy in your repo to drift from this one.
 
@@ -117,6 +124,8 @@ The first two update the skills, the third updates the CLI, and they move indepe
 
 `canon upgrade` reads the package manager off its own install path and reinstalls with that one, so you don't have to remember which put it there. It names what it detected before it runs anything, and it refuses a source checkout rather than reinstalling over your clone.
 
+### Checking for drift
+
 You don't have to wait until something breaks to find out you're behind. `canon sync --check` and `canon claude skills drift` both report the installed version against the newest published one, and neither changes its exit code over it, so an offline machine reads unknown rather than red.
 
 To stop doing this by hand, turn auto-update on once under `/plugin` in the Marketplaces tab. Confirm what you are running with `canon --version` and `claude plugin list`.
@@ -127,6 +136,8 @@ Working on the toolkit starts from a clone. Running the CLI doesn't, since it in
 
 ### Prerequisites
 
+Bun, Git, and a shell are required, and the GitHub CLI is optional.
+
 - [Bun](https://bun.sh) for the CLI runtime and scripts
 - [Git](https://git-scm.com) with worktree support
 - [GitHub CLI](https://cli.github.com) (optional) for ship flows
@@ -141,7 +152,10 @@ bun install
 bun run bootstrap
 ```
 
-The script is idempotent, so re-run it after pulling upstream changes without duplicating anything. That also means it leaves an alias block you already have alone rather than refreshing it, so an alias added upstream needs the block deleted and the script re-run. It confirms the install by resolving `canon --help` on the last step. See [zshrc aliases](docs/workflow/zshrc-aliases.md) for what each alias does, how to pick up a new one, and how to opt out of the block.
+The script is idempotent, so re-run it after pulling upstream changes without duplicating anything. It confirms the install by resolving `canon --help` on the last step.
+
+- It leaves an alias block you already have alone rather than refreshing it, so an alias added upstream needs the block deleted and the script re-run.
+- [Zshrc aliases](docs/workflow/zshrc-aliases.md) covers what each alias does, how to pick up a new one, and how to opt out of the block.
 
 With the CLI linked, scaffold a fresh project.
 
@@ -151,9 +165,12 @@ git init
 canon init
 ```
 
-`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the workflow and doc-authoring rules in `.claude/rules/`. Each rule names the skill it loads, so no corpus is copied into your project.
+`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages.
 
-Pass `--stack <name>` for a language stack such as `node` or `python`, or `--skip governance` to leave rules out. Run `canon tooling list --json` to see the catalog.
+- Governance defaults to the `base` stack, so a bare init lands the workflow and doc-authoring rules in `.claude/rules/`.
+- Each rule names the skill it loads, so no corpus is copied into your project.
+- Pass `--stack <name>` for a language stack such as `node` or `python`, or `--skip governance` to leave rules out.
+- Run `canon tooling list --json` to see the catalog.
 
 For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target/projects.md).
 
@@ -161,13 +178,13 @@ For the full journey from scaffold through adding a domain later to syncing upst
 
 Each domain carries an entry written for someone maintaining the toolkit rather than installing it. These paths resolve in a clone only. The published package ships `docs` and not `.claude`, so an installed copy does not carry them.
 
-- [Claude Code plugin](canon/context/claude-plugin/index.md)
-- [Governance rules](canon/context/governance/index.md)
-- [Tooling stacks](canon/context/tooling/index.md)
-- [Design system](canon/context/design.md)
+- [Claude Code plugin](canon/context/surfaces/plugin.md)
+- [Governance rules](canon/context/surfaces/governance.md)
+- [Tooling stacks](canon/context/surfaces/tooling.md)
+- [Design system](canon/context/features/design.md)
 - [Slides](canon/context/features/slides.md)
 - [Transcripts](canon/context/features/transcripts.md)
-- [Sandbox](canon/context/sandbox/index.md)
+- [Sandbox](canon/context/development/sandbox.md)
 
 ## Contributing
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.39.0",
+  "version": "5.41.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/auto-ship/REQUIREMENT.md

@@ -19,6 +19,7 @@ Without this skill, the run from an approved plan to an open pull request is a c
 - Open the pull request as a draft before the continuous integration watch begins, since a pull request marked after it is mergeable for the length of the run
 - Continue past a produced UI checklist rather than stopping on it, and report its unchecked boxes in the closing block, since the draft mark already holds the merge
 - Prove the draft target's head is the current branch and its state is open before marking it, and stop with nothing marked on a mismatch, since the number is retyped between steps and a draft mark on a release pull request holds that release
+- Stop a fan-in member after its verify and test order with a push and a done message rather than a pull request, and open an integrator's build by merging the member branches, since parallel batches sharing edge files put every open sibling into conflict on each merge
 - Name the recovery for the stop it took, since the value of stopping is that the user knows where to resume
 
 ## Must not

package/claude/skills/auto-ship/SKILL.md

@@ -73,6 +73,8 @@ When this run decides against a suggestion, rewrite its line as `overridden at e
 
 Load `canon:build-in-slices`, reporting it when it does not resolve, and implement only what the plan describes. Do not expand scope, refactor neighbors, or touch files outside the plan's "Files to touch" list without reason.
 
+When the plan's `**Constraints:**` carry a `Fans in` bullet, this run is a fan-in integrator, so open this step by merging the member branches, per `${CLAUDE_SKILL_DIR}/references/fan-in.md`.
+
 ## Step 3: verify
 
 Run the verify commands defined in `CLAUDE.md` (lint, typecheck, tests). On failure:
@@ -97,6 +99,10 @@ The verb reads git history rather than the working tree, so it catches a violati
 
 Never read a missing subcommand as clean. Read `${CLAUDE_SKILL_DIR}/references/verb-absent.md` on meeting one.
 
+### A fan-in member stops here
+
+When the plan's `**Constraints:**` carry a `Fan-in member of` bullet, push the branch, announce it done, and stop before Step 5. A member opens no pull request, since its integrator ships the whole set. Read `${CLAUDE_SKILL_DIR}/references/fan-in.md` for the push and the message.
+
 ## Step 5: UI checklist (conditional)
 
 If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:ui-checklist`, then continue to Step 6 whatever it returns, in every run. The Step 6 draft mark holds the merge, so a stop here protects nothing.

package/claude/skills/auto-ship/references/fan-in.md

@@ -0,0 +1,59 @@
+---
+title: Fan-in member exit and integrator merge
+description: How auto-ship stops a fan-in member after its push and how an integrator merges the member branches before its own build, so a set of parallel batches ships as one pull request
+---
+
+# Fan-in
+
+The session reads this file at one of two points in `auto-ship`. A member reads `## Member exit` after Step 4, and an integrator reads `## Integrator merge` at the opening of Step 2. When to fan in and how a plan declares its side are in `${CLAUDE_SKILL_DIR}/../plan-feature/references/batches.md`.
+
+## Member exit
+
+Step 3's verify and Step 4's test order have already run, so the branch is green and committed. The member ends here rather than at a pull request.
+
+1. Push the branch with `git push -u origin <branch>`. The pre-push hook runs the project check, and a member that fails it stops the way Step 3 does.
+2. Read the head with `git rev-parse HEAD` once the push returns.
+3. Announce the batch done to the controlling session through `canon:session-relay`, carrying the branch, the head commit, the integrator the plan names, and any row this build turned up.
+4. Stop. Run no UI checklist, no `git-ship`, and no draft mark.
+
+The pushed branch is the done signal the integrator's gate reads, so push once, at the end, and never mid-build. The announcement carries no reach, since members of one set share files by design and the integrator's announcement carries the reach for the whole set.
+
+A fix the integrator needs after this point lands on the integrator's branch, since a member has no pull request to fix it on.
+
+## Integrator merge
+
+The members are pushed before this run starts, since `canon tasks plan-answers` holds an integrator until every member branch is on origin. Confirm that before merging anything:
+
+```bash
+git fetch origin --quiet
+canon tasks plan-answers <plan> --json
+```
+
+Stop on `launchable: false`, reporting each `open` entry, since a `Fan-in pending` entry names a member that has not pushed and a `Fan-in set` entry names a set whose sides disagree. Then merge each member in the order the `Fans in` bullet lists:
+
+```bash
+git merge --no-ff --no-edit origin/<member branch>
+```
+
+### Conflicts and the order
+
+`--no-ff` keeps one merge commit per member, so `git log --first-parent` shows the reviewer one member at a time. Never squash or fast-forward a member in.
+
+- Resolve each conflict by `## Resolving a conflict` in `${CLAUDE_SKILL_DIR}/../review-address/references/rebase-conflicts.md`
+- Stop on a hunk needing a decision with `git merge --abort` in place of the rebase abort that file names
+- Regenerate the indexes once, after the last merge, rather than resolving a generated file by hand at each one
+- Run `git config rerere.enabled true` before the first merge, since a stale integrator rebases with `--rebase-merges` per the same file and that replays each merge without its recorded resolution
+
+Continue Step 2 with the integrator plan's own `**Files to touch:**`, then the rest of the chain as an ordinary worker.
+
+### What the pull request carries
+
+Say in the pull request body that each member is one merge commit and name the members in merge order. Once the pull request merges, delete each member's branch on origin, its worktree, and its local branch:
+
+```bash
+git push origin --delete <member branch>
+git worktree remove <member worktree>
+git branch -D <member branch>
+```
+
+Read each member's worktree path off `git worktree list --porcelain` by its branch. The integrator holds the member list, so the deletion is its step rather than a sweep's. No member opens a pull request, so `canon worktrees reclaim` never reads a member's branch as merged and reports a leftover worktree as unmerged work on every run.

package/claude/skills/canvas-board/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 Drive the canvas the operator is looking at. A page is a folder of HTML frames and a frame is one file, so a session draws by writing files and the operator sees each write land in the browser. The content format is fixed by `${CLAUDE_SKILL_DIR}/references/canvas.md`. Read it before writing a frame.
 
-Every verb below is `canon canvas`. Run `canon docs canvas` for the full verb reference, its records, and its refusals.
+Every verb below is `canon canvas`. Run `canon canvas --help` for the verbs and their refusals, and read `${CLAUDE_SKILL_DIR}/references/canvas.md` for the content format.
 
 ## Guards
 

package/claude/skills/create-skill/references/skill.md

@@ -104,7 +104,7 @@ allowed-tools: <tools required>
 
 - **`name`** (required): kebab-case, matches folder name, no spaces or capitals
 - **`description`** (required): what it does + when to use it, under 1024 chars, no XML tags
-- **`disable-model-invocation: true`**: user-invoked only, Claude will not auto-trigger. Set it on a skill that starts a process the operator owns, never on one reachable by a matched trigger.
+- **`disable-model-invocation: true`**: Claude will not auto-trigger, and the `Skill` tool also refuses the operator's own request made in words. Set it only on a skill run by slash command alone. A skill wanting just the first effect writes `Do NOT auto-trigger` in its description.
 - **`allowed-tools`**: restrict tool access when the skill is active
 - **`metadata`**: optional key-value pairs (`author`, `version`, `mcp-server`)
 - **`metadata.family`** (required on a skill under `claude/skills/`): the skill map group the skill's row sits under, as one key from `families` in `canon claude skills list --json`. A skill under `.claude/skills/` takes none.

package/claude/skills/decision-escalate/REQUIREMENT.md

@@ -41,4 +41,4 @@ The opposite failure is the one that ships silently. A session that takes a pref
 
 - Making the ordinary judgment call, which is a pick plus a one-sentence tradeoff and needs no surface
 - Writing the decision into a plan, task, or context entry, which each owning standard governs and this skill only routes to
-- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so escalating is the operator's call rather than a description match.
+- Deciding when to fire. The description states `Do NOT auto-trigger`, so escalating is the operator's call rather than a description match.

package/claude/skills/decision-escalate/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: decision-escalate
-description: Collects every open decision whose answer turns on the operator's preference, since only they know what they need, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
-disable-model-invocation: true
+description: Collects every open decision whose answer turns on the operator's preference, since only they know what they need, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence. Do NOT auto-trigger.
 metadata:
   family: decide
 ---

package/claude/skills/draft-slides/SKILL.md

@@ -11,16 +11,15 @@ Draw each slide as an HTML file in a deck folder, then shell out to `canon slide
 
 ## Read the decks and the format
 
-Run both first. Never hardcode a deck name, an attribute, or a chart type. The CLI is the source of truth for each.
+Run the list first, then read the format. Never hardcode a deck name, an attribute, or a chart type.
 
 ```bash
 canon slides list --json 2>/dev/null
-canon docs slides
 ```
 
 The list returns one row per deck, carrying its `name`, `title`, slide count, and `path`. When the request names a deck the list holds, edit that folder. Otherwise pick a new kebab-case name no row carries.
 
-The docs page states what `deck.json` holds, what each slide declares on its `<body>`, the motion attributes, speaker notes, charts, and what each refusal reports.
+Read `${CLAUDE_SKILL_DIR}/references/deck.md`. It states what `deck.json` holds, what each slide declares on its `<body>`, the motion attributes, speaker notes, and charts. Each refusal prints as a `✗` line from the render.
 
 ## Draw the deck
 

package/claude/skills/draft-slides/references/deck.md

@@ -0,0 +1,183 @@
+---
+title: Deck reference
+description: The deck folder, the deck.json fields, the attributes a slide sets on its body, motion, the master's token roles, speaker notes, and charts
+---
+
+# Deck reference
+
+Applies to the slides under `.canon/slides/<deck>/`, which `canon slides render <deck>` turns into an editable PowerPoint file. Each slide describes its own shapes. What belongs to the whole deck sits in `deck.json`.
+
+## Contents
+
+- [The deck folder](#the-deck-folder)
+- [The deck file](#the-deck-file)
+- [What each slide declares](#what-each-slide-declares)
+- [Motion](#motion)
+- [The master](#the-master)
+- [Speaker notes](#speaker-notes)
+- [Charts](#charts)
+
+## The deck folder
+
+| Path                             | Holds                                                |
+| -------------------------------- | ---------------------------------------------------- |
+| `.canon/slides/<deck>/*.html`    | the slides, rendered in filename order               |
+| `.canon/slides/<deck>/deck.json` | what belongs to the whole deck                       |
+| `.canon/slides/<deck>/assets/`   | images the slides reference by a relative path       |
+| `.canon/slides/layouts/`         | the project's shared layouts, never listed as a deck |
+
+A folder holding no `.html` file is not a deck. `render` with no name takes the only deck, and refuses with the list when there are several. It also takes a folder path outside `.canon/slides/`.
+
+## The deck file
+
+`deck.json` is optional. Without it the deck takes the defaults below.
+
+| Field          | Default                        | What it sets                                      |
+| -------------- | ------------------------------ | ------------------------------------------------- |
+| `title`        | the folder name                | the file's title and the default footer text      |
+| `header`       | off                            | a band at the top, with `left`, `center`, `right` |
+| `footer`       | on, with the title on the left | a band at the bottom, with the same three slots   |
+| `slideNumbers` | `true`                         | the number at the right of the footer             |
+| `mark`         | none                           | an image path, relative to the folder, top right  |
+| `fonts`        | none                           | faces to embed in the file                        |
+
+```json
+{
+  "title": "Q3 review",
+  "header": { "left": "Acme" },
+  "footer": { "center": "Internal" },
+  "mark": "assets/mark.png",
+  "fonts": [
+    { "family": "Inter", "path": "fonts/Inter-Regular.ttf" },
+    { "family": "Inter", "weight": 700, "path": "fonts/Inter-Bold.ttf" }
+  ]
+}
+```
+
+### Bands and the mark
+
+A band takes `show` and the three slots. A declared band merges over its default, so `"footer": { "center": "Internal" }` keeps the title on the left. Declaring any slot turns a band on unless it also says `"show": false`. Set a slot to `""` to empty it.
+
+- Slide numbers hold the footer's right slot and show only where the footer does. Set `slideNumbers` to `false` to use `footer.right`.
+- Prefer a raster mark, since an SVG mark lands as a vector with a broken fallback.
+
+### Embedded faces
+
+Each `fonts` entry names one TrueType or OpenType file inside the deck folder:
+
+| Key      | Default  | Rule                                                                |
+| -------- | -------- | ------------------------------------------------------------------- |
+| `family` | required | match the family the slides set                                     |
+| `weight` | `400`    | `600` and above fills the bold slot, anything lighter fills regular |
+| `style`  | `normal` | `normal` or `italic`                                                |
+| `path`   | required | relative to the folder, and has to stay inside it                   |
+
+A face is left out, and the deck still written, when its license forbids embedding, when it is a variable font or a `woff` or `woff2` file, or when a second face lands in a filled slot. Supply static instances, one per weight, and the TrueType or OpenType file a `woff2` was compressed from.
+
+## What each slide declares
+
+A slide sets its place in the deck through attributes on `<body>`.
+
+| Attribute                               | Effect                                        |
+| --------------------------------------- | --------------------------------------------- |
+| `data-section="Results"`                | opens a section the slides after it stay in   |
+| `data-hidden`                           | hides the slide in the show                   |
+| `data-header="off"`                     | drops the header on this slide                |
+| `data-footer="off"`                     | drops the footer and its number on this slide |
+| `data-footer-left`, `-center`, `-right` | replaces that footer slot on this slide alone |
+| `data-header-left`, `-center`, `-right` | replaces that header slot on this slide alone |
+
+Once any slide opens a section, slides ahead of the first sit in a section named after the deck. A title the deck returns to after another section opens a new section numbered `Intro (2)`.
+
+A slide dropping one band keeps the other from the master. A slide replacing a slot draws its band as its own text, so a later edit in the master view skips it.
+
+## Motion
+
+| Attribute                  | Takes                           | Effect                                 |
+| -------------------------- | ------------------------------- | -------------------------------------- |
+| `data-transition`          | `fade`, `push`, `wipe`, `cover` | the transition into this slide         |
+| `data-transition-duration` | `500`, `500ms`, or `0.5s`       | rounded to 0.5, 0.75, or 1 second      |
+| `data-enter`               | `fade`, `fly`, `wipe`, `zoom`   | an entrance played on a click          |
+| `data-enter-order`         | a number                        | the click it plays on, lowest first    |
+| `data-enter-duration`      | `500`, `500ms`, or `0.5s`       | the entrance length, 500 ms by default |
+
+`data-transition` and `data-transition-duration` go on `<body>`. The `data-enter` family goes on the element.
+
+```html
+<body data-transition="fade">
+  <h1>Results</h1>
+  <div class="card" data-enter="fly" data-enter-order="1">…</div>
+  <div class="card" data-enter="fly" data-enter-order="2">…</div>
+</body>
+```
+
+- Each entrance is its own click, and entrances without an order play after the ordered ones, in page order.
+- An entrance brings in every shape drawn from its element and the elements inside it, so a card's box and text arrive together.
+- An inner element with its own `data-enter` waits for its own click.
+- Fly comes in from the bottom and wipe from the left.
+
+## The master
+
+The master takes its colors from the `<html>` element of the first slide, laid out with the project's token stylesheet injected:
+
+| Source                                       | Used for         |
+| -------------------------------------------- | ---------------- |
+| `--color-background`                         | the slide ground |
+| `--color-text`                               | the header text  |
+| `--color-muted`                              | the footer text  |
+| `--color-accent`                             | the slide number |
+| `<body>` font family, ` Variable` suffix cut | the theme face   |
+
+A role the project declares no token for falls back to the slide body's own color and prints one `✗` line naming it. It never falls back to the toolkit's palette.
+
+A slide whose `<body>` background differs from the master's keeps its own. A slide whose `<body>` computes a `--color-text` apart from the master's prints a `✗` line, since its bands keep the master's colors and may not read against its ground.
+
+## Speaker notes
+
+`<aside class="notes">` becomes the slide's notes and is never drawn. Each paragraph or list item becomes its own line, and markup is dropped.
+
+## Charts
+
+A `<figure data-chart="...">` holding a `<table>` becomes a native, editable chart where the figure was laid out. The table is not drawn as well.
+
+```html
+<figure data-chart="bar" data-labels>
+  <figcaption>Revenue by region</figcaption>
+  <table>
+    <tr>
+      <th>Region</th>
+      <th>Q1</th>
+      <th>Q2</th>
+    </tr>
+    <tr>
+      <td>North</td>
+      <td>12</td>
+      <td>16</td>
+    </tr>
+    <tr>
+      <td>South</td>
+      <td></td>
+      <td>11</td>
+    </tr>
+  </table>
+</figure>
+```
+
+- `data-chart` takes `bar`, `line`, `area`, `pie`, or `doughnut`.
+- The header row names the series and the first column names the categories.
+- An empty cell is a gap, not a zero. A comma is a thousands separator only where it groups in threes, as in `12,345.5`, so a comma-decimal `3,5` refuses.
+- `data-labels` shows each value, and a `<figcaption>` becomes the chart title.
+- Series take the accent first, then every other declared `--color-*` role in sheet order except the background and surface, repeating past the last.
+
+A refused chart, effect, or face is left out and the rest of the deck is written. Each prints a `✗` line, and the exit depends on the case:
+
+| Case                                                                    | Exit |
+| ----------------------------------------------------------------------- | ---- |
+| malformed or unknown `deck.json` field                                  | 1    |
+| `mark` path missing                                                     | 1    |
+| `fonts` path missing or outside the folder                              | 1    |
+| face that cannot embed                                                  | 0    |
+| unknown transition or entrance name                                     | 0    |
+| entrance on an element that draws nothing                               | 0    |
+| chart cell that is not a number, or `data-chart` off-list               | 0    |
+| token role not declared, or a slide body setting its own `--color-text` | 0    |

package/claude/skills/git-branch/REQUIREMENT.md

@@ -9,12 +9,17 @@ description: What branch naming is for, the gaps it closes, and where the family
 
 Without this skill, a branch name is invented once per session. The type prefix drifts from what the history already carries, the name runs past the width a pull request list renders, and a rename lands on a branch that already exists on the remote, which detaches every open pull request pointing at it.
 
+A session standing on `main` has no route either. The `git.md` rule sends every git operation through a `git-*` skill, and the only one for branches stopped on `Cannot rename a protected branch`, so the first act of any feature, creating its branch, had no skill to go through.
+
 ## Must
 
 - Read the branch format reference before generating, so the type vocabulary and the length limit come from one source
-- Derive the name from the commits ahead of main when the invocation carries no description
+- Create the branch on `main` or `master` and rename it anywhere else, so one skill covers both ends of a branch's start
+- Derive the name from the commits ahead of main when a rename carries no description
+- Take a created name from `canon tasks plan-branch` when the invocation names a plan, so the skill and the dispatch gate hold one derivation
 - Resolve whether the branch exists on the remote before proposing a rename, since the hazard is invisible from local state
-- Show the name and its length against the limit before renaming
+- Read the remote itself with `git ls-remote` before creating, since `origin/<name>` sees only the last fetch
+- Show the name and its length against the limit before renaming or creating
 - Execute immediately after the preview. The tool permission dialog is the confirmation gate.
 
 ## Must not
@@ -22,17 +27,23 @@ Without this skill, a branch name is invented once per session. The type prefix
 - Rename `main` or `master`
 - Rename when the current name already conforms. The skill is chained, so a conforming name has to pass through rather than churn the branch.
 - Rename a branch that exists on the remote. Local rename plus force push is not the same operation and it breaks the pull request.
+- Create a branch from anywhere but `main` or `master`, or create one whose name exists locally or on the remote
+- Invent a name when the plan verb refuses, since a name the skill calls non-conforming strands the rename at ship
+- Fetch or stash while creating
 - Emit anything after the result line
 
 ## Guards
 
-- On a protected branch: stop and say the branch is protected
-- Name already conforms: stop with a success marker, not a failure, since a chained caller continues past it
-- No commits and no description: stop and name both missing inputs
-- Branch exists on the remote: stop and route to the surface that preserves the pull request link
+- Create with no plan and no name: stop and name both missing inputs
+- Create with a name breaking the branch standard: stop and name the cap
+- Create with a name existing locally or on the remote: stop and say which
+- Rename name already conforms: stop with a success marker, not a failure, since a chained caller continues past it
+- Rename with no commits and no description: stop and name both missing inputs
+- Rename of a branch existing on the remote: stop and route to the surface that preserves the pull request link
 
 ## Out of scope
 
 - The commit message, which `git-commit` owns
 - Pushing and opening the pull request, which `git-pr` owns. That skill reads a conforming name as a precondition and refuses without one, so this skill runs first.
 - Splitting a branch whose commits span concerns, which `git-split` owns
+- Entering a worktree, which `session-worktree` owns and which names its own branch

package/claude/skills/git-branch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-branch
-description: Generates and validates conventional branch names. Use for any branch naming or renaming, such as when asked to "name this branch".
+description: Generates and validates conventional branch names, creating the branch from main or master and renaming it anywhere else. Use for any branch naming, creating, or renaming, such as when asked to "name this branch" or "create the branch for this feature".
 metadata:
   family: ship
 ---
@@ -13,7 +13,64 @@ Before generating a branch name, read:
 
 Follow it exactly.
 
-## Context
+Run `git branch --show-current` to pick the mode. On `main` or `master` the skill creates a branch, and anywhere else it renames the current one.
+
+## Create mode
+
+### Name
+
+Take the name from the invocation. An argument ending in `.md` or resolving under `.canon/plans/` is a plan, and anything else is a branch name, since a name always carries a `<type>/` segment.
+
+- For a plan, run `canon tasks plan-branch <plan> --json` and take the record's `branch`. The verb fixes the type at `feat`, so a plan never yields another type.
+- When the verb refuses or the record carries `conforms: false`, stop and relay its reason. Never invent a name in its place.
+- For a name, check it against the whole Format section of `branch.md`, including the description word bound and the no-repeated-type rule, as the rename guard does.
+
+### Context
+
+Run these in parallel once the name is known:
+
+- `git show-ref --verify --quiet "refs/heads/<name>" && echo "LOCAL_EXISTS" || echo "LOCAL_FREE"`
+- `git ls-remote --exit-code --heads origin "<name>" 2>/dev/null; echo "REMOTE_EXIT=$?"`
+
+Exit 0 on the remote read is a collision. Exit 2, or a repository with no `origin`, is no collision. The check reads the remote itself, never `origin/<name>`, which sees only the last fetch. The skill does not fetch.
+
+### Guards
+
+Each guard stops before any ref moves.
+
+- If the invocation carries no plan and no name, stop: `❌ No plan or branch name to create from.`
+- If the name breaks `branch.md`, stop and name the cap it broke: `❌ <name> breaks the branch standard: <cap>.`
+- If the name exists locally, stop: `❌ Branch <name> already exists locally.`
+- If the name exists on the remote, stop: `❌ Branch <name> already exists on origin.`
+
+### Preview
+
+Output the preview first.
+
+- **Current:** <main_or_master>
+- **Creating:** <name>
+- **Length:** <count>/50
+- **Source:** <plan | name>
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Final command
+
+The branch starts at the current tip, and uncommitted changes carry onto it. The skill stashes nothing.
+
+```bash
+git switch -c <name>
+```
+
+### After execution
+
+Respond with exactly one line and add no other text:
+
+`✅ Created: <name>`
+
+## Rename mode
+
+### Context
 
 Run these commands in parallel to gather git context:
 
@@ -21,14 +78,13 @@ Run these commands in parallel to gather git context:
 - `git rev-parse --verify "origin/$(git branch --show-current)" 2>/dev/null && echo "EXISTS" || echo "LOCAL_ONLY"`
 - `git log main..HEAD --oneline 2>/dev/null || echo "NO_COMMITS"`
 
-## Guards
+### Guards
+
+A conforming name passes through, so a chained caller continues past it.
 
-- If already on main or master, stop: `❌ Cannot rename a protected branch.`
 - If branch name already follows conventions, stop: `✅ Branch name already follows conventions.`
 - If no commits and no args provided, stop: `❌ No commits or description to derive a branch name from.`
 
-## Response format
-
 ### Preview
 
 Output the preview first.
@@ -55,7 +111,7 @@ Only output if LOCAL_ONLY:
 git branch -m <current> <suggested>
 ```
 
-## After execution
+### After execution
 
 Respond with exactly one line and add no other text: