Local Agent Authoring

Local Agent Authoring lets Claude Code or Codex work on one encrypted zudo-text cloud workspace through the official stdio MCP server. This is how local editing returns after the cloud-primary pivot: a real coding agent runs on the user's machine and calls narrow workspace tools. It is not an in-app terminal or PTY, and it does not recreate a local workspace directory.

The only shipped MCP transport is the local stdio process from the versioned public @takazudo/zudotext-mcp npm package. There is no public remote MCP endpoint and no per-published-site MCP endpoint.

This page is the design and safety-policy authority. The MCP integration guide owns user workflow, while the package page owns distribution, configuration, exact inventory, and release details.

System shape

Claude Code or Codex
        │ local stdio MCP
        ▼
zudotext-mcp (one process, one workspace)
        ├── document tools ── HTTPS ── Automation API ── files / versions / changes
        ├── asset tools ───── HTTPS ── opaque /api/assets ── D1 + R2
        └── ask_zudo_agent ── HTTPS ── agent-server ── Automation API tools

The MCP process holds the configured workspace id, workspace-bound PAT, and workspace password. It translates plaintext, workspace-relative paths into the two encrypted wire contracts; the coding-agent harness never needs to implement zudo-text crypto itself.

One process, one authority boundary

A normal authoring process is intentionally narrower than an interactive app session:

Grant	Shipped authority
`documents:read`	List, read, and search documents; poll document changes; read versions and checkpoint projections.
`documents:write`	Create, replace, soft-delete, move, restore document versions, and create authoring checkpoints.
`assets:read`	List, inspect quota, and download assets; also fetch the encryption salt needed for local asset-key derivation.
`assets:write`	Upload a new asset or create an empty asset folder.
`agent:invoke`	Optional access to `ask_zudo_agent`.
`full`	Explicit compatibility grant for the wider interactive/server surface; never part of the local-agent default.

The default guided flow mints exactly the first four scopes and binds the PAT to the current workspace. Add agent:invoke only when cloud-agent delegation is required. One MCP process exposes one ZUDOTEXT_WORKSPACE_ID; workspace multiplexing is deliberately absent.

The server still treats a PAT request that omits scopes as full for pre-scoped compatibility. The app avoids that compatibility default: the generic token form preselects the four narrow authoring scopes and presents Full access as a mutually exclusive opt-in.

Documents and assets use different key paths

Documents: bounded server key session

The MCP process derives three raw 32-byte document subkeys locally with PBKDF2-SHA-256 at 600,000 iterations. It sends the transient bytes over TLS to the Automation API once to open a key session. The sync Worker keeps them only in Durable Object memory for at most one hour, never in D1, R2, logs, Durable Object storage, or an agent conversation.

The returned session id is bearer-equivalent access to decrypted documents and stays in process memory. Expiry or eviction triggers one re-derivation/reopen retry. MCP close, transport close, SIGINT, and SIGTERM start the same idempotent best-effort session deletion; abnormal death falls back to expiry.

Assets: local non-extractable keys

Asset tools do not open or use the document key session. The local process derives non-extractable Web Crypto keys and sends only deterministic encrypted path tokens and encrypted byte envelopes to the existing /api/assets family. Plaintext asset paths and bytes exist only in the MCP process and the explicit local source or destination files.

An assets:read PAT may fetch only encryptionSalt from workspace metadata without the document subscription gate. That exception still checks PAT workspace binding and ownership; it authorizes no keyed document route. assets:write alone does not grant the metadata read, which is why normal asset configuration includes both asset scopes.

Direct tools and cloud-agent turns

The MCP registry has exactly 21 tools. Direct document, history, change, and asset tools are deterministic operations and spend zero AI turns. ask_zudo_agent is the one delegation tool: use it for semantic, open-ended, or genuinely multi-step work, not to guess around a missing path or an omitted asset operation.

Every admitted ask_zudo_agent call spends one of the user's shared 100 AI turns per UTC day, before the model runs; a later failure still consumes that admission. Assistant-panel and inline-AI calls use the same pool. All Automation API routes, including the cloud agent's internal tool calls, also share one fixed 120 requests per user per minute budget. One regex search scans at most 2,000 candidate paths and reads content from at most 240 documents, so a truncated answer is incomplete rather than proof that no later match exists. The cloud agent's internal query_kanban can spend up to 85 of those shared requests in one bounded discovery/recovery walk.

The cloud agent can commit create_note directly because it is create-only and fails on a collision. Existing-note changes use propose_edit instead: ask_zudo_agent returns validated previews with newContent, baseVersion, diff, summary, and expiry, but applies none of them. A local caller reviews the candidate and, while it is valid, writes it with expectedVersion: baseVersion. Conversation history may retain plaintext excerpts from tool results; the document store's E2EE guarantee does not extend to that conversation record.

Document history, move, and undo

Document writes are whole-body writes with optimistic concurrency. Omitting expectedVersion means create-only; replacing, deleting, moving, and restoring requires a current version. Move preserves the stable file id and history, then appends an ordered old-path delete and new-path upsert; it does not add a move action or a content version.

what_changed is an ordered document-only polling cursor. It includes document upserts, tombstones, and both rows of a document move. It excludes assets and is not a WebSocket feed.

begin_authoring_session creates the checkpoint that marks an agent's document undo boundary. A checkpoint is a named change-log cursor, not a workspace snapshot. Per-file version restore is server-backed. Checkpoint rollback is a client-orchestrated manifest of restore, delete, and noop work:

fetch the restore manifest and its expectedHeadCursor;
page explicit what_changed(afterCursor: 0) calls until hasMore is false, passing each page's changeCursor into the next call, then compare the final cursor;
apply each normal optimistic mutation;
stop on the first conflict and report possible partial progress.

There is no one-call or atomic workspace rollback. HISTORY_COMPACTED is a typed failure, not an empty history. History, checkpoints, restore manifests, and change cursors cover documents only.

The sync server's nightly retention pass keeps every version from the most recent 24 hours, then thins unpinned history to hourly, daily, and weekly representatives. Current versions and versions pinned by a checkpoint are always retained. Pruned version rows hand off unreferenced encrypted R2 blobs to a queue with a further 24-hour grace period before deletion; this affects which old versions a local agent can read, but never deletes changes rows or changes HISTORY_COMPACTED semantics.

Narrow asset policy

The five asset tools are list, usage, local-path download, local-path upload, and empty-folder creation. Upload accepts only an explicit absolute path to a regular non-symlink file and enforces a 25 MiB plaintext limit. Download uses an explicit absolute destination, refuses to overwrite it, and removes only the partial file that call exclusively created after a failure. Asset bytes never enter MCP text or structured results.

Assets have no immutable revision, versions, history, checkpoint coverage, document change cursor, or undo. Consequently the narrow family has no move, rename, delete, recursive delete, replace, or delete-and-recreate operation. Those remain interactive/full; callers must not emulate them. Neither a document move nor an interactive asset rename rewrites Markdown references.

Committed asset mutations wake open filers with the content-free { type: "assets-changed" } notification. It only means “refetch listing and usage”; it is not ordered, replayable, or connected to the document cursor.

Resource policy

Direct whole-document writes are powerful enough to damage structured product files even when the version precondition succeeds:

Ordinary notes and archives/ documents are writable; archives/ is an ordinary workspace-relative prefix and needs no special tool or scope.
Preserve an existing YAML frontmatter block byte-for-byte unless the user explicitly requests a field change. A malformed raw rewrite can desynchronize indexed metadata.
zudo-text directive round-tripping through an agent write is unverified. Preserve directive text unless the user explicitly accepts the risk.
Treat boards as read-mostly. Kanban has an evidenced 400 ms whole-board debounce race; todo, timeline, mindmap, spreadsheet, and slide use separate persistence paths whose agent-write safety remains unverified.
Treat .zudotext.settings.json, frameset state, and pins as read-only. They are whole-document last-writer-wins state; concurrent app writes can clobber automation, while malformed settings can fall back to defaults.

The packaged Claude Code and Codex skills encode these defaults, including an owner-editable confirmation policy for destructive whole-note operations.

Local active-note pointer

The desktop app also has an optional local active-note pointer. It is off by default and is never enabled by PAT creation. When enabled, the app writes ~/.config/zudotext/<appname>/active-note.json with the active workspace-relative note path, pane/view, and selected line/column range; note content is never included. It refreshes every 10 seconds and on note/pane/view changes. Readers treat data older than 30 seconds as stale. Disable, workspace switch, no active workspace note, and clean shutdown clear it; a crash may leave a stale file. This is read-only orientation metadata, not an MCP write-back channel.

Deliberately absent in v1

public remote or per-published-site MCP endpoints;
patch/range edits, merge engines, and multi-file transactions;
an agent WebSocket feed (poll what_changed for documents);
asset history, checkpoints, cursor entries, reference rewriting, or narrow destructive asset tools;
token self-service from a PAT, workspace multiplexing in one MCP process, or a redesign of cloud-agent conversation deletion/privacy;
compaction while checkpoints exist; nightly version/blob retention does not compact or delete the document change log, so its growth remains explicit.

Verification map

The MCP surface has several evidence layers. A green deterministic lane proves only the contract named in its row; it does not silently promote a fake, packaged, or in-process result into deployed authenticated evidence.

Contract	Status	Deterministic evidence	What it proves	What it does not prove	Environment validity
Inventory and schema contract	Passing	`server-inventory` and `tool-quality` in `packages/zudotext-mcp/src/` (PR gate)	Every registered tool, description, input/output schema, and annotation matches the checked-in inventory and quality rules.	Family behavior, route parity, package installation, or a deployed account.	In-process MCP server with fake transport; deterministic PR evidence.
Per-family tool behavior	Passing	`packages/zudotext-mcp/src/tools/*.test.ts` (fake transports, permutations, and failures)	Each direct tool family handles its expected success, conflict, malformed, and failure paths.	A real Hono backend, deployed service, real account, or release tarball.	Package Vitest fakes; deterministic PR evidence.
Backend route parity	Passing	`agent-route-inventory` plus `feature-manifest` (PR gate)	Agent-facing Automation and Assets routes are mapped to an MCP tool or an explicit v1 exemption.	That the mapped route works through a deployed service or that a fake covers every wire detail.	Checked-in snapshots and manifest diffed in tests; deterministic PR evidence.
Connected authoring journey	Passing	`workers/sync-server/test/mcp-journey`	The MCP source connects to the real Hono application and exercises encrypted documents and assets in Miniflare.	The deployed service, a published tarball, a real account, credentials, or production quotas.	In-process real Hono app with Miniflare D1/R2 and Durable Objects; deterministic PR evidence.
Packaged binary	Passing	`release:verify` in the PR gate and release workflow	The built tarball installs, starts, reports its version, exposes the exact inventory, and carries the expected skills and dependencies.	Deployed authentication, live workspace behavior, or agent capability.	Temporary-prefix install of the locally built artifact; deterministic package/release evidence.
Live authenticated journey	Outstanding	`mcp-live-verify.yml` (the scheduled `live:verify` lane)	Only a conforming credentialed run can establish deployed end-to-end behavior and its archived report.	Package fakes, Miniflare, a health check, a local smoke, or an unprovisioned/manual run.	Dedicated smoke workspace, narrow PAT, password source, deployed server, and published release; Outstanding until a conforming scheduled run is linked.
Agent scenarios	Outstanding	`eval:agents`	A manual run can measure whether an agent completes representative cards with the shipped skill and permitted tools.	Deterministic tool correctness, every possible prompt, or a PR-gate result.	Manual isolated harness run; archive each report per run on the epic; Outstanding until an owner run is linked.
Structured-document jobs	Raw-text-only	`MCP_FEATURES` rows for kanban, mindmap, todo, and timeline	The manifest records which read/write tools can cover these jobs as raw Markdown text and names their gaps.	Format-aware parsing, transactional multi-file edits, or product-specific safety for those formats.	Deterministic manifest coverage only; format-aware tools are a follow-up epic.