[aicayzer]

Summary

Aligns the docs with marfa v0.0.18: the release sync, a v0.0.18 changelog entry, and the guide changes the release's pull requests call for. The release changes what the owner sees (approval choices, a confirm dialog, Home, key and account pages), how Marfa treats numbers, URLs and tags, and how a device sets aside a failing write.

Changes

• Sync. scripts/sync-from-marfa.sh with MARFA_ROOT set to a detached worktree of marfa at the v0.0.18 tag (commit a8497e40a). Generated files are as the sync wrote them.
• Changelog. A v0.0.18 entry in the shape of v0.0.17, dated October 20, 2026: seven entries for running an instance and fifteen for apps and devices.
• Authenticate. The passkey and sign-in paragraphs say what asks for a recent sign-in. New sections: Confirm it's you (the dialog, POST /auth/confirm, attempt windows, what a program sees), Start from Home (Home at /, the sign-in redirect, the older management page) and What the owner chooses (levels per type, Choose types, Already allowed, powers, access_denied). The recent-sign-in section now describes the dialog instead of a redirect.
• Manage keys. A new section on the API keys page; POST /keys answers Cache-Control: no-store; narrow_only on PATCH /keys/{id}; the sample output shows the access words.
• CLI. marfa login and the key and whoami commands print access in the approval page's words; the device-code sample uses the new format.
• Field kinds, properties and troubleshooting. Exact whole numbers and the URL rules (400 invalid_properties), the tag rule for . and .., and updated troubleshooting entries for 403 forbidden ("Sign in again to perform this operation") and 400 invalid_properties.
• Devices. The sixth blocked reason failing_alone, how a device decides on it, and the last answer that marfa device queue prints.
• Sync a folder and Keep folders running. A file item keeps its bytes under a document name; a folder stays listed when another directory takes its place.
• Receive webhooks. A new section on what a change to a webhook cancels.
• Write safely. 422 idempotency_result_not_retained and the device's reading of a 2xx details.original_status.
• Quickstart, Deploy, Access, Connect a web page. Node.js 22.14 (the container image runs Node.js 24), Home after setup, GET / for a browser, and the approval wording.

Testing

• pnpm test: 28 files, 354 tests passed (after one fix: the glossary lint caught "white space" and "integration data"). pnpm build, pnpm build:status and pnpm types:check passed. All through Tools/heavy-run/heavy-run. After the review rounds, pnpm test (354 tests), pnpm build, pnpm build:status and pnpm types:check passed again.
• Checked in dist/: the v0.0.18 changelog is in the built page and in llms-full.txt, and every anchor the new links name exists as a heading (#confirm-its-you, #start-from-home, #what-the-owner-chooses, #when-approval-needs-a-recent-sign-in, #sign-in-as-the-owner, #a-missing-or-unreadable-directory, #use-the-api-keys-page, #narrow-a-key, #change-what-a-webhook-sends, #retry-with-an-idempotency-key, #verdicts, #check-what-a-command-will-use). The updateWebhook operation page exists.
• CI not awaited.

Checked against

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

• Approval pages (keys-and-oauth/approval-*, consent-page-confirm, consent-recent-needed, device-code-lifetime, authorize-narrowed-types, consent-nothing-denies): contract. Row titles and wording from routes/access-choices, consent and pages/registry.ts.
• Confirm it's you (authentication/confirm-*, keys-and-oauth/sign-in-end-self, sign-in-end-recent, revoke-recent): contract. The dialog's wording and the client gate are in pages/client/confirm.ts, account.ts and passkey.ts, in the code only.
• Home and the console pages (instance/root-home*, authentication/console-*): contract. The groups Home lists in this release (Access, You, the older management page) come from routes/home-page.tsx and pages/registry.ts.
• API keys page (keys-and-oauth/update-narrow-only*, manage-narrows-only, app-key-narrows-only, plaintext-no-store): contract; page layout from routes/key-pages.tsx and pages/client/keys.ts.
• CLI access words: core/marfa-cli/src/access.rs and commands/{login,keys,whoami}.rs, against the glossary's access words.
• Numbers, URLs and tags (items/property-number-exact*, property-number-kept, tag-dot-segment, types/url-*, device/number-exact, url-trimmed, url-idna-unassigned, tag-bound): contract.
• Devices (queue-and-verdicts/stuck-write-*, streak-*, failing-alone-*, queue-shows-last-failure, release-clears-streak, not-retained-accepted) and errors/idem-not-retained*: contract; core/marfa-core/src/drain.rs.
• Folders (folders/file-item-doc-name-*, registry-root-identity, registry-replaced-kept, watch-every-root-returns): contract.
• Webhooks (events/cancel-unselected): contract; the cancel text is the error string in the code.
• Node.js 22.14: engines in the root package.json at the tag.
• Lock file message: core/marfa-core/src/lock.rs, code only.

Pages read

• Rewritten or extended: the changelog, authenticate, manage-keys, cli, field-kinds, properties-metadata-and-edges, troubleshooting, devices, sync-a-folder, keep-folders-running, receive-webhooks, write-safely, quickstart, deploy, access, connect-a-web-page (above).
• No change needed: (reference)/api-reference/errors.mdx, api-reference/index.mdx, typescript-sdk.mdx, guides/connector-pull-and-push.mdx, (overview)/items-and-types.mdx, guides/define-a-type.mdx, catalog/your-own-types.mdx, guides/audit-log.mdx, guides/keep-in-sync.mdx, guides/back-up-and-restore.mdx (the restore's five-minute rule is unchanged), guides/settings.mdx, guides/upgrade.mdx, (reference)/folder-watch-record.mdx, the glossary page.

Notes for reviewers

• Left out of the changelog: the CI and test-only pull requests (the four with no change a reader would notice).
• Review round. A review found rules stated more broadly than the contract. Each was checked against the contract and code at the tag and reworded: file items at a document name (only a file already bound to a file item), failing_alone (streak spacing, the independent write, the resend, 429), a retained 2xx (not a create with no id), narrow_only (the enforcement_override limit applies only with it), URL hosts (special schemes, IDNA, the device exception), approval with nothing newly chosen, Choose types, held levels in approval, revoke_keys, POST /auth/confirm from a program, a wrong password on confirmation, the password change, / for a browser that is signed out, and the watch resuming for the original directory. The changelog gains the --no-keychain change, approval rows told apart by identifier, Sign out on a phone, and the destructive-action card with Save shown after a change. Also corrected: the webhook change text ("before it answers" belongs to narrowing), the tag message, and the CLI's requested scopes (it asks for every scope an owner can grant, from OWNER_SCOPES in core/marfa-cli/src/auth.rs).
• Second review round. Passages that restated an intricate rule now say what a reader needs and link the contract statement for the exact conditions. Checked against the contract and code at the tag: the failing-alone rule (queue-and-verdicts/stuck-write-suspect, stuck-write-test-refused: the run needs at least five minutes since it began and no gap over 15 minutes, and a credential refusal of the test parks the queue instead of resending the suspect), whether approval asks the owner to confirm (it follows the access the owner turns on that the app does not already hold, keys-and-oauth/consent-recent-needed, confirm-gate.ts, pages/client/confirm.ts; the 403 follows the same condition), what a form may post (approval-beyond-shown, approval-types-beyond), the held scopes (approval-held-now), access_denied (consent-nothing-denies), and the CLI's requested scopes (OWNER_SCOPES in core/marfa-cli/src/auth.rs, which leaves out profile:write among others, so the page now names the list instead of saying "every"). The same wording replaced the older restatements in Access, Troubleshooting, Connect a web page and the Swift streak row.
• Swift names unverified. (reference)/swift-sdk.mdx and guides/swift-app.mdx are unchanged: I did not confirm the Swift names for failing_alone or the last answer, so the Swift pages do not mention them. A reviewer who knows the Swift surface should say whether they need a line.
• Node.js floor. guides/run-a-connector.mdx still says Node.js 22.13 or later. It was already there, and the connector's own requirement was not checked here.
• Lock file change has no contract id, so its changelog line rests on the code.
• The pages that Home links to but this release does not build are not described.

Checklist

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

[aicayzer]

Review: ready to merge

Summary. The docs now match marfa v0.0.18: the release sync, a v0.0.18 changelog entry, and the pages whose rules changed, each checked against the contract and code at the tag.

First draft: 3/5. Two review rounds found 22 statements that were untrue or overbroad against the contract, mostly where the docs restated a rule with many conditions (approval and consent, the stuck-write rule, URL and folder rules), and four user-facing changes missing from the changelog. All fixed; the rules with many conditions now state the plain rule in a sentence or two and link to the contract statement for the exact conditions.

Checked.

• True: every Marfa name, code, status, rule and number the pull request adds or changes, against the contract and code at v0.0.18; the Swift names against marfa-swift at the release.
• Done: the changelog covers every user-facing change from v0.0.17 to v0.0.18 and nothing CI-only; the generated files match the sync byte for byte; pnpm test, pnpm build and pnpm types:check pass.

Found.

• Overbroad or untrue rules on the queue, folders, URLs and numbers, approval and consent, confirming a sign-in, webhooks, the CLI's scopes. Fixed in 2ac3073 and 81b38df. True
• Changelog missing four changes (#2216, #2212, #2226, #2231). Fixed. Done

Quick fixes. 5 applied by the reviewer.

---

Reviewed by withmarfa-reviewer on Codex GPT-6-Astra. This review may contain mistakes.