docs(release): align the docs with marfa v0.0.17

[aicayzer]

Summary

Aligns the docs with marfa v0.0.17: the release sync, a v0.0.17 changelog entry, and the guide changes the release's pull requests call for.

Changes

• Sync. scripts/sync-from-marfa.sh with MARFA_ROOT set to a detached worktree of marfa at the v0.0.17 tag (commit 1c1df5f18). The script accepts a tag checkout: it reads committed files and takes the release from git describe --tags, which names v0.0.17 there. Generated files are as the sync wrote them: release data, CLI download, server image snippet, settings (MARFA_UPLOAD_IDLE_TIMEOUT_MS), error codes (request_timeout and blob_store_unavailable wording), the contract index and openapi.json.
• Changelog. A v0.0.17 entry in the shape of v0.0.16, dated October 20, 2026 (the tag's date): eight entries for running an instance and one for apps and devices.
• Back up and restore. The three passages and the code block for marfa export --output with missing blobs now say the archive is kept as <path>.incomplete and the path is not touched. A restore takes items and edges of force-deleted types as the archive holds them, refuses an archive without its four files (details.entries), has no time limit while bytes arrive and ends 408 request_timeout after the idle limit, and judges the owner's recent sign-in when it starts. An export ends with an error when its credential ends or narrows. A copy of the volume older than the bucket needs a prefix of its own, linked to the deployment guide.
• Deploy. The health check names a missing blob folder or marker as blob storage down.
• Housekeeping. The bin purge runs again at once while a backlog remains.
• Handle files. No size cap and no total time limit on an upload, the idle limit, and 503 blob_store_unavailable on a download when no store answers.
• Troubleshooting. The lockout entry says the page names the wait and that a passkey signs in; a new 408 request_timeout entry.
• Quickstart. Claiming in the browser signs the owner in and goes on through setup.

Testing

• pnpm test: 28 files, 354 tests passed. pnpm build, pnpm build:status and pnpm types:check passed. All through Tools/heavy-run/heavy-run.
• Checked in dist/: the changelog shows v0.0.17, and every anchor the new links name exists (#what-an-export-checks, #restore-an-archive, #when-an-archive-lacks-a-files-bytes, #empty-the-bin, #keep-it-running, #claim-the-instance, #every-environment-setting).
• CI not awaited.

Checked against

Every changelog and guide claim was read against the contract at the tag (git diff v0.0.16 v0.0.17 -- conformance/spec/), openapi.json, and the code at the tag:

• Blob folder gone (stores/integrity-unreachable-*, stores/unreachable-read, instance/health-blob-down): contract. The restore 503 blob_store_unavailable (was 500), replication not ending its run, and the extraction sweep giving the attempt back are in the code only (restore-archive.ts, blob-replicate.ts, sweeper.ts), not the contract.
• Bin purge (housekeeping/retention-trash-keeps-up): contract. The batch size is not stated in the docs.
• Restore and export of force-deleted types (search-and-filters/restore-rows-*, restore-edges-*, archive-rows-shape-free, archive-edges-*): contract. That the old refusal was 409 export_rows_unrestorable comes from the v0.0.16 contract and changelog.
• Missing archive members (search-and-filters/restore-members): contract, and details.entries in openapi.json.
• Upload idle limit (blobs/upload-*, search-and-filters/restore-*): contract; name, default 60000 and range in config.ts, settings.md and openapi.json.
• Export and credential (search-and-filters/export-credential-*, archive-selection-key): contract; controller.error in routes/export.ts for the early end.
• marfa export --output (search-and-filters/cli-export-*): contract and core/marfa-cli/src/commands/export.rs at the tag: the file name <path>.incomplete, the hidden .<name>.partial-<pid> file when that name can't be written, the exit 1 with blobs_missing.
• Claim and sign-in pages (instance-claim/claim-*, keys-and-oauth/sign-in-form-limit-wait, sign-in-lockout-page, device-lookup-*): contract. The six steps (SETUP_STEP_COUNT and its comment in pages/setup-words.ts, routes/setup-pages.tsx) and the Forgot password page (routes/auth-pages.ts, forgot-password-page.tsx) are in the code only.

Pages read

• Rewritten or extended: the changelog, back-up-and-restore, deploy, housekeeping, handle-files, troubleshooting, quickstart (above).
• No change needed: (overview)/files.mdx, (reference)/api-reference/index.mdx, (reference)/typescript-sdk.mdx (they cite uploads and the export operation, and say nothing the release changes); (overview)/access.mdx, guides/authenticate.mdx, guides/manage-keys.mdx, guides/connect-a-web-page.mdx (sign-in and claim: the password chosen at claim and the passkey sign-in are still true); (overview)/items-and-types.mdx, (overview)/properties-metadata-and-edges.mdx, guides/define-a-type.mdx, guides/list-filter-search.mdx (forced delete and edges: nothing contradicts the new rules); guides/upgrade.mdx (it points to the back-up page); guides/settings.mdx (the settings table is generated and includes the new setting).

Notes for reviewers

• #2191 (restoring an older volume while the bucket is live) is in v0.0.16, not v0.0.17: it is an ancestor of the v0.0.16 tag. The public guide had no mention of the topic, so the back-up page now links the deployment guide's section. This is a gap fix, not a release change, and it is left out of the changelog.
• Not in the changelog: #2205 (test only). #2198 is not in the tag.
• Left out because the contract does not state them and the code is the only source: the Referrer-Policy change on /setup, the revoked-grant purge's backlog behavior, and the /setup/name form-only rule.
• manage-keys.mdx still gives only the address limit (ten attempts in 15 minutes) for a password lock. The contract also has an account limit across addresses (a hundred in an hour, keys-and-oauth/sign-in-account-limit), which predates this release, so it is not changed here.

Checklist

• Checked against marfa at v0.0.17
• No em dashes, American English
• Generated files changed only by the sync
• Review

[aicayzer]

Review: ready to merge

Summary. The pass documents what v0.0.17 changed, and every claim in the changelog and the edited guides was checked against the contract and code at the tag.

First draft: 3/5. The fact-check found nine claims that were wrong, overclaimed or unsupported, all fixed in c5a24c6.

Checked.

• True: each name, status and exit code, setting and default, file name and step count against conformance/spec/, the code and openapi.json at the tag.
• Done: the generated files match what scripts/sync-from-marfa.sh writes against the tag, so none was hand edited.
• Nothing left behind: nothing from after the tag and nothing from before v0.0.16 is claimed as new; links and anchors resolve.

Found.

• Restore and an unreachable disk. The 503 applies when the folder exists but its marker is missing or names another store, not when the folder is gone, and the claimed earlier 500 was unsupported. Fixed in c5a24c6. True
• A drive that did not mount. At start the server recreates the folder, so health is down only for a folder that disappears while running. Fixed in c5a24c6. True
• Overclaims. Edges "as the archive holds it", a 401 for NDJSON exports, "the file doesn't unpack" for both formats, the 503 condition on a blob read, the purge re-run condition and a 409 example that a restore now takes. Fixed in c5a24c6. True

For an issue.

• A blob folder missing at server start. The server replaces it with an empty store and reports it healthy; filed in withmarfa/marfa.

---

Reviewed by withmarfa-reviewer on Opus. This review may contain mistakes.