# Bootstrap — get your consulting vault running

> **If you're a person reading this: you don't need to do anything here.** Paste
> the "Start here" prompt from the README into Claude Code and follow what Claude
> asks. Claude does the technical parts; you only ever click in your web browser
> when asked.

## What's about to happen (so nothing is a surprise)

Claude will, with your permission at each step:
1. Install a few small, free tools (Homebrew, plus `gh`, `jq`, `doppler`) and the
   **Tolaria** app. The first install may ask for **your Mac password once** and
   pop up **Apple's "command line tools" installer** — that's normal, not an error.
2. Help you sign in to **GitHub** (free) and **Doppler** (free) — both happen in
   your **web browser**, never in a black Terminal window.
3. Create your **private** business workspace (only you can see it) and put a copy
   on your Mac.

Nothing else leaves your machine. Your billing runs locally; secrets live in
Doppler, never in files. You will not type a single git command.

---

## For Claude: runbook for bootstrapping a non-developer who has ONLY Claude Code

The user has Claude Code and likely **nothing else** — possibly no GitHub or
Doppler account, no `gh`/`jq`/`doppler`, no Tolaria, no copy of this repo — and
has **never used git**. Hard rules:

- **Never show git jargon.** Say "your private workspace" not "repo", "save
  online" not "push", "copy onto your Mac" not "clone".
- **Never send the user into Terminal.** You are their terminal. They only ever
  act in a web browser, and only when you hand them a link via **AskUserQuestion**.
- Do each technical step yourself; say one plain sentence first about what and why.
- **Verify each step functionally before moving on** — presence on PATH is not
  proof a tool works (check versions / run the real command).
- **If an install fails** (managed/work Mac, no admin rights, blocked network):
  do NOT loop or pretend success. Tell the user plainly and give them a copy-paste
  message for their IT team (see Step 1). Stalling silently is the worst outcome.

Re-runnable: skip anything already done.

### Step 1 — Install the free tools
Say: "I'm installing a few small free tools. You may be asked for your Mac
password once and to approve an Apple installer — that's expected."
- Homebrew: `command -v brew`. If missing, install via the official script at
  https://brew.sh. If the install **fails** (no admin / MDM / proxy), stop and
  tell the user: *"Your Mac blocks new software installs. Send your IT team this:
  'Please install Homebrew, gh, jq, doppler, uv, pango, and the Tolaria app.'
  Then come back."*
- Tools: `brew install gh jq doppler uv pango` and `brew install --cask tolaria`.
  (`uv` + `pango` are for turning invoices/proposals into PDFs.)
- Verify functionally: `gh --version` (need 2.x — if older, `brew upgrade gh`),
  `jq --version`, `doppler --version`, `ls /Applications/Tolaria.app`. A tool that
  is present but errors is BROKEN — reinstall it, don't treat it as done.

### Step 2 — Connect GitHub (browser only — never Terminal)
Say: "GitHub safely backs up your business online. It's free and we'll do this in
your browser."
- `gh auth status` — if already signed in, skip to Step 3.
- No account yet? AskUserQuestion with https://github.com/signup ("Create a free
  account, then tell me you're done").
- Sign in **without sending them to Terminal**: start the browser device flow
  yourself and relay the code. Run, in the background,
  `printf '\n' | gh auth login --hostname github.com --git-protocol https --web`.
  It prints a one-time code (format `XXXX-XXXX`) and opens https://github.com/login/device.
  Read the code from its output and give the user, via AskUserQuestion, the code
  and that URL: "Enter this code in the page that opened and click Authorize, then
  tell me when done." Then confirm with `gh auth status`.
- If the device flow can't run in this environment, as a LAST resort walk them
  through it click-by-click — but the default is browser-only, Claude-driven.

### Step 3 — Create their private workspace (you run git; they never see it)
- Pick a name with them (default `my-firm`).
- Check for organisations: `gh api user/orgs --jq '.[].login'`. If any exist, ask
  (AskUserQuestion) whether this is for them personally or a business/org, and use
  that owner. Default to their personal account.
- Run: `gh repo create <owner>/<name> --template hudgeon/consulting-vault-template --private --clone`
  (omit `<owner>/` for personal). Then `cd <name>`.
- Say: "Done — I've created your private business workspace and put a copy on your
  Mac at <full path>."

### Step 4 — Hand off to setup
You're inside the vault now.
- Run `bash scripts/check.sh --json`, read the JSON, and tell the user the status
  in plain words (never paste the raw output to a non-technical user).
- Then follow `.claude/skills/setup/SKILL.md` from Step 3 onward (tools + GitHub
  are done). That covers Doppler sign-in, the billing interview (writes `firm.md`),
  and seeding their clients.
- Mention they can restart Claude Code in the new folder and type `/setup` anytime.

### Confirm they're correctly set up
Verify and state each in plain words:
1. `gh auth status` → "Your GitHub is connected."
2. `bash scripts/check.sh` reports Ready (no items needing attention).
3. `/Applications/Tolaria.app` exists → open it (`open -a Tolaria`), reveal the
   folder (`open <full path>`), and say: "In Tolaria, choose **Open Vault** and
   pick this folder — that's your business, ready to edit."
4. A sample invoice generates: `python3 scripts/billing/generate_invoice.py acme-co`
   → "Billing works end to end."
Only call setup complete when all four pass.