The 2-minute picture
You and Claude are building an operations brain.
Initiation HQ is a private web app that turns the messy raw material of your work — meeting recordings, notes, spreadsheets — into a clean, trustworthy picture of your actions, decisions, commitments, risks and relationships. This guide explains how it's put together, and quietly translates every bit of jargon along the way.
There's really only one idea to hold in your head. Everything else is a detail hanging off it.
Nothing writes itself into your live data. When Claude reads a transcript, or a spreadsheet gets imported, or a duplicate is spotted — the result is only ever a proposal sitting in a review queue called Triage. It becomes real only when you press Apply. The AI drafts; you sign off. This is the review-queue gate, and it's the safety rail the whole system is built around.
Why build it this way?
Because an assistant that silently edits your records is worse than no assistant at all — you'd never fully trust it. By forcing every change to pause for your approval, HQ can be bold about suggesting things (extract everything, spot every duplicate, flag every risk) while staying safe, because the worst it can ever do is put a bad suggestion in front of you to reject.
The two hands that build it
🛠️ The Code side
Where the software is written and shipped — the dashboard, the behind-the-scenes logic, the database shape. Tracked with git and published to the web with a couple of commands. Think: the workshop.
💬 The Cowork side
Where the content is curated — cleaning up transcripts, shaping the CRM, writing strategy. No code. Think: the editorial desk. A small tool, hq.mjs, lets either side post changes into HQ.
What's in this guide
- The pieces — the four building blocks (your browser, Cloudflare, the database, Claude) in plain terms.
- The loop — an animated walk-through of how a meeting becomes a tracked action.
- The app — a tour of every screen, and the 12 kinds of record HQ keeps.
- Using it — the daily rhythm and the practical how-to for each part.
- How we build — the phase-by-phase method, the tools, and how a change reaches the live site.
- Under the hood — the back-office functions, the security model, and how the AI bill is kept tiny.
- If it breaks — the handful of things that go wrong, why, and the fix. Plus an FAQ.
- Glossary — every technical term, searchable, in one place.
The pieces
Four building blocks
HQ is a stack of four cooperating parts. Data flows down when you ask for something and back up when you get an answer. Tap each layer to open it up.
The path a request takes
Put the four pieces in motion and this is the route every request travels. Two things to notice: the dashboard only ever talks to the back office (never the database), and automated updates from Cowork or the Code tab reach the back office directly with a service token — no browser needed.
Capture sources (Plaud, Teams, CSV, typed notes) also enter through the Functions and land in the transcripts table, ready for the loop.
The loop
How a meeting becomes a tracked action
This is the signature move of Initiation HQ. Watch the dot travel the line, then tap any stop to see what happens there.
Steps 1–4 all happen before anything is real. The AI can read, draft and suggest as freely as it likes — it's all just sitting in the queue. Only step 5, Apply, which only you can press, writes to your live records. The same gate catches everything: typed quick-captures, spreadsheet imports, duplicate-spotting, even a new priority the system thinks it found.
Two clever safety details
🧠 It knows fact from guess
When Claude reads a transcript it labels each item as stated (someone actually said it) or inferred (a reasonable read between the lines), following a fixed rubric. You see which is which before approving.
🛟 It can't overwrite you
If you're editing on your phone while a background job tries to change the same record, the second one is politely refused and told to re-read the latest version first. That's the revision guard — it prevents silent data loss.
The app
Every screen, and everything it remembers
The screens
One app, many views — you switch between them from the top bar. Tap a card to expand what it's for.
The 12 kinds of record
Under the surface, everything in HQ is one of these record types. Each stores a specific kind of thing and links to the others. Tap to see the fields it keeps.
How it all connects — "entity-360"
The magic isn't the records — it's the wiring between them. Two rules do most of the work: everything remembers its source, and everything hangs off a person. Click a name, a priority or a workstream and HQ shows you everything tied to it. That's what the Connections view is.
🧾 Source traceability
Every action, decision, commitment and risk carries a transcript id. You can always ask "where did this come from?" and land on the exact meeting — often the exact quote.
🧍 People at the centre
Decisions are made by people; commitments bind two people; risks have an owner. The CRM is the hub the rest of the data radiates from.
🧵 Workstream roll-up
Tag a record with a workstream and you can flip between "what's on this action?" and "show me everything on the Metrolink mobilisation".
🔗 Sequences & projects
Actions and tasks can chain in order or group as a project. A commitment that becomes an action cross-links the two, so nothing floats orphaned.
Using it
Running HQ day-to-day
You've seen the screens and the machinery. This is how you actually work it — the daily rhythm, then the practical how-to for each part.
Capture freely, process in batches, clear the queue, Apply. Everything else is optional polish on top of that loop.
The daily rhythm
- Capture — upload transcripts & notes, or jot straight into Triage.
- Process a batch (cheaper, and cleaner to review together).
- Clear the queue — group by recording, fix any chip the app guessed wrong, set dues & reminders, merge duplicates.
- Approve & Apply — the live register moves forward, fully traced to its source.
- Work the day from Hybrid or the boards; let Reminders surface what's due.
- Use Connections whenever you need the whole picture on a person or workstream.
The how-to, part by part
Tap any area to open its practical guide.
How we build
Small phases, always shippable
The road so far
HQ isn't built in one big go. It grows one phase at a time — each adds a single capability, gets tested live, and is backed up before the next begins.
A selection of the ~35 phases. Green = live, amber = in progress, grey = ahead of us.
Two kinds of change, two lifecycles
Confusingly, "change" means two different things in HQ, and they travel completely different roads. Getting this distinction is the key to understanding how it's built.
🧱 Changing the software
A new button, a new view, a bug fix. This is the Code side.
- Edit the files on the machine at
C:\HQ - Sanity-check them (
node --check) - Deploy to the web with Wrangler
- Check it works live at hq.thekms.uk
- Save a snapshot in git (a commit)
- Back up the whole folder to OneDrive
📇 Changing the data
Adding or editing the actual records. This is the loop.
- Something is captured or extracted
- It becomes a proposal in Triage
- You review — edit, approve, reject, route
- You press Apply
- It merges into the live records
- Every screen updates to show it
The tools that do the work
A handful of small scripts automate the repetitive jobs — posting updates, making backups, importing dates, generating Word/Excel files.
The repo, folder by folder
Everything lives in one folder — the repo — at C:\HQ. Here's what's inside.
The safety rails, all in one place
- Local-first history. The full change history lives in git on your machine only — no third-party like GitHub. A robocopy backup to OneDrive after each phase is the second copy.
- Secrets never travel in the code. API keys and passwords live in ignored files (secrets), set directly on Cloudflare — never written into the repo.
- Only one key can write to the database. The service key is held only by the back office, never handed to a browser.
- Every phase gets a snapshot. A copy of the dashboard is frozen per phase in
_phase-snapshots/so the progression is never lost. - The review-queue gate. Above all — no data change reaches "live" without your Apply.
Under the hood
The back office in detail
The endpoints
The dashboard never touches the database itself. Instead it asks the back office through named endpoints — each a single web address doing one job. Search them below.
| Route | Type | What it does |
|---|
The shared libraries
The endpoints lean on a set of shared helper files (their names start with an underscore, meaning "internal — not a web address"). This is where the real cleverness lives.
The security model
HQ holds sensitive work data, so it's locked down at several layers. In plain terms:
Keeping the AI bill tiny
Running an AI over hundreds of transcripts could get expensive fast. HQ uses several tricks to keep it cheap — often free.
If it breaks
The handful of things that go wrong
A system this size has a small set of classic failure modes. Each has a clear cause and a known fix — so nothing here is a mystery.
Quick questions
Glossary