@polintpro/proposit-core 0.2.3 → 0.2.4

package/skills/proposit-core/docs/architecture.md

@@ -0,0 +1,256 @@
+# Architecture & Internals
+
+Reference for proposit-core internal design. Covers class structure, data representations, invariants, and implementation details.
+
+---
+
+## Class Hierarchy
+
+```
+ArgumentEngine
+  ├─ VariableManager (shared, owned by engine)
+  └─ PremiseManager (one per premise, receives shared VariableManager)
+       └─ ExpressionManager (expression tree)
+```
+
+| Class               | File                                | Exported?        |
+| ------------------- | ----------------------------------- | ---------------- |
+| `ArgumentEngine`    | `src/lib/core/ArgumentEngine.ts`    | Yes (public API) |
+| `PremiseManager`    | `src/lib/core/PremiseManager.ts`    | Yes (public API) |
+| `ExpressionManager` | `src/lib/core/ExpressionManager.ts` | No (internal)    |
+| `VariableManager`   | `src/lib/core/VariableManager.ts`   | No (internal)    |
+| `ChangeCollector`   | `src/lib/core/ChangeCollector.ts`   | No (internal)    |
+
+- `ArgumentEngine` owns a single `VariableManager` instance and passes it by reference to every `PremiseManager` it creates. All premises share the same variable registry.
+- Each `PremiseManager` owns one `ExpressionManager` for its expression tree.
+- Constructor: `new ArgumentEngine(argument, options?)` where `options?: { checksumConfig?: TCoreChecksumConfig }`.
+
+---
+
+## Expression Tree Representation
+
+Three internal maps in `ExpressionManager`:
+
+```typescript
+expressions: Map<string, TExpressionInput>
+// Main store. Entities lack checksums; checksums attached lazily by getters.
+
+childExpressionIdsByParentId: Map<string | null, Set<string>>
+// Fast child lookup. The null key holds root expression IDs.
+
+childPositionsByParentId: Map<string | null, Set<number>>
+// Tracks which positions are occupied under each parent.
+```
+
+Expressions are **immutable value objects**. To move one, delete and re-insert or use internal `reparent()`.
+
+### Expression Types (Discriminated Union)
+
+`TPropositionalExpression` narrows on `type`:
+
+| `type`       | Extra fields                         | Notes                                   |
+| ------------ | ------------------------------------ | --------------------------------------- |
+| `"variable"` | `variableId: string`                 | Leaf node referencing a variable        |
+| `"operator"` | `operator: TCoreLogicalOperatorType` | `and`, `or`, `not`, `implies`, `iff`    |
+| `"formula"`  | (none)                               | Transparent unary wrapper (parentheses) |
+
+### Input Types (Distributive Omit)
+
+These preserve discriminated-union narrowing via conditional type distribution:
+
+- `TExpressionInput` -- `Omit<TPropositionalExpression, "checksum">` (storage type)
+- `TExpressionWithoutPosition` -- `Omit<TPropositionalExpression, "position" | "checksum">` (for `appendExpression`, `addExpressionRelative`)
+- `TExpressionUpdate` -- `{ position?, variableId?, operator? }` (for `updateExpression`)
+
+---
+
+## Midpoint-Based Positions
+
+File: `src/lib/utils/position.ts`
+
+```typescript
+POSITION_MIN = 0
+POSITION_MAX = Number.MAX_SAFE_INTEGER // 2^53 - 1
+POSITION_INITIAL = Math.floor(POSITION_MAX / 2)
+
+midpoint(a, b) = a + (b - a) / 2 // overflow-safe
+```
+
+| Scenario                       | Position                                  |
+| ------------------------------ | ----------------------------------------- |
+| First child (no siblings)      | `POSITION_INITIAL`                        |
+| Append (after last sibling)    | `midpoint(last.position, POSITION_MAX)`   |
+| Prepend (before first sibling) | `midpoint(POSITION_MIN, first.position)`  |
+| Between two siblings           | `midpoint(left.position, right.position)` |
+
+Approximately 52 bisections at the same insertion point before losing IEEE 754 double precision.
+
+### Intent-Based Insertion API
+
+- `appendExpression(parentId, expression)` -- appends as last child, position computed automatically.
+- `addExpressionRelative(siblingId, "before" | "after", expression)` -- inserts relative to an existing sibling.
+- `addExpression(expression)` -- low-level escape hatch with explicit position.
+
+All three exist on both `ExpressionManager` and `PremiseManager`.
+
+---
+
+## Root-Only Operators
+
+`implies` and `iff` must always have `parentId: null`. They cannot be nested inside another expression. Enforced in both `addExpression` and `insertExpression`. Attempting to add them with a non-null `parentId` throws.
+
+---
+
+## Formula Nodes
+
+The `formula` expression type is a **transparent unary wrapper** -- equivalent to parentheses around its single child.
+
+- Must have exactly one child.
+- Collapse rules apply identically to `formula` and `operator` nodes.
+- During evaluation, `formula` nodes propagate their child's value transparently.
+
+---
+
+## Operator Collapse
+
+Triggered by `removeExpression(id, deleteSubtree)`. After removal, `collapseIfNeeded(parentId)` runs on the parent:
+
+| Children remaining | Action                                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| 0                  | Delete the operator/formula. Recurse to grandparent.                                                                                       |
+| 1                  | Delete the operator/formula. Promote surviving child (inherits `parentId` + `position`). No recursion (grandparent child count unchanged). |
+| 2+                 | No action.                                                                                                                                 |
+
+### removeExpression Behavior
+
+The `deleteSubtree` parameter (required boolean) controls behavior:
+
+- **`deleteSubtree: true`** -- Removes expression and all descendants. Then runs `collapseIfNeeded(parentId)`.
+- **`deleteSubtree: false`** -- Removes expression and promotes its single child into its slot (inheriting `parentId` and `position`). Throws if >1 child. Validates that root-only operators (`implies`/`iff`) are not promoted into non-root positions. No collapse runs after promotion. Leaf removal with `deleteSubtree: false` runs collapse on the parent (same as `true`).
+
+---
+
+## insertExpression Mutation Order
+
+`reparent(rightNodeId, ...)` runs **before** `reparent(leftNodeId, ...)`.
+
+This handles the case where the right node is a descendant of the left node's subtree -- it must be detached first to avoid corrupting the tree.
+
+---
+
+## Premise Types
+
+Derived dynamically from the root expression -- not stored on disk.
+
+| Method           | Returns `true` when                                                        | Used for                           |
+| ---------------- | -------------------------------------------------------------------------- | ---------------------------------- |
+| `isInference()`  | Root is `implies` or `iff`                                                 | Supporting/conclusion chain        |
+| `isConstraint()` | Root is anything else (`variable`, `not`, `and`, `or`) or premise is empty | Restricting admissible assignments |
+
+---
+
+## Derived Supporting Premises
+
+Supporting premises are **not explicitly managed**. The methods `addSupportingPremise()` and `removeSupportingPremise()` were removed.
+
+**Rule:** Any inference premise that is not the conclusion is automatically considered supporting.
+
+`TCoreArgumentRoleState` contains only `{ conclusionPremiseId?: string }`. `listSupportingPremises()` derives the list dynamically on each call from the current set of premises.
+
+---
+
+## Auto-Conclusion Assignment
+
+When the first premise is added to an `ArgumentEngine` (via `createPremise` or `createPremiseWithId`) and no conclusion is currently set, that premise is automatically designated as the conclusion.
+
+- Auto-assignment is reflected in the mutation changeset.
+- `setConclusionPremise()` overrides auto-assignment.
+- Removing or clearing the conclusion re-enables auto-assignment for the next premise created.
+
+---
+
+## Mutation Changesets
+
+Every mutating method on `PremiseManager` and `ArgumentEngine` returns `TCoreMutationResult<T>`:
+
+```typescript
+interface TCoreMutationResult<T> {
+    result: T // direct answer (e.g. removed expression, new role state)
+    changes: TCoreChangeset // all side effects
+}
+```
+
+### TCoreChangeset Structure
+
+```typescript
+interface TCoreChangeset {
+    expressions?: TCoreEntityChanges<TPropositionalExpression>
+    variables?: TCoreEntityChanges<TPropositionalVariable>
+    premises?: TCoreEntityChanges<TCorePremise>
+    roles?: TCoreArgumentRoleState // present only when roles changed
+    argument?: TCoreArgument // present only when argument metadata changed
+}
+
+interface TCoreEntityChanges<T> {
+    added: T[]
+    modified: T[]
+    removed: T[]
+}
+```
+
+### Internal Flow
+
+1. `ChangeCollector` (not exported) accumulates entity changes during a mutation.
+2. `toChangeset()` produces `TCoreRawChangeset` (uses input types without checksums: `TExpressionInput`, `TVariableInput`).
+3. `attachChangesetChecksums()` converts to `TCoreChangeset` with checksums attached before returning to callers.
+
+---
+
+## Checksum System
+
+Per-entity checksums provide lightweight change detection without deep comparison.
+
+### How It Works
+
+- All entity types carry a required `checksum: string` field in their schemas.
+- Internally, managers store entities **without checksums** using input types (`TExpressionInput`, `TVariableInput`).
+- Checksums are **attached lazily** by getters (`getExpression()`, `getVariables()`, `getArgument()`, `toData()`) and in changeset outputs.
+- `PremiseManager.checksum()` and `ArgumentEngine.checksum()` use dirty flags for lazy recomputation.
+
+### Checksum Utilities
+
+File: `src/lib/core/checksum.ts`
+
+| Function                                     | Description                                          |
+| -------------------------------------------- | ---------------------------------------------------- |
+| `computeHash(input: string): string`         | FNV-1a 32-bit hash. Returns 8-char hex string.       |
+| `canonicalSerialize(value: unknown): string` | Deterministic JSON with sorted keys at all levels.   |
+| `entityChecksum(entity, fields): string`     | Picks specified fields (sorted), serializes, hashes. |
+
+### Configuration
+
+File: `src/lib/consts.ts`
+
+- `DEFAULT_CHECKSUM_CONFIG` -- defines which fields are hashed per entity type.
+- `createChecksumConfig(additional)` -- merges additional fields into defaults (union, not replace).
+- `ArgumentEngine` constructor accepts `options?: { checksumConfig?: TCoreChecksumConfig }`.
+
+`TCoreChecksumConfig` fields (all `Set<string>`, all optional):
+
+- `expressionFields` -- default: `id`, `type`, `parentId`, `position`, `argumentId`, `argumentVersion`, `variableId`, `operator`
+- `variableFields` -- default: `id`, `symbol`, `argumentId`, `argumentVersion`
+- `premiseFields` -- default: `id`, `rootExpressionId`
+- `argumentFields` -- default: `id`, `version`
+- `roleFields` -- default: `conclusionPremiseId`
+
+---
+
+## ESM Import Requirements
+
+The project uses `moduleResolution: "bundler"` in `tsconfig.json` but `src/cli.ts` is compiled and run directly by Node.js ESM.
+
+**Rules:**
+
+- All relative imports in `src/cli/` and `src/lib/` must end in `.js`.
+- Directory imports must use the explicit index path: `schemata/index.js` not `schemata/`.
+- Critical: `src/lib/utils/` (directory) and `src/lib/utils.ts` (file) both compile to `dist/lib/`, and Node.js ESM resolves the directory first if no extension is given.

package/skills/proposit-core/docs/cli.md

@@ -0,0 +1,304 @@
+# proposit-core CLI Reference
+
+## Running the CLI
+
+```bash
+# Local development (builds first, then runs)
+pnpm run build
+pnpm cli -- --help
+
+# Installed globally
+proposit-core --help
+```
+
+Always build before running the CLI locally. The entry point is `src/cli.ts`, compiled to `dist/cli.js`.
+
+## Routing
+
+**Source:** `src/cli.ts`, `src/cli/router.ts`
+
+`argv[2]` is inspected by `isNamedCommand()` to decide the routing path:
+
+**Named commands** (handled by top-level Commander program):
+
+- `help`, `--help`, `-h`
+- `version`, `--version`, `-V`
+- `arguments`
+- `diff`
+
+**Version-scoped commands** (everything else):
+
+- `argv[2]` is treated as `<argument_id>`
+- `argv[3]` is the version selector
+- After `resolveVersion()`, a sub-Commander program is built with the remaining args
+- Registered sub-commands: `show`, `render`, `roles`, `variables`, `premises`, `expressions`, `analysis`
+
+If `argv[2]` is undefined, `isNamedCommand()` returns `true` (falls through to Commander's help).
+
+## Version Selectors
+
+**Source:** `src/cli/router.ts`
+
+`resolveVersion(argumentId, versionArg)` accepts:
+
+| Selector                           | Behavior                                                                           |
+| ---------------------------------- | ---------------------------------------------------------------------------------- |
+| `"latest"`                         | Max version number found in the argument directory                                 |
+| `"last-published"`                 | Highest published version (iterates from highest to lowest; exits 1 if none found) |
+| Integer string (e.g. `"0"`, `"3"`) | Exact version number (must be non-negative integer; must exist on disk)            |
+
+Exits with error if no versions exist for the argument, or if the specified version is not found.
+
+## State Storage Layout
+
+**Source:** `src/cli/config.ts`
+
+Root directory: `$PROPOSIT_HOME` (default: `~/.proposit-core`)
+
+```
+$PROPOSIT_HOME/
+  arguments/
+    <argument-id>/
+      meta.json            # { id, title, description }
+      <version>/           # 0, 1, 2, ...
+        meta.json          # { version, createdAt, published, publishedAt? }
+        variables.json     # TCorePropositionalVariable[]
+        roles.json         # { conclusionPremiseId? }
+        premises/
+          <premise-id>/
+            meta.json      # { id, title? }
+            data.json      # { rootExpressionId?, variables: id[], expressions[] }
+        <analysis>.json    # { argumentId, argumentVersion, assignments, rejectedExpressionIds }
+```
+
+**Reserved filenames** (excluded from analysis file listing): `meta.json`, `variables.json`, `roles.json`.
+
+Analysis files default to `analysis.json`. The `listAnalysisFiles` function uses `Value.Check` to silently skip corrupt or non-analysis JSON files in the version directory.
+
+**Path helpers** (`src/cli/config.ts`):
+
+- `getStateDir()` -- root state directory
+- `getArgumentsDir()` -- `<state>/arguments/`
+- `getArgumentDir(argumentId)` -- `<state>/arguments/<id>/`
+- `getVersionDir(argumentId, version)` -- `<state>/arguments/<id>/<version>/`
+- `getPremisesDir(argumentId, version)` -- `<state>/arguments/<id>/<version>/premises/`
+- `getPremiseDir(argumentId, version, premiseId)` -- `<state>/arguments/<id>/<version>/premises/<premiseId>/`
+
+## Engine Hydration
+
+**Source:** `src/cli/engine.ts`
+
+### `hydrateEngine(argumentId, version)`
+
+Builds a fully-hydrated `ArgumentEngine` from on-disk state:
+
+1. **Parallel read:** argument meta, version meta, variables, roles, and premise IDs (via `Promise.all`)
+2. **Construct argument:** merge `argMeta` and `versionMeta` into `Omit<TCoreArgument, "checksum">`
+3. **Create engine:** `new ArgumentEngine(argument)`
+4. **Register variables:** iterate all variables, call `engine.addVariable()` for each (with `argumentVersion` set)
+5. **For each premise:** read meta + data in parallel, then `engine.createPremiseWithId(premiseId, extras)`
+6. **Add expressions in BFS order:** roots first (`parentId === null`), then children of already-added nodes in subsequent passes until all are placed
+7. **Set conclusion role last:** `engine.setConclusionPremise(roles.conclusionPremiseId)` if defined. Supporting premises are derived automatically from expression type.
+
+### `persistEngine(engine)`
+
+The inverse of hydration -- writes all engine state back to disk:
+
+1. Extracts argument meta and version meta from `engine.getArgument()`
+2. Writes argument meta, version meta, variables, and roles
+3. For each premise: writes meta and data (expressions + variables)
+
+## Publish Semantics
+
+**Source:** `src/cli/commands/arguments.ts`
+
+`arguments publish <id>`:
+
+1. Reads the latest version meta; exits if already published
+2. Marks the current latest version `published: true, publishedAt: new Date()`
+3. Copies the entire version directory to `version + 1`
+4. Writes a fresh unpublished meta for the new version (removes `publishedAt`)
+
+**Publish guard:** All mutating CLI commands (roles, variables, premises, expressions) call `assertNotPublished(argumentId, version)` before making changes. If the version is already published, it exits with code 1.
+
+## Command Reference
+
+### Top-Level Commands
+
+| Command     | Subcommands                                        |
+| ----------- | -------------------------------------------------- |
+| `version`   | Prints the package version                         |
+| `arguments` | `create`, `import`, `list`, `delete`, `publish`    |
+| `diff`      | `<args...>` (version or cross-argument comparison) |
+
+#### `arguments create <title> <description>`
+
+Creates a new argument with a generated UUID. Initializes version 0 with empty variables, roles, and premises directory. Prints the argument ID.
+
+#### `arguments import <yaml_file>`
+
+Imports an argument from a YAML file. Parses the YAML, builds an `ArgumentEngine` via `importArgumentFromYaml()`, then persists it to disk. Prints the argument ID.
+
+#### `arguments list [--json]`
+
+Lists all arguments sorted newest-first by `createdAt`. Plain output shows `id | title (created date)`. JSON output includes `id`, `title`, `description`, `latestVersion`, `latestCreatedAt`, `latestPublished`.
+
+#### `arguments delete <id> [--confirm] [--all]`
+
+Deletes an argument. Without `--all`, deletes only the latest version (unless only one version exists, in which case the entire argument is deleted). With `--all`, deletes all versions and the argument directory. Without `--confirm`, prompts for interactive confirmation.
+
+#### `arguments publish <id>`
+
+Publishes the latest version and creates a new draft. See [Publish Semantics](#publish-semantics).
+
+#### `diff <args...> [--json]`
+
+Compares two argument versions. Accepts either:
+
+- 3 args: `<id> <verA> <verB>` -- same argument, two versions
+- 4 args: `<idA> <verA> <idB> <verB>` -- cross-argument comparison
+
+Without `--json`, renders a human-readable diff. With `--json`, outputs the raw `TCoreArgumentDiff` object.
+
+### Version-Scoped Commands
+
+Invoked as `proposit-core <argument_id> <version> <command> ...`
+
+#### `show [--json]`
+
+Shows metadata for the argument version. Plain output lists id, title, description, version, created date, published status. JSON merges argument meta and version meta.
+
+#### `render`
+
+Renders all premises as logical expression strings. The conclusion premise is listed first, marked with `*`. Empty premises show `(empty)`.
+
+#### `roles`
+
+| Subcommand                    | Description                                                        |
+| ----------------------------- | ------------------------------------------------------------------ |
+| `show [--json]`               | Shows the conclusion premise ID and derived supporting premise IDs |
+| `set-conclusion <premise_id>` | Sets the designated conclusion premise (premise must exist)        |
+| `clear-conclusion`            | Clears the designated conclusion premise                           |
+
+#### `variables`
+
+| Subcommand                           | Description                                                                                               |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `create <symbol> [--id <id>]`        | Registers a new variable with the given symbol. Optionally specify an explicit ID. Prints the variable ID |
+| `list [--json]`                      | Lists all argument-level variables                                                                        |
+| `show <id> [--json]`                 | Shows a single variable                                                                                   |
+| `update <id> [--symbol <new>]`       | Updates a variable's symbol                                                                               |
+| `delete <id>`                        | Removes a variable (cascade-deletes all referencing expressions across all premises)                      |
+| `list-unused [--json]`               | Lists variables not referenced by any expression                                                          |
+| `delete-unused [--confirm] [--json]` | Deletes all unreferenced variables (prompts unless `--confirm`)                                           |
+
+#### `premises`
+
+| Subcommand                                    | Description                                                                     |
+| --------------------------------------------- | ------------------------------------------------------------------------------- |
+| `create [--title <title>]`                    | Creates a new empty premise. Prints the premise ID                              |
+| `list [--json]`                               | Lists all premises with type (inference/constraint), display string, and title  |
+| `show <id> [--json]`                          | Shows premise metadata, type, root expression, variable count, expression count |
+| `update <id> [--title <new>] [--clear-title]` | Updates premise metadata. `--title` and `--clear-title` are mutually exclusive  |
+| `delete <id> [--confirm]`                     | Deletes a premise. Clears the conclusion role if this was the conclusion        |
+| `render <id>`                                 | Renders the premise as a logical expression string                              |
+
+#### `expressions`
+
+| Subcommand                             | Description                                    |
+| -------------------------------------- | ---------------------------------------------- |
+| `create <premise_id> [flags]`          | Adds an expression to a premise                |
+| `insert <premise_id> [flags]`          | Inserts an expression, wrapping existing nodes |
+| `delete <premise_id> <expr_id>`        | Removes an expression and its subtree          |
+| `list <premise_id> [--json]`           | Lists all expressions in a premise             |
+| `show <premise_id> <expr_id> [--json]` | Shows a single expression                      |
+
+**`create` flags:**
+
+- `--type <type>` (required): `variable`, `operator`, or `formula`
+- `--id <id>`: explicit expression ID (default: generated UUID)
+- `--parent-id <parent_id>`: parent expression ID (omit for root)
+- `--position <n>`: explicit position among siblings
+- `--before <sibling_id>`: insert before this sibling (mutually exclusive with `--after` and `--position`)
+- `--after <sibling_id>`: insert after this sibling (mutually exclusive with `--before` and `--position`)
+- `--variable-id <id>`: required for `type=variable`
+- `--operator <op>`: required for `type=operator` (`not`, `and`, `or`, `implies`, `iff`)
+
+When neither `--position`, `--before`, nor `--after` is specified, the expression is appended as the last child via `appendExpression`.
+
+**`insert` flags:**
+
+- `--type <type>` (required): `variable`, `operator`, or `formula`
+- `--id <id>`: explicit expression ID
+- `--parent-id <parent_id>`: parent expression ID
+- `--position <n>`: position among siblings
+- `--variable-id <id>`: required for `type=variable`
+- `--operator <op>`: required for `type=operator`
+- `--left-node-id <id>`: left node to wrap
+- `--right-node-id <id>`: right node to wrap
+
+At least one of `--left-node-id` or `--right-node-id` is required.
+
+#### `analysis`
+
+| Subcommand                                   | Description                                                                                               |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `create [filename] [--default <value>]`      | Creates a new analysis file with all variables. Default assignment value: `unset` (or `true`/`false`)     |
+| `list [--json]`                              | Lists analysis files in the version directory                                                             |
+| `show [--file <f>] [--json]`                 | Shows variable assignments and rejected expressions                                                       |
+| `set <symbol> <value> [--file <f>]`          | Sets a single variable assignment (`true`, `false`, or `unset`)                                           |
+| `reset [--file <f>] [--value <v>]`           | Resets all assignments to one value (default: `unset`)                                                    |
+| `reject <expr_id> [--file <f>]`              | Rejects an expression (evaluates to `false`, children skipped)                                            |
+| `accept <expr_id> [--file <f>]`              | Accepts an expression (restores normal evaluation)                                                        |
+| `validate-assignments [--file <f>] [--json]` | Validates analysis file against the argument version (checks symbols, IDs, rejected expression existence) |
+| `delete [--file <f>] [--confirm]`            | Deletes an analysis file                                                                                  |
+| `evaluate [--file <f>] [--json] [flags]`     | Evaluates the argument using the analysis file's assignments                                              |
+| `check-validity [--json] [flags]`            | Runs truth-table validity checking                                                                        |
+| `validate-argument [--json]`                 | Validates argument structure for evaluability                                                             |
+| `refs [--json]`                              | Shows variables referenced across all premises (symbol, premise IDs)                                      |
+| `export [--json]`                            | Exports the full argument engine state snapshot                                                           |
+
+**`evaluate` flags:**
+
+- `--strict-unknown-assignment-keys`: reject extra assignment keys
+- `--no-expression-values`: omit per-expression truth values from output
+- `--no-diagnostics`: omit inference diagnostics from output
+- `--no-validate-first`: skip evaluability validation before evaluating
+- `--skip-analysis-file-validation`: skip analysis file validation (symbol/ID mismatch checks)
+
+**`check-validity` flags:**
+
+- `--mode <mode>`: `first-counterexample` (default) or `exhaustive`
+- `--max-variables <n>`: maximum number of variables to allow
+- `--max-assignments-checked <n>`: maximum assignments to enumerate
+- `--include-counterexample-evaluations`: include full evaluation payloads for counterexamples
+- `--no-validate-first`: skip evaluability validation
+
+All analysis subcommands default to `analysis.json` when `--file` is not specified.
+
+## Storage Utilities
+
+**Source:** `src/cli/storage/`
+
+| File           | Key Functions                                                                                                                                                                                             |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `arguments.ts` | `readArgumentMeta`, `writeArgumentMeta`, `readVersionMeta`, `writeVersionMeta`, `listArgumentIds`, `listVersionNumbers`, `latestVersionNumber`, `deleteVersionDir`, `deleteArgumentDir`, `copyVersionDir` |
+| `variables.ts` | `readVariables`, `writeVariables`                                                                                                                                                                         |
+| `roles.ts`     | `readRoles`, `writeRoles`                                                                                                                                                                                 |
+| `premises.ts`  | `readPremiseMeta`, `writePremiseMeta`, `readPremiseData`, `writePremiseData`, `listPremiseIds`, `deletePremiseDir`, `premiseExists`                                                                       |
+| `analysis.ts`  | `readAnalysis`, `writeAnalysis`, `listAnalysisFiles`, `deleteAnalysisFile`, `analysisFileExists`, `resolveAnalysisFilename`                                                                               |
+
+Most disk reads use `Value.Parse(Schema, raw)` from `typebox/value`, which throws on invalid data. Some reads (e.g. `readVersionMeta`) use `Value.Decode` instead. `listAnalysisFiles` uses `Value.Check` to silently skip corrupt files.
+
+Local CLI schemata (in `src/cli/schemata.ts`) use optional `checksum` fields for backward compatibility with older data files that may not include checksums.
+
+## Output Helpers
+
+**Source:** `src/cli/output.ts`
+
+| Function                      | Behavior                                                                                                                   |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `printJson(value)`            | `JSON.stringify(value, null, 2)` + newline to stdout                                                                       |
+| `printLine(text)`             | Text + newline to stdout                                                                                                   |
+| `errorExit(message, code=1)`  | Message + newline to stderr, then `process.exit(code)`. Return type is `never`                                             |
+| `requireConfirmation(prompt)` | Reads from `/dev/tty` (falls back to stdin). Expects the user to type `"confirm"`. Calls `errorExit("Aborted.")` otherwise |