[aicayzer]

Summary

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

Changes

• Sync. scripts/sync-from-marfa.sh against a clean checkout of the v0.0.16 tag: release data, CLI download, server image snippet, settings (MARFA_DISK_RESERVE_BYTES now covers archive exports, and MARFA_ENRICHMENT_MAX_TEXT_CHARS counts UTF-16 code units), error codes (export_rows_unrestorable, export_unrestorable), the contract index and openapi.json.
• Changelog. A v0.0.16 entry in the shape of v0.0.15, dated October 19, 2026 (the tag's date). Each line was checked against the contract and code at the tag.
• Authenticate. A new section, "When approval needs a recent sign-in": a browser that signed in more than five minutes ago can approve reading only, approving write access or a permission the app wasn't approved for before asks the owner to sign in again and returns them to the screen, and a caller that doesn't ask for a page gets 403 forbidden. Disconnecting an app from a browser needs a recent sign-in. The access, CLI, connect-a-web-page and manage-keys pages say the same where they describe approving or revoking.
• Back up and restore. A new "What an export checks" section names 409 export_rows_unrestorable and 503 export_unrestorable, and says an export is refused 507 insufficient_storage below MARFA_DISK_RESERVE_BYTES. The restore refusals list text that isn't well-formed UTF-16.
• Troubleshooting. Two entries: 403 forbidden "Sign in again to perform this operation", and 400 validation_error for a lone surrogate.

Testing

• pnpm test: 28 files, 354 tests passed.
• pnpm build: passed; checked the changelog, authenticate, back-up-and-restore, manage-keys and troubleshooting pages in dist/, including the new anchors.
• Both through Tools/heavy-run/heavy-run.
• CI not awaited.

Notes for reviewers

• The draft changelog line for the key-narrowing change said it covered extension, folder, type, blob and connector writes. The code does change those doors, but the contract states the rule only for item writes (items/write-race-key-narrowed and its siblings), so the entry names item writes and bulk writes.
• The decoding change is described as a device keeping its working copy (device/undecodable-answer, device/undecodable-answer-keeps-copy, device/event-cut-short). A catch-up cut mid-event ends stream_incomplete, and a follow opens the stream again.
• Recent sign-in for approval has an exception the contract states: a scope the app's standing consent already covers needs no new sign-in (keys-and-oauth/consent-recent-held, device-recent-held).
• Left out of the changelog as internal or not a docs matter: #2179 (tests only), #2189 (a shared page system for Marfa's own screens) and #2191 (a deployment note in the marfa repository).

Checklist

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

[aicayzer]

Review: ready to merge

The docs now match marfa v0.0.16: the sync, a v0.0.16 changelog entry, and the guide changes for recent sign-in, export checks, refused text, the key race and device decoding.

First draft: 4/5. Five statements were less exact than the contract: the sign-in link for a stale session, the second 503 export_unrestorable case, what an export check guarantees, when the second read sends the archive, and the full list of scopes an older sign-in may approve. All were fixed before merge in 8dd6a25, 3f66ec9 and 969c5b9.

Checked.

• True: every added claim against conformance/spec/ and the code at v0.0.16.
• Generated files: re-ran the sync against the tag; every generated file matches.
• Links: new anchors resolve; content lint passes.

For an issue. None.

---

Reviewed by withmarfa-reviewer on Claude Sonnet 5.5. This review may contain mistakes.