[aicayzer]

Summary

Rewrites the Swift SDK, CLI and TypeScript SDK reference pages so each one leads with install and then lists the API by area, with every command's output captured from a real v0.0.20 server. Each page ends shorter than on main.

Changes

• Swift SDK (2,987 to 2,804 words): install first, then the API by area in tables (open, keep in step, read and write, declare types, follow changes, queue, live queries, folders, errors). Contract rule IDs move to the footer. The verdict explanation stays on Devices; this page keeps the API (Verdict, BlockedReason, withdraw, release).
  • BlockedReason has five cases in marfa-swift v0.0.24. The contract's sixth reason, awaiting_dependency, is shown as QueuedWrite.waiting with no verdict (queue-and-verdicts/binding-shows-waiting), so the page says so. Devices keeps the six-reason table.
  • "Open a working copy" now shows how an app keeps its key in the keychain, which the Swift tutorial (docs(guides): rewrite the Swift app tutorial around a live list #550) links to. The sentence "Build an app with Swift handles each" is gone, as docs(guides): rewrite the Swift app tutorial around a live list #550 also removes it.
• CLI (1,549 to 1,193 words): the keychain section becomes a table of login, logout, keys keep and keys forget. marfa operations, marfa whoami and setup status use <Terminal>. The marfa profile update paragraph is dropped (it lives on Authenticate). Every heading other pages link to is kept.
• TypeScript SDK (1,021 to 924 words): "Write and read an item" becomes "Call an operation" without re-teaching the Quickstart's note. Upload, error and contract-check examples use <Terminal>.

Testing

• pnpm test, pnpm build, pnpm build:status and pnpm types:check pass.
• Viewed each page with pnpm dev at desktop and 375 px width (no horizontal page scroll), and read each .md copy.
• Output is from a local server built from marfa v0.0.20 and the CLI built from the same tag. The TypeScript examples ran against it with @withmarfa/client.
• Checked behavior by running it: a key with no server named exits 2; --socket with MARFA_API_URL exits 2; marfa events through the socket exits 5; MARFA_NO_KEYCHAIN takes 1, true, yes and on; marfa login refuses while a key is kept.
• Checked Swift names against marfa-swift v0.0.24.

Notes for reviewers

• whoami output: the server line reads https://marfa.example.com in place of the local address it printed. The rest is as printed.
• Contract mismatch output: produced through a local proxy that rewrote X-Marfa-Contract to 1, because no released server speaks another contract.
• Corrected claim: the old CLI page said a missing MARFA_KEYCHAIN file ends any command with exit code 4. Run for real, marfa status reports no credential, and marfa keys keep refuses with exit code 4. The page now says that.
• The generated exit-code and global-option sections read awkwardly. That needs a change in marfa's core/marfa-cli/COMMANDS.md, not here.

Checklist

• No edits under src/generated/ or to openapi.json
• No URL changes; inbound anchors kept
• Every changed page is shorter than on main
• Output captured, not composed (two disclosed substitutions above)

[aicayzer]

Review: ready to merge

Summary. Rewrites the Swift SDK, CLI and TypeScript SDK pages as shorter references; one wrong Swift fact and several cut or overstated facts are fixed, every inbound link resolves, and each page is shorter than on main.

First draft: 3/5. 1 blocking issue and 5 quick fixes, all fixed in 83e0cb7.

Checked.

• True: every type, case and signature on the Swift page against marfa-swift v0.0.24 (BlockedReason, Keychain.system, all 31 MarfaError cases, Change.Origin, FolderEvent, FileState, LiveQuery, Following); the keychain table and sections against core/marfa-cli at v0.0.20, with operations, whoami and keys forget run on the v0.0.20 build; the contract-mismatch text against the TypeScript client.
• Every path: every link into /cli, /swift-sdk and /typescript-sdk resolves after merging main.

Found.

• The edge-move refusal rule was backwards. A move is refused where the staying end holds more than one edge of the type. Fixed in 83e0cb7. Untrue against marfa
• A missing keychain file: login, logout and keys forget also exit 4. Fixed in 83e0cb7. Untrue against marfa
• folders watch honours MARFA_KEYCHAIN in a shell; only the login agent uses the default keychain. Fixed in 83e0cb7. Untrue against marfa
• Keychain and Server.fromEnvironment throw their own error types, not MarfaError. Fixed in 83e0cb7. Untrue against marfa
• Facts an agent needs were cut: the remaining MarfaError cases, Edges.update returning nil, invalid_properties, the purge permissions, fromEnvironment's throw, original(ofConflictedCopy:) returning an ID, and when blobs.get fetches. Restored in 83e0cb7. Untrue against marfa

Quick fixes. 9 applied by the reviewer.

---

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