[Gastown] PR 25: Documentation & API Reference

[jrf0110]

Parent: #204 | Phase 4: Hardening

Revised: Documentation now covers container architecture and control server API in addition to DO schemas and tool plugin.

Goal

Comprehensive documentation for internal developers and external users.

Internal Documentation

• Architecture overview (DOs, workers, Town Container, control server, tool plugin)
• Container control server API reference (start/stop/status/health/merge endpoints)
• DO state schemas (Rig DO, Town DO, Agent Identity DO SQLite schemas)
• Tool plugin API reference (all gt_* tools with input/output schemas)
• System prompt templates (polecat, refinery, mayor)
• Auth flow (JWT minting, internal vs agent auth)
• Container resilience model (checkpoint/restore, ephemeral disk recovery)
• Escalation and convoy lifecycle diagrams

External Documentation

• User guide for hosted Gastown
• Getting started (create town, connect repo, sling first bead)
• Concepts (towns, rigs, beads, agents, convoys, molecules)
• Configuration reference (rig config, quality gates, escalation thresholds)

Dependencies

• All previous PRs

Acceptance Criteria

• Architecture doc with diagrams (including container model)
• Container control server API reference
• DO schema reference
• Tool plugin API reference
• User guide
• Configuration reference