@erclx/canon 4.89.0 → 4.92.0

package/src/design/tokens.ts

@@ -39,6 +39,12 @@ export interface TypeToken {
   readonly verify?: readonly ('family' | 'weight' | 'size' | 'lineHeight')[]
 }
 
+/** One size the system offers, named apart from any role that takes it. */
+export interface TypeStep {
+  readonly step: string
+  readonly size: string
+}
+
 export interface SpaceToken {
   readonly step: string
   readonly multiplier: string
@@ -57,6 +63,7 @@ export interface DesignTokens {
   readonly personality: string
   readonly color: readonly ColorToken[]
   readonly colorNote: string
+  readonly typeScale: readonly TypeStep[]
   readonly typography: readonly TypeToken[]
   readonly typographyNote: string
   readonly spacing: readonly SpaceToken[]
@@ -68,20 +75,19 @@ export interface DesignTokens {
   readonly preamble: string
 }
 
-/** The monospace stack every surface but the landing page hero declares. */
+/** The monospace stack, taken by code and by the terminal frames a page embeds. */
 const MONO = 'Noto Sans Mono, DejaVu Sans Mono, monospace'
 
 /**
- * The proportional stack the landing page hero declares and nothing else does.
- * Noto Sans is the proportional sibling of the mono above rather than a face
- * picked for taste, so the pairing is one superfamily rather than two systems.
+ * The proportional stack every role but `code` declares. Geist is the face the
+ * visual-direction track set throughout, embedded through `FONT_FACES`.
  *
  * The stack stops at two names and a generic because `src/design/base.css` is
  * written by `canon design regen` and formatted by prettier, and a declaration
  * past 80 columns is wrapped by the second and flattened by the first. Every
  * emitted line stays inside the width so the two writers never disagree.
  */
-const SANS = 'Noto Sans, DejaVu Sans, sans-serif'
+const SANS = 'Geist Variable, DejaVu Sans, sans-serif'
 
 const DARK_GROUNDS = ['background', 'surface'] as const
 const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
@@ -94,13 +100,13 @@ export const TOKENS: DesignTokens = {
     '',
     'The two rendered captures read it as well. `scripts/core/regen-hero.sh` fills `assets/captures/hero.html.tmpl` and `assets/captures/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
     '',
-    'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `canon/ARCHITECTURE.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
+    'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `canon/context/scripts/framing.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
   ].join('\n'),
 
   personality: [
-    'Warm neutrals carry the frame under a single rust accent, rendered in the same monospace the terminal uses. The subject picks the register rather than taste: a toolkit whose primary surface is a shell has no proportional voice available, so the rendered surfaces match the terminal instead of the reverse. One accent carries every count, link, and primary action. Promoting a second and third into structural roles is what reads as a generated interface, so the palette stays at one.',
+    'Warm neutrals carry the frame under a single rust accent, set in Geist. The subject is a toolkit for people who read documents and diffs as much as they run commands, so the voice is a proportional one and the page reads as prose. One accent carries every count, link, and primary action. Promoting a second and third into structural roles is what reads as a generated interface, so the palette stays at one.',
     '',
-    'One surface is carved out of the sentence above, and it is the landing page hero. A rendered surface here shows a reader what the terminal did, so matching the terminal is what makes it legible. A public page addresses somebody who has never opened the terminal at all, and the shell has no voice available for that, which is the reverse of the case the rule was written for. The `page-display` role below is the whole of the carve-out. Every other role on that page stays monospace, including its body, its controls, and every frame it embeds, so the page reads as two families rather than as a second design system.',
+    'Monospace is a role the page uses rather than its voice. The `code` role takes it, and so does any terminal frame a surface embeds, since those show what the shell printed and matching the shell is what makes them legible. Every other role is Geist.',
   ].join('\n'),
 
   colorNote: [
@@ -236,52 +242,62 @@ export const TOKENS: DesignTokens = {
   ],
 
   typographyNote: [
-    'One family covers every role but `page-display`, which is the landing page hero and takes the proportional sibling of the same superfamily. The size scale runs from 11.5 to 52 pixels, and six values map onto a role. Five further values are adjustments inside a single component and get no role here, since a scale with five invented steps reads as a system the surfaces do not implement. They are 11.5, 12.5, 13, 14, and 15 pixels.',
+    'Seven sizes are on offer, named `t0` through `t6` and emitted as custom properties beside the roles. They are 3.175, 2.375, 1.375, 1.125, 0.9375, 0.8125 and 0.6875 rem, which paint at 50.8, 38, 22, 18, 15, 13 and 11 pixels, and each role takes one. A step answers what sizes exist and a role answers what a stylesheet asks for, so the two stay separate: a role whose step did not move renders as it did, and a role that moved is the only thing that changes what a surface paints. Two steps, `t3` at 18 pixels and `t6` at 11, are offered with no role pointing at them yet.',
     '',
-    'The 52 pixel step sits above the 34 the rest of the scale tops out at, and it is the one size no other surface reaches, since a hero headline set at the display cap reads as an opening rather than as a section heading.',
+    'Every role but `code` is Geist and `code` is monospace. The hero headline takes the largest step at 50.8 pixels, which no other role reaches, since a headline set at the display cap reads as an opening rather than as a section heading.',
     '',
     'A tagged cell is one no rendering surface exercises yet, which is a declaration the system has not tested rather than one it has.',
     '',
     'Two rules set tracking and no others touch it. The label role carries `0.05em`, and the display role tightens to `-0.01em`.',
   ].join('\n'),
 
+  typeScale: [
+    { step: 't0', size: '3.175rem' },
+    { step: 't1', size: '2.375rem' },
+    { step: 't2', size: '1.375rem' },
+    { step: 't3', size: '1.125rem' },
+    { step: 't4', size: '0.9375rem' },
+    { step: 't5', size: '0.8125rem' },
+    { step: 't6', size: '0.6875rem' },
+  ],
+
   typography: [
     {
       role: 'display',
-      family: MONO,
+      family: SANS,
       weight: '700',
-      size: '34px',
+      size: '2.375rem',
       lineHeight: '1.3',
     },
     {
       role: 'page-display',
       family: SANS,
       weight: '700',
-      size: '52px',
+      size: '3.175rem',
       lineHeight: '1.1',
-      verify: ['family', 'size', 'lineHeight'],
+      verify: ['size', 'lineHeight'],
     },
     {
       role: 'heading',
-      family: MONO,
+      family: SANS,
       weight: '700',
-      size: '19px',
+      size: '1.375rem',
       lineHeight: '1.3',
       verify: ['lineHeight'],
     },
     {
       role: 'body',
-      family: MONO,
+      family: SANS,
       weight: '400',
-      size: '16px',
+      size: '0.9375rem',
       lineHeight: '1.65',
       verify: ['weight'],
     },
     {
       role: 'label',
-      family: MONO,
+      family: SANS,
       weight: '400',
-      size: '12px',
+      size: '0.8125rem',
       lineHeight: '1.45',
       verify: ['weight', 'lineHeight'],
     },
@@ -289,27 +305,26 @@ export const TOKENS: DesignTokens = {
       role: 'code',
       family: MONO,
       weight: '700',
-      size: '14.5px',
+      size: '0.8125rem',
       lineHeight: '1.3',
       verify: ['lineHeight'],
     },
   ],
 
   spacingNote: [
-    'The base is six pixels, which is the largest unit dividing the values that recur: 6, 12, 18, 24, and 30. One-off paddings at 9, 10, 11, 13, 14, 16, 22, 26, 34, and 40 pixels sit off the scale entirely and get no step.',
+    'Seven steps run from a quarter rem to six, at 4, 8, 14, 24, 40, 64 and 96 pixels on a 16 pixel root. The scale is not a grid of one base, since the 14 between the 8 and the 24 is the step a control needs and no multiple of four supplies it, so the multiplier column counts quarter rems rather than claiming a unit.',
     '',
-    'The outer window padding is a single declaration reading `44px 52px 38px`, and none of its three values divides by six. They carry no multiplier for that reason, and one declaration setting all three is the only thing grouping them, so they are a frame register rather than a scale.',
+    'The outer window padding of the capture frames, which the previous record carried as a three-value frame register, is not part of the scale. Those frames set their own padding in the template and read no step, so the register is retired here rather than mapped onto steps no frame uses.',
   ].join('\n'),
 
   spacing: [
-    { step: 'xs', multiplier: '1', value: '6px' },
-    { step: 'sm', multiplier: '2', value: '12px' },
-    { step: 'md', multiplier: '3', value: '18px' },
-    { step: 'lg', multiplier: '4', value: '24px' },
-    { step: 'xl', multiplier: '5', value: '30px' },
-    { step: 'frame-top', multiplier: 'none', value: '44px' },
-    { step: 'frame-inline', multiplier: 'none', value: '52px' },
-    { step: 'frame-bottom', multiplier: 'none', value: '38px' },
+    { step: 'xs', multiplier: '1', value: '0.25rem' },
+    { step: 'sm', multiplier: '2', value: '0.5rem' },
+    { step: 'md', multiplier: '3.5', value: '0.875rem' },
+    { step: 'lg', multiplier: '6', value: '1.5rem' },
+    { step: 'xl', multiplier: '10', value: '2.5rem' },
+    { step: '2xl', multiplier: '16', value: '4rem' },
+    { step: '3xl', multiplier: '24', value: '6rem' },
   ],
 
   bordersNote: [

package/src/gate/measures.ts

@@ -7,6 +7,11 @@ import {
   type ClientCommand,
   clientCommandCitationsIn,
 } from '@/client-commands'
+import {
+  isOverCount,
+  isOverLength,
+  measureArchitecture,
+} from '@/context/architecture'
 import { listRepositoryFiles } from '@/git-files'
 import {
   isShippedCorpus,
@@ -222,6 +227,41 @@ function citedPaths(record: { paths?: unknown } | undefined): string[] {
   })
 }
 
+/**
+ * The architecture record against the two limits it states for itself: the
+ * line ceiling its allowances derive and the entry cap.
+ *
+ * Read in-process rather than through `context audit`, whose one gating stage
+ * here runs `--citations-only` and never opens the record, which is why the
+ * line ceiling went unenforced by `bun run check` until this stage. A project
+ * carrying no record, or a record stating neither limit, passes, since both
+ * limits belong to the record rather than to the toolkit.
+ */
+export const architectureRecord: Measure = async (ctx) => {
+  const report = await measureArchitecture(ctx.root)
+  if (report === undefined) {
+    return { emissions: [info('No architecture record to measure')] }
+  }
+
+  const decisions = report.decisions.length
+  const failures = [
+    isOverCount(report) &&
+      `${decisions} decisions against a cap of ${report.entryCap}. Merge two or retire one in ${report.rel}, never compress.`,
+    isOverLength(report) &&
+      `${report.lines} lines against a ceiling of ${report.ceiling} in ${report.rel}.`,
+  ].filter((failure): failure is string => typeof failure === 'string')
+
+  if (failures.length > 0) return { emissions: [], failure: failures.join(' ') }
+
+  const cap =
+    report.entryCap === undefined
+      ? 'no entry cap stated'
+      : `a cap of ${report.entryCap}`
+  return {
+    emissions: [info(`${decisions} decisions against ${cap}`)],
+  }
+}
+
 /**
  * A second run of the records move should rewrite nothing, and the count is
  * only knowable once the folders themselves have landed.

package/src/gate/stages.ts

@@ -1,4 +1,5 @@
 import {
+  architectureRecord,
   auditSet,
   captureStamps,
   clientCommandCitations,
@@ -326,7 +327,7 @@ export const STAGES: readonly Stage[] = [
   {
     // A hook, a workflow, or a husky script reaching one side of the seed or
     // config boundary and not the other is a capability withheld with no
-    // recorded reason, per the criterion in .claude/ARCHITECTURE.md.
+    // recorded reason, per the criterion in canon/context/tooling.md.
     id: 'capability-seeding',
     label: 'Capability seeding',
     checks: [
@@ -362,6 +363,13 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Context citations resolve',
   },
+  {
+    // The record's two limits are facts it states about itself, unlike the
+    // judgment thresholds the stage above leaves out, so they gate here.
+    id: 'architecture-record',
+    label: 'Architecture record',
+    checks: [{ kind: 'measure', measure: architectureRecord }],
+  },
   {
     // A rule citing a file that moved fails silently. The consumed-copy drift
     // stage passes an authored rule and its copy that are wrong together, and

package/src/teach/workspace.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
+import { basename, join, relative } from 'node:path'
 import { TEACH_STYLESHEET_COMPONENTS } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
@@ -230,9 +230,14 @@ export function refuse(
  * Every workspace sits under the main worktree root rather than under the
  * checkout the caller stands in. Resolving that root belongs to the caller, so
  * this takes one and never reads the working directory.
+ *
+ * A root already named `teach` is taken as the teach folder itself rather than
+ * a project root to wrap, which is what lets a caller point straight at a
+ * folder such as `examples/teach` that holds workspaces outside any `.canon/`
+ * or `.claude/` record root.
  */
 export function teachDir(root: string): string {
-  return recordDir(root, 'teach')
+  return basename(root) === 'teach' ? root : recordDir(root, 'teach')
 }
 
 async function listSlugs(dir: string): Promise<string[]> {
@@ -241,6 +246,7 @@ async function listSlugs(dir: string): Promise<string[]> {
   return entries
     .filter((entry) => entry.isDirectory())
     .map((entry) => entry.name)
+    .filter((name) => WORKSPACE_NAME.test(name))
     .sort()
 }
 

package/standards/architecture.md

@@ -5,7 +5,7 @@ description: Shape and content rules for canon/ARCHITECTURE.md
 
 # Architecture reference
 
-Applies to `canon/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: principles live there, patterns and decisions live here. Update when a decision is made or a risk is resolved.
+Applies to `canon/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: session behavior lives there, and the system's shape lives here. Update when a decision is made or a risk is resolved.
 
 ## Scope
 
@@ -20,15 +20,26 @@ Does not govern:
 ## What goes in
 
 - A high-level overview of how the system is structured and why
-- Key technical decisions as named H3 entries: what was chosen and why over the alternatives, including stack and library choices
+- Key technical decisions as named H3 entries, each filling one of the five slots below: what was chosen and why over the alternatives
 - Risks and open questions still unresolved
 
+A decision belongs here only when it fills a slot:
+
+- Stack and runtime: the language, the runtime, and the major libraries the system is built on
+- Delivery: how the system's content or code reaches the place it runs
+- Enforced boundaries: a boundary the system checks mechanically, and what enforces it
+- Layout: how the project's top-level roots and context tiers divide what they hold
+- Build principles: a rule for how a behavior is built that changes work in more than one domain, stated in one sentence
+
+The slots come from a scale test. Ask whether the decision would still be in this file if the project were ten times its size. At that size an always-loaded file holding one entry per decision fits no context window, and what survives is the shape: the stack, the delivery, the boundaries, the layout, and the principles. A decision that fits no slot is a domain decision, and its home is that domain's `canon/context/<domain>.md` entry under `## Decisions`, however many domains its reasoning touches. Reach is not the test, since nearly every decision reaches a second domain.
+
 ## What does not go in
 
 - How individual functions work line by line. The code carries its own behavior.
 - Full type definitions. They live in code. Reference the shape conceptually if needed.
-- A measurement paragraph specific to one domain's own mechanism. Route it to that domain's `canon/context/<domain>.md` entry instead. The choice and its rejected alternative stay here whatever their reach, since reach is what makes a decision cross-domain, not how many domains its supporting measurement happens to touch.
-- A decision that constrains one domain alone. It lives in that domain's context entry, and this file carries at most one line pointing at it.
+- A decision that fills no slot. It lives in the domain context entry it constrains, and this file carries at most one line pointing at it.
+- A measurement paragraph specific to one domain's own mechanism, even behind a slot decision. Route it to that domain's context entry and keep the choice, the alternative that lost, and one reason here.
+- The instances of a build principle. The principle takes one sentence here, and each instance lives in the domain entry where it applies.
 - The history of how a decision was reached or revised: rounds of candidates, a figure followed by its correction, a branch or change that moved a number. That trail goes to the decision log or the change that introduced it.
 
 ## Sections
@@ -38,7 +49,7 @@ Use `## Overview`, `## Key technical decisions` with one named H3 per decision,
 ## Keeping it current
 
 - Rewrite a decision a later one changed rather than appending the change beside it. A reader should find the design that stands in one place, with the alternative that lost stated once.
-- Hold only what is open under `## Risks / open questions`. An entry leaves the section in the change that settles it, becoming a decision here when it constrains more than one domain and moving to that domain's context entry when it does not.
+- Hold only what is open under `## Risks / open questions`. An entry leaves the section in the change that settles it, becoming a decision here when it fills a slot and moving to the domain context entry it constrains when it does not.
 
 ## Verification anchors
 
@@ -54,27 +65,41 @@ A decision's reasoning stays correct while the numbers it cites move. The anchor
 - Do not edit a claim in the pass that first anchors it. The anchor states what the claim was measured against, so changing both at once leaves nothing to check the anchor against.
 - Refresh the anchor whenever the number is re-read, whether or not it moved. A confirmed number and an unread one are the same text without the date.
 
-## Length
+## Entry cap
 
-Every session pays for this file before any work starts, so a heavy read is a real cost. Judge weight by reading the file rather than by counting it: a file that reads heavy is carrying too many decisions, not decisions written too long. A word count, for the file and for each decision, is read alongside that judgment when one is available, and it never gates.
+Every session pays for this file before any work starts, so a heavy read is a real cost. A file that reads heavy is carrying too many decisions, not decisions written too long, so the bound is a count of decisions rather than of words.
 
-- Bring a heavy file back by merging two decisions or retiring one, never by compressing a decision's prose.
+- State the cap in the record itself as a clause of the form `This record holds at most <n> decisions.` The cap is the record's own, so a checker reads it from the file, and a record stating none is measured and never gated.
+- Set the cap near one decision per slot plus a small margin.
+- At the cap, merge two decisions or retire one before adding another, and name which in the change that does it. Never compress a decision's prose to fit, and never pack two decisions under one heading, which the count cannot see.
+- Retire a decision by moving it to the domain context entry it constrains, not by deleting its reasoning.
+- A word count, for the file and for each decision, is read alongside the judgment when one is available, and it never gates.
 - Yield to the paragraph weight checkpoint in `markdown.md`. A paragraph past the checkpoint is a defect no length guideline licenses.
 
 ## Template
 
-The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none.
+The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none. Each heading below names a slot, so a record starts with one decision per slot and renames each heading to the choice it records.
 
 ```markdown
 # Architecture
 
 ## Overview
 
+This record holds at most 12 decisions.
+
 ## Key technical decisions
 
-### Decision name
+### Stack and runtime
+
+What was chosen, the alternative that lost, and why. Measured at <short-sha> on <YYYY-MM-DD>.
+
+### Delivery
+
+### Enforced boundaries
+
+### Layout
 
-Reasoning and tradeoffs, carrying the measured number the choice rested on. Measured at <short-sha> on <YYYY-MM-DD>.
+### Build principles
 
 ## Risks / open questions
 ```

package/standards/context.md

@@ -13,7 +13,7 @@ Governs per-domain narrative entries under `canon/context/`: their structure, th
 
 Does not govern:
 
-- Cross-domain decisions and system-wide risks: `architecture.md`
+- Decisions filling a stack, delivery, boundary, layout, or build-principle slot, and system-wide risks: `architecture.md`
 - Product scope, goals, and non-goals: `requirements.md`
 - Path-scoped coding rules: `rule.md`
 - Diagrams and wireframes, which answer structure and layout questions an entry hands off: `diagrams.md` and `wireframes.md`
@@ -82,7 +82,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 ## What goes in
 
 - Per-domain narrative on how the code is structured and why
-- Decisions specific to the domain. Broader cross-domain decisions belong in `canon/ARCHITECTURE.md`.
+- Decisions that constrain the domain, whether or not their reasoning touches another one. This is a decision's default home, and `canon/ARCHITECTURE.md` takes only a decision that fills one of the slots its standard names.
 - Constraints, gotchas, things tried and rejected
 - Domain-specific conventions that do not fit a `paths:`-scoped rule
 - A measured figure, anchored the way `architecture.md` states under `## Verification anchors`, so an entry and the architecture record date a number the same way.

package/standards/ready.md

@@ -11,6 +11,8 @@ The folder is gitignored, and backed wherever a records remote is configured: `c
 
 ## Scope
 
+The `draft-ready` skill owns the procedure that writes a ready folder, and this standard owns the shape it writes to.
+
 Governs a ready folder under `.canon/ready/<nn>-<slug>/`: folder layout, ordinal naming, the overview's frontmatter, what the mirrored tree holds, the thin-plan contract that ships it, and the lifecycle from the live folder to the archive.
 
 Does not govern:

package/standards/session.md

@@ -18,6 +18,7 @@ Does not govern:
 - The task board the file sits beside, its filenames, and its archiving: `tasks.md`
 - The transform from a branch name to the slug in the filename: `slug.md`
 - The role-specific sections a caller adds over the core, which belong to that caller
+- The note a plain session writes at `.canon/compact/<slug>.md`, whose shape lives in the `session-compact` skill's own reference
 - Which memories a session captures before writing, which is the capture surface's own subject
 
 ## What a working session map looks like

package/tooling/claude/seeds/canon/ARCHITECTURE.md

@@ -4,10 +4,20 @@ Authoring guidance: the architecture standard.
 
 ## Overview
 
+This record holds at most 12 decisions.
+
 ## Key technical decisions
 
-### Decision name
+### Stack and runtime
+
+What was chosen, the alternative that lost, and why.
+
+### Delivery
+
+### Enforced boundaries
+
+### Layout
 
-Reasoning and tradeoffs.
+### Build principles
 
 ## Risks / open questions