@erclx/aitk 0.34.0 → 0.35.1

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

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

package/claude/skills/bash-script/SKILL.md

@@ -9,6 +9,10 @@ Generate production-ready Bash scripts for DevOps and CLI workflows. Enforce str
 
 Load `${CLAUDE_SKILL_DIR}/references/patterns.md` for the timeline lifecycle, logging, interactive prompt, help-screen, and full-script code templates. `${CLAUDE_SKILL_DIR}` expands to this skill's own directory, so the path resolves from any project. Copy those definitions verbatim, keeping only the colors and functions the script actually uses.
 
+## Guards
+
+- A request for a script with no human at the terminal stops and routes to `cli-script`. CI jobs, cron entries, agent-run tasks, and any script whose output is consumed by a pipe render no timeline, so generating one costs the frame and returns nothing.
+
 ## Script setup
 
 - Start with `#!/usr/bin/env bash`, `set -e`, and `set -o pipefail`.

package/claude/skills/ci-workflow/SKILL.md

@@ -7,6 +7,11 @@ description: Generates GitHub Actions CI workflow files with parallel jobs, emoj
 
 Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job execution, emoji job naming, and gated deployment stages.
 
+## Guards
+
+- A request for what runs inside a deploy, publish, or release job stops at the gate. Credentials, environments, and deploy targets are invisible to this skill, so emit the job with its `needs` wiring and a placeholder step, then name what the caller fills in. Never guess a deploy command.
+- The build, test, and deploy commands belong to the project. Read them from its scripts rather than asserting a second copy in the workflow.
+
 ## Workflow setup
 
 - Include `workflow_dispatch` on every workflow alongside the primary trigger.
@@ -49,4 +54,5 @@ Before responding, verify:
 - E2E uses `needs: build`. Release and deploy use `needs: e2e`.
 - Artifacts upload on `if: failure()` only with `retention-days: 7`.
 - Job names use emoji + title format.
+- Deploy, publish, and release jobs carry a placeholder step and a named handoff, never a guessed deploy command.
 - Bun projects use `oven-sh/setup-bun@v2` with `bun install --frozen-lockfile`.

package/claude/skills/docs-sync/SKILL.md

@@ -55,14 +55,19 @@ Read each discovered file in parallel.
 For each discovered doc, classify as one of:
 
 - `stale`: the diff touches something the doc describes
+- `departed`: the doc records a deliberate contract and the diff broke it
 - `unrelated`: no overlap between diff and doc content
 
+The split between `stale` and `departed` is whether the doc was describing or promising. A doc that trailed the code is `stale`. A doc stating a contract the code was meant to keep is `departed`, and rewriting it to match the diff would record the regression as the contract.
+
 Classify at the section level, not the file level. A doc edited earlier in the session can still be partially stale. For each diff surface, verify the corresponding section is synced.
 
 ## Action
 
 Rewrite only the stale sections. Do not touch sections unrelated to the diff. Write the updated file immediately after the preview. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 
+Never rewrite a `departed` section. Leave it as written and report it as a finding, since the repair belongs in the code rather than in the prose.
+
 ## Response format
 
 ### Preview
@@ -73,6 +78,7 @@ Rewrite only the stale sections. Do not touch sections unrelated to the diff. Wr
 | Doc         | Status    | Action |
 | ----------- | --------- | ------ |
 | README.md   | stale     | update |
+| docs/cli.md | departed  | report |
 | docs/api.md | unrelated | skip   |
 
 After outputting the preview, write all stale updates immediately.
@@ -84,4 +90,5 @@ One line per file, using the same relative path format as the preview table (e.g
 ```plaintext
 ✅ Updated: <relative-path>
 ⏭️  Skipped: <relative-path>
+⚠️ Departed: <relative-path> records <the contract>, and the diff <what it did>. Left unwritten.
 ```

package/claude/skills/migration-claude-md/SKILL.md

@@ -7,6 +7,8 @@ description: Classifies each section of a target project's bloated `CLAUDE.md` i
 
 Rebalance a large `CLAUDE.md` so only always-load behavior stays in it, path-scoped behavior becomes a rule, and domain narrative becomes a context entry. Every move is a proposal the user applies by hand.
 
+Run `migration-context` first when both apply. Its moves populate `.claude/context/`, and Step 3 has to read the folder those moves left so an existing entry resolves to an append rather than blocking the move that should have created it.
+
 ## Guards
 
 - If no `CLAUDE.md` exists at `pwd`, stop: `❌ No CLAUDE.md found at the project root.`

package/claude/skills/migration-context/SKILL.md

@@ -5,6 +5,8 @@ description: Classifies markdown files in a target project's `docs/` folder and
 
 # Claude context migrate
 
+Run this skill before `migration-claude-md` when both apply. That skill proposes entries into the same `.claude/context/` folder, and an entry landing there first makes the corresponding move here read as a conflict and get skipped, which loses the richer `docs/` file.
+
 ## Guards
 
 - If no `docs/` directory exists at `pwd`, stop: `❌ No docs/ directory found.`

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

@@ -36,13 +36,14 @@ Match the detected evidence to the catalog:
 
 If a detected technology has no matching rule, stop and surface the gap. Do not guess.
 
-Present three options:
+Present four options:
 
-1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `.claude/standards/rule.md`, or `${CLAUDE_SKILL_DIR}/../../standards/rule.md` when the project does not have it, commit, then re-run install.
-2. Install the matching non-<tech> rules and skip the tech-specific layer.
-3. Abort.
+1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `.claude/standards/rule.md`, or `${CLAUDE_SKILL_DIR}/../../standards/rule.md` when the project does not have it, commit, then re-run install. Take this route when the toolkit should ship the rule to every project.
+2. Invoke `create-rule`, which scaffolds the file into the target project at a non-colliding number. Take this route when the rule is specific to this project and no sync should ever overwrite it.
+3. Install the matching non-<tech> rules and skip the tech-specific layer.
+4. Abort.
 
-Rules are authored in the toolkit repository, never in the target project on the fly.
+This skill authors no rule itself. Option 1 writes in the toolkit repository, and option 2 hands the project-local file to `create-rule`.
 
 ## Preview
 

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

@@ -10,6 +10,7 @@ Orchestrates the onboarding chain. Detects project type, resolves per-domain arg
 ## Scope
 
 - This skill and `aitk init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `aitk <domain> install` or `aitk sync` paths instead.
+- The chain does not bootstrap the `index.md` system and does not provision Claude Code plugins. `setup-indexes` owns the first. `setup-plugins` owns the second, which installs once per machine rather than into a project, so no project-scoped chain can carry it. Name both in the report so a clean result does not read as onboarding complete.
 
 ## Read catalogs
 
@@ -112,3 +113,4 @@ After the chain, report:
 - `setup-verify` outcome
 - Any domains or scripts that failed
 - Any detection gaps surfaced during resolve
+- Onboarding steps left to the caller: `setup-indexes` for the `index.md` system, `setup-plugins` for Claude Code plugins

package/docs/agents.md

@@ -80,7 +80,7 @@ Full help: `aitk <command> --help`.
 | `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
 | `aitk tasks archive`     | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
 | `aitk comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
-| `aitk context audit`     | Report entry length, depth, cited-path resolution, provenance, and index drift                 |
+| `aitk context audit`     | Report entry length, depth, bullet weight, cited-path resolution, provenance, and index drift  |
 | `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
 
 ### Domain commands
@@ -387,7 +387,7 @@ aitk context audit --folder context,diagrams
 
 Scope defaults to `context`, `diagrams`, and `wireframes`, and a folder the project does not carry is skipped rather than reported. A domain that outgrew one file and split into `<domain>/` is audited as its own folder, so a split entry measures at the same grain as a flat one.
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Length, depth, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Length, depth, bullet weight, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
 
 ### What each check reports
 
@@ -395,11 +395,13 @@ Length and depth quote their checkpoints from `.claude/standards/context.md`: ro
 
 Both checks count rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see. Measuring one checkpoint in each unit would put an entry length beside a run length that mean different things. Their exclusions still differ: the file measure counts fenced blocks and frontmatter, while the run measure skips a fence so an example cannot break the run around it. A reference-heavy entry therefore ranks by its examples, which the length legend states on every run. Runs count blank lines, which the standard leaves open, so a hand reader who drops them lands a line or two lower. Both sections state the width on every run, since a number in rendered lines cannot be reproduced without it.
 
+The bullet check reports a top-level bullet past roughly 400 characters, which is where a bullet stops carrying a decision alone and starts carrying the incident that motivated it beside the decision. Continuation lines fold into the bullet they belong to, so a heavy bullet cannot fall under the checkpoint by wrapping across two source lines, while a nested item is left out because the parent's own text is what the checkpoint asks about. Findings group by entry and narrow to `.claude/context/` for the reasons the provenance ones do both. Unlike the peer-list threshold above it, this corpus has no gap behind the number: bullet weight decays smoothly from a median near 170, so the number is a judgment where that one was a measurement, and a bullet reading well past it means the number is wrong rather than the rule.
+
 The table check reports a catalog that grows a row per shipped thing, not a table count. A fixed comparison table never reflows, so its size costs nothing. A table qualifies at six or more body rows whose first column mostly carries a path, command, or link, which is what separates a catalog from a comparison without reading the prose.
 
 The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since the content checks read the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle. Length is the exception, counting the whole file, so a reader applying the 150-rendered-line checkpoint against the body alone lands a few lines under what the tool reports.
 
-This one check covers `.claude/context/` alone, while length, depth, and the table finding reach every audited folder. The rule is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder: a threshold on how far a reader travels generalizes across entry types, while a rule about what an entry may say is the jurisdiction a scope statement exists to settle. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
+The provenance and bullet-weight checks cover `.claude/context/` alone, while length, depth, and the table finding reach every audited folder. The rule is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is whether the remedy is actionable rather than what the check measures. Subdividing a run and splitting a file mean something in any entry, so length and depth generalize. Moving an incident out of a bullet and keeping the decision means nothing in a folder whose entries declare no decisions, which is why bullet weight narrows despite measuring a distance like the two that do not. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
 
 Index drift compares an index against its siblings in both directions. An entry the index does not link is invisible to a session choosing what to open, and a linked name resolving to nothing sends one to a path that opens nothing.
 

package/package.json

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

package/src/commands/context.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
+  BULLET_CHECKPOINT,
   type EntryReport,
   governsContent,
   LENGTH_CHECKPOINT,
@@ -50,7 +51,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report entry length, depth, citations, provenance, and index drift',
+      'Report entry length, depth, bullet weight, citations, provenance, and index drift',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -67,7 +68,7 @@ export function register(program: Command): void {
         '  2  a cited path did not resolve',
         '',
         'Only unresolved citations set a failing exit code. Length, depth,',
-        'table, provenance, and index findings are advisory.',
+        'bullet, table, provenance, and index findings are advisory.',
         '',
         'Examples:',
         '  aitk context audit',
@@ -139,6 +140,7 @@ async function runAudit(
     reportCitations(citations)
     reportLength(entries)
     reportDepth(entries)
+    reportBullets(entries, folders)
     reportTables(entries)
     reportProvenance(entries, folders)
     reportDrift(drift)
@@ -167,6 +169,7 @@ async function runAudit(
           runCountsBlankLines: true,
           renderWidth: RENDER_WIDTH,
           peerBullet: PEER_BULLET_CHECKPOINT,
+          bullet: BULLET_CHECKPOINT,
           provenanceFolder: PROVENANCE_FOLDER,
         },
       })}\n`,
@@ -311,6 +314,66 @@ function reportDepth(entries: readonly EntryReport[]): void {
   )
 }
 
+/**
+ * Groups by entry, and states its reach on every run, for the reasons the
+ * provenance report does both.
+ *
+ * Bullets past the checkpoint cluster in a handful of entries and the heaviest
+ * entries carry them a dozen at a time, so a flat list of bullets buries the
+ * entry holding one. What a reader acts on is which file to open.
+ */
+function reportBullets(
+  entries: readonly EntryReport[],
+  folders: readonly AuditedFolder[],
+): void {
+  logStep('Bullets')
+
+  const governed = folders.filter(governsContent)
+  if (governed.length === 0) {
+    logInfo(
+      `Out of scope. The rule is stated in the standard governing .claude/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
+    )
+    return
+  }
+
+  logInfo(
+    `Covers .claude/${PROVENANCE_FOLDER}/ alone, since moving an incident out of a bullet needs a decision to keep.`,
+  )
+  logInfo(
+    'Top-level bullets measure characters, folding in continuation lines.',
+  )
+  logInfo(
+    'Nested items and fenced blocks are excluded. Weight is a judgment, never a defect.',
+  )
+
+  const carrying = entries
+    .filter((entry) => entry.heavyBullets.length > 0)
+    .sort((a, b) => b.heavyBullets.length - a.heavyBullets.length)
+
+  if (carrying.length === 0) {
+    logInfo(`No bullet past the ${BULLET_CHECKPOINT}-character checkpoint.`)
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, entry) => sum + entry.heavyBullets.length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'bullet')} past the ${BULLET_CHECKPOINT}-character checkpoint across ${carrying.length} ${carrying.length === 1 ? 'entry' : 'entries'}`,
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (entry) =>
+          `${entry.rel}  ${plural(entry.heavyBullets.length, 'bullet')}\n${entry.heavyBullets
+            .map((found) => `  :${found.line}  ${found.characters} characters`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 function reportTables(entries: readonly EntryReport[]): void {
   logStep('Tables')
 

package/src/context/audit.ts

@@ -27,6 +27,18 @@ export const RENDER_WIDTH = 80
  */
 export const PEER_BULLET_CHECKPOINT = 130
 
+/**
+ * Characters a bullet carries before it holds more than the decision itself.
+ *
+ * Unlike the peer-list checkpoint above, this corpus has no gap behind the
+ * number. Bullet weight decays smoothly from a median near 170 with the
+ * steepest relative fall across this boundary and nothing resembling two
+ * populations, so the number is a judgment where that one was a measurement.
+ * A bullet that reads well past it means the number is wrong rather than the
+ * rule, which is why this reports and never gates.
+ */
+export const BULLET_CHECKPOINT = 400
+
 /**
  * A table this size or larger whose first column mostly names artifacts reads
  * as a catalog that grows a row per shipped thing, which is the shape the
@@ -71,6 +83,14 @@ const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
  * audited folder, because a threshold on how far a reader travels generalizes
  * across entry types while a rule about what an entry may say does not.
  *
+ * Bullet weight sits on this side of the split with provenance, which the
+ * measure alone would not predict. What decides it is whether the remedy is
+ * actionable: subdividing a run and splitting a file mean something in any
+ * entry, while moving an incident out of a bullet and keeping the decision
+ * means nothing in a folder whose entries carry no decisions to keep. No
+ * diagram entry declares `## Decisions` or `## Gotchas`, so the scope of the
+ * rule is what narrows the finding rather than the shape of the number.
+ *
  * Restating the exclusion in the sibling standards was the alternative. It
  * duplicates one knowledge item across three surfaces, which the root
  * instruction file forbids, and pointing is not available because the surface
@@ -87,6 +107,12 @@ export interface TableFinding {
   readonly rows: number
 }
 
+export interface BulletFinding {
+  readonly line: number
+  /** Weight as folded, so a report says how far past the checkpoint it sits. */
+  readonly characters: number
+}
+
 export interface ProvenanceFinding {
   readonly line: number
   readonly kind: ProvenanceKind
@@ -116,6 +142,8 @@ export interface EntryReport {
   readonly catalogTables: readonly TableFinding[]
   /** Empty for an entry no standard bans a change narrative in. */
   readonly provenance: readonly ProvenanceFinding[]
+  /** Empty for the same reason `provenance` is, and under the same folder. */
+  readonly heavyBullets: readonly BulletFinding[]
 }
 
 interface BodyLine {
@@ -302,6 +330,60 @@ function catalogTables(lines: readonly BodyLine[]): TableFinding[] {
   return findings
 }
 
+/**
+ * Finds the top-level bullets carrying more than a decision.
+ *
+ * A nested item is left out rather than folded into its parent, since the
+ * checkpoint asks what one bullet carries and a child carries its own. Lines
+ * continuing a bullet do fold in, so a heavy bullet cannot fall under the
+ * checkpoint by being wrapped across two source lines. Fenced blocks are
+ * skipped for the reason the scans above skip them: a sample an entry displays
+ * is not a claim it makes.
+ */
+function heavyBullets(lines: readonly BodyLine[]): BulletFinding[] {
+  const findings: BulletFinding[] = []
+  let open: BulletFinding | null = null
+  let fenced = false
+
+  const close = (): void => {
+    if (open && open.characters > BULLET_CHECKPOINT) findings.push(open)
+    open = null
+  }
+
+  for (const line of lines) {
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      close()
+      continue
+    }
+    if (fenced) continue
+
+    const item = line.text.match(LIST_ITEM)
+    const text = line.text.trim()
+
+    if (item) {
+      close()
+      if (item[1].length === 0) {
+        open = { line: line.number, characters: text.length }
+      }
+      continue
+    }
+
+    if (text === '' || HEADING.test(line.text) || TABLE_ROW.test(line.text)) {
+      close()
+      continue
+    }
+
+    // The joining space a wrapped line would have carried, so folding two
+    // source lines measures what one unwrapped line would have.
+    if (open) open = { ...open, characters: open.characters + text.length + 1 }
+  }
+
+  close()
+
+  return findings
+}
+
 /**
  * Finds the markers narrating a change rather than describing the domain.
  *
@@ -365,6 +447,7 @@ export function measureEntry(
     longestRunLine: run.line,
     catalogTables: catalogTables(lines),
     provenance: governsContent ? provenance(lines) : [],
+    heavyBullets: governsContent ? heavyBullets(lines) : [],
   }
 }
 

package/standards/context.md

@@ -104,8 +104,11 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
 - Both checkpoints count rendered lines, so wrap each source line at 80 columns and sum the heights. Source lines undercount an entry authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. Counting the two checkpoints in different units would put a file measured one way beside a run measured another.
 - Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides. Mixing prose with the list, or nesting levels inside it, ends the exemption at any weight.
+- Past roughly 400 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, check whether the incident that motivated the decision sits beside the decision itself. Keep the current design and the alternative that lost, and move the incident to the change that introduced it, the issue that tracked it, or the research record behind it. The number is a checkpoint like the two above, and a bullet reading well past it means the number is wrong rather than the rule.
+- Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
+- Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.
 - Split into a folder (`.claude/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
 - Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
 - Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and turns a one-line edit into a whole-file rewrite that conflicts with any sibling branch. This is what forced the split above.