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.

Phase 0a: Install Manifest Recovery

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"
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:

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

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

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.

Phase 1: Identity

Ask these 5 questions. One at a time. 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:

# {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 1.6: Adopt prior AI footprint

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. 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 2.
• 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.)

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 2.
• 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.
• 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).

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/.

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.

For each knowledge base the user wants to create:

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"