@erclx/aitk 1.2.0 → 1.4.0

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

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

package/docs/agents/commands.md

@@ -37,7 +37,8 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                     |
 | `aitk teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                       |
 | `aitk records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                              |
-| `aitk records push`        | Commit the eight backed record folders and push them to a private records remote (`--json`)                                               |
+| `aitk records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                              |
+| `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                   |
 | `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                            |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                    |

package/docs/agents/index.md

@@ -21,7 +21,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
-- [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, backing the folders to a private remote, and which root each kind defaults to
+- [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on

package/docs/agents/output-shape.md

@@ -46,6 +46,19 @@ Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to
 
 `--json` and `--names` keep stdout clean and machine-readable. The frame still renders on stderr (open, banner, close) so the stream discipline is consistent across modes. Consumers that only read stdout see pure data.
 
+## Color
+
+Escape sequences reach a destination that renders them and nowhere else. The question is asked per stream rather than once for the process, so a run piping its data while keeping a terminal on stderr still gets color on the frame.
+
+Either condition alone turns color off:
+
+- `NO_COLOR` is set to any non-empty value, whatever that value says
+- The destination is not a terminal, which covers a pipe, a file, and a captured session
+
+The frame survives both. `┌`, `│`, `├`, `└`, and the `✓ ! + - ✗` marks are structure rather than color, and they are what lets a captured run still read as one block. A caller wanting neither the frame nor the color reads `--json` instead.
+
+Terminal control is a separate question this section does not cover. The cursor and key sequences an interactive prompt writes run only where a terminal already exists.
+
 ## Process exit
 
 A command action sets `process.exitCode` and returns. Calling `process.exit()` there ends the process before a stdout write drains, which truncates piped output at the 64K pipe buffer while still reporting the right exit code. Redirecting to a file hides the truncation, so it surfaces only through a pipe, which is what a check has to use to catch it.

package/docs/agents/records.md

@@ -1,6 +1,6 @@
 ---
 title: Records
-description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, backing the folders to a private remote, and which root each kind defaults to
+description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 ---
 
 # Records
@@ -72,6 +72,34 @@ aitk records validate plans --json | jq -r '.findings[] | "\(.kind): \(.subject)
 
 For the shapes each check enforces, see `.claude/standards/plan.md`, `.claude/standards/groundwork.md`, `.claude/standards/intake.md`, `.claude/standards/memory.md`, and `.claude/standards/standard.md`.
 
+## Size
+
+`aitk records size` reports what each record folder holds and how much of it is recent. It reads the nine backed folders named under Push and pull, plus `.claude/.tmp`, and it gates nothing.
+
+```bash
+aitk records size
+aitk records size --json
+```
+
+| Option          | Behavior                                      |
+| --------------- | --------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout       |
+| `--root <path>` | Project root, defaulting to the main worktree |
+
+The table carries one row per folder that exists, heaviest first, with the file count, the bytes, a count for each growth window, and the dates of the least and most recently written file. Those dates render in the machine's local time, which is the calendar day whoever wrote the file was living in, and the reading is per-machine already. Folders that do not exist are named on one line below it rather than printed as rows of zeros. The record a `--json` call emits carries every folder either way, each with a `present` flag, so a caller reading the record gets a stable set of keys and can tell an absent folder from one the reading skipped.
+
+Ordering by weight is what makes the reading worth taking. A folder listed alphabetically hides behind its neighbors, and the row a reader came for is the one that grew.
+
+The reading carries two windows rather than one, at 7 and 30 days. A single window cannot separate a folder growing steadily from one that took a single batch: a folder whose 7-day count is most of its 30-day count moved in one pass, and one where the two are proportional is growing at a rate.
+
+Nothing fails on a number here. A record folder has no correct size, so the reading is a number to notice rather than a threshold to gate, and the point of the verb is that the next reading is taken by a command instead of by someone remembering to count the folder. The memory pen went from 44 entries to 236 between two readings taken by hand two weeks apart, which is the measurement this replaces.
+
+`.claude/.tmp` is read here and skipped by a backup, because deletable without loss is not the same as empty. The routing handoffs and the memory archive both sit there and both accumulate. `.claude/.records.git` stays out because it is the backup history rather than a record, and `.claude/worktrees/` stays out because each entry is a checkout of the project with its own removal verb, and one of them outweighs every record folder combined.
+
+The window counts read `mtime`, so what they report is a file written inside the window rather than one created there. An entry edited long after it landed reads as recent, which overstates growth and never understates it, and these folders are append-mostly so the two readings agree on nearly every file. The one reading that is wrong rather than early is a machine restored by `aitk records pull`, which resets the work tree hard and re-dates every file it writes, so a window taken there counts the restore. Nothing on the filesystem separates the two, since a restored file is new by every stamp it carries.
+
+Exit codes: `0` the reading completed, `1` refused. The one refusal is `no-folder`, raised when the root holds no `.claude` directory at all.
+
 ## Push and pull
 
 `aitk records push` commits the backed record folders to a private remote and pushes them. `aitk records pull` fetches the other direction and writes them back. Both take `--json` and `--root` the way `validate` does, and both exit `0` on agreement and `1` on a refusal.
@@ -82,9 +110,9 @@ aitk records push --json
 aitk records pull
 ```
 
-The backed folders are `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, and `tasks`, all under `.claude/`. They are the gitignored Claude group minus `.claude/.tmp`, which is deletable without loss, and `.claude/worktrees/`, whose contents belong to the project repository already. The list is a constant rather than configuration, matching the four folder names `validate` hardcodes.
+The backed folders are `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, `tasks`, and `teach`, all under `.claude/`. They are the gitignored Claude group minus `.claude/.tmp`, which is deletable without loss, and `.claude/worktrees/`, whose contents belong to the project repository already. The list is a constant rather than configuration, matching the four folder names `validate` hardcodes.
 
-Records are gitignored by design, so the history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the eight folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched.
+Records are gitignored by design, so the history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the nine folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched.
 
 ### Setup
 
@@ -113,7 +141,7 @@ Point it at a private repository, and at one that is not a remote of the project
 | `local-ahead`       | `pull` found local commits that never reached the origin                             |
 | `git-failed`        | A git call failed, with its stderr in the message                                    |
 
-The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding none of the eight has nothing to lose, so a restore onto a fresh checkout runs straight through.
+The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding none of the nine has nothing to lose, so a restore onto a fresh checkout runs straight through.
 
 ### When it runs
 

package/docs/ai-workflow.md

@@ -93,10 +93,12 @@ An execution that picks other than the suggestion rewrites the `- Suggested:` li
 
 `aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, `memory`, and `teach`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all five folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
-`aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Eight of them are backed: `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, and `tasks`. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
+`aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Nine of them are backed: `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, `tasks`, and `teach`. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
 
 A person points it at a private repository once and both verbs refuse until they have, and `push` refuses when that origin is also a remote of the project, since the payload is the memory pen and the groundwork trails. `.husky/post-merge` runs the push after its archive loop, on every merge rather than only on one that closed a task. See [records](agents/records.md) for the refusal table.
 
+`aitk records size` reports what each of these folders holds, heaviest first, along with `.claude/.tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: the memory pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
+
 A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans-archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. Both folders are gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 
 The sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.

package/docs/visual-design-workflow.md

@@ -24,6 +24,8 @@ The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table
 
 The `aitk:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `aitk design render` writes an HTML plus CSS preview to `.claude/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
 
+A cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
+
 ### Tools
 
 - None beyond Claude Code itself

package/package.json

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

package/src/cli.ts

@@ -28,12 +28,12 @@ import { register as sessions } from '@/commands/sessions'
 import { register as audits } from '@/commands/audits'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
-
-const GREY = '\x1b[0;90m'
-const WHITE = '\x1b[1;37m'
-const NC = '\x1b[0m'
+import { palette } from '@/ui'
 
 function showHelp(): void {
+  // The help text is the one framed surface written to stdout, so it asks
+  // about that stream rather than the stderr every other writer here uses.
+  const { GREY, NC, WHITE } = palette(process.stdout)
   const lines = [
     `${GREY}┌${NC}`,
     `${GREY}├${NC} ${WHITE}Usage:${NC} aitk [command]`,
@@ -61,7 +61,7 @@ function showHelp(): void {
     `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
     `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
-    `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, push, pull)${NC}`,
+    `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
@@ -101,6 +101,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk context audit --json`,
     `${GREY}│${NC}    aitk markdown audit .claude/rules --json`,
     `${GREY}│${NC}    aitk records validate plans`,
+    `${GREY}│${NC}    aitk records size --json`,
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
     `${GREY}│${NC}    aitk audits run --json`,

package/src/commands/claude.ts

@@ -44,16 +44,13 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   pipeOutput,
   plural,
   select,
 } from '@/ui'
 import { describeSkew, readSkew, type SkewReport } from '@/version/skew'
 
-const GREEN = '\x1b[0;32m'
-const GREY = '\x1b[0;90m'
-const NC = '\x1b[0m'
-
 interface SeedsListOptions {
   readonly json?: boolean
   readonly names?: boolean
@@ -266,6 +263,7 @@ export function register(program: Command): void {
 }
 
 function succeed(message: string): number {
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(`${GREEN}✓ ${message}${NC}\n`)
   return 0
@@ -472,6 +470,7 @@ async function runSeedsList(opts: SeedsListOptions): Promise<number> {
     return 0
   }
 
+  const { GREY, NC } = palette(process.stderr)
   intro('aitk claude')
   logStep('Seed docs')
   for (const listing of listings) {
@@ -531,6 +530,7 @@ async function runSkillsDrift(
     // is the moment a skew warning is worth most, since an old binary is one
     // reason the cache and the CLI disagree in the first place.
     if (skew.state === 'behind') {
+      const { GREY, NC } = palette(process.stderr)
       process.stderr.write(`${GREY}${describeSkew(skew)}${NC}\n`)
     }
   }

package/src/commands/design.ts

@@ -2,12 +2,7 @@ import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { renderDesignDoc } from '@/design/render'
-
-const GREY = '\x1b[0;90m'
-const WHITE = '\x1b[1;37m'
-const RED = '\x1b[0;31m'
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
+import { palette } from '@/ui'
 
 export function register(program: Command): void {
   const design = program
@@ -22,6 +17,7 @@ export function register(program: Command): void {
     .action((opts: { source: string; out: string }) => {
       const sourcePath = resolve(process.cwd(), opts.source)
       const outDir = resolve(process.cwd(), opts.out)
+      const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
       if (!existsSync(sourcePath)) {
         process.stderr.write(
           `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${opts.source} not found\n${GREY}└${NC}\n`,

package/src/commands/feedback.ts

@@ -4,10 +4,7 @@ import type { Command } from 'commander'
 import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
 import { PROJECT_ROOT } from '@/project-root'
 import { createGithubIssue } from '@/github'
-import { frameError, frameSuccess } from '@/ui'
-
-const YELLOW = '\x1b[0;33m'
-const NC = '\x1b[0m'
+import { frameError, frameSuccess, palette } from '@/ui'
 
 function readStdin(): Promise<string> {
   return new Promise((resolveStream, rejectStream) => {
@@ -88,6 +85,7 @@ export function register(program: Command): void {
           process.exitCode = 1
           return
         }
+        const { NC, YELLOW } = palette(process.stderr)
         process.stderr.write(
           `${YELLOW}! gh unavailable, wrote local scratch instead${NC}\n`,
         )

package/src/commands/gov.ts

@@ -30,12 +30,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 const PAYLOAD_REL = join('.claude', '.tmp', 'gov', 'rules.md')
 const RULES_REL = join('.claude', 'rules')
 
@@ -461,6 +459,7 @@ async function runInstall(
     )
   }
 
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(`${GREEN}✓ Rules installed${NC}\n`)
   return 0
@@ -510,6 +509,7 @@ async function runBuild(target: string): Promise<number> {
   await writeFile(output, buildRulesPayload(files))
   logAdd(PAYLOAD_REL)
 
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(
     `${GREEN}✓ Rules built (${files.length} rules → ${PAYLOAD_REL})${NC}\n`,

package/src/commands/init.ts

@@ -6,11 +6,7 @@ import { type InitFlags, parseSkip, planInit } from '@/init/plan'
 import { runDomains } from '@/init/run'
 import { buildSteps } from '@/init/steps'
 import { resolveTarget } from '@/target'
-import { intro, logInfo, logStep, logWarn, outro, select } from '@/ui'
-
-const GREEN = '\x1b[0;32m'
-const YELLOW = '\x1b[0;33m'
-const NC = '\x1b[0m'
+import { intro, logInfo, logStep, logWarn, outro, palette, select } from '@/ui'
 
 interface InitOptions {
   /** Always present: the option falls back to `DEFAULT_STACK`. */
@@ -107,6 +103,8 @@ async function runInit(
   outro()
   process.stderr.write('\n')
 
+  const { GREEN, NC, YELLOW } = palette(process.stderr)
+
   if (failed.length === 0) {
     process.stderr.write(
       `${GREEN}✓ Project initialized (${plan.total} domains)${NC}\n`,

package/src/commands/records.ts

@@ -1,11 +1,13 @@
 import type { Command } from 'commander'
+import { BACKED_FOLDERS, pullRecords, pushRecords } from '@/records/backup'
 import {
-  BACKED_FOLDERS,
-  type PullOutcome,
-  pullRecords,
-  type PushOutcome,
-  pushRecords,
-} from '@/records/backup'
+  type FolderSize,
+  formatBytes,
+  GROWTH_WINDOWS,
+  SIZED_FOLDERS,
+  type SizeOutcome,
+  sizeRecords,
+} from '@/records/size'
 import {
   type Finding,
   isRecordKind,
@@ -23,6 +25,7 @@ import {
   logWarn,
   outro,
   pipeOutput,
+  plural,
 } from '@/ui'
 import { currentWorktreeRoot, mainWorktreeRoot } from '@/worktree'
 
@@ -87,6 +90,41 @@ export function register(program: Command): void {
       process.exitCode = await runValidate(kind, opts)
     })
 
+  records
+    .command('size')
+    .description('Report what each record folder holds and how much is recent')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Folders read under .claude/:',
+        `  ${SIZED_FOLDERS.join(', ')}`,
+        '',
+        'Exit codes:',
+        '  0  the reading completed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It gates nothing. A record folder has no correct size, so the reading is',
+        'a number to notice rather than a threshold to fail, and a session takes it',
+        `by running this rather than by counting the folder. The ${GROWTH_WINDOWS.join(
+          ' and ',
+        )} day`,
+        'counts read mtime, so a file rewritten long after it landed reads as recent,',
+        'and a machine restored by records pull reads its whole tree as one week old.',
+        '',
+        'Examples:',
+        '  aitk records size',
+        '  aitk records size --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: BackupCommandOptions) => {
+      process.exitCode = await runSize(opts)
+    })
+
   records
     .command('push')
     .description(
@@ -149,6 +187,99 @@ function backupHelp(verb: 'push' | 'pull'): string {
   ].join('\n')
 }
 
+async function runSize(opts: BackupCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await sizeRecords(root)
+
+  if (!outcome.ok)
+    return reportRefusal('aitk records size', outcome, opts.json ?? false)
+
+  if (opts.json ?? false) {
+    process.stdout.write(`${JSON.stringify(outcome)}\n`)
+    return 0
+  }
+
+  reportSize(outcome)
+  return 0
+}
+
+/** Widest cell in the column, so a row lines up against the header as well. */
+function columnWidth(header: string, cells: readonly string[]): number {
+  return Math.max(header.length, ...cells.map((cell) => cell.length))
+}
+
+function sizeRow(entry: FolderSize): string[] {
+  return [
+    entry.folder,
+    String(entry.files),
+    formatBytes(entry.bytes),
+    ...entry.touched.map((window) => String(window.files)),
+    entry.oldest ?? '',
+    entry.newest ?? '',
+  ]
+}
+
+/**
+ * Renders the present folders as a table, heaviest first.
+ *
+ * The order is what makes the reading worth taking. A folder listed
+ * alphabetically hides behind its neighbors, and the one that grew is the row
+ * a reader came for, so it leads.
+ */
+function reportSize(outcome: Extract<SizeOutcome, { ok: true }>): void {
+  const present = outcome.folders
+    .filter((entry) => entry.present)
+    .toSorted((left, right) => right.files - left.files)
+  const absent = outcome.folders
+    .filter((entry) => !entry.present)
+    .map((entry) => entry.folder)
+
+  intro('aitk records size')
+  logStep('Folders')
+
+  if (present.length === 0) {
+    logInfo('none of the record folders exist yet')
+  } else {
+    const headers = [
+      'folder',
+      'files',
+      'size',
+      ...GROWTH_WINDOWS.map((days) => `${days}d`),
+      'oldest',
+      'newest',
+    ]
+    const rows = present.map(sizeRow)
+    const widths = headers.map((header, column) =>
+      columnWidth(
+        header,
+        rows.map((row) => row[column]),
+      ),
+    )
+
+    // The name column reads as a list and the rest as numbers, so one is
+    // left-aligned and the others are not.
+    const render = (cells: readonly string[]): string =>
+      cells
+        .map((cell, column) =>
+          column === 0
+            ? cell.padEnd(widths[column])
+            : cell.padStart(widths[column]),
+        )
+        .join('  ')
+        .trimEnd()
+
+    pipeOutput([render(headers), ...rows.map(render)].join('\n'))
+  }
+
+  if (absent.length > 0) logInfo(`absent: ${absent.join(', ')}`)
+
+  logStep('Total')
+  logInfo(
+    `${plural(outcome.files, 'file')}, ${formatBytes(outcome.bytes)} across ${plural(present.length, 'folder')}`,
+  )
+  outro()
+}
+
 async function runPush(opts: BackupCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
   const outcome = await pushRecords(root)
@@ -197,9 +328,16 @@ async function runPull(opts: BackupCommandOptions): Promise<number> {
   return 0
 }
 
+/**
+ * Reports a refusal from any of the three verbs that carry one.
+ *
+ * The parameter is structural rather than the union of their outcome types,
+ * because the three refusal vocabularies are separate lists and naming them all
+ * here would grow with every verb added.
+ */
 function reportRefusal(
   banner: string,
-  outcome: Extract<PushOutcome | PullOutcome, { ok: false }>,
+  outcome: { readonly reason: string; readonly message: string },
   emitJson: boolean,
 ): number {
   if (emitJson) {

package/src/commands/slides.ts

@@ -5,12 +5,7 @@ import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
 import { renderSlidesDoc } from '@/slides/render'
 import type { Variant } from '@/slides/styles'
-import { intro, outro } from '@/ui'
-
-const GREY = '\x1b[0;90m'
-const GREEN = '\x1b[0;32m'
-const RED = '\x1b[0;31m'
-const NC = '\x1b[0m'
+import { intro, outro, palette } from '@/ui'
 
 export function register(program: Command): void {
   const slides = program
@@ -44,6 +39,7 @@ export function register(program: Command): void {
           }
           const variant = parseVariant(opts.variant)
           const mirror = resolveMirror(opts.mirror)
+          const { GREEN, GREY, NC, RED } = palette(process.stderr)
           intro('Render slides')
           const result = await renderSlidesDoc(sourcePath, outDir, {
             variant,
@@ -81,6 +77,7 @@ export function register(program: Command): void {
         process.stdout.write(`${JSON.stringify(LAYOUTS)}\n`)
         return
       }
+      const { GREEN, GREY, NC } = palette(process.stderr)
       intro('Slide layouts')
       for (const layout of LAYOUTS) {
         process.stderr.write(
@@ -121,6 +118,7 @@ function fail(message: string): never {
  */
 function reportFailure(error: unknown): void {
   if (!(error instanceof SlidesError)) throw error
+  const { GREY, NC, RED } = palette(process.stderr)
   process.stderr.write(
     `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${error.message}\n${GREY}└${NC}\n`,
   )

package/src/commands/snippets.ts

@@ -21,12 +21,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 const SNIPPETS_REL = '.claude/snippets'
 
 const PASS_THROUGH_VERBS = ['create'] as const
@@ -180,6 +178,7 @@ async function runInstall(
   }
   await recordStamp(createSnippetsAdapter(PROJECT_ROOT), resolved, new Date())
 
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(`${GREEN}✓ Snippets installed${NC}\n`)
   return 0

package/src/commands/standards.ts

@@ -21,13 +21,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const GREY = '\x1b[0;90m'
-const NC = '\x1b[0m'
-
 interface InstallOptions {
   /** Always present: the option falls back to `ALL_SELECTION`. */
   readonly only: string
@@ -196,6 +193,7 @@ async function runInstall(target: string, selection: string): Promise<number> {
   await recordStamp(createStandardsAdapter(PROJECT_ROOT), resolved, new Date())
 
   outro()
+  const { GREEN, GREY, NC } = palette(process.stderr)
   process.stderr.write(
     `\n${GREEN}✓ Standards installed${NC} ${GREY}(${files.length} files)${NC}\n`,
   )

package/src/commands/sync.ts

@@ -29,13 +29,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
 } from '@/ui'
 import { describeSkew } from '@/version/skew'
 
-const GREY = '\x1b[0;90m'
-const YELLOW = '\x1b[0;33m'
-const NC = '\x1b[0m'
-
 const SYNC_ARGS: Record<SyncDomain, readonly string[]> = {
   standards: ['standards', 'sync'],
   snippets: ['snippets', 'sync'],
@@ -180,6 +177,7 @@ function renderCheck(report: CheckReport): void {
   )
   if (uncovered.length === 0) return
 
+  const { GREY, NC } = palette(process.stderr)
   process.stderr.write(
     `${GREY}Unstamped: ${uncovered.join(', ')}. Run the matching sync to record one.${NC}\n`,
   )
@@ -338,6 +336,7 @@ async function runSync(target: string): Promise<number> {
   if (typeof resolved === 'number') return resolved
 
   const git = createGitRunner(resolved)
+  const { GREY, NC, YELLOW } = palette(process.stderr)
 
   logStep('Checking working tree')
   if (!isTreeClean(await git.status([]))) {

package/src/commands/tooling.ts

@@ -28,12 +28,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 const PASS_THROUGH_VERBS = ['ref', 'create', 'verify'] as const
 
 interface SyncOptions {
@@ -256,6 +254,7 @@ async function runSync(
   report(result, includeReferences)
 
   const mode = resolveWriteMode(opts)
+  const { GREEN, NC } = palette(process.stderr)
 
   if (result.totalChanges === 0) {
     // The stamp is a write like any other, so a run with no authority to write