@erclx/canon 4.115.0 → 4.116.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.115.0",
+  "version": "4.116.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/teach-workspace/SKILL.md

@@ -113,7 +113,7 @@ Write each option as a `<label class="opt" data-k="<letter>">` holding a radio `
 
 Then carry a teach-back block beside the quiz. A quiz is recognition and the pedagogy prefers production, so a lesson offering only a quiz tests the weak form. Ask for an explanation to a named audience, and carry a `<details>` listing what a complete explanation covers, closed by default, so a learner reading with no session in the room can grade themselves. The reference states both shapes in full.
 
-Compose the quiz and the teach-back block as one string. Below, that string is the block list's trailing `raw` entry, rather than markup written into the file by hand.
+Compose the quiz and the teach-back block as one string. Below, that string is the block list's last `raw` entry, followed only by `refs`, rather than markup written into the file by hand.
 
 ### Building the lesson body
 
@@ -126,12 +126,14 @@ echo '[
   {"type":"heading","level":1,"text":"<title>"},
   {"type":"paragraph","lede":true,"text":"<the dek>"},
   {"type":"paragraph","text":"<a body paragraph>"},
+  {"type":"paragraph","text":"<a claim resting on a source>","cites":[1]},
   {"type":"list","ordered":true,"items":["<step one>","<step two>"]},
-  {"type":"raw","html":"<the quiz and teach-back block composed above>"}
+  {"type":"raw","html":"<the quiz and teach-back block composed above>"},
+  {"type":"refs","items":[{"title":"<source name>","url":"<https URL>"}]}
 ]' | canon teach render --json
 ```
 
-A `heading`, a `paragraph` (`lede: true` for the dek), and a `list` cover the structural body. Reach for `raw` only where none of the three can carry the content, never as a shortcut around composing one, and give the quiz and teach-back block the array's trailing `raw` entry every time, since their fixed contract is not a components concern. Take the call's `html` field and write it between the header's close marker and the footnav's open marker, and nothing else anywhere in the file.
+A `heading`, a `paragraph` (`lede: true` for the dek, `cites` for a claim resting on a source), a `list`, and the one `refs` block the cites number into cover the structural body. Reach for `raw` only where none of those can carry the content, never as a shortcut around composing one, and give the quiz and teach-back block the array's last `raw` entry every time, followed only by `refs`, since their fixed contract is not a components concern. Take the call's `html` field and write it between the header's close marker and the footnav's open marker, and nothing else anywhere in the file.
 
 Report it rather than proceeding silently when the verb does not resolve, which is an installed CLI predating it, and never compose the lesson body by hand as a fallback. That is the state this section exists to end, and a target holds this skill body before it holds the verb, since a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes.
 

package/claude/skills/teach-workspace/references/lesson-craft.md

@@ -14,6 +14,7 @@ A workspace accumulates lessons over weeks. The learner reads them as one body o
 - `canon teach nav` embeds and re-embeds the shared stylesheet into every lesson on each run, so growing that stylesheet, by promoting anything used a second time into it, is the only step left by hand.
 - Keep the structural furniture identical across lessons: where the title sits, where the quiz sits, what a correct answer looks like
 - Do not restate styles inside a lesson. A local override is a decision the next lesson has to either copy or contradict.
+- Refer to another lesson in the same workspace as "lesson" followed by its four-digit number, such as "lesson 0003", and let `canon teach nav` turn the mention into a link and report a number naming no lesson. A hand-written link is the one form nav never checks.
 
 ## Typography
 
@@ -73,14 +74,17 @@ The stepper hides and shows and sets nothing else, so how a selected option look
 
 ## The block list
 
-`canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Four types, and every structural body composes from them:
+`canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Five types, and every structural body composes from them:
 
 - `{"type":"heading","level":1|2,"text":"<text>"}`: an `<h1>` or `<h2>`.
-- `{"type":"paragraph","text":"<text>","lede":true}`: a `<p>`, marked `lede` for the dek that opens the lesson.
+- `{"type":"paragraph","text":"<text>","lede":true,"cites":[1]}`: a `<p>`, marked `lede` for the dek that opens the lesson. `cites` adds a footnote marker per reference number after the text, and a lede takes none.
 - `{"type":"list","items":["<text>", ...],"ordered":true}`: a `<ul>` or, with `ordered`, an `<ol>`.
+- `{"type":"refs","items":[{"title":"<name>","url":"<https URL>","note":"<text>"}, ...]}`: the lesson's one reference list, numbered from 1 in item order. `url` and `note` are optional, and a `url` must be http or https.
 - `{"type":"raw","html":"<markup>"}`: the escape hatch, passed through unescaped.
 
-The quiz and the teach-back block above are the one case `raw` is always needed for, since their fixed contract is not a components concern. Give them the array's trailing entry rather than reaching for `raw` anywhere the other three could carry the content instead.
+The quiz and the teach-back block above are the one case `raw` is always needed for, since their fixed contract is not a components concern. Give them the array's last `raw` entry, followed only by `refs`, rather than reaching for `raw` anywhere the other types could carry the content instead.
+
+A claim resting on a source carries a `cites` number, and the source goes in the lesson's one `refs` block rather than into the sentence. Draw every reference from what `canon teach resource --read` recorded, never from a lead, since a lead is a source nobody opened. Render refuses a cite no reference resolves, so number the list before citing into it.
 
 ## Teach back
 

package/docs/agents/commands.md

@@ -48,7 +48,7 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 | `canon teach lesson`             | Resolve the numbered path, shared stylesheet, mission success lines, and one quiz option order per question for the next lesson, writing nothing (`--json`)                                                                                                                                                                  |
 | `canon teach stylesheet`         | Seed a workspace stylesheet from the design source, leaving an existing one alone without `--force` (`--json`)                                                                                                                                                                                                               |
 | `canon teach nav`                | Rewrite the teach-root listing, a workspace's contents page, each lesson's chrome from its four marker regions, and each reference page's rendered HTML sibling (`--json`)                                                                                                                                                   |
-| `canon teach render`             | Render a JSON block list (heading, paragraph, list, raw) from stdin to HTML through the shared components, refusing `bad-input` by block index (`--json`)                                                                                                                                                                    |
+| `canon teach render`             | Render a JSON block list (heading, paragraph with `cites`, list, refs, raw) from stdin to HTML through the shared components, refusing `bad-input` by block index (`--json`)                                                                                                                                                 |
 | `canon records validate`         | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                                                                                                                                                                                                 |
 | `canon records migrate`          | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                                                                                                                                                                                               |
 | `canon records ordinal`          | Report or claim the next ordinal `intake` and `groundwork` share, creating the folder atomically (`--claim`, `--json`)                                                                                                                                                                                                       |
@@ -65,6 +65,8 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 | `canon migrate scratch-evidence` | Move a folder under `.tmp/` that a durable record cites as evidence to a numbered `.canon/evidence/<nn>-<folder>/`, repointing every citation live or archived, reporting the plan without `--write` (`--root`, `--json`)                                                                                                    |
 | `canon migrate record-layout`    | Fold review receipts and the retired-entry archive under the memory pen, and move everything under `.canon/review/` that is not a review out to its own folder, repointing each citation that reaches into a moved folder or names a moved file, live or archived, reporting the plan without `--write` (`--root`, `--json`) |
 | `canon sessions list`            | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                                                                                                                                                                               |
+| `canon sessions export`          | Pack a session transcript, its side folder, and a manifest into one local gzip bundle, never uploading it (`--out`, `--json`)                                                                                                                                                                                                |
+| `canon sessions import`          | Place an exported session under the local project folder so `claude --resume` finds it, refusing to overwrite (`--root`, `--json`)                                                                                                                                                                                           |
 | `canon worktrees list`           | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                                                                                                                                                                                   |
 | `canon worktrees reclaim`        | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run` (`--json`)                                                                                                                                                                                                            |
 | `canon comments scan`            | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                                                                                                                                                                       |

package/docs/agents/index.md

@@ -40,7 +40,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Rule citations](rule-citations.md): Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the three forms a citation is written in, the shapes that look like citations and are not, the two classes where an absent path is correct, why the glob half reads one corpus, and why this one gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
-- [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, and what each session surface can see
+- [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and moving a session to another machine with export and import
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
 - [Standard success criteria](standards-audit.md): Reading the corpus against the success-criterion gate, the two headings it accepts, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets

package/docs/agents/sandbox.md

@@ -39,7 +39,7 @@ The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.to
 
 Omitting `--writes`, `--escapes`, or `--envelope` does not silently drop the assertion kinds that need them. Write scope, escape scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. Supplying `--escapes` without `--escapes-watched` reports the same way: a zero-escape result with no root confirmed watched is unmeasured rather than a pass. A verdict never reports `pass` with zero assertions.
 
-An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `canon/context/sandbox/overview.md` names what the watch reaches and what it cannot.
+An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `canon/context/sandbox/isolation.md` names what the watch reaches and what it cannot.
 
 An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
 

package/docs/agents/sessions.md

@@ -1,6 +1,6 @@
 ---
 title: Sessions
-description: Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, and what each session surface can see
+description: Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and moving a session to another machine with export and import
 ---
 
 # Sessions
@@ -117,6 +117,89 @@ Every row carries `statusUpdatedAt`, the stamp a client writes beside `status` a
 
 The dwell is what separates a status that resolves on its own from one that does not. `busy` and `idle` transition without help, so a long dwell there is ordinary. `waiting` does not: a session in that state is blocked on something outside itself, and a dwell that keeps growing past the ordinary span of a prompt is a session stalled rather than paused. `canon sessions list` renders the dwell beside the status at the coarsest unit that keeps it a whole number, and the JSON record carries both fields on every row.
 
+## Export
+
+`canon sessions export <id>` packs one session into a single gzip tarball so it can resume on another machine. The bundle holds the transcript, its side folder with every path kept, and a manifest.
+
+```bash
+canon sessions export <id>
+canon sessions export <id> --out ~/session.tar.gz --json
+```
+
+| Option         | Behavior                                                   |
+| -------------- | ---------------------------------------------------------- |
+| `--out <path>` | Write the bundle here rather than under the scratch folder |
+| `--json`       | Add a machine-readable record on stdout                    |
+
+Without `--out` the bundle lands at `.canon/tmp/session-export/<id>.tar.gz` under the main worktree root, which is gitignored and reclaimed by `canon records prune-tmp`. It writes locally and never uploads. A transcript holds whatever tool output passed through the session, credentials included where one was printed, so treat the bundle as private.
+
+Exit codes: `0` the bundle was written, `1` refused. The refusal carries a `reason` of `not-found`, where no project folder holds a transcript for the id, or `no-archive`, where the running Bun predates `Bun.Archive`.
+
+The lookup walks every folder under the configuration directory's `projects/`, so a transcript filed under any encoding is found. The transcript is read up to its last newline and never rewritten, so a session exporting itself mid-append drops at most the half line it was writing.
+
+Export runs no skill. Write a handoff with `canon:session-compact` and push it with `canon records push` first where one is wanted. The manifest reports whether a handoff exists and whether it reached the records history, and whatever calls the verb owns that order.
+
+### The manifest
+
+| Field              | Holds                                                                        |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `format`           | The bundle format version, `1`                                               |
+| `sessionId`        | The exported id                                                              |
+| `title`            | The last custom title the transcript recorded, or `null`                     |
+| `cwd`              | The last working directory the transcript recorded, or `null`                |
+| `root`             | The main worktree root of the repository the export read                     |
+| `origin`           | The `origin` remote reduced to `host/path`, or `null`                        |
+| `branch`, `head`   | The branch and commit of the checkout the export ran in                      |
+| `recordsHead`      | The records history `HEAD`, or `null` where no records history exists        |
+| `compacted`        | Whether the transcript carries a compaction boundary                         |
+| `live`             | Whether the id was live in the roster at export                              |
+| `handoff`          | The newest `.canon/compact/` note written since the session began, or `null` |
+| `handoffCommitted` | Whether that note is committed in the records history                        |
+| `recommend`        | `handoff` where a handoff exists, `transcript` otherwise                     |
+
+`recommend` prefers the handoff even though the transcript resumes in full. A resumed transcript carries the source machine's absolute paths into a session working somewhere else, and a handoff states the work without them.
+
+## Import
+
+`canon sessions import <bundle>` places an exported session under this machine's configuration directory so `claude` can resume it.
+
+```bash
+canon sessions import session.tar.gz
+canon sessions import session.tar.gz --root ~/repos/canon --json
+```
+
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--root <path>` | The repository to resume in. Defaults to the main worktree |
+| `--json`        | Add a machine-readable record on stdout                    |
+
+The transcript and side folder land under `projects/<encoding>/`, where the encoding is the root with every character outside `[A-Za-z0-9]` turned into a dash. Import writes new files only and never overwrites.
+
+Exit codes: `0` the session was placed, `1` refused. The refusal carries one of these reasons:
+
+- `not-a-bundle`: the file is no gzip tarball, carries no manifest at format `1`, or names a path outside its own session, such as one climbing out with `..` or an absolute one
+- `other-repository`: the local `origin` differs from the one the bundle recorded
+- `exists`: the target transcript or side folder is already there, or any other project folder already holds a transcript for the id, which `--resume <id>` could reach first
+- `live-here`: the id is live in the local roster, so a second copy would fork it
+- `write-failed`: a write failed partway for a reason other than a copy appearing, such as a bundle carrying a file where it also needs a folder
+- `no-archive`: the running Bun predates `Bun.Archive`
+
+A write that fails partway removes every file this run placed and every folder it created before refusing, so a retry of the same bundle does not refuse on its own leftovers. Any path it could not remove is named in the message. A copy that appears between the existence check and the write refuses as `exists` on the same terms.
+
+A placed session can still lag the source. The record's `behind` list carries `repository-behind` when this checkout lacks the exported `HEAD`, and `records-behind` when the records history lacks the exported records commit, which `canon records pull` brings. Neither refuses, since each has a remedy the reader runs before resuming.
+
+On success the record carries two `routes`. One runs `claude --resume <id>` from the root, and the other starts `claude` there and runs `/canon:session-resume` bare against the handoff.
+
+### What resume depends on
+
+Measured on `claude` 2.1.281 on 2026-09-24, `--resume <id>` found a copied transcript in any folder under `projects/` and chained the next turn onto its full history, run from a repository path the transcript never recorded. `--continue` found it only under the local encoding, which is why import derives the folder rather than keeping the source machine's.
+
+The encoding is inferred from observed folders rather than read from a published rule, and how a client shortens a path past its length limit was never observed. A client changing the rule leaves `--continue` looking elsewhere while `--resume <id>` still works. The framed report names the derived folder so a reader can compare.
+
+The side folder did not change the conversation sent. What it carries is `tool-results/`, which a `persisted-output` pointer in the transcript names by the source machine's absolute path, and `subagents/`, which holds background agent transcripts. On a machine whose path matches, those pointers resolve. On one whose path differs, they dangle.
+
+Resuming on the target while the source session keeps running forks the conversation, and nothing detects that across machines. The manifest's `live` field and the printed routes are the only warning.
+
 ## What the read depends on
 
 The records live under the Claude Code configuration directory, which the verb resolves from `CLAUDE_CONFIG_DIR` and falls back to `~/.claude`. Their location, their filenames, and the fields inside them are a client implementation detail rather than a published interface, so a client change can move them. The verb reports an absent registry as a refusal rather than as a machine running no sessions, which is what surfaces the move instead of burying it in an empty roster.

package/docs/agents/teach.md

@@ -141,7 +141,7 @@ The order is drawn here rather than instructed, and that is the point of the ver
 
 ## Render
 
-`canon teach render` renders a lesson body's structural blocks to HTML, through the three lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
+`canon teach render` renders a lesson body's structural blocks to HTML, through the four lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
 
 ```bash
 echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach render --json
@@ -151,9 +151,21 @@ echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach re
 | -------- | ---------------------------------------- |
 | `--json` | Emit a machine-readable record on stdout |
 
-It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the three components can express takes a `raw` block, carrying its own HTML verbatim and unescaped, which is the shape the quiz and the teach-back block travel in.
+It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, `refs`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the components can express takes a `raw` block, carrying its own HTML verbatim and unescaped, which is the shape the quiz and the teach-back block travel in.
 
-It refuses `bad-input` on empty stdin, on malformed JSON, on stdin that does not parse to an array, and on a block carrying an unrecognized `type` or a field of the wrong shape for its type, naming the block's index in the message.
+A citation takes two shapes. A `paragraph` carries an optional `cites` array of reference numbers, rendered as `sup.cite` markers after its text. The one `refs` block carries `items` of `{ title, url?, note? }`, rendered as `ol.refs` and numbered from 1, so cite `1` links to the first item.
+
+```json
+[
+  { "type": "paragraph", "text": "North is fixed.", "cites": [1] },
+  {
+    "type": "refs",
+    "items": [{ "title": "Compass manual", "url": "https://example.com" }]
+  }
+]
+```
+
+It refuses `bad-input` on empty stdin, on malformed JSON, on stdin that does not parse to an array, and on a block carrying an unrecognized `type` or a field of the wrong shape for its type, naming the block's index in the message. Citations add four refusals, each naming the offending block: a cite that resolves to no reference, `cites` on a lede paragraph, a second `refs` block, and a reference `url` that is not `http` or `https`.
 
 ## Nav
 
@@ -172,7 +184,9 @@ canon teach nav regular-expressions --json
 
 With no topic it rewrites every workspace. The teach-root listing is always rewritten regardless, since it reports on every workspace and a scoped run leaving it stale would be a second kind of drift this verb exists to end.
 
-A lesson carries its chrome as four marker pairs the authoring skill writes empty: `canon:teach:style`, `canon:teach:header`, `canon:teach:footnav`, and `canon:teach:scripts`. This verb splices each one from the current workspace state, embedding the toolkit's favicon, the shared stylesheet, and the script that settles the course panel before the page paints, rebuilding the course sidebar, the breadcrumb and jump menus, the prev/next footer nav, and the behavior scripts. It leaves the authored `<h1>`, lede, body, and quiz between the header and the footnav as written, and wraps them in `<main>` when the lesson holds none, since the column width hangs off that element. A lesson that already carries a `<main>` keeps its own.
+A lesson carries its chrome as four marker pairs the authoring skill writes empty: `canon:teach:style`, `canon:teach:header`, `canon:teach:footnav`, and `canon:teach:scripts`. This verb splices each one from the current workspace state, embedding the toolkit's favicon, the shared stylesheet, and the script that settles the course panel before the page paints, rebuilding the course sidebar, the breadcrumb and jump menus, the prev/next footer nav, and the behavior scripts. It leaves the authored `<h1>`, lede, body, and quiz between the header and the footnav as written, with two exceptions. It wraps them in `<main>` when the lesson holds none, since the column width hangs off that element, and a lesson that already carries a `<main>` keeps its own.
+
+It also links each "lesson NNNN" mention in that region to the lesson file in the same workspace carrying that number, skipping text inside `a`, `code`, `pre`, `script`, `style`, `label`, `summary`, and comments. A link the verb writes carries `data-lesson-ref`, and it is the only kind the verb rewrites: every run points one at the current filename for its number, or unwraps it to plain text once that number names no lesson. A link an author wrote is never touched.
 
 Every workspace label in that chrome, being the breadcrumb, the sidebar heading, the workspace switcher, and the root listing's row, reads the mission's `title` and falls back to the folder topic in sentence case where the mission names none.
 
@@ -184,6 +198,8 @@ That seeding fires on the absent file alone, so a workspace already holding a `c
 
 A lesson missing one of the four marker pairs is refused by name rather than rewritten, and every other lesson in the run still rewrites. The record's `skipped` list carries the refused files and which marker each is missing.
 
+A mention whose number names no lesson in its workspace stays plain text and lands in the record's `unresolved` list, one `{ file, lesson }` entry per distinct number per lesson, with `file` relative to the root the way a `skipped` entry is. The lesson still rewrites and counts toward `lessons`, and the exit stays 0. A mention of the lesson's own number stays plain and is not reported, and a refused lesson reports nothing.
+
 The `style` region carries the quiz stepper after the workspace stylesheet, for every lesson but the one shape named three paragraphs down, so it wins the cascade at equal specificity and reaches a workspace seeded before it existed. The stepper is CSS over the radio inputs a quiz is written from: it hides every question that follows one holding no checked input, and hides a question's feedback until that question does. The general sibling combinator is what keeps that from depending on the markup contract holding, since it selects the same questions as the adjacent one for a quiz written correctly and goes on gating when anything sits between two of them, where the adjacent one matches nothing and shows them all at once. Gating there rather than in a script is what keeps a later stem from answering an earlier question with nothing to bind, and the whole block sits inside `@supports selector(:has(*))`, so an engine without `:has()` renders every question rather than a stepper showing nothing. Feedback there follows the workspace stylesheet, shown by one that says nothing about `.fb` and hidden by one grown under the retired script.
 
 The block hides and shows and sets nothing else, which leaves a workspace's own layout for a question and its own appearance for an option and a feedback panel. The one value it names is `display: block` on revealed feedback, since every stylesheet grown under the retired script carries `.fb { display: none }` and nothing adds the class that used to reveal it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.115.0",
+  "version": "4.116.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/sessions.ts

@@ -10,6 +10,11 @@ import {
   type SessionReport,
   selfOf,
 } from '@/sessions/resolve'
+import {
+  type Behind,
+  exportSession,
+  importSession,
+} from '@/sessions/transfer/bundle'
 import {
   intro,
   logInfo,
@@ -19,6 +24,7 @@ import {
   pipeOutput,
   plural,
 } from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
 
 interface ListCommandOptions {
   readonly json?: boolean
@@ -144,6 +150,222 @@ export function register(program: Command): void {
     .action(async (opts: ListCommandOptions) => {
       process.exitCode = await runList(opts)
     })
+
+  sessions
+    .command('export')
+    .description(
+      'Pack a session transcript, its side folder, and a manifest into one local bundle',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .argument('<id>', 'The sessionId to export')
+    .option(
+      '--out <path>',
+      'Write the bundle here rather than under .canon/tmp/session-export/',
+    )
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the bundle was written',
+        '  1  refused, with the reason on stderr and in the record',
+        '',
+        'The bundle is a gzip tarball on local disk and is never uploaded. It',
+        'holds whatever tool output passed through the session, so treat it as',
+        'private. Export runs no skill: write and push a handoff first where one',
+        'is wanted, and the manifest reports whether one was found and pushed.',
+        '',
+        'Refusal reasons: "not-found" (no transcript carries the id) and',
+        '"no-archive" (this Bun has no Bun.Archive).',
+        '',
+        'Examples:',
+        '  canon sessions export <id>',
+        '  canon sessions export <id> --out ~/session.tar.gz --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (id: string, opts: ExportCommandOptions) => {
+      process.exitCode = await runExport(id, opts)
+    })
+
+  sessions
+    .command('import')
+    .description(
+      'Place an exported session under this machine so claude can resume it',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .argument('<bundle>', 'The bundle an export wrote')
+    .option(
+      '--root <path>',
+      'The repository to resume in. Defaults to the main worktree',
+    )
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the session was placed, with any lag reported in "behind"',
+        '  1  refused, with the reason on stderr and in the record',
+        '',
+        'Refusal reasons: "not-a-bundle", "other-repository" (the origin',
+        'differs), "exists" (the transcript or side folder is already there),',
+        '"live-here" (the id is live on this machine), "write-failed" (a',
+        'write failed partway), and "no-archive". A failure partway removes',
+        'every file this run placed, and names any it could not remove.',
+        '',
+        '"behind" lists "repository-behind" when this checkout lacks the',
+        'exported HEAD, and "records-behind" when the records history lacks',
+        'the exported records commit, which canon records pull brings.',
+        '',
+        'Examples:',
+        '  canon sessions import session.tar.gz',
+        '  canon sessions import session.tar.gz --root ~/repos/canon --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (bundle: string, opts: ImportCommandOptions) => {
+      process.exitCode = await runImport(bundle, opts)
+    })
+}
+
+interface ExportCommandOptions {
+  readonly out?: string
+  readonly json?: boolean
+}
+
+interface ImportCommandOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+/**
+ * Whether a session id is live in the local roster. An unreadable roster
+ * answers false, since the roster is advisory here and the manifest says so.
+ */
+async function isLiveHere(id: string): Promise<boolean> {
+  const report = await resolveSessions()
+  return (
+    report.kind === 'resolved' &&
+    report.sessions.some((session) => session.sessionId === id)
+  )
+}
+
+function writeRecord(json: boolean | undefined, record: object): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}
+
+async function runExport(
+  id: string,
+  opts: ExportCommandOptions,
+): Promise<number> {
+  const outcome = await exportSession({
+    id,
+    out: opts.out ? resolve(opts.out) : undefined,
+    isLive: isLiveHere,
+  })
+
+  intro('canon sessions export')
+
+  if (!outcome.ok) {
+    logStep('Refused')
+    logWarn(outcome.message)
+    outro()
+    writeRecord(opts.json, { ...outcome, sessionId: id })
+    return 1
+  }
+
+  const { manifest } = outcome
+  logStep('Bundle')
+  logInfo(`Wrote ${outcome.path}`)
+  logInfo(`${plural(outcome.files.length, 'side file')} beside the transcript`)
+
+  if (manifest.live) {
+    logWarn(
+      'The session is live, so the copy stops at its last whole line and resuming elsewhere forks it.',
+    )
+  }
+
+  logStep('Handoff')
+  if (manifest.handoff === null) {
+    logInfo(
+      'No compact note since the session began, so resume the transcript.',
+    )
+  } else if (manifest.handoffCommitted) {
+    logInfo(`${manifest.handoff} is in the records history. Prefer it.`)
+  } else {
+    logWarn(
+      `${manifest.handoff} is not in the records history yet. Run canon records push so the other machine can pull it.`,
+    )
+  }
+  outro()
+
+  writeRecord(opts.json, {
+    ok: true,
+    path: outcome.path,
+    sessionId: id,
+    files: outcome.files,
+    manifest,
+  })
+  return 0
+}
+
+const BEHIND_REMEDIES: Record<Behind, string> = {
+  'repository-behind':
+    'This checkout lacks the exported HEAD. Fetch and check out the branch before resuming.',
+  'records-behind':
+    'The records history lacks the exported commit. Run canon records pull to bring the handoff.',
+}
+
+async function runImport(
+  bundle: string,
+  opts: ImportCommandOptions,
+): Promise<number> {
+  const root = opts.root ? resolve(opts.root) : await mainWorktreeRoot()
+  const outcome = await importSession({
+    bundle: resolve(bundle),
+    root,
+    isLive: isLiveHere,
+  })
+
+  intro('canon sessions import')
+
+  if (!outcome.ok) {
+    logStep('Refused')
+    logWarn(outcome.message)
+    outro()
+    writeRecord(opts.json, outcome)
+    return 1
+  }
+
+  logStep('Placed')
+  logInfo(outcome.transcript)
+  logInfo(
+    `Folder ${outcome.folder}, derived from ${root}. --continue looks there, and --resume finds the id in any folder.`,
+  )
+  for (const lag of outcome.behind) logWarn(BEHIND_REMEDIES[lag])
+
+  logStep('Resume')
+  logInfo(
+    outcome.manifest.recommend === 'handoff'
+      ? `Recommended: the handoff at ${outcome.manifest.handoff}, since the transcript carries the source machine's absolute paths.`
+      : 'Recommended: the transcript, since no handoff was written since the session began.',
+  )
+  for (const route of outcome.routes) logInfo(route)
+  outro()
+
+  writeRecord(opts.json, {
+    ok: true,
+    sessionId: outcome.manifest.sessionId,
+    folder: outcome.folder,
+    transcript: outcome.transcript,
+    files: outcome.files,
+    behind: outcome.behind,
+    routes: outcome.routes,
+    manifest: outcome.manifest,
+  })
+  return 0
 }
 
 async function runList(opts: ListCommandOptions): Promise<number> {

package/src/commands/teach.ts

@@ -393,9 +393,16 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'Reads a JSON array of blocks from stdin, each a heading, paragraph,',
-        'list, or raw block, and renders it through the same components the',
-        'fixture lesson is generated from. Content the three cannot express',
-        'takes type raw, carrying its own html verbatim, unescaped.',
+        'list, refs, or raw block, and renders it through the same components',
+        'the fixture lesson is generated from. Content the structured blocks',
+        'cannot express takes type raw, carrying its own html verbatim,',
+        'unescaped.',
+        '',
+        'A paragraph takes an optional cites array of reference numbers,',
+        'rendered as footnote markers after its text. The one refs block',
+        'lists { title, url?, note? } items numbered from 1, and a cite that',
+        'resolves to no item, a cite on a lede, or a second refs block is',
+        'refused. A url must be http or https.',
         '',
         'Takes no topic and no --root: the verb is a stateless transform,',
         'reading nothing off a workspace on disk.',
@@ -799,6 +806,7 @@ function reportNav(
         lessons: outcome.lessons,
         reference: outcome.reference,
         skipped: outcome.skipped,
+        unresolved: outcome.unresolved,
       })}\n`,
     )
     return 0
@@ -821,6 +829,13 @@ function reportNav(
     }
   }
 
+  if (outcome.unresolved.length > 0) {
+    logStep('Lesson references naming no lesson')
+    for (const reference of outcome.unresolved) {
+      logWarn(`${reference.file}: lesson ${reference.lesson}`)
+    }
+  }
+
   outro()
   return 0
 }

package/src/records/backup.ts

@@ -318,7 +318,7 @@ function failed(action: string, result: GitResult): BackupRefused {
  * as written passes a records origin that publishes the payload through the
  * other protocol.
  */
-function remoteIdentity(url: string): string {
+export function remoteIdentity(url: string): string {
   return url
     .trim()
     .toLowerCase()

package/src/sandbox/census.ts

@@ -69,7 +69,7 @@ export function listSkills(root: string): string[] {
 /**
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
- * `<category>-<command>` is the rule `canon/context/sandbox/coverage.md` states, and it
+ * `<category>-<command>` is the rule `canon/context/sandbox/coverage/census.md` states, and it
  * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/target-setup.sh` drives the `target-setup` skill, not a `claude-target-setup` that
  * does not exist. Stating one spelling and shipping two is what let the audit

package/src/sessions/registry.ts

@@ -48,19 +48,23 @@ export interface SessionRecord {
 }
 
 /**
- * Resolves the folder holding one file per session.
+ * Resolves the client's configuration directory, which holds both the session
+ * registry and the projects folder a transcript lives in.
  *
  * `CLAUDE_CONFIG_DIR` comes first because a client honouring it writes its
  * records nowhere near the home directory, and a read that ignored it would
  * report an empty roster on a machine running sessions.
  */
-export function registryDir(): string {
+export function claudeConfigDir(): string {
   const configured = process.env.CLAUDE_CONFIG_DIR
-  const base =
-    configured && configured.length > 0
-      ? configured
-      : join(homedir(), '.claude')
-  return join(base, 'sessions')
+  return configured && configured.length > 0
+    ? configured
+    : join(homedir(), '.claude')
+}
+
+/** Resolves the folder holding one file per session. */
+export function registryDir(): string {
+  return join(claudeConfigDir(), 'sessions')
 }
 
 /**