Operator guide

This section is for the human running Ticket Board day to day: the person who creates projects, drafts wiki pages, manages the bots, and looks at the audit log when something goes sideways. It assumes the stack is already up and you can log in — see Getting started if not.

Ticket Board is a single-operator tool. There is exactly one human user, an arbitrary number of bots, and one workspace. Everything in this guide is scoped to that workspace.

What you actually do here

Day-to-day work falls into a small handful of surfaces:

Surface	What you use it for	Where to read
Projects	Containers for work. Each has its own workflow states and labels.	Projects
Tickets & boards	The unit of work: epic, story, or subtask. Lives on a swim-lane board.	Tickets & boards
Wiki	Long-form notes with [[wikilinks]] and backlinks. Obsidian-style.	Wiki
Sticky notes	Quick capture. Convert to a ticket when an idea sticks.	Sticky notes
Bots	First-class identities with their own tokens, project allowlist, and read/write mode.	Bots
Webhooks	Outbound HMAC-signed event delivery to external receivers.	Webhooks
Audit log	Append-only record of every write. The activity feed is a filtered projection of it.	Audit log
Troubleshooting	Top issues with the exact log greps and fixes.	Troubleshooting

How the surfaces fit together

flowchart LR
    YOU[Operator] -->|browser| UI[Web UI]
    BOT[Bot client] -->|MCP or X-API-Key| API[REST + MCP]
    UI -->|fetch JSON| API
    API --> SVC[Service layer]
    SVC --> DB[(Postgres)]
    SVC --> EVT[Event emitter]
    EVT --> AUD[(audit_event)]
    EVT --> WH[Webhook deliveries]
    WH -->|HMAC-signed POST| EXT[External receivers]

A handful of properties hold across every surface:

• One service layer. A human PATCHing a ticket and a bot calling update_ticket over MCP both go through the same service function. The same authorization checks fire. The same audit event lands.
• Every write is attributed. No anonymous mutations. System sweepers record themselves as actor_kind='system'.
• Bots are scoped twice. A project_allowlist (what they can see) and a read/write mode (what they can do). The two dimensions are independent.
• The audit log is the security log. Logins, token rotations, and tool calls all land in the same audit_event table as ticket transitions and wiki edits.

Working assumptions

Throughout this section:

• "The operator" means you — the lone human with a session cookie. Bots never read these docs.
• URLs are written as if you are at http://localhost (the default Docker Compose origin). In production replace with your actual host.
• The shell examples assume the Compose stack is running and you have .env loaded into your shell or are running make targets from the repo root.

What this section does not cover

• Deploying the stack: see Deployment.
• API or MCP contracts at wire level: see API & MCP.
• Why decisions were made the way they were: see Architecture decisions.

Reading order

If you've never touched Ticket Board before, read in this order:

1. Projects — the container for everything else.
2. Tickets & boards — the daily-driver surface.
3. Wiki and Sticky notes — capture and reference.
4. Bots — when you're ready to bring an AI workforce in.
5. Webhooks — when you need to fan events out to something else.
6. Audit log — the receipts.
7. Troubleshooting — when something looks wrong.