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.

HQ Desktop: the Setup bot

Current HQ Desktop (0.10.347, verified against hq-desktop-app origin/main@c621a6a1 on 2026-09-27) runs guided setup as a chat with the Setup bot, not as a stepped card. Run Setup on #welcome creates a personal local bot named setup from the worker template core/workers/public/setup (hq bot create setup --worker setup). The person talks to it in its DM. The bot walks the phases of this skill in plain words and follows core/workers/public/setup/worker.yaml, which overrides the guided-mode rules below: it never prints [hq-setup] lines and never uses multiple-choice pickers.

The Setup bot can end a message with hq-block fences that the desktop turns into UI. The fence is three backticks followed by hq-block on the same line, the JSON on its own line, then three closing backticks, not indented, and nothing after it:

• Suggested replies — {"v":1,"blocks":[{"kind":"suggestions","items":["For a company","Just for me"]}]}. Two to four short replies; the app keeps at most 4, drops duplicates, and caps each at 80 characters. They show as buttons under the bot's newest message and a click sends the text as the person's reply. The app always adds its own "Something else" button, so do not add an "Other" item. Leave them out when only the person can type the answer (names, emails, URLs).
• Setup finished — {"v":1,"blocks":[{"kind":"setupDone"}]}, or {"v":1,"blocks":[{"kind":"setupDone","slackAgent":true}]} for someone who started their own company, which adds a "put the bot in Slack" offer. Send it once, as the last thing in the closing message, never together with suggestions. The app shows a finish card until the person writes again.

In the current app the desktop acts on these two blocks only in the Setup bot's DM. Full contract: core/knowledge/public/hq-core/desktop-rich-messages.md.

Guided mode (legacy scripted run): --guided

Older HQ Desktop builds ran this skill as a scripted session on #welcome, drawn as a stepped card, started with /setup --guided. The step and card parsers are still in the app source, but the current app no longer starts that session (the in-app session engine was removed in 0.10.270), and the Setup bot's DM does not strip marker lines. Follow these rules only when the arguments actually 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).

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:

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"
# Windows (Git Bash): the toolchain is %LOCALAPPDATA%\IndigoHQ\toolchain, with
# node.exe in node/ and npm shims in npm-prefix/. Without this every tool
# reports MISSING even when the managed toolchain is installed.
if [ -n "${LOCALAPPDATA:-}" ] && command -v cygpath >/dev/null 2>&1; then
  for d in node npm-prefix npm-global/bin; do
    [ -d "$(cygpath -u "$LOCALAPPDATA")/IndigoHQ/toolchain/$d" ] && export PATH="$(cygpath -u "$LOCALAPPDATA")/IndigoHQ/toolchain/$d:$PATH"
  done
fi
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 → the HQ root has no Git repo; run git init && git add . && git commit -m "init" from the HQ root only. This installer step does not apply to company directories.

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:

# 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, the exact pin from core/scripts/install-deps.allow (the
# version Desktop installs). Newer unpinned qmd has no better-sqlite3 binary on
# Windows and crashes on every command. 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@2.5.3
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

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:

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:

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:

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, X) 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, X) 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: for X / Twitter, say in one plain line that it is skipped and use WebSearch "{name} {handle}" to fill gaps. Never WebFetch x.com or twitter.com. For other public profiles, WebFetch the page and use WebSearch 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:

# {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/. Company knowledge always stays a plain directory with no Git metadata; personal knowledge may use embedded Git when independent version history is needed. Never symlink knowledge into repos/.

mkdir -p repos/public repos/private

Personal scaffold

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. Company knowledge must remain a plain directory; do not initialize Git inside it. Add a company through /newcompany {slug}, which creates that directory and records its path in the manifest.

For each personal knowledge base that needs separate version history:

1. Create the directory and embedded git repo:

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:

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:

# 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, HQ Git tracks personal/knowledge/ as a plain directory. This works for single-machine setups. Company knowledge stays plain and syncs through its vault.

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/. Personal knowledge may use embedded Git for separate
version history. Company knowledge must stay a plain directory; never initialize
Git there or move it into repos/ and symlink it back.

Profile files

personal/knowledge/profile.md:

# {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):

# {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:

# {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):

# {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):

# {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

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 directories:
Personal knowledge bases are real directories under personal/knowledge/ and may
use embedded Git for independent version history. Company knowledge lives in a
plain directory under companies/{slug}/knowledge/ and syncs through the company
vault. Knowledge directories are never symlinked into HQ.
See "Knowledge directories" 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, /prd, /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:

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:

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:

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: /prd (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 / /prd / /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: /prd 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 (/prd, /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