# Writing Station × AI — agent instructions

Machine-readable twin of https://writingstation.rocketrepublic.com/ai

Writing Station is a local-first macOS writing studio over a plain-markdown vault.
Agents file notes into it through ONE engine with a hard contract:

## The contract

1. TWO STEPS, ALWAYS. `propose` validates and returns a preview + a 30-minute token;
   only `commit <token>` writes. Show the human the preview (destination, type, tags,
   people, refs) and commit ONLY on their explicit yes. If they don't agree, adjust and
   propose again — keep suggesting until agreement. Unconfirmed proposals expire; that
   is correct behavior.
2. TAGS BELONG TO THE HUMAN. Choose only from `list_tags` (call it fresh each session).
   Never invent a tag. If nothing fits, file untagged and say so — tags are added in
   Writing Station → Settings → Tags by the human.
3. PEOPLE ARE CANONICAL. `Last, First` ("Luther, Martin", never "Martin Luther").
   Check `list_people` first; reuse existing spellings; relay near-duplicate warnings.
4. FIVE TYPES (folder-decided, fixed): `snip` = captured quote/excerpt · `idea` = the
   human's own thought · `book` = a book record · `person` = a bio hub that REPRESENTS
   someone (a mere mention is NOT a person note) · `general` = everything else.
5. SCRIPTURE REFS like "John 1:1-5" or "Romans 8" power the Bible filter; invalid refs
   are rejected.
6. ADD-ONLY. Never overwrite, move, rename, or delete anything in the vault. Never
   write sidecar files (`.heristand-*.json`).

Filters/indexes are computed from note content automatically — nothing to register.

## Requirements

- macOS with Writing Station installed and a vault chosen (tools read the vault path
  from the app's settings; override with `WS_VAULT=/path/to/vault`).
- The Writing Station toolkit repo on that Mac, `node 22+`, `pnpm install` run once.

## CLI (from the toolkit repo; add --json for machine output)

    pnpm -s ws-note types
    pnpm -s ws-note tags
    pnpm -s ws-note people
    pnpm -s ws-note propose --type snip --title "Grace upon grace" \
      --tags "Quotes" --people "Edwards, Jonathan" --refs "John 1:16" \
      --source "Religious Affections" --body "Of his fullness we have all received."
    # → preview + token
    pnpm -s ws-note commit <token>       # only after the human agrees
    pnpm -s ws-note proposals            # pending proposals

Body alternatives: `--file note.md` or stdin. People are `;`-separated (names contain
commas). `--page` must be a positive integer.

## MCP (server: writing-station-notes, stdio)

Tools: `list_types` · `list_tags` · `list_people` · `list_proposals` · `propose_note` ·
`commit_note`.

- Claude Code: auto-registered when the session starts inside the toolkit repo
  (`.mcp.json`). Elsewhere:
  `claude mcp add writing-station-notes -- npx tsx /path/to/repo/tools/notewriter/mcp.mts`
- Claude Desktop / any stdio MCP client:

      {
        "mcpServers": {
          "writing-station-notes": {
            "command": "npx",
            "args": ["tsx", "/path/to/repo/tools/notewriter/mcp.mts"]
          }
        }
      }

## Errors you may see (all intentional)

- "No vault found" → open Writing Station once and pick a vault, or set WS_VAULT.
- "Tag … is not in the vocabulary" → pick from the list; the human adds new tags in-app.
- "That proposal expired" → propose again so the human sees a current preview.

The library stays the human's. The agent is a very careful librarian.