@pretense/cli 0.6.9 → 0.6.11

package/README.md

@@ -1,10 +1,60 @@
 # pretense
 
-Local-first AI firewall. Mutates proprietary code before it leaves your laptop.
-
-Your `getUserPaymentMethod` becomes `_fn8a3c` on the wire to Claude, Codex, Cursor, or any OpenAI-compatible API. The reply gets reversed back to your real names. The LLM never sees your real names. Comments and strings stay byte-exact.
-
-Think locked garage. Your car never leaves.
+Local-first AI firewall. It finds the secrets and PII in a file, swaps them for
+deterministic synthetic values before anything leaves your laptop, and swaps the
+real values back afterwards.
+
+Nothing in this README is written from the spec. Every command below was run
+against the published `@pretense/cli` on 2026-07-21 and its real exit code is
+recorded. Where something does not work yet, this file says so instead of
+pretending.
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     EXECUTABLE-DOCS REGISTRY — read by cli/e2e/docs-commands-execute.test.ts.
+
+     That test extracts every command in every fenced block below, runs it
+     against the built CLI in a temp dir with an isolated HOME, and asserts the
+     exit code. Default expectation is 0; a `console` block that already prints
+     `$ echo $?` needs nothing here, because the doc's own number is lifted out
+     and asserted.
+
+     Two markers, and every one of them requires a reason. (The two lines below
+     use "->" where a real marker uses an em dash, so that these examples are
+     not themselves parsed as markers.)
+       docs-exec:skip   "<command>"   -> why it cannot run in CI
+       docs-exec:expect "<command>" N -> the exit code it really returns
+
+     A marker that matches no command in this file FAILS the test, so this list
+     cannot rot: delete a command from the docs and its marker starts shouting.
+     Add a command and you must run it — there is no third option.
+
+     ── Cannot run here ─────────────────────────────────────────────────────
+     docs-exec:skip "npm i -g @pretense/cli" — mutates the developer's global npm prefix
+     docs-exec:skip "npm i -g @pretense/cli@0.6.9" — mutates the developer's global npm prefix
+     docs-exec:skip "npm i -g @pretense/cli --version 0.6.9" — documented anti-example; npm prints its own version and installs nothing
+     docs-exec:skip "curl -fsSL https://www.pretense.ai/install.sh | sh" — downloads and installs a binary from the network
+     docs-exec:skip "pretense start" — long-running server; it would outlive the suite holding port 9339
+     docs-exec:skip "pretense start --port 9500" — long-running server; it would outlive the suite holding port 9500
+     docs-exec:skip "curl -s http://localhost:9339/health" — needs the proxy from the preceding line, which cannot be started here
+     docs-exec:skip "claude" — third-party CLI that is not a dependency of this repo
+     docs-exec:skip `curl -fsSLO "${BASE}/SHA256SUMS"` — network fetch from the release host
+     docs-exec:skip `curl -fsSLO "${BASE}/SHA256SUMS.cosign.bundle"` — network fetch from the release host
+     docs-exec:skip `curl -fsSLO "${BASE}/${TARGET}"` — network fetch of a large release binary
+     docs-exec:skip `cosign verify-blob \` — needs the cosign binary and the artifacts the skipped curls would fetch
+     docs-exec:skip `grep " ${TARGET}$" SHA256SUMS | shasum -a 256 -c -` — needs SHA256SUMS from the skipped network fetch
+     docs-exec:skip "pretense scan ci" — needs a git working tree with an untracked file; the session dir is deliberately not a git repo
+     docs-exec:skip "git add untracked.ts && pretense scan ci" — stages a file in a git repo; the session dir is deliberately not a git repo
+
+     ── Runs, and does not exit 0 ───────────────────────────────────────────
+     docs-exec:expect "pretense scan <file|dir>" 1 — findings present in the fixture
+     docs-exec:expect "pretense scan <file> --policy hipaa" 1 — findings present in the fixture
+     docs-exec:expect "pretense scan <file> --policy <preset>" 1 — findings present in the fixture
+     docs-exec:expect "pretense scan <file> --severity high" 1 — the fixture holds a critical finding
+     docs-exec:expect "pretense scan s.ts" 1 — findings present in the fixture
+     docs-exec:expect "pretense scan s.ts --level 1" 1 — L1 finds the fixture secrets
+     docs-exec:expect "pretense scan s.ts --level 9" 3 — invalid level is a usage error (D-02: plain scan usage errors exit 3, distinct from findings=1)
+     docs-exec:expect "pretense scan ci src/" 2 — the session fixture dir holds secrets; 2 is the documented findings code
+     ═══════════════════════════════════════════════════════════════════════ -->
 
 ## Install
 
@@ -12,24 +62,169 @@ Think locked garage. Your car never leaves.
 npm i -g @pretense/cli
 ```
 
-Or with pnpm:
+Verify the install with the only version string in the product that is read from
+the package itself:
+
+```bash
+pretense --version
+```
+
+`pnpm add -g @pretense/cli` also installs and runs `scan`, `mutate` and
+`reverse`. It does **not** currently give you a working `pretense start` — pnpm
+blocks the `better-sqlite3` build script by default and the proxy's audit store
+cannot load its native addon. Use npm if you want the proxy.
+
+There is also a standalone binary that needs no Node at all:
+
+```bash
+curl -fsSL https://www.pretense.ai/install.sh | sh
+```
+
+Use `-fsSL` and the `www` host exactly as written. The apex domain answers with
+a redirect; without `-L` curl prints the redirect page and your shell tries to
+execute the word `Redirecting...`.
+
+The binary runs `scan`, `mutate` and `reverse`. `pretense start` does **not**
+work on it today — see [The proxy](#the-proxy).
+
+To pin a version, attach it to the package name:
 
 ```bash
-pnpm add -g @pretense/cli
+npm i -g @pretense/cli@0.6.9      # correct
+npm i -g @pretense/cli --version 0.6.9   # WRONG — npm reads --version as its own flag
+```
+
+The second form exits 0, prints npm's own version, and installs nothing.
+
+Requires Node.js 20 or newer (`engines.node` is `>=20.0.0`). The standalone
+binary has no Node requirement.
+
+## Three verbs and one flag
+
+```bash
+pretense scan <file|dir>              # what would leak
+pretense mutate <file> --map m.json -i  # swap it before the AI sees it
+pretense reverse <file> --map m.json -i # put the real values back
+pretense start                        # proxy mode (npm install only, see below)
+pretense scan <file> --policy hipaa   # the flag most people type
+```
+
+Two honest caveats about the verbs:
+
+- `mutate` and `reverse` take **one file at a time**. `pretense mutate .` and
+  `pretense mutate src` both fail with `Cannot read file: .` and exit 1.
+  Directory mutation is not available yet. `scan` does accept a directory.
+- `mutate` **previews by default** — it prints to stdout and leaves the file
+  untouched. `-i` writes in place. `-i` without `--map` is irreversible; there
+  is no global map store to recover from.
+
+## The 30-second walkthrough
+
+This is a complete, copy-pasteable session with synthetic values. The output
+below is verbatim from a real run; only the mutated values will differ on your
+machine (they are salted per install).
+
+```bash
+mkdir demo && cd demo && mkdir src
+cat > src/config.ts <<'EOF'
+export const DB_URL = "postgres://placeholder_user:placeholder_pw@db.example.invalid:5432/appdb";
+export const AWS_KEY = "AKIAEXAMPLEEXAMPLE00";
+export const CONTACT = "nobody@example.invalid";
+EOF
+```
+
+**1. Record the original bytes.**
+
+```console
+$ shasum -a 256 src/config.ts
+8cbe81bb0608b0e8ed23fa9dea1f4d0e89921abb857612d7182e11db0c448258  src/config.ts
+```
+
+**2. See what would leak.**
+
+```console
+$ pretense scan src/config.ts
+
+  Pretense Scan — src/config.ts
+
+  Patterns: 98 | Duration: 46.19ms
+
+  🔴  database-url                   block    post...ppdb
+  🔴  aws-access-key                 block    AKIAEX...LE00
+  🟡  email                          warn     n***@example.invalid
+
+  Total: 3 findings | 2 blocked, 0 redacted
+
+$ echo $?
+1
 ```
 
-Both install the `pretense` command — the package name is scoped, the binary is not.
+Exit 1 is expected — see [Exit codes](#exit-codes).
+
+**3. Swap the secrets, keeping a reversal map.**
+
+```console
+$ pretense mutate src/config.ts --map map.json -i
+  ✓ Wrote encrypted reversal map → map.json (AES-256-GCM, mode 0600)
+  ✓ Mutated 3 secrets in src/config.ts (in-place)
+
+$ cat src/config.ts
+export const DB_URL = "postgres://pretense_mut_u2ovo8wiyqa:pretense_mut_pvck8pnmq1g@db.example.invalid:5432/appdb";
+export const AWS_KEY = "AKIA3ff0p1g3d9vdf2n0";
+export const CONTACT = "1llwxqz4wi36bdpgffjt6j";
+```
 
-Requires Node.js 20 or newer.
+Structured credentials keep their shape — the Postgres URL is still a parseable
+Postgres URL, the AWS key still carries its `AKIA` prefix — so the file stays
+useful as context for a model. Shape preservation is not universal: the email
+address above came back as a bare token, not a synthetic email.
 
-## Verifying a release
+Note what did **not** change: `DB_URL`, `AWS_KEY`, `CONTACT`. Pretense mutates
+secret and PII *values*, not identifiers.
 
-The released binaries are signed with Sigstore cosign (keyless — no key to
-fetch or leak). Each release ships a `SHA256SUMS` file plus a
-`SHA256SUMS.cosign.bundle` signature covering it. To verify a download:
+**4. Put the real values back and prove it was exact.**
+
+```console
+$ pretense reverse src/config.ts --map map.json -i
+  ✓ Restored .../src/config.ts (3 tokens, in-place)
+
+$ shasum -a 256 src/config.ts
+8cbe81bb0608b0e8ed23fa9dea1f4d0e89921abb857612d7182e11db0c448258  src/config.ts
+```
+
+Byte-identical to step 1.
+
+## Verify it yourself
+
+Four checks a skeptical reviewer can run in a couple of minutes. Each one can
+fail, which is the point.
+
+**1. The round trip is byte-exact, not approximately exact.**
 
 ```bash
-VERSION=0.6.8
+B=$(shasum -a 256 src/config.ts | cut -d' ' -f1)
+pretense mutate src/config.ts --map map.json -i
+pretense reverse src/config.ts --map map.json -i
+A=$(shasum -a 256 src/config.ts | cut -d' ' -f1)
+[ "$A" = "$B" ] && echo IDENTICAL || echo DIFFER
+```
+
+**2. The reversal map holds no plaintext.** Grep it for a secret you put in.
+An exit code of 1 from `grep` means not found, which is what you want.
+
+```console
+$ grep -c placeholder_pw map.json
+0
+$ echo $?
+1
+$ ls -l map.json
+-rw-------  1 you  staff  1215  map.json
+```
+
+**3. The release binaries are signed, and the signature can be broken.**
+
+```bash
+VERSION="$(pretense --version)"
 TARGET=pretense-darwin-arm64
 BASE="https://www.pretense.ai/releases/${VERSION}"
 
@@ -42,91 +237,374 @@ cosign verify-blob \
   --certificate-identity "https://github.com/pretense-a1/pretense/.github/workflows/release.yml@refs/tags/v${VERSION}" \
   --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
   SHA256SUMS
+# Verified OK
 
-grep " ${TARGET}$" SHA256SUMS | sha256sum -c -   # shasum -a 256 -c - on macOS
+grep " ${TARGET}$" SHA256SUMS | shasum -a 256 -c -   # sha256sum -c - on Linux
+# pretense-darwin-arm64: OK
 ```
 
-Verify the signature over `SHA256SUMS` *before* trusting any hash inside it —
-checking a binary against an unverified checksum file proves nothing.
+Verify the signature over `SHA256SUMS` *before* trusting any hash inside it.
+Then confirm the check is real: append a byte to `SHA256SUMS` and re-run
+`cosign verify-blob` — it must fail with `invalid signature`.
+
+Take `VERSION` from `pretense --version`, not from this file. Signature bundles
+are not published for every historical version.
 
-Full details, including the regexp form for automation and why npm provenance
-is not used, are in [docs/verifying-releases.md](../docs/verifying-releases.md).
+Full details, including the regexp form for automation and why npm provenance is
+not used, are in [docs/verifying-releases.md](../docs/verifying-releases.md).
 
-## First 5 minutes
+## The proxy
 
-1. Initialize Pretense in your repo.
+`pretense start` runs a local HTTP proxy that applies the same mutation engine to
+LLM API traffic.
 
 ```bash
-cd your-project
-pretense init
+pretense start              # listens on port 9339
+pretense start --port 9500  # any other port
+curl -s http://localhost:9339/health
 ```
 
-2. Scan for secrets and identifiers.
+Then point your tool at it:
 
 ```bash
-pretense scan src
+export ANTHROPIC_BASE_URL=http://localhost:9339
+claude
 ```
 
-3. Start the proxy on port 9339.
-
-```bash
-pretense start
+`OPENAI_BASE_URL` works the same way, as does any client that accepts a base URL.
+
+Read this before you rely on the proxy:
+
+- **npm install only.** `start` crashes on the `curl | sh` binary
+  (`Could not find module root ...`, a native-addon resolution failure inside the
+  compiled runtime) and on a `pnpm add -g` install (build scripts blocked). A fix
+  for the binary is in progress. `npm i -g @pretense/cli` is the only path where
+  `start` runs today.
+- **Upgrading from an older CLI can crash it.** If `~/.pretense/audit.db` was
+  created by an earlier version, `start` exits with
+  `SqliteError: table audit_log has no column named detector_kinds`. There is no
+  schema migration yet. This is a bug, not a configuration problem.
+- **The default is to mutate.** The generated `pretense.yaml` sets
+  `blockMode: mutate`: a request containing a secret is forwarded with the
+  secret replaced by a reversible token, so the upstream never sees plaintext.
+  Set `blockMode: reject` if you want the request refused with HTTP 400
+  instead — that is strict mode, for orgs where a secret must never leave the
+  perimeter even tokenized.
+- **`proxy.port` in `pretense.yaml` is not honoured.** Only `--port` changes the
+  port. `pretense status` also probes 9339 unconditionally, so it reports
+  "Proxy not running" whenever you started on another port.
+- **It listens on every interface, not just loopback.** `lsof` shows the
+  listener bound to `*:9339`, so anything that can reach your machine can reach
+  the proxy. Do not run it on an untrusted network.
+- **There is no dashboard.** Up to 0.6.9 the start banner advertised
+  `Dashboard: http://localhost:9340` and `pretense init` wrote a `dashboardPort`
+  key into `pretense.yaml`. There is no dashboard process at all and
+  nothing listens on 9340, so the banner line, the config key and the
+  `--dashboard-port` flag were all removed. An existing `pretense.yaml` that
+  still sets `dashboardPort` keeps loading; the key is ignored.
+- **The banner's version used to be wrong; it is not any more.** It printed a
+  hardcoded `v0.2.0` for eight releases. Every version this CLI emits —
+  `--version`, the `version` command, the start banner, `/health`, the
+  `x-pretense-version` header, SARIF `tool.driver.version` and the npm
+  postinstall notice — is now injected at build time from `cli/package.json`
+  and asserted equal by the test suite, in the compiled binary as well as the
+  npm bundle.
+
+## Exit codes
+
+Measured, not aspirational.
+
+| Command | Exit | Meaning |
+| --- | --- | --- |
+| `pretense scan <path>` | 0 | no findings |
+| `pretense scan <path>` | 1 | findings present |
+| `pretense scan <path>` | 3 | usage error — unknown flag, invalid `--level`, missing option value. Kept distinct from findings (`1`) so a CI gate can tell a typo from a leak |
+| `pretense scan ci` | 0 | no findings *(see caveat)* |
+| `pretense scan ci` | 2 | findings present |
+| `pretense scan ci` | 1 | the scan could not run — not a git repository, git unavailable, or the given path does not exist |
+| `pretense scan ci` | 1 | usage error — its findings code is `2`, so a bad flag stays on `1` and is already distinct from a leak |
+| `pretense --version`, `init`, `status`, `audit`, `policy`, `credits` | 0 | success |
+| `pretense mutate`, `pretense reverse` | 0 | success |
+| anything else — unknown command, unreadable file, integrity failure, or a bad flag on any command other than plain `scan` | 1 | failure |
+
+In one sentence, because the tests cite this line:
+`pretense scan ci` returns `0` when clean and `2` when findings are present.
+<!-- VERIFIED 2026-07-21 against the built binary: in a git repo with a
+     committed Stripe key, `pretense scan ci` exited 2; after removing and
+     committing, it exited 0. cli/e2e/exit-code-contract.test.ts asserts this
+     exact sentence is present — do not reword it without updating that test. -->
+
+Because a clean `scan` is 0 and a dirty `scan` is 1, `pretense scan . && echo ok`
+never prints `ok` when there is anything to find. That is intentional; use it as
+your gate.
+
+**Caveat on `pretense scan ci`:** with no path argument it emits SARIF over your
+**git-tracked** content (`git ls-files`). Files you have `git add`ed — **staged,
+even if not yet committed** — ARE scanned; the hole is files git has never been
+told about. An **untracked** file (say `untracked.ts`, never `git add`ed) is
+invisible to `git ls-files`, so `scan ci` reports zero results and exits 0 while
+its secret sits on disk:
+
+```console
+$ pretense scan ci          # untracked.ts is not git-tracked, so it is not seen
+$ echo $?
+0                           # 0 results in the SARIF — and the secret is still there
+
+$ git add untracked.ts && pretense scan ci
+$ echo $?
+2                           # now tracked (staging is enough) — the secret is caught
 ```
 
-4. Point your AI tool at the proxy. Example for Claude Code:
+Staged files are not the hole; untracked files are. To gate the whole working
+tree regardless of git state, scan a path directly — `pretense scan .` walks
+everything on disk, and `pretense scan ci <path>` needs no git at all.
 
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:9339
-claude
+**`scan ci` fails CLOSED.** It used to swallow every git failure and report an
+empty SARIF with exit 0, so a run in a directory that was not a git repository —
+a shallow CI checkout, a missing `.git`, git not on `PATH` — marked the gate
+green over a tree it had never read. It now exits `1` with a named message and
+scans nothing silently. Exit `0` from `scan ci` means git answered and the
+answer was clean; it never means "the scan did not happen".
+
+`scan ci` also accepts an explicit path, which needs no git at all and is the
+way to gate a non-repository build:
+
+```console
+$ pretense scan ci src/
 ```
 
-5. Check what got mutated.
+## Command reference
+
+Every line below was executed; the exit code is the one observed.
 
 ```bash
-pretense audit --limit 20
+pretense --version                        # 0  — the authoritative version
+pretense init                             # 0  — writes pretense.yaml + .pretense/
+pretense scan <file|dir>                  # 0 clean / 1 findings
+pretense scan <file> --policy <preset>    # 0 clean / 1 findings
+pretense scan <file> --severity high      # 0 clean / 1 findings
+pretense mutate <file>                    # 0  — preview to stdout, file untouched
+pretense mutate <file> --map m.json -i    # 0  — in place, reversible
+pretense reverse <file> --map m.json -i   # 0  — byte-exact restore
+pretense status                           # 0
+pretense audit --limit 20                 # 0
+pretense audit --json                     # 0  — JSONL; empty state emits 0 bytes
+pretense audit --list-frameworks          # 0
+pretense policy list                      # 0
+pretense policy show <id>                 # 0
+pretense credits                          # 0
+pretense start                            # runs until Ctrl-C; see The proxy
 ```
 
-That is it. Your code is mutated outbound and reversed inbound.
+Run `pretense <command> --help` for the full flag list.
+
+One known rough edge: `pretense init` prints `✓ Added .pretense/ to .gitignore`
+even when there is no `.gitignore` to add it to, in which case it creates
+nothing. Check for the entry yourself, or use `pretense quickstart`, which
+creates the file correctly.
+
+`--level` is a real flag again — see [Detection levels](#detection-levels-l1-and-l2).
+It is a debugging filter, not something most people need to type.
+
+Not documented here because it does not work: `pretense mutate <directory>`, the
+port-9340 dashboard, and `pretense-mcp` (no such binary ships).
+
+### `pretense login` verifies the key
+
+`pretense login --key <key>` (and `pretense auth login`) checks the key against
+`POST /api/cli/auth/validate` before saying anything about it. It reports one of
+three outcomes, and never conflates them:
+
+| Outcome | Message | Exit | Stored? |
+| --- | --- | --- | --- |
+| API accepted the key | `Authenticated. The key was verified by the Pretense API.` | 0 | yes, with `verified: true` |
+| API rejected the key | `The Pretense API REJECTED this key. It will not work.` | 1 | yes, marked rejected — unless a verified key already exists, which is kept |
+| API unreachable, or `--offline` | `Key saved — NOT verified.` + the reason | 0 | yes, with `verified: false` |
+
+Up to 0.6.9 it printed `Authenticated successfully.` for *any* correctly
+prefixed string, with no server call at all.
+
+The key is written in **plaintext** to `~/.pretense/credentials.json` at mode
+`0600`, inside a `~/.pretense` directory at mode `0700`. It is not encrypted:
+anything running as your user can read it. `pretense auth status` says whether
+the stored key was ever verified, and `pretense logout` deletes the file.
+
+Point it at a different backend with `PRETENSE_API_URL`; raise the 5s
+verification timeout with `PRETENSE_API_TIMEOUT_MS`.
+
+## What actually gets mutated
+
+Secret and PII **values**: API keys, database URLs, tokens, email addresses, and
+the rest of the 98 shipped detectors. Substitutions are deterministic for a given
+install: the same input produces the same synthetic value every time, which is
+what makes `reverse` possible. The salt is per-install, so two machines produce
+different synthetics for the same secret.
+
+Identifiers — function, class and variable names — are **not** mutated. Older
+docs claimed `getUserPaymentMethod` would appear as `_fn8a3c` on the wire. It
+does not; it goes over the wire unchanged. Identifier-level mutation is on the
+roadmap and is not in this release.
+
+`reverse` is a strict, byte-exact restore. It verifies a SHA-256 of the whole
+file and refuses to write if anything changed after mutation — so a file an LLM
+has edited will not reverse today. Token-substitution reversal is on the roadmap.
+
+## Where the reversal map lives
+
+In the CLI path, a map exists only where you ask for one, via
+`pretense mutate --map <path>`. It is AES-256-GCM encrypted and written mode
+`0600`.
+
+In the proxy path the reverse map is held in memory for the life of the request
+and is never written to disk — deliberately, so Pretense never becomes an
+at-rest store of your secrets.
+
+Note on the encryption: the AES key sits next to the map at `~/.pretense/keys/`,
+same user, no passphrase or OS keychain. That defeats a stolen, backed-up, or
+accidentally committed map file. It does **not** defeat another process running
+as you. We do not claim "encrypted at rest" to security reviewers, and neither
+should you.
+
+## Compliance presets
+
+`pretense policy list` and `pretense policy show <id>` cover **5** built-in
+presets: `hipaa`, `gdpr`, `soc2`, `nist`, `pci`.
+
+`scan --policy <preset>` re-weights detector severity for that framework. It does
+**not** narrow the scan — you still see every finding, including ones outside
+that framework's scope. Measured on the walkthrough fixture: `scan` reports the
+email finding as `warn`, `scan --policy hipaa` reports the same finding as
+`redact`. Same 3 findings, same 98 patterns, different actions.
+<!-- Measured 2026-07-21 against @pretense/cli@0.6.9. A preset only produces
+     actionOverrides (cli/src/compliance-preset.ts). `mutate --policy` does not
+     exist. Separately, `audit --framework` is backed by a DIFFERENT 36-name
+     registry — the two lists are disjoint, so never quote 36 here. Per the
+     compliance baseline, never quote CMMC_L2 anywhere. -->
+
+`pretense audit --framework <name>` maps findings against a separate, larger set
+of **36** compliance frameworks vendored from the `pretense-compliance-standards`
+dataset (`pretense audit --list-frameworks` prints them). The two lists are not
+the same thing and should never be conflated.
 
 ## Supported languages
 
 TypeScript, JavaScript, Python, Go, Java, C#, Ruby, Rust.
 
-## Supported AI tools
+## Detection levels (L1 and L2)
 
-Anything that talks to an OpenAI-compatible API. Claude Code, Codex CLI, Cursor, Copilot CLI, Continue, Aider, custom scripts. Set the base URL to `http://localhost:9339` and you are done.
+<!-- OBSERVED, not specified. Every output block below was produced on
+     2026-07-21 by installing the packed tarball (npm pack -> npm install into
+     an empty dir with an isolated HOME) and running the commands shown.
+     The "installed user" claim is proved by: cli/package.json#files is
+     ["dist/","README.md","LICENSE"] (no *.node), @pretense/scanner-rs is a
+     devDependency and is `"private": true`, and `tar -tzf` on the packed
+     tarball returns ZERO .node files. -->
 
-## Common commands
+Pretense has two detection passes:
+
+| Level | How it works | What it finds |
+| --- | --- | --- |
+| **L1** | regex over raw bytes | flat secrets and PII — 98 patterns |
+| **L2** | tree-sitter AST + data-flow | credentials regex cannot see, e.g. an opaque literal passed to `client.setApiKey("...")` |
+
+Both run by default and every row is labelled with the level that found it.
+L2 is strictly **additive**: L1 runs first and locks its spans, so a value that
+is both a secret and a code identifier is reported once, by L1, with L1's
+severity. A merged scan can never report fewer findings than L1 alone.
+
+### L2 is not available if you installed from npm
+
+This is the part that matters, and it is the honest answer: **L2 needs a native
+Rust addon that is not published.** It is not in the tarball, so on a normal
+`npm i -g @pretense/cli` it never loads. You get L1 in full, and the CLI tells
+you so rather than quietly reporting less:
 
-```bash
-pretense init                  Initialize .pretense/ in current dir
-pretense scan <file|dir>       Scan for secrets and identifiers
-pretense mutate <file>         Preview a mutation
-pretense reverse <file>        Reverse a mutation using the saved map
-pretense start                 Start the proxy on port 9339
-pretense status                Show plan, quota, seat usage
-pretense audit                 View the audit log
-pretense --version             Print the CLI version
 ```
+$ pretense scan s.ts
 
-Run `pretense <command> --help` for command-specific help.
+  Pretense Scan — s.ts
 
-## How it works
+  Patterns: 98 | Levels: L1 (L2 unavailable) | Duration: 16.25ms
 
-Pretense runs a tiny proxy on `localhost:9339`. Outbound requests to LLM APIs get parsed. Identifiers (variables, functions, classes) get hashed to deterministic stand-ins like `_v8a3c`, `_fn8a3c`, `_cls8a3c`. Comments and string literals are left alone. The LLM response gets passed through a reverse map so your editor sees real names again.
+  ! L2 AST core unavailable (native @pretense/scanner-rs addon not installed for this platform)
+    L1 (regex) ran in full; no finding was dropped.
 
-No code touches our servers. Your mutation map lives in `.pretense/` in your repo. Same as `.git/`.
+  🔴  L1  stripe-secret-key              block    L1:17 len=32
 
-## Plan limits
+  Total: 1 findings | 1 blocked, 0 redacted
+```
 
-Free: 1,000 mutations per 7-day rolling window.
-Pro: 100,000 mutations per 7-day rolling window. $23 per seat per month billed
-annually ($276/seat/year), or $29 per seat billed monthly.
-Enterprise: unlimited. $79 per seat per month billed annually ($948/seat/year),
-or $99 per seat billed monthly. Contact sales for SSO, audit export, custom rules.
+Exit code 1, as with any scan that finds something. `npm install` never needs a
+Rust toolchain, and a missing addon is never an error — it degrades to L1 and
+says the word "unavailable" out loud. The same is true of the `curl | sh`
+binary and of any language for which no grammar is compiled in: L1 always runs
+in full, and a parse failure is never reported as "clean".
+
+Shipping L2 to installed users needs prebuilt binaries for darwin-arm64,
+darwin-x64, linux-arm64, linux-x64 and win32-x64, or a WASM build. That work is
+not done, so no released version of this CLI performs L2 detection.
+
+### `--level`, for debugging
+
+If you have built the addon from source, `--level` filters which pass reports.
+It is a debugging aid — the default (both levels) is what you want:
+
+```bash
+pretense scan s.ts --level 1   # L1 rows only
+pretense scan s.ts --level 2   # L2 rows only
+```
+
+Anything other than `1` or `2` is a usage error and exits `3` (see [Exit codes](#exit-codes) — plain `scan` usage errors are `3`, kept distinct from findings `1`):
+
+```
+$ pretense scan s.ts --level 9
+error: option '--level <n>' argument '9' is invalid. Detection level must be 1 (regex) or 2 (AST).
+$ echo $?
+3
+```
+
+One rough edge, recorded rather than hidden: on a build with no addon,
+`--level 2` prints the "L2 unavailable" notice and then `✓ No secrets or PII
+detected` with exit 0 — it filtered to a pass that could not run. The notice is
+printed, so it is not silent, but the checkmark is misleading. Use the default
+or `--level 1`.
+
+## Plan limits
 
-Check what you have left with `pretense credits` (alias: `pretense tokens`), see the
-full usage table with `pretense usage`, and compare plans with `pretense upgrade`.
+<!-- NUMBERS AND THEIR SOURCE — do not edit without re-reading these.
+     Seats:  packages/billing/src/plan-limits.ts PLAN_CONFIGS (free.maxSeats 3,
+             pro.maxSeats 100) and the backend PLAN_SEAT_LIMITS
+             (FREE 1-3, PRO 1-100, ENTERPRISE 25-100, hard cap MAX_ORG_SEATS
+             100, enforced by assertSeatsValidForPlan — it throws above 100).
+     Counts: PLAN_CONFIGS.mutationsPerPeriod — free 1000, pro 100_000,
+             enterprise null (unlimited), over a ROLLING 7-DAY period.
+     Prices: PLAN_CONFIGS.pricePerSeatCents — free 0, pro 2900,
+             enterprise null (no self-serve price; contact sales).
+             pricePerSeatCents is the MONTHLY rate; annual is 20% off and
+             pricing-consistency.test.ts is the spec.
+     RESET WINDOW: a rolling 7 days on every plan (founder-confirmed
+     2026-07-21). apps/web (api/cli/log/route.ts PERIOD_DAYS = 7), the CLI
+     (cli/src/plan-usage.ts QUOTA_PERIOD_DAYS = 7) and the backend all meter
+     the same window. Do not describe it as a calendar month. -->
+
+Free: $0. 1,000 code protections per 7 days, up to 3 seats.
+Pro: $29 per seat per month, or $23 per seat per month billed annually
+($276/seat/year). 100,000 code protections per 7 days, 1 to 100 seats.
+Enterprise: custom pricing — contact sales. Unlimited code protections,
+25 to 100 seats. SSO/SAML, SIEM and on-prem are gated to this tier and are
+marked coming soon.
+<!-- Enterprise IS custom-priced (founder-confirmed 2026-07-21). Do not print an
+     Enterprise rate. Do not write "5 to 100,000 seats" for either paid tier;
+     the enforced cap is 100 and assertSeatsValidForPlan throws above it.
+     Do not write "SOC 2 exports" — no such export command exists; the only
+     export the CLI has is JSONL via `pretense audit --json`.
+     Log retention is deliberately not listed: five mutually contradictory
+     values exist across the codebase and NONE of them are enforced (no prune
+     job, no clamp on the query window). Add it back when C9 ships. -->
+
+Check what you have left with `pretense credits` (alias: `pretense tokens`), see
+the full usage table with `pretense usage`, and compare plans with
+`pretense upgrade`.
 
 ## License