@cerefox/memory 1.15.2 → 1.15.3

package/docs/guides/api.md

@@ -0,0 +1,297 @@
+# The `/api/v1` HTTP API
+
+`cerefox web` serves a JSON API at `/api/v1` alongside the web UI. It was built
+as the UI's own backend, and since **v1.11.0** it is also usable by other
+clients: any caller can identify itself, so its reads and writes are attributed
+to it rather than to the web app. Since **v1.12.0** it is authenticated for
+callers that are not on the same machine (see below).
+
+This guide covers what you need to call it from something that is not the
+bundled UI. It is not an exhaustive endpoint reference; the routes live in
+`packages/memory/src/web/routes/` and the response shapes are pinned by the zod
+schemas in `_shared/schemas/`.
+
+**If you are choosing a surface, read [`access-paths.md`](access-paths.md)
+first.** MCP is the right answer for most agents. This API is the right answer
+when you want plain HTTP, are already running `cerefox web` (or Cerefox Local),
+and do not want an MCP client in the loop.
+
+---
+
+## Security posture: local by default, key for anything else
+
+Since **v1.12.0** this surface is authenticated for callers that are not on the
+same machine:
+
+> **A request arriving on the loopback interface (`127.0.0.1`) is allowed
+> without a credential. A request arriving on any other interface must present
+> the server's API key** as `Authorization: Bearer <key>`.
+
+So the web UI, agents on the same machine and localhost scripts need nothing,
+while a caller on a Docker network or across a widened bind needs a key:
+
+```bash
+cerefox api-key generate     # cerefox web
+cerefox-local api-key        # Cerefox Local (minted at first boot)
+```
+
+Without a valid key the server answers `401` with a `WWW-Authenticate: Bearer`
+challenge and a `detail` explaining what to do. With no key configured at all,
+the gate is off and the server behaves exactly as it did before v1.12.0, so
+upgrading never breaks a working install.
+
+**→ [`securing-local-access.md`](securing-local-access.md) is the full guide**:
+whether you need a key at all, why it is drawn at the network boundary, the
+container and reverse-proxy recipes, rotation, and what this deliberately does
+not protect.
+
+Two things to carry into the rest of this document:
+
+- **There is no TLS here.** The key authenticates; it does not encrypt. This is
+  still not an internet-facing API. If you need Cerefox reachable over a
+  network you do not control, use the Edge Functions.
+- **`X-Forwarded-For` is never consulted** to decide where a request came from.
+  A same-host reverse proxy therefore makes every request look local; that
+  topology sets `CEREFOX_API_REQUIRE_KEY=1`.
+
+## Identifying your client
+
+By default every call is recorded as the web app: author `web-ui`, author type
+`user`, access path `webapp`. Supply an identity and it is recorded as you.
+
+**This identity is declared, not verified.** It is a label the caller chooses,
+recorded for attribution and record-keeping: so the audit trail says which
+harness wrote a document, so usage analytics can tell your bot's reads from the
+web app's, and so an agent-authored ingest is queued for review (while the
+review workflow is on). It is not a
+credential, it grants nothing, and nothing checks it. See
+[Attribution is not authentication](#attribution-is-not-authentication) below
+before relying on it for anything else.
+
+Three optional fields:
+
+| Field | Header | Recorded as | Default |
+|---|---|---|---|
+| author | `X-Cerefox-Author` | `cerefox_audit_log.author` on writes | `web-ui` |
+| requestor | `X-Cerefox-Requestor` | `cerefox_usage_log.requestor` on reads and writes | `web-ui` |
+| author type | `X-Cerefox-Author-Type` | `cerefox_audit_log.author_type` | `user` |
+
+`author_type` must be `user` or `agent`. Anything else is a `400` naming the
+two valid values.
+
+**Headers work on every method.** A `GET` cannot carry a body, and reads are
+half the point of attribution, so headers are the primary mechanism. Endpoints
+that take a JSON body (or a multipart form) also accept the same three as
+fields in it, for clients that find that more natural. If both appear, the
+header wins.
+
+```bash
+# A write, attributed
+curl -X POST http://127.0.0.1:8000/api/v1/ingest \
+  -H 'Content-Type: application/json' \
+  -H 'X-Cerefox-Author: my-bot' \
+  -H 'X-Cerefox-Author-Type: agent' \
+  -d '{"title": "Meeting notes", "content": "# Notes\n\n..."}'
+
+# A read, attributed
+curl http://127.0.0.1:8000/api/v1/documents/<uuid> \
+  -H 'X-Cerefox-Requestor: my-bot'
+```
+
+`author` and `requestor` stand in for each other. They name one actor; the
+split is historical (the MCP tools used `requestor` on reads and `author` on
+writes until v1.13.1, which collapsed them to `author` with `requestor` kept as
+an alias). Supplying either identifies you for both, so a client that only sets
+`X-Cerefox-Author` still has its reads attributed correctly.
+
+### Two consequences worth knowing before you use it
+
+**`author_type: agent` marks your documents as pending review.** An
+agent-authored ingest is recorded `pending_review` rather than `approved`,
+exactly as it is over MCP. That equivalence is the point of the feature: the
+same actor is recorded, and treated, identically whichever transport it used.
+If you want your writes approved on arrival, send `user` (or send nothing).
+
+Whether anyone *sees* that status is the store's `review_workflow_enabled`
+flag. With the workflow **off** (the default on a fresh v1.13.0+ install) the
+API does not expose review status at all: no row carries a `review_status`
+key, `GET /search?review_status=…` is a `400`, and
+`POST /documents/{id}/review-status` is a `404`. The status is still recorded
+(v1.13.1), so turning the workflow on later shows exactly what the store would
+have had all along. Read the flag from `GET /config/review_workflow_enabled`
+if your client needs to know. Attribution is unaffected either way. See
+[configuration.md → Review Workflow](configuration.md#review-workflow).
+
+**Identifying yourself changes the access path.** There is deliberately no way
+to ask for a particular `access_path`: the server derives it. Supply any
+identity field and the operation is logged as `api`; supply none and it is
+logged as `webapp`. The reasoning is that `access_path` is the one field in the
+usage log the server still sets itself, so accepting it from the caller would
+let a client misreport which transport it used. In the Analytics dashboard,
+`api` operations count toward the agent total; `webapp` does not.
+
+### Attribution is not authentication
+
+`author`, `requestor` and `author_type` are **declared by the caller and taken
+at face value**. Nothing verifies them, here or anywhere else in Cerefox: MCP
+takes `author` as a client-declared string, and the Edge Functions accept
+whatever `requestor` arrives. Any client can send any name, including a name
+another client uses.
+
+They exist for **attribution and record-keeping**: a legible audit trail, usage
+analytics that can tell callers apart, and the review-queue behaviour of
+`author_type: agent` while the review workflow is on. They are not a security measure, they do not establish an
+authenticated identity, and no access decision is made on them. Treat a name in
+the audit log as "what the caller said", never as "who the caller was".
+
+The API key added in v1.12.0 (#229) does not change this. It proves a caller is
+*allowed to talk to this server*; it does not prove the caller is *who it says
+it is*. A remote client holding the key can still send any `author` it likes.
+Authentication and attribution stay separate on purpose — conflating them would
+produce a design that does neither well.
+
+`require_requestor_identity` and `requestor_identity_format` do **not** apply to
+this surface. They are enforced by the Edge Functions only. See
+[`configuration.md`](configuration.md).
+
+---
+
+## Endpoints
+
+**A machine-readable OpenAPI 3.1 document lives at
+[`docs/api/openapi.json`](../api/openapi.json).** If you are generating a client
+or a tool set, read that rather than this table: it carries the request and
+response *shapes*, the path parameters and the error model, which a prose table
+cannot. Point any OpenAPI tool at it.
+
+It is **generated** (`bun scripts/gen_openapi.ts`) from three sources that are
+each kept honest on their own: the route registrations, the summaries in the
+table below, and the zod schemas in `_shared/schemas/`. Those schemas are
+asserted against a running server by `api-schema-truth.test.ts`, so the spec
+describes what the API returns rather than what someone believed it returned.
+
+Coverage is stated in the document itself under `x-cerefox-coverage`. Endpoints
+with no modelled shape are listed there and get no response schema rather than
+an invented one — a spec that guesses is worse than one that admits a gap.
+
+Base URL is wherever `cerefox web` is listening (`http://127.0.0.1:8000` by
+default; Cerefox Local picks its own port and `cerefox-local status` prints it).
+
+| Method + path | Purpose |
+|---|---|
+| `GET /version` | Server version and environment label. |
+| `GET /schema-version` | Deployed schema version. |
+| `GET /openapi.json` | This API's OpenAPI 3.1 description, served by the version you are talking to. Every `/api/v1` response points at it with `Link: </api/v1/openapi.json>; rel="service-desc"` (RFC 8631). |
+| `GET /search?q=…` | Hybrid search (FTS + semantic). `&review_status=approved\|pending_review` filters server-side; `400` while the review workflow is off. |
+| `GET /dashboard`, `GET /dashboard/recent-docs` | Dashboard aggregates. |
+| `GET /documents/{id}` | Full document, with metadata, projects and versions. |
+| `GET /documents/{id}/chunks` | The document's chunks. |
+| `GET /documents/{id}/versions` | Version history. |
+| `POST /documents/{id}/versions/{version_id}/archive` | Archive or unarchive one stored version (body `{ "archived": true\|false }`). Archiving strips a version's search artifacts; its content is kept as the safety copy. |
+| `GET /documents/{id}/download` | Raw markdown. |
+| `GET /documents/trash` | Soft-deleted documents, newest first, `limit` ≤ 500. The exact total is in the `X-Total-Count` response header (v1.14.1). |
+| `POST /documents/metadata-search` | Query by metadata / project / time, no text query. |
+| `GET /metadata-keys` | Metadata keys with counts and example values. |
+| `GET /resolve-link`, `GET /check-filename` | Link and title resolution helpers. |
+| `POST /ingest` | Create or update from JSON (`title`, `content`, …). Unknown fields are a `400`. |
+| `POST /ingest/file` | Create from a multipart file upload. |
+| `POST /documents/{id}/upload` | Replace a document's content from a file. |
+| `POST /documents/{id}/edit` | Update title, content, metadata, projects. Unknown fields are a `400`. |
+| `DELETE /documents/{id}` | Soft-delete (to trash). |
+| `POST /documents/{id}/restore` | Restore from trash. |
+| `DELETE /documents/{id}/purge` | Permanent delete. Irreversible. |
+| `POST /documents/{id}/review-status` | Approve or re-queue for review. `404` while the review workflow is off. |
+| `GET /projects`, `POST /projects`, `PUT /projects/{id}`, `DELETE /projects/{id}` | Project CRUD. |
+| `GET /projects/{id}/documents` | A project's documents. |
+| `GET /config`, `GET /config/{key}`, `PUT /config/{key}` | Runtime config. |
+| `GET /audit-log` | Audit trail, filterable. |
+| `GET /preferences`, `PUT /preferences` | Web UI preferences (currently the colour scheme), stored in a file in the user-state dir, not the database. Registers even when Supabase is not configured. |
+| `GET /docs`, `GET /docs/{path}` | The guides bundled with this server: a listing, and one document's markdown. Serves the shipped copies, so it answers the same content regardless of what is in the knowledge base. |
+| `GET /usage-log`, `GET /usage-log/summary`, `GET /usage-log/export.csv` | Usage queries. |
+
+Paths are shown without the `/api/v1` prefix for width; every one carries it.
+The writes and the two reads that log usage (`/search`, `/documents/{id}`)
+honour the identity headers. `/version` needs nothing.
+
+### Every mutation needs a concurrency token
+
+Cerefox uses optimistic locking, and this API is no exception. Read the
+document first: `GET /documents/{id}` returns its `content_hash`. Then send
+that hash back with the write. A stale hash is a `409` carrying `current_hash`,
+so you can re-read without a second round trip. Sending no hash (and no
+`last_write_wins`) is a `400` with `CEREFOX_TOKEN_REQUIRED`.
+
+| Write | Where the hash goes | `last_write_wins` |
+|---|---|---|
+| `POST /ingest` with `document_id`, or with `update_if_exists` matching a document | `expected_content_hash` in the body | Accepted |
+| `POST /documents/{id}/edit` | `expected_content_hash` in the body. Checked on every save, including a metadata-only one | Accepted |
+| `POST /documents/{id}/upload`, `POST /ingest/file` with `update_existing` | `expected_content_hash` form field | `last_write_wins=true` form field |
+| `DELETE /documents/{id}` | `X-Cerefox-Expected-Content-Hash` header, or `expected_content_hash` query parameter | Not accepted |
+| `POST /documents/{id}/restore`, `DELETE /documents/{id}/purge` | No hash | Not applicable |
+
+`last_write_wins` skips the check. Use it only when an external source of truth
+(a file you are syncing, say) makes a conflict meaningless; there is no implicit
+default. Creating a new document needs no hash.
+
+**Check the status code, not just the body.** Every refusal is a real HTTP
+status: `400` for a malformed or incomplete request (including a body field the
+route does not know, which is refused rather than ignored), `404` for a missing
+document or version, `409` for a concurrency conflict or a trashed document,
+`422` for content that links to document ids that do not exist, and `503` when
+the embedder is unavailable. The reason is in the body's `detail` (and, on the
+ingest and edit routes, also in `error`, which they have always used). Until
+v1.15.2 a delete with a stale hash answered `500`, and `POST /ingest` answered
+`200` with `success: false` for a missing title or empty content; both are
+fixed.
+
+**Delete follows a read too.** A caller that identifies itself must send the
+hash on `DELETE /documents/{id}`, exactly as `cerefox_delete_document` requires
+it over MCP. A caller that sends no identity is the bundled web UI, which
+confirms with the human in a dialog instead, and it keeps working unchanged.
+
+The full contract of every endpoint (parameters, headers, bodies, error codes)
+is in [`docs/api/openapi.json`](../api/openapi.json), generated from the route
+handlers themselves. A running server serves its own copy at
+`GET /api/v1/openapi.json` (since v1.15.3), so a client always gets the
+contract of the version it is actually talking to. It does not need to know
+that path: every `/api/v1` response carries
+`Link: </api/v1/openapi.json>; rel="service-desc"`, the standard pointer to a
+machine-readable API description (RFC 8631).
+
+Purge (`DELETE /documents/{id}/purge`) is irreversible and takes no token. It is
+reachable by anything that can reach the port, which is another reason the
+warning at the top of this guide is not boilerplate.
+
+The response is `{ "success": true, "purged": <bool> }` (v1.14.0): `purged` is
+`false` when the document was no longer in the trash when the call landed (a
+restore raced it) and is still live; the RPC is a silent no-op in that case.
+
+**There is no bulk purge.** The web UI's "Empty trash" (v1.14.0) is a loop in
+the browser over this per-document endpoint, one call and one audit entry per
+document, with a confirmation and a Stop button in front of it. It purges only
+the documents listed when the count was confirmed; anything trashed afterwards
+stays in the trash. A single
+request that emptied the trash would be a footgun on a surface anything with
+the key can reach, so it was not added and should not be.
+
+---
+
+## Choosing between this and MCP
+
+Both surfaces run the same code underneath and write the same rows. The
+practical differences:
+
+| | `/api/v1` | MCP |
+|---|---|---|
+| Transport | Plain HTTP | stdio or Streamable HTTP |
+| Client needs | An HTTP client | An MCP client |
+| Identity | Optional, defaults to `web-ui` | Per-call `author` |
+| Section-level edits | None: `POST /documents/{id}/edit` replaces the whole content | `cerefox_insert`, `cerefox_edit` |
+| Guidance for agents | This guide | `cerefox_get_help()`, in-band |
+| Authentication | None on loopback; API key otherwise | None locally; token or OAuth remotely |
+
+If an agent is doing the calling, MCP is usually better: the tools carry their
+own documentation, and `cerefox_get_help()` keeps the conventions in front of
+the model. Reach for the API when the caller is a program you are writing
+yourself, or when you want one transport for a harness that already speaks
+HTTP.

package/docs/guides/linking.md

@@ -0,0 +1,118 @@
+# Document links: capabilities and guardrails
+
+Cerefox documents can link to each other with ordinary markdown links. This
+guide covers how linking works, and the deterministic guardrails (v1.7.0+)
+that protect links from the most common way they break: an AI agent
+corrupting a long document id while rewriting content.
+
+## How linking works
+
+Write a normal markdown link whose target is the document's UUID:
+
+```markdown
+See the [Opportunity Index](c937b70f-77af-43d3-b9bc-9f31e0d2041d) for details.
+```
+
+The Cerefox web UI resolves these at click time — the stored markdown is
+untouched, and the link keeps working if the target is renamed. Every search
+result and every write response includes the document id, so an id is always
+one lookup away.
+
+Four link forms are accepted; one is recommended:
+
+| Form | Example target | Use |
+|---|---|---|
+| **Document UUID** | `c937b70f-…` | **Always, for cross-references.** Stable, unambiguous, encoding-safe, validated (below). |
+| Repo-relative path | `docs/guides/quickstart.md` | Repo-ingested files only (their markdown naturally uses paths). |
+| Basename | `quickstart.md` | Best-effort fallback for the same. |
+| `[[Wikilink]]` | `[[Future Doc Name]]` | A deliberate **dangling** reference — "this document should exist someday." Never validated. |
+
+Agent-specific writing rules live in `AGENT_GUIDE.md` → "Writing linkable
+content".
+
+## Why links need a guardrail: LLMs and long ids
+
+This is worth understanding, because it explains the design and it is not a
+bug in any particular AI model — it is structural.
+
+A language model editing a document does not copy text the way a program
+does. It **regenerates** the text token by token from an internal
+representation. Normal prose survives this well because language is
+redundant — if a word drifts slightly, the surrounding context constrains it
+back. A UUID has **zero redundancy**: 32 hex characters, each independent,
+carrying no meaning that could catch a mistake. `508e4c21` regenerated as
+`502041d8` looks equally plausible to the model, and to anyone reading past
+it.
+
+Now compound that. A document with a table of 25–30 links makes an agent
+regenerate 25–30 UUIDs *every time it rewrites that table*. Even an
+excellent per-character accuracy, multiplied across hundreds of characters
+of pure entropy, several times per session, makes occasional corruption
+**expected, not unlucky** — and observed repeatedly in real use. Each
+corrupted id silently becomes a
+dead link that read-back review may or may not catch.
+
+Two defenses exist, and they compose:
+
+1. **Reduce how much gets regenerated**: the partial-edit tools
+   (`cerefox_insert`, `cerefox_edit`) change only the targeted section, so
+   untouched links are never retyped and literally cannot corrupt. Give
+   link-heavy tables their own heading so appends never rewrite existing
+   rows.
+2. **Catch what still gets retyped**: the write-time validation below.
+
+## The write-time guardrail (v1.7.0+)
+
+Every write — create, full update, or partial edit, on every surface (MCP,
+CLI, web, GPT Actions) — validates the `[Text](uuid)` links in the content
+against the store, inside the same database transaction as the write:
+
+- **A link to a document id that does not exist rejects the whole write**,
+  and the error lists every unresolvable id. Nothing is stored; the
+  corruption never lands. The check is deterministic and costs ~1–2ms.
+- **The agent can self-correct in the same turn**: the error says to re-read
+  the source each link was copied from, fix the id(s), and resend — and
+  explicitly not to retry unchanged.
+- **Examples escape via code formatting.** A link inside backticks or a
+  fenced code block is an example, not a link, and is not validated — which
+  is also just correct markdown, since a bare link-syntax example would
+  render as a real link. There is deliberately **no bypass flag**.
+- **A trashed target still resolves** (the id denotes a document; restoring
+  decides its fate). **`[[Wikilinks]]` are never validated** — that is the
+  sanctioned form for a forward reference.
+
+### Updates validate only what the write introduces
+
+On an update, only **newly-introduced** link ids are validated. A dead link
+the document *already carried* — typically because its target was purged
+after the link was written — does not block an unrelated edit or a file
+re-sync. Without this, one purge could make every document that ever linked
+the purged target permanently unwritable through automated paths.
+
+The corollary: a link that was mangled *before* v1.7.0, or whose target was
+purged later, sits undetected in the content. That is what the sweep is for.
+
+## The dead-link sweep (v1.7.1+)
+
+```bash
+cerefox document dead-links          # human-readable report
+cerefox document dead-links --json   # machine-readable
+```
+
+One server-side pass over the whole knowledge base, reporting every
+`[Text](uuid)` link whose target no longer exists — with the linking
+document and an occurrence count. Same scanning rules as the write guard
+(the two share one implementation, so they cannot disagree). Trashed
+*linker* documents are excluded until restored. Run it after a purge, or
+periodically; it is a full content scan, so it is deliberately on demand
+rather than part of `cerefox doctor`.
+
+Fix each hit by editing the linking document: correct the id, remove the
+link, or backtick it as an example.
+
+## Design record
+
+The full rationale — including the rejected bypass-flag design, why fence
+handling splits on lines instead of pairing with a regex, and the
+probability analysis of a mangled id colliding with a real document — is in
+[`docs/specs/link-integrity-design.md`](../specs/link-integrity-design.md).

package/docs/guides/securing-local-access.md

@@ -0,0 +1,253 @@
+# Securing local access (the API key)
+
+`cerefox web` and Cerefox Local serve an HTTP API on a port. This guide is
+about who is allowed to use it.
+
+**Most people need to do nothing.** Read the first section, confirm you are in
+the common case, and stop.
+
+---
+
+## The rule
+
+> **A request arriving on the loopback interface (`127.0.0.1`) is allowed
+> without a credential. A request arriving on any other interface must present
+> the server's API key.**
+
+Loopback means "a connection that started on this machine". Your browser, an
+agent running on your laptop, a script you typed into your own terminal: all
+loopback, all exempt, all work with no configuration.
+
+Introduced in **v1.12.0** ([#229](https://github.com/fstamatelopoulos/cerefox/issues/229)).
+
+## Do you need a key?
+
+**It depends on how Cerefox itself is running**, so start there.
+
+### If you run Cerefox Local (Docker)
+
+| Your publish address | Cerefox checks credentials? | What protects the port | You do |
+|---|---|---|---|
+| `127.0.0.1` (the default) | **No** | **Docker.** The port is bound to this machine's loopback only, so nothing outside it can open a connection at all. | Nothing |
+| Anything wider (`CEREFOX_LOCAL_BIND=0.0.0.0`) | **Yes, for every caller** | The key | Give the key to every client, including your own browser |
+
+**Read the middle column carefully.** On a default install Cerefox is *not*
+refusing remote callers — it never sees them. Docker declines the connection at
+the socket, before Cerefox is involved. "No key required" and "protected" are
+both true at the same time, for different reasons, and it is worth knowing
+which is doing the work: widen the publish address and the first protection
+disappears instantly, which is why the key turns on in the same move.
+
+There is no middle setting here, and that is deliberate rather than a
+limitation we forgot to lift. **Docker rewrites the source address of every
+request that comes through a published port**, so a server inside a container
+cannot tell a request from your own machine apart from one that crossed the
+network — both arrive from the same bridge address. Since the distinction
+cannot be made, the gate does not pretend to make it: it is either off, with
+the publish address as the boundary, or on for everybody.
+
+`cerefox-local` sets this for you from `CEREFOX_LOCAL_BIND`. To force the gate
+on while still publishing to loopback:
+
+```bash
+echo 'CEREFOX_API_REQUIRE_KEY=1' >> ~/.cerefox/local/.env
+cerefox-local restart
+```
+
+> **v1.12.0 got this wrong** and injected a key into every container without
+> require-mode, so the loopback exemption never matched and every caller — the
+> web UI included — got a `401`. Fixed in **v1.12.1**. If you are on v1.12.0
+> and seeing 401s from a container, upgrade.
+
+### If you run `cerefox web` directly (npm install)
+
+Here the server sees real client addresses, so the loopback rule applies as
+written.
+
+| Your situation | Need a key? |
+|---|---|
+| You use the web UI in your browser | **No** |
+| An agent or script runs on the same machine | **No** |
+| A container reaches your host server via `host.docker.internal` | **No** — it arrives on the host's loopback |
+| You bind `--host 0.0.0.0` to reach Cerefox from another machine | **Yes** |
+| A reverse proxy sits in front on the same machine | **Yes**, plus `CEREFOX_API_REQUIRE_KEY=1` (see below) |
+
+If every row that applies to you says No, you are done.
+
+**Not sure?** Ask for the version endpoint the way your client will. `200`
+means you are on the exempt path; `401` means you need a key.
+
+```bash
+docker exec <your-client-container> \
+  curl -s -o /dev/null -w '%{http_code}\n' http://host.docker.internal:8010/api/v1/version
+```
+
+## Why it works this way
+
+The attacker worth defending against can reach the port but **cannot read your
+filesystem**: a machine on the café wifi after you widened the bind, a
+container on a shared Docker network, a malicious page open in your browser.
+
+Someone who *can* read your filesystem already has the key file, your `.env`,
+and your database credentials. Demanding a key from them would protect nothing
+while making the common case worse for everyone. On a single-user machine,
+loopback access and key-file access are the same trust boundary, so the gate is
+drawn at the place where the trust actually changes: the network.
+
+This is also why **the browser never holds a key**. The web UI is a static
+file, so a key embedded in the page could be read by anything that can load the
+page — precisely the attacker the key exists to stop. A key in an
+unauthenticated page is not a secret. The UI works because it is local, not
+because it holds a credential.
+
+## Getting a key
+
+### `cerefox web` (npm install)
+
+No key exists until you ask for one. Until then the gate is off and the server
+behaves exactly as it did before v1.12.0, which is what makes upgrading safe.
+
+```bash
+cerefox api-key generate   # mint one, write it to your .env, print it once
+cerefox api-key show       # print it again, in full
+cerefox api-key rotate     # replace it
+```
+
+`generate` refuses if a key already exists. Silently replacing one would give
+every client you had already configured a `401` with no explanation.
+
+### Cerefox Local (Docker)
+
+The container mints a key **automatically at first boot** and persists it on
+the data volume, so it survives `cerefox-local upgrade`. You never create it;
+you only read it.
+
+```bash
+cerefox-local api-key            # print it (and say whether it is enforced)
+cerefox-local api-key --rotate   # mint a new one and restart
+```
+
+The key exists whether or not the gate is on, so turning the gate on later
+never changes the value your clients were given. `cerefox-local api-key` tells
+you which state you are in — printing a key while implying it is being enforced
+when it is not would be worse than printing nothing.
+
+## Using it
+
+A remote caller sends it as a bearer token:
+
+```bash
+curl http://<host>:8010/api/v1/documents/<uuid> \
+  -H 'Authorization: Bearer cfx_lak_…' \
+  -H 'X-Cerefox-Requestor: my-bot'
+```
+
+Without a valid key the server answers `401` with a `WWW-Authenticate: Bearer`
+challenge and a `detail` field explaining what to do.
+
+The key authenticates; it does not identify. `X-Cerefox-Requestor` and
+`X-Cerefox-Author` are still declared labels for attribution, exactly as
+described in [`api.md`](api.md#attribution-is-not-authentication). Holding the
+key does not make the name you send true.
+
+## Recipe: a harness in its own container
+
+The case where a key is genuinely needed, and the one worth automating.
+
+**The ordering that avoids a chicken-and-egg problem.** You could boot Cerefox,
+read its key, then configure the client — but that is two steps and a manual
+copy every time either side is rebuilt. Instead, mint one key on the host and
+give the same value to both containers. Cerefox prefers an injected key over
+the one it would generate, so this pins it across recreates.
+
+```bash
+# 1. Mint once, on the host.
+KEY="cfx_lak_$(openssl rand -base64 32 | tr -d '=+/' | cut -c1-43)"
+
+# 2. Give it to Cerefox Local. Both variables are on the passthrough allowlist,
+#    so they survive `cerefox-local upgrade` and any recreate. REQUIRE_KEY is
+#    what turns the gate on: inside a container there is no loopback exemption
+#    to fall back on, so the gate is all-or-nothing.
+{ echo "CEREFOX_API_KEY=$KEY"; echo "CEREFOX_API_REQUIRE_KEY=1"; } >> ~/.cerefox/local/.env
+cerefox-local restart
+
+# Note: with the gate on, YOUR BROWSER needs the key too. If you use the web UI
+# daily, prefer leaving Cerefox published on loopback with the gate off and
+# giving your harness host networking instead.
+
+# 3. Give the same value to your client container, however it takes config.
+docker run -e CEREFOX_API_KEY="$KEY" … your-harness
+```
+
+**Rotating** is the same two writes plus two restarts, in this order: update
+Cerefox first, then the client. Between them the client gets `401`s, so keep
+the window short, or accept both keys briefly by setting a comma-separated list
+(`CEREFOX_API_KEY=new,old`), migrating the client, then dropping the old value.
+
+## Recipe: a reverse proxy on the same machine
+
+**This is the case the loopback rule cannot handle on its own, so read it if it
+applies to you.**
+
+A proxy on the same host terminates the client's connection and opens its own
+to Cerefox, from `127.0.0.1`. So *every* proxied request looks local and is
+exempt, including requests that came from the internet.
+
+Cerefox deliberately does **not** read `X-Forwarded-For` to recover the
+original address. That header is set by the caller, so trusting it would let
+anyone claim to be local — strictly worse than having no gate at all.
+
+The answer is to stop exempting loopback:
+
+```bash
+CEREFOX_API_REQUIRE_KEY=1
+```
+
+Now every caller presents the key, proxy included. Your browser will need it
+too, so this mode suits headless deployments rather than daily UI use.
+
+## What this does not protect
+
+**Other programs on your own machine.** Any local process can reach a loopback
+port. This is a network boundary, not process isolation.
+
+**Traffic on the wire.** There is no TLS. The key authenticates; it does not
+encrypt. Anyone who can observe the connection can read the key and everything
+else.
+
+**Fine-grained access.** One key, all-or-nothing. No per-client scoping, no
+read-only keys, no expiry, no revocation beyond rotating the single value.
+
+**Being on the internet.** A key makes a widened bind survivable. It does not
+turn this into an internet-facing API: there is no rate limiting, no TLS, no
+audit of failed attempts. If you need Cerefox reachable over a network you do
+not control, use the Edge Functions — that is the surface built for it, and it
+authenticates every request against a rotatable token. See
+[`access-paths.md`](access-paths.md).
+
+## Troubleshooting
+
+**Everything returns 401 after upgrading.** You have `CEREFOX_API_REQUIRE_KEY=1`
+set, which removes the loopback exemption. Unset it unless you are running a
+reverse proxy.
+
+**My container gets 401 but curl on the host works.** With `cerefox web` on the
+host, that is the gate behaving correctly: your container reaches Cerefox over
+a Docker network, not loopback. Give it the key (see the recipe above).
+
+**Everything gets 401 from a Cerefox Local container, including the web UI.**
+That is the v1.12.0 bug, not a configuration problem. Run
+`cerefox-local upgrade` to get v1.12.1 or newer.
+
+**`cerefox-local api-key` says no key was found.** The image predates v1.12.0.
+Run `cerefox-local upgrade`.
+
+**I rotated and now everything is broken.** Rotation invalidates the old key at
+the next restart. Update every remote client. Local callers are unaffected,
+which is a useful way to confirm the server itself is healthy: if
+`curl http://127.0.0.1:<port>/api/v1/version` works from the host, the server
+is fine and the problem is client configuration.
+
+**I lost the key.** You cannot recover it from the server, but you can read it
+from where it is stored: `cerefox api-key show`, or `cerefox-local api-key`.
+Failing that, rotate and reconfigure your clients.