@erclx/canon 5.53.0 → 5.55.0

package/claude/skills/plan-groundwork/SKILL.md

@@ -37,7 +37,7 @@ Write only inside `.canon/groundwork/<nn>-<slug>/`. A feature plan, source chang
 
 What a spike produces stays inside the track, under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches only top-level entries, so a nested folder cannot be mistaken for a track, and scratch holds only what can be deleted without loss.
 
-A `pick-by-eye` run invoked from inside a live track follows its own branch for this. It writes its renders to `evidence/` here, and drafts its candidates as canvas pages under `.canon/canvas/` that its close deletes.
+A `pick-by-eye` run invoked from inside a live track follows its own branch for this. It writes its renders to `evidence/` here, and drafts its candidates as pages on the Frameboard board at `.canon/canvas/` that its close deletes.
 
 ### Reading and backing
 

package/claude/skills/target-check/SKILL.md

@@ -17,7 +17,7 @@ Six domains carry the report. Five answer from a verb that already exists and th
 - No `.claude/` directory at the working root: stop. `❌ No .claude/ here, so nothing is installed to check. Run canon init first.`
 - A `claude/skills/` folder at the root, no leading dot: stop. `❌ This is the toolkit itself rather than a target. Ask the orchestrator for a worker per repository to take a change out to the targets.`
   - A target receives skills at `.claude/skills/` and authors none, so the spelling without the dot separates the source from what it installs into
-- Run every command under `CANON_NON_INTERACTIVE=1` and prompt at no point, since every caller is a dispatched worker with nobody to answer
+- Prompt at no point, since every caller is a dispatched worker with nobody to answer. A call with no terminal on stdin already runs headless, so no command takes a prefix.
 - Branch on each record's own fields rather than on an exit status. A shell function wrapping `canon` can report every refusal as success.
 
 ## Step 1: read the reports
@@ -25,25 +25,23 @@ Six domains carry the report. Five answer from a verb that already exists and th
 Run these from the target root, in parallel:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon sync --check . --json
-CANON_NON_INTERACTIVE=1 canon context audit --json
+canon sync --check . --json
+canon context audit --json
 ```
 
 The first answers five domains from one read, being `skew`, `domains`, `seeds`, `tooling`, and the layout fields `unmigrated`, `superseded`, `unmovedSurfaces`, and `reverse`. The second deepens a domain that first read only counts.
 
-Then run `CANON_NON_INTERACTIVE=1 canon records validate <kind> --json` once per record folder the target carries, taking `<kind>` from what is present under the record root rather than from a list held here.
+Then run `canon records validate <kind> --json` once per record folder the target carries, taking `<kind>` from what is present under the record root rather than from a list held here.
 
 ### The tooling read takes a stack, always
 
 The tooling comparison runs last, because it needs a value the first read returns. Take `<stack>` from the first name in the report's `tooling.chain`, which records the stack nearest the target, and pass it:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon tooling sync --check <stack>
+canon tooling sync --check <stack>
 ```
 
-Refuse the domain and report it unread when `chain` names nothing, rather than running the command bare. A bare call reaches the stack prompt, which the non-interactive variable resolves to the catalog's first option instead of refusing.
-
-Every target would then be compared against whichever stack sorts first, on every run, and the drift reported would be an artifact of the wrong comparison rather than anything the target did.
+Refuse the domain and report it unread when `chain` names nothing, rather than running the command bare. A bare call reaches the stack prompt, which refuses a headless caller, so it would report nothing about the domain.
 
 ### Domains come from the report
 

package/claude/skills/target-check/references/domains.md

@@ -72,10 +72,7 @@ Read the `tooling` block off the report first, because the comparison command ne
 
 ### The comparison
 
-On a measured report, take `<stack>` from the first name in `chain` and run `canon tooling sync --check <stack>`. Never run it bare.
-
-- Omitting the stack reaches a prompt the non-interactive variable resolves to the catalog's first entry rather than refusing
-- That compares the target against a stack it does not use and reports the difference as drift
+On a measured report, take `<stack>` from the first name in `chain` and run `canon tooling sync --check <stack>`. Never run it bare, since omitting the stack reaches a prompt that refuses a headless caller and compares nothing.
 
 ### Verdicts
 

package/claude/skills/target-setup/SKILL.md

@@ -33,9 +33,9 @@ rather than a step within it, so the full chain never runs it separately.
 
 ## Non-interactive path
 
-Every phase runs under `CANON_NON_INTERACTIVE=1` with no TTY. Three phases
-otherwise pause, and each takes an argument that answers its prompt ahead of
-time:
+Every phase runs headless with no prefix, since a call with no terminal on
+stdin is already headless. Three phases otherwise pause, and each takes an
+argument that answers its prompt ahead of time:
 
 | Phase               | Pauses to                                  | Answered ahead by                                          | With neither and no TTY                               |
 | ------------------- | ------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------- |
@@ -91,7 +91,7 @@ target project's current directory. Do not cd into the toolkit source tree. The
 Step 1: `canon init` installs base tooling, claude seeds, and governance rules.
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon init \
+canon init \
   --stack <stack> \
   --add <rules> \
   <target>
@@ -106,7 +106,7 @@ Step 2: `canon tooling sync <tooling-stack> --write` installs stack deps, script
 - A fresh target has nothing to lose, so pass `--write` directly rather than reading a report first
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon tooling sync <tooling-stack> <target> --write
+canon tooling sync <tooling-stack> <target> --write
 ```
 
 ### Monorepo with multiple language roots
@@ -114,8 +114,8 @@ CANON_NON_INTERACTIVE=1 canon tooling sync <tooling-stack> <target> --write
 Run `canon init` once at the repo root so `base` (husky, oxfmt, commitlint, CI) lands once, then sync each subtree with `--skip base`. Take the subtree commands from the preview's per-root rows rather than picking folders by hand.
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon tooling sync vite-react ./frontend --skip base --write
-CANON_NON_INTERACTIVE=1 canon tooling sync python ./backend --skip base --write
+canon tooling sync vite-react ./frontend --skip base --write
+canon tooling sync python ./backend --skip base --write
 ```
 
 - Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break
@@ -139,7 +139,7 @@ Resolve exactly as the detect reference states, confirm the proposed extras
 there, then run:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon gov install <stack> --add <extras> <target>
+canon gov install <stack> --add <extras> <target>
 ```
 
 Report the rule count installed, the target path, and any rules that failed to

package/claude/skills/target-update/SKILL.md

@@ -24,7 +24,7 @@ Stop with the line beside each state.
 
 Then hold two rules for every verb this body runs.
 
-- Run it under `CANON_NON_INTERACTIVE=1` from the target root
+- Run it from the target root with no prefix, since a call with no terminal on stdin already runs headless
 - Branch on its record's fields rather than its exit, which a shell function wrapping `canon` can flatten
 
 ## Step 1: bring the binary and plugin forward
@@ -38,12 +38,12 @@ Both write to the machine rather than the target, and the preview needs the verb
 Run these in parallel from the target root:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon changelog --json
-CANON_NON_INTERACTIVE=1 canon migrate status --json
-CANON_NON_INTERACTIVE=1 canon sync --check . --json
+canon changelog --json
+canon migrate status --json
+canon sync --check . --json
 ```
 
-Then take `<stack>` from the first name in the report's `tooling.chain` and run `canon tooling diff <stack> . --json`. Never run it bare, since the stack prompt resolves to the catalog's first entry under the non-interactive variable. Report tooling unmeasured when `tooling.measured` is false or `chain` names nothing.
+Then take `<stack>` from the first name in the report's `tooling.chain` and run `canon tooling diff <stack> . --json`. Never run it bare, since the stack prompt refuses a headless caller. Report tooling unmeasured when `tooling.measured` is false or `chain` names nothing.
 
 ### When a read refuses
 

package/claude/skills/teach-craft/REQUIREMENT.md

@@ -17,6 +17,7 @@ Its quizzes leak the answer through option length or position, and nothing tests
 - Ask the learner's starting point and read the subject from sources, saying which claims rest on recall
 - State quiz design that leaks no answer, and pair a quiz with a teach-back
 - Hold that the wrong answer itself is what the next session places from
+- Cite an opened source in the ledger for every kept rule, or label it house judgment with the reason it stays, then close on excuses, red flags, and a checklist
 
 ## Must not
 
@@ -27,4 +28,3 @@ Its quizzes leak the answer through option length or position, and nothing tests
 ## Out of scope
 
 - Where a lesson is stored or how it renders, which belongs to whatever surface the session writes to
-- A cited source ledger for the practice family, which is a follow-on task

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

@@ -7,7 +7,7 @@ metadata:
 
 # Teach craft
 
-A session asked to teach explains, and a smooth explanation reads as a lesson learned. It is fluency, which decays within days. This skill carries what turns teaching into retention: test before telling, space the returns, and grade only what the learner produced unaided.
+A session asked to teach explains, and a smooth explanation reads as a lesson learned. It is fluency, which does not survive a delay. This skill carries what turns teaching into retention: test before telling, space the returns, and grade only what the learner produced unaided.
 
 It produces nothing of its own. The lesson lands wherever the session already writes, being the conversation, a file, or a page.
 
@@ -18,6 +18,8 @@ It produces nothing of its own. The lesson lands wherever the session already wr
 
 Read `pedagogy.md` before picking what to teach next, and `lesson-craft.md` before writing a quiz or a lesson.
 
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records the research each rule rests on, the passage relied on, and which rules stand as house judgment.
+
 ## Before teaching
 
 - Ask what the learner already knows rather than assuming it. Difficulty with no floor under it teaches nobody.
@@ -37,3 +39,32 @@ Read `pedagogy.md` before picking what to teach next, and `lesson-craft.md` befo
 | They followed the explanation, so move on | Following is fluency. Advance on a retrieval the learner passed unaided.                     |
 | Review the last lesson before testing it  | Review rebuilds the fluency the test would have measured. Test first, then fill what missed. |
 | The answer is obvious from the options    | Then the distractors are not misconceptions anyone holds. Rewrite them.                      |
+
+## Red flags
+
+- You are about to explain a topic and the learner has not yet tried to answer anything on it.
+- The learner said it makes sense and you are moving to the next topic.
+- A returning learner's session opens on new material.
+
+### Quizzes and records
+
+These flags fire on what the session has written.
+
+- The correct options in a quiz are the longest ones, or sit in the same slot.
+- You are writing a claim about the subject with no source open.
+- The learning record you are about to write holds a score and no wrong answer.
+
+## Before handing over
+
+Check each line against the lesson and the record the session produced.
+
+- Every advance followed a retrieval the learner passed unaided, not a smooth explanation.
+- The lesson carries a quiz and a teach-back with a named audience.
+- Every quiz keeps its options to one length and rotates the correct slot by question number.
+- Every claim names the source it was read from, or says it rests on recall.
+- The learning record names each wrong answer and the next revisit from the ladder.
+
+## What this delegates
+
+- Finding and opening the sources a lesson is read from: `search-craft`
+- Where a lesson is stored and how it renders, which belongs to the surface the session writes to

package/claude/skills/teach-craft/references/adopted.md

@@ -0,0 +1,113 @@
+---
+title: Adopted and declined
+description: Which learning-science sources this skill's rules rest on, the passage each one was taken from, what was declined, and which rules stand as house judgment with no opened source behind them
+---
+
+# Adopted and declined
+
+The field is learning science and cognitive psychology, with educational measurement for quiz construction. Every source below was opened, the papers through the PubMed API and the practice guide as a PDF. Each entry quotes the passage relied on, and a later session extends this file rather than re-arguing an item settled here.
+
+## Contents
+
+- [Adopted](#adopted)
+- [Declined](#declined)
+- [House judgment](#house-judgment)
+
+## Adopted
+
+### Retrieval over restudy, and fluency against retention
+
+[Roediger and Karpicke 2006, Test-enhanced learning](https://pubmed.ncbi.nlm.nih.gov/16507066/) backs testing before reviewing, and the rule that confidence says nothing about retention.
+
+- Passage: "prior testing produced substantially greater retention than studying, even though repeated studying increased students' confidence in their ability to remember the material"
+- The same abstract: "When the final test was given after 5 min, repeated studying improved recall relative to repeated testing"
+- Adopted in `pedagogy.md` as the fluency and retrieval sections, and in the body's excuses table
+
+### Failing an attempt before the answer
+
+[Kornell, Hays and Bjork 2009, Unsuccessful retrieval attempts enhance subsequent learning](https://pubmed.ncbi.nlm.nih.gov/19586265/) backs asking before telling and letting the learner fail first.
+
+- Passage: in the test condition "participants attempted to answer the question before being shown the answer", and "Unsuccessful retrieval attempts enhanced learning with both types of materials"
+- The read-only condition it beat is "the question and answer were presented together"
+- Adopted as the rule to open on the question, and in `lesson-craft.md` as feedback after the attempt rather than beside the question
+
+### Spacing, and the gap growing with the interval
+
+[Cepeda et al. 2006, Distributed practice in verbal recall tasks](https://pubmed.ncbi.nlm.nih.gov/16719566/) backs spacing, and the best gap growing with how long the material has to last.
+
+- Passage: "the ISI producing maximal retention increased as retention interval increased"
+- Adopted as the spacing section's principle. It names no schedule and reports no result for expanding gaps, so the ladder is house judgment.
+
+[Pashler et al. 2007, IES practice guide NCER 2007-2004](https://ies.ed.gov/ncee/wwc/Docs/PracticeGuide/20072004.pdf) backs the same at classroom scale, and its panel rates the evidence moderate.
+
+- Passage: key concepts seen on at least two occasions, "separated by a period of several weeks to several months"
+- Adopted as the rule to revisit once forgetting has begun rather than while the material is fresh
+
+### Quizzing at every phase
+
+The same IES guide, in Recommendation 5, backs carrying a quiz in every lesson. Its panel rates quizzes that re-expose key content as strong evidence and pre-questions as low.
+
+- Passage: "Use quizzing with active retrieval of information at all phases of the learning process"
+- Adopted as the rule to carry a quiz. Opening on a question rests on Kornell, Hays and Bjork above, with this as weak support.
+
+### Worked examples while acquiring
+
+The IES guide's Recommendation 2 backs worked examples for a learner taking on a procedure, rated moderate.
+
+- Passage: students "learn more by alternating between studying examples of worked-out problem solutions and solving similar problems on their own"
+- Adopted as the clause introducing new material through worked examples. The wider split between skill and knowledge is house judgment below.
+
+### Interleaving exemplars
+
+[Kornell and Bjork 2008, Learning concepts and categories](https://pubmed.ncbi.nlm.nih.gov/18578849/) backs mixing related items within a session, and names the fluency trap of blocked practice.
+
+- Passage: paintings "presented consecutively (massed) or interleaved with other artists' paintings (spaced)", and induction profited from the interleaved order
+- The same abstract: "Participants rated massing as more effective than spacing"
+- Adopted as the claim that blocked practice feels better and teaches less. The study mixes exemplars of categories, so mixing topics is an extension, recorded below.
+
+### Feedback on a quiz
+
+[Butler and Roediger 2008, Feedback and multiple-choice testing](https://pubmed.ncbi.nlm.nih.gov/18491500/) backs giving feedback on a multiple-choice quiz.
+
+- Passage: "The selection of lures can lead students to acquire false knowledge", and feedback "reduced the proportion of intrusions"
+- Adopted as the rule to write feedback for every question. It tests feedback against none, not where distractors come from or how feedback explains them.
+- It found immediate and delayed feedback both help, so the timing rule rests on Kornell, Hays and Bjork instead
+
+### The teach-back
+
+[Nestojko et al. 2014, Expecting to teach](https://pubmed.ncbi.nlm.nih.gov/24845756/) backs asking the learner to explain to an audience.
+
+- Passage: "Participants expecting to teach produced more complete and better organized free recall of the passage"
+- Adopted as the teach-back block and its named audience
+- The participants expected to teach and never taught. The finding backs framing the ask as teaching, not a gain from the explanation itself.
+
+## Declined
+
+### A fixed schedule from the literature
+
+Cepeda's synthesis and the IES guide each tie the best gap to how long the material has to last, and neither names a sequence of days. Neither is cited for the ladder, so the ladder does not read as sourced.
+
+### Dunlosky et al. 2013
+
+[Improving students' learning](https://journals.sagepub.com/doi/10.1177/1529100612453266) refused with a 403. It stays a lead, never cited, and is the first source to open when extending the retrieval or spacing rules.
+
+### Leads not opened
+
+Bjork on desirable difficulties, Vygotsky on the zone of proximal development, and Haladyna, Downing and Rodriguez 2002 on item writing were each searched for and not opened. The item-writing review refused with a 403 at the publisher, and Crossref carries no abstract for it. Each rule it would back is labeled below.
+
+## House judgment
+
+These rules stay with no opened source behind them, each for the reason given.
+
+- **The review ladder.** The 1, 3, 7, 16, and 35 day rungs, and moving a rung on each hit or miss, are a house schedule. An author told to widen a gap settles on whatever feels right.
+- **Forgetting as the mechanism of spacing.** It explains why the gap matters, and no opened source tests it.
+- **Production over selection, and no cue in the question.** Both studies above compare testing with restudy, and neither compares a recognition test.
+- **Misconception distractors, explained one by one.** A distractor nobody holds removes itself, and Butler tests only feedback against none.
+- **Interleaving topics rather than exemplars.** This extends Kornell and Bjork and the IES worked-example finding. It stays because working out which approach a problem calls for carries over.
+- **Never interleaving an unseen topic.** Telling two things apart needs something on each side.
+- **Where difficulty helps and hurts.** The split stays because it changes what a lesson withholds. Kornell, Hays and Bjork back difficulty at retrieval, and IES backs worked examples while acquiring.
+- **The zone of proximal development.** Placing the learner just past what they can do unaided is how a session picks the next step from the learning record.
+- **Equal option length.** A longer option reads as the considered one, and a session can check the rule by counting.
+- **Rotating the correct slot.** An author varying position by judgment settles on the first slot.
+- **Restraint and what makes a lesson worth returning to.** Both are editorial judgment about a page rather than claims about memory.
+- **The sourcing ladder.** It is this toolkit's rule for what a lesson cites, not a finding about learning.

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

@@ -5,7 +5,7 @@ description: Restraint, quiz design, teach back, and what makes a lesson worth r
 
 # Lesson craft reference
 
-Judgment rather than shape. This file covers what makes a lesson worth opening twice, whatever surface it renders on.
+Judgment rather than shape. This file covers what makes a lesson worth opening twice, whatever surface it renders on. Each section names its research or says it is house judgment, and `adopted.md` beside this file carries the passages.
 
 ## Contents
 
@@ -23,6 +23,8 @@ Every element competes with the material for attention.
 - Do not animate anything the learner did not trigger
 - Prefer whitespace over rules and boxes to separate sections
 
+This section is house judgment, an editorial call about a page rather than a claim about memory.
+
 ## Quiz design
 
 The quiz is the retrieval, so a leak in its construction turns it into a reading test.
@@ -35,18 +37,24 @@ The quiz is the retrieval, so a leak in its construction turns it into a reading
 
 One feedback block reads as an explanation where a block per option reads as four verdicts, and only the explanation names what separates a wrong option from the answer. Name the correct option in the feedback text, since it is what a learner reads to find out whether they were right.
 
+Butler and Roediger 2008 back giving feedback on a multiple-choice quiz, since its lures can teach false knowledge. Kornell, Hays and Bjork 2009 back giving it after the attempt. Misconception distractors, explaining each one, equal option length, and the slot rotation are house judgment.
+
 ## Teach back
 
-A quiz is recognition and a teach-back is production, which is the form retrieval practice prefers. Carry both: the quiz places the learner against options someone could hold, and the teach-back is where the learner finds out what they cannot say without help.
+A quiz is recognition and a teach-back is production, which this skill prefers as house judgment. Carry both: the quiz places the learner against options someone could hold, and the teach-back is where the learner finds out what they cannot say without help.
 
 - Ask for an explanation to a named audience rather than for an answer. Telling a non-programmer why a lazy quantifier is not an optional one has a floor, and "explain lazy quantifiers" has none.
 - Ask about the thing the lesson was for, not a detail beside it. A teach-back on a footnote tests attention rather than the material.
 - Carry a self-check, hidden until the learner opens it, listing what a complete explanation covers. A learner with no session in the room otherwise cannot grade the ask, and hidden leaks nothing.
 - Write the self-check as what the explanation has to cover rather than as the explanation itself. A model answer is read instead of produced, which turns the block back into reading.
 
+Nestojko et al. 2014 back framing the ask as teaching a named audience. The self-check rules are house judgment.
+
 ## What makes a lesson worth returning to
 
 - The worked example is complete. A learner returning for the example finds the whole thing rather than a fragment they have to reconstruct.
 - The lesson states what it assumes. A returning reader can tell in one line whether they are in the right place.
 - The hard part is named as the hard part. Material that flattens everything to one difficulty gives a returning reader nothing to navigate by.
 - Nothing depends on the session it was written in. A lesson referring to what was discussed is unreadable a week later.
+
+This section is house judgment, like restraint above.

package/claude/skills/teach-craft/references/pedagogy.md

@@ -7,15 +7,29 @@ description: Fluency against storage strength, retrieval practice, spacing, inte
 
 The rules a lesson is built from. Read this before picking what to teach next.
 
+Each section names the research behind it or says it is house judgment. The passage each source was taken from, and the reason each house rule stays, sit in `adopted.md` beside this file.
+
+## Contents
+
+- [Fluency is not storage strength](#fluency-is-not-storage-strength)
+- [Retrieval practice](#retrieval-practice)
+- [Spacing](#spacing)
+- [Interleaving](#interleaving)
+- [The zone of proximal development](#the-zone-of-proximal-development)
+- [Where difficulty helps and where it hurts](#where-difficulty-helps-and-where-it-hurts)
+- [Sourcing](#sourcing)
+
 ## Fluency is not storage strength
 
-A learner who follows an explanation smoothly has demonstrated that the explanation was clear. That is fluency, and it decays within days. Storage strength is whether the material can be retrieved later without the explanation present, and the two move independently.
+A learner who follows an explanation smoothly has demonstrated that the explanation was clear. That is fluency, and it does not last. Storage strength is whether the material can be retrieved later without the explanation present, and the two move independently.
 
 The practical consequence is that a lesson cannot report its own success. Only a later retrieval can, which is why the learning record exists and why every session opens by testing the last one rather than by reviewing it.
 
 - Treat a learner's confidence as evidence about the lesson, never about their retention
 - Never advance on the strength of a smooth session. Advance on a retrieval the learner passed unaided.
 
+Roediger and Karpicke 2006 back this section. Restudying won on a test five minutes later and lost on the delayed tests, while it raised the learners' confidence.
+
 ## Retrieval practice
 
 Pulling an answer out of memory strengthens it far more than reading it again. Recognition is the weak form: a learner who picks the right option from four has done less work than one who produced the answer from nothing.
@@ -24,6 +38,7 @@ Pulling an answer out of memory strengthens it far more than reading it again. R
 - Prefer a question the learner has to produce an answer to over one they select from
 - Let the learner fail an attempt before correcting it. A failed retrieval followed by the answer beats being told first.
 - Do not cue the answer in the question. A question restating the material tests reading rather than memory.
+- Asking first and the failed attempt rest on Kornell, Hays and Bjork 2009. Production over selection and the no-cue rule are house judgment, since no opened study compared a recognition test.
 
 The teach-back block is the production form this section prefers, which is why a lesson carries one beside its quiz. A quiz is recognition, so a lesson offering only one tests the weak form and reports it as retrieval.
 
@@ -33,6 +48,8 @@ Explaining the material to somebody who lacks it makes the learner produce the w
 - Name the audience the explanation is for, since an explanation with no reader has no floor to sit above
 - Record what the explanation left out under what the learner got wrong. A missed production and a missed selection are both retrieval failures, and two sections would split one placement input.
 
+Nestojko et al. 2014 found that expecting to teach produced fuller and better organized recall. Its participants never taught, so the finding backs framing the ask as teaching.
+
 ## Spacing
 
 The same total time spread across days beats the same time in one sitting. Forgetting between sessions is the mechanism rather than the cost, because effortful retrieval is what strengthens the trace.
@@ -41,10 +58,14 @@ The same total time spread across days beats the same time in one sitting. Forge
 - Widen the gap each time a topic is retrieved correctly, and shorten it after a miss
 - Name what to revisit and when in the learning record, so the next session has a schedule rather than a guess
 
+Cepeda et al. 2006 found the best gap grew with how long the material had to last, and the IES practice guide recommends spacing at classroom scale. Forgetting as the mechanism, and widening or shortening the gap after each retrieval, are house judgment.
+
 The ladder is 1, 3, 7, 16, and 35 days. A topic retrieved unaided moves up a rung and a miss drops it back one, held inside the ladder at either end, so a topic the learner keeps missing stays on the shortest gap rather than restarting a sequence.
 
 - Apply the ladder as written rather than picking a gap by judgment, since an author told to widen a gap settles on whatever feels right
 
+The ladder is house judgment. No opened source names a sequence of days or tests a gap that widens after each correct retrieval.
+
 ## Interleaving
 
 Mixing related topics within a session beats finishing one before starting the next. Blocked practice inflates in-session performance and hurts what survives it, because the learner stops having to work out which approach a problem calls for.
@@ -53,6 +74,8 @@ Mixing related topics within a session beats finishing one before starting the n
 - Keep problems in a mixed set close enough that telling them apart is the work
 - Do not interleave a topic the learner has never seen. Interleaving discriminates between things already known.
 
+Kornell and Bjork 2008 found interleaved paintings taught each artist's style better, while learners rated blocked study as more effective. The study mixed exemplars of categories, so mixing topics and the unseen-topic clause are house judgment.
+
 ## The zone of proximal development
 
 The productive band is what the learner cannot do alone and can do with support. Below it the session is review, and above it the support carries the whole task and nothing transfers.
@@ -62,6 +85,8 @@ The productive band is what the learner cannot do alone and can do with support.
 - Withdraw support as the learner succeeds, and restore it on a miss rather than repeating the lesson
 - Where the records show nothing, ask. A guessed starting point misses in both directions.
 
+This section is house judgment. Vygotsky's account was not opened, so the band rests on how a session picks the next step from the record rather than on a citation.
+
 ## Where difficulty helps and where it hurts
 
 Difficulty is not uniformly good. It helps skill acquisition, where the learner is building a procedure they will execute, and it hurts knowledge acquisition, where the learner is taking on facts and structure they do not have yet.
@@ -70,9 +95,11 @@ Difficulty is not uniformly good. It helps skill acquisition, where the learner
 - Add difficulty once the learner is practicing rather than acquiring: withhold the worked step, vary the surface of the problem, delay the feedback
 - Never confuse a hard explanation with a hard problem. A confusing explanation adds load that teaches nothing.
 
+The split between skill and knowledge acquisition is house judgment. The IES guide backs worked examples while a learner acquires a procedure, and Kornell, Hays and Bjork back difficulty at retrieval.
+
 ## Sourcing
 
-Parametric recall is confident where it is wrong, and a learner cannot audit it. Every claim in a lesson traces to something read.
+Parametric recall is confident where it is wrong, and a learner cannot audit it. Every claim in a lesson traces to something read. This section is the toolkit's rule for what a lesson cites rather than a finding about memory.
 
 - Read the subject from sources before teaching, and record each one with its link
 - Mark any claim resting on recall as resting on recall, in the lesson itself

package/docs/agents/install-and-sync.md

@@ -15,8 +15,8 @@ Any flag skips the confirmation prompt, but the `base` default of `--stack` does
 
 ## Governance install
 
-- `canon gov install <stack> [target]` needs the stack under `CANON_NON_INTERACTIVE=1`, else lists the valid names on stderr and exits 1
-- `--yes` answers the install confirm with no TTY and no env var. Without it, a headless call refuses and the message names `--yes`. It does not pick a stack.
+- `canon gov install <stack> [target]` needs the stack on a call with no terminal, else lists the valid names on stderr and exits 1
+- A headless call takes Yes at the install confirm, and `--yes` answers it at a terminal too. Neither picks a stack.
 - It refuses the toolkit root and a missing path
 - `--add <rules>` with no stack installs into the one positional, or the current directory, keeping the recorded chain. Pass `./node` for a target named like a stack.
 
@@ -70,14 +70,6 @@ After a rename the new name shows as `missing` when the stamp records a stack, a
 
 `canon tooling inject` and `prune-gitignore` apply one stack with no scan or prompt, and the latter prints the number removed on stdout. Use `sync` unless scripting provisioning, and pass `--nested` inside an open frame.
 
-## Design
-
-- `canon design install` copies `base.css` to `.claude/design/` and creates no override
-- Project overrides live in `.claude/design/project/`, which `design sync` never touches
-- `canon design fonts add <file> --family <name>` copies a `woff2`, `woff`, `ttf`, or `otf` face into `project/fonts/` with its `fonts.css` rule, and refuses mismatched bytes as `invalid-font`
-- `fonts list --json` flags a missing or out-of-folder file as a `problem`
-- `canon sync` skips the domain where `design install` never ran
-
 ## Whole-project sync
 
 `canon sync [path]` runs every installed domain sync, then offers a commit and pull request. Headlessly it applies the syncs, refuses the git workflow, reports what it would have made, and exits 0. It refuses a dirty working tree.

package/docs/agents/output-shape.md

@@ -22,18 +22,19 @@ Data goes to stdout. UI and logs go to stderr. Help is the exception and prints
 - `└` closes the frame on stderr
 - An error renders as `│ ✗ message` inside the frame, never as a lone line
 - Help skips the banner and puts `Usage:` directly on `├`
+- A stderr that is not a terminal gets plain lines instead, with the banner and section titles bare and each item behind its mark alone
 
 A help request naming an unknown subcommand, under a group taking no operand, writes its refusal to stderr and exits 1.
 
 ## JSON and names modes
 
-`--json` and `--names` keep stdout pure data. The frame still renders on stderr, and diagnostics reach stderr in every mode. A JSON refusal carries an action and a reason, so branch on the record rather than on stderr.
+`--json` and `--names` keep stdout pure data. A `--json` run writes no progress to stderr, only its warnings and errors, since diagnostics reach stderr in every mode. A JSON refusal carries an action and a reason, so branch on the record rather than on stderr.
 
 A shell profile may wrap `canon` in a function that takes its status from a later command. Where a verb documents a record field, read the field rather than the exit.
 
 ## Color
 
-Escape sequences reach a destination that renders them and nowhere else, decided per stream. `NO_COLOR` set to any non-empty value turns color off, and so does a destination that is not a terminal. The frame glyphs and the `✓ ! + - ✗` marks survive both.
+Escape sequences reach a destination that renders them and nowhere else, decided per stream. `NO_COLOR` set to any non-empty value turns color off, and so does a destination that is not a terminal. The `✓ ! + - ✗` marks survive both. The frame glyphs need a terminal.
 
 ## Exit discipline
 
@@ -59,16 +60,16 @@ Discover names at runtime rather than hardcoding them.
 
 ## Headless invocation
 
-Set `CANON_NON_INTERACTIVE=1` to refuse every prompt.
+A call with no terminal on stdin is headless and needs no prefix. Each prompt takes its documented default or refuses and names the flag to pass.
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon init --stack node --skip records /path/to/project
-CANON_NON_INTERACTIVE=1 canon sync /path/to/project
-CANON_NON_INTERACTIVE=1 canon gov install node --add astro,shadcn /path/to/project
-CANON_NON_INTERACTIVE=1 canon gov sync /path/to/project
-CANON_NON_INTERACTIVE=1 canon gov build /path/to/project
-CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
-CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --write
+canon init --stack node --skip records /path/to/project
+canon sync /path/to/project
+canon gov install node --add astro,shadcn /path/to/project
+canon gov sync /path/to/project
+canon gov build /path/to/project
+canon tooling diff astro /path/to/project
+canon tooling sync astro /path/to/project --write
 canon tooling inject base /path/to/project --configs --seeds
 canon tooling prune-gitignore base /path/to/project
 canon tooling verify vite-react

package/docs/target/migrations.md

@@ -121,7 +121,7 @@ From the registry the walk reports `historyUnavailable`, so check both paths by
 | ----------------- | ------------------------------------------------------------- |
 | `task-board`      | `board`, `tasks`, `tasks-decline`                             |
 | `context-fold`    | `context`                                                     |
-| `canvas-board`    | `canvas`, `design`                                            |
+| `canvas-board`    | `canvas`, `design` <!-- canon-keep-retired -->                |
 | `docs-sync`       | `docs`, `readme`                                              |
 | `draw-figure`     | `figures`, `mermaid`                                          |
 | `create-rule`     | `rule`                                                        |
@@ -150,12 +150,17 @@ The wireframes record is retired, and nothing deletes what a project holds.
 
 ## Keep or delete the retired product files, your call
 
-The learning workspace, the deck renderer, and the app recorder are retired with their verbs and skills, and nothing deletes what a project holds.
+The learning workspace, deck renderer, app recorder, canvas, and design install are retired with their verbs, and nothing deletes what a project holds.
 
-- `.canon/teach/` holds rendered HTML that opens as it is, so it needs nothing <!-- canon-keep-retired -->
+- `.canon/teach/` holds HTML that opens as it is <!-- canon-keep-retired -->
 - `.canon/slides/` and a `demos/` folder hold sources nothing renders any more, so delete them once nothing cites them <!-- canon-keep-retired -->
+- Move the `.claude/design/project/` values, `fonts/`, and `fonts.css` to the stylesheet your `canon/DESIGN.md` lead names, then delete `.claude/design/`
+
+A reference to a retired skill takes a hand edit.
+
 - Replace a `canon:teach-workspace` reference with `canon:teach-craft` by hand, since `canon migrate skill-names` does not rewrite it <!-- canon-keep-retired -->
 - Delete a `canon:make-deck`, `canon:script-screencast`, `canon:record-screencast`, `canon:read-frames`, or `canon:video-craft` reference, since none has a successor <!-- canon-keep-retired -->
+- Delete a `canon:canvas-board` reference too. Frameboard, which `canon:pick-by-eye` drives, reads each `.canon/canvas/` folder as a project, so move a kept page under one <!-- canon-keep-retired -->
 
 ## Move decisions out of a held architecture record, once
 

package/docs/target/projects.md

@@ -56,7 +56,7 @@ Keep the `## Scripts` table in `canon/context/development/local-loop.md` current
 Before the first feature session:
 
 1. Fill `canon/REQUIREMENTS.md` with the problem, goals, and non-goals. The seed's 600-word cap gates under `canon context audit`.
-2. For a UI project, write `canon/DESIGN.md` from the seed and name the stylesheet in its lead, or work the direction out with `canon:canvas-board`
+2. For a UI project, write `canon/DESIGN.md` from the seed and name the stylesheet in its lead, or work the direction out with `canon:pick-by-eye`
 3. Optionally invoke `canon:draw-figure` for an architecture view. The Mermaid CLI downloads on first use.
 4. Start the feature loop in [AI workflow](../workflow/ai-workflow.md)
 

package/docs/target/sync.md

@@ -51,4 +51,4 @@ Try a scenario from [sandbox](../../canon/context/development/sandbox.md) before
 
 ## Running sync from an agent session
 
-`canon sync .` applies every domain sync, then offers a commit and pull request that needs a terminal. Under `CANON_NON_INTERACTIVE=1` the syncs apply, the git step is refused, and the command exits 0. Commit yourself. Sync refuses a dirty working tree, and `canon sync --check .` does not.
+`canon sync .` applies every domain sync, then offers a commit and pull request that needs a terminal. With no terminal on stdin the syncs apply, the git step is refused, and the command exits 0. Commit yourself. Sync refuses a dirty working tree, and `canon sync --check .` does not.

package/docs/workflow/skill-map.md

@@ -25,7 +25,6 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:plan-groundwork`    | The state is unmeasured and approaches compete     |
 | `canon:decision-escalate`  | Open decisions turn on your preference             |
 | `canon:pick-by-eye`        | The call is taste, wanting candidates side by side |
-| `canon:canvas-board`       | A direction should be drawn as editable frames     |
 | `canon:task-board`         | A decided item needs a file on the board           |
 | `canon:plan-feature`       | The approach is settled and needs a plan           |
 | `canon:codebase-layout`    | A change adds a file and needs a folder            |

package/docs/workflow/visual-design-workflow.md

@@ -13,14 +13,11 @@ Three tiers run from prose-only design docs to a graphical source of truth, and
 The default. `canon/DESIGN.md` holds visual intent as one Overview paragraph, at most three one-line rules a section, and a table naming each color and shape role, with a lead naming the stylesheet. Claude Code alone suffices, and [`test-craft`](../../claude/skills/test-craft/SKILL.md) says which layer a Playwright journey belongs at.
 
 - The seed is `tooling/claude/seeds/canon/DESIGN.md`, and its column headers stay verbatim
-- `canon design render` previews it in `.canon/tmp/render/design/`
-- `canon design install` copies a neutral base to `.claude/design/base.css`, so override values in `.claude/design/project/`. See `canon/context/features/design.md`.
 
 These skills cover the tier:
 
 - `canon:ui-checklist`, `canon:ux-audit`, and `canon:ux-measure` review and measure a UI
-- `canon:pick-by-eye` drafts candidates as frames on the canvas and takes your pick
-- `canon:canvas-board` works a direction out as HTML frames you edit in the browser, and hands the pick on
+- `canon:pick-by-eye` drafts candidates as frames on a [Frameboard](https://www.npmjs.com/package/frameboard) board and takes your pick
 - `canon:design-record` lands a pick in `canon/design/` and carries its values into `canon/DESIGN.md`
 - `canon:design-identity` drafts a logo mark and social card