@cerefox/memory 1.15.1 → 1.15.3

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.

package/docs/guides/staging-env.md

@@ -0,0 +1,334 @@
+# Running a staging environment alongside production
+
+Cerefox can talk to more than one backend from a single machine. This guide sets
+up a **staging** environment — a second Supabase project you can deploy
+pre-release builds to, import production data into, and break freely — while
+production stays untouched.
+
+> **Nothing here affects a normal single-environment install.** Every mechanism
+> below is opt-in and inert unless you set `CEREFOX_CONFIG_DIR`. If you never
+> want staging, you can stop reading; `cerefox …` behaves exactly as documented
+> in [`setup-supabase.md`](setup-supabase.md).
+
+**Status**: validated end to end — config, database, backups, CLI version, and
+the web server all separate cleanly. One gap remains (agent/MCP wiring); see
+[Known limits](#known-limits).
+
+This is a **convention, not a feature**. There is no `--env` flag and no profile
+system to learn: two environment variables and a shell alias do the whole job,
+which is why none of it can destabilise a normal single-environment install.
+
+---
+
+## Why bother
+
+Three things, and the third turned out to matter most:
+
+- **Upgrades.** A release that changes the schema will run its migrations
+  against your real data exactly once. Staging lets you rehearse that on a copy.
+- **Destructive or expensive operations.** `server migrate-format` re-embeds
+  every legacy document (real spend, rewrites chunks). Proving it on a copy
+  first turns an act of faith into a measurement.
+- **Development.** A store you are willing to break is the cheapest way to turn
+  a claim about runtime behaviour into a measurement. During the 1.1.0 cycle this
+  found a retry loop executing 68,825 times per request, a `migrate-format` that
+  reported success while converting nothing, and a `backup create` that failed
+  against older servers — none visible from the code or the test suite. Keep it
+  available during development stretches, not only around releases.
+
+---
+
+## 1. Create the staging Supabase project
+
+Follow [`setup-supabase.md` Step 1](setup-supabase.md), with two differences:
+
+- Name it distinctly (`cerefox-staging`) — the dashboard project switcher is
+  your first defense against acting on the wrong database.
+- Pick the **same region as production** if you care about comparable timings.
+  A different region is fine functionally; just never compare *speed* across
+  the two.
+
+The creation-time security options are the same as production, and the
+"automatically expose new tables" setting is worth disabling on both — Cerefox
+grants its tables to `service_role` explicitly.
+
+---
+
+## 2. Give staging its own config directory
+
+`CEREFOX_CONFIG_DIR` overrides where Cerefox reads `.env`. Production lives at
+`~/.cerefox/.env` and is never consulted when the override is set.
+
+```bash
+mkdir -p ~/.cerefox/staging && chmod 700 ~/.cerefox/staging
+```
+
+Then either run the interactive setup against it:
+
+```bash
+CEREFOX_CONFIG_DIR=~/.cerefox/staging cerefox init
+```
+
+…or write `~/.cerefox/staging/.env` (mode 0600) directly:
+
+```bash
+CEREFOX_ENV_LABEL=staging
+CEREFOX_SUPABASE_URL=https://<staging-ref>.supabase.co
+CEREFOX_SUPABASE_KEY=sb_secret_…                 # staging project's secret key
+CEREFOX_DATABASE_URL=postgresql://postgres.<staging-ref>:…@aws-0-<region>.pooler.supabase.com:5432/postgres?sslmode=require
+
+# Isolate snapshots. CEREFOX_BACKUP_DIR does NOT follow the config dir, so
+# without this line staging backups land beside production's.
+# Use an ABSOLUTE path: a relative value resolves against the working
+# directory, so snapshots scatter wherever you happen to run the command.
+CEREFOX_BACKUP_DIR=~/.cerefox/staging/backups
+
+OPENAI_API_KEY=sk-…
+SUPABASE_ACCESS_TOKEN=sbp_…                       # account-level; same as prod
+```
+
+> **Snapshot isolation needs v1.1.0-beta.3 or later.** On **beta.2 and
+> earlier**, `backup create` read `CEREFOX_BACKUP_DIR` *before* loading the
+> `.env` file, so the setting above was silently ignored and staging snapshots
+> landed in production's directory. Until staging is on a build with the fix,
+> pass the destination explicitly: `cfx-stg backup create --output-dir
+> ~/.cerefox/staging/backups`.
+
+**Mirror production's tuning.** Chunking and embedder settings still live in
+`.env` (`CEREFOX_MAX_CHUNK_CHARS`, `CEREFOX_MIN_CHUNK_CHARS`, `CEREFOX_EMBEDDER`);
+retrieval and retention moved into the database in v1.1.0, so mirror those with
+`cerefox config set` against staging (or the Settings page).
+A staging result only means something if the knobs match; different chunk sizes
+make every comparison noise. **Do not** copy credentials — staging has its own.
+
+---
+
+## 3. Pin a Cerefox version for staging
+
+`CEREFOX_CONFIG_DIR` switches the *database*, not the *code*. The `cerefox` on
+your PATH is a single global npm install, so on its own it would point both
+environments at the same version — which defeats the main purpose of staging:
+rehearsing a **pre-release** build before production ever sees it.
+
+Give staging its own install tree. npm's `--prefix` keeps it entirely separate
+from the global one, so production's binary is never touched:
+
+```bash
+# Rehearsing a pre-release (the usual case):
+npm install -g --prefix ~/.cerefox/staging/cli @cerefox/memory@beta
+
+# Rehearsing a NORMAL release, where no beta was cut: pin the version
+# explicitly. A bare `@cerefox/memory` resolves `latest` at install time, so
+# staging silently records nothing about what it is running — and running it
+# before the publish completes would install the PREVIOUS version, which is the
+# one thing staging exists to avoid.
+npm install -g --prefix ~/.cerefox/staging/cli @cerefox/memory@1.4.0
+```
+
+Then bind **both axes — version and environment — in a single alias**, so they
+can never drift apart:
+
+```bash
+alias cfx-stg='CEREFOX_CONFIG_DIR=~/.cerefox/staging ~/.cerefox/staging/cli/bin/cerefox'
+```
+
+Put it in `~/.zshrc` (or `~/.bashrc`) and reload. From here on, `cerefox` means
+production-version-on-production-data and `cfx-stg` means
+staging-version-on-staging-data. There is no combination of the two that a typo
+can produce.
+
+> **The alias is the protection — scripts and agents that bypass it lose it.**
+> `CEREFOX_CONFIG_DIR=~/.cerefox/staging cerefox …` (bare binary, staging
+> config) recombines the axes: production *code* on staging *data*. Aliases
+> don't exist in non-interactive shells, which is exactly where automation
+> runs, so spell out the pinned binary path there. And remember the global
+> binary is itself a production component: `cerefox self-update` replaces it
+> no matter which `CEREFOX_CONFIG_DIR` is set — updating "for staging" that
+> way is a production change.
+
+Verify the split before trusting it:
+
+```bash
+cerefox --version    # production, e.g. 1.0.8
+cfx-stg --version    # staging, e.g. 1.1.0-beta.2
+```
+
+To move staging to a newer pre-release later, re-run the `npm install` above;
+production is unaffected. If you'd rather not keep an install tree at all,
+`npx --package=@cerefox/memory@beta cerefox …` works too, but it re-resolves the
+package on every call and makes the version harder to pin down when something
+misbehaves.
+
+---
+
+## 4. Deploy and verify
+
+```bash
+cfx-stg server deploy      # fresh database → schema + RPCs + 9 Edge Functions
+cfx-stg doctor
+```
+
+`doctor` should report the staging config path and URL. Two lines are expected
+on a fresh project:
+
+- `ℹ edge functions … No CEREFOX_ACCESS_TOKEN set` — staging has no Cerefox
+  access token yet. Run `cfx-stg token generate` if you plan to test the Edge
+  Function / remote-MCP path there.
+- `✓ content format  no documents yet` — nothing imported.
+
+**Checking database/schema state.** There is no `cerefox db status` command.
+Use one of:
+
+| Want | Command |
+|---|---|
+| Deployed schema version, reachability, drift banner | `cfx-stg doctor` |
+| What a deploy *would* do, without doing it | `cfx-stg server deploy --dry-run` |
+| Per-migration applied/pending list | `bun scripts/db_migrate.ts --status` (repo clone; contributor-only) |
+
+`doctor` is the one to reach for; the migration list is only interesting when a
+deploy behaved unexpectedly.
+
+> **Contributor scripts and a repo `.env`.** The `bun scripts/*.ts` tools honour
+> `CEREFOX_CONFIG_DIR` — but only from the version that fixed this. Bun
+> auto-loads `.env` from the working directory, so on **v1.1.0-beta.1 and
+> earlier** a repo clone with its own `.env` silently outranked the config dir:
+> `CEREFOX_CONFIG_DIR=…/staging bun scripts/db_migrate.ts --status` reported
+> *production*. If you're on an older build, run those scripts from a directory
+> with no `.env`, and confirm the target before trusting the output.
+
+---
+
+## 5. Populate from a production snapshot
+
+```bash
+cerefox backup create                       # production
+cfx-stg backup restore ~/.cerefox/backups/<snapshot>.json
+```
+
+Backups carry documents, chunks, projects, memberships and (from v1.1.0)
+relations and lifecycle status. Restore is idempotent — re-running it is safe
+and converges on the same state rather than duplicating anything.
+
+Restoring an **older** snapshot into a **newer** schema works — new columns take
+their defaults. The reverse is not supported.
+
+Two count details that look like bugs and are not:
+
+- **Trashed documents are not carried over.** `backup create` captures live
+  documents only (`deleted_at IS NULL`), so anything in production's trash is
+  absent from staging. Nothing in the trash is lost *in production* — it just
+  isn't part of the snapshot.
+- **A membership shortfall on pre-v1.1.0 snapshots.** Older `backup create`
+  captured the document↔project junction unfiltered, including rows belonging
+  to trashed documents. Restore drops those (their document isn't in the file),
+  so the summary reports fewer memberships than the header claims — 362 of 369
+  on the maintainer's store. From v1.1.0 the capture filters them out, and the
+  two numbers agree.
+
+---
+
+## 6. Run both web servers at once
+
+The daemon's pidfile and log follow `CEREFOX_CONFIG_DIR`, so staging writes to
+`~/.cerefox/staging/web.{pid,log}` and production to `~/.cerefox/web.{pid,log}`.
+Each `web stop` / `web status` acts only on its own environment.
+
+> **Requires v1.1.0-beta.2 or later.** On **beta.1 and earlier** both
+> environments shared `~/.cerefox/web.pid`, so `cfx-stg web start` refuses with
+> *"A Cerefox web daemon is already running on :8000"* — it is reading
+> production's pidfile. Until staging is on a build with the fix, start it in
+> the **foreground** instead, which never touches the pidfile:
+>
+> ```bash
+> cfx-stg web --port 8030      # no `start` subcommand; Ctrl-C to stop
+> ```
+
+Pick a different port for staging so the two can run simultaneously:
+
+```bash
+cfx-stg web start --port 8010
+cfx-stg web status      # staging only
+cerefox web status      # production only — unaffected
+```
+
+Set `CEREFOX_ENV_LABEL=staging` in the staging `.env` (Step 2) and the
+environment names itself everywhere it matters — two tabs that look identical
+otherwise:
+
+| Surface | With the label set |
+|---|---|
+| Web UI | A banner on every page: *"STAGING environment — not production."* |
+| `doctor` | Title line reads `Cerefox doctor [STAGING]` |
+| `backup create` | Filename becomes `cerefox-staging-<stamp>.json`, and the label is stored in the payload |
+| `backup restore` | Warns when the snapshot's environment differs from the target's |
+
+The filename and restore warning matter because `CEREFOX_BACKUP_DIR` does not
+follow `CEREFOX_CONFIG_DIR`: staging and production snapshots can end up in one
+directory, and a restore that picks "the most recent file" there would
+otherwise seed production from staging without saying so.
+
+**Requires v1.1.0-beta.3 or later** — on earlier builds `CEREFOX_ENV_LABEL` is
+read but nothing acts on it.
+
+---
+
+## Known limits
+
+| Area | Problem |
+|---|---|
+| **Agent (MCP) config** | Safe since v1.4.0 ([#168](https://github.com/fstamatelopoulos/cerefox/issues/168)). `configure-agent` names the server after `CEREFOX_ENV_LABEL`, so a staging environment registers as **`cerefox-staging`** alongside your production `cerefox` entry rather than replacing it, and an agent can hold both. The labelled entry also carries its own `CEREFOX_CONFIG_DIR` and `CEREFOX_ENV_LABEL` in the config it writes — without that the client would spawn the server with *its own* environment (a GUI client launched from the dock has none), `CEREFOX_CONFIG_DIR` would be absent, and an entry named `cerefox-staging` would quietly serve production. Before v1.4.0 it registered every environment as `cerefox` and running it from staging silently repointed all your agents. |
+| **`doctor`'s `mcp clients` line** | It inspects your global agent configs, which point at production, and reports them even in staging mode. Informative, but easy to misread as "staging is wired to my agents". |
+| **`doctor` remediation commands** | Environment-aware since v1.8.0: in a staging environment the remediations tell you to prefix `CEREFOX_CONFIG_DIR` (or use the alias). Before that, a staging `doctor` printed bare `cerefox …` remediations that act on production. |
+
+Everything else — config, database, backups, CLI version, web daemon — is
+separated and validated.
+
+### What is *not* isolated, by design
+
+Two things are shared on purpose, and both are safe:
+
+- **`SUPABASE_ACCESS_TOKEN`** is an account-level credential, not a
+  project-level one. The same value belongs in both `.env` files; the project
+  it acts on comes from the URL and database URL beside it.
+- **Your OpenAI key.** Staging embeds against the same account, so staging
+  ingestion and `migrate-format` rehearsals cost real money. That is the point —
+  it is how you measure the spend before committing production to it.
+
+---
+
+## Housekeeping
+
+Pause the staging project in the Supabase dashboard between test rounds — a
+paused project keeps its data without consuming free-tier compute. Check your
+plan's limit on simultaneously active projects before creating the second one.
+
+## Pause it when you are not using it
+
+A Supabase project on the free tier costs nothing while paused, and leaving a
+staging environment running between bursts of work is pure waste. Pause it from
+the Supabase dashboard when you finish, and unpause it when you start.
+
+Two things follow from that:
+
+- **Give it a minute after unpausing.** The first queries against a
+  just-resumed project are slow while the instance wakes.
+- **A paused project does not announce itself.** Commands hang or fail with
+  connection and timeout errors, and `cerefox doctor` reports the Data API as
+  unreachable. That looks identical to a broken deployment or a bad credential.
+  Check whether the project is paused before diagnosing anything else.
+
+## Running the test suites against staging
+
+The package suite's live tests write real documents. They resolve credentials
+exactly as the CLI does, so a bare `bun test` on a maintainer's machine targets
+**production** — which is how a run once left ~79 audit-log entries there. Since
+v1.4.0 those suites **skip unless the target carries `CEREFOX_ENV_LABEL`**, so
+point them at staging explicitly:
+
+```bash
+CEREFOX_CONFIG_DIR=~/.cerefox/staging bun test
+```
+
+`CEREFOX_ALLOW_PROD_WRITE_TESTS=1` overrides the guard, for the rare case where
+production really is the intended target. Pointing every *command* at staging is
+not enough: the test runner is a separate process with its own resolution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.15.1",
+  "version": "1.15.3",
   "description": "Cerefox \u2014 user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",
@@ -40,27 +40,27 @@
   ],
   "dependencies": {
     "@hono/node-server": "^2.1.1",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "@supabase/supabase-js": "^2.45.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@supabase/supabase-js": "^2.117.2",
     "cli-progress": "^3.12.0",
     "commander": "^15.0.0",
-    "hono": "^4.13.7",
-    "mammoth": "^1.9.0",
+    "hono": "^4.13.9",
+    "mammoth": "^1.13.0",
     "ora": "^9.4.0",
     "picocolors": "^1.0.0",
     "postgres": "^3.4.9",
     "prompts": "^2.4.2",
-    "smol-toml": "^1.6.1",
+    "smol-toml": "^1.9.0",
     "zod": "^4.6.5"
   },
   "optionalDependencies": {
-    "@huggingface/transformers": "^4.2.0",
+    "@huggingface/transformers": "^4.3.0",
     "onnxruntime-node": "^1.21.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.2",
     "@types/cli-progress": "^3.11.5",
-    "@types/node": "^24.13.3",
+    "@types/node": "^24.19.0",
     "@types/prompts": "^2.4.9",
     "typescript": "^6.0.3"
   },