@josfox/jos 4.0.8 → 5.0.0

package/SECURITY-SECRETS.md

@@ -0,0 +1,108 @@
+# `jos secrets` — threat model, format and migration
+
+Applies to `@josfox/jos` 5.0.0-rc.3 and later (verified again under 5.0.0). Code: `src/commands/secrets.js`. Tests: `test/secrets.test.js` (gate: `npm run test:secrets`, 100 % lines, branches and functions).
+
+`jos secrets` keeps credentials for one user on one machine, so a `.jos` run or an agent can use them without anyone typing or pasting them. It is not a team vault, a KMS or a sync service; the F2 vault replaces it.
+
+## What lives where
+
+| Path | Content | Mode |
+|---|---|---|
+| `~/.jos/secrets/` | the directory | 0700 |
+| `~/.jos/secrets/.master` | master key: 32 random bytes as 64 hex characters | 0600 |
+| `~/.jos/secrets/vault.json` | `{"<name>": <entry>, ...}`: the names in clear, the values encrypted | 0600 |
+| `~/.jos/secrets/vault.json.bak-<UTC time>-v1` | a copy of the vault before `migrate` (old format) | 0600 |
+| `~/.jos/secrets/keychain.json` | keychain backend only: the names (never the values) | 0600 |
+
+Every file is written to a unique temporary name created exclusively (`O_EXCL`, mode 0600), synced, then renamed over the target, so a reader never sees a half-written vault and a planted file or symlink at the temporary name is never followed.
+
+## Threat model: who can read what
+
+| Who | Can read | Why |
+|---|---|---|
+| The user, through `jos secrets` | names, fingerprints; values only via `exec` (into a child) or `get --reveal` (to a terminal, after typing the name back) | by design |
+| Another local user (not root) | nothing | directory 0700, files 0600; `jos` refuses to read while any mode is wider, or a file is a symlink or owned by someone else, until `jos secrets fix-perms` (which fixes modes, never ownership or symlinks) |
+| Someone who sees the screen, the scrollback or a terminal recording | the fingerprint | `get` prints `NAME exists · hmac:xxxxxxxx · format` (file backend); the hidden prompt of `set --stdin` does not echo. The fingerprint is keyed with the master key, so it does not let them confirm a guess (next rows) |
+| The process list (`ps`), shell history, CI logs of the command line | the names only | values are never accepted as arguments (`set NAME VALUE` exits 64); `exec` puts them in the child's environment, not in its argv |
+| Someone with a copy of `vault.json` only (backup, sync folder, a disk image without `.master`) | the names, the length of each value | AES-256-GCM without the key |
+| Someone who can write `vault.json` but not read `.master` | cannot forge or alter a v2 value undetected: any change of a byte of `iv`, `tag` or `ct`, or moving an entry to another name, fails authentication (exit 1, never a value). They can delete entries, roll the file back to an older copy, or put back a v1 (old format) entry | GCM tag + name as AAD; v1 entries are unauthenticated (CBC), which is why `list` marks them and `migrate` exists |
+| Root, or any process running as the same user | everything | it can read `.master` and `vault.json`, or the environment of a child of `exec`. **This is not protected.** Use the keychain backend to move the key material into the login keychain; even then, a process of the same user can ask `security` for an item `jos` created |
+| An MCP client of `jos serve --mcp` | nothing of `~/.jos/secrets`: the file tools and the module tools deny the directory and everything in it, however the path is written or reached (symlink, hard link, case). With `--allow-shell`, a client runs programs as you and can read the secrets like any process of the same user (`cat ~/.jos/secrets/.master`) | the server's path jail is not a sandbox for `run_command`, which is why it is off by default; what a client can and cannot reach: `SECURITY-MCP.md` |
+| The child started by `exec --only A,B` | the values of A and B (and nothing else from the vault) | that is its purpose; it can print them, so give it only what it needs |
+| Anyone who sees a fingerprint (file backend), without the master key | cannot test a guess: the fingerprint is `hmac:` + the first 8 hex of `HMAC-SHA256(fpkey, value)`, with `fpkey = HKDF-SHA256(ikm = master key, salt = empty, info = "jos-secrets/v2 fingerprint hmac-sha256", length = 32)`, a label of its own, so it is not the encryption key. Before rc.3 it was `sha256:` + the first 8 hex of the bare sha256 of the value, which let anyone who saw it check guesses for a low-entropy secret offline (finding O-04). It is stable for one value in one vault (same value under two names, or set again: same digits), different between vaults (another master key), and 32 bits of a MAC, so it cannot be inverted to a value | a fingerprint is for recognising a value you stored, not for hiding it. What it still shows: two names of the same vault holding the same value have the same fingerprint, and it changes if the master key changes. Whoever has the master key can compute it (and can decrypt everything anyway). The keychain backend prints none (see below) |
+
+What never contains a value: stdout and stderr of `jos` (except `get --reveal` to a terminal), error messages (they name the secret, never its value), exceptions (an unexpected error is reported as `secrets: unexpected error`; `JOS_DEBUG=1` shows the original, which has no value either), argv of any process, files other than the vault and its backup. The secrets command emits no receipt and has no `--json`. The in-memory copies of a value (buffers) are zeroed after use, best effort: JavaScript strings, which `exec` needs for the environment, cannot be zeroed.
+
+## Format v2 (written by every `set`)
+
+```json
+{"NAME": {"v": 2, "alg": "aes-256-gcm", "iv": "<24 hex>", "tag": "<32 hex>", "ct": "<hex>"}}
+```
+
+- Key: `HKDF-SHA256(ikm = master key, salt = empty, info = "jos-secrets/v2 aes-256-gcm", length = 32)`. The old CBC entries use the raw master key; deriving a separate key means no key is ever used with two modes.
+- Nonce: 12 bytes from `crypto.randomBytes` for every write (a new nonce even when the value is the same).
+- AAD: the entry name as UTF-8 bytes. An entry copied or renamed to another name does not decrypt.
+- Tag: 16 bytes. The plaintext is the exact bytes read (UTF-8 from a terminal; any bytes from a pipe, up to 1 MiB).
+- An entry is accepted only with exactly these five fields and these lengths; anything else is `vault is corrupt: entry "NAME"`. A number `v` greater than 2 is reported as a newer format this jos does not read.
+- Format is per entry: a vault can mix v1 and v2 entries while it is not migrated.
+
+## Format v1 (4.x and 5.0.0-rc.1/rc.2, read only)
+
+`{"NAME": "<32 hex iv>:<hex ciphertext>"}`, AES-256-CBC with the raw master key and PKCS#7 padding, no authentication. It is still read by `get`, `exec` and `list` and is never rewritten implicitly; `list` marks each such entry `[v1 aes-256-cbc, old format]` and counts them.
+
+## Migration (`jos secrets migrate`)
+
+1. Decrypt every v1 entry. If one does not decrypt, stop: nothing is written, no backup is made.
+2. Copy the exact bytes of `vault.json` to `vault.json.bak-<UTC time>-v1` (created exclusively, 0600; a second migration in the same second gets `-1`, `-2`, ...), read the copy back and compare it byte for byte.
+3. Re-encrypt every v1 entry as v2 (v2 entries are kept as they are) and write the new vault atomically.
+4. Read the vault back from disk, check that it parses, has the same number of entries, that every migrated entry is v2 and decrypts to the same bytes. If anything differs, write the original bytes back and stop with an error naming the backup.
+
+The backup holds the old unauthenticated ciphertexts under the same master key: delete it once you have checked the vault (`jos secrets list`, `jos secrets get NAME`).
+
+Without `migrate`, no command changes a v1 entry: `set` of another name writes the new entry as v2 and keeps the v1 strings byte for byte.
+
+## Permissions
+
+Before reading anything, every action except `fix-perms` checks the directory and every entry in it: the directory and subdirectories must be 0700 or narrower, files 0600 or narrower, all owned by the user, no symlinks (neither the directory nor anything inside). Each problem is printed with its path and mode, and the action exits 1 without reading. `jos secrets fix-perms` sets the modes and refuses (exit 1) for symlinks and foreign owners, which need a human. On Windows no POSIX mode is checked (the directory ACL applies).
+
+## Commands
+
+| Command | Behaviour |
+|---|---|
+| `set NAME --stdin` | From a pipe: reads until EOF, removes one final `\n` or `\r\n`, at most 1 MiB. From a terminal: hidden prompt (raw mode, no echo), backspace edits, Enter or Ctrl-D ends, Ctrl-C cancels (exit 130). Empty value: exit 64. A value argument: exit 64 with an explanation. Names: 1–256 characters, no control characters, and valid environment variable names: `[A-Za-z_][A-Za-z0-9_]*` (letters, digits and `_`, not starting with a digit), the same rule as `exec --only`, so a stored secret can always be handed to a command (finding H-02). Anything else exits 64 and says the rule; nothing is created. |
+| `get NAME` | File backend: `NAME exists · hmac:<8 hex> · <format>`; decrypts (so a tampered entry fails here too) but prints no value. The fingerprint is keyed (threat model above). Keychain backend: `NAME exists · macOS keychain`, no fingerprint (below). `get` accepts any name already in the vault, valid or not. |
+| `get NAME --reveal` | Only when stdin and stdout are both terminals, and only after the name is typed back. Otherwise exit 1 and a hint to use `exec`. |
+| `exec --only A,B -- CMD [ARGS]` | Every named secret must exist (or the command is not started); names must be valid environment variable names (the rule of `set`: `[A-Za-z_][A-Za-z0-9_]*`; otherwise exit 64). The child gets the current environment plus those variables, its own stdio, no shell. Exit code: the child's; 127 if it is not found, 126 if it cannot be executed; 128+n if it dies by signal n. SIGINT, SIGTERM and SIGHUP are relayed to the child. |
+| `list` | Names, with the v1 entries marked. Reads no value, needs no decryption. Lists every name, valid or not. |
+| `delete NAME` | Removes the entry. Accepts any name already in the vault, valid or not. |
+| `migrate`, `fix-perms` | Above. `migrate` does not validate or rename: it rewrites the entries under the names they have. |
+
+**Vaults with names that `set` would now refuse.** Older versions (4.x, 5.0.0-rc.1/rc.2) accepted any name (`my-key`, `a=b`, `bad name`, `../x`). Such an entry is not lost or rejected: `list`, `get` (fingerprint, and `--reveal` on a terminal) and `delete` keep working on it, `migrate` rewrites it as v2 under the same name, and it is untouched by `set` of other names. What does not work is handing it to a command (`exec --only` needs a valid name) and overwriting it with `set`. To keep the value under a valid name: `get NAME --reveal` on a terminal, `set NEW_NAME --stdin`, then `delete NAME`.
+
+The master key is created only by the first `set` into an empty vault. If `vault.json` has entries and `.master` is missing, every command that needs it fails with `master key is missing`: a new key next to old entries would make them undecryptable.
+
+## Keychain backend (macOS, `JOS_SECRETS_BACKEND=keychain`)
+
+- Items: generic passwords with service `jos` and account `NAME` in the default (login) keychain.
+- Write: `/usr/bin/security add-generic-password -U -s jos -a NAME -w`, with `-w` last so `security` prompts for the password; `jos` starts it in a new session without a controlling terminal, so the prompt reads the value (twice: value and confirmation) from the stdin pipe. The value is never in an argument. After writing, `jos` reads the item back and compares; if it differs, the item is deleted and the command fails.
+- Values: printable ASCII, at most 128 characters (the limit of `getpass(3)` used by `security`, and `security -w` prints other bytes as hex). Other values exit 64: keep those in the file backend.
+- `keychain.json` keeps the names, because the keychain cannot be listed without dumping it.
+- No fingerprint: `get` prints `NAME exists · macOS keychain`, and `set` does not print one. A keyed fingerprint needs a secret key that `jos` holds and an attacker who only saw the output does not. The file backend has the master key; the keychain backend has none (the keychain is the key store), and a bare digest of the value would bring back O-04 (guesses testable from the output alone). A second key kept just for the fingerprint, in a file next to `keychain.json` or as one more keychain item, would add key material and a write on `get` for a convenience; to check a value use `get NAME --reveal` on a terminal. Names follow the same rule as the file backend (`set` only).
+- `migrate` does not apply (exit 64).
+- Verified against the real keychain by the opt-in test (`JOS_TEST_KEYCHAIN=1 node --test --test-name-pattern="real keychain" test/secrets.test.js`), which creates and deletes its own `JOS_TEST_KC_<random>` item. The default suite uses a stand-in for `security` that records its argv (the tests assert the value is not there), and every test file and gate script deletes `JOS_SECRETS_BACKEND` (and the test files `JOS_TEST_KEYCHAIN`) inherited from the shell before anything runs, so a developer who exports `JOS_SECRETS_BACKEND=keychain` never has the default suite call the real `security` (finding R-07; `test/gate.test.js` checks it statically).
+
+## What this does not protect
+
+- A process running as the same user, root, or malware in the user's session (it can read `.master`, the keychain items `jos` created, or the environment of an `exec` child), or a program started by an MCP client of `jos serve --mcp --allow-shell`.
+- Whatever the child of `exec` does with the value.
+- Swap, core dumps or memory inspection while a value is in memory.
+- Deletion, rollback to an older copy, or replacing a v2 entry by a v1 entry by someone who can write the directory (the names and formats are visible with `list`; there is no rollback counter).
+- Two `jos secrets` writers at the same time: each write is atomic, but the last one wins for the whole file (no lock).
+- The fingerprint no longer lets someone without the master key confirm a guess (O-04), but it still shows that two names of one vault hold the same value.
+
+## Tests and coverage
+
+`npm run test:secrets` (Node 22+) runs `test/secrets.test.js` with Node's coverage restricted to `src/commands/secrets.js` and fails below 100 % of lines, branches or functions. Every requirement (R1 input, R2 authenticated encryption, R3 migration, R4 permissions, R5 reading, R6 exec, R7 keychain, R8 no value in any output, R0 compatibility) has positive and negative tests. Two lines are excluded with `node:coverage ignore next`, each with its reason in the code:
+
+1. `uid: typeof process.getuid === 'function' ? process.getuid() : -1` — the `-1` side exists only on Windows, where no mode or owner is checked.
+2. The `'error'` listener on the stdin pipe of `security` — EPIPE when `security` exits before reading; the input (at most 2 × 129 bytes) fits in the pipe buffer before the child can exit, so a test cannot produce it. Without the listener such an error would crash the host.

package/STYLE.md

@@ -0,0 +1,23 @@
+# Output style of the host
+
+Every line `jos` writes for a person looks the same, whichever command wrote it. `npm test` enforces it (`test/style.test.js`).
+
+## Rules
+
+1. **One style module.** `src/ui.js` is the only file that writes to stdout or stderr. A command takes a printer (`ui.printer(stream)`) and uses its parts: `header(title, sub)` (blank line, rule, `TITLE // sub`, rule, blank line), `ok` / `fail` / `warn` / `step` (`✓` green, `✖` red, `⚠` yellow, `▶` cyan, each with an optional gray detail), `hint` (an indented, dimmed follow-up line), `field` (`  label: value`), `item` (`  • text`), `cmd` (`    $ command`), `line` and `text` for a line or block composed with the printer's palette `C`.
+2. **Color only on a terminal.** A printer's palette is empty when the stream is not a TTY or `NO_COLOR` is set: piped output and logs carry no escape codes. No file other than `src/ui.js` contains an escape code.
+3. **Machine output is plain.** `--json` goes through `ui.json(stream, value)`: two-space JSON and one newline, never color or decoration, whatever the terminal. Data that is not a message (the output of a step a document ran, a value revealed by `secrets get --reveal`) goes through `ui.data(stream, chunk)`, byte for byte.
+4. **Errors on stderr, same format.** An error is `✖ jos <command>: <what happened>` on stderr, followed by `hint` lines for the usage or the next step; a warning is `⚠ …`. Results a script reads (`--json`, `version`, `secrets get`, `secrets list`) go to stdout.
+5. **No raw log line reaches the user.** No `console.log`, `console.error`, `process.stdout.write` or `process.stderr.write` outside `src/ui.js`, and no `<stream>.write` on a stdout, stderr or output stream, except the exceptions below. Debug detail (a stack trace) appears only with `JOS_DEBUG=1`, still through a printer.
+6. **Marks, not emoji.** `✓ ✖ ⚠ ▶ •` and the rule `━`. The Kitsune banner of `jos --help` is the one picture.
+7. **Commands to copy are copyable.** Paths in a printed command are absolute and quoted for a POSIX shell when needed (`ui.shellArg`).
+
+## Exceptions
+
+`test/style.test.js` reads this table: each row is a file and the exact code it may contain, and the test fails if a row no longer matches a line of its file (an exception that is not used is removed, not kept).
+
+<!-- style-exceptions:start -->
+| File | Code | Why |
+|---|---|---|
+| src/mcp.js | `output.write(JSON.stringify(response) + '\n')` | The JSON-RPC 2.0 channel of `jos serve --mcp`: one compact JSON message per line on stdout, read by the MCP client, never by a person. Notices of the server go to stderr through a printer. |
+<!-- style-exceptions:end -->

package/bin/jos

@@ -1,28 +1,29 @@
 #!/usr/bin/env node
-const fs = require('fs'), path = require('path'), { spawn } = require('child_process');
-const JOS_HOME = path.join(process.env.HOME, '.jos');
+'use strict';
+const fs = require('fs'), path = require('path'), os = require('os');
+const pkg = require('../package.json');
+const ui = require('../src/ui');
+const { supportsUnicode, RULE } = ui;
 
-// AURORA Design System
-const C = {
-    reset: '\x1b[0m',
-    bold: '\x1b[1m',
-    dim: '\x1b[2m',
-    purple: '\x1b[38;5;135m',
-    magenta: '\x1b[38;5;198m',
-    cyan: '\x1b[38;5;51m',
-    blue: '\x1b[38;5;39m',
-    white: '\x1b[38;5;255m',
-    gray: '\x1b[38;5;245m',
-    pink: '\x1b[38;5;213m',
-    teal: '\x1b[38;5;44m',
-};
+const JOS_HOME = path.join(os.homedir(), '.jos');
+
+// A reader that closes the pipe early (`jos run x.jos --json | head -c1`) must end the process quietly with
+// the exit code already decided, not with an unhandled 'error' event and a stack trace.
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on('error', (e) => {
+        if (e && e.code === 'EPIPE') process.exit(typeof process.exitCode === 'number' ? process.exitCode : 0);
+        throw e;
+    });
+}
 
-// Aurora palette for random Kitsune colors 🦊
-const AURORA_COLORS = [C.purple, C.magenta, C.cyan, C.blue, C.pink, C.teal];
-const randomAurora = () => AURORA_COLORS[Math.floor(Math.random() * AURORA_COLORS.length)];
+// Palette for random Kitsune colors
+const randomColor = (C) => {
+    const colors = [C.purple, C.magenta, C.cyan, C.blue, C.pink, C.teal];
+    return colors[Math.floor(Math.random() * colors.length)];
+};
 
-// The legendary Kitsune fox
-const KITSUNE_FOX = `
+// Unicode Kitsune fox (for modern terminals)
+const KITSUNE_UNICODE = `
 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⡀⠀⠀⠀
 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⠙⠻⢶⣄⡀⠀⠀⠀⢀⣤⠶⠛⠛⡇⠀⠀⠀
 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢹⣇⠀⠀⣙⣿⣦⣤⣴⣿⣁⠀⠀⣸⠇⠀⠀⠀
@@ -39,60 +40,131 @@ const KITSUNE_FOX = `
 ⠀⠀⠀⠀⠙⠿⣿⣿⣿⣿⣿⣿⣿⡿⠿⠛⠋⠉⠁⠀⠀⠀⠀⠈⠛⠃⠀⠀⠀⠀
 ⠀⠀⠀⠀⠀⠀⠀⠉⠉⠉⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀`;
 
-const getKitsuneBanner = () => {
-    const color = randomAurora();
-    return `${color}${KITSUNE_FOX}${C.reset}
-                            ${C.dim}Made with ❤️ & AI${C.reset}`;
+// ASCII fallback for terminals without Unicode (like Raspberry Pi)
+const KITSUNE_ASCII = `
+        /\\___/\\
+       (  o o  )
+       (  =^=  ) 
+        )     (
+       (       )
+      ( KITSUNE )
+       (       )
+        \\_____/
+    JOS // AI Agent`;
+
+const getKitsuneBanner = (C) => {
+    const color = randomColor(C);
+    const fox = supportsUnicode() ? KITSUNE_UNICODE : KITSUNE_ASCII;
+    return `${color}${fox}${C.reset}
+                            ${C.dim}Made with <3 & AI${C.reset}`;
 };
 
-const ALIASES = { server: 'serve' };
+// The last line of `jos --help` (README, Security: Disclaimer).
+const DISCLAIMER = 'Figures jos prints (cost, tokens, time) are estimates; vendor invoices are authoritative. Any AI output it ' +
+    'relays can be wrong: use the receipts and the ledger as evidence for your own decision. Provided "AS IS", without ' +
+    'warranty (Apache-2.0).';
+
+// Fixed command table: no lookup in ~/.jos, no user code is loaded.
+const COMMANDS = {
+    run: '../src/commands/run.js',
+    validate: '../src/commands/validate.js',
+    migrate: '../src/commands/migrate.js',
+    verify: '../src/commands/verify.js',
+    version: '../src/commands/version.js',
+    init: '../src/commands/init.js',
+    start: '../src/commands/start.js',
+    ids: '../src/commands/ids.js',
+    ledger: '../src/commands/ledger.js',
+    meter: '../src/commands/meter.js',
+    runs: '../src/commands/runs.js',
+    secrets: '../src/commands/secrets.js',
+    serve: '../src/serve.js',
+};
+const OVERVIEW = '../src/commands/overview.js';
+const NEEDS_HOME = new Set(['serve', 'secrets']);
+const FROZEN = new Set(['llm', 'prompts', 'get', 'repo', 'add']);
+const ALIASES = { server: 'serve', '--version': 'version', '-V': 'version', '-v': 'version', help: '--help' };
 const rawCmd = process.argv[2];
-const cmd = ALIASES[rawCmd] || rawCmd;
+const cmd = Object.prototype.hasOwnProperty.call(ALIASES, rawCmd) ? ALIASES[rawCmd] : rawCmd;
 
-if (!cmd) {
-    console.log(getKitsuneBanner());
-    console.log(`\n${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}`);
-    console.log(`  ${C.white}${C.bold}JOS${C.reset} ${C.cyan}KERNEL v4.0${C.reset} ${C.gray}// Stoic Architecture${C.reset}`);
-    console.log(`  ${C.dim}Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)${C.reset}`);
-    console.log(`${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}`);
-    console.log(`\n${C.white}${C.bold}  Usage:${C.reset} ${C.cyan}jos${C.reset} ${C.gray}<command>${C.reset} ${C.dim}[options]${C.reset}\n`);
-    console.log(`${C.white}${C.bold}  Commands:${C.reset}`);
-    console.log(`    ${C.cyan}serve${C.reset}      ${C.gray}Start local development server${C.reset}`);
-    console.log(`    ${C.cyan}init${C.reset}       ${C.gray}Create new .jos artifact${C.reset}`);
-    console.log(`    ${C.cyan}add${C.reset}        ${C.gray}Add task to .jos artifact${C.reset}`);
-    console.log(`    ${C.cyan}validate${C.reset}   ${C.gray}Validate .jos artifact${C.reset}`);
-    console.log(`    ${C.purple}run${C.reset}        ${C.gray}Execute .jos artifacts${C.reset}`);
-    console.log(`    ${C.magenta}secrets${C.reset}    ${C.gray}Manage encrypted credentials${C.reset}`);
-    console.log(`    ${C.blue}get${C.reset}        ${C.gray}Fetch packages from repos${C.reset}\n`);
-    console.log(`${C.dim}  Run ${C.cyan}jos <cmd> --help${C.reset}${C.dim} for command-specific options${C.reset}\n`);
-    process.exit(0);
+function printHelp() {
+    const out = ui.printer(process.stdout);
+    const { C } = out;
+    let kv = 'jos-core not found';
+    try { kv = 'jos-core ' + require('../src/kernel').locate().version; } catch (e) { /* reported by version/run */ }
+    out.line(getKitsuneBanner(C));
+    out.line(`\n${C.purple}${RULE}${C.reset}`);
+    out.line(`  ${C.white}${C.bold}JOS${C.reset} ${C.cyan}v${pkg.version}${C.reset} ${C.gray}// host of ${kv}${C.reset}`);
+    out.line(`  ${C.dim}Reads .jos 2.0.0, 1.1.0, 1.0.0 and 0.0.7 documents${C.reset}`);
+    out.line(`${C.purple}${RULE}${C.reset}`);
+    out.line(`\n${C.white}${C.bold}  Usage:${C.reset} ${C.cyan}jos${C.reset} ${C.gray}<command>${C.reset} ${C.dim}[options]${C.reset}\n`);
+    out.line(`${C.white}${C.bold}  Commands:${C.reset}`);
+    out.line(`    ${C.cyan}start${C.reset}      ${C.gray}Write four examples to run first (no keys, no network)${C.reset}`);
+    out.line(`    ${C.purple}run${C.reset}        ${C.gray}Run a .jos document: intention, receipts, verdict (jos-core)${C.reset}`);
+    out.line(`    ${C.cyan}validate${C.reset}   ${C.gray}Validate a .jos document without running it (jos-core)${C.reset}`);
+    out.line(`    ${C.cyan}migrate${C.reset}    ${C.gray}Reseal a 0.0.7 document sealed by integrity_ref as 2.0 (integrity.hash)${C.reset}`);
+    out.line(`    ${C.cyan}ids${C.reset}        ${C.gray}Content and entity ids: art_, ent_, directory hash${C.reset}`);
+    out.line(`    ${C.cyan}runs${C.reset}       ${C.gray}List the runs in ~/.jos/runs${C.reset}`);
+    out.line(`    ${C.cyan}ledger${C.reset}     ${C.gray}ledger verify <run>: check a run's hash-chained ledger${C.reset}`);
+    out.line(`    ${C.cyan}meter${C.reset}      ${C.gray}Tokens, cost and time of a run, from its verified ledger${C.reset}`);
+    out.line(`    ${C.cyan}init${C.reset}       ${C.gray}Write a new 2.0 atom that run accepts${C.reset}`);
+    out.line(`    ${C.green}verify${C.reset}     ${C.gray}Self-check: run the embedded hello.jos${C.reset}`);
+    out.line(`    ${C.cyan}version${C.reset}    ${C.gray}Print host and kernel versions${C.reset}`);
+    out.line(`    ${C.magenta}secrets${C.reset}    ${C.gray}Manage encrypted credentials${C.reset}`);
+    out.line(`    ${C.cyan}serve${C.reset}      ${C.gray}MCP server (--mcp) for Claude Code, Claude Desktop, Cursor; see jos serve --help${C.reset}\n`);
+    out.line(`${C.dim}  Frozen in 5.0.0: add, llm, prompts, get, repo (jos <name> says why)${C.reset}`);
+    out.line(`${C.dim}  Run ${C.cyan}jos <cmd> --help${C.reset}${C.dim} for command-specific options${C.reset}\n`);
+    out.line(`${C.dim}  ${DISCLAIMER}${C.reset}`);
 }
 
-// Look for command in multiple locations (priority order)
-const PKG_COMMANDS = path.join(__dirname, '..', 'src', 'commands');  // npm package
-const USER_COMMANDS = path.join(JOS_HOME, 'commands');               // user installed
-
-function findCommand(name) {
-    // 1. Check user's ~/.jos/commands first (allows overrides)
-    const userPath = path.join(USER_COMMANDS, name, 'index.js');
-    if (fs.existsSync(userPath)) return userPath;
-
-    // 2. Check npm package src/commands
-    const pkgPath = path.join(PKG_COMMANDS, `${name}.js`);
-    if (fs.existsSync(pkgPath)) return pkgPath;
-
-    // 3. Check npm package src/ directly (for serve.js)
-    const srcPath = path.join(__dirname, '..', 'src', `${name}.js`);
-    if (fs.existsSync(srcPath)) return srcPath;
+// A first argument that is no command but names a .jos document (a file ending in .jos or .jos.json, or a folder
+// with a .jos/ directory): `jos hola.jos` gets the two commands it most likely meant, and nothing runs by itself.
+function looksLikeDocument(arg) {
+    try {
+        const st = fs.statSync(arg);
+        if (st.isFile()) return /\.jos(\.json)?$/.test(arg);
+        return path.basename(path.resolve(arg)) === '.jos' || fs.statSync(path.join(arg, '.jos')).isDirectory();
+    } catch (e) { return false; }
+}
 
-    return null;
+// `jos --help`: every command. `jos` alone (or ''): what it does and what is in this folder, read only (overview.js).
+if (cmd === '--help' || cmd === '-h') {
+    printHelp();
+    process.exit(0);
 }
 
-const cmdPath = findCommand(cmd);
-if (!cmdPath) {
-    const color = randomAurora();
-    console.log(`\n${color}  ✖${C.reset} ${C.white}Unknown command:${C.reset} ${C.cyan}${rawCmd}${C.reset}`);
-    console.log(`${C.dim}    Try: ${C.cyan}jos --help${C.reset}${C.dim} to see available commands${C.reset}\n`);
+if (cmd && !Object.prototype.hasOwnProperty.call(COMMANDS, cmd)) {
+    const err = ui.printer(process.stderr);
+    err.line();
+    if (FROZEN.has(cmd)) {
+        err.warn('Command frozen in 5.0.0: ' + rawCmd);
+        // The one-line README with the reason ships in the package (package.json "files"); the frozen code does not.
+        err.hint('It returns in a later phase. Why: ' + path.join(__dirname, '..', 'src', 'commands', '_frozen', cmd + '.README.md'));
+    } else if (looksLikeDocument(rawCmd)) {
+        const arg = (rawCmd.startsWith('-') ? '-- ' : '') + ui.shellArg(rawCmd);
+        err.fail('Unknown command: ' + rawCmd, '(it is a .jos document; jos does not run it by itself)');
+        err.hint('To run it:       jos run ' + arg);
+        err.hint('To validate it:  jos validate ' + arg);
+    } else {
+        err.fail('Unknown command: ' + rawCmd);
+        err.hint('Try: jos --help to see available commands');
+    }
+    err.line();
     process.exit(1);
 }
-require(cmdPath).execute(process.argv.slice(3), JOS_HOME);
+
+if (NEEDS_HOME.has(cmd)) {
+    try { fs.mkdirSync(JOS_HOME, { recursive: true }); } catch (e) { /* the command reports what it cannot do */ }
+}
+
+Promise.resolve()
+    .then(() => require(cmd ? COMMANDS[cmd] : OVERVIEW).execute(process.argv.slice(3), JOS_HOME))
+    .then((code) => { if (typeof code === 'number') process.exitCode = code; })
+    .catch((e) => {
+        // A host bug, never a document outcome: exit 70 (EX_SOFTWARE). The stack trace only with JOS_DEBUG=1.
+        const msg = e && e.message ? e.message : String(e);
+        const err = ui.printer(process.stderr);
+        err.fail('jos: internal error: ' + msg);
+        if (process.env.JOS_DEBUG) err.line(e && e.stack ? e.stack : '');
+        process.exitCode = 70;
+    });

package/bin/jos.cmd

@@ -0,0 +1,5 @@
+@echo off
+SETLOCAL
+SET dp0=%~dp0
+node "%dp0%\jos" %*
+ENDLOCAL

package/examples/01-hello.jos

@@ -0,0 +1,44 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.hello",
+  "meta": {
+    "name": "tour.hello",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Print a greeting and exit cleanly",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "hello"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf",
+      "curl",
+      "wget"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "echo",
+      "hello, .jos"
+    ],
+    "env": [
+      "PATH"
+    ]
+  }
+}

package/examples/02-criteria.jos

@@ -0,0 +1,54 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.criteria",
+  "meta": {
+    "name": "tour.criteria",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Print exactly one greeting line and nothing on stderr",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "hello"
+      },
+      {
+        "stdout_matches": "^hello, \\.jos\\n$"
+      },
+      {
+        "stderr_empty": true
+      },
+      {
+        "not": {
+          "exit": 3
+        }
+      },
+      "A person can read the greeting"
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "echo",
+      "hello, .jos"
+    ],
+    "env": [
+      "PATH"
+    ]
+  }
+}

package/examples/03-flow-gate.jos

@@ -0,0 +1,83 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "flow"
+  },
+  "id": "tour.flow-gate",
+  "meta": {
+    "name": "tour.flow-gate",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Build, wait for a person to approve the build, then publish",
+    "success_criteria": [
+      {
+        "exit": 0
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "orchestration": {
+    "definitions": {
+      "build": {
+        "engine": "shell",
+        "run": [
+          "echo",
+          "built"
+        ],
+        "description": "Make the artifact",
+        "intention": {
+          "objective": "Make the artifact",
+          "success_criteria": [
+            {
+              "stdout_contains": "built"
+            }
+          ]
+        }
+      },
+      "publish": {
+        "engine": "shell",
+        "run": [
+          "echo",
+          "published"
+        ],
+        "description": "Runs only after a person approved build",
+        "intention": {
+          "objective": "Publish the approved build",
+          "success_criteria": [
+            {
+              "stdout_contains": "published"
+            }
+          ]
+        }
+      }
+    },
+    "flows": {
+      "main": {
+        "steps": [
+          "build",
+          "publish"
+        ],
+        "gates": {
+          "build": {
+            "kind": "human"
+          }
+        }
+      },
+      "build-only": {
+        "steps": [
+          "build"
+        ]
+      }
+    }
+  }
+}

package/examples/04-use-template/README.md

@@ -0,0 +1,22 @@
+# 04 · use, a template and a digest
+
+`lib/greeting.jos` is a `template`: its slot `name` is declared as a JSON Schema in `execution.inputs`
+(a string of letters and spaces, 1 to 64 characters). `use.jos` is a flow that uses it twice, `ana` and `leo`, each
+with its own `with`, and pins the template's content in `requires[].digest` (its `art_`).
+
+Run from the folder that holds `04-use-template/`:
+
+| Command | Result |
+|---|---|
+| `jos run 04-use-template/use.jos --library 04-use-template/lib` | `use` resolves `tour.greeting@^1.0.0` in the library folder, the digest matches, both steps run; prints `hello, Leo` (the output of the last step); exit 0 |
+| `jos run 04-use-template/use.jos` | no library given: the pinned artifact is not found, `/requires/0: not satisfied`; nothing runs; exit 5 |
+| `jos run 04-use-template/lib/greeting.jos --with '{"name":"Ana"}'` | the template run directly, instantiated with `--with`; prints `hello, Ana`; exit 0 |
+| `jos run 04-use-template/lib/greeting.jos` | no value for the required slot: `/with: required 'name'`; exit 2 |
+| `jos ids 04-use-template/lib/greeting.jos` | the template's `art_`, the value pinned in `use.jos` |
+
+Change anything in `lib/greeting.jos` (for example `hello` to `hi`) and run `use.jos` with the library again: the
+template's `art_` no longer equals the digest, the run is refused (exit 5). Put the text back, or pin the new
+`art_` (`jos ids`), and it runs.
+
+The same `use` also resolves from a `.jos/` folder above the document (`.jos/templates/`, `.jos/flows/`, …), nearest
+level first, before the library.

package/examples/04-use-template/lib/greeting.jos

@@ -0,0 +1,56 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "template"
+  },
+  "id": "tour.greeting",
+  "meta": {
+    "name": "tour.greeting",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Greet {{ name }} by name",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "{{ name }}"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "inputs": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[A-Za-z ]+$"
+        }
+      }
+    },
+    "run": [
+      "echo",
+      "hello, {{ name }}"
+    ],
+    "env": [
+      "PATH"
+    ]
+  }
+}