Setup

---
name: setup
description: Run the HQ Starter Kit setup wizard.
allowed-tools: Read, Write, Edit, AskUserQuestion, Glob, Bash, Task, WebFetch, WebSearch, Skill, mcp__Claude_in_Chrome__*
---

# HQ Setup Wizard

Get your HQ running: dependencies, HQ Cloud (login + sync), a profile built from
who you are, and a private welcome page that hands you your first moves. One
question at a time; nothing here is mandatory — skip anything and setup still
completes.

## Guided mode (HQ Desktop): `--guided`

HQ Desktop runs this skill inside its #welcome channel as a native, stepped
card — not as a chat. It starts the session with `/setup --guided`. When the
arguments contain `--guided`:

- **Emit a step marker at every phase boundary**, on its own line, exactly:
  `[hq-setup] step=<id> status=<running|done>`. The ids, in order, and the
  phases they cover:

  | step      | phases                                   |
  |-----------|------------------------------------------|
  | `tools`   | 0a, 0b                                   |
  | `cloud`   | 0c                                       |
  | `import`  | 0d (adopt prior AI footprint)            |
  | `you`     | 1, 1.5, 2, 3, 4, 4.5, 5a, 5b             |
  | `connect` | 5b.5 (secrets), 5b.6 (apps)              |
  | `moves`   | 5c, 5d, 5e, 5f, 6                        |

  Emit `status=running` when a phase group starts and `status=done` when it
  ends. Never go backwards; skipping a whole group is fine — mark it `done`.
- **Emit a card marker right before the question it belongs to**, on its own
  line: `[hq-setup] card=<one-line JSON>`. The desktop draws the card in place
  of the plain option list and answers the *same* AskUserQuestion. Three kinds:
  - `{"kind":"found","title":"…","items":[{"label":"…","count":12,"detail":"…"}]}`
    — "Here's what I found", paired with the Import question (0d).
  - `{"kind":"secret","name":"DATABASE_URL","label":"…","hint":"…","scope":"personal|company","company":"<slug>"}`
    — one credential; the desktop stores it straight into the vault and
    answers `Done`. Paired with a `header: "Secret"` question with options
    `Done` / `Skip` (5b.5). **In guided mode do not mint a `generate-link`
    URL** — the card is the intake.
  - `{"kind":"integrations","items":[{"id":"<entryId>","name":"…","description":"…","auth":"oauth|none","status":"connected|available"}]}`
    — app tiles, paired with a multi-select `header: "Integrations"` question
    whose option labels are the app names plus `Skip for now` (5b.6).
- **Two ways to ask, and only two.** A choice (2–4 options) is one
  AskUserQuestion call. A fill-in-the-blank (name, what you do, goals,
  challenges, systems of record, role, typical day, a URL) is asked in plain
  words as the **last line of the message, in bold, ending with a question
  mark** — one question per message, then stop and wait; the person types
  the answer in the chat. Never bundle several questions into one message,
  never number them, and never ask a fill-in-the-blank through AskUserQuestion
  (the runtime needs real options; a fake "Skip" option is not a question).
- **Speak only to the person, never about the mechanics.** The desktop shows
  your words as a "Setup Agent" chat. Do not mention pickers, tools,
  AskUserQuestion, markers, phases, modes, "the desktop", or why you are
  asking a question one way rather than another ("that one's a
  fill-in-the-blank, so I'll ask it straight" is exactly what not to say).
  Say what you are doing for them and ask the question — nothing else.
- **Markers are plain lines, never in backticks or code fences**, one per
  line, at the start of the message. A marker line is never the whole message
  — put a one-sentence plain status beside it so the card has something to say.
- One question at a time, plain words. The finish: emit
  `[hq-setup] step=moves status=done` on its own line, then the closing
  summary in ordinary Markdown (headings, bullets), not a code block.
- Without `--guided` (a terminal), emit no markers and no cards, and use the
  terminal flows described in each phase (e.g. the secret link in 5b.5).

## Phase 0a: Install Manifest Recovery

*(guided: `[hq-setup] step=tools status=running`)*

Before anything else, check if the HQ Installer left a manifest. HQ Desktop
writes it to the USER'S home (`~/.hq/install-manifest.json`); older installers
wrote it inside the HQ folder. Check both — reading only `.hq/` inside HQ made
`/setup` believe nothing was installed and re-run `npm install -g` with the
system npm on every run (prefix conflicts, permission errors, supply-chain
block; reported 2026-08-28).

```bash
cat ~/.hq/install-manifest.json 2>/dev/null || cat .hq/install-manifest.json 2>/dev/null
```

Then, BEFORE declaring any dependency missing, put HQ's managed toolchain on
PATH for this session — the installer puts tools there, and a GUI-launched or
hook-launched shell often does not see them:

```bash
export PATH="$HOME/Library/Application Support/Indigo HQ/toolchain/node/bin:$HOME/Library/Application Support/Indigo HQ/toolchain/npm-global/bin:$HOME/Library/Application Support/Indigo HQ/toolchain/git-shim:$HOME/.local/bin:$PATH"
for t in node npm qmd hq git yq jq; do printf '%-5s %s\n' "$t" "$(command -v $t || echo MISSING)"; done
```

Newer manifests record the dependency stage only as `steps.deps` (the
`dependencies` map is empty); use the PATH check above as the source of truth
for what is actually present. On a Mac without Xcode Command Line Tools,
`/usr/bin/git` and `/usr/bin/python3` are stubs that pop an install dialog —
never call them; the managed `git-shim` is the real git.

If no manifest exists, skip to Phase 0b — the user installed manually or is running setup for the first time.

If a manifest exists, this phase becomes the primary driver of setup. The manifest is a journal of everything the installer attempted — successes, failures, and skips. Your job is to triage and actively remediate each issue, not just list them.

### Triage priority (handle in this order)

**P0 — Blocking (fix these first, setup can't proceed without them):**
- `steps.directory` failed or missing → HQ directory doesn't exist; abort setup and tell user to re-run installer
- `steps.templates` failed → HQ template not fetched; attempt `npx --package=@indigoai-us/hq-cli hq init .`
- `dependencies.node` failed → nothing works; guide user through Node install
- `steps.git-init` failed → no git repo; run `git init && git add . && git commit -m "init"`

**P1 — Required (HQ works poorly without these):**
- `dependencies.qmd` failed → no semantic search; install the SANCTIONED pin (see `core/scripts/install-deps.allow`): `npm install -g @tobilu/qmd@2.5.3`, then `qmd index .`. Unpinned installs are blocked by the supply-chain guard on purpose.
- `dependencies.claude-code` failed → can't run workers; `npm install -g @anthropic-ai/claude-code@<version>` (explicit version pin required by the guard)
- `dependencies.yq` failed → can't parse YAML configs; `brew install yq` or download binary
- `dependencies.hq-cli` failed → can't install packs or sync; `npm install -g @indigoai-us/hq-cli@<version>` (explicit version pin required by the guard)
- `steps.indexing` failed → search won't work; run `qmd index .` directly
- `packs` with status `"failed"` or `"running"` (interrupted) → retry each: `npx --package=@indigoai-us/hq-cli hq install {pack-name}`

**P2 — Recommended (HQ works but some features limited):**
- `dependencies.gh` failed/skipped → no PR workflows; install directly: `brew install gh` (then `gh auth login` — the browser auth is the one warranted prompt)
- `dependencies.homebrew` skipped → limits future installs; install directly (best-effort; skip silently if the platform install can't run unattended)
- `steps.personalize` failed → profile not set up; Phase 1 below will cover this

### Remediation flow

**Install missing dependencies and CLI tools directly — never ask whether to
install them, and never surface an "install all / install some / skip all"
picker.** A user running `/setup` has already opted into getting HQ working; a
mid-setup "do you want these tools?" question is pure friction. The install
commands in the triage lists above are safe, idempotent, and non-blocking — just
run them. This includes P2 items (`gh`, `homebrew`): install them directly too.

For each issue found (in priority order):

1. **Install it directly, silently.** Run the item's install command (from the
   triage lists above), best-effort. Do not pause for permission, do not
   explain-then-ask, and do not offer install-method choices — pick the standard
   method and run it.
2. **After each fix: verify.** Run `command -v {tool}` AND `{tool} --version` (a path alone is not proof — stubs and broken shims exist). If it worked,
   move on without narrating it. If it failed, try one alternative, then record
   it under "Still needs attention" in the summary and keep going — never block
   setup on a failed optional tool.
3. **The only permitted prompt in this phase is a genuine interactive auth** that
   cannot run unattended (e.g. `gh auth login`, which opens a browser).
   *Installing* a tool is never that case — installs are always direct.
4. **Bootstrap dependencies are the one install exception.** A P0 that cannot be
   installed unattended from within setup — Node itself (nothing runs without it,
   and there is no npm to install it with), or a platform package manager on a
   machine that has none (e.g. Homebrew on a bare macOS) — falls back to *guiding*
   the user through that one install, per its triage entry. This is not the
   tool-choice picker the rule forbids; it is the narrow "we literally cannot do
   this for you" case. Everything installable via npm / an existing package
   manager still installs directly, no prompt.

### After remediation

Once all issues are addressed, show a summary:

```
Install recovery complete.

Fixed:
  ✓ {item} — {what was done}
  ...

Skipped (optional):
  ○ {item} — {why it's optional}
  ...

Still needs attention:
  ✗ {item} — {what went wrong, what user can do}
  ...
```

Skip items already `"ok"` in the manifest — don't re-check things the installer already handled successfully. Then continue to Phase 0b only for auth state the manifest doesn't cover.

## Phase 0b: Dependencies + auth checks (non-manifest)

If Phase 0a ran, skip any deps already checked there. This phase covers the
fresh / manual install case where there is **no** install manifest — the tools
the wizard leans on may simply not be present yet.

**Missing tools — install directly, never ask.** When there's no manifest, probe
the core tooling and install whatever is missing, best-effort and silently. Do
**not** present an "install all / some / none" choice — a user running `/setup`
wants HQ working, so install and move on:

```bash
# hq-cli — honor the native installer's managed toolchain before system npm.
# GUI-launched Claude/Codex sessions do not source the shell profile that the
# installer writes, so `command -v hq` alone can miss this already-installed
# binary. Do not consult `~/.hq`: the install manifest belongs to this HQ root.
HQ_MANAGED_TOOLCHAIN="$HOME/Library/Application Support/Indigo HQ/toolchain"
HQ_MANAGED_HQ_BIN="$HQ_MANAGED_TOOLCHAIN/npm-global/bin"
HQ_MANAGED_NODE_BIN="$HQ_MANAGED_TOOLCHAIN/node/bin"
if [ -x "$HQ_MANAGED_HQ_BIN/hq" ]; then
  # Prepend in reverse order so the managed Node resolves the hq shebang.
  for bin in "$HQ_MANAGED_HQ_BIN" "$HQ_MANAGED_NODE_BIN"; do
    if [ -d "$bin" ]; then
      case ":$PATH:" in
        *":$bin:"*) ;;
        *) export PATH="$bin:$PATH" ;;
      esac
    fi
  done
fi
command -v hq >/dev/null 2>&1 || npm install -g @indigoai-us/hq-cli

# qmd — npm global; on macOS it loads SQLite extensions the built-in sqlite3
# can't, so ensure Homebrew SQLite is present regardless of whether qmd itself
# was already installed.
command -v qmd >/dev/null 2>&1 || npm install -g @tobilu/qmd
if [ "$(uname)" = "Darwin" ] && command -v brew >/dev/null 2>&1; then
  brew list sqlite >/dev/null 2>&1 || brew install sqlite
fi

# gh — pick the platform-appropriate installer (brew / apt / winget); best-effort.
if ! command -v gh >/dev/null 2>&1; then
  if   command -v brew    >/dev/null 2>&1; then brew install gh
  elif command -v apt-get >/dev/null 2>&1; then sudo apt-get update && sudo apt-get install -y gh
  elif command -v winget  >/dev/null 2>&1; then winget install --id GitHub.cli -e --source winget
  fi
fi
```

Verify each with `command -v {tool}` afterward. If an install fails (or no
supported installer is available on this platform), note it under "Still needs
attention" in the Phase 3 summary and continue — never block setup on a failed
optional tool.

**Auth checks** (not tracked by manifest):
- `gh auth status` — if gh is installed but not authenticated, offer `gh auth login`
  (a browser auth is the one place a prompt is warranted; installing gh is not).

Do **not** check for or install third-party deploy CLIs (e.g. the Vercel CLI) here.
HQ's own features never shell out to them — `/deploy` targets hq-deploy
infrastructure, not Vercel — so they are not HQ setup dependencies. They are
user-provided tools, installed on-demand by the user only when deploying their
own projects to their own pipeline; point-of-use guidance lives in the relevant
policy (e.g. `core/policies/hq-vercel.md`), not in setup.

Post-install: run `qmd index .` if qmd was just installed or no index exists.

*(guided: `[hq-setup] step=tools status=done` once 0a/0b are through)*

## Phase 0c: HQ Cloud — login, claim invites, ensure sync

*(guided: `[hq-setup] step=cloud status=running`)*

Connect this HQ to HQ Cloud so the user lands logged in, with any cloud-company
invites claimed and sync working. Do this **before** identity so synced company
context can inform the rest of the wizard, and so the welcome-page `/deploy`
(Phase 6) is already authenticated. One question at a time. Solo / offline HQ is
fine — never block setup on cloud.

### 1. Confirm Cognito login

```bash
hq auth status 2>/dev/null
```

- **Signed in, token valid** → continue. Show identity: `hq whoami`.
- **Token expired** → try a silent refresh first: `hq auth refresh`.
- **Not signed in, or refresh failed** → ask one question: "Sign in to HQ Cloud
  now? (unlocks team sync, shared knowledge, and publishing)". If yes, run the
  `/hq-login` skill (browser Cognito login). If they decline, note that cloud
  features (sync, `/deploy`, shared companies) are unavailable until they run
  `/hq-login`, and skip the rest of Phase 0c.

There is **no command that lists "companies I've been invited to."** Modern
invites are email-keyed and claimed automatically the first time sync runs (the
sync-runner "claim dance"). So do not promise an invite list — claim them via
sync in step 2.

### 2. Ensure sync + claim invites

Once signed in, run a full sync via the `/hq-sync` skill (engine:
`hq sync pull --all` / `hq-sync-runner --companies --direction both`). This fires
the claim dance — auto-accepting any email-keyed pending invites — and pulls
every cloud company the user belongs to.

The runner emits `setup-needed` when a run cannot proceed. It carries a `reason`
and, when relevant, a `pendingInviteCount` — read both and act on them. Do NOT
fall through to the solo path on a bare `setup-needed`:

- `reason: "no-memberships"` with `pendingInviteCount > 0` — the user has an
  invite that has not been accepted. Say so, and tell them to run
  `/accept <link-or-token>`, then re-run sync. This is the single most common
  reason someone is wrongly told they are solo.
- `reason: "no-memberships"` with no pending invites — genuinely no company yet.
  The solo path is correct here.
- `reason: "no-person-entity"` — signed in, but there is no personal entity to
  sync into. Usually a **legacy magic-link** invite; point them to
  `/accept <link-or-token>` to redeem it, then re-run sync.
- If sync errors (network, transport), report it plainly and continue.

An older runner emits `setup-needed` with no `reason` at all. Treat that as
"unknown — do not conclude solo", and offer `/accept` rather than asserting the
user has no team.

### 3. Report what landed

**Membership is the source of truth here, not the manifest file.** A newly
invited member's `companies/manifest.yaml` arrives as the stock empty template
synced from their personal vault, so grepping it reports "solo" for someone who
demonstrably belongs to a company. That is the exact bug this step exists to
avoid re-introducing.

Resolve the company list in this order:

1. **The runner's `fanout-plan` event** from the sync you just ran. It lists
   every company target the run resolved, with slug and name. This is free —
   you already have it.
2. **`GET /membership/me`** via the vault client, if you need to resolve
   membership without a sync in hand.
3. **The manifest grep, fallback only** — use it when the API is unreachable,
   and say that the answer is local-only:

```bash
grep -E "^  [a-z0-9-]+:" companies/manifest.yaml 2>/dev/null | sed -E 's/^  ([a-z0-9-]+):.*/\1/'
```

Then report:

- Companies resolved → "You're connected and synced. You're in: {names}." Name
  the companies. A user who was just told they are on a team and cannot see
  which one has not actually been told anything.
- API says companies exist but the manifest grep disagrees → report the API
  answer, and note that local routing has been repaired (the sync runner
  reconciles the manifest entry and seeds `activeCompany` on the way through;
  a freshly written manifest propagates on the NEXT sync).
- Nothing resolved, and no pending invites → "You're signed in. No cloud
  companies yet — you're solo for now, that's fine."

Keep Phase 0c to a few plain lines; the heavy lifting is the reused skills.

*(guided: `[hq-setup] step=cloud status=done`)*

## Phase 0d: Adopt prior AI footprint

*(guided: `[hq-setup] step=import status=running`)*

If the user already used AI tools before HQ — Claude Code, Codex, Grok, or
claude.ai chat — they have two kinds of prior context worth adopting: artifacts
on disk (skills, hooks, policies, plans, MCP servers, repos in `~/.claude/` and
common code dirs) and **conversation history** (Claude Code, Codex, and Grok
session stores, plus claude.ai chats via export). Hydrating both into HQ now
means the rest of the wizard — Dream Big (4.5), the action interview (5) —
reflects the companies, knowledge, policies, and projects they already have,
instead of starting from a blank slate. This is the `/import-context` skill
(formerly `/import-claude`), surfaced as a first-class setup step, and it runs
**before** identity so the rest of the wizard already knows what they brought.
One question at a time; never block setup — a clean install with no prior
footprint flows straight past this.

### 1. Detect a prior footprint (cheap, read-only)

`/import-context` requires `companies/manifest.yaml` to exist (a fresh `hq init`
ships it). If it's missing, skip this phase. Otherwise do a quick existence probe
of the scanner's main allowlist plus the conversation stores — do **not** run
the full scan here, just decide whether there's plausibly anything to import:

```bash
test -f companies/manifest.yaml || echo "no-manifest-skip"
# Probe the highest-signal locations; any non-empty hit means "offer the import".
for d in "$HOME/.claude/plans" "$HOME/.claude/commands" "$HOME/.claude/skills" \
         "$HOME/.claude/projects" "$HOME/.claude/agents" \
         "$HOME/.codex/sessions" "$HOME/.grok/sessions"; do
  [ -d "$d" ] && find "$d" -mindepth 1 -maxdepth 2 -print -quit 2>/dev/null
done
```

- **No manifest, or every probe is empty** → print one plain line ("No prior
  AI footprint to import — starting fresh.") and continue to Phase 1.
- **Any probe returns a path** → there's plausibly something to adopt; offer it
  in step 2. (The authoritative scan, with counts and redaction, happens inside
  `/import-context` itself — keep this probe lightweight.)

**Guided mode:** before offering, count what the probe hit (still read-only,
still cheap) and emit a `found` card with only the non-zero rows, then the
step-2 question. For example:

```bash
for pair in "Claude Code sessions:$HOME/.claude/projects:*.jsonl" \
            "Plans:$HOME/.claude/plans:*" "Commands:$HOME/.claude/commands:*" \
            "Skills:$HOME/.claude/skills:*" "Agents:$HOME/.claude/agents:*" \
            "Codex sessions:$HOME/.codex/sessions:*" "Grok sessions:$HOME/.grok/sessions:*"; do
  label=${pair%%:*}; rest=${pair#*:}; dir=${rest%%:*}; glob=${rest#*:}
  [ -d "$dir" ] && n=$(find "$dir" -mindepth 1 -maxdepth 3 -name "$glob" 2>/dev/null | wc -l | tr -d ' ') || n=0
  [ "$n" -gt 0 ] && echo "$label=$n"
done
```

```
[hq-setup] card={"kind":"found","title":"Here's what I found","items":[{"label":"Claude Code sessions","count":12},{"label":"Plans","count":3}]}
```

### 2. Offer the import (AskUserQuestion)

One AskUserQuestion call:

- `question`: "Looks like you've used Claude Code, Codex, or Grok before. Want
  me to import your existing skills, plans, and repos — and mine your past
  conversations for proposed companies, knowledge, and projects — now? You
  approve every item before it's created."
- `header`: "Import"
- `multiSelect`: false
- `options`:
  - `Import now` — "Run /import-context inline — discovers your artifacts,
    mines your conversation history across tools, and proposes companies,
    knowledge, policies, and projects (you confirm each step)"
  - `Preview first` — "Scan and show me what's there, import nothing yet
    (/import-context --dry-run)"
  - `Skip` — "Don't import; I'll run /import-context later if I want"

### 3. Run it

- **Import now** → inline-invoke the `/import-context` skill via the Skill tool.
  It runs its own preflight, scan, redaction, conversation mining, and
  per-category triage — every write is gated by its own AskUserQuestion prompts,
  so you don't re-ask here. If the user mentions claude.ai chats, pass
  `--claude-export=<path>` once they have a data export (claude.ai → Settings →
  Privacy → Export data). When it returns, briefly note what landed (companies
  created, knowledge seeded, projects proposed, workers synthesized, repos
  adopted) in one plain line, then continue to Phase 1.

  **Guided mode:** show what landed as a card, not a sentence. Emit a `found`
  card titled "What landed" with one row per outcome that is non-zero
  (companies created, knowledge files seeded, projects proposed, workers,
  repos adopted — `detail` names them, e.g. `"detail":"acme, northwind"`),
  then one AskUserQuestion — `header`: "Import", `question`: "Here's what the
  import brought in. Good to go on?", options `Looks good` / `Let me review`
  ("Open the import report before moving on"). On `Let me review`, print the
  report path and the per-category list, then re-ask once.
- **Preview first** → inline-invoke `/import-context --dry-run`. It scans and
  reports counts without importing. After it returns, ask once whether to run the
  real import now (re-invoke `/import-context` without the flag) or defer. If they
  defer, treat it as Skip.

  **Guided mode:** the person chose Preview to *see* what is there, so the
  scan result must be the card, not prose. Build a `found` card titled
  "What's there" from the dry-run's counts-per-category summary — one row
  per non-zero category in plain words (`Plans`, `MCP servers`, `Settings`,
  `Commands`, `Skills`, `Hooks`, `Policies`, `CLAUDE.md files`, `Knowledge
  folders`, `Repos`, `Agents`, `Conversations` with the per-tool breakdown as
  `detail`) — emit it, then ask the run-now-or-skip question (`header`:
  "Import", options `Import now` / `Skip for now`).
- **Skip** → note that `/import-context` is available anytime, and add it to the
  Phase 5 recommended-commands list so it resurfaces in their launch block.

Because `/import-context` already creates companies (`/newcompany`) and workers
(`/newworker`) inline and confirms every write, running it here is the canonical
way to hydrate the skeleton — do not hand-roll an equivalent import. Whatever it
brings in becomes context for Dream Big (4.5) and the action interview (5).

*(guided: `[hq-setup] step=import status=done`)*

## Phase 1: Identity

*(guided: `[hq-setup] step=you status=running`)*

Ask these 5 questions. One at a time — one message per question, the
question as its bold last line. These answers are the strategic frame for
the whole wizard — they feed the knowledge files (Phase 2), the Dream Big vision
block (Phase 4.5), and every tailored command in the action interview (Phase 5).
So gather all five before moving on.

1. **What's your name?**
2. **What do you do?** (1-2 sentences — your roles, work, domain)
3. **What are your goals for using HQ?** (what do you want AI workers to help with?)
4. **What are your biggest challenges or pain points right now?** (what's hard,
   slow, repetitive, or keeps slipping)
5. **What are your main systems of record?** (where your truth lives — DB, CRM,
   Slack, email, analytics, repos, spreadsheets, etc.) For each, capture its
   **name + type**, and note which ones have a **credential** we could connect
   later (a connection string, API token, etc.). Don't ask for the secret itself
   — just whether one exists.

Personal scope lives at the top-level `personal/` directory (peer of `core/`), not as a company. Workers, knowledge, policies, and skills you create for yourself live under `personal/{type}/...` — they are read directly from `personal/` (the old `core/<type>/` symlink mirror was retired), so they load without any mirror step and survive `/update-hq`. (Personal skills surface via the `.claude/skills/personal:<name>/` bridge.)

## Phase 1.5: Social presence + browser harness

Learn who the user is from their public presence — and initialize their browser
harness in the process, so they leave setup ready to have HQ drive the web for
them. One question at a time. Everything here is optional; never block setup.

### 1. Frame it

One short message: "Let's connect your browser so HQ can learn from your public
presence — and so you've got a browser harness ready for future work (research,
filling forms, pulling data from sites you're logged into)."

### 2. Detect / initialize the browser harness

Check whether a browser harness is connected:

- **Claude Code:** call `mcp__Claude_in_Chrome__list_connected_browsers`. If no
  browser is connected, point the user to install the **Claude for Chrome**
  extension (the recommended harness), then wait for them to connect and re-check.
- **Codex:** use the Codex browser tool equivalent if present.

The browser harness is what makes **login-walled** profiles (LinkedIn,
Instagram) readable — it drives the user's own authenticated session, so it sees
what they see.

**Fallback (no harness):** if the user declines or can't install the extension,
fall back to best-effort public fetching with `WebFetch` + `WebSearch`, and tell
them up front that login-walled sources (LinkedIn, Instagram) will be skipped.
Never block on the extension.

### 3. Ask for profiles — ONE AT A TIME

Ask for each, accepting "skip" for any (use AskUserQuestion, one per call):

1. X / Twitter
2. LinkedIn
3. Instagram
4. Personal website / blog
5. (optional) GitHub

### 4. Read each source

For every URL the user provided (these are the user's **own** profiles, so the
link-safety suspicion check is satisfied):

- **With harness:** `navigate` to the URL, then `get_page_text` / `read_page`.
- **Without harness:** `WebFetch` the public ones; `WebSearch` "{name} {handle}"
  to fill gaps for walled sources.

**Delegate the fetch + synthesis to a subagent** (Task / Agent tool) that returns
a **text summary only** — keep raw pages and any screenshots out of the parent
session (HQ context diet; parent stays under the image cap). Ask the subagent for:
who they are publicly, what they work on / care about, recurring themes, and
voice/tone cues — plus which sources it couldn't reach.

### 5. Persist the understanding (synthesized, never raw)

Write only synthesized understanding — never raw page dumps, never credentials,
never session URLs. Create the dir first if needed (`mkdir -p personal/knowledge`):

**personal/knowledge/social-presence.md:**
```markdown
# {Name} — Public Presence

_Synthesized during /setup from the profiles below. Refresh anytime._

## Who they are publicly
{1–2 paragraph synthesis}

## Themes & focus
- {recurring topic / area}

## Voice & tone cues
- {observed phrasing, register, what they sound like}

## Profiles
| Source | Link | Read? |
|---|---|---|
| X | {url} | {yes / walled / skipped} |
| LinkedIn | {url} | {yes / walled / skipped} |
| ... | | |
```

Hold this understanding in working memory — Phase 2 weaves it into `profile.md`,
`agents-profile.md`, and `voice-style.md`, and Phase 4.5 + Phase 6 draw on it.

## Phase 2: Generate Files

### Repos directory (required)

Code repos live under `repos/public/` and `repos/private/`. Knowledge bases are **real directories** under `personal/knowledge/` or `companies/{slug}/knowledge/` (embedded git) — not symlinks into `repos/`.

```bash
mkdir -p repos/public repos/private
```

### Personal scaffold
```bash
mkdir -p personal/{knowledge,policies,workers,settings,skills,hooks}
```

### Company structure (only when adding a real company — use `/newcompany {slug}` instead)
For reference, a company directory looks like:
```
companies/{slug}/{settings,data,knowledge,workers,policies}
```
The schema and a fillable template live at `companies/_template/`.

### Knowledge directories

Personal and company knowledge directories must be **real directories** so cloud
sync uploads document contents. Do **not** symlink `personal/knowledge/` or
`companies/{slug}/knowledge/` into `repos/` — sync records symlinks as vault
markers and teammates receive nothing.

For each knowledge base the user wants to create:

1. Create the directory and embedded git repo:
```bash
mkdir -p personal/knowledge/{name}
cd personal/knowledge/{name}
git init
printf '# %s Knowledge Base\n' "{Name}" > README.md
git add . && git commit -m "init knowledge repo"
cd -
```

Verify:

```bash
test -d personal/knowledge/{name} && ! test -L personal/knowledge/{name} \
  && echo "OK: knowledge is a real directory"
```

**Optional:** turn all of `personal/knowledge/` into one git repo for cross-machine sync:
```bash
# Only when personal/knowledge/ is still empty or the user confirms migration
mkdir -p personal/knowledge
cd personal/knowledge
git init
printf '# Personal Knowledge Base\n' > README.md
git add . && git commit -m "init personal knowledge"
cd -
```

If you skip embedded git, `personal/knowledge/` is a plain directory tracked by HQ git — fine for single-machine setups.

**The starter kit's bundled knowledge (Ralph, workers, ai-security-framework, etc.) ships as plain directories. Explain to the user:**
```
Bundled knowledge (Ralph, workers, security framework) ships as plain directories.
Keep those real directories in place so upgrades and sync see their contents. Add
personal or company-specific knowledge under personal/knowledge/ or
companies/{slug}/knowledge/. If separate version history is needed, initialize git
inside the canonical real directory; never move it into repos/ and symlink it back.
```

### Profile files

**personal/knowledge/profile.md:**
```markdown
# {Name}'s Profile

## About
{Answer from Q2 — enriched with the public-presence synthesis from Phase 1.5 if
available. Cross-reference: see personal/knowledge/social-presence.md.}

## Goals
{Answer from Q3}

## Challenges
{Answer from Q4 — the pain points HQ should help attack}

## Systems of Record
{Answer from Q5, as a table}

| System | Type | Has credential? |
|---|---|---|
| {name} | {DB / CRM / Slack / email / analytics / repo / ...} | {yes / no} |

## Preferences
- Communication style: [to be filled by /personal-interview]
- Autonomy level: [to be filled by /personal-interview]
```

**personal/knowledge/systems-of-record.md** (canonical list workers consult to
know where the user's truth lives — write full prose, one row per system from
Q5; `Connection` starts as `capture-only` and flips to `connected` in Phase 5b.5
when a secret-link is minted):
```markdown
# {Name}'s Systems of Record

Where the truth lives. Workers consult this before assuming or re-deriving data.

| System | Type | Has credential? | Connection |
|---|---|---|---|
| {name} | {type} | {yes / no} | {capture-only / connected / not yet} |

> To connect a system later: `/hq-secrets` (mints a link you fill in; the agent
> never sees the secret). Never paste a credential or a share/secret link into
> this file — those are capabilities, surfaced inline at mint time only.
```

**personal/knowledge/voice-style.md:**
```markdown
# {Name}'s Voice Style

## Observed cues
{Seed with the voice/tone cues synthesized in Phase 1.5, if any — e.g. register,
recurring phrasing, how they sound publicly. Leave a note if none were captured.}

Run `/personal-interview` to deepen this with your authentic voice and
communication style.
```

**agents-profile.md** (root level — first line MUST match `# {Name} - Profile` for the inject-local-context.sh hook regex):
```markdown
# {Name} - Profile

- **Location**: {city}
- **Background**: {Answer from Q2 — folded together with the Phase 1.5
  public-presence synthesis if available}

## Goals
{Answer from Q3}

## Challenges
{Answer from Q4 — surfaced every session via inject-local-context.sh so workers
know the standing pain points to attack}

## Working Preferences

Run `/personal-interview` to populate the autonomy matrix and communication style.

## Company Roster

Full company/role context lives in `agents-companies.md` (three tiers: Operate / Client / Portfolio).
```

**personal/agents-companies.md** (created empty, populated by `/personal-interview` or manually):
```markdown
# {Name} — Company Contexts

> Three tiers: (1) Operate = founder/CEO hats. (2) Client = paid build work. (3) Portfolio = advisory/equity.
> Within Operate: active / slow-burn / on hold. `slug` = the key in `companies/manifest.yaml`.

## 1. Operate — Founder / CEO hats

_Run `/personal-interview` or edit manually to populate._

## 2. Client work (build, not owned)

## 3. Portfolio / Advisory
```

Add to `.gitignore` if not already present:
```
# Personal knowledge contents (tracked by embedded git when configured)
personal/knowledge/
```

### Index
```bash
qmd update 2>/dev/null || qmd index . 2>/dev/null || true
```

## Phase 3: Summary

```
HQ Setup Complete!

Created:
- repos/public/, repos/private/ (code repositories only)
- personal/ scaffold (knowledge, policies, workers, settings, skills, hooks)
- personal/knowledge/profile.md
- personal/knowledge/systems-of-record.md
- personal/knowledge/social-presence.md (if profiles captured in Phase 1.5)
- personal/knowledge/voice-style.md
- agents-profile.md
- agents-companies.md
- personal/knowledge/ as a real directory (optionally an embedded git repo)

HQ Cloud:
✓ Signed in {as email} — or "not connected (run /hq-login later)"
✓ Synced — {N companies} or "solo, nothing to pull yet"

Dependencies:
✓ claude (Claude Code CLI)
✓ qmd (semantic search) — or skipped
✓ gh (GitHub CLI) — or skipped

Still needs attention:      ← include this block ONLY if a direct install failed
✗ {tool} — {what failed; the one manual command the user can run to finish it}
...

Knowledge Repos:
Your personal knowledge bases are real directories under personal/knowledge/.
Initialize git inside a knowledge directory when it needs independent version history;
knowledge repositories are never symlinked into HQ.
See "Knowledge Repos" in core/docs/hq/README.md for details.

Setup is done. Next: a short orientation + a few questions so I can hand you
the exact commands to start your first real work.
```

Do not print a static next-steps list here. Continue to Phase 4.

## Phase 4: Learn the HQ Mental Model

A brief orientation before the interview. Keep it to roughly a screenful — this
is a mental model, not a course. Pull the framing from
`core/docs/hq/USER-GUIDE.md` rather than reinventing it; do not duplicate the
hands-on lessons that already live in `/tutorial`.

Present this (adapt wording, keep it tight):

```
How HQ works — the 60-second model:

  • Sessions are disposable. Start with /startwork,
    do one focused thing, end with /handoff (it saves where you left off so
    the next session resumes exactly there). A fresh session is a feature,
    not a reset.
  • Three homes for things: personal/ (your overlay — workers, knowledge,
    policies just for you), companies/ (isolated tenants you operate or
    serve), repos/ (all actual code, public or private).
  • Knowledge compounds. Workers, knowledge docs, and policies you create
    make every future session smarter — capture learnings, don't re-derive.
  • Slash commands are the interface. /newworker, /plan, /deploy, /search,
    /onboard — you drive HQ by naming the capability, not hand-rolling it.
  • /search (or qmd) finds anything across HQ — knowledge, projects,
    workers, policies, indexed repos.

Go deeper anytime:
  • /tutorial          — hands-on, interactive lessons against your real HQ
  • /personal-interview — deep dive on your voice + working style so workers
                          sound and decide like you
```

Then continue to Phase 4.5 (don't wait for acknowledgement — flow straight in).

## Phase 4.5: Dream Big

Before the action interview, paint the destination. Ground this entirely in the
user's own answers (Q2 what-you-do, Q3 goals, Q4 challenges, Q5 systems of
record) plus the Phase 1.5 public-presence synthesis — generic HQ marketing is
worse than nothing. Produce **2-3 concrete, tailored scenarios**, each in the
shape: *their pain point → the HQ capability that attacks it → the outcome they'd
feel*. Name the real command in each.

**Templates to adapt — substitute every `<…>` slot with the user's literal Q1-Q5
words before emitting. Never print the angle-bracket form to the user.** The `<…>`
slots are author-time placeholders, not output. If a slot has no matching answer,
drop the bullet rather than emit a generic stand-in.

Scenario shapes to choose from (pick 2-3 that actually fit the user's answers):

- *Worker for a recurring pain:* "You said **<their literal Q4 pain point>** eats
  your time. Build a `/newworker` specialist that does exactly that — and it gets
  smarter every run, so the work compounds instead of repeating."
- *Connect a system, ship a live report:* "Your truth lives in **<their literal
  Q5 system, e.g. 'Postgres in Supabase' or 'HubSpot CRM'>**. Connect it once
  with `hq secrets generate-link`, then `/deploy` a live report behind a signed
  URL your team can open — no copy-paste, no stale screenshots."
- *Compounding knowledge:* "**<their recurring task from Q2/Q3>** becomes a
  knowledge base that compounds: every session adds to it via `/learn`, so you
  never re-derive the same answer twice."

**Worked example — this is the shape of what to actually emit to the user.**
Assume Q4 = "I lose hours re-summarizing the same investor updates each week"
and Q5 = "HubSpot CRM (has credential)":

> You said **losing hours re-summarizing investor updates each week** eats your
> time. Build a `/newworker` specialist that drafts each week's update from your
> CRM activity — it learns your phrasing every run, so by month three you're
> editing, not writing.
>
> Your truth lives in **HubSpot**. Connect it once with `hq secrets generate-link`,
> then `/deploy` a live investor-update preview behind a signed URL your LPs can
> open — no copy-paste, no stale screenshots.

Keep it to ~half a screen, aspirational but grounded — not salesy. Close with one
line, e.g.: "That's the destination. Let's take the first concrete steps now."
Then flow straight into Phase 5.

## Phase 5: What Do You Need Help With?

A branching interview that both **does** lightweight scaffolding inline and
**collects** a recommended-command list for future fresh sessions. It ends in a
two-section launch block (done now / run next). Ask one question at a time
(decision-queue-one-at-a-time). Reuse Phase 1 answers (name, what they do, goals,
challenges, systems of record) — never re-ask what's captured.

### 5a. Role discovery (FIRST — before any scope question)

Go one level deeper than Phase 1's high-level "what do you do". Conversational,
free-text (a picker would flatten the nuance) — one message per question,
the question as its bold last line. Phase 1 Q4 already captured pain
points — don't re-ask. Focus here on the day-to-day texture that shapes which
commands to suggest:

1. **What's your specific role?** (title + the hat you actually wear day-to-day)
2. **Walk me through a typical day — what do you actually spend time on?**

These answers, plus the Q4 challenges and Q5 systems of record, anchor every
command suggestion below — keep them in working memory for the synthesis step.

### 5b. Primary scope (AskUserQuestion)

One AskUserQuestion call, four options:

- `Run my own companies / clients`
- `Personal projects & automation`
- `Learn / explore HQ first`
- `Bring in an existing codebase`

*(guided: `[hq-setup] step=you status=done` then `[hq-setup] step=connect status=running`
before 5b.5)*

### 5b.5. Connect a system of record (inline, optional)

For each Q5 system the user said has a credential, offer to wire it up **now** so
they leave setup with a real connection, not just a note. This is the one
write-side connection primitive HQ has (`hq sources` is read-only).

**Guided mode (HQ Desktop):** do not mint a link. For each system, emit a
`secret` card and then one AskUserQuestion — the desktop shows a masked field,
stores the value with `hq secrets set --from-stdin` itself (the value never
enters this session), and answers `Done`:

```
[hq-setup] card={"kind":"secret","name":"DATABASE_URL","label":"Postgres connection string","hint":"Starts with postgres://","scope":"company","company":"{slug}"}
```

- `question`: "Add your {label} now? It goes straight into the HQ vault."
- `header`: "Secret"
- `multiSelect`: false
- `options`: `Done` — "It's stored in the vault" · `Skip` — "Leave it for later"

On `Done`, confirm the name now appears in `hq secrets list [--personal |
--company {slug}]` (names only — never `get` the value) before flipping the
system to `connected`. On `Skip`, it stays `capture-only`.

**Terminal mode:** mint a one-time link instead:

```bash
hq secrets generate-link <SECRET_PATH> [--personal | --company {slug}]
```

- Pick a sensible `SECRET_PATH` per system (e.g. `DATABASE_URL`, `SLACK_TOKEN`,
  `STRIPE_API_KEY`). Use `--personal` for personal scope, or `--company {slug}`
  matching the scope chosen in 5b.
- The command mints a one-time URL the user opens to enter the secret — the agent
  never sees it. **Surface that URL inline at mint time only.** It is a
  capability: never write it into `systems-of-record.md`,
  `getting-started-next-steps.md`, or any later turn (per
  `hq-share-session-urls-are-capabilities`).
- After each one is wired, flip that system's `Connection` cell in
  `personal/knowledge/systems-of-record.md` from `capture-only` to `connected`.
- Accept "skip" for any system → it stays `capture-only`; add `/hq-secrets` to
  the recommended-commands list so they can connect it later.

### 5b.6. Connect apps (inline, optional — company scope only)

If 5b chose a company scope and the company is cloud-backed, offer the apps HQ
recommends for that company so agents can use them from day one. Derive the
list from the authoritative catalog — never a hand-kept list:

```bash
hq integrations catalog --company {slug} --json   # candidates
hq integrations list --company {slug} --json      # already connected
```

- Keep catalog rows with `"source": "hq-recommended"` and `"mcpReady": true`
  whose `authClass` is `oauth` or `none` (API-key apps need a key intake the
  guided run does not have yet — mention `/hq-integrations` for those). Cap
  at six, catalog order. Mark any whose provider is already in `list` as
  `connected`.
- Nothing left to offer, or personal scope, or solo HQ → skip this step
  silently.

**Guided mode:** emit an `integrations` card, then one multi-select
AskUserQuestion whose option labels are exactly the app names plus
`Skip for now`:

```
[hq-setup] card={"kind":"integrations","items":[{"id":"hq-recommended-linear","name":"Linear","description":"Issues and projects","auth":"oauth","status":"available"},{"id":"…","name":"GitHub","auth":"oauth","status":"connected"}]}
```

- `header`: "Integrations" · `question`: "Which apps should HQ connect now?"

**Terminal mode:** the same question without the card.

For each picked app run `hq integrations connect --entry-id <id> --company
{slug}` one at a time. OAuth opens the browser; relay the two outcomes exactly
as `/hq-integrations` describes ("Connected …" is live; a printed sign-in URL
means **not connected yet**). After the batch, re-emit the `integrations` card
with updated `status` values in guided mode, and add `/hq-integrations` to the
recommended-commands list for anything skipped.

*(guided: `[hq-setup] step=connect status=done` then
`[hq-setup] step=moves status=running` before 5c)*

### 5c. Team / cloud detection (shapes the strongest recommendation)

Use the membership list already resolved in Phase 0c step 3 — do not re-derive
this from a manifest grep. If the user has at least one active company
membership, this is a team / cloud context, full stop. A joiner whose manifest
has not caught up yet is still on a team.

Only when membership could not be resolved at all (API unreachable), fall back
to the local signals:

```bash
grep -l 'cloud' companies/*/manifest.yaml 2>/dev/null | head -1
grep -iE 'cloud_backed|hq[-_]?pro|team' companies/manifest.yaml 2>/dev/null | head -3
```

Also treat it as team/cloud if `companies/manifest.yaml` has at least one real
company entry (top-level keys under `companies:`), or the user's role-discovery
answers describe working with a team. Notes:

- The top-level `personal/` overlay does not count — it's not a company.
- `companies/_template/` does not count either — it's the scaffold copied by
  `/newcompany`, and is never listed in `manifest.yaml`. A fresh HQ install
  with only `_template/` on disk is **solo**, not team/cloud.

**If team/cloud** — make the headline recommendation a *shareable asset* task:

- Build a reusable asset grounded in the role-discovery pain point, then share
  it with the team: `/newworker` (a specialist for the draining task), or a
  knowledge doc + `/learn`, then `/hq-share <path>` (or `/designate-team` to
  make the company cloud-backed for the whole team).
- And/or **produce a report and deploy it**: `/plan` (or a direct artifact) →
  `/deploy` — framed as "show your team something real, behind a signed URL".

**Deploy is not team-gated.** Even for solo / personal scope, surface a
"create something small and `/deploy` it" task as a high-value early win
(a report, a one-pager site, a shareable result).

### 5d. Branch follow-ups — split do-now vs recommend (AskUserQuestion, one at a time)

Mirror how `/tutorial` Step 1 and `/startwork` gate picks. For each branch, sort
actions into **(a) do-now inline** (lightweight, high-momentum — run this
session) and **(b) recommend for a fresh session** (heavy / context-hungry — add
to the launch list, do NOT run inline). See the Rules for the inline/handoff line.

- **Companies / clients** → "Is the company already in HQ?"
  - *Do now:* `/newcompany {slug}` (new — lightweight scaffold) or `/onboard`
    (join existing). If Phase 0d was skipped and they're an existing Claude
    user, re-offer `/import-context` here to hydrate the skeleton.
  - **Never offer `/newcompany` for a slug the user already has an active
    membership in.** Check the membership list resolved in Phase 0c step 3
    first. Routing a joiner to `/newcompany` for a company they already belong
    to is what produced the duplicate companies this flow exists to prevent —
    they end up owning a second, empty company with the same name as the real
    one. If the slug matches an existing membership, the answer is "you're
    already in that one" plus `/startwork {slug}`, not a scaffold.
  - *Recommend:* first deliverable → `/brainstorm` / `/plan` / `/startwork {slug}`.
    If team/cloud, fold in the shareable-asset + `/deploy` recommendation.
- **Personal projects** → "What's the first thing you want a worker to do?"
  (anchored to role-discovery + Q4 challenges).
  - *Do now:* `/idea` to capture it on the board; `/newworker` if a recurring
    specialist is clearly implied.
  - *Recommend:* `/plan` for the first real deliverable, plus the solo
    `/deploy` early-win.
- **Learn first** → *Do now:* nothing heavy. *Recommend:* `/tutorial` (suggest a
  topic from role-discovery + Phase 1 goal) then `/personal-interview`.
- **Existing codebase** → *Do now:* note the clone target (`repos/public/` or
  `repos/private/`). *Recommend:* `/discover <repo>` in a fresh session (it's
  context-hungry — never run inline during setup).

### 5e. Synthesize + emit the two-section launch block

Produce two ordered lists, each command **fully substituted** (real slugs/paths
— never `{placeholder}` tokens), each with a one-line "why" tied to their
answers. Print inline:

```
You're set up. Here's where you landed.

Done this session:
  ✓ {what was actually scaffolded / connected — company, idea, secret-link, knowledge doc}
  ...

Run these next — start a FRESH session for each (context hygiene, see Phase 4):
  1. {command}        — {why, tied to their challenge / goal / system of record}
  2. {command}        — {why}
  ...

Saved to personal/knowledge/getting-started-next-steps.md — reopen anytime.
```

### 5f. Persist the artifact

Write `personal/knowledge/getting-started-next-steps.md` (the dir is created in
Phase 2, so the path always exists). Full prose — this is a disk artifact, not
chat. Contents:

- Generated date
- The user's role + stated goal + top challenges (from Phase 1 + 5a)
- **Done this session** — what was actually scaffolded/connected (company, idea,
  knowledge docs, which systems of record got connected)
- **Run these next** — the same recommended command list shown inline, each with
  its rationale, one fresh session per command
- A "Your systems of record" recap (mirror the table, with connection status) so
  they remember what's wired vs still to connect
- An "If you get lost" footer: `/startwork`, `/tutorial`, `/search <topic>`

**Never** write any secret-link / share URL into this file — those are
capabilities, surfaced inline at mint time only.

If the file already exists, show the user what would change and confirm via
AskUserQuestion before overwriting (per the Rules below — never overwrite
silently).

## Phase 6: Deploy the welcome page + hand off

The visual capstone. Turn everything learned into a small, **private**,
personalized welcome page and publish it, then send the user off to a fresh
session. Requires the Cognito login from Phase 0c; if the user never signed in,
skip the deploy and just deliver the launch block + handoff message in chat.

### 1. Build the page (one `index.html`)

Generate a single `index.html` — **never** multiple `.html` files: the static
host SPA-fallbacks every `.html` subpath to `index.html` silently, so use one
file with a `#/route` hash router if it needs sections.

- **Design:** if the `impeccable` skill is available, use it to craft the page
  (the owner's lives at `personal/skills/impeccable/`). If it's absent in this
  HQ, produce a high-quality inline design instead — degrade gracefully, never
  hard-depend on impeccable.
- **Content** — four sections, all drawn from earlier phases:
  1. **Who you are** — the synthesis from Phase 1 (identity) + Phase 1.5
     (public presence).
  2. **How your HQ is set up** — cloud companies synced (Phase 0c), the personal
     scaffold, systems of record and which are connected.
  3. **Starter moves** — the Phase 5 recommended commands as **copy-paste prompt
     blocks**, each fully substituted (real slugs/paths — never `{placeholder}`),
     each with a one-line "why".
  4. **Hand off** — close this session, start a fresh one, paste the first prompt.
- Stage it in a scratch dir (e.g. `workspace/setup-welcome/index.html`).

### 2. Deploy private

Run the `/deploy` skill on the staged dir with **private (owner-only)** access
mode. The page holds personal understanding, and `sensitivity-check.sh` greps
filenames only — it returns `sensitive:false` for a lone `index.html` even when
the content is personal — so set the access mode to private manually; do not rely
on the auto-verdict.

### 3. Surface the link + hand off

Print the deploy URL **inline, in one plain line** (this is the `/deploy`
capability carveout — surfaced at publish time, never re-pasted into knowledge
files or later turns). Then point the user to the guided public course as their
canonical visual walkthrough:

`https://www.hqforwork.com/getting-started/tutorials/install-hq-macos?source=hq_setup_wizard`

Call it the **guided HQ tutorial (videos + written steps)** so it stays distinct
from the adaptive, in-agent `/tutorial` command. Then deliver the handoff message:

```
You're all set — here's your welcome page (private to you): {url}

Follow the guided HQ tutorial here (videos + written steps):
https://www.hqforwork.com/getting-started/tutorials/install-hq-macos?source=hq_setup_wizard

Open it, then close this session and start a fresh one. Your first move:

  {first copy-paste prompt, fully substituted}

(A fresh session per task keeps context clean — see your welcome page for the
full list.)
```

### 4. Teach the `/handoff` habit before they go

This is the one habit that makes every future session work. Setup is where they
learn it, so end by teaching it explicitly — don't leave it as an optional
aside.

Deliver a short, plain-language nudge along these lines (adapt the wording, keep
it to a few lines):

```
One habit that'll save you every time: when you finish real work in a
session, end it with /handoff.

/handoff writes down where you left off — what you did, what's next, which
files changed — and saves it so a fresh session picks up exactly there. No
"remind me what we were doing." You just run /startwork next time and it's
all waiting.

The rhythm is: /startwork → do one focused thing → /handoff → close the
session. Try it at the end of your very first work session.
```

**Nudge, don't just mention.** As real work accumulates in *this* session
(a company scaffolded, a worker built, a knowledge doc written), it's worth
actively offering to run `/handoff` now so they see it once end-to-end — for a
bare setup with nothing substantive done yet, teaching the habit is enough and
starting fresh with the first prompt is fine. Either way, they should leave
setup knowing what `/handoff` is, why it matters, and how to run it.

*(guided: `[hq-setup] step=moves status=done` as the last line of Phase 6)*

## Rules

- **Guided mode markers are part of the contract.** With `--guided`, every
  step boundary and every card question carries its marker line (see "Guided
  mode" above); without it, none do.
- Ask questions one at a time — every phase, including the Phase 0c login prompt
  and each Phase 1.5 social URL. Never batch. In guided mode a choice is an
  AskUserQuestion call, a fill-in-the-blank is the bold last line of its own
  message, and you never narrate how or why you are asking.
- **Never block setup on HQ Cloud.** Login, invite-claim, and sync (Phase 0c) are
  best-effort; a solo or offline HQ completes setup fine. There is no
  list-pending-invites command — invites are claimed by running sync.
- **Browser harness is optional.** Prefer the Claude for Chrome harness (Codex
  equivalent in Codex) so login-walled profiles are readable; if the user
  declines, fall back to public `WebFetch` + `WebSearch` and skip walled sources.
  Never block on the extension.
- **Delegate browser reads + scrape synthesis to a subagent** that returns text
  only — keep raw pages and screenshots out of the parent session (HQ context
  diet; stay under the image cap). Persist only synthesized understanding, never
  raw dumps or credentials.
- **The welcome page is private** and contains personal understanding — set
  `/deploy` access mode to owner-only manually; don't trust the filename-only
  sensitivity verdict.
- **`impeccable` is optional** — use it for the welcome page if present, else
  produce a high-quality inline design. Degrade gracefully.
- **Inline vs handoff:** scaffold lightweight, high-momentum items inline during
  setup (`/newcompany`, `/idea`, a knowledge doc, a `hq secrets generate-link`
  connection). Heavy / context-hungry work (`/plan`, `/discover`, deep
  planning) is recommended for a fresh session — never run inline. This honors
  HQ context hygiene while still delivering first-session momentum.
- **Secret-link / share / deploy URLs are capabilities** — surface inline at mint
  or publish time only. Never write them into `getting-started-next-steps.md`,
  `systems-of-record.md`, `social-presence.md`, or any later turn
  (`hq-share-session-urls-are-capabilities`).
- Use defaults when user says "skip"
- Never overwrite existing files without asking
- Create parent directories as needed
- **Install missing dependencies and CLI tools directly — never ask.** Do not
  prompt "do you want to install X?" and never surface an install-all / some /
  none picker for tooling; the standard install command runs unattended. The one
  exception is an interactive auth that can't run unattended (e.g. `gh auth
  login`). Don't block setup if an optional tool's install fails — note it in the
  summary and move on. These are "recommended" not "required" (except claude itself).
- On the rare occasion a symlink is genuinely needed (never for knowledge — knowledge repositories are real directories at their canonical paths), use a relative target, not an absolute path
- Phase 4/5 are skippable — if the user says "skip", still write `personal/knowledge/getting-started-next-steps.md` using best-effort defaults from Phase 1 answers. Never block setup completion on the orientation or interview
- Phase 6 (welcome page) is skippable — if the user isn't signed in or declines,
  skip the `/deploy` and just deliver the launch block + handoff message in chat.
  Never block setup completion on the deploy