Runbooks

Runbooks are the unit of re-usable support knowledge. Structured fields, semantic matching, one-click save from closed cases.

Structure

A runbook is a note with noteType = "runbook" and a structured runbookMeta object:

{
  symptoms: ["customer can't log in", "401 after 2FA", ...],
  preconditions: "Customer is on a paid plan.",
  steps: [
    "Confirm email address.",
    "Check account lock status.",
    "Verify 2FA device is registered.",
    ...
  ],
  resolution: "Customer logs in successfully.",
  tags: ["auth", "2fa"]
}

The symptoms field is the search key — it's what semantic search matches against when a new case opens. Put the exact phrases customers and agents actually use, one per entry.

Creating a runbook

Three ways:

1. From scratch at /runbooks. Fill in the structured fields directly, or click "Open full editor" to use the rich TipTap editor for body content.
2. From a template. The "Support Runbook" template at /notes/new?template=support-runbook creates a pre-structured note ready to fill.
3. From a solved case. On the case detail view, click "Save as runbook" — Claude drafts the runbook from the case's title, description, activity timeline, and linked-note content. Review, edit, save.

How matching works

When a case opens, Momentum queries /api/runbooks/suggest against the note embeddings table, restricted to runbook-type notes in the current workspace.

Two signals combine:

• Cosine similarity over embeddings of the case description vs. runbook content
• Symptom-token overlap — heuristic bonus when case text contains tokens from a runbook's symptoms list

Results are grouped by note (MAX across chunks), ranked, and top 3 are returned with match percentages and the specific symptom quote that matched best.

Maintenance

Three habits keep runbooks healthy:

1. Save as runbook on every closed case with a non-obvious fix. Two minutes per save.
2. Review the least-opened 20 once a quarter. Archive or rewrite them.
3. Add to symptoms every time you see a new phrasing for an existing problem. The symptom list is the search key.

Seeded runbooks

Every new workspace is auto-seeded with five generic support runbooks:

• Customer can't log in
• Data sync is stuck or delayed
• Permission denied / access errors
• Attachment or file upload fails
• Notifications aren't arriving

These are live examples, not placeholders. Customize them to your product and they'll become real workflow tools.