Development guide

The engineer-facing onramp. This page is about how you hack on outl — clone, build, test, debug, ship.

If you’re looking for what reviewers measure your PR against, that’s Contributing & code review. The two pages are deliberately split: this one is workflow, that one is policy. Read this first; read that before opening a PR.

If anything here is wrong or out of date, that’s a bug — open an issue or fix it in the same PR that drifted the behavior.

---

1. Quick start

git clone https://github.com/outlmd/outl.git
cd outl
cargo build --workspace
cargo test --workspace

You need Rust 1.99+. rust-toolchain.toml pins the exact version, so rustup installs it on the first build. No other system dependency is needed for the core, CLI, TUI, or MCP server.

To smoke-test that the build actually does something, generate a fixture workspace and open it:

# Creates ./playground with a few pages + journals
just init-playground   # or: invoke /init-playground inside Claude Code
cargo run -p outl-tui -- --workspace ./playground

Press ? inside the TUI for the keymap. q quits.

Optional toolchains by area

The CI containers don’t install GTK, so outl-mobile and outl-desktop are excluded from the workspace cargo clippy/test/doc runs (see CI walkthrough). That means a clean cargo test --workspace does not exercise those two crates. If you change them, run their crate-specific commands and let CI’s mobile.yml / desktop.yml matrices cover the rest.

---

2. Repository tour

The workspace lives in crates/. Each crate has its own CLAUDE.md — read it before editing.

Desktop crate layout

crates/outl-desktop/
├── package.json / tsconfig*.json / vite.config.ts / vitest.config.ts / index.html
├── src/                       # frontend (Solid)
│   ├── index.tsx  App.tsx (Onboarding/AppShell gate)  styles.css  setup.test.ts
│   ├── components/            # AppShell, Sidebar, OutlineView (impl BlockCallbacks),
│   │                         #   BlockRow (chrome) → BlockBody (read) / BlockEditor
│   │                         #     (textarea) / block-suggest / block-callbacks /
│   │                         #     CodeFenceView / SuggestPopups, BacklinksPanel, Picker,
│   │                         #   SettingsModal, ChromeToggleBar, SyncIndicator,
│   │                         #   PropertyEditor (key:: value chips + create/delete),
│   │                         #   Onboarding, WorkspacePicker
│   └── lib/                   # api.ts (desktop-only cmds), code-block.ts, events.ts,
│                             #   shortcuts.ts, action-handlers.ts, store.ts
└── src-tauri/
    ├── Cargo.toml  build.rs  tauri.conf.json (app.outl.desktop)  capabilities/  icons/
    └── src/                   # main.rs, lib.rs (run() registers all commands),
                              #   settings.rs, state.rs, helpers.rs, workspace_open.rs,
                              #   plugin_service.rs, fs_watcher.rs,
                              #   commands/ (thin shims over outl_tauri_shared::commands)

Entry points by intent

When you want to make a change, don’t start from the client — start from the layer that owns the concept.

If you can’t tell where something belongs, grep the Shared primitives catalog. Its three parts — core, markdown, actions — are the canonical map of “who owns this concept”. One grep covers all of them: grep -n 'symbol' docs/shared-primitives.md docs/primitives-*.md.

---

3. Running outl locally

CLI / TUI

# From a fresh build, no install needed:
cargo run -p outl-cli -- init ~/playground-notes
cargo run -p outl-tui -- --workspace ~/playground-notes

# Or build once, run many:
cargo build --release
./target/release/outl init ~/playground-notes
./target/release/outl --workspace ~/playground-notes        # TUI
./target/release/outl --workspace ~/playground-notes page list --json

MCP server (Claude Desktop, Cursor)

cargo run -p outl-cli -- mcp --workspace ~/playground-notes

For wiring into Claude Desktop / Cursor, see docs/mcp.md. Every MCP tool has a outl_* name; the source lives in crates/outl-cli/src/mcp/.

Mobile (iOS simulator)

cd crates/outl-mobile
bun install                     # only once
bun run tauri ios dev           # boots the iOS simulator with hot reload

crates/outl-mobile/CLAUDE.md covers the versioning + TestFlight contract. Do not touch tauri.conf.json’s version field — the version is read from Cargo.toml at build time on purpose.

The commands below spell this cargo tauri rather than bun run tauri. Both drive the same Tauri CLI and either works: bun run tauri goes through the @tauri-apps/cli dev-dependency pinned in package.json (nothing to install beyond bun install), while cargo tauri uses a globally installed cargo-tauri. CI uses the cargo spelling, so that is what the release-shaped commands show.

Simulator, device, and release archive

cd crates/outl-mobile

# iOS simulator
cargo tauri ios dev "iPhone 17 Pro outl"

# Physical device (Mac + iPhone on the same WiFi)
cargo tauri ios dev "<device-name>" --host

# Release archive for TestFlight (local smoke test only — CI ships)
cargo tauri ios build

After the first run, the iCloud capability must be confirmed in Xcode (Signing & Capabilities → iCloud → Containers → iCloud.app.outl.mobile-app).

Why the mobile crate has native Swift / ObjC code

Tauri 2 gives you a WebView + a JS ↔ Rust bridge. What it does not give you is direct access to the iOS platform APIs that outl actually needs to function as a multi-device app:

The native code is split into two tiers with different test contracts:

• crates/outl-mobile/swift/OutlKit/ — pure Swift package (SPM). Logic that’s testable in isolation: brand color, autocomplete chip parsing, toolbar action enum + MFU ordering, peer-file predicates, JS string escaping. Has unit tests under swift/OutlKit/Tests/OutlKitTests/. Run with swift test from swift/OutlKit/ or via mobile.yml in CI.
• crates/outl-mobile/src-tauri/gen/apple/Sources/outl-mobile/ — Tauri-generated iOS shell + outl-specific UIKit / Foundation bridges. Files: main.mm, OutlOpsWatcher.swift, OutlBackgroundRefresh.swift, OutlToolbar.swift, OutlSuggestOverlay.swift, OutlSuggestView.swift, OutlSwizzle.swift, OutlBrandChrome.swift. No unit tests — observed via NSLog probes printed on app boot. Run on a real device or simulator to exercise.

Rule of thumb: if the helper can be tested in a vacuum, it goes in OutlKit. If it has to bind to a UIKit / Foundation API that needs the iOS runtime, it goes in gen/apple/.../*.swift and ships with diagnostic logs instead of tests.

Desktop (Tauri 2)

cd crates/outl-desktop
bun install                     # only once
bun run tauri dev               # dev window with hot reload

A release dmg is built only in CI (release.yml’s build_desktop job, universal arm64 + x86_64). Linux bundles come from build_desktop_linux (AppImage / deb / rpm, one leg per architecture: x86_64 and aarch64, each on a runner of that architecture) and the Windows installer from build_desktop_windows (NSIS .exe; not msi — WiX rejects the non-numeric pre-release identifier every beta carries). Local bun run tauri build is fine for smoke-testing your own arch.

The dmg’s install window is artwork, and CI has to be told to apply it. crates/outl-desktop/src-tauri/dmg/background.svg is the source of truth. background.png beside it (660x400, Tauri’s default dmg window size) is what the bundler actually consumes, and tauri.conf.json’s bundle.macOS.dmg places the app and the Applications alias on it. Regenerate with nix run nixpkgs#resvg -- background.svg background.png -w 660. The card’s fill is tuned to a specific luminance so that both system label colours clear WCAG AA on it, because the Finder draws those labels in a colour that flips with the OS appearance. That reasoning and its numbers live in the SVG’s own comment; lightening or darkening the band under the labels breaks one appearance.

Two things about it are silent, which is why they are written down:

• tauri-bundler turns the whole thing off under CI. It passes --skip-jenkins to its vendored bundle_dmg.sh whenever CI == "true", and that flag skips the AppleScript applying the background and the icon positions. The result is a stock window and no error. release.yml’s dmg step sets TAURI_BUNDLER_DMG_IGNORE_CI: "true" to opt back in, and retries once without it if that AppleScript fails, because it drives the Finder over Apple Events and a runner can refuse it Automation permission. The dmg is a required asset, so without that retry a background image could hold back the whole macOS release.
• Don’t build a release dmg locally under a tiling window manager. The AppleScript sizes the Finder window, and the Finder then bakes whatever frame it ended up with into the dmg’s .DS_Store. AeroSpace (or any tiler) snaps that window first, so the snapped size is what ships. CI has no window manager, so the configured size sticks there.

There is no retina variant: tauri-bundler copies the single background file verbatim and has no @2x or tiffutil path, which is why the art is drawn with flat shapes and thick strokes.

desktop.yml has no aarch64 leg, on purpose. Its check job compiles the whole desktop tree on Linux, so a compile error reaches a PR there whatever the architecture; what is specific to aarch64 is the bundling — the runner’s webkit2gtk, linuxdeploy’s aarch64 AppImage tooling, the per-arch AppRun seed — and none of that is exercised by a --no-bundle debug build. The thing that does exercise it is release.yml dispatched with dry_run: true, which builds and verifies every artifact on the branch and publishes nothing. Run that on any PR touching the release pipeline; adding a second bundling leg to every desktop PR buys the same signal at a recurring cost.

Adding a platform starts in scripts/release_assets.py. That file is the list of what a release publishes: one entry per build-matrix leg, naming its assets, whether it is required, and which package manager points at it. Then the matrix leg in release.yml, its entries in update_tap’s loops, and the url / sha256 / bottle anchors in the manifest that serves it. Every way those can disagree is silent at release time — a sed that matches no line exits 0, update_tap finishes on git diff --quiet, which only asks whether something changed — so somebody’s brew install or scoop install is the first thing to notice, one release later. scripts/check-release-assets.py --manifest runs in hygiene.yml and fails on the mismatch instead; it parses rather than builds, so it takes a second and needs nothing installed.

A release publishes on what is on the draft, not on whether every job went green. The gate used to be needs.<job>.result == 'success' per build job, which made each job a single point of failure for every other job’s assets: one architecture’s bundler, or one flaky runner, and a release with 25 finished artifacts published none of them. The repo’s own workaround for build_android was the opposite extreme — absent from the conditions, so a missing APK published in silence, and the same shape produced a v0.12.0 draft with zero assets that nothing complained about.

So required lives in that table and the pipeline reads it in three places:

• a leg marked optional carries continue-on-error: ${{ matrix.optional || false }}, which keeps the workflow run from going red over a platform still in bring-up;
• publish_release does not read job results at all, which is the part that actually keeps the release moving — a half-failed matrix reports whatever it reports to needs, and the gate never asks;
• what it reads instead is the draft’s asset list, against the table: a missing required asset fails the publish, and a missing optional one publishes with the gap named in that release’s own notes and in the run summary;
• update_tap moves a manifest only when every asset that manifest points at is present, because a manifest carrying a new version and the previous release’s digest is a hash mismatch on install — worse than one still pointing at a release that exists.

Promoting a platform out of bring-up is flipping required in the table, and that flip is the record that it has been green. Nothing about this is a reason to leave a platform optional: the gap is loud in three places, and a leg that keeps failing is a bug with a name.

Asset names use two architecture spellings, and both are deliberate. The CLI / TUI tarballs are outl-linux-x64 / outl-linux-arm64 (and outl-macos-x64 / outl-macos-arm64), the desktop bundles are outl-desktop-linux-x86_64 / outl-desktop-linux-aarch64. The desktop set matches uname -m and Linux packaging convention, which is what a .deb / .rpm / AppImage user expects; the CLI set is older and is what the Homebrew anchors and every published release URL already say. A release asset URL does not redirect, so renaming either family breaks links that are already in the wild — the spellings stay split, and the docs name both.

# from the repo root
bun install                            # hoists workspace deps

# dev (Tauri opens a native window with the Vite dev server inside)
cd crates/outl-desktop
cargo tauri dev

# production bundle (.dmg / .AppImage / .msi depending on host OS)
cargo tauri build

The Vite dev server runs on port 1421 so it can coexist with outl-mobile (port 1420) when both are running side by side.

Testing P2P sync from a source build

A binary cargo launches is a different device from the installed app. The repo’s .cargo/config.toml exports OUTL_DEVICE_DIR = .dev-device-store so the test suite stays off your real ~/.config/outl and ~/.outl. A suite that used them would mint keys in your home directory and arbitrate the endpoint lease against your running desktop app. Cargo exports that variable to everything it launches, cargo run -p outl-desktop included, so a source build gets its own actor id and its own iroh identity — a node id no peer has ever heard of.

Two things follow, and both look like a transport bug when you hit them:

• Devices paired with the installed app store that app’s node id, so the source build reads as offline to them forever.
• The identity is not under target/, and that is deliberate. It was, and cargo clean deletes target/ — which the size hooks run automatically — so every clean minted a new node id and voided every pairing made with the old one. The peer then answers peer refused: this device is not paired with it, because pairing is bidirectional and the phone still lists an id that no longer exists. Three node ids in one day before the store moved to .dev-device-store/, which survives a clean.

default_device_dir() logs one WARN naming the directory at startup, so a source build always says which device it is.

To exercise sync against real peers (a phone on TestFlight, another machine), clear the variable for that command so the build uses the machine’s real identity:

OUTL_DEVICE_DIR= cargo run --release -p outl-desktop

Only do that for a run you want on the wire — it takes the endpoint lease from any installed client that is already running, and writes to your real device store. A source build is now stably paired by default. Pair the phone against .dev-device-store’s identity once and it stays paired across rebuilds and cleans; deleting that directory is the one thing that breaks it again.

It does grow, and pruning it is not the same as deleting it. Every test opens a temp workspace and leaves an actor binding behind, and cargo clean no longer sweeps them: one session left 935 records, all pointing at TempDir paths that were already gone.

./scripts/gc-dev-device-store.sh --dry-run   # count first
./scripts/gc-dev-device-store.sh             # drop bindings whose workspace is gone

It only touches actors/, and only records whose root= no longer exists. A binding is regenerated on the next open, so losing one costs nothing; iroh/identity.key is the node id, so losing that voids every pairing. That asymmetry is the whole reason this is a script and not rm -rf.

Symptoms and network-side causes are in sync.md → Troubleshooting sync.

Playground workspace

Manual smoke tests share a fixture workspace at ./playground/. Generate it with the /init-playground slash command (Claude Code) or by hand:

mkdir -p playground
cargo run -p outl-cli -- init ./playground
# Seed a few pages / journal entries with the `outl page create` / `outl daily append` CLI.

./playground/ is gitignored — feel free to nuke and regenerate.

---

4. The dev loop

The expected per-edit cycle:

1. Edit the relevant .rs / .md / .ts.
2. Run /check (or cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace).
3. If you touched the CRDT four (do_op, undo_op, apply_op, creates_cycle), run /check-invariants + /coverage outl-core.
4. If you touched outl-md, run /roundtrip.
5. Commit using Conventional Commits.

Slash commands

Hooks (run automatically)

.claude/settings.json wires these PostToolUse hooks on every Edit / Write:

• fmt + clippy on the touched crate (faster than /check, runs per save).

• file-size-guard.sh — informational at 400–600 lines, warns at 600–900, blocks at 900+, for .rs, .ts and .tsx alike. When it fires, invoke the refactor-architect agent to propose a split. It covered only .rs until 2026-09, which is why the largest files in the repo are frontend ones it never looked at.

  A hook only runs when Claude Code is the editor. A human in an editor, a Copilot PR and a dependabot bump all bypass it, so the same limit is enforced for everyone in CI by scripts/check-file-size.sh (the hygiene job in hygiene.yml). That runs as a ratchet, not a cliff: the files already past the threshold are frozen with their current line counts in .github/file-size-baseline.txt, and the job fails only when a file not in the baseline crosses 600 lines, or one in it grows past its recorded number. Large files therefore stay editable and the ceiling only moves down. After a split lowers a count, re-record it with scripts/check-file-size.sh --update; the script refuses to write a baseline from a scan that matched nothing, so a broken checkout cannot silently empty it.

• scripts/check-docs-index.sh — every RFC in docs/rfcs/ is reachable from docs/SUMMARY.md. It exists because the index was silently wrong five times in a row: one branch added five RFCs — including the two documenting the changes most capable of destroying data — and listed none of them. The index was complete each time it was last edited; five separate changes each forgot the same step, and nothing failed when they did. It checks reachability, not wording: the summary line is the RFC author’s to write, and a script that generated it would become a second owner of that fact.

• file-size-sweep.sh — the same ratchet, wired as a Stop hook so it runs once at the end of a turn. Every hook above it is PostToolUse on Edit|Write, and that matcher does not include the Bash tool: a file created with python3 - <<'PY', sed -i, cat > or git mv lands on disk having passed no guard at all. The per-edit hook answers “Claude used Edit/Write on a big file”; this one answers “something got big, however it arrived”. It exits 2 once with the failure, then reports without blocking if it fires again (stop_hook_active), so a condition Claude cannot clear does not loop.

• single-declaration-guard.sh — catches code written where a cross-client surface used to live. Three surfaces are declared once and consumed everywhere, each having replaced N hand-maintained copies. The Tauri command surface (outl-tauri-shared/src/wrappers/catalog.rs), the post-mutation commit sequence (outl_actions::commit_page), and the Rust ↔ TypeScript wire contract (tests/wire_types.rs, tests/wire_enums.rs, tests/wire_mirrors.rs). Each already has a test that fails when a client drifts; this hook solves a different problem. A model working from the shape of the old code writes the hand-rolled version again, because the git history is full of it. The test catches that in CI; this catches it at the keystroke, with the file the change belongs in. Every check is deliberately narrow, because a hook that fires on correct code teaches the reader to ignore it. It compares command wrappers per function signature, so open_ref — which needs an AppHandle — stays silent while a plain duplicate does not. It flags a bare apply_page_md_with_sidecar_guarded only in a file that also mutates. And it carries a frozen baseline of the CLI / TUI call sites issue 264 already tracks. That baseline may only get shorter: migrating a file to commit_page deletes its row.

• section-ref-guard.sh — flags a quoted section title that no longer exists. doc-sync-guard.sh reasons about files touched, so renaming a heading passes it clean while leaving the old title quoted in every file that pointed at it. This one resolves `path.md` → "Title" and see "Title" against the target’s headings, bold labels and table rows. Editing a .md also checks the references aimed at it, which is the direction a rename breaks. Full sweep on demand: .claude/hooks/section-ref-guard.sh --all. Its deliberate blind spots are listed in the script header — most importantly, a rename that only appends to the old title stays silent, because this repo quotes shortened titles on purpose.

If you’re not using Claude Code, run cargo fmt -p <crate> && cargo clippy -p <crate> -- -D warnings manually after edits.

Agents (specialised reviewers)

The agents are in .claude/agents/ if you want to inspect or extend them.

cargo doc gotcha

CI runs RUSTDOCFLAGS="-D warnings" cargo doc --workspace --exclude outl-mobile --exclude outl-desktop --no-deps and blocks on rustdoc::private_intra_doc_links. The workspace is mostly pub(crate), so almost every [Foo] link in a doc comment to an internal type breaks the build.

Fix: drop the brackets, keep the backticks.

// Bad — fails CI:
/// See [`MyInternalThing`] for details.

// Good:
/// See `MyInternalThing` for details.

/check runs cargo doc as step 4, so a broken intra-doc link fails there before CI sees it.

---

5. Testing strategy

Where each test type lives

Per-client test suites

Two layers cover each GUI client. outl-mobile:

Every bug fixed in a pure helper (the tokenize duplicate, refs/tags extraction, fuzzy matching) must land with a unit test before merge so it never regresses.

Native bits (main.mm swizzle, BGTaskScheduler, NSMetadataQuery) are not covered by unit tests yet — they’re observed via the NSLog probes shown on app boot. If we add Swift Tests later they belong next to main.mm in gen/apple/Tests/.

outl-desktop:

Frontend suites today: src/setup.test.ts (scaffold smoke — @outl/shared alias resolves), src/lib/chord-format.test.ts, src/lib/markdown-wrap.test.ts, and src/lib/action-handlers.test.ts — OpenRefUnderCursor regression (Enter edits the block; backlink rows open the source; pins #70). Same file smoke-tests the block clipboard (cut arms blockClipboard; paste routes cut → moveBlockAfter, copy → pasteBlockAfter).

The 100% rule

do_op / undo_op (outl-core/src/tree/op.rs), apply_op (tree/apply.rs) and creates_cycle (tree/cycle.rs) carry a 100% line and branch coverage rule. Any new branch needs a new test.

# Coverage report for outl-core specifically (uses cargo-llvm-cov):
/coverage outl-core

The crdt-invariant-checker agent runs the same gate from CI on PRs.

Proptest budget: PROPTEST_CASES

The property suites (outl-core/tests/property_based.rs, outl-md/tests/roundtrip.rs, and any future outl-sync-iroh convergence proptests) bake a low default case count via ProptestConfig::with_cases(200) so local runs stay fast. PROPTEST_CASES is proptest’s built-in override of that number; set it to explore harder without touching the test files.

# Dev default (fast): 200 cases baked into the suites.
cargo test -p outl-core

# Explore the convergence space harder, locally:
PROPTEST_CASES=1024 cargo test -p outl-core -p outl-sync-iroh --all-targets

CI’s dedicated sync job (in ci.yml) sets PROPTEST_CASES=1024 for exactly this pair of crates. That way the probabilistic convergence bugs (op reordering, cycle no-ops, concurrent moves) actually get generated cases on every PR. That job is a required status check: a red convergence run blocks merge. Keep the high budget on the sync job only — running 1024 across the whole test matrix burns runner minutes for no extra signal.

TDD for bug fixes

Bug → reproduce as a test that fails on main → patch turns it green.

# Find an existing similar test:
rg 'fn it_' crates/outl-core/tests/

# Add yours, run only that file:
cargo test --test crdt_convergence -- --nocapture

A bug fix without a regression test is a blocker in review.

What to mock and what not to

• Real JsonlStorage when the test is about persistence, sync, or anything an ops-*.jsonl would touch. Use tempfile::TempDir for the workspace root.
• MemoryStorage when the test is about the algorithm and the storage is incidental noise.
• No mocks for the Tree CRDT. Always replay through the real do_op / undo_op. Mocking those is how you ship a sync bug.
• HLC: prefer the real generator with a known actor id (ActorId::from_u128(1)). Hard-coded timestamps creep into test assertions and break when you change the encoding.

Frontend tests

# From repo root:
bun install              # first time
bun run test             # vitest across every package that declares the script
bun run typecheck        # tsc --noEmit across the same set

# Or per-package:
cd crates/outl-mobile && bun run test
cd crates/outl-frontend-shared && bun run test

Most shared helpers (looksLikeOutline, utf16OffsetToCharOffset, detectRefContext) have direct unit tests under crates/outl-frontend-shared/src/**. New helpers go there, not under a client.

---

6. Cookbooks

Concrete walkthroughs for the changes contributors hit most often.

Add a new Op variant

1. Run /new-op <Variant> for the checklist.
2. Touch order: Op enum (outl-core/src/op.rs) → apply_op + undo_op (tree/mod.rs) → sidecar projection (if it carries metadata) → markdown rendering (if it’s visible) → unit + invariant tests → per-crate docs.
3. Invariants: the inverse must be exact (apply_op then undo_op is identity); cycle-creating moves remain a no-op on the tree but are still appended to the log; new variant carries an HLC + actor id.
4. Run /check-invariants + /coverage outl-core.
5. Update docs/crdt.md if the op changes how the algorithm is described.

Add a TUI shortcut

1. Add the chord to crates/outl-shortcuts/src/.
2. Wire the handler in crates/outl-tui/src/.
3. Add a test that asserts the action ran (against the workspace, not the internal handler).
4. Update docs/tui.md (key table) + docs/shortcuts.md (canonical chord list).
5. If desktop should mirror it, wire it on the outl-desktop side too — the chord catalog is shared.

Add a shared workspace action

The rule from the root CLAUDE.md is: any operation more than one client needs lives in outl-actions before its first use.

1. Add the function to the right module in outl-actions/src/{block,collapsed,todo,page,journal}.rs.
2. Signature: (&mut Workspace, &HlcGenerator, ...) -> Result<...>.
3. Routes every mutation through Workspace::apply — no direct storage writes.
4. Add an integration test in crates/outl-actions/tests/.
5. Wire the TUI / mobile / desktop calls in their respective crates.
6. Add the function to the Shared primitives catalog (docs/primitives-*.md + mirror in .github/instructions/shared-primitives.instructions.md).

Add an MCP tool

1. Add the handler in crates/outl-cli/src/cmd/*.rs returning Result<Value, ApiError>, then register it in mcp/tools/registry.rs (schema) and mcp/tools/dispatch.rs (dispatch) — mirror an existing tool.
2. Tool name: outl_<verb>_<noun> (e.g. outl_block_append, outl_page_create).
3. Wire the underlying logic through outl-actions if it mutates state; through outl-md indices if it’s a read.
4. Return the handler’s Value and let mcp/tools/payload.rs wrap it. MCP does not use the CLI’s { ok, data, error } envelope: a success reply is content-only (compact JSON in content[].text, no structuredContent), and only an error keeps the envelope in structuredContent (RFC 0276). Do not build the result shape in the dispatcher, and do not add an outputSchema to the tool def — declaring one obliges the server to send structuredContent on success. Only add a tool to payload.rs’s markdown_field if the caller already holds every field the flattening drops; crates/outl-cli/CLAUDE.md → MCP has the test and the two ways it was got wrong.
5. Update docs/mcp.md with the tool’s purpose, params, and an example invocation.

Add a theme

1. Add the palette to crates/outl-theme/src/presets/.
2. Register it in the preset enum.
3. Update docs/theming.md.
4. The TUI and desktop pick it up automatically — both read the same palette catalog.

Add a CLI subcommand

1. New module under crates/outl-cli/src/cmd/, mirroring an existing one.
2. Both human-readable and --json output paths — the JSON envelope is documented in docs/cli.md.
3. Hook it into clap in the main command dispatcher.
4. Update docs/cli.md.

Touch the iOS native bridge (Swift / ObjC)

Decide which tier before opening the file:

1. Can the logic be tested without UIKit? (string parsing, predicate, MFU ordering, color math, escape) → goes in crates/outl-mobile/swift/OutlKit/Sources/OutlKit/<Module>/. Add a unit test alongside in swift/OutlKit/Tests/OutlKitTests/. Run swift test from swift/OutlKit/.
2. Does it need a UIKit / Foundation runtime? (UIView, BGTaskScheduler, NSMetadataQuery, NSFileCoordinator, method swizzle) → goes in crates/outl-mobile/src-tauri/gen/apple/Sources/outl-mobile/. Add NSLog probes on entry / exit / error so the behavior is observable on the device console. No unit test today.

If you find yourself writing UIKit-shaped code inside OutlKit, stop — extract the pure part into OutlKit and keep the UIKit binding in gen/apple/. The iCloud peer-file watcher is the canonical pattern: predicate logic lives in OutlKit/Watcher/OpsFilePredicate.swift (tested), the NSMetadataQuery driver lives in gen/apple/.../OutlOpsWatcher.swift (boot-time logged).

Always re-read crates/outl-mobile/CLAUDE.md § “Peer-file materialisation” before touching main.mm or the watcher — that section spells out the iCloud race that two lines of code prevent.

Add a code-block runtime (outl-exec)

1. Add a lang-<name> feature in crates/outl-exec/Cargo.toml.
2. Create crates/outl-exec/src/runtimes/<name>.rs — one struct + impl Runtime. Use echo.rs as the simplest template, or runtimes/query/ for the full pattern (workspace access + embed output + auto-run).
3. Register in RuntimeRegistry::with_builtins behind the feature.
4. Add aliases to KNOWN_ALIASES in crates/outl-md/src/lang.rs and the TS mirror crates/outl-frontend-shared/src/highlight/aliases.ts (same commit — the doc-sync-guard hook checks this).
5. If the runtime returns OutputFormat::Embeds, the orchestrator already handles it — no UI change needed.
6. If the runtime should auto-run, override auto_run() to return true.
7. Document the DSL in docs/markdown-format.md § Query code blocks (or create a new section for non-query runtimes).
8. Read crates/outl-exec/CLAUDE.md for the full surface and “what this crate does NOT own”.

---

7. Debugging

Common failure modes

Dump the op log

Each device’s log is a plain JSONL file under ops/:

cat ops/ops-<actor-uuid>.jsonl | jq .
cat ops/ops-<actor-uuid>.jsonl | jq -r '.timestamp + " " + .op.type' | head

To replay a log into a fresh MemoryStorage and inspect the materialized tree, write a tiny binary under xtask/ — there’s already a pattern in xtask/src/bin/gen-10k.rs.

Tracing

The libraries emit tracing spans at debug. Run any binary with RUST_LOG to enable them:

RUST_LOG=outl_actions=debug,outl_core=debug cargo run -p outl-cli -- --workspace ./playground page list
RUST_LOG=outl_tui=debug,outl_md=info cargo run -p outl-tui -- --workspace ./playground

Spans of interest:

• outl_actions::sync — SyncEngine work loop, peer detection.
• outl_core::log — replay, append, lock acquisition.
• outl_md::reconcile — 3-level matching decisions.

Doctor

cargo run -p outl-cli -- workspace doctor --workspace ./playground --json

Walks the workspace and reports: corrupted sidecars, orphan blocks, mismatched hashes, missing op log entries. Run this before assuming the bug is in your patch.

---

8. Performance

Hot paths (from contributing.md)

• outl_core::tree — every op apply, every tree walk.
• outl_core::log — every append, every replay.
• outl_md::parse / render — every .md read/write, every TUI buffer refresh.
• outl_md::index — backlink rebuild; scales with workspace size.
• outl_tui render loop — runs on every keystroke.
• outl_actions::SyncEngine work loop — every file event.

Anything outside those is a correctness conversation, not a perf one.

Running benches locally

The criterion suite lives under crates/outl-md/benches/:

# Whole suite (small + medium + large fixtures, sub-second each):
cargo bench -p outl-md

# Single bench:
cargo bench -p outl-md --bench parse
cargo bench -p outl-md --bench index -- "medium_"

# 10k-file xlarge (slow — minutes, not seconds):
cargo bench -p outl-md --bench index -- \
  --warm-up-time 2 --measurement-time 10 --sample-size 10 "xlarge_"

Criterion writes target/criterion/<bench>/report/index.html. Open it in a browser to compare a baseline against your change.

End-to-end CLI bench

xtask/src/bin/gen-10k.rs builds a 10k-page payload; hyperfine measures CLI wall-clock. The exact recipe lives in .github/workflows/bench.yml bench-cli-xlarge if you want to reproduce locally.

Composite-write diagnostic bench

crates/outl-actions/tests/composite_write_bench.rs is an #[ignore]d, non-criterion test. It times the two write shapes the MCP / batch surface uses most (page create + forest + properties, full page replace) with and without an outer Workspace::begin_batch(). It’s a diagnostic baseline, not a CI gate — run it manually when touching the batch persistence path:

cargo test -p outl-actions --release --test composite_write_bench -- --ignored --nocapture

---

9. CI walkthrough

Action pinning

Every uses: points at a full commit SHA with the release tag in a comment (actions/checkout@<sha> # v7.0.1), so a moved or hijacked tag can’t change what runs next to the release secrets. Don’t hand-edit a SHA back to a tag: .github/dependabot.yml bumps the GitHub Actions pins weekly in one grouped PR, along with Cargo and Bun. To pin a new action, resolve the tag with gh api repos/<owner>/<repo>/git/ref/tags/<tag> and, when that returns a tag object, follow it to the commit.

Runner sizing

Every workflow runs on Blacksmith runners (runs-on: blacksmith-<n>vcpu-<image>, with -arm appended for ARM64 Linux), never on GitHub-hosted ones. The one exception is release.yml::publish_npm, which runs on ubuntu-24.04: npm trusted publishing (OIDC) does not accept self-hosted runners yet, and Blacksmith registers as self-hosted. Moving it back to Blacksmith breaks the npm publish. Its trusted publisher on npmjs.com (@outl/plugin-sdk → Settings → Trusted publishing) must stay configured as owner outlmd, repository outl, workflow release.yml, environment release, with publishing allowed. Billing is per vCPU-minute, with a platform multiplier on top: ARM 0.625x, x64 Linux 1x, Windows 2x, macOS 6.67x. That multiplier is why job placement matters more than job speed: a 29s macOS job costs more than a 5min Linux one.

Two rules follow from it, and both are already applied in the workflows:

1. Only platform-specific work runs on macOS or Windows. Anything that produces the same result on Linux runs on Linux, once. mobile.yml::rust-check builds outl-mobile only for this reason — outl-actions / outl-core / outl-md are covered by ci.yml::test, and running their suites again on macOS was 55% of a full run’s bill.
2. Size the SKU from measured CPU and memory, not from intuition. blacksmith jobs stats <job_id> prints the per-job CPU timeseries, memory peak and OOM count; blacksmith usage --breakdown-by workflow_job prints what each job costs.

Sizes as of the Blacksmith migration, from a full run of every workflow:

The Linux release legs are pinned to ubuntu-2204, not 2404, and that is not a cost decision. A glibc-linked binary runs on the glibc it was built against or newer, never older, so the image the artifact is built on is its compatibility floor: 22.04 is glibc 2.35 (Debian 12, every supported Ubuntu LTS), 24.04 is 2.39 (and nothing older than itself). build_desktop_linux was pinned for this from the start and said so; the CLI leg was built on 24.04 until #411, which made outl-linux-x64.tar.gz die with version GLIBC_2.38 not found on exactly the distros where someone downloads a tarball instead of using a package manager. Bumping either to 24.04 raises that floor for everyone; do it on purpose, or not at all.

Check names must not contain the runner SKU. Branch protection matches required checks by name, so test (ubuntu-latest) becoming test (blacksmith-8vcpu-ubuntu-2404) leaves main blocked on a check that will never report again. Matrix jobs therefore carry a stable label (linux, macos, macOS arm64, …) and the SKU lives only in matrix.os.

What blocks merge

The ci.yml jobs are the merge gate. The PR template and the policy in docs/contributing.md describe everything else reviewers look at on top of CI.

Debugging a red CI

1. Read the failing job’s “Annotations” at the top of the PR check page — it usually points at the file + line.
2. Reproduce locally with the exact command the workflow ran (the YAML is the source of truth).
3. If cargo doc fails with rustdoc::private_intra_doc_links, see the doc gotcha above.
4. If clippy fails on a target you don’t have (e.g. you’re on Linux and it’s the macOS leg), check that the failure isn’t environmental before suspecting your patch. outl-mobile and outl-desktop are explicitly excluded from ci.yml’s clippy job; if you somehow re-included them, that’s the bug.

Flakes

Treat a flaky test as a real bug. The CRDT and parser have no inherent flakiness — if a test fails twice and passes the third time, it’s hiding a race or a non-deterministic order in something we control. Don’t add retries; find the cause.

---

10. Release process

Version source of truth

[workspace.package].version in the root Cargo.toml. Crate manifests inherit via version.workspace = true. Bumping the workspace bumps everything.

crates/outl-mobile/src-tauri/tauri.conf.json deliberately omits version; CI reads Cargo.toml and injects the value into cargo tauri ios build via --config. This is non-negotiable — see crates/outl-mobile/CLAUDE.md § “Versioning + TestFlight release”.

Beta cadence

Every push to main produces a beta release automatically:

• Tag: v<workspace.version>-beta.<run_number> (e.g. v0.6.0-beta.48).
• Binary: reports the full beta version (the workflow seds Cargo.toml in-place before cargo build; the change is local to the runner).
• GitHub: published as a prerelease with auto-generated release notes.
• Homebrew tap (Formula/outl-beta.rb, Casks/outl-desktop-beta.rb) bumped automatically with [skip ci] commit.

GA

Bump workspace.package.version (e.g. 0.6.0 → 0.7.0), merge to main, then push a v0.7.0 tag by hand. The tags: ["v*"] trigger in release.yml picks it up.

TestFlight (iOS)

mobile.yml builds + signs the IPA on every push. testflight.yml runs after mobile.yml completes, downloads the IPA artifact, uploads to App Store Connect.

Release notes (“What to Test”) come from conventional-changelog-cli (preset conventionalcommits) reading the commit log since the last tag. Use Conventional Commits. A commit without a feat: / fix: / chore: prefix lands under a generic “Other changes” bucket — the user loses context.

iOS version propagation and TestFlight

Single source of truth: Cargo.toml workspace version. To bump the app version, edit [workspace.package].version at the repo root — everywhere else inherits:

Why --config and not Tauri’s Cargo.toml fallback? The iOS code path doesn’t honor that fallback — it uses 1.0.0 instead. So CI reads the workspace version (awk against Cargo.toml in Compute build metadata) and passes it via --config; the Patch archive CFBundleVersion step aborts if the propagated short version mismatches. Never put "version": "x.y.z" back in tauri.conf.json — Tauri would then use the static value over the --config override and the two drift on the next bump.

CI release flow

A push to main triggers in parallel:

1. Release (release.yml) — auto-bumps Cargo.toml locally to <base>-beta.<run_number>, cuts a v<...>-beta.<N> tag, builds desktop binaries, ships the Homebrew formula (never commits the bump back).
2. Mobile (mobile.yml) — builds the signed IPA from the unbumped Cargo.toml, uploads it as outl-ios-release, triggers TestFlight.
3. TestFlight (testflight.yml) — downloads the artifact, uploads to App Store Connect (xcrun altool).

CFBundleVersion (build number) scheme

Apple needs CFBundleVersion strictly monotonic across every IPA, but the marketing version (0.5.1) repeats across beta builds. Scheme: CFBundleShortVersionString = <SHORT_VERSION> (e.g. 0.5.1); CFBundleVersion = <SHORT_VERSION><BETA_PAD> (e.g. 0.5.1027, beta number zero-padded to 3 digits). BETA comes from the latest v<SHORT_VERSION>-beta.<N> git tag (set by Release), falling back to Mobile’s github.run_number; re-runs append .<run_attempt> as a 4th component to dodge Apple’s duplicate guard. The build number is patched into the .xcarchive’s embedded Info.plist after cargo tauri ios build but before xcodebuild -exportArchive — the only injection point that survives, since Tauri exposes a single version field.

What goes wrong if you forget this

• Patching gen/apple/.../Info.plist pre-build is a no-op (Tauri regenerates it); xcrun altool exits 0 even on 409, so testflight.yml greps for ERROR:, don’t simplify it.

Homebrew

The tap is at the root of this same repo (Formula/, Casks/). The update_tap job in release.yml patches version + sha256 anchors for both the CLI formula and the desktop cask after every beta release.

The desktop dmg is unsigned today (Apple Developer account pending). The cask carries a caveats block with the xattr -dr com.apple.quarantine workaround.

crates.io (lib crates for embedders)

The publish_crates job in release.yml publishes outl-core, outl-md, outl-actions, outl-ws and outl-exec to crates.io on every release, beta and GA, at the same version the binaries report. The first four are the embedding contract; outl-exec ships only because outl-actions references it and cargo refuses to publish a crate whose dependencies aren’t in the registry. Every other crate in the workspace carries publish = false; flipping one later is a one-line change (plus adding it to the job’s publish loop).

SemVer keeps consumers safe: a plain outl-core = "0.11" requirement never resolves a -beta.N prerelease, so crates.io consumers only see GA versions unless they opt in with a "0.11.0-beta"-style requirement.

The job is idempotent (it checks crates.io before each publish, so re-runs resume instead of failing) and self-gating (cargo publish verifies each crate by building it). It authenticates with the CARGO_REGISTRY_TOKEN secret in the release environment.

---

11. Where to ask

• Bugs: GitHub issues with the bug report template.
• Feature requests: GitHub issues with the feature template.
• Security: SECURITY.md. Do not open a public issue.
• Design discussion: open an issue with the discussion label, or a draft PR labeled RFC.
• Direct contact: the project maintainer is @avelino.

Welcome aboard. Read contributing.md before opening a PR — it’s the policy this dev guide is the workflow for.