wanderlog-mcp: Instructions file for Claude Code

Wanderdog — agent instructions

Wanderdog is an MCP server that exposes Wanderlog trip editing to LLM agents. TypeScript, stdio transport, cookie-based auth.

Read before making changes

In order:

1. docs/north-star.md — goals, non-goals, success criteria
2. docs/architecture.md — file layout, runtime flow, and the invariants you must not violate
3. docs/kanban.md — current status and what's next
4. docs/gotchas.md — landmines we've already hit; read this before you think "it should be easy"
5. docs/api-reference.md — reverse-engineered Wanderlog protocol (consult as needed)

Keep the kanban in sync

docs/kanban.md is the source of truth for project status. Update it as you work:

• Before starting a task: move it from Todo to Doing (🚧). If the task isn't in the board yet, add it in the right phase before starting.
• While working: if you discover follow-up tasks, bugs, or scope changes, add them to the appropriate phase's Todo section.
• When completing a task: move it to Done (✅) with a short note — one sentence on what shipped, optionally referencing the commit or file.
• When finishing a phase: update the phase status marker at the top and flip the section header (📍 → ✅).
• Status markers: ✅ done · 🚧 in progress · 📍 next · ⏸️ planned · ❌ dropped. Stick to these.

Diffs to docs/kanban.md should be small and visible in git log. If you make a large change to the board, include it in a dedicated commit with a message like kanban: mark phase 2 mutation tools complete.

Invariants (from docs/architecture.md — do not violate)

1. Never assume block shape. Real trips contain place, note, flight, train, and unknown types. Always discriminate on block.type with a fallback.
2. Never expose raw IDs (place_id, section indices, ShareDB paths) to the LLM by default. Use natural references.
3. Every REST response is {success, payload}. Always unwrap.
4. Startup must surface auth errors clearly. The server stays alive (for hosting platform health checks) but every tool returns an auth-required error until valid credentials are provided.
5. Cookie value must never appear in tool responses, logs, or error messages.
6. Section indices are not stable across edits. Always resolve by date/heading/type from a fresh snapshot.
7. Natural language in, natural language out — the LLM shouldn't need to touch ShareDB paths or ChIJ... place_ids.
8. All mutations go through submitOp in src/tools/shared.ts. That helper holds the per-trip mutex, wraps the submit in try/catch, and invalidates the cache on failure. Do NOT call ShareDBClient.submit() directly from a tool — it bypasses parallel-safety and cache-consistency guarantees.
9. Failed submits must invalidate the cache (tripCache.invalidate(tripKey)) so the next read refetches a fresh snapshot.
10. Error frames in ShareDBClient.handleFrame must be matched by seq first; only fall back to failAllPending when the error can't be attributed. One op's error must not kill unrelated in-flight ops.