[aicayzer]

Summary

Brings the docs in line with Marfa v0.0.14: the published server image, the per-instance backup prefix, the CLI exit codes, webhooks to private addresses, telemetry attributes, backups that name missing blobs, folder push exits and the file-write refusal. The release sync is the first commit, so the generated release data, the CLI download and the settings and error tables name v0.0.14.

Changes

• Sync: chore(sync) runs scripts/sync-from-marfa.sh against the v0.0.14 tag (generated files only). feat(sync) adds src/generated/server-image.md, written from the release like cli-download.md, with its test in sync-from-marfa.test.sh and docs-structure.test.ts.
• Deploy and upgrade: the container route pulls ghcr.io/withmarfa/marfa-server by release tag (from the generated snippet) and publishes the port on loopback, with the reason. TRUSTED_PROXY_CIDRS for a proxy on the same machine, and why (sign-in limits count each address). The bare-metal start is node --import ./dist/instrumentation.js dist/index.js. Upgrade names the old build by its image tag, gives the new build its own volume, port and S3_PREFIX, and checks release.
• Prefix: <S3_PREFIX>/db in deploy, back up and restore (with the S3_PREFIX= form of litestream restore) and upgrade.
• Backups: missing_blobs, blobs_missing, the exit codes 1 and 3, the null type and size, and 503 blob_store_unavailable.
• CLI: keys keep accepts any valid key, events exit codes, owner passkeys add, and release in marfa whoami and status.
• Webhooks: private addresses and names refused at registration and update, dead_letter at once, and unstored Tailscale- headers.
• Telemetry: service.instance.id, OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME precedence, for the server and the CLI.
• Folders and files: folders push exits, the rate limit, the waiting count, folders restore listing, the UTF-16 move, 404 blob_not_found on a file write and its Idempotency-Key behavior.
• Changelog: a v0.0.14 entry.

Testing

• pnpm test (354 tests, including the content lint), pnpm build, pnpm build:status and pnpm types:check pass, and .github/scripts/sync-from-marfa.test.sh passes (597).
• Read each changed page in the built site and checked that every changed anchor link resolves.
• Checked each claim against marfa at v0.0.14 (the contract, openapi.json, deploy/README.md, the server and CLI source).
• Not run: the image itself (it is not public yet), a real Tailscale proxy, and the CLI binary against a failing blob store.

Notes for reviewers

• The release is still a draft and the image package is not public. The docs build reads release data from the local marfa tag, not GitHub, so nothing is hard-coded. The docker pull and the CLI download URL fail, and the changelog link to the v0.0.14 release is a 404, until the release is published and the package is made public. Merge after that.
• Brief items that did not match the pages: the Quickstart has no container route (it runs from a clone), and the deploy page does not describe Tailscale Serve, so the proxy advice sits in "The address". There is no scan report reference page: the waiting count is explained in "Know whether a push finished" in the sync guide.
• TRUSTED_PROXY_CIDRS for the container network is derived from client-ip.ts (the server trusts X-Forwarded-For only from a trusted peer) and Docker's publishing behavior. It was not run with a real proxy.
• The changelog release date is the tag's date, October 19, 2026.
• src/generated/server-image.md is written by the sync script, never by hand.

Checklist

• The title is a scoped Conventional Commit.
• Pages follow STYLE.md, with American English and no em dashes.
• Generated files are changed only by the sync script.
• The build, type check and tests pass locally.
• Checked on the live site, which needs the release published first.

[aicayzer]

Review: ready to merge

Summary. Brings the docs in line with v0.0.14: the published server image, each instance's replica under its own prefix, the new exit codes, private webhook addresses, telemetry that names the instance, missing blobs in archives, the folder push and file-write proof. Safe to merge once the v0.0.14 release and image are public.

First draft: 4/5. One untrue sentence found and fixed.

Checked.

• True: every changed claim against the marfa code at tag v0.0.14: exit codes, setting names and defaults, the image name and run command, the <S3_PREFIX>/db replica path and litestream restore commands, TRUSTED_PROXY_CIDRS, the telemetry start, webhook refusals and the changelog entry.
• Generated data: the sync from the tag produces no diff in src/generated/ or openapi.json.

Found.

• folders restore was said to print a flag for a file it could not write. The text output prints the path and reason; the flag appears only with --json. Fixed in 10b7a89.

Quick fixes. 1 applied by the reviewer.

---

Reviewed by withmarfa-reviewer on claude-sonnet-5-5. This review may contain mistakes.