# Phase 3 — Cataloging Desk (plan)

Status: **draft — recorded 2026-06-14 (Fritz + Opus). Important.** Not yet
scheduled, but flagged high among the forward phases. This is the detailed
plan behind the roadmap's "Phase 3 cataloging desk" bullet.

## One-line

Add the **write side**: create and edit documents *in markdown source* from the
Reading Room — a projection of the broker's write protocol (`mark_publish` /
`mark_append`), the same way reads project the read protocol (ADR 0005 decision
11). Markdown in, rendered out. No WYSIWYG, no rich text, no comments.

## Why (the gap)

The room is **read-only today**. The library `WorldGateway` port has read verbs
only (`Fetch`/`List`/`Versions`/`Lookup`/`Worlds`); there is no write path
through the hexagon. The write *protocol* already exists at the broker — this
phase is the room's surface onto it, so a human edits a document the same way an
agent does, and both pass through the same authz + write gate.

## What the broker already gives us (verified 2026-06-14)

- **Writes** use "a long-lived per-world token the broker provisions on first
  write" (broker `MCPConfig` doc). The write token's op is hardcoded to
  `["publish"]` (#163) and its `Paths` are world-config globs.
- **`mark_publish`** carries metadata OUT OF BAND — `title`, `tags`,
  `importance` in a `metadata` object; the body is pure markdown. A body that
  opens with a `---` frontmatter fence is stored as literal content (the
  recurring publisher bug). `expected_version` is required (0 to create);
  `on_conflict` defaults to a structural-merge candidate the caller re-verifies.
- **`mark_append`** appends to a body and CANNOT carry metadata — tags/importance
  stay frozen at the doc's last publish; a materially new subject means re-publish
  with extended tags.
- A **write-time gate** enforces tags/importance at the system's chosen severity
  (warn / block / ask). The desk should satisfy it on the first submit.

## Design decisions (recommendations — settle before building)

### D1. Editor surface — RECOMMEND htmx-pure textarea + live server preview first

The room is htmx-hard, no client state (ADR 0003). An editor is the natural place
to break that, so be deliberate:

- **Recommended:** a plain `<textarea>` whose input `hx-post`s to a
  server-rendered **preview fragment** (debounced) — the same markdown→HTML
  pipeline the reader already uses, so WYSIWYG-grade fidelity with ZERO new JS
  and the server as the single source of truth. True to ADR 0003.
- **Escalation (documented, not first):** a CodeMirror **island** for syntax
  highlighting / large docs — a bounded JS island like mermaid/KaTeX, client
  state confined to the edit buffer, server still authoritative on submit. Spend
  this island only if the textarea proves inadequate.

The roadmap's "CodeMirror island" phrasing is the escalation, not the default.

### D2. Editing is a focused-pane MODE, not a trail chunk — RECOMMEND

A trail URL is a shareable *reading* context; an unsaved draft is client state
that has no place in a shared, reconstructable URL. So:

- Editing is an **action on the focused document pane** (an edit mode), reached
  from a margin "edit" affordance — NOT a new pane kind in the trail codec.
- On save, the room re-reads the doc live (focused-live policy) and the trail is
  unchanged. A fresh-create flow lands the new doc as the focused pane.
- This keeps the trail format (decision 14) clean — agents still only mint/parse
  reading trails, never draft state.

### D3. Metadata as separate form fields — RECOMMEND (and it's load-bearing)

The single most important UX rule, given the frontmatter-fence bug history:
title / tags / importance are **dedicated form inputs** that map to the
`mark_publish` `metadata` object. The body field is markdown only. The desk must
make it *structurally impossible* to hand-author a `---` fence into the body:
- Title → `metadata.title` (or the body H1 — pick one and be consistent).
- Tags → a tag input → `metadata.tags`; the **status axis** (`status:draft|wip|
  accepted|archived`) is a tag, surfaced as a status picker that writes
  `status:<v>` so the badge round-trips.
- Importance → a 0–1 control → `metadata.importance`.
- Satisfy the write gate before submit (client-side hint + server is the
  authority).

### D4. Create vs edit vs append + optimistic concurrency — RECOMMEND

- **Edit** fetches the current doc (body + version), the editor carries the
  `version`/etag, and submit sends `expected_version`. On conflict, surface the
  broker's merge candidate for the human to resolve, then re-submit at the
  returned publish-at-version — never blind-overwrite (the silent-loss trap the
  merge flow exists to prevent).
- **Create** is `expected_version: 0`; the new path lands as the focused pane.
- **Append** (`mark_append`) is a lighter affordance for adding to a log/journal
  doc; remind that it can't change tags, so a new-subject append nudges a
  re-publish.

### D5. Write authorization — DEPENDS ON / COORDINATE WITH Phase 2

Reads are tokenless; today *who may write* is only bounded by the world-level
`AllowConfig` (SSO gate) + the write token's path globs. Surfacing editing to
every SSO-authed reader is probably too open. The "who can edit which paths"
question is the **write-side twin of Phase 2's read collections** — design them
together (reuse the `AllowConfig`-per-glob shape). At minimum, the room must only
show the edit affordance where the identity can actually write, and degrade
gracefully (broker rejects → the desk says "not permitted to write here," not a
generic error).

## Library work (the bulk)

1. **Outbound port:** `WorldGateway` grows write verbs — `Publish(ctx, world,
   path, body, meta, expectedVersion)` and `Append(ctx, world, path, body)` —
   implemented by the broker MCP adapter (calls `mark_publish`/`mark_append`
   with the reader's bearer; the broker maps to the per-world write token). QUIC
   adapter implements them too (direct token) or returns not-supported.
2. **Inbound port / service:** an `Edit`/`Create`/`Append` use case + a
   `Preview` render (reuse the existing renderer). Service owns validation
   shaping; web owns the form.
3. **Web:** edit-mode template (textarea + metadata fields + live preview
   target), `POST` handlers (`/w/:world/edit/*`, `/w/:world/new`, append),
   conflict UI, margin "edit" affordance on doc panes (only when writable).
   Invalidate the rendered-document cache for the written (world,path,version)
   on success so the re-read shows fresh content.
4. **Agent symmetry (decision 11/12):** every desk affordance ⇄ the `mark_*`
   write channel; the protocol escape already shows `mark://` + raw source.

## Broker work (small, if any)

- Likely none for the basic flow — `mark_publish`/`mark_append` + first-write
  token provisioning already exist. IF D5 lands write-collections, that's broker
  config + enforcement (shared with Phase 2).
- Confirm the write gate severity for the cluster (warn vs block) so the desk's
  client-side hinting matches.

## Acceptance (both transports — ADR 0005 decision 16)

- Broker mode: an authorized identity edits a doc — preview matches the read
  render; save publishes with metadata out of band (no `---` in the stored body);
  status picker round-trips the badge; a stale edit hits the merge flow, not
  silent loss; an unauthorized write shows a clear "not permitted," and the edit
  affordance is hidden where the identity can't write.
- QUIC mode: with a write token configured, the same flow works directly; without
  one, the desk is read-only (affordance absent) — honest degradation.

## Scope / non-goals

- Markdown source editing only — no WYSIWYG, no rich-text, no comments/reactions.
- No media upload (the universe is markdown-native, no hosted media).
- Write authz beyond "affordance gated on writability" is Phase 2-coupled (D5).
- Bulk/CLI authoring stays the agent's job (the desk is the human projection).

## Build order

1. Settle D1–D5 with Fritz (esp. D1 surface and D5 authz coupling).
2. Outbound write verbs + broker adapter (smallest end-to-end: create a doc).
3. Service use cases + live preview fragment.
4. Edit-mode UI: textarea + metadata fields + preview + status picker.
5. Conflict/merge flow + cache invalidation on write.
6. Edit affordance gating (writability) + not-permitted UX.
7. Acceptance both transports; update the authoring contract
   (`/.well-known/library/authoring.md`) if the desk changes any conventions.

## Dependencies / risks

- **First write path through the library** — the read-only invariant that has
  simplified everything (cacheable, idempotent) ends here; treat write
  idempotency, cache invalidation, and conflict handling as first-class.
- **Frontmatter-fence trap** (D3): the desk must make in-band metadata
  structurally impossible, or it will reproduce the exact bug R1 was built to
  paper over.
- **Authz coupling** (D5): don't ship an open write surface — coordinate with
  Phase 2 so read-collections and write-permissions share one model.
- Needs the broker repo only if D5 write-collections are in scope; the basic
  desk is library-only.