@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/docs/gsc.md

@@ -0,0 +1,175 @@
+# Google Search Console (`pa gsc`)
+
+`pa gsc` automates Google Search Console onboarding and analytics across any
+domain whose DNS lives on Cloudflare in an account the operator controls.
+
+## Status
+
+Implemented: `add-property`, `verify-via-cf-dns`, `submit-sitemap`,
+`pull-analytics`, `list-properties`. Auth via Google service-account JSON
+loaded from the SOPS vault. Cloudflare planting via the CF v4 REST API.
+
+## Dependencies
+
+Two npm packages (declared in `@stravica-ai/digital-operator-pa`):
+
+- `googleapis` — the canonical Node SDK for Google Cloud APIs.
+- `google-auth-library` — JWT auth helper used by `googleapis`.
+
+## Operator setup (one-time per platform install)
+
+1. **Create a Google Cloud project** dedicated to GSC automation. Pick a
+   short name like `gsc-automation-prod`.
+
+2. **Enable the APIs** in that project:
+   - Search Console API:  
+     https://console.cloud.google.com/apis/library/searchconsole.googleapis.com
+   - Site Verification API:  
+     https://console.cloud.google.com/apis/library/siteverification.googleapis.com
+
+3. **Create a service account** under IAM & Admin → Service accounts:
+   - Name: `gsc-automation`
+   - No project-level roles needed (GSC permissions are granted per-property
+     in the GSC dashboard, not at GCP IAM level).
+
+4. **Generate a JSON key** for the service account (Keys tab → Add Key →
+   JSON). Download the file — this is the SA key.
+
+5. **Store the SA key in the SOPS vault**:
+   ```bash
+   pnpm exec secrets set GSC_SERVICE_ACCOUNT_KEY -
+   # paste the entire JSON contents, then Ctrl-D
+   ```
+
+6. **Store Cloudflare credentials** (also one-time). Two key shapes are
+   supported; pick whichever fits your setup:
+
+   **Single-account setup** — one CF account, no `--account` flag needed:
+   ```bash
+   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY <token>
+   pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID <account-id>
+   ```
+
+   **Multi-account setup** — multiple CF accounts, each addressed by name:
+   ```bash
+   # Stravica account → addressed as --account stravica
+   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY_STRAVICA <token>
+   pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID_STRAVICA <account-id>
+
+   # Clive account → addressed as --account clive
+   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY_CLIVE <token>
+   pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID_CLIVE <account-id>
+   ```
+
+   The CF API token needs `Zone:DNS:Edit` and `Zone:Zone:Read` for any
+   zones the tool will operate on. Account-level "Write to all resources"
+   tokens also work.
+
+   For back-compat, the legacy `CLOUDFLARE_API_TOKEN` /
+   `CLOUDFLARE_ACCOUNT_ID` pair is read as a last-resort fallback when
+   no `--account` flag is passed and the `CLOUDFLARE_PAGES_*` unsuffixed
+   pair is absent. Don't rely on it — set the `CLOUDFLARE_PAGES_*` keys.
+
+## Per-domain setup (each time you onboard a new property)
+
+7. **Grant the service-account access to the GSC property.** Until the
+   property exists, you can't grant access. So the workflow is:
+
+   1. Run `pa gsc verify-via-cf-dns <domain>` — this performs verification
+      end-to-end and registers the property under the SA's identity, so
+      the SA implicitly has Owner permission.
+
+   *Or, if a property already exists under a human Google account:*
+
+   2. Open Search Console → Settings → Users and permissions →
+      Add user, paste the SA email (`<name>@<project>.iam.gserviceaccount.com`),
+      grant Owner (or Full).
+
+   The `pa gsc list-properties` command will then show the property.
+
+## Usage
+
+```bash
+# Get the verification TXT token for a domain (no DNS change yet)
+pnpm exec pa gsc add-property stravica.ai
+
+# Plant the TXT in Cloudflare, wait, verify, register
+pnpm exec pa gsc verify-via-cf-dns stravica.ai
+# Optional --wait SECONDS to override the default 60s propagation pause:
+pnpm exec pa gsc verify-via-cf-dns stravica.ai --wait 120
+# Multi-account: select which CF account's vault keys to use:
+pnpm exec pa gsc verify-via-cf-dns stravica.ai --account stravica
+pnpm exec pa gsc verify-via-cf-dns besafetraining.co.uk --account clive
+
+# Submit a sitemap
+pnpm exec pa gsc submit-sitemap stravica.ai https://stravica.ai/sitemap.xml
+
+# Pull search analytics (default 28d, top queries, 100 rows)
+pnpm exec pa gsc pull-analytics stravica.ai
+pnpm exec pa gsc pull-analytics stravica.ai --days 90 --dimensions query,page --rows 500
+
+# List every property the SA can see (sanity-check setup)
+pnpm exec pa gsc list-properties
+```
+
+## Multi-account selection
+
+When `--account <name>` is passed to `verify-via-cf-dns`, the tool resolves
+the Cloudflare credentials by upper-casing the name and looking up the
+corresponding suffixed vault pair. For example:
+
+```
+--account stravica  ->  CLOUDFLARE_PAGES_API_KEY_STRAVICA
+                        CLOUDFLARE_PAGES_ACCOUNT_ID_STRAVICA
+--account clive     ->  CLOUDFLARE_PAGES_API_KEY_CLIVE
+                        CLOUDFLARE_PAGES_ACCOUNT_ID_CLIVE
+```
+
+If `--account` is passed but the suffixed pair isn't set, the command
+fails fast with a message telling you which key is missing. It does
+**not** silently fall back to the unsuffixed pair — that would defeat
+the safety the flag exists to provide.
+
+Without `--account`, resolution order is:
+1. `CLOUDFLARE_PAGES_API_KEY` + `CLOUDFLARE_PAGES_ACCOUNT_ID`
+2. Legacy `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` (back-compat
+   only; do not rely on this).
+
+The account name accepts letters and digits only — anything else is a
+usage error.
+
+## Notes
+
+- Properties are always registered as **domain-properties** (`sc-domain:<host>`),
+  which cover https + http + every subdomain under a single property. The
+  legacy URL-prefix shape is not supported by this tool.
+- The verification TXT record is planted at the **apex** of the domain
+  (no `_google-site-verification` subdomain prefix — that is required for
+  URL-prefix properties only).
+- The Cloudflare DNS write is **idempotent**: a re-run with the same
+  token leaves DNS untouched; a re-run after a token rotation updates
+  the existing record in place.
+- Verification can fail if DNS hasn't propagated yet. Re-run with
+  `--wait 180` if the default 60s is too short.
+
+## Exit codes
+
+```
+0  OK
+1  Usage error / vault uninitialised / domain ambiguous
+2  Operational failure (Google API, Cloudflare API, verification failed)
+3  Transport / network / missing SDK
+```
+
+## Live-test gap
+
+The mock test suite covers the auth-construction path, domain
+normalisation, CF API request shape, and the GSC verb plumbing. Live
+testing requires:
+
+1. The operator setup above completed (GCP project + APIs + SA key in vault).
+2. CF credentials in vault.
+3. One real domain to verify.
+
+After GCP setup, run `pa gsc list-properties` first — it requires no
+DNS or verification and proves the SA key + scopes work end-to-end.

package/dist/engineering-pa-cli/docs/lint-linkedin.md

@@ -0,0 +1,139 @@
+# pa lint linkedin
+
+Deterministic voice-rule linter for operator-authored LinkedIn text. Loads a
+JSON rule corpus and reports voice-rule violations in **alter-format** — each
+finding tells the writer what to do (`swap → X`, `cut`, `rename`) rather than
+just flagging a banned token.
+
+## Why this exists
+
+Voice rules that are machine-checkable should be machine-checked, not left to a
+prompt instruction the writer mentally verifies against. Three voice failures
+shipped in one week despite a pre-delivery checklist (a forced "isn't X, it's Y"
+contrast, a `the right cut` reaction phrase reused across sibling replies, an
+`Indeed..` opener repeated across replies). This linter moves those rules into a
+validator. The framing is deliberately **alter, not block**: the writer is more
+reliable picking from a known target than avoiding a blacklist, so every rule
+carries its swap / cut / rename guidance inline.
+
+## Usage
+
+```sh
+pa lint linkedin <input-file> [options]
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--rules <path>` | `operator/knowledge/writing/linkedin-rules.json` under the repo root | Rule corpus JSON. Required if the default file is absent. |
+| `--format <text\|json>` | `text` | Output format. |
+| `--severity <error\|warning\|info>` | `error` | Severity floor — only violations at or above this level are reported. |
+| `--surface <name>` | `linkedin` | Surface context: `all`, `linkedin`, `article`, `newsletter`, `reply`. A rule applies if its `surface` is `all` or includes this value. |
+| `-h, --help` | | Show help. |
+
+The default rules path resolves relative to the operator repo root (located via
+`$DAVE_REPO_ROOT` / `$PA_REPO_ROOT`, else by walking up to the nearest `.git`).
+If it is absent and `--rules` is not given, the command exits 3 with guidance.
+
+### Text output
+
+One line per violation:
+
+```
+<file>:<line>:<col>  <severity>  <ruleId>  <matched-text>  →  <alter-guidance>
+```
+
+Example:
+
+```
+post.md:1:14  error  punct-em-dash  "—"  →  swap → "," | " - " — Comma or hyphen carries the load.
+post.md:2:7   error  vocab-utilize  "utilize"  →  swap → "use" — Plain word.
+```
+
+### JSON output
+
+`--format json` prints an array (`[]` when clean — always valid JSON). Each
+entry:
+
+```json
+{
+  "file": "post.md",
+  "line": 1,
+  "col": 14,
+  "ruleId": "punct-em-dash",
+  "severity": "error",
+  "matched": "—",
+  "alter": "swap → \",\" | \" - \" — Comma or hyphen carries the load.",
+  "rationale": "Hard AI tell. Operator-mandated permanent rule.",
+  "source": "operator/knowledge/writing/voice-guide.md"
+}
+```
+
+## Exit codes
+
+This command uses **lint-semantic exit codes** (ESLint/ruff-style), where the
+code reports the worst severity among the *reported* (post-floor) findings:
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean — no findings at/above the floor (info-only also exits 0) |
+| `1` | At least one `error` finding |
+| `2` | `warning` findings only (no errors) |
+| `3` | Usage / IO / config error (bad flag, missing file, malformed corpus) |
+
+> **Note — deviation from tooling standard §6.** The platform standard reserves
+> exit `1` for usage errors and `2`/`3` for operational/transport failure. A
+> linter's exit code is load-bearing differently: automation needs to branch on
+> *what was found*, not just *did the tool run*. So this command follows the
+> universal linter convention (`1` = findings, higher = clean-vs-broken) and
+> maps every non-finding failure to `3`. This is the only `pa` verb that
+> deviates, and it does so intentionally.
+
+## Rule corpus schema
+
+The corpus is a JSON array of independent rule objects (order does not matter).
+The loader validates strictly — a malformed corpus is a config error (exit 3),
+never a silent skip.
+
+```jsonc
+{
+  "ruleId": "punct-em-dash",          // kebab-case, unique across the corpus
+  "category": "punctuation",          // punctuation | vocabulary | phrase |
+                                      //   reaction-phrase | filler | structural |
+                                      //   format | count
+  "surface": ["all"],                 // any of: all linkedin article newsletter reply
+  "severity": "error",                // error | warning | info
+  "detect": { /* see below */ },
+  "alter":  { /* see below */ },
+  "rationale": "Hard AI tell.",       // why the rule exists
+  "source": "operator/knowledge/writing/voice-guide.md"  // human-readable home
+}
+```
+
+### `detect`
+
+| `type` | Fields | Behaviour |
+|---|---|---|
+| `literal-phrase` | `phrase`, `caseSensitive` (default `false`), `wordBoundary` (default `true`) | Matches the phrase as text. Word boundaries are applied at word-character edges only. |
+| `regex` | `pattern`, `caseSensitive` (default `false`) | Matches the pattern. Scanned line-by-line, so positions are exact and negated classes can't swallow newlines. |
+| `count` | `pattern`, `max` | Counts matches document-wide; flags every occurrence **beyond** `max`. Use `(?:^\|\n)…` anchoring to count line openers. |
+
+### `alter`
+
+| `kind` | Fields | Rendered as |
+|---|---|---|
+| `swap` | `with` (array of replacement strings), `guidance` | `swap → "a" \| "b" — guidance` |
+| `cut` | `guidance` | `cut → guidance` |
+| `rename` | `guidance` (open-ended rephrase instruction) | `rename → guidance` |
+
+## Examples
+
+```sh
+# Lint a draft against the default operator corpus.
+pa lint linkedin drafts/post.md
+
+# Lint a reply, surfacing warnings too, as JSON.
+pa lint linkedin drafts/reply.md --surface reply --severity warning --format json
+
+# Lint against an explicit corpus (e.g. in CI or a fixture).
+pa lint linkedin post.md --rules path/to/linkedin-rules.json
+```

package/dist/engineering-pa-cli/docs/secrets.md

@@ -0,0 +1,221 @@
+# Secrets Management
+
+Identity: `ai.stravica.ops.secrets` — CLI alias `secrets`.
+
+Dave uses SOPS with age encryption for secrets management. Secrets are encrypted at rest and stored in `.vault/` within the repository. The encrypted file is safe to commit to git — only the holder of the private key can decrypt it.
+
+## Status
+
+Implemented: `init`, `get`, `set`, `list`, `delete`, `rotate`, `status`, `backup`, `vaults`, `find` (alias `which`), `verify`. No npm dependencies — shells out to `sops` and `age` via `node:child_process.spawn`.
+
+`set` additionally supports `--canonical-clone PATH` (write a canonical clone's vault file first, then the resolved workspace copy — aborts before touching the workspace copy if the canonical write fails). `verify --values --against PATH` does a byte-level comparison of DECRYPTED values between the resolved vault and a reference vault at PATH — never a decrypt-only pass. See "Value-compare verification" and "Canonical-first writes" below.
+
+`get`/`set` run without `--scope`/`--file` now resolve a **default scope** — `$SECRETS_DEFAULT_SCOPE` env var, then `"defaultScope"` in `~/.config/stravica-pa/defaults.json`, then the calling PA's own `agents/<name>/identity.json`, then the legacy single-file vault as a last resort. Every such invocation prints a one-line stderr notice naming the target vault BEFORE the operation runs, including the legacy-fallback case ("no scope specified and no default configured") — see `secrets --help` → "Default scope" for the full precedence and example notices.
+
+## Prerequisites
+
+Two tools are required:
+
+- **age** — modern encryption tool
+  - macOS: `brew install age`
+  - Debian/Ubuntu: `sudo apt install age`
+  - Manual: https://github.com/FiloSottile/age/releases/latest
+
+- **SOPS** — encrypted file editor
+  - macOS: `brew install sops`
+  - Debian/Ubuntu: download from https://github.com/getsops/sops/releases
+  - Manual: https://github.com/getsops/sops/releases/latest
+
+## Invoke
+
+The CLI shim is `core/tools/secrets/bin/secrets`. You can run it directly with `node`:
+
+```bash
+node core/tools/secrets/bin/secrets <verb> [ARGS]
+```
+
+Or via the per-tool symlink convention (see tooling standard §14):
+
+```bash
+secrets <verb> [ARGS]
+```
+
+## Commands
+
+```bash
+# Initialise the vault (generate keys, create config, empty encrypted store)
+node core/tools/secrets/bin/secrets init
+
+# Store a secret
+node core/tools/secrets/bin/secrets set API_KEY "sk-abc123"
+
+# Retrieve a secret
+node core/tools/secrets/bin/secrets get API_KEY
+
+# List all secret names (values are not shown)
+node core/tools/secrets/bin/secrets list
+
+# Remove a secret
+node core/tools/secrets/bin/secrets delete API_KEY
+
+# Re-encrypt all secrets with the current recipients
+node core/tools/secrets/bin/secrets rotate
+
+# Check vault health (exit 0 when initialised, 1 otherwise)
+node core/tools/secrets/bin/secrets status
+
+# Open a browser with a QR code of the master key for backup
+node core/tools/secrets/bin/secrets backup
+
+# Write a canonical clone's vault FIRST, then the workspace copy second.
+# Aborts (exit 2) before touching the workspace copy if the canonical
+# write fails (e.g. the existing canonical store can't be decrypted).
+node core/tools/secrets/bin/secrets set API_KEY "sk-abc123" --canonical-clone /path/to/canonical/vault/scope.enc.json
+
+# Byte-level comparison of DECRYPTED values against a reference vault.
+# --values is required — there is no decrypt-only verification mode
+# (decrypt-only false-passes a vault that decrypts cleanly but holds the
+# wrong content, e.g. a clobbered/stale copy with placeholder values).
+node core/tools/secrets/bin/secrets verify --values --against /path/to/other/vault/scope.enc.json
+```
+
+### Canonical-first writes (`set --canonical-clone`)
+
+Without the flag, `set` behaves exactly as before — it writes only the
+resolved workspace copy. With `--canonical-clone PATH`, `set`:
+
+1. Resolves `PATH` the same way `--file` resolves any other vault (its
+   own `.sops.yaml` expected alongside it), reusing this host's own key
+   material (`keyDir`/`keyFile`) — the canonical clone and the workspace
+   copy are expected to share recipients in practice (same operator,
+   same device).
+2. Decrypts the existing canonical store (if any) and writes the new key
+   into it. **If this fails for any reason — the existing canonical
+   store can't be decrypted, or the encrypt itself fails — `set` aborts
+   with exit 2 and the workspace copy is never touched.**
+3. Only on canonical success does it proceed to the existing
+   decrypt-mutate-encrypt cycle against the resolved workspace copy.
+
+This closes the "device-side vault mutation only round-trips halfway"
+class: a device-side `secrets set` that updates the workspace copy but
+never reaches canonical leaves the two vaults silently diverged until the
+next down-path materialisation clobbers the device's fresher value.
+`--canonical-clone` makes the canonical write the FIRST, gating step —
+the workspace never ends up ahead of canonical.
+
+### Value-compare verification (`verify --values --against`)
+
+Any vault verification that stops at "the store decrypts" is a false-pass
+waiting to happen: an always-take-canonical materialisation can silently
+overwrite a device's real secret values with stale or placeholder
+content, and the decrypt still succeeds (same recipients) — only a
+byte-level VALUE comparison against a known-good reference catches it.
+`secrets verify` therefore has no decrypt-only mode at all; `--values` is
+required, and omitting it is a usage error (exit 1), not a lesser check.
+
+`--against PATH` names the reference vault (any vault file, resolved the
+same way `--file` resolves elsewhere). Both vaults are decrypted and
+compared key-by-key; the report never prints a decrypted value, only the
+per-key result:
+
+- `same` — both sides hold byte-identical values
+- `differs` — both sides have the key, values differ
+- `missing-in-reference` — key exists in the working vault only
+- `missing-in-working` — key exists in the reference vault only
+
+Exit 0 only when every key is `same`; exit 2 otherwise (or if either side
+fails to decrypt at all).
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | OK |
+| `1` | Usage / not-initialised / not-found |
+| `2` | Operational failure (sops decrypt or encrypt failed, bad JSON) |
+| `3` | Transport failure (spawn failed) |
+
+## Operational discipline
+
+- The private key must never be committed. It lives only at `~/.config/dave/age-key.txt`, with mode `600` on a `700` key directory.
+- All sops/age invocations are spawned with arguments as an array — no shell interpolation surface.
+- Tests must never touch the real `~/.config/dave/` or repo `.vault/`. The test helpers mint a disposable temp directory for every case.
+
+## Project layout
+
+```
+core/tools/secrets/
+  bin/secrets            # node shebang shim — one line
+  package.json           # name: ai.stravica.ops.secrets, type: module, no deps
+  README.md              # this file
+  src/
+    cli.mjs              # verb routing + exit-code translation
+    vault.mjs            # domain + sops/age spawn chokepoint
+    commands/
+      init.mjs           # generate keypair, write recipients/config, empty store
+      get.mjs            # print a single secret value
+      set.mjs            # upsert and re-encrypt
+      list.mjs           # sorted key names
+      delete.mjs         # remove and re-encrypt
+      rotate.mjs         # decrypt + re-encrypt with current recipients
+      status.mjs         # vault health report
+      backup.mjs         # render QR-code HTML and open it in the default browser
+      backup-template.mjs  # HTML + embedded alphanumeric QR generator
+      vaults.mjs         # enumerate every visible vault (names only, no decryption)
+      find.mjs           # report which vault(s) contain a key by name (alias: which)
+      verify.mjs         # byte-level DECRYPTED-value comparison against a reference vault
+  test/
+    helpers.mjs          # temp-vault isolation
+    *.test.mjs           # node:test coverage per subcommand + CLI routing
+```
+
+## Security model
+
+- The **private key** (`~/.config/dave/age-key.txt`) never enters the repository. It is gitignored and lives only on the machine where secrets need to be decrypted.
+- The **public key** (`.vault/recipients.txt`) is committed. It allows anyone with repo access to encrypt new secrets, but only the private key holder can decrypt them.
+- The **encrypted secrets file** (`.vault/secrets.enc.json`) is committed. It is safe to store in git because its contents are encrypted with the age public key.
+- SOPS handles encryption/decryption transparently. The `.vault/.sops.yaml` config tells SOPS which key to use.
+
+## Key rotation
+
+If you need to rotate keys (e.g. a machine was compromised):
+
+1. Generate a new keypair: `age-keygen -o ~/.config/dave/age-key.txt`
+2. Update `.vault/recipients.txt` with the new public key
+3. Update `.vault/.sops.yaml` with the new public key
+4. Run `node core/tools/secrets/bin/secrets rotate` to re-encrypt all secrets with the new key
+
+Note: you need the old private key present to decrypt before re-encrypting. If the old key is lost, the secrets cannot be recovered.
+
+## Multi-machine setup
+
+To use secrets on a second machine:
+
+1. Clone the repository (public key and encrypted secrets are included)
+2. Copy your private key to `~/.config/dave/age-key.txt` on the new machine
+3. Secrets are immediately accessible via `node core/tools/secrets/bin/secrets get`
+
+The private key must be transferred securely (e.g. via a password manager, secure file transfer, or physical media). Never send it over unencrypted channels.
+
+## Backup
+
+Back up `~/.config/dave/age-key.txt` securely. If you lose it, your encrypted secrets are unrecoverable. The encrypted file in git is useless without the private key.
+
+The `backup` command renders the master key as a QR code in a temporary HTML file and opens it in the default browser. The file self-destructs after 30 seconds. No browser-automation dependency — the QR generator is a small pure-JS module embedded in the generated HTML.
+
+## Tests
+
+```bash
+node --test core/tools/secrets/test/*.test.mjs
+```
+
+The integration tests require `sops` and `age` on PATH and skip gracefully when either is missing. The CLI-routing tests always run.
+
+## The tooling standard
+
+This tool conforms to the standard in [`core/knowledge/standards/tooling.md`](../../knowledge/standards/tooling.md). Notable points:
+
+- Zero npm dependencies. Node stdlib only.
+- All external effects (sops, age, fs writes in the vault path) route through `src/vault.mjs`.
+- Commands return numeric exit codes or throw `VaultError` with an `exitCode` property. The CLI wrapper translates to `process.exit`.
+- JSON property names are camelCase.

package/dist/engineering-pa-cli/docs/smoke.md

@@ -0,0 +1,113 @@
+# smoke
+
+## Identity
+
+- **Name**: `ai.stravica.platform.smoke`
+- **Alias**: `smoke`
+- **Purpose**: Fresh-clone smoke suite for the Dave platform. Simulates a clean clone and validates structure, server, APIs, and CLI tools before shipping.
+
+## Status
+
+Implemented: all 52 assertions from the legacy `test/smoke.sh` (path existence, workspace server boot, HTML page HTTP 200s, JSON API validity, CLI `--help` invocations, `secrets` execution, `dave.sh --help`).
+
+Deferred: none. This is a direct Node.js port with no scope change.
+
+## Install / invoke
+
+From the repo root:
+
+```sh
+npm run test:smoke
+```
+
+Or invoke the binary directly:
+
+```sh
+node core/tools/smoke/bin/smoke
+```
+
+## Commands
+
+The tool has a single default command; `npm run test:smoke` is the canonical invocation.
+
+| Flag            | Purpose                                                         |
+|-----------------|-----------------------------------------------------------------|
+| `--help, -h`    | Print usage and exit 0                                          |
+| `--root <path>` | Repo root to smoke-test (default: auto-detected from the binary location) |
+| `--port <n>`    | HTTP port for the workspace server during the run (default: 4201) |
+
+No verbs, no subcommands — this is a single-purpose runner.
+
+## Exit codes
+
+| Code | Meaning                                                              |
+|------|----------------------------------------------------------------------|
+| `0`  | All checks passed                                                    |
+| `1`  | One or more checks failed, or a usage error (bad argument)           |
+| `2`  | Internal error (uncaught exception in the tool itself)               |
+| `3`  | IO / transport failure during setup (tempdir, copy, or server launch)|
+
+## Operational discipline rules
+
+- **No side effects on the source tree.** The suite copies the repo into a temp directory (`rm -rf`'d on exit) and performs every assertion against the copy. The source tree is only read.
+- **Single chokepoint for external effects.** `src/runner.mjs` owns every process spawn, HTTP fetch, and filesystem mutation. Commands and checks delegate to it; no other module may spawn or fetch.
+- **Server lifecycle is bracketed.** The workspace server is launched once per run, killed in `finally`, and never leaks across invocations. If a check throws, cleanup still runs.
+- **HTTP / JSON checks are gated.** If the server fails to come up within the ready-probe budget, downstream HTTP and JSON assertions are skipped (not failed) — matching the legacy behaviour.
+- **Zero npm dependencies.** The tool uses only `node:` built-ins (`util`, `child_process`, `fs/promises`, `path`, `os`, `test`, `assert/strict`) plus the global `fetch`.
+
+## Project layout
+
+```
+core/tools/smoke/
+  bin/smoke                # node shebang shim — one line
+  package.json             # name, version, type: module, no dependencies
+  README.md                # this file
+  src/
+    cli.mjs                # parseArgs, --help, exit-code translation
+    checks.mjs             # pure check plan: path, http, json, cli classes
+    runner.mjs             # external-effects chokepoint (spawn, fetch, fs)
+    commands/
+      run.mjs              # orchestrates copy → launch → check → cleanup
+  test/
+    checks.test.mjs        # plan shape, parity with legacy smoke.sh
+    cli.test.mjs           # arg parsing and exit-code cases
+    run.test.mjs           # orchestration via fake runner
+```
+
+Per-entry rationale:
+
+- **`bin/smoke`** — one-line shim; logic lives in `src/cli.mjs`.
+- **`src/cli.mjs`** — the only module that calls `process.exit`. Commands return numbers or throw; this wrapper translates.
+- **`src/checks.mjs`** — pure data + helpers. Defines the ordered plan. No I/O.
+- **`src/runner.mjs`** — chokepoint for every external effect. Tests inject fakes here.
+- **`src/commands/run.mjs`** — the single command that orchestrates the suite.
+- **`test/`** — `node:test` files. No separate config.
+
+## Check plan (parity with legacy `test/smoke.sh`)
+
+| Section | Count | Class        | What                                                          |
+|---------|-------|--------------|---------------------------------------------------------------|
+| Step 3  | 1     | `execFile`   | `dave.sh` is an executable file                               |
+| Step 4  | 1     | `file`       | `dave.ps1` exists                                             |
+| Step 5  | 33    | `path`       | Expected-path existence (roles, retrieval, desk, workspace app, .gitkeeps, top-level docs) |
+| Step 6-7| 1     | `serverReady`| Workspace server becomes reachable on the test port          |
+| Step 8  | 7     | `httpStatus` | `/`, `home.html`, `onboarding.html`, `tasks.html`, `knowledge.html`, `secrets.html`, `viewer.html` all return 200 |
+| Step 9  | 3     | `jsonValid`  | `/__api/overview`, `/__api/projects`, `/__api/work` return parseable JSON |
+| Step 10-13 | 4  | `cliExit`    | `backlink-indexer.mjs --help`, `graph-builder.mjs --help`, `query.mjs --help`, `desk --help` exit 0 |
+| Step 14 | 1     | `vaultExit`  | `node core/tools/secrets/bin/secrets` exits 0 or 1           |
+| Step 15 | 1     | `cliShell`   | `bash dave.sh --help` exits 0                                 |
+| **Total** | **52** |            |                                                               |
+
+Labels match the bash `PASS:` lines verbatim — CI log comparisons stay valid.
+
+## Tests
+
+```sh
+node --test core/tools/smoke/test/*.test.mjs
+```
+
+The test suite exercises the plan, the CLI wrapper, and the orchestration layer via a fake runner. The real `runner.mjs` is exercised end-to-end by `npm run test:smoke` against the live repo.
+
+## The tooling standard
+
+Governed by [`core/knowledge/standards/tooling.md`](../../knowledge/standards/tooling.md). This tool follows sections §1–§16 as written: identity (§1), Node-only (§2), zero-dep (§3), project structure (§4), CLI conventions (§5), exit codes (§6), chokepoint (§7), testing (§8), README-as-contract (§9), operational discipline (§10), JSON camelCase (§11).