[aicayzer]

Summary

Rewrites four dense guides so each page does one job, in an order a reader can follow, with command output captured from a running instance. Every page is shorter than on main, and no URL changes.

Page	Words before	Words after
Define a type	2,094	1,440
Keep a copy in sync	1,625	1,511
Export and restore an archive	1,439	1,352
Deploy	1,492	1,465

Changes

• Define a type. Shows receipt.json once. Each call then sends that file, so the body is no longer repeated nine times. Field keys and identifier rules link to the Catalog's Type rules instead of being repeated in a table. The strict-mode paragraph is now two sentences that link to Settings. The register response now includes provenance, as v0.0.21 returns it.
• Keep a copy in sync. Builds sync.ts in five <Steps>, with each step adding its own piece of code. Defines apply, saveCursor, rebuild and follow where they first appear. Replaces the 600-character SSE line with real marfa events output in a <Terminal> and a short raw-frame example. Replaces the stub section with one sentence that links to the read-views chapter.
• Export and restore an archive. Keeps one page, because moving data is one job. The hanging ### sections are now ## sections. On-screen names are bold. The three command and output pairs are in <Terminal>. Inline contract IDs move to the footer.
• Deploy. Puts the run steps first: generate the secrets, write marfa.env, start the container, then claim the instance. The configuration reference follows. Bold drops from 20 phrases to 8. The six inline contract IDs move to the footer. The Docker subnet aside is now part of the TRUSTED_PROXY_CIDRS bullet. The socket's 401 rule now names what needs a key, as v0.0.21's CLI says it.
• Links. Settings now links NODE_ENV to #run-it-without-a-container, because #what-the-server-needs is gone. The changelog's normalize entry now links to #change-the-type. Deploy keeps #the-private-socket as a subheading, because Manage keys and Sign in as the owner link to it.

Testing

• pnpm test passed (364 tests, including the content lint). pnpm build, pnpm build:status and pnpm types:check succeeded.
• Every link into or out of the four pages and Settings was checked against the target page's headings, including the new changelog. No anchor is broken.
• Each page was viewed with pnpm dev: at desktop width in headless Chromium, and at 375 px in a browser, with no horizontal page scroll. Each .md copy was read. Steps, Terminal and Files render as headings and plain fenced blocks.
• Output was captured from local v0.0.21 servers built from the v0.0.21 tag, on a fresh database:
  • POST /types (201, with provenance), a repeat (409 type_already_exists), normalize, replace and delete.
  • marfa events --type core.note --edges none --from 4, and the raw SSE frames from cursor 5.
  • sync.ts with @withmarfa/client@0.0.21 passed tsc with no errors. It rebuilt the copy, applied a live create and a purge, and rebuilt after a forced cursor_ahead. (The cursor_ahead run was on v0.0.20.)
  • marfa export followed by tar -tzf. An export with one blob file removed exited 1, kept <path>.incomplete, and listed the blob under missing_blobs.
  • marfa --socket ... restore into a second fresh instance, run twice (duplicates, already_present). A key's restore was refused 403 forbidden.
  • The socket's 401 message, /health components, and the image's ENV and HEALTHCHECK lines.
• Not tested: the browser Export and restore page (its labels were read from the v0.0.21 source), the Docker image itself, Railway, the S3 settings, and a restore with blobs_missing.

Notes for reviewers

• The page facts were first checked against v0.0.20. main moved to v0.0.21 during the work, so I re-ran the captures and reread the v0.0.21 contract diff for types, events, export and restore, instance and device. Two changes affected these pages: the type provenance and the socket's 401 wording. Both are updated.
• Deploy says a new volume of a shared-prefix instance "starts on whichever database was replicated last". This comes from marfa's deploy/README.md, not a contract rule.
• Export and restore no longer says a store failure is one that "doesn't answer within 15 seconds", because I couldn't confirm that number.
• The raw SSE example in Keep a copy in sync shortens the item to ..., and the page says so.
• Export and restore still has 19 bold phrases. They are all on-screen names or bold-lead list items. None is emphasis.

Checklist

• The title is a scoped Conventional Commit.
• New behavior has a test that was seen failing first, or no test was needed and the reason is above. (Docs only. The content lint and the link checks above cover it.)
• Docs, comments and the contract still say what is true after this change.
• No URL changes, no edits to src/generated/ or openapi.json, and no internal hostnames, personal paths, keys or tokens.

[aicayzer]

Review: ready to merge

Summary. Rewrites Define a type, Keep a copy in sync, Export and restore and Deploy shorter and in the reader's order; true against marfa v0.0.21 after four fixes.

First draft: 4/5. No blocking finding; quick fixes that mattered, in 560e38e.

Checked.

• True: export formats, state=any, files=false, the archive's files, missing_blobs, .incomplete and the refusals; restore rules and on-screen labels; the Dockerfile settings, the two secrets, the socket path, /health, instance/stop-within-eight, the sign-in limit; the shared-bucket claim (instance/replica-restores-own, instance/replica-under-prefix); type register, repeat, normalize, replace, delete and provenance; the event frames and @withmarfa/client 0.0.21 exports.
• Every path: every link into and out of the four pages resolves.

Found.

• Running without a container implied the server reads marfa.env. It doesn't, so a reader would have started with trial secrets. The page now says the settings must be in the server's environment. Fixed in 560e38e. Untrue against marfa
• The CLI replaces the export path only when the export ended whole and lacks no files. Fixed in 560e38e. Untrue against marfa
• resolved_type "never matches" and "within about eight seconds" overstated or blurred their rules. Fixed in 560e38e. Untrue against marfa

Quick fixes. 8 applied by the reviewer.

---

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