[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71E25G08MWSW7XJHCGHPPZY":3,"skill-same:01M71E25G08MWSW7XJHCGHPPZY":73},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":50,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M71E25G08MWSW7XJHCGHPPZY","setup",null,"Run the HQ Starter Kit setup wizard.","indigoai-us\u002Fhq-core","indigoai-us","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F122242446?v=4","01M71DTQ5NGD10GT1Z7E6XKWC5","HQ","01M71DTQ6BKSYYBNC9RAKT3YDK",94,"MIT","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsetup\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[5,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"wizard","kit","MCP","run","read","write","edit","Bash","websearch","setup wizard","chrome","task","starter","webfetch","2026-11-10 10:12:30",false,"---\nname: setup\ndescription: Run the HQ Starter Kit setup wizard.\nallowed-tools: Read, Write, Edit, AskUserQuestion, Glob, Bash, Task, WebFetch, WebSearch, Skill, mcp__Claude_in_Chrome__*\n---\n\n# HQ Setup Wizard\n\nGet your HQ running: dependencies, HQ Cloud (login + sync), a profile built from\nwho you are, and a private welcome page that hands you your first moves. One\nquestion at a time; nothing here is mandatory — skip anything and setup still\ncompletes.\n\n## HQ Desktop: the Setup bot\n\nCurrent HQ Desktop (0.10.347, verified against hq-desktop-app\n`origin\u002Fmain@c621a6a1` on 2026-09-27) runs guided setup as a chat with the\n**Setup bot**, not as a stepped card. Run Setup on `#welcome` creates a\npersonal local bot named `setup` from the worker template\n`core\u002Fworkers\u002Fpublic\u002Fsetup` (`hq bot create setup --worker setup`). The\nperson talks to it in its DM. The bot walks the phases of this skill in plain\nwords and follows `core\u002Fworkers\u002Fpublic\u002Fsetup\u002Fworker.yaml`, which overrides the\nguided-mode rules below: it never prints `[hq-setup]` lines and never uses\nmultiple-choice pickers.\n\nThe Setup bot can end a message with `hq-block` fences that the desktop turns\ninto UI. The fence is three backticks followed by `hq-block` on the same line,\nthe JSON on its own line, then three closing backticks, not indented, and\nnothing after it:\n\n- **Suggested replies** — `{\"v\":1,\"blocks\":[{\"kind\":\"suggestions\",\"items\":[\"For a company\",\"Just for me\"]}]}`.\n  Two to four short replies; the app keeps at most 4, drops duplicates, and\n  caps each at 80 characters. They show as buttons under the bot's newest\n  message and a click sends the text as the person's reply. The app always\n  adds its own \"Something else\" button, so do not add an \"Other\" item. Leave\n  them out when only the person can type the answer (names, emails, URLs).\n- **Setup finished** — `{\"v\":1,\"blocks\":[{\"kind\":\"setupDone\"}]}`, or\n  `{\"v\":1,\"blocks\":[{\"kind\":\"setupDone\",\"slackAgent\":true}]}` for someone who\n  started their own company, which adds a \"put the bot in Slack\" offer. Send\n  it once, as the last thing in the closing message, never together with\n  `suggestions`. The app shows a finish card until the person writes again.\n\nIn the current app the desktop acts on these two blocks only in the Setup\nbot's DM. Full contract: `core\u002Fknowledge\u002Fpublic\u002Fhq-core\u002Fdesktop-rich-messages.md`.\n\n## Guided mode (legacy scripted run): `--guided`\n\nOlder HQ Desktop builds ran this skill as a scripted session on `#welcome`,\ndrawn as a stepped card, started with `\u002Fsetup --guided`. The step and card\nparsers are still in the app source, but the current app no longer starts\nthat session (the in-app session engine was removed in 0.10.270), and the\nSetup bot's DM does not strip marker lines. Follow these rules only when the\narguments actually contain `--guided`:\n\n- **Emit a step marker at every phase boundary**, on its own line, exactly:\n  `[hq-setup] step=\u003Cid> status=\u003Crunning|done>`. The ids, in order, and the\n  phases they cover:\n\n  | step      | phases                                   |\n  |-----------|------------------------------------------|\n  | `tools`   | 0a, 0b                                   |\n  | `cloud`   | 0c                                       |\n  | `import`  | 0d (adopt prior AI footprint)            |\n  | `you`     | 1, 1.5, 2, 3, 4, 4.5, 5a, 5b             |\n  | `connect` | 5b.5 (secrets), 5b.6 (apps)              |\n  | `moves`   | 5c, 5d, 5e, 5f, 6                        |\n\n  Emit `status=running` when a phase group starts and `status=done` when it\n  ends. Never go backwards; skipping a whole group is fine — mark it `done`.\n- **Emit a card marker right before the question it belongs to**, on its own\n  line: `[hq-setup] card=\u003Cone-line JSON>`. The desktop draws the card in place\n  of the plain option list and answers the *same* AskUserQuestion. Three kinds:\n  - `{\"kind\":\"found\",\"title\":\"…\",\"items\":[{\"label\":\"…\",\"count\":12,\"detail\":\"…\"}]}`\n    — \"Here's what I found\", paired with the Import question (0d).\n  - `{\"kind\":\"secret\",\"name\":\"DATABASE_URL\",\"label\":\"…\",\"hint\":\"…\",\"scope\":\"personal|company\",\"company\":\"\u003Cslug>\"}`\n    — one credential; the desktop stores it straight into the vault and\n    answers `Done`. Paired with a `header: \"Secret\"` question with options\n    `Done` \u002F `Skip` (5b.5). **In guided mode do not mint a `generate-link`\n    URL** — the card is the intake.\n  - `{\"kind\":\"integrations\",\"items\":[{\"id\":\"\u003CentryId>\",\"name\":\"…\",\"description\":\"…\",\"auth\":\"oauth|none\",\"status\":\"connected|available\"}]}`\n    — app tiles, paired with a multi-select `header: \"Integrations\"` question\n    whose option labels are the app names plus `Skip for now` (5b.6).\n- **Two ways to ask, and only two.** A choice (2–4 options) is one\n  AskUserQuestion call. A fill-in-the-blank (name, what you do, goals,\n  challenges, systems of record, role, typical day, a URL) is asked in plain\n  words as the **last line of the message, in bold, ending with a question\n  mark** — one question per message, then stop and wait; the person types\n  the answer in the chat. Never bundle several questions into one message,\n  never number them, and never ask a fill-in-the-blank through AskUserQuestion\n  (the runtime needs real options; a fake \"Skip\" option is not a question).\n- **Speak only to the person, never about the mechanics.** The desktop shows\n  your words as a \"Setup Agent\" chat. Do not mention pickers, tools,\n  AskUserQuestion, markers, phases, modes, \"the desktop\", or why you are\n  asking a question one way rather than another (\"that one's a\n  fill-in-the-blank, so I'll ask it straight\" is exactly what not to say).\n  Say what you are doing for them and ask the question — nothing else.\n- **Markers are plain lines, never in backticks or code fences**, one per\n  line, at the start of the message. A marker line is never the whole message\n  — put a one-sentence plain status beside it so the card has something to say.\n- One question at a time, plain words. The finish: emit\n  `[hq-setup] step=moves status=done` on its own line, then the closing\n  summary in ordinary Markdown (headings, bullets), not a code block.\n- Without `--guided` (a terminal), emit no markers and no cards, and use the\n  terminal flows described in each phase (e.g. the secret link in 5b.5).\n\n## Phase 0a: Install Manifest Recovery\n\n*(guided: `[hq-setup] step=tools status=running`)*\n\nBefore anything else, check if the HQ Installer left a manifest. HQ Desktop\nwrites it to the USER'S home (`~\u002F.hq\u002Finstall-manifest.json`); older installers\nwrote it inside the HQ folder. Check both — reading only `.hq\u002F` inside HQ made\n`\u002Fsetup` believe nothing was installed and re-run `npm install -g` with the\nsystem npm on every run (prefix conflicts, permission errors, supply-chain\nblock; reported 2026-08-28).\n\n```bash\ncat ~\u002F.hq\u002Finstall-manifest.json 2>\u002Fdev\u002Fnull || cat .hq\u002Finstall-manifest.json 2>\u002Fdev\u002Fnull\n```\n\nThen, BEFORE declaring any dependency missing, put HQ's managed toolchain on\nPATH for this session — the installer puts tools there, and a GUI-launched or\nhook-launched shell often does not see them:\n\n```bash\nexport PATH=\"$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\u002Fnode\u002Fbin:$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\u002Fnpm-global\u002Fbin:$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\u002Fgit-shim:$HOME\u002F.local\u002Fbin:$PATH\"\n# Windows (Git Bash): the toolchain is %LOCALAPPDATA%\\IndigoHQ\\toolchain, with\n# node.exe in node\u002F and npm shims in npm-prefix\u002F. Without this every tool\n# reports MISSING even when the managed toolchain is installed.\nif [ -n \"${LOCALAPPDATA:-}\" ] && command -v cygpath >\u002Fdev\u002Fnull 2>&1; then\n  for d in node npm-prefix npm-global\u002Fbin; do\n    [ -d \"$(cygpath -u -- \"$LOCALAPPDATA\")\u002FIndigoHQ\u002Ftoolchain\u002F$d\" ] && export PATH=\"$(cygpath -u -- \"$LOCALAPPDATA\")\u002FIndigoHQ\u002Ftoolchain\u002F$d:$PATH\"\n  done\nfi\nfor t in node npm qmd hq git yq jq; do printf '%-5s %s\\n' \"$t\" \"$(command -v $t || echo MISSING)\"; done\n```\n\nNewer manifests record the dependency stage only as `steps.deps` (the\n`dependencies` map is empty); use the PATH check above as the source of truth\nfor what is actually present. On a Mac without Xcode Command Line Tools,\n`\u002Fusr\u002Fbin\u002Fgit` and `\u002Fusr\u002Fbin\u002Fpython3` are stubs that pop an install dialog —\nnever call them; the managed `git-shim` is the real git.\n\nIf no manifest exists, skip to Phase 0b — the user installed manually or is running setup for the first time.\n\nIf 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.\n\n### Triage priority (handle in this order)\n\n**P0 — Blocking (fix these first, setup can't proceed without them):**\n- `steps.directory` failed or missing → HQ directory doesn't exist; abort setup and tell user to re-run installer\n- `steps.templates` failed → HQ template not fetched; attempt `npx --package=@indigoai-us\u002Fhq-cli hq init .`\n- `dependencies.node` failed → nothing works; guide user through Node install\n- `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.\n\n**P1 — Required (HQ works poorly without these):**\n- `dependencies.qmd` failed → no semantic search; install the SANCTIONED pin (see `core\u002Fscripts\u002Finstall-deps.allow`): `npm install -g @tobilu\u002Fqmd@2.5.3`, then `qmd index .`. Unpinned installs are blocked by the supply-chain guard on purpose.\n- `dependencies.claude-code` failed → can't run workers; `npm install -g @anthropic-ai\u002Fclaude-code@\u003Cversion>` (explicit version pin required by the guard)\n- `dependencies.yq` failed → can't parse YAML configs; `brew install yq` or download binary\n- `dependencies.hq-cli` failed → can't install packs or sync; `npm install -g @indigoai-us\u002Fhq-cli@\u003Cversion>` (explicit version pin required by the guard)\n- `steps.indexing` failed → search won't work; run `qmd index .` directly\n- `packs` with status `\"failed\"` or `\"running\"` (interrupted) → retry each: `npx --package=@indigoai-us\u002Fhq-cli hq install {pack-name}`\n\n**P2 — Recommended (HQ works but some features limited):**\n- `dependencies.gh` failed\u002Fskipped → no PR workflows; install directly: `brew install gh` (then `gh auth login` — the browser auth is the one warranted prompt)\n- `dependencies.homebrew` skipped → limits future installs; install directly (best-effort; skip silently if the platform install can't run unattended)\n- `steps.personalize` failed → profile not set up; Phase 1 below will cover this\n\n### Remediation flow\n\n**Install missing dependencies and CLI tools directly — never ask whether to\ninstall them, and never surface an \"install all \u002F install some \u002F skip all\"\npicker.** A user running `\u002Fsetup` has already opted into getting HQ working; a\nmid-setup \"do you want these tools?\" question is pure friction. The install\ncommands in the triage lists above are safe, idempotent, and non-blocking — just\nrun them. This includes P2 items (`gh`, `homebrew`): install them directly too.\n\nFor each issue found (in priority order):\n\n1. **Install it directly, silently.** Run the item's install command (from the\n   triage lists above), best-effort. Do not pause for permission, do not\n   explain-then-ask, and do not offer install-method choices — pick the standard\n   method and run it.\n2. **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,\n   move on without narrating it. If it failed, try one alternative, then record\n   it under \"Still needs attention\" in the summary and keep going — never block\n   setup on a failed optional tool.\n3. **The only permitted prompt in this phase is a genuine interactive auth** that\n   cannot run unattended (e.g. `gh auth login`, which opens a browser).\n   *Installing* a tool is never that case — installs are always direct.\n4. **Bootstrap dependencies are the one install exception.** A P0 that cannot be\n   installed unattended from within setup — Node itself (nothing runs without it,\n   and there is no npm to install it with), or a platform package manager on a\n   machine that has none (e.g. Homebrew on a bare macOS) — falls back to *guiding*\n   the user through that one install, per its triage entry. This is not the\n   tool-choice picker the rule forbids; it is the narrow \"we literally cannot do\n   this for you\" case. Everything installable via npm \u002F an existing package\n   manager still installs directly, no prompt.\n\n### After remediation\n\nOnce all issues are addressed, show a summary:\n\n```\nInstall recovery complete.\n\nFixed:\n  ✓ {item} — {what was done}\n  ...\n\nSkipped (optional):\n  ○ {item} — {why it's optional}\n  ...\n\nStill needs attention:\n  ✗ {item} — {what went wrong, what user can do}\n  ...\n```\n\nSkip 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.\n\n## Phase 0b: Dependencies + auth checks (non-manifest)\n\nIf Phase 0a ran, skip any deps already checked there. This phase covers the\nfresh \u002F manual install case where there is **no** install manifest — the tools\nthe wizard leans on may simply not be present yet.\n\n**Missing tools — install directly, never ask.** When there's no manifest, probe\nthe core tooling and install whatever is missing, best-effort and silently. Do\n**not** present an \"install all \u002F some \u002F none\" choice — a user running `\u002Fsetup`\nwants HQ working, so install and move on:\n\n```bash\n# hq-cli — honor the native installer's managed toolchain before system npm.\n# GUI-launched Claude\u002FCodex sessions do not source the shell profile that the\n# installer writes, so `command -v hq` alone can miss this already-installed\n# binary. Do not consult `~\u002F.hq`: the install manifest belongs to this HQ root.\nHQ_MANAGED_TOOLCHAIN=\"$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\"\nHQ_MANAGED_HQ_BIN=\"$HQ_MANAGED_TOOLCHAIN\u002Fnpm-global\u002Fbin\"\nHQ_MANAGED_NODE_BIN=\"$HQ_MANAGED_TOOLCHAIN\u002Fnode\u002Fbin\"\nif [ -x \"$HQ_MANAGED_HQ_BIN\u002Fhq\" ]; then\n  # Prepend in reverse order so the managed Node resolves the hq shebang.\n  for bin in \"$HQ_MANAGED_HQ_BIN\" \"$HQ_MANAGED_NODE_BIN\"; do\n    if [ -d \"$bin\" ]; then\n      case \":$PATH:\" in\n        *\":$bin:\"*) ;;\n        *) export PATH=\"$bin:$PATH\" ;;\n      esac\n    fi\n  done\nfi\ncommand -v hq >\u002Fdev\u002Fnull 2>&1 || npm install -g @indigoai-us\u002Fhq-cli\n\n# qmd — npm global, the exact pin from core\u002Fscripts\u002Finstall-deps.allow (the\n# version Desktop installs). Newer unpinned qmd has no better-sqlite3 binary on\n# Windows and crashes on every command. On macOS it loads SQLite extensions the\n# built-in sqlite3 can't, so ensure Homebrew SQLite is present regardless of\n# whether qmd itself was already installed.\ncommand -v qmd >\u002Fdev\u002Fnull 2>&1 || npm install -g @tobilu\u002Fqmd@2.5.3\nif [ \"$(uname)\" = \"Darwin\" ] && command -v brew >\u002Fdev\u002Fnull 2>&1; then\n  brew list sqlite >\u002Fdev\u002Fnull 2>&1 || brew install sqlite\nfi\n\n# gh — pick the platform-appropriate installer (brew \u002F apt \u002F winget); best-effort.\nif ! command -v gh >\u002Fdev\u002Fnull 2>&1; then\n  if   command -v brew    >\u002Fdev\u002Fnull 2>&1; then brew install gh\n  elif command -v apt-get >\u002Fdev\u002Fnull 2>&1; then sudo apt-get update && sudo apt-get install -y gh\n  elif command -v winget  >\u002Fdev\u002Fnull 2>&1; then winget install --id GitHub.cli -e --source winget\n  fi\nfi\n```\n\nVerify each with `command -v {tool}` afterward. If an install fails (or no\nsupported installer is available on this platform), note it under \"Still needs\nattention\" in the Phase 3 summary and continue — never block setup on a failed\noptional tool.\n\n**Auth checks** (not tracked by manifest):\n- `gh auth status` — if gh is installed but not authenticated, offer `gh auth login`\n  (a browser auth is the one place a prompt is warranted; installing gh is not).\n\nDo **not** check for or install third-party deploy CLIs (e.g. the Vercel CLI) here.\nHQ's own features never shell out to them — `\u002Fdeploy` targets hq-deploy\ninfrastructure, not Vercel — so they are not HQ setup dependencies. They are\nuser-provided tools, installed on-demand by the user only when deploying their\nown projects to their own pipeline; point-of-use guidance lives in the relevant\npolicy (e.g. `core\u002Fpolicies\u002Fhq-vercel.md`), not in setup.\n\nPost-install: run `qmd index .` if qmd was just installed or no index exists.\n\n*(guided: `[hq-setup] step=tools status=done` once 0a\u002F0b are through)*\n\n## Phase 0c: HQ Cloud — login, claim invites, ensure sync\n\n*(guided: `[hq-setup] step=cloud status=running`)*\n\nConnect this HQ to HQ Cloud so the user lands logged in, with any cloud-company\ninvites claimed and sync working. Do this **before** identity so synced company\ncontext can inform the rest of the wizard, and so the welcome-page `\u002Fdeploy`\n(Phase 6) is already authenticated. One question at a time. Solo \u002F offline HQ is\nfine — never block setup on cloud.\n\n### 1. Confirm Cognito login\n\n```bash\nhq auth status 2>\u002Fdev\u002Fnull\n```\n\n- **Signed in, token valid** → continue. Show identity: `hq whoami`.\n- **Token expired** → try a silent refresh first: `hq auth refresh`.\n- **Not signed in, or refresh failed** → ask one question: \"Sign in to HQ Cloud\n  now? (unlocks team sync, shared knowledge, and publishing)\". If yes, run the\n  `\u002Fhq-login` skill (browser Cognito login). If they decline, note that cloud\n  features (sync, `\u002Fdeploy`, shared companies) are unavailable until they run\n  `\u002Fhq-login`, and skip the rest of Phase 0c.\n\nThere is **no command that lists \"companies I've been invited to.\"** Modern\ninvites are email-keyed and claimed automatically the first time sync runs (the\nsync-runner \"claim dance\"). So do not promise an invite list — claim them via\nsync in step 2.\n\n### 2. Ensure sync + claim invites\n\nOnce signed in, run a full sync via the `\u002Fhq-sync` skill (engine:\n`hq sync pull --all` \u002F `hq-sync-runner --companies --direction both`). This fires\nthe claim dance — auto-accepting any email-keyed pending invites — and pulls\nevery cloud company the user belongs to.\n\nThe runner emits `setup-needed` when a run cannot proceed. It carries a `reason`\nand, when relevant, a `pendingInviteCount` — read both and act on them. Do NOT\nfall through to the solo path on a bare `setup-needed`:\n\n- `reason: \"no-memberships\"` with `pendingInviteCount > 0` — the user has an\n  invite that has not been accepted. Say so, and tell them to run\n  `\u002Faccept \u003Clink-or-token>`, then re-run sync. This is the single most common\n  reason someone is wrongly told they are solo.\n- `reason: \"no-memberships\"` with no pending invites — genuinely no company yet.\n  The solo path is correct here.\n- `reason: \"no-person-entity\"` — signed in, but there is no personal entity to\n  sync into. Usually a **legacy magic-link** invite; point them to\n  `\u002Faccept \u003Clink-or-token>` to redeem it, then re-run sync.\n- If sync errors (network, transport), report it plainly and continue.\n\nAn older runner emits `setup-needed` with no `reason` at all. Treat that as\n\"unknown — do not conclude solo\", and offer `\u002Faccept` rather than asserting the\nuser has no team.\n\n### 3. Report what landed\n\n**Membership is the source of truth here, not the manifest file.** A newly\ninvited member's `companies\u002Fmanifest.yaml` arrives as the stock empty template\nsynced from their personal vault, so grepping it reports \"solo\" for someone who\ndemonstrably belongs to a company. That is the exact bug this step exists to\navoid re-introducing.\n\nResolve the company list in this order:\n\n1. **The runner's `fanout-plan` event** from the sync you just ran. It lists\n   every company target the run resolved, with slug and name. This is free —\n   you already have it.\n2. **`GET \u002Fmembership\u002Fme`** via the vault client, if you need to resolve\n   membership without a sync in hand.\n3. **The manifest grep, fallback only** — use it when the API is unreachable,\n   and say that the answer is local-only:\n\n```bash\ngrep -E \"^  [a-z0-9-]+:\" companies\u002Fmanifest.yaml 2>\u002Fdev\u002Fnull | sed -E 's\u002F^  ([a-z0-9-]+):.*\u002F\\1\u002F'\n```\n\nThen report:\n\n- Companies resolved → \"You're connected and synced. You're in: {names}.\" Name\n  the companies. A user who was just told they are on a team and cannot see\n  which one has not actually been told anything.\n- API says companies exist but the manifest grep disagrees → report the API\n  answer, and note that local routing has been repaired (the sync runner\n  reconciles the manifest entry and seeds `activeCompany` on the way through;\n  a freshly written manifest propagates on the NEXT sync).\n- Nothing resolved, and no pending invites → \"You're signed in. No cloud\n  companies yet — you're solo for now, that's fine.\"\n\nKeep Phase 0c to a few plain lines; the heavy lifting is the reused skills.\n\n*(guided: `[hq-setup] step=cloud status=done`)*\n\n## Phase 0d: Adopt prior AI footprint\n\n*(guided: `[hq-setup] step=import status=running`)*\n\nIf the user already used AI tools before HQ — Claude Code, Codex, Grok, or\nclaude.ai chat — they have two kinds of prior context worth adopting: artifacts\non disk (skills, hooks, policies, plans, MCP servers, repos in `~\u002F.claude\u002F` and\ncommon code dirs) and **conversation history** (Claude Code, Codex, and Grok\nsession stores, plus claude.ai chats via export). Hydrating both into HQ now\nmeans the rest of the wizard — Dream Big (4.5), the action interview (5) —\nreflects the companies, knowledge, policies, and projects they already have,\ninstead of starting from a blank slate. This is the `\u002Fimport-context` skill\n(formerly `\u002Fimport-claude`), surfaced as a first-class setup step, and it runs\n**before** identity so the rest of the wizard already knows what they brought.\nOne question at a time; never block setup — a clean install with no prior\nfootprint flows straight past this.\n\n### 1. Detect a prior footprint (cheap, read-only)\n\n`\u002Fimport-context` requires `companies\u002Fmanifest.yaml` to exist (a fresh `hq init`\nships it). If it's missing, skip this phase. Otherwise do a quick existence probe\nof the scanner's main allowlist plus the conversation stores — do **not** run\nthe full scan here, just decide whether there's plausibly anything to import:\n\n```bash\ntest -f companies\u002Fmanifest.yaml || echo \"no-manifest-skip\"\n# Probe the highest-signal locations; any non-empty hit means \"offer the import\".\nfor d in \"$HOME\u002F.claude\u002Fplans\" \"$HOME\u002F.claude\u002Fcommands\" \"$HOME\u002F.claude\u002Fskills\" \\\n         \"$HOME\u002F.claude\u002Fprojects\" \"$HOME\u002F.claude\u002Fagents\" \\\n         \"$HOME\u002F.codex\u002Fsessions\" \"$HOME\u002F.grok\u002Fsessions\"; do\n  [ -d \"$d\" ] && find \"$d\" -mindepth 1 -maxdepth 2 -print -quit 2>\u002Fdev\u002Fnull\ndone\n```\n\n- **No manifest, or every probe is empty** → print one plain line (\"No prior\n  AI footprint to import — starting fresh.\") and continue to Phase 1.\n- **Any probe returns a path** → there's plausibly something to adopt; offer it\n  in step 2. (The authoritative scan, with counts and redaction, happens inside\n  `\u002Fimport-context` itself — keep this probe lightweight.)\n\n**Guided mode:** before offering, count what the probe hit (still read-only,\nstill cheap) and emit a `found` card with only the non-zero rows, then the\nstep-2 question. For example:\n\n```bash\nfor pair in \"Claude Code sessions:$HOME\u002F.claude\u002Fprojects:*.jsonl\" \\\n            \"Plans:$HOME\u002F.claude\u002Fplans:*\" \"Commands:$HOME\u002F.claude\u002Fcommands:*\" \\\n            \"Skills:$HOME\u002F.claude\u002Fskills:*\" \"Agents:$HOME\u002F.claude\u002Fagents:*\" \\\n            \"Codex sessions:$HOME\u002F.codex\u002Fsessions:*\" \"Grok sessions:$HOME\u002F.grok\u002Fsessions:*\"; do\n  label=${pair%%:*}; rest=${pair#*:}; dir=${rest%%:*}; glob=${rest#*:}\n  [ -d \"$dir\" ] && n=$(find \"$dir\" -mindepth 1 -maxdepth 3 -name \"$glob\" 2>\u002Fdev\u002Fnull | wc -l | tr -d ' ') || n=0\n  [ \"$n\" -gt 0 ] && echo \"$label=$n\"\ndone\n```\n\n```\n[hq-setup] card={\"kind\":\"found\",\"title\":\"Here's what I found\",\"items\":[{\"label\":\"Claude Code sessions\",\"count\":12},{\"label\":\"Plans\",\"count\":3}]}\n```\n\n### 2. Offer the import (AskUserQuestion)\n\nOne AskUserQuestion call:\n\n- `question`: \"Looks like you've used Claude Code, Codex, or Grok before. Want\n  me to import your existing skills, plans, and repos — and mine your past\n  conversations for proposed companies, knowledge, and projects — now? You\n  approve every item before it's created.\"\n- `header`: \"Import\"\n- `multiSelect`: false\n- `options`:\n  - `Import now` — \"Run \u002Fimport-context inline — discovers your artifacts,\n    mines your conversation history across tools, and proposes companies,\n    knowledge, policies, and projects (you confirm each step)\"\n  - `Preview first` — \"Scan and show me what's there, import nothing yet\n    (\u002Fimport-context --dry-run)\"\n  - `Skip` — \"Don't import; I'll run \u002Fimport-context later if I want\"\n\n### 3. Run it\n\n- **Import now** → inline-invoke the `\u002Fimport-context` skill via the Skill tool.\n  It runs its own preflight, scan, redaction, conversation mining, and\n  per-category triage — every write is gated by its own AskUserQuestion prompts,\n  so you don't re-ask here. If the user mentions claude.ai chats, pass\n  `--claude-export=\u003Cpath>` once they have a data export (claude.ai → Settings →\n  Privacy → Export data). When it returns, briefly note what landed (companies\n  created, knowledge seeded, projects proposed, workers synthesized, repos\n  adopted) in one plain line, then continue to Phase 1.\n\n  **Guided mode:** show what landed as a card, not a sentence. Emit a `found`\n  card titled \"What landed\" with one row per outcome that is non-zero\n  (companies created, knowledge files seeded, projects proposed, workers,\n  repos adopted — `detail` names them, e.g. `\"detail\":\"acme, northwind\"`),\n  then one AskUserQuestion — `header`: \"Import\", `question`: \"Here's what the\n  import brought in. Good to go on?\", options `Looks good` \u002F `Let me review`\n  (\"Open the import report before moving on\"). On `Let me review`, print the\n  report path and the per-category list, then re-ask once.\n- **Preview first** → inline-invoke `\u002Fimport-context --dry-run`. It scans and\n  reports counts without importing. After it returns, ask once whether to run the\n  real import now (re-invoke `\u002Fimport-context` without the flag) or defer. If they\n  defer, treat it as Skip.\n\n  **Guided mode:** the person chose Preview to *see* what is there, so the\n  scan result must be the card, not prose. Build a `found` card titled\n  \"What's there\" from the dry-run's counts-per-category summary — one row\n  per non-zero category in plain words (`Plans`, `MCP servers`, `Settings`,\n  `Commands`, `Skills`, `Hooks`, `Policies`, `CLAUDE.md files`, `Knowledge\n  folders`, `Repos`, `Agents`, `Conversations` with the per-tool breakdown as\n  `detail`) — emit it, then ask the run-now-or-skip question (`header`:\n  \"Import\", options `Import now` \u002F `Skip for now`).\n- **Skip** → note that `\u002Fimport-context` is available anytime, and add it to the\n  Phase 5 recommended-commands list so it resurfaces in their launch block.\n\nBecause `\u002Fimport-context` already creates companies (`\u002Fnewcompany`) and workers\n(`\u002Fnewworker`) inline and confirms every write, running it here is the canonical\nway to hydrate the skeleton — do not hand-roll an equivalent import. Whatever it\nbrings in becomes context for Dream Big (4.5) and the action interview (5).\n\n*(guided: `[hq-setup] step=import status=done`)*\n\n## Phase 1: Identity\n\n*(guided: `[hq-setup] step=you status=running`)*\n\nAsk these 5 questions. One at a time — one message per question, the\nquestion as its bold last line. These answers are the strategic frame for\nthe whole wizard — they feed the knowledge files (Phase 2), the Dream Big vision\nblock (Phase 4.5), and every tailored command in the action interview (Phase 5).\nSo gather all five before moving on.\n\n1. **What's your name?**\n2. **What do you do?** (1-2 sentences — your roles, work, domain)\n3. **What are your goals for using HQ?** (what do you want AI workers to help with?)\n4. **What are your biggest challenges or pain points right now?** (what's hard,\n   slow, repetitive, or keeps slipping)\n5. **What are your main systems of record?** (where your truth lives — DB, CRM,\n   Slack, email, analytics, repos, spreadsheets, etc.) For each, capture its\n   **name + type**, and note which ones have a **credential** we could connect\n   later (a connection string, API token, etc.). Don't ask for the secret itself\n   — just whether one exists.\n\nPersonal scope lives at the top-level `personal\u002F` directory (peer of `core\u002F`), not as a company. Workers, knowledge, policies, and skills you create for yourself live under `personal\u002F{type}\u002F...` — they are read directly from `personal\u002F` (the old `core\u002F\u003Ctype>\u002F` symlink mirror was retired), so they load without any mirror step and survive `\u002Fupdate-hq`. (Personal skills surface via the `.claude\u002Fskills\u002Fpersonal:\u003Cname>\u002F` bridge.)\n\n## Phase 1.5: Social presence + browser harness\n\nLearn who the user is from their public presence — and initialize their browser\nharness in the process, so they leave setup ready to have HQ drive the web for\nthem. One question at a time. Everything here is optional; never block setup.\n\n### 1. Frame it\n\nOne short message: \"Let's connect your browser so HQ can learn from your public\npresence — and so you've got a browser harness ready for future work (research,\nfilling forms, pulling data from sites you're logged into).\"\n\n### 2. Detect \u002F initialize the browser harness\n\nCheck whether a browser harness is connected:\n\n- **Claude Code:** call `mcp__Claude_in_Chrome__list_connected_browsers`. If no\n  browser is connected, point the user to install the **Claude for Chrome**\n  extension (the recommended harness), then wait for them to connect and re-check.\n- **Codex:** use the Codex browser tool equivalent if present.\n\nThe browser harness is what makes **login-walled** profiles (LinkedIn,\nInstagram, X) readable — it drives the user's own authenticated session,\nso it sees what they see.\n\n**Fallback (no harness):** if the user declines or can't install the extension,\nfall back to best-effort public fetching with `WebFetch` + `WebSearch`, and tell\nthem up front that login-walled sources (LinkedIn, Instagram, X) will be skipped.\nNever block on the extension.\n\n### 3. Ask for profiles — ONE AT A TIME\n\nAsk for each, accepting \"skip\" for any (use AskUserQuestion, one per call):\n\n1. X \u002F Twitter\n2. LinkedIn\n3. Instagram\n4. Personal website \u002F blog\n5. (optional) GitHub\n\n### 4. Read each source\n\nFor every URL the user provided (these are the user's **own** profiles, so the\nlink-safety suspicion check is satisfied):\n\n- **With harness:** `navigate` to the URL, then `get_page_text` \u002F `read_page`.\n- **Without harness:** for X \u002F Twitter, say in one plain line that it is skipped\n  and use `WebSearch` \"{name} {handle}\" to fill gaps.\n  Never `WebFetch` x.com or twitter.com.\n  For other public profiles, `WebFetch` the page and use\n  `WebSearch` to fill gaps for walled sources.\n\n**Delegate the fetch + synthesis to a subagent** (Task \u002F Agent tool) that returns\na **text summary only** — keep raw pages and any screenshots out of the parent\nsession (HQ context diet; parent stays under the image cap). Ask the subagent for:\nwho they are publicly, what they work on \u002F care about, recurring themes, and\nvoice\u002Ftone cues — plus which sources it couldn't reach.\n\n### 5. Persist the understanding (synthesized, never raw)\n\nWrite only synthesized understanding — never raw page dumps, never credentials,\nnever session URLs. Create the dir first if needed (`mkdir -p personal\u002Fknowledge`):\n\n**personal\u002Fknowledge\u002Fsocial-presence.md:**\n```markdown\n# {Name} — Public Presence\n\n_Synthesized during \u002Fsetup from the profiles below. Refresh anytime._\n\n## Who they are publicly\n{1–2 paragraph synthesis}\n\n## Themes & focus\n- {recurring topic \u002F area}\n\n## Voice & tone cues\n- {observed phrasing, register, what they sound like}\n\n## Profiles\n| Source | Link | Read? |\n|---|---|---|\n| X | {url} | {yes \u002F walled \u002F skipped} |\n| LinkedIn | {url} | {yes \u002F walled \u002F skipped} |\n| ... | | |\n```\n\nHold this understanding in working memory — Phase 2 weaves it into `profile.md`,\n`agents-profile.md`, and `voice-style.md`, and Phase 4.5 + Phase 6 draw on it.\n\n## Phase 2: Generate Files\n\n### Repos directory (required)\n\nCode repos live under `repos\u002Fpublic\u002F` and `repos\u002Fprivate\u002F`. Knowledge bases are **real directories** under `personal\u002Fknowledge\u002F` or `companies\u002F{slug}\u002Fknowledge\u002F`. 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\u002F`.\n\n```bash\nmkdir -p repos\u002Fpublic repos\u002Fprivate\n```\n\n### Personal scaffold\n```bash\nmkdir -p personal\u002F{knowledge,policies,workers,settings,skills,hooks}\n```\n\n### Company structure (only when adding a real company — use `\u002Fnewcompany {slug}` instead)\nFor reference, a company directory looks like:\n```\ncompanies\u002F{slug}\u002F{settings,data,knowledge,workers,policies}\n```\nThe schema and a fillable template live at `companies\u002F_template\u002F`.\n\n### Knowledge directories\n\nPersonal and company knowledge directories must be **real directories** so cloud\nsync uploads document contents. Do **not** symlink `personal\u002Fknowledge\u002F` or\n`companies\u002F{slug}\u002Fknowledge\u002F` into `repos\u002F` — sync records symlinks as vault\nmarkers and teammates receive nothing. Company knowledge must remain a plain\ndirectory; do not initialize Git inside it. Add a company through\n`\u002Fnewcompany {slug}`, which creates that directory and records its path in the\nmanifest.\n\nFor each **personal** knowledge base that needs separate version history:\n\n1. Create the directory and embedded git repo:\n```bash\nmkdir -p personal\u002Fknowledge\u002F{name}\ncd personal\u002Fknowledge\u002F{name}\ngit init\nprintf '# %s Knowledge Base\\n' \"{Name}\" > README.md\ngit add . && git commit -m \"init knowledge repo\"\ncd -\n```\n\nVerify:\n\n```bash\ntest -d personal\u002Fknowledge\u002F{name} && ! test -L personal\u002Fknowledge\u002F{name} \\\n  && echo \"OK: knowledge is a real directory\"\n```\n\n**Optional:** turn all of `personal\u002Fknowledge\u002F` into one git repo for cross-machine sync:\n```bash\n# Only when personal\u002Fknowledge\u002F is still empty or the user confirms migration\nmkdir -p personal\u002Fknowledge\ncd personal\u002Fknowledge\ngit init\nprintf '# Personal Knowledge Base\\n' > README.md\ngit add . && git commit -m \"init personal knowledge\"\ncd -\n```\n\nIf you skip embedded Git, HQ Git tracks `personal\u002Fknowledge\u002F` as a plain directory. This works for single-machine setups. Company knowledge stays plain and syncs through its vault.\n\n**The starter kit's bundled knowledge (Ralph, workers, ai-security-framework, etc.) ships as plain directories. Explain to the user:**\n```\nBundled knowledge (Ralph, workers, security framework) ships as plain directories.\nKeep those real directories in place so upgrades and sync see their contents. Add\npersonal or company-specific knowledge under personal\u002Fknowledge\u002F or\ncompanies\u002F{slug}\u002Fknowledge\u002F. Personal knowledge may use embedded Git for separate\nversion history. Company knowledge must stay a plain directory; never initialize\nGit there or move it into repos\u002F and symlink it back.\n```\n\n### Profile files\n\n**personal\u002Fknowledge\u002Fprofile.md:**\n```markdown\n# {Name}'s Profile\n\n## About\n{Answer from Q2 — enriched with the public-presence synthesis from Phase 1.5 if\navailable. Cross-reference: see personal\u002Fknowledge\u002Fsocial-presence.md.}\n\n## Goals\n{Answer from Q3}\n\n## Challenges\n{Answer from Q4 — the pain points HQ should help attack}\n\n## Systems of Record\n{Answer from Q5, as a table}\n\n| System | Type | Has credential? |\n|---|---|---|\n| {name} | {DB \u002F CRM \u002F Slack \u002F email \u002F analytics \u002F repo \u002F ...} | {yes \u002F no} |\n\n## Preferences\n- Communication style: [to be filled by \u002Fpersonal-interview]\n- Autonomy level: [to be filled by \u002Fpersonal-interview]\n```\n\n**personal\u002Fknowledge\u002Fsystems-of-record.md** (canonical list workers consult to\nknow where the user's truth lives — write full prose, one row per system from\nQ5; `Connection` starts as `capture-only` and flips to `connected` in Phase 5b.5\nwhen a secret-link is minted):\n```markdown\n# {Name}'s Systems of Record\n\nWhere the truth lives. Workers consult this before assuming or re-deriving data.\n\n| System | Type | Has credential? | Connection |\n|---|---|---|---|\n| {name} | {type} | {yes \u002F no} | {capture-only \u002F connected \u002F not yet} |\n\n> To connect a system later: `\u002Fhq-secrets` (mints a link you fill in; the agent\n> never sees the secret). Never paste a credential or a share\u002Fsecret link into\n> this file — those are capabilities, surfaced inline at mint time only.\n```\n\n**personal\u002Fknowledge\u002Fvoice-style.md:**\n```markdown\n# {Name}'s Voice Style\n\n## Observed cues\n{Seed with the voice\u002Ftone cues synthesized in Phase 1.5, if any — e.g. register,\nrecurring phrasing, how they sound publicly. Leave a note if none were captured.}\n\nRun `\u002Fpersonal-interview` to deepen this with your authentic voice and\ncommunication style.\n```\n\n**agents-profile.md** (root level — first line MUST match `# {Name} - Profile` for the inject-local-context.sh hook regex):\n```markdown\n# {Name} - Profile\n\n- **Location**: {city}\n- **Background**: {Answer from Q2 — folded together with the Phase 1.5\n  public-presence synthesis if available}\n\n## Goals\n{Answer from Q3}\n\n## Challenges\n{Answer from Q4 — surfaced every session via inject-local-context.sh so workers\nknow the standing pain points to attack}\n\n## Working Preferences\n\nRun `\u002Fpersonal-interview` to populate the autonomy matrix and communication style.\n\n## Company Roster\n\nFull company\u002Frole context lives in `agents-companies.md` (three tiers: Operate \u002F Client \u002F Portfolio).\n```\n\n**personal\u002Fagents-companies.md** (created empty, populated by `\u002Fpersonal-interview` or manually):\n```markdown\n# {Name} — Company Contexts\n\n> Three tiers: (1) Operate = founder\u002FCEO hats. (2) Client = paid build work. (3) Portfolio = advisory\u002Fequity.\n> Within Operate: active \u002F slow-burn \u002F on hold. `slug` = the key in `companies\u002Fmanifest.yaml`.\n\n## 1. Operate — Founder \u002F CEO hats\n\n_Run `\u002Fpersonal-interview` or edit manually to populate._\n\n## 2. Client work (build, not owned)\n\n## 3. Portfolio \u002F Advisory\n```\n\nAdd to `.gitignore` if not already present:\n```\n# Personal knowledge contents (tracked by embedded git when configured)\npersonal\u002Fknowledge\u002F\n```\n\n### Index\n```bash\nqmd update 2>\u002Fdev\u002Fnull || qmd index . 2>\u002Fdev\u002Fnull || true\n```\n\n## Phase 3: Summary\n\n```\nHQ Setup Complete!\n\nCreated:\n- repos\u002Fpublic\u002F, repos\u002Fprivate\u002F (code repositories only)\n- personal\u002F scaffold (knowledge, policies, workers, settings, skills, hooks)\n- personal\u002Fknowledge\u002Fprofile.md\n- personal\u002Fknowledge\u002Fsystems-of-record.md\n- personal\u002Fknowledge\u002Fsocial-presence.md (if profiles captured in Phase 1.5)\n- personal\u002Fknowledge\u002Fvoice-style.md\n- agents-profile.md\n- agents-companies.md\n- personal\u002Fknowledge\u002F as a real directory (optionally an embedded git repo)\n\nHQ Cloud:\n✓ Signed in {as email} — or \"not connected (run \u002Fhq-login later)\"\n✓ Synced — {N companies} or \"solo, nothing to pull yet\"\n\nDependencies:\n✓ claude (Claude Code CLI)\n✓ qmd (semantic search) — or skipped\n✓ gh (GitHub CLI) — or skipped\n\nStill needs attention:      ← include this block ONLY if a direct install failed\n✗ {tool} — {what failed; the one manual command the user can run to finish it}\n...\n\nKnowledge directories:\nPersonal knowledge bases are real directories under personal\u002Fknowledge\u002F and may\nuse embedded Git for independent version history. Company knowledge lives in a\nplain directory under companies\u002F{slug}\u002Fknowledge\u002F and syncs through the company\nvault. Knowledge directories are never symlinked into HQ.\nSee \"Knowledge directories\" in core\u002Fdocs\u002Fhq\u002FREADME.md for details.\n\nSetup is done. Next: a short orientation + a few questions so I can hand you\nthe exact commands to start your first real work.\n```\n\nDo not print a static next-steps list here. Continue to Phase 4.\n\n## Phase 4: Learn the HQ Mental Model\n\nA brief orientation before the interview. Keep it to roughly a screenful — this\nis a mental model, not a course. Pull the framing from\n`core\u002Fdocs\u002Fhq\u002FUSER-GUIDE.md` rather than reinventing it; do not duplicate the\nhands-on lessons that already live in `\u002Ftutorial`.\n\nPresent this (adapt wording, keep it tight):\n\n```\nHow HQ works — the 60-second model:\n\n  • Sessions are disposable. Start with \u002Fstartwork,\n    do one focused thing, end with \u002Fhandoff (it saves where you left off so\n    the next session resumes exactly there). A fresh session is a feature,\n    not a reset.\n  • Three homes for things: personal\u002F (your overlay — workers, knowledge,\n    policies just for you), companies\u002F (isolated tenants you operate or\n    serve), repos\u002F (all actual code, public or private).\n  • Knowledge compounds. Workers, knowledge docs, and policies you create\n    make every future session smarter — capture learnings, don't re-derive.\n  • Slash commands are the interface. \u002Fnewworker, \u002Fprd, \u002Fdeploy, \u002Fsearch,\n    \u002Fonboard — you drive HQ by naming the capability, not hand-rolling it.\n  • \u002Fsearch (or qmd) finds anything across HQ — knowledge, projects,\n    workers, policies, indexed repos.\n\nGo deeper anytime:\n  • \u002Ftutorial          — hands-on, interactive lessons against your real HQ\n  • \u002Fpersonal-interview — deep dive on your voice + working style so workers\n                          sound and decide like you\n```\n\nThen continue to Phase 4.5 (don't wait for acknowledgement — flow straight in).\n\n## Phase 4.5: Dream Big\n\nBefore the action interview, paint the destination. Ground this entirely in the\nuser's own answers (Q2 what-you-do, Q3 goals, Q4 challenges, Q5 systems of\nrecord) plus the Phase 1.5 public-presence synthesis — generic HQ marketing is\nworse than nothing. Produce **2-3 concrete, tailored scenarios**, each in the\nshape: *their pain point → the HQ capability that attacks it → the outcome they'd\nfeel*. Name the real command in each.\n\n**Templates to adapt — substitute every `\u003C…>` slot with the user's literal Q1-Q5\nwords before emitting. Never print the angle-bracket form to the user.** The `\u003C…>`\nslots are author-time placeholders, not output. If a slot has no matching answer,\ndrop the bullet rather than emit a generic stand-in.\n\nScenario shapes to choose from (pick 2-3 that actually fit the user's answers):\n\n- *Worker for a recurring pain:* \"You said **\u003Ctheir literal Q4 pain point>** eats\n  your time. Build a `\u002Fnewworker` specialist that does exactly that — and it gets\n  smarter every run, so the work compounds instead of repeating.\"\n- *Connect a system, ship a live report:* \"Your truth lives in **\u003Ctheir literal\n  Q5 system, e.g. 'Postgres in Supabase' or 'HubSpot CRM'>**. Connect it once\n  with `hq secrets generate-link`, then `\u002Fdeploy` a live report behind a signed\n  URL your team can open — no copy-paste, no stale screenshots.\"\n- *Compounding knowledge:* \"**\u003Ctheir recurring task from Q2\u002FQ3>** becomes a\n  knowledge base that compounds: every session adds to it via `\u002Flearn`, so you\n  never re-derive the same answer twice.\"\n\n**Worked example — this is the shape of what to actually emit to the user.**\nAssume Q4 = \"I lose hours re-summarizing the same investor updates each week\"\nand Q5 = \"HubSpot CRM (has credential)\":\n\n> You said **losing hours re-summarizing investor updates each week** eats your\n> time. Build a `\u002Fnewworker` specialist that drafts each week's update from your\n> CRM activity — it learns your phrasing every run, so by month three you're\n> editing, not writing.\n>\n> Your truth lives in **HubSpot**. Connect it once with `hq secrets generate-link`,\n> then `\u002Fdeploy` a live investor-update preview behind a signed URL your LPs can\n> open — no copy-paste, no stale screenshots.\n\nKeep it to ~half a screen, aspirational but grounded — not salesy. Close with one\nline, e.g.: \"That's the destination. Let's take the first concrete steps now.\"\nThen flow straight into Phase 5.\n\n## Phase 5: What Do You Need Help With?\n\nA branching interview that both **does** lightweight scaffolding inline and\n**collects** a recommended-command list for future fresh sessions. It ends in a\ntwo-section launch block (done now \u002F run next). Ask one question at a time\n(decision-queue-one-at-a-time). Reuse Phase 1 answers (name, what they do, goals,\nchallenges, systems of record) — never re-ask what's captured.\n\n### 5a. Role discovery (FIRST — before any scope question)\n\nGo one level deeper than Phase 1's high-level \"what do you do\". Conversational,\nfree-text (a picker would flatten the nuance) — one message per question,\nthe question as its bold last line. Phase 1 Q4 already captured pain\npoints — don't re-ask. Focus here on the day-to-day texture that shapes which\ncommands to suggest:\n\n1. **What's your specific role?** (title + the hat you actually wear day-to-day)\n2. **Walk me through a typical day — what do you actually spend time on?**\n\nThese answers, plus the Q4 challenges and Q5 systems of record, anchor every\ncommand suggestion below — keep them in working memory for the synthesis step.\n\n### 5b. Primary scope (AskUserQuestion)\n\nOne AskUserQuestion call, four options:\n\n- `Run my own companies \u002F clients`\n- `Personal projects & automation`\n- `Learn \u002F explore HQ first`\n- `Bring in an existing codebase`\n\n*(guided: `[hq-setup] step=you status=done` then `[hq-setup] step=connect status=running`\nbefore 5b.5)*\n\n### 5b.5. Connect a system of record (inline, optional)\n\nFor each Q5 system the user said has a credential, offer to wire it up **now** so\nthey leave setup with a real connection, not just a note. This is the one\nwrite-side connection primitive HQ has (`hq sources` is read-only).\n\n**Guided mode (HQ Desktop):** do not mint a link. For each system, emit a\n`secret` card and then one AskUserQuestion — the desktop shows a masked field,\nstores the value with `hq secrets set --from-stdin` itself (the value never\nenters this session), and answers `Done`:\n\n```\n[hq-setup] card={\"kind\":\"secret\",\"name\":\"DATABASE_URL\",\"label\":\"Postgres connection string\",\"hint\":\"Starts with postgres:\u002F\u002F\",\"scope\":\"company\",\"company\":\"{slug}\"}\n```\n\n- `question`: \"Add your {label} now? It goes straight into the HQ vault.\"\n- `header`: \"Secret\"\n- `multiSelect`: false\n- `options`: `Done` — \"It's stored in the vault\" · `Skip` — \"Leave it for later\"\n\nOn `Done`, confirm the name now appears in `hq secrets list [--personal |\n--company {slug}]` (names only — never `get` the value) before flipping the\nsystem to `connected`. On `Skip`, it stays `capture-only`.\n\n**Terminal mode:** mint a one-time link instead:\n\n```bash\nhq secrets generate-link \u003CSECRET_PATH> [--personal | --company {slug}]\n```\n\n- Pick a sensible `SECRET_PATH` per system (e.g. `DATABASE_URL`, `SLACK_TOKEN`,\n  `STRIPE_API_KEY`). Use `--personal` for personal scope, or `--company {slug}`\n  matching the scope chosen in 5b.\n- The command mints a one-time URL the user opens to enter the secret — the agent\n  never sees it. **Surface that URL inline at mint time only.** It is a\n  capability: never write it into `systems-of-record.md`,\n  `getting-started-next-steps.md`, or any later turn (per\n  `hq-share-session-urls-are-capabilities`).\n- After each one is wired, flip that system's `Connection` cell in\n  `personal\u002Fknowledge\u002Fsystems-of-record.md` from `capture-only` to `connected`.\n- Accept \"skip\" for any system → it stays `capture-only`; add `\u002Fhq-secrets` to\n  the recommended-commands list so they can connect it later.\n\n### 5b.6. Connect apps (inline, optional — company scope only)\n\nIf 5b chose a company scope and the company is cloud-backed, offer the apps HQ\nrecommends for that company so agents can use them from day one. Derive the\nlist from the authoritative catalog — never a hand-kept list:\n\n```bash\nhq integrations catalog --company {slug} --json   # candidates\nhq integrations list --company {slug} --json      # already connected\n```\n\n- Keep catalog rows with `\"source\": \"hq-recommended\"` and `\"mcpReady\": true`\n  whose `authClass` is `oauth` or `none` (API-key apps need a key intake the\n  guided run does not have yet — mention `\u002Fhq-integrations` for those). Cap\n  at six, catalog order. Mark any whose provider is already in `list` as\n  `connected`.\n- Nothing left to offer, or personal scope, or solo HQ → skip this step\n  silently.\n\n**Guided mode:** emit an `integrations` card, then one multi-select\nAskUserQuestion whose option labels are exactly the app names plus\n`Skip for now`:\n\n```\n[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\"}]}\n```\n\n- `header`: \"Integrations\" · `question`: \"Which apps should HQ connect now?\"\n\n**Terminal mode:** the same question without the card.\n\nFor each picked app run `hq integrations connect --entry-id \u003Cid> --company\n{slug}` one at a time. OAuth opens the browser; relay the two outcomes exactly\nas `\u002Fhq-integrations` describes (\"Connected …\" is live; a printed sign-in URL\nmeans **not connected yet**). After the batch, re-emit the `integrations` card\nwith updated `status` values in guided mode, and add `\u002Fhq-integrations` to the\nrecommended-commands list for anything skipped.\n\n*(guided: `[hq-setup] step=connect status=done` then\n`[hq-setup] step=moves status=running` before 5c)*\n\n### 5c. Team \u002F cloud detection (shapes the strongest recommendation)\n\nUse the membership list already resolved in Phase 0c step 3 — do not re-derive\nthis from a manifest grep. If the user has at least one active company\nmembership, this is a team \u002F cloud context, full stop. A joiner whose manifest\nhas not caught up yet is still on a team.\n\nOnly when membership could not be resolved at all (API unreachable), fall back\nto the local signals:\n\n```bash\ngrep -l 'cloud' companies\u002F*\u002Fmanifest.yaml 2>\u002Fdev\u002Fnull | head -1\ngrep -iE 'cloud_backed|hq[-_]?pro|team' companies\u002Fmanifest.yaml 2>\u002Fdev\u002Fnull | head -3\n```\n\nAlso treat it as team\u002Fcloud if `companies\u002Fmanifest.yaml` has at least one real\ncompany entry (top-level keys under `companies:`), or the user's role-discovery\nanswers describe working with a team. Notes:\n\n- The top-level `personal\u002F` overlay does not count — it's not a company.\n- `companies\u002F_template\u002F` does not count either — it's the scaffold copied by\n  `\u002Fnewcompany`, and is never listed in `manifest.yaml`. A fresh HQ install\n  with only `_template\u002F` on disk is **solo**, not team\u002Fcloud.\n\n**If team\u002Fcloud** — make the headline recommendation a *shareable asset* task:\n\n- Build a reusable asset grounded in the role-discovery pain point, then share\n  it with the team: `\u002Fnewworker` (a specialist for the draining task), or a\n  knowledge doc + `\u002Flearn`, then `\u002Fhq-share \u003Cpath>` (or `\u002Fdesignate-team` to\n  make the company cloud-backed for the whole team).\n- And\u002For **produce a report and deploy it**: `\u002Fprd` (or a direct artifact) →\n  `\u002Fdeploy` — framed as \"show your team something real, behind a signed URL\".\n\n**Deploy is not team-gated.** Even for solo \u002F personal scope, surface a\n\"create something small and `\u002Fdeploy` it\" task as a high-value early win\n(a report, a one-pager site, a shareable result).\n\n### 5d. Branch follow-ups — split do-now vs recommend (AskUserQuestion, one at a time)\n\nMirror how `\u002Ftutorial` Step 1 and `\u002Fstartwork` gate picks. For each branch, sort\nactions into **(a) do-now inline** (lightweight, high-momentum — run this\nsession) and **(b) recommend for a fresh session** (heavy \u002F context-hungry — add\nto the launch list, do NOT run inline). See the Rules for the inline\u002Fhandoff line.\n\n- **Companies \u002F clients** → \"Is the company already in HQ?\"\n  - *Do now:* `\u002Fnewcompany {slug}` (new — lightweight scaffold) or `\u002Fonboard`\n    (join existing). If Phase 0d was skipped and they're an existing Claude\n    user, re-offer `\u002Fimport-context` here to hydrate the skeleton.\n  - **Never offer `\u002Fnewcompany` for a slug the user already has an active\n    membership in.** Check the membership list resolved in Phase 0c step 3\n    first. Routing a joiner to `\u002Fnewcompany` for a company they already belong\n    to is what produced the duplicate companies this flow exists to prevent —\n    they end up owning a second, empty company with the same name as the real\n    one. If the slug matches an existing membership, the answer is \"you're\n    already in that one\" plus `\u002Fstartwork {slug}`, not a scaffold.\n  - *Recommend:* first deliverable → `\u002Fbrainstorm` \u002F `\u002Fprd` \u002F `\u002Fstartwork {slug}`.\n    If team\u002Fcloud, fold in the shareable-asset + `\u002Fdeploy` recommendation.\n- **Personal projects** → \"What's the first thing you want a worker to do?\"\n  (anchored to role-discovery + Q4 challenges).\n  - *Do now:* `\u002Fidea` to capture it on the board; `\u002Fnewworker` if a recurring\n    specialist is clearly implied.\n  - *Recommend:* `\u002Fprd` for the first real deliverable, plus the solo\n    `\u002Fdeploy` early-win.\n- **Learn first** → *Do now:* nothing heavy. *Recommend:* `\u002Ftutorial` (suggest a\n  topic from role-discovery + Phase 1 goal) then `\u002Fpersonal-interview`.\n- **Existing codebase** → *Do now:* note the clone target (`repos\u002Fpublic\u002F` or\n  `repos\u002Fprivate\u002F`). *Recommend:* `\u002Fdiscover \u003Crepo>` in a fresh session (it's\n  context-hungry — never run inline during setup).\n\n### 5e. Synthesize + emit the two-section launch block\n\nProduce two ordered lists, each command **fully substituted** (real slugs\u002Fpaths\n— never `{placeholder}` tokens), each with a one-line \"why\" tied to their\nanswers. Print inline:\n\n```\nYou're set up. Here's where you landed.\n\nDone this session:\n  ✓ {what was actually scaffolded \u002F connected — company, idea, secret-link, knowledge doc}\n  ...\n\nRun these next — start a FRESH session for each (context hygiene, see Phase 4):\n  1. {command}        — {why, tied to their challenge \u002F goal \u002F system of record}\n  2. {command}        — {why}\n  ...\n\nSaved to personal\u002Fknowledge\u002Fgetting-started-next-steps.md — reopen anytime.\n```\n\n### 5f. Persist the artifact\n\nWrite `personal\u002Fknowledge\u002Fgetting-started-next-steps.md` (the dir is created in\nPhase 2, so the path always exists). Full prose — this is a disk artifact, not\nchat. Contents:\n\n- Generated date\n- The user's role + stated goal + top challenges (from Phase 1 + 5a)\n- **Done this session** — what was actually scaffolded\u002Fconnected (company, idea,\n  knowledge docs, which systems of record got connected)\n- **Run these next** — the same recommended command list shown inline, each with\n  its rationale, one fresh session per command\n- A \"Your systems of record\" recap (mirror the table, with connection status) so\n  they remember what's wired vs still to connect\n- An \"If you get lost\" footer: `\u002Fstartwork`, `\u002Ftutorial`, `\u002Fsearch \u003Ctopic>`\n\n**Never** write any secret-link \u002F share URL into this file — those are\ncapabilities, surfaced inline at mint time only.\n\nIf the file already exists, show the user what would change and confirm via\nAskUserQuestion before overwriting (per the Rules below — never overwrite\nsilently).\n\n## Phase 6: Deploy the welcome page + hand off\n\nThe visual capstone. Turn everything learned into a small, **private**,\npersonalized welcome page and publish it, then send the user off to a fresh\nsession. Requires the Cognito login from Phase 0c; if the user never signed in,\nskip the deploy and just deliver the launch block + handoff message in chat.\n\n### 1. Build the page (one `index.html`)\n\nGenerate a single `index.html` — **never** multiple `.html` files: the static\nhost SPA-fallbacks every `.html` subpath to `index.html` silently, so use one\nfile with a `#\u002Froute` hash router if it needs sections.\n\n- **Design:** if the `impeccable` skill is available, use it to craft the page\n  (the owner's lives at `personal\u002Fskills\u002Fimpeccable\u002F`). If it's absent in this\n  HQ, produce a high-quality inline design instead — degrade gracefully, never\n  hard-depend on impeccable.\n- **Content** — four sections, all drawn from earlier phases:\n  1. **Who you are** — the synthesis from Phase 1 (identity) + Phase 1.5\n     (public presence).\n  2. **How your HQ is set up** — cloud companies synced (Phase 0c), the personal\n     scaffold, systems of record and which are connected.\n  3. **Starter moves** — the Phase 5 recommended commands as **copy-paste prompt\n     blocks**, each fully substituted (real slugs\u002Fpaths — never `{placeholder}`),\n     each with a one-line \"why\".\n  4. **Hand off** — close this session, start a fresh one, paste the first prompt.\n- Stage it in a scratch dir (e.g. `workspace\u002Fsetup-welcome\u002Findex.html`).\n\n### 2. Deploy private\n\nRun the `\u002Fdeploy` skill on the staged dir with **private (owner-only)** access\nmode. The page holds personal understanding, and `sensitivity-check.sh` greps\nfilenames only — it returns `sensitive:false` for a lone `index.html` even when\nthe content is personal — so set the access mode to private manually; do not rely\non the auto-verdict.\n\n### 3. Surface the link + hand off\n\nPrint the deploy URL **inline, in one plain line** (this is the `\u002Fdeploy`\ncapability carveout — surfaced at publish time, never re-pasted into knowledge\nfiles or later turns). Then point the user to the guided public course as their\ncanonical visual walkthrough:\n\n`https:\u002F\u002Fwww.hqforwork.com\u002Fgetting-started\u002Ftutorials\u002Finstall-hq-macos?source=hq_setup_wizard`\n\nCall it the **guided HQ tutorial (videos + written steps)** so it stays distinct\nfrom the adaptive, in-agent `\u002Ftutorial` command. Then deliver the handoff message:\n\n```\nYou're all set — here's your welcome page (private to you): {url}\n\nFollow the guided HQ tutorial here (videos + written steps):\nhttps:\u002F\u002Fwww.hqforwork.com\u002Fgetting-started\u002Ftutorials\u002Finstall-hq-macos?source=hq_setup_wizard\n\nOpen it, then close this session and start a fresh one. Your first move:\n\n  {first copy-paste prompt, fully substituted}\n\n(A fresh session per task keeps context clean — see your welcome page for the\nfull list.)\n```\n\n### 4. Teach the `\u002Fhandoff` habit before they go\n\nThis is the one habit that makes every future session work. Setup is where they\nlearn it, so end by teaching it explicitly — don't leave it as an optional\naside.\n\nDeliver a short, plain-language nudge along these lines (adapt the wording, keep\nit to a few lines):\n\n```\nOne habit that'll save you every time: when you finish real work in a\nsession, end it with \u002Fhandoff.\n\n\u002Fhandoff writes down where you left off — what you did, what's next, which\nfiles changed — and saves it so a fresh session picks up exactly there. No\n\"remind me what we were doing.\" You just run \u002Fstartwork next time and it's\nall waiting.\n\nThe rhythm is: \u002Fstartwork → do one focused thing → \u002Fhandoff → close the\nsession. Try it at the end of your very first work session.\n```\n\n**Nudge, don't just mention.** As real work accumulates in *this* session\n(a company scaffolded, a worker built, a knowledge doc written), it's worth\nactively offering to run `\u002Fhandoff` now so they see it once end-to-end — for a\nbare setup with nothing substantive done yet, teaching the habit is enough and\nstarting fresh with the first prompt is fine. Either way, they should leave\nsetup knowing what `\u002Fhandoff` is, why it matters, and how to run it.\n\n*(guided: `[hq-setup] step=moves status=done` as the last line of Phase 6)*\n\n## Rules\n\n- **Guided mode markers are part of the contract.** With `--guided`, every\n  step boundary and every card question carries its marker line (see \"Guided\n  mode\" above); without it, none do.\n- Ask questions one at a time — every phase, including the Phase 0c login prompt\n  and each Phase 1.5 social URL. Never batch. In guided mode a choice is an\n  AskUserQuestion call, a fill-in-the-blank is the bold last line of its own\n  message, and you never narrate how or why you are asking.\n- **Never block setup on HQ Cloud.** Login, invite-claim, and sync (Phase 0c) are\n  best-effort; a solo or offline HQ completes setup fine. There is no\n  list-pending-invites command — invites are claimed by running sync.\n- **Browser harness is optional.** Prefer the Claude for Chrome harness (Codex\n  equivalent in Codex) so login-walled profiles are readable; if the user\n  declines, fall back to public `WebFetch` + `WebSearch` and skip walled sources.\n  Never block on the extension.\n- **Delegate browser reads + scrape synthesis to a subagent** that returns text\n  only — keep raw pages and screenshots out of the parent session (HQ context\n  diet; stay under the image cap). Persist only synthesized understanding, never\n  raw dumps or credentials.\n- **The welcome page is private** and contains personal understanding — set\n  `\u002Fdeploy` access mode to owner-only manually; don't trust the filename-only\n  sensitivity verdict.\n- **`impeccable` is optional** — use it for the welcome page if present, else\n  produce a high-quality inline design. Degrade gracefully.\n- **Inline vs handoff:** scaffold lightweight, high-momentum items inline during\n  setup (`\u002Fnewcompany`, `\u002Fidea`, a knowledge doc, a `hq secrets generate-link`\n  connection). Heavy \u002F context-hungry work (`\u002Fprd`, `\u002Fdiscover`, deep\n  planning) is recommended for a fresh session — never run inline. This honors\n  HQ context hygiene while still delivering first-session momentum.\n- **Secret-link \u002F share \u002F deploy URLs are capabilities** — surface inline at mint\n  or publish time only. Never write them into `getting-started-next-steps.md`,\n  `systems-of-record.md`, `social-presence.md`, or any later turn\n  (`hq-share-session-urls-are-capabilities`).\n- Use defaults when user says \"skip\"\n- Never overwrite existing files without asking\n- Create parent directories as needed\n- **Install missing dependencies and CLI tools directly — never ask.** Do not\n  prompt \"do you want to install X?\" and never surface an install-all \u002F some \u002F\n  none picker for tooling; the standard install command runs unattended. The one\n  exception is an interactive auth that can't run unattended (e.g. `gh auth\n  login`). Don't block setup if an optional tool's install fails — note it in the\n  summary and move on. These are \"recommended\" not \"required\" (except claude itself).\n- 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\n- Phase 4\u002F5 are skippable — if the user says \"skip\", still write `personal\u002Fknowledge\u002Fgetting-started-next-steps.md` using best-effort defaults from Phase 1 answers. Never block setup completion on the orientation or interview\n- Phase 6 (welcome page) is skippable — if the user isn't signed in or declines,\n  skip the `\u002Fdeploy` and just deliver the launch block + handoff message in chat.\n  Never block setup completion on the deploy\n","# HQ Setup Wizard\n\nGet your HQ running: dependencies, HQ Cloud (login + sync), a profile built from\nwho you are, and a private welcome page that hands you your first moves. One\nquestion at a time; nothing here is mandatory — skip anything and setup still\ncompletes.\n\n## HQ Desktop: the Setup bot\n\nCurrent HQ Desktop (0.10.347, verified against hq-desktop-app\n`origin\u002Fmain@c621a6a1` on 2026-09-27) runs guided setup as a chat with the\n**Setup bot**, not as a stepped card. Run Setup on `#welcome` creates a\npersonal local bot named `setup` from the worker template\n`core\u002Fworkers\u002Fpublic\u002Fsetup` (`hq bot create setup --worker setup`). The\nperson talks to it in its DM. The bot walks the phases of this skill in plain\nwords and follows `core\u002Fworkers\u002Fpublic\u002Fsetup\u002Fworker.yaml`, which overrides the\nguided-mode rules below: it never prints `[hq-setup]` lines and never uses\nmultiple-choice pickers.\n\nThe Setup bot can end a message with `hq-block` fences that the desktop turns\ninto UI. The fence is three backticks followed by `hq-block` on the same line,\nthe JSON on its own line, then three closing backticks, not indented, and\nnothing after it:\n\n- **Suggested replies** — `{\"v\":1,\"blocks\":[{\"kind\":\"suggestions\",\"items\":[\"For a company\",\"Just for me\"]}]}`.\n  Two to four short replies; the app keeps at most 4, drops duplicates, and\n  caps each at 80 characters. They show as buttons under the bot's newest\n  message and a click sends the text as the person's reply. The app always\n  adds its own \"Something else\" button, so do not add an \"Other\" item. Leave\n  them out when only the person can type the answer (names, emails, URLs).\n- **Setup finished** — `{\"v\":1,\"blocks\":[{\"kind\":\"setupDone\"}]}`, or\n  `{\"v\":1,\"blocks\":[{\"kind\":\"setupDone\",\"slackAgent\":true}]}` for someone who\n  started their own company, which adds a \"put the bot in Slack\" offer. Send\n  it once, as the last thing in the closing message, never together with\n  `suggestions`. The app shows a finish card until the person writes again.\n\nIn the current app the desktop acts on these two blocks only in the Setup\nbot's DM. Full contract: `core\u002Fknowledge\u002Fpublic\u002Fhq-core\u002Fdesktop-rich-messages.md`.\n\n## Guided mode (legacy scripted run): `--guided`\n\nOlder HQ Desktop builds ran this skill as a scripted session on `#welcome`,\ndrawn as a stepped card, started with `\u002Fsetup --guided`. The step and card\nparsers are still in the app source, but the current app no longer starts\nthat session (the in-app session engine was removed in 0.10.270), and the\nSetup bot's DM does not strip marker lines. Follow these rules only when the\narguments actually contain `--guided`:\n\n- **Emit a step marker at every phase boundary**, on its own line, exactly:\n  `[hq-setup] step=\u003Cid> status=\u003Crunning|done>`. The ids, in order, and the\n  phases they cover:\n\n  | step      | phases                                   |\n  |-----------|------------------------------------------|\n  | `tools`   | 0a, 0b                                   |\n  | `cloud`   | 0c                                       |\n  | `import`  | 0d (adopt prior AI footprint)            |\n  | `you`     | 1, 1.5, 2, 3, 4, 4.5, 5a, 5b             |\n  | `connect` | 5b.5 (secrets), 5b.6 (apps)              |\n  | `moves`   | 5c, 5d, 5e, 5f, 6                        |\n\n  Emit `status=running` when a phase group starts and `status=done` when it\n  ends. Never go backwards; skipping a whole group is fine — mark it `done`.\n- **Emit a card marker right before the question it belongs to**, on its own\n  line: `[hq-setup] card=\u003Cone-line JSON>`. The desktop draws the card in place\n  of the plain option list and answers the *same* AskUserQuestion. Three kinds:\n  - `{\"kind\":\"found\",\"title\":\"…\",\"items\":[{\"label\":\"…\",\"count\":12,\"detail\":\"…\"}]}`\n    — \"Here's what I found\", paired with the Import question (0d).\n  - `{\"kind\":\"secret\",\"name\":\"DATABASE_URL\",\"label\":\"…\",\"hint\":\"…\",\"scope\":\"personal|company\",\"company\":\"\u003Cslug>\"}`\n    — one credential; the desktop stores it straight into the vault and\n    answers `Done`. Paired with a `header: \"Secret\"` question with options\n    `Done` \u002F `Skip` (5b.5). **In guided mode do not mint a `generate-link`\n    URL** — the card is the intake.\n  - `{\"kind\":\"integrations\",\"items\":[{\"id\":\"\u003CentryId>\",\"name\":\"…\",\"description\":\"…\",\"auth\":\"oauth|none\",\"status\":\"connected|available\"}]}`\n    — app tiles, paired with a multi-select `header: \"Integrations\"` question\n    whose option labels are the app names plus `Skip for now` (5b.6).\n- **Two ways to ask, and only two.** A choice (2–4 options) is one\n  AskUserQuestion call. A fill-in-the-blank (name, what you do, goals,\n  challenges, systems of record, role, typical day, a URL) is asked in plain\n  words as the **last line of the message, in bold, ending with a question\n  mark** — one question per message, then stop and wait; the person types\n  the answer in the chat. Never bundle several questions into one message,\n  never number them, and never ask a fill-in-the-blank through AskUserQuestion\n  (the runtime needs real options; a fake \"Skip\" option is not a question).\n- **Speak only to the person, never about the mechanics.** The desktop shows\n  your words as a \"Setup Agent\" chat. Do not mention pickers, tools,\n  AskUserQuestion, markers, phases, modes, \"the desktop\", or why you are\n  asking a question one way rather than another (\"that one's a\n  fill-in-the-blank, so I'll ask it straight\" is exactly what not to say).\n  Say what you are doing for them and ask the question — nothing else.\n- **Markers are plain lines, never in backticks or code fences**, one per\n  line, at the start of the message. A marker line is never the whole message\n  — put a one-sentence plain status beside it so the card has something to say.\n- One question at a time, plain words. The finish: emit\n  `[hq-setup] step=moves status=done` on its own line, then the closing\n  summary in ordinary Markdown (headings, bullets), not a code block.\n- Without `--guided` (a terminal), emit no markers and no cards, and use the\n  terminal flows described in each phase (e.g. the secret link in 5b.5).\n\n## Phase 0a: Install Manifest Recovery\n\n*(guided: `[hq-setup] step=tools status=running`)*\n\nBefore anything else, check if the HQ Installer left a manifest. HQ Desktop\nwrites it to the USER'S home (`~\u002F.hq\u002Finstall-manifest.json`); older installers\nwrote it inside the HQ folder. Check both — reading only `.hq\u002F` inside HQ made\n`\u002Fsetup` believe nothing was installed and re-run `npm install -g` with the\nsystem npm on every run (prefix conflicts, permission errors, supply-chain\nblock; reported 2026-08-28).\n\n```bash\ncat ~\u002F.hq\u002Finstall-manifest.json 2>\u002Fdev\u002Fnull || cat .hq\u002Finstall-manifest.json 2>\u002Fdev\u002Fnull\n```\n\nThen, BEFORE declaring any dependency missing, put HQ's managed toolchain on\nPATH for this session — the installer puts tools there, and a GUI-launched or\nhook-launched shell often does not see them:\n\n```bash\nexport PATH=\"$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\u002Fnode\u002Fbin:$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\u002Fnpm-global\u002Fbin:$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\u002Fgit-shim:$HOME\u002F.local\u002Fbin:$PATH\"\n# Windows (Git Bash): the toolchain is %LOCALAPPDATA%\\IndigoHQ\\toolchain, with\n# node.exe in node\u002F and npm shims in npm-prefix\u002F. Without this every tool\n# reports MISSING even when the managed toolchain is installed.\nif [ -n \"${LOCALAPPDATA:-}\" ] && command -v cygpath >\u002Fdev\u002Fnull 2>&1; then\n  for d in node npm-prefix npm-global\u002Fbin; do\n    [ -d \"$(cygpath -u -- \"$LOCALAPPDATA\")\u002FIndigoHQ\u002Ftoolchain\u002F$d\" ] && export PATH=\"$(cygpath -u -- \"$LOCALAPPDATA\")\u002FIndigoHQ\u002Ftoolchain\u002F$d:$PATH\"\n  done\nfi\nfor t in node npm qmd hq git yq jq; do printf '%-5s %s\\n' \"$t\" \"$(command -v $t || echo MISSING)\"; done\n```\n\nNewer manifests record the dependency stage only as `steps.deps` (the\n`dependencies` map is empty); use the PATH check above as the source of truth\nfor what is actually present. On a Mac without Xcode Command Line Tools,\n`\u002Fusr\u002Fbin\u002Fgit` and `\u002Fusr\u002Fbin\u002Fpython3` are stubs that pop an install dialog —\nnever call them; the managed `git-shim` is the real git.\n\nIf no manifest exists, skip to Phase 0b — the user installed manually or is running setup for the first time.\n\nIf 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.\n\n### Triage priority (handle in this order)\n\n**P0 — Blocking (fix these first, setup can't proceed without them):**\n- `steps.directory` failed or missing → HQ directory doesn't exist; abort setup and tell user to re-run installer\n- `steps.templates` failed → HQ template not fetched; attempt `npx --package=@indigoai-us\u002Fhq-cli hq init .`\n- `dependencies.node` failed → nothing works; guide user through Node install\n- `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.\n\n**P1 — Required (HQ works poorly without these):**\n- `dependencies.qmd` failed → no semantic search; install the SANCTIONED pin (see `core\u002Fscripts\u002Finstall-deps.allow`): `npm install -g @tobilu\u002Fqmd@2.5.3`, then `qmd index .`. Unpinned installs are blocked by the supply-chain guard on purpose.\n- `dependencies.claude-code` failed → can't run workers; `npm install -g @anthropic-ai\u002Fclaude-code@\u003Cversion>` (explicit version pin required by the guard)\n- `dependencies.yq` failed → can't parse YAML configs; `brew install yq` or download binary\n- `dependencies.hq-cli` failed → can't install packs or sync; `npm install -g @indigoai-us\u002Fhq-cli@\u003Cversion>` (explicit version pin required by the guard)\n- `steps.indexing` failed → search won't work; run `qmd index .` directly\n- `packs` with status `\"failed\"` or `\"running\"` (interrupted) → retry each: `npx --package=@indigoai-us\u002Fhq-cli hq install {pack-name}`\n\n**P2 — Recommended (HQ works but some features limited):**\n- `dependencies.gh` failed\u002Fskipped → no PR workflows; install directly: `brew install gh` (then `gh auth login` — the browser auth is the one warranted prompt)\n- `dependencies.homebrew` skipped → limits future installs; install directly (best-effort; skip silently if the platform install can't run unattended)\n- `steps.personalize` failed → profile not set up; Phase 1 below will cover this\n\n### Remediation flow\n\n**Install missing dependencies and CLI tools directly — never ask whether to\ninstall them, and never surface an \"install all \u002F install some \u002F skip all\"\npicker.** A user running `\u002Fsetup` has already opted into getting HQ working; a\nmid-setup \"do you want these tools?\" question is pure friction. The install\ncommands in the triage lists above are safe, idempotent, and non-blocking — just\nrun them. This includes P2 items (`gh`, `homebrew`): install them directly too.\n\nFor each issue found (in priority order):\n\n1. **Install it directly, silently.** Run the item's install command (from the\n   triage lists above), best-effort. Do not pause for permission, do not\n   explain-then-ask, and do not offer install-method choices — pick the standard\n   method and run it.\n2. **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,\n   move on without narrating it. If it failed, try one alternative, then record\n   it under \"Still needs attention\" in the summary and keep going — never block\n   setup on a failed optional tool.\n3. **The only permitted prompt in this phase is a genuine interactive auth** that\n   cannot run unattended (e.g. `gh auth login`, which opens a browser).\n   *Installing* a tool is never that case — installs are always direct.\n4. **Bootstrap dependencies are the one install exception.** A P0 that cannot be\n   installed unattended from within setup — Node itself (nothing runs without it,\n   and there is no npm to install it with), or a platform package manager on a\n   machine that has none (e.g. Homebrew on a bare macOS) — falls back to *guiding*\n   the user through that one install, per its triage entry. This is not the\n   tool-choice picker the rule forbids; it is the narrow \"we literally cannot do\n   this for you\" case. Everything installable via npm \u002F an existing package\n   manager still installs directly, no prompt.\n\n### After remediation\n\nOnce all issues are addressed, show a summary:\n\n```\nInstall recovery complete.\n\nFixed:\n  ✓ {item} — {what was done}\n  ...\n\nSkipped (optional):\n  ○ {item} — {why it's optional}\n  ...\n\nStill needs attention:\n  ✗ {item} — {what went wrong, what user can do}\n  ...\n```\n\nSkip 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.\n\n## Phase 0b: Dependencies + auth checks (non-manifest)\n\nIf Phase 0a ran, skip any deps already checked there. This phase covers the\nfresh \u002F manual install case where there is **no** install manifest — the tools\nthe wizard leans on may simply not be present yet.\n\n**Missing tools — install directly, never ask.** When there's no manifest, probe\nthe core tooling and install whatever is missing, best-effort and silently. Do\n**not** present an \"install all \u002F some \u002F none\" choice — a user running `\u002Fsetup`\nwants HQ working, so install and move on:\n\n```bash\n# hq-cli — honor the native installer's managed toolchain before system npm.\n# GUI-launched Claude\u002FCodex sessions do not source the shell profile that the\n# installer writes, so `command -v hq` alone can miss this already-installed\n# binary. Do not consult `~\u002F.hq`: the install manifest belongs to this HQ root.\nHQ_MANAGED_TOOLCHAIN=\"$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\"\nHQ_MANAGED_HQ_BIN=\"$HQ_MANAGED_TOOLCHAIN\u002Fnpm-global\u002Fbin\"\nHQ_MANAGED_NODE_BIN=\"$HQ_MANAGED_TOOLCHAIN\u002Fnode\u002Fbin\"\nif [ -x \"$HQ_MANAGED_HQ_BIN\u002Fhq\" ]; then\n  # Prepend in reverse order so the managed Node resolves the hq shebang.\n  for bin in \"$HQ_MANAGED_HQ_BIN\" \"$HQ_MANAGED_NODE_BIN\"; do\n    if [ -d \"$bin\" ]; then\n      case \":$PATH:\" in\n        *\":$bin:\"*) ;;\n        *) export PATH=\"$bin:$PATH\" ;;\n      esac\n    fi\n  done\nfi\ncommand -v hq >\u002Fdev\u002Fnull 2>&1 || npm install -g @indigoai-us\u002Fhq-cli\n\n# qmd — npm global, the exact pin from core\u002Fscripts\u002Finstall-deps.allow (the\n# version Desktop installs). Newer unpinned qmd has no better-sqlite3 binary on\n# Windows and crashes on every command. On macOS it loads SQLite extensions the\n# built-in sqlite3 can't, so ensure Homebrew SQLite is present regardless of\n# whether qmd itself was already installed.\ncommand -v qmd >\u002Fdev\u002Fnull 2>&1 || npm install -g @tobilu\u002Fqmd@2.5.3\nif [ \"$(uname)\" = \"Darwin\" ] && command -v brew >\u002Fdev\u002Fnull 2>&1; then\n  brew list sqlite >\u002Fdev\u002Fnull 2>&1 || brew install sqlite\nfi\n\n# gh — pick the platform-appropriate installer (brew \u002F apt \u002F winget); best-effort.\nif ! command -v gh >\u002Fdev\u002Fnull 2>&1; then\n  if   command -v brew    >\u002Fdev\u002Fnull 2>&1; then brew install gh\n  elif command -v apt-get >\u002Fdev\u002Fnull 2>&1; then sudo apt-get update && sudo apt-get install -y gh\n  elif command -v winget  >\u002Fdev\u002Fnull 2>&1; then winget install --id GitHub.cli -e --source winget\n  fi\nfi\n```\n\nVerify each with `command -v {tool}` afterward. If an install fails (or no\nsupported installer is available on this platform), note it under \"Still needs\nattention\" in the Phase 3 summary and continue — never block setup on a failed\noptional tool.\n\n**Auth checks** (not tracked by manifest):\n- `gh auth status` — if gh is installed but not authenticated, offer `gh auth login`\n  (a browser auth is the one place a prompt is warranted; installing gh is not).\n\nDo **not** check for or install third-party deploy CLIs (e.g. the Vercel CLI) here.\nHQ's own features never shell out to them — `\u002Fdeploy` targets hq-deploy\ninfrastructure, not Vercel — so they are not HQ setup dependencies. They are\nuser-provided tools, installed on-demand by the user only when deploying their\nown projects to their own pipeline; point-of-use guidance lives in the relevant\npolicy (e.g. `core\u002Fpolicies\u002Fhq-vercel.md`), not in setup.\n\nPost-install: run `qmd index .` if qmd was just installed or no index exists.\n\n*(guided: `[hq-setup] step=tools status=done` once 0a\u002F0b are through)*\n\n## Phase 0c: HQ Cloud — login, claim invites, ensure sync\n\n*(guided: `[hq-setup] step=cloud status=running`)*\n\nConnect this HQ to HQ Cloud so the user lands logged in, with any cloud-company\ninvites claimed and sync working. Do this **before** identity so synced company\ncontext can inform the rest of the wizard, and so the welcome-page `\u002Fdeploy`\n(Phase 6) is already authenticated. One question at a time. Solo \u002F offline HQ is\nfine — never block setup on cloud.\n\n### 1. Confirm Cognito login\n\n```bash\nhq auth status 2>\u002Fdev\u002Fnull\n```\n\n- **Signed in, token valid** → continue. Show identity: `hq whoami`.\n- **Token expired** → try a silent refresh first: `hq auth refresh`.\n- **Not signed in, or refresh failed** → ask one question: \"Sign in to HQ Cloud\n  now? (unlocks team sync, shared knowledge, and publishing)\". If yes, run the\n  `\u002Fhq-login` skill (browser Cognito login). If they decline, note that cloud\n  features (sync, `\u002Fdeploy`, shared companies) are unavailable until they run\n  `\u002Fhq-login`, and skip the rest of Phase 0c.\n\nThere is **no command that lists \"companies I've been invited to.\"** Modern\ninvites are email-keyed and claimed automatically the first time sync runs (the\nsync-runner \"claim dance\"). So do not promise an invite list — claim them via\nsync in step 2.\n\n### 2. Ensure sync + claim invites\n\nOnce signed in, run a full sync via the `\u002Fhq-sync` skill (engine:\n`hq sync pull --all` \u002F `hq-sync-runner --companies --direction both`). This fires\nthe claim dance — auto-accepting any email-keyed pending invites — and pulls\nevery cloud company the user belongs to.\n\nThe runner emits `setup-needed` when a run cannot proceed. It carries a `reason`\nand, when relevant, a `pendingInviteCount` — read both and act on them. Do NOT\nfall through to the solo path on a bare `setup-needed`:\n\n- `reason: \"no-memberships\"` with `pendingInviteCount > 0` — the user has an\n  invite that has not been accepted. Say so, and tell them to run\n  `\u002Faccept \u003Clink-or-token>`, then re-run sync. This is the single most common\n  reason someone is wrongly told they are solo.\n- `reason: \"no-memberships\"` with no pending invites — genuinely no company yet.\n  The solo path is correct here.\n- `reason: \"no-person-entity\"` — signed in, but there is no personal entity to\n  sync into. Usually a **legacy magic-link** invite; point them to\n  `\u002Faccept \u003Clink-or-token>` to redeem it, then re-run sync.\n- If sync errors (network, transport), report it plainly and continue.\n\nAn older runner emits `setup-needed` with no `reason` at all. Treat that as\n\"unknown — do not conclude solo\", and offer `\u002Faccept` rather than asserting the\nuser has no team.\n\n### 3. Report what landed\n\n**Membership is the source of truth here, not the manifest file.** A newly\ninvited member's `companies\u002Fmanifest.yaml` arrives as the stock empty template\nsynced from their personal vault, so grepping it reports \"solo\" for someone who\ndemonstrably belongs to a company. That is the exact bug this step exists to\navoid re-introducing.\n\nResolve the company list in this order:\n\n1. **The runner's `fanout-plan` event** from the sync you just ran. It lists\n   every company target the run resolved, with slug and name. This is free —\n   you already have it.\n2. **`GET \u002Fmembership\u002Fme`** via the vault client, if you need to resolve\n   membership without a sync in hand.\n3. **The manifest grep, fallback only** — use it when the API is unreachable,\n   and say that the answer is local-only:\n\n```bash\ngrep -E \"^  [a-z0-9-]+:\" companies\u002Fmanifest.yaml 2>\u002Fdev\u002Fnull | sed -E 's\u002F^  ([a-z0-9-]+):.*\u002F\\1\u002F'\n```\n\nThen report:\n\n- Companies resolved → \"You're connected and synced. You're in: {names}.\" Name\n  the companies. A user who was just told they are on a team and cannot see\n  which one has not actually been told anything.\n- API says companies exist but the manifest grep disagrees → report the API\n  answer, and note that local routing has been repaired (the sync runner\n  reconciles the manifest entry and seeds `activeCompany` on the way through;\n  a freshly written manifest propagates on the NEXT sync).\n- Nothing resolved, and no pending invites → \"You're signed in. No cloud\n  companies yet — you're solo for now, that's fine.\"\n\nKeep Phase 0c to a few plain lines; the heavy lifting is the reused skills.\n\n*(guided: `[hq-setup] step=cloud status=done`)*\n\n## Phase 0d: Adopt prior AI footprint\n\n*(guided: `[hq-setup] step=import status=running`)*\n\nIf the user already used AI tools before HQ — Claude Code, Codex, Grok, or\nclaude.ai chat — they have two kinds of prior context worth adopting: artifacts\non disk (skills, hooks, policies, plans, MCP servers, repos in `~\u002F.claude\u002F` and\ncommon code dirs) and **conversation history** (Claude Code, Codex, and Grok\nsession stores, plus claude.ai chats via export). Hydrating both into HQ now\nmeans the rest of the wizard — Dream Big (4.5), the action interview (5) —\nreflects the companies, knowledge, policies, and projects they already have,\ninstead of starting from a blank slate. This is the `\u002Fimport-context` skill\n(formerly `\u002Fimport-claude`), surfaced as a first-class setup step, and it runs\n**before** identity so the rest of the wizard already knows what they brought.\nOne question at a time; never block setup — a clean install with no prior\nfootprint flows straight past this.\n\n### 1. Detect a prior footprint (cheap, read-only)\n\n`\u002Fimport-context` requires `companies\u002Fmanifest.yaml` to exist (a fresh `hq init`\nships it). If it's missing, skip this phase. Otherwise do a quick existence probe\nof the scanner's main allowlist plus the conversation stores — do **not** run\nthe full scan here, just decide whether there's plausibly anything to import:\n\n```bash\ntest -f companies\u002Fmanifest.yaml || echo \"no-manifest-skip\"\n# Probe the highest-signal locations; any non-empty hit means \"offer the import\".\nfor d in \"$HOME\u002F.claude\u002Fplans\" \"$HOME\u002F.claude\u002Fcommands\" \"$HOME\u002F.claude\u002Fskills\" \\\n         \"$HOME\u002F.claude\u002Fprojects\" \"$HOME\u002F.claude\u002Fagents\" \\\n         \"$HOME\u002F.codex\u002Fsessions\" \"$HOME\u002F.grok\u002Fsessions\"; do\n  [ -d \"$d\" ] && find \"$d\" -mindepth 1 -maxdepth 2 -print -quit 2>\u002Fdev\u002Fnull\ndone\n```\n\n- **No manifest, or every probe is empty** → print one plain line (\"No prior\n  AI footprint to import — starting fresh.\") and continue to Phase 1.\n- **Any probe returns a path** → there's plausibly something to adopt; offer it\n  in step 2. (The authoritative scan, with counts and redaction, happens inside\n  `\u002Fimport-context` itself — keep this probe lightweight.)\n\n**Guided mode:** before offering, count what the probe hit (still read-only,\nstill cheap) and emit a `found` card with only the non-zero rows, then the\nstep-2 question. For example:\n\n```bash\nfor pair in \"Claude Code sessions:$HOME\u002F.claude\u002Fprojects:*.jsonl\" \\\n            \"Plans:$HOME\u002F.claude\u002Fplans:*\" \"Commands:$HOME\u002F.claude\u002Fcommands:*\" \\\n            \"Skills:$HOME\u002F.claude\u002Fskills:*\" \"Agents:$HOME\u002F.claude\u002Fagents:*\" \\\n            \"Codex sessions:$HOME\u002F.codex\u002Fsessions:*\" \"Grok sessions:$HOME\u002F.grok\u002Fsessions:*\"; do\n  label=${pair%%:*}; rest=${pair#*:}; dir=${rest%%:*}; glob=${rest#*:}\n  [ -d \"$dir\" ] && n=$(find \"$dir\" -mindepth 1 -maxdepth 3 -name \"$glob\" 2>\u002Fdev\u002Fnull | wc -l | tr -d ' ') || n=0\n  [ \"$n\" -gt 0 ] && echo \"$label=$n\"\ndone\n```\n\n```\n[hq-setup] card={\"kind\":\"found\",\"title\":\"Here's what I found\",\"items\":[{\"label\":\"Claude Code sessions\",\"count\":12},{\"label\":\"Plans\",\"count\":3}]}\n```\n\n### 2. Offer the import (AskUserQuestion)\n\nOne AskUserQuestion call:\n\n- `question`: \"Looks like you've used Claude Code, Codex, or Grok before. Want\n  me to import your existing skills, plans, and repos — and mine your past\n  conversations for proposed companies, knowledge, and projects — now? You\n  approve every item before it's created.\"\n- `header`: \"Import\"\n- `multiSelect`: false\n- `options`:\n  - `Import now` — \"Run \u002Fimport-context inline — discovers your artifacts,\n    mines your conversation history across tools, and proposes companies,\n    knowledge, policies, and projects (you confirm each step)\"\n  - `Preview first` — \"Scan and show me what's there, import nothing yet\n    (\u002Fimport-context --dry-run)\"\n  - `Skip` — \"Don't import; I'll run \u002Fimport-context later if I want\"\n\n### 3. Run it\n\n- **Import now** → inline-invoke the `\u002Fimport-context` skill via the Skill tool.\n  It runs its own preflight, scan, redaction, conversation mining, and\n  per-category triage — every write is gated by its own AskUserQuestion prompts,\n  so you don't re-ask here. If the user mentions claude.ai chats, pass\n  `--claude-export=\u003Cpath>` once they have a data export (claude.ai → Settings →\n  Privacy → Export data). When it returns, briefly note what landed (companies\n  created, knowledge seeded, projects proposed, workers synthesized, repos\n  adopted) in one plain line, then continue to Phase 1.\n\n  **Guided mode:** show what landed as a card, not a sentence. Emit a `found`\n  card titled \"What landed\" with one row per outcome that is non-zero\n  (companies created, knowledge files seeded, projects proposed, workers,\n  repos adopted — `detail` names them, e.g. `\"detail\":\"acme, northwind\"`),\n  then one AskUserQuestion — `header`: \"Import\", `question`: \"Here's what the\n  import brought in. Good to go on?\", options `Looks good` \u002F `Let me review`\n  (\"Open the import report before moving on\"). On `Let me review`, print the\n  report path and the per-category list, then re-ask once.\n- **Preview first** → inline-invoke `\u002Fimport-context --dry-run`. It scans and\n  reports counts without importing. After it returns, ask once whether to run the\n  real import now (re-invoke `\u002Fimport-context` without the flag) or defer. If they\n  defer, treat it as Skip.\n\n  **Guided mode:** the person chose Preview to *see* what is there, so the\n  scan result must be the card, not prose. Build a `found` card titled\n  \"What's there\" from the dry-run's counts-per-category summary — one row\n  per non-zero category in plain words (`Plans`, `MCP servers`, `Settings`,\n  `Commands`, `Skills`, `Hooks`, `Policies`, `CLAUDE.md files`, `Knowledge\n  folders`, `Repos`, `Agents`, `Conversations` with the per-tool breakdown as\n  `detail`) — emit it, then ask the run-now-or-skip question (`header`:\n  \"Import\", options `Import now` \u002F `Skip for now`).\n- **Skip** → note that `\u002Fimport-context` is available anytime, and add it to the\n  Phase 5 recommended-commands list so it resurfaces in their launch block.\n\nBecause `\u002Fimport-context` already creates companies (`\u002Fnewcompany`) and workers\n(`\u002Fnewworker`) inline and confirms every write, running it here is the canonical\nway to hydrate the skeleton — do not hand-roll an equivalent import. Whatever it\nbrings in becomes context for Dream Big (4.5) and the action interview (5).\n\n*(guided: `[hq-setup] step=import status=done`)*\n\n## Phase 1: Identity\n\n*(guided: `[hq-setup] step=you status=running`)*\n\nAsk these 5 questions. One at a time — one message per question, the\nquestion as its bold last line. These answers are the strategic frame for\nthe whole wizard — they feed the knowledge files (Phase 2), the Dream Big vision\nblock (Phase 4.5), and every tailored command in the action interview (Phase 5).\nSo gather all five before moving on.\n\n1. **What's your name?**\n2. **What do you do?** (1-2 sentences — your roles, work, domain)\n3. **What are your goals for using HQ?** (what do you want AI workers to help with?)\n4. **What are your biggest challenges or pain points right now?** (what's hard,\n   slow, repetitive, or keeps slipping)\n5. **What are your main systems of record?** (where your truth lives — DB, CRM,\n   Slack, email, analytics, repos, spreadsheets, etc.) For each, capture its\n   **name + type**, and note which ones have a **credential** we could connect\n   later (a connection string, API token, etc.). Don't ask for the secret itself\n   — just whether one exists.\n\nPersonal scope lives at the top-level `personal\u002F` directory (peer of `core\u002F`), not as a company. Workers, knowledge, policies, and skills you create for yourself live under `personal\u002F{type}\u002F...` — they are read directly from `personal\u002F` (the old `core\u002F\u003Ctype>\u002F` symlink mirror was retired), so they load without any mirror step and survive `\u002Fupdate-hq`. (Personal skills surface via the `.claude\u002Fskills\u002Fpersonal:\u003Cname>\u002F` bridge.)\n\n## Phase 1.5: Social presence + browser harness\n\nLearn who the user is from their public presence — and initialize their browser\nharness in the process, so they leave setup ready to have HQ drive the web for\nthem. One question at a time. Everything here is optional; never block setup.\n\n### 1. Frame it\n\nOne short message: \"Let's connect your browser so HQ can learn from your public\npresence — and so you've got a browser harness ready for future work (research,\nfilling forms, pulling data from sites you're logged into).\"\n\n### 2. Detect \u002F initialize the browser harness\n\nCheck whether a browser harness is connected:\n\n- **Claude Code:** call `mcp__Claude_in_Chrome__list_connected_browsers`. If no\n  browser is connected, point the user to install the **Claude for Chrome**\n  extension (the recommended harness), then wait for them to connect and re-check.\n- **Codex:** use the Codex browser tool equivalent if present.\n\nThe browser harness is what makes **login-walled** profiles (LinkedIn,\nInstagram, X) readable — it drives the user's own authenticated session,\nso it sees what they see.\n\n**Fallback (no harness):** if the user declines or can't install the extension,\nfall back to best-effort public fetching with `WebFetch` + `WebSearch`, and tell\nthem up front that login-walled sources (LinkedIn, Instagram, X) will be skipped.\nNever block on the extension.\n\n### 3. Ask for profiles — ONE AT A TIME\n\nAsk for each, accepting \"skip\" for any (use AskUserQuestion, one per call):\n\n1. X \u002F Twitter\n2. LinkedIn\n3. Instagram\n4. Personal website \u002F blog\n5. (optional) GitHub\n\n### 4. Read each source\n\nFor every URL the user provided (these are the user's **own** profiles, so the\nlink-safety suspicion check is satisfied):\n\n- **With harness:** `navigate` to the URL, then `get_page_text` \u002F `read_page`.\n- **Without harness:** for X \u002F Twitter, say in one plain line that it is skipped\n  and use `WebSearch` \"{name} {handle}\" to fill gaps.\n  Never `WebFetch` x.com or twitter.com.\n  For other public profiles, `WebFetch` the page and use\n  `WebSearch` to fill gaps for walled sources.\n\n**Delegate the fetch + synthesis to a subagent** (Task \u002F Agent tool) that returns\na **text summary only** — keep raw pages and any screenshots out of the parent\nsession (HQ context diet; parent stays under the image cap). Ask the subagent for:\nwho they are publicly, what they work on \u002F care about, recurring themes, and\nvoice\u002Ftone cues — plus which sources it couldn't reach.\n\n### 5. Persist the understanding (synthesized, never raw)\n\nWrite only synthesized understanding — never raw page dumps, never credentials,\nnever session URLs. Create the dir first if needed (`mkdir -p personal\u002Fknowledge`):\n\n**personal\u002Fknowledge\u002Fsocial-presence.md:**\n```markdown\n# {Name} — Public Presence\n\n_Synthesized during \u002Fsetup from the profiles below. Refresh anytime._\n\n## Who they are publicly\n{1–2 paragraph synthesis}\n\n## Themes & focus\n- {recurring topic \u002F area}\n\n## Voice & tone cues\n- {observed phrasing, register, what they sound like}\n\n## Profiles\n| Source | Link | Read? |\n|---|---|---|\n| X | {url} | {yes \u002F walled \u002F skipped} |\n| LinkedIn | {url} | {yes \u002F walled \u002F skipped} |\n| ... | | |\n```\n\nHold this understanding in working memory — Phase 2 weaves it into `profile.md`,\n`agents-profile.md`, and `voice-style.md`, and Phase 4.5 + Phase 6 draw on it.\n\n## Phase 2: Generate Files\n\n### Repos directory (required)\n\nCode repos live under `repos\u002Fpublic\u002F` and `repos\u002Fprivate\u002F`. Knowledge bases are **real directories** under `personal\u002Fknowledge\u002F` or `companies\u002F{slug}\u002Fknowledge\u002F`. 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\u002F`.\n\n```bash\nmkdir -p repos\u002Fpublic repos\u002Fprivate\n```\n\n### Personal scaffold\n```bash\nmkdir -p personal\u002F{knowledge,policies,workers,settings,skills,hooks}\n```\n\n### Company structure (only when adding a real company — use `\u002Fnewcompany {slug}` instead)\nFor reference, a company directory looks like:\n```\ncompanies\u002F{slug}\u002F{settings,data,knowledge,workers,policies}\n```\nThe schema and a fillable template live at `companies\u002F_template\u002F`.\n\n### Knowledge directories\n\nPersonal and company knowledge directories must be **real directories** so cloud\nsync uploads document contents. Do **not** symlink `personal\u002Fknowledge\u002F` or\n`companies\u002F{slug}\u002Fknowledge\u002F` into `repos\u002F` — sync records symlinks as vault\nmarkers and teammates receive nothing. Company knowledge must remain a plain\ndirectory; do not initialize Git inside it. Add a company through\n`\u002Fnewcompany {slug}`, which creates that directory and records its path in the\nmanifest.\n\nFor each **personal** knowledge base that needs separate version history:\n\n1. Create the directory and embedded git repo:\n```bash\nmkdir -p personal\u002Fknowledge\u002F{name}\ncd personal\u002Fknowledge\u002F{name}\ngit init\nprintf '# %s Knowledge Base\\n' \"{Name}\" > README.md\ngit add . && git commit -m \"init knowledge repo\"\ncd -\n```\n\nVerify:\n\n```bash\ntest -d personal\u002Fknowledge\u002F{name} && ! test -L personal\u002Fknowledge\u002F{name} \\\n  && echo \"OK: knowledge is a real directory\"\n```\n\n**Optional:** turn all of `personal\u002Fknowledge\u002F` into one git repo for cross-machine sync:\n```bash\n# Only when personal\u002Fknowledge\u002F is still empty or the user confirms migration\nmkdir -p personal\u002Fknowledge\ncd personal\u002Fknowledge\ngit init\nprintf '# Personal Knowledge Base\\n' > README.md\ngit add . && git commit -m \"init personal knowledge\"\ncd -\n```\n\nIf you skip embedded Git, HQ Git tracks `personal\u002Fknowledge\u002F` as a plain directory. This works for single-machine setups. Company knowledge stays plain and syncs through its vault.\n\n**The starter kit's bundled knowledge (Ralph, workers, ai-security-framework, etc.) ships as plain directories. Explain to the user:**\n```\nBundled knowledge (Ralph, workers, security framework) ships as plain directories.\nKeep those real directories in place so upgrades and sync see their contents. Add\npersonal or company-specific knowledge under personal\u002Fknowledge\u002F or\ncompanies\u002F{slug}\u002Fknowledge\u002F. Personal knowledge may use embedded Git for separate\nversion history. Company knowledge must stay a plain directory; never initialize\nGit there or move it into repos\u002F and symlink it back.\n```\n\n### Profile files\n\n**personal\u002Fknowledge\u002Fprofile.md:**\n```markdown\n# {Name}'s Profile\n\n## About\n{Answer from Q2 — enriched with the public-presence synthesis from Phase 1.5 if\navailable. Cross-reference: see personal\u002Fknowledge\u002Fsocial-presence.md.}\n\n## Goals\n{Answer from Q3}\n\n## Challenges\n{Answer from Q4 — the pain points HQ should help attack}\n\n## Systems of Record\n{Answer from Q5, as a table}\n\n| System | Type | Has credential? |\n|---|---|---|\n| {name} | {DB \u002F CRM \u002F Slack \u002F email \u002F analytics \u002F repo \u002F ...} | {yes \u002F no} |\n\n## Preferences\n- Communication style: [to be filled by \u002Fpersonal-interview]\n- Autonomy level: [to be filled by \u002Fpersonal-interview]\n```\n\n**personal\u002Fknowledge\u002Fsystems-of-record.md** (canonical list workers consult to\nknow where the user's truth lives — write full prose, one row per system from\nQ5; `Connection` starts as `capture-only` and flips to `connected` in Phase 5b.5\nwhen a secret-link is minted):\n```markdown\n# {Name}'s Systems of Record\n\nWhere the truth lives. Workers consult this before assuming or re-deriving data.\n\n| System | Type | Has credential? | Connection |\n|---|---|---|---|\n| {name} | {type} | {yes \u002F no} | {capture-only \u002F connected \u002F not yet} |\n\n> To connect a system later: `\u002Fhq-secrets` (mints a link you fill in; the agent\n> never sees the secret). Never paste a credential or a share\u002Fsecret link into\n> this file — those are capabilities, surfaced inline at mint time only.\n```\n\n**personal\u002Fknowledge\u002Fvoice-style.md:**\n```markdown\n# {Name}'s Voice Style\n\n## Observed cues\n{Seed with the voice\u002Ftone cues synthesized in Phase 1.5, if any — e.g. register,\nrecurring phrasing, how they sound publicly. Leave a note if none were captured.}\n\nRun `\u002Fpersonal-interview` to deepen this with your authentic voice and\ncommunication style.\n```\n\n**agents-profile.md** (root level — first line MUST match `# {Name} - Profile` for the inject-local-context.sh hook regex):\n```markdown\n# {Name} - Profile\n\n- **Location**: {city}\n- **Background**: {Answer from Q2 — folded together with the Phase 1.5\n  public-presence synthesis if available}\n\n## Goals\n{Answer from Q3}\n\n## Challenges\n{Answer from Q4 — surfaced every session via inject-local-context.sh so workers\nknow the standing pain points to attack}\n\n## Working Preferences\n\nRun `\u002Fpersonal-interview` to populate the autonomy matrix and communication style.\n\n## Company Roster\n\nFull company\u002Frole context lives in `agents-companies.md` (three tiers: Operate \u002F Client \u002F Portfolio).\n```\n\n**personal\u002Fagents-companies.md** (created empty, populated by `\u002Fpersonal-interview` or manually):\n```markdown\n# {Name} — Company Contexts\n\n> Three tiers: (1) Operate = founder\u002FCEO hats. (2) Client = paid build work. (3) Portfolio = advisory\u002Fequity.\n> Within Operate: active \u002F slow-burn \u002F on hold. `slug` = the key in `companies\u002Fmanifest.yaml`.\n\n## 1. Operate — Founder \u002F CEO hats\n\n_Run `\u002Fpersonal-interview` or edit manually to populate._\n\n## 2. Client work (build, not owned)\n\n## 3. Portfolio \u002F Advisory\n```\n\nAdd to `.gitignore` if not already present:\n```\n# Personal knowledge contents (tracked by embedded git when configured)\npersonal\u002Fknowledge\u002F\n```\n\n### Index\n```bash\nqmd update 2>\u002Fdev\u002Fnull || qmd index . 2>\u002Fdev\u002Fnull || true\n```\n\n## Phase 3: Summary\n\n```\nHQ Setup Complete!\n\nCreated:\n- repos\u002Fpublic\u002F, repos\u002Fprivate\u002F (code repositories only)\n- personal\u002F scaffold (knowledge, policies, workers, settings, skills, hooks)\n- personal\u002Fknowledge\u002Fprofile.md\n- personal\u002Fknowledge\u002Fsystems-of-record.md\n- personal\u002Fknowledge\u002Fsocial-presence.md (if profiles captured in Phase 1.5)\n- personal\u002Fknowledge\u002Fvoice-style.md\n- agents-profile.md\n- agents-companies.md\n- personal\u002Fknowledge\u002F as a real directory (optionally an embedded git repo)\n\nHQ Cloud:\n✓ Signed in {as email} — or \"not connected (run \u002Fhq-login later)\"\n✓ Synced — {N companies} or \"solo, nothing to pull yet\"\n\nDependencies:\n✓ claude (Claude Code CLI)\n✓ qmd (semantic search) — or skipped\n✓ gh (GitHub CLI) — or skipped\n\nStill needs attention:      ← include this block ONLY if a direct install failed\n✗ {tool} — {what failed; the one manual command the user can run to finish it}\n...\n\nKnowledge directories:\nPersonal knowledge bases are real directories under personal\u002Fknowledge\u002F and may\nuse embedded Git for independent version history. Company knowledge lives in a\nplain directory under companies\u002F{slug}\u002Fknowledge\u002F and syncs through the company\nvault. Knowledge directories are never symlinked into HQ.\nSee \"Knowledge directories\" in core\u002Fdocs\u002Fhq\u002FREADME.md for details.\n\nSetup is done. Next: a short orientation + a few questions so I can hand you\nthe exact commands to start your first real work.\n```\n\nDo not print a static next-steps list here. Continue to Phase 4.\n\n## Phase 4: Learn the HQ Mental Model\n\nA brief orientation before the interview. Keep it to roughly a screenful — this\nis a mental model, not a course. Pull the framing from\n`core\u002Fdocs\u002Fhq\u002FUSER-GUIDE.md` rather than reinventing it; do not duplicate the\nhands-on lessons that already live in `\u002Ftutorial`.\n\nPresent this (adapt wording, keep it tight):\n\n```\nHow HQ works — the 60-second model:\n\n  • Sessions are disposable. Start with \u002Fstartwork,\n    do one focused thing, end with \u002Fhandoff (it saves where you left off so\n    the next session resumes exactly there). A fresh session is a feature,\n    not a reset.\n  • Three homes for things: personal\u002F (your overlay — workers, knowledge,\n    policies just for you), companies\u002F (isolated tenants you operate or\n    serve), repos\u002F (all actual code, public or private).\n  • Knowledge compounds. Workers, knowledge docs, and policies you create\n    make every future session smarter — capture learnings, don't re-derive.\n  • Slash commands are the interface. \u002Fnewworker, \u002Fprd, \u002Fdeploy, \u002Fsearch,\n    \u002Fonboard — you drive HQ by naming the capability, not hand-rolling it.\n  • \u002Fsearch (or qmd) finds anything across HQ — knowledge, projects,\n    workers, policies, indexed repos.\n\nGo deeper anytime:\n  • \u002Ftutorial          — hands-on, interactive lessons against your real HQ\n  • \u002Fpersonal-interview — deep dive on your voice + working style so workers\n                          sound and decide like you\n```\n\nThen continue to Phase 4.5 (don't wait for acknowledgement — flow straight in).\n\n## Phase 4.5: Dream Big\n\nBefore the action interview, paint the destination. Ground this entirely in the\nuser's own answers (Q2 what-you-do, Q3 goals, Q4 challenges, Q5 systems of\nrecord) plus the Phase 1.5 public-presence synthesis — generic HQ marketing is\nworse than nothing. Produce **2-3 concrete, tailored scenarios**, each in the\nshape: *their pain point → the HQ capability that attacks it → the outcome they'd\nfeel*. Name the real command in each.\n\n**Templates to adapt — substitute every `\u003C…>` slot with the user's literal Q1-Q5\nwords before emitting. Never print the angle-bracket form to the user.** The `\u003C…>`\nslots are author-time placeholders, not output. If a slot has no matching answer,\ndrop the bullet rather than emit a generic stand-in.\n\nScenario shapes to choose from (pick 2-3 that actually fit the user's answers):\n\n- *Worker for a recurring pain:* \"You said **\u003Ctheir literal Q4 pain point>** eats\n  your time. Build a `\u002Fnewworker` specialist that does exactly that — and it gets\n  smarter every run, so the work compounds instead of repeating.\"\n- *Connect a system, ship a live report:* \"Your truth lives in **\u003Ctheir literal\n  Q5 system, e.g. 'Postgres in Supabase' or 'HubSpot CRM'>**. Connect it once\n  with `hq secrets generate-link`, then `\u002Fdeploy` a live report behind a signed\n  URL your team can open — no copy-paste, no stale screenshots.\"\n- *Compounding knowledge:* \"**\u003Ctheir recurring task from Q2\u002FQ3>** becomes a\n  knowledge base that compounds: every session adds to it via `\u002Flearn`, so you\n  never re-derive the same answer twice.\"\n\n**Worked example — this is the shape of what to actually emit to the user.**\nAssume Q4 = \"I lose hours re-summarizing the same investor updates each week\"\nand Q5 = \"HubSpot CRM (has credential)\":\n\n> You said **losing hours re-summarizing investor updates each week** eats your\n> time. Build a `\u002Fnewworker` specialist that drafts each week's update from your\n> CRM activity — it learns your phrasing every run, so by month three you're\n> editing, not writing.\n>\n> Your truth lives in **HubSpot**. Connect it once with `hq secrets generate-link`,\n> then `\u002Fdeploy` a live investor-update preview behind a signed URL your LPs can\n> open — no copy-paste, no stale screenshots.\n\nKeep it to ~half a screen, aspirational but grounded — not salesy. Close with one\nline, e.g.: \"That's the destination. Let's take the first concrete steps now.\"\nThen flow straight into Phase 5.\n\n## Phase 5: What Do You Need Help With?\n\nA branching interview that both **does** lightweight scaffolding inline and\n**collects** a recommended-command list for future fresh sessions. It ends in a\ntwo-section launch block (done now \u002F run next). Ask one question at a time\n(decision-queue-one-at-a-time). Reuse Phase 1 answers (name, what they do, goals,\nchallenges, systems of record) — never re-ask what's captured.\n\n### 5a. Role discovery (FIRST — before any scope question)\n\nGo one level deeper than Phase 1's high-level \"what do you do\". Conversational,\nfree-text (a picker would flatten the nuance) — one message per question,\nthe question as its bold last line. Phase 1 Q4 already captured pain\npoints — don't re-ask. Focus here on the day-to-day texture that shapes which\ncommands to suggest:\n\n1. **What's your specific role?** (title + the hat you actually wear day-to-day)\n2. **Walk me through a typical day — what do you actually spend time on?**\n\nThese answers, plus the Q4 challenges and Q5 systems of record, anchor every\ncommand suggestion below — keep them in working memory for the synthesis step.\n\n### 5b. Primary scope (AskUserQuestion)\n\nOne AskUserQuestion call, four options:\n\n- `Run my own companies \u002F clients`\n- `Personal projects & automation`\n- `Learn \u002F explore HQ first`\n- `Bring in an existing codebase`\n\n*(guided: `[hq-setup] step=you status=done` then `[hq-setup] step=connect status=running`\nbefore 5b.5)*\n\n### 5b.5. Connect a system of record (inline, optional)\n\nFor each Q5 system the user said has a credential, offer to wire it up **now** so\nthey leave setup with a real connection, not just a note. This is the one\nwrite-side connection primitive HQ has (`hq sources` is read-only).\n\n**Guided mode (HQ Desktop):** do not mint a link. For each system, emit a\n`secret` card and then one AskUserQuestion — the desktop shows a masked field,\nstores the value with `hq secrets set --from-stdin` itself (the value never\nenters this session), and answers `Done`:\n\n```\n[hq-setup] card={\"kind\":\"secret\",\"name\":\"DATABASE_URL\",\"label\":\"Postgres connection string\",\"hint\":\"Starts with postgres:\u002F\u002F\",\"scope\":\"company\",\"company\":\"{slug}\"}\n```\n\n- `question`: \"Add your {label} now? It goes straight into the HQ vault.\"\n- `header`: \"Secret\"\n- `multiSelect`: false\n- `options`: `Done` — \"It's stored in the vault\" · `Skip` — \"Leave it for later\"\n\nOn `Done`, confirm the name now appears in `hq secrets list [--personal |\n--company {slug}]` (names only — never `get` the value) before flipping the\nsystem to `connected`. On `Skip`, it stays `capture-only`.\n\n**Terminal mode:** mint a one-time link instead:\n\n```bash\nhq secrets generate-link \u003CSECRET_PATH> [--personal | --company {slug}]\n```\n\n- Pick a sensible `SECRET_PATH` per system (e.g. `DATABASE_URL`, `SLACK_TOKEN`,\n  `STRIPE_API_KEY`). Use `--personal` for personal scope, or `--company {slug}`\n  matching the scope chosen in 5b.\n- The command mints a one-time URL the user opens to enter the secret — the agent\n  never sees it. **Surface that URL inline at mint time only.** It is a\n  capability: never write it into `systems-of-record.md`,\n  `getting-started-next-steps.md`, or any later turn (per\n  `hq-share-session-urls-are-capabilities`).\n- After each one is wired, flip that system's `Connection` cell in\n  `personal\u002Fknowledge\u002Fsystems-of-record.md` from `capture-only` to `connected`.\n- Accept \"skip\" for any system → it stays `capture-only`; add `\u002Fhq-secrets` to\n  the recommended-commands list so they can connect it later.\n\n### 5b.6. Connect apps (inline, optional — company scope only)\n\nIf 5b chose a company scope and the company is cloud-backed, offer the apps HQ\nrecommends for that company so agents can use them from day one. Derive the\nlist from the authoritative catalog — never a hand-kept list:\n\n```bash\nhq integrations catalog --company {slug} --json   # candidates\nhq integrations list --company {slug} --json      # already connected\n```\n\n- Keep catalog rows with `\"source\": \"hq-recommended\"` and `\"mcpReady\": true`\n  whose `authClass` is `oauth` or `none` (API-key apps need a key intake the\n  guided run does not have yet — mention `\u002Fhq-integrations` for those). Cap\n  at six, catalog order. Mark any whose provider is already in `list` as\n  `connected`.\n- Nothing left to offer, or personal scope, or solo HQ → skip this step\n  silently.\n\n**Guided mode:** emit an `integrations` card, then one multi-select\nAskUserQuestion whose option labels are exactly the app names plus\n`Skip for now`:\n\n```\n[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\"}]}\n```\n\n- `header`: \"Integrations\" · `question`: \"Which apps should HQ connect now?\"\n\n**Terminal mode:** the same question without the card.\n\nFor each picked app run `hq integrations connect --entry-id \u003Cid> --company\n{slug}` one at a time. OAuth opens the browser; relay the two outcomes exactly\nas `\u002Fhq-integrations` describes (\"Connected …\" is live; a printed sign-in URL\nmeans **not connected yet**). After the batch, re-emit the `integrations` card\nwith updated `status` values in guided mode, and add `\u002Fhq-integrations` to the\nrecommended-commands list for anything skipped.\n\n*(guided: `[hq-setup] step=connect status=done` then\n`[hq-setup] step=moves status=running` before 5c)*\n\n### 5c. Team \u002F cloud detection (shapes the strongest recommendation)\n\nUse the membership list already resolved in Phase 0c step 3 — do not re-derive\nthis from a manifest grep. If the user has at least one active company\nmembership, this is a team \u002F cloud context, full stop. A joiner whose manifest\nhas not caught up yet is still on a team.\n\nOnly when membership could not be resolved at all (API unreachable), fall back\nto the local signals:\n\n```bash\ngrep -l 'cloud' companies\u002F*\u002Fmanifest.yaml 2>\u002Fdev\u002Fnull | head -1\ngrep -iE 'cloud_backed|hq[-_]?pro|team' companies\u002Fmanifest.yaml 2>\u002Fdev\u002Fnull | head -3\n```\n\nAlso treat it as team\u002Fcloud if `companies\u002Fmanifest.yaml` has at least one real\ncompany entry (top-level keys under `companies:`), or the user's role-discovery\nanswers describe working with a team. Notes:\n\n- The top-level `personal\u002F` overlay does not count — it's not a company.\n- `companies\u002F_template\u002F` does not count either — it's the scaffold copied by\n  `\u002Fnewcompany`, and is never listed in `manifest.yaml`. A fresh HQ install\n  with only `_template\u002F` on disk is **solo**, not team\u002Fcloud.\n\n**If team\u002Fcloud** — make the headline recommendation a *shareable asset* task:\n\n- Build a reusable asset grounded in the role-discovery pain point, then share\n  it with the team: `\u002Fnewworker` (a specialist for the draining task), or a\n  knowledge doc + `\u002Flearn`, then `\u002Fhq-share \u003Cpath>` (or `\u002Fdesignate-team` to\n  make the company cloud-backed for the whole team).\n- And\u002For **produce a report and deploy it**: `\u002Fprd` (or a direct artifact) →\n  `\u002Fdeploy` — framed as \"show your team something real, behind a signed URL\".\n\n**Deploy is not team-gated.** Even for solo \u002F personal scope, surface a\n\"create something small and `\u002Fdeploy` it\" task as a high-value early win\n(a report, a one-pager site, a shareable result).\n\n### 5d. Branch follow-ups — split do-now vs recommend (AskUserQuestion, one at a time)\n\nMirror how `\u002Ftutorial` Step 1 and `\u002Fstartwork` gate picks. For each branch, sort\nactions into **(a) do-now inline** (lightweight, high-momentum — run this\nsession) and **(b) recommend for a fresh session** (heavy \u002F context-hungry — add\nto the launch list, do NOT run inline). See the Rules for the inline\u002Fhandoff line.\n\n- **Companies \u002F clients** → \"Is the company already in HQ?\"\n  - *Do now:* `\u002Fnewcompany {slug}` (new — lightweight scaffold) or `\u002Fonboard`\n    (join existing). If Phase 0d was skipped and they're an existing Claude\n    user, re-offer `\u002Fimport-context` here to hydrate the skeleton.\n  - **Never offer `\u002Fnewcompany` for a slug the user already has an active\n    membership in.** Check the membership list resolved in Phase 0c step 3\n    first. Routing a joiner to `\u002Fnewcompany` for a company they already belong\n    to is what produced the duplicate companies this flow exists to prevent —\n    they end up owning a second, empty company with the same name as the real\n    one. If the slug matches an existing membership, the answer is \"you're\n    already in that one\" plus `\u002Fstartwork {slug}`, not a scaffold.\n  - *Recommend:* first deliverable → `\u002Fbrainstorm` \u002F `\u002Fprd` \u002F `\u002Fstartwork {slug}`.\n    If team\u002Fcloud, fold in the shareable-asset + `\u002Fdeploy` recommendation.\n- **Personal projects** → \"What's the first thing you want a worker to do?\"\n  (anchored to role-discovery + Q4 challenges).\n  - *Do now:* `\u002Fidea` to capture it on the board; `\u002Fnewworker` if a recurring\n    specialist is clearly implied.\n  - *Recommend:* `\u002Fprd` for the first real deliverable, plus the solo\n    `\u002Fdeploy` early-win.\n- **Learn first** → *Do now:* nothing heavy. *Recommend:* `\u002Ftutorial` (suggest a\n  topic from role-discovery + Phase 1 goal) then `\u002Fpersonal-interview`.\n- **Existing codebase** → *Do now:* note the clone target (`repos\u002Fpublic\u002F` or\n  `repos\u002Fprivate\u002F`). *Recommend:* `\u002Fdiscover \u003Crepo>` in a fresh session (it's\n  context-hungry — never run inline during setup).\n\n### 5e. Synthesize + emit the two-section launch block\n\nProduce two ordered lists, each command **fully substituted** (real slugs\u002Fpaths\n— never `{placeholder}` tokens), each with a one-line \"why\" tied to their\nanswers. Print inline:\n\n```\nYou're set up. Here's where you landed.\n\nDone this session:\n  ✓ {what was actually scaffolded \u002F connected — company, idea, secret-link, knowledge doc}\n  ...\n\nRun these next — start a FRESH session for each (context hygiene, see Phase 4):\n  1. {command}        — {why, tied to their challenge \u002F goal \u002F system of record}\n  2. {command}        — {why}\n  ...\n\nSaved to personal\u002Fknowledge\u002Fgetting-started-next-steps.md — reopen anytime.\n```\n\n### 5f. Persist the artifact\n\nWrite `personal\u002Fknowledge\u002Fgetting-started-next-steps.md` (the dir is created in\nPhase 2, so the path always exists). Full prose — this is a disk artifact, not\nchat. Contents:\n\n- Generated date\n- The user's role + stated goal + top challenges (from Phase 1 + 5a)\n- **Done this session** — what was actually scaffolded\u002Fconnected (company, idea,\n  knowledge docs, which systems of record got connected)\n- **Run these next** — the same recommended command list shown inline, each with\n  its rationale, one fresh session per command\n- A \"Your systems of record\" recap (mirror the table, with connection status) so\n  they remember what's wired vs still to connect\n- An \"If you get lost\" footer: `\u002Fstartwork`, `\u002Ftutorial`, `\u002Fsearch \u003Ctopic>`\n\n**Never** write any secret-link \u002F share URL into this file — those are\ncapabilities, surfaced inline at mint time only.\n\nIf the file already exists, show the user what would change and confirm via\nAskUserQuestion before overwriting (per the Rules below — never overwrite\nsilently).\n\n## Phase 6: Deploy the welcome page + hand off\n\nThe visual capstone. Turn everything learned into a small, **private**,\npersonalized welcome page and publish it, then send the user off to a fresh\nsession. Requires the Cognito login from Phase 0c; if the user never signed in,\nskip the deploy and just deliver the launch block + handoff message in chat.\n\n### 1. Build the page (one `index.html`)\n\nGenerate a single `index.html` — **never** multiple `.html` files: the static\nhost SPA-fallbacks every `.html` subpath to `index.html` silently, so use one\nfile with a `#\u002Froute` hash router if it needs sections.\n\n- **Design:** if the `impeccable` skill is available, use it to craft the page\n  (the owner's lives at `personal\u002Fskills\u002Fimpeccable\u002F`). If it's absent in this\n  HQ, produce a high-quality inline design instead — degrade gracefully, never\n  hard-depend on impeccable.\n- **Content** — four sections, all drawn from earlier phases:\n  1. **Who you are** — the synthesis from Phase 1 (identity) + Phase 1.5\n     (public presence).\n  2. **How your HQ is set up** — cloud companies synced (Phase 0c), the personal\n     scaffold, systems of record and which are connected.\n  3. **Starter moves** — the Phase 5 recommended commands as **copy-paste prompt\n     blocks**, each fully substituted (real slugs\u002Fpaths — never `{placeholder}`),\n     each with a one-line \"why\".\n  4. **Hand off** — close this session, start a fresh one, paste the first prompt.\n- Stage it in a scratch dir (e.g. `workspace\u002Fsetup-welcome\u002Findex.html`).\n\n### 2. Deploy private\n\nRun the `\u002Fdeploy` skill on the staged dir with **private (owner-only)** access\nmode. The page holds personal understanding, and `sensitivity-check.sh` greps\nfilenames only — it returns `sensitive:false` for a lone `index.html` even when\nthe content is personal — so set the access mode to private manually; do not rely\non the auto-verdict.\n\n### 3. Surface the link + hand off\n\nPrint the deploy URL **inline, in one plain line** (this is the `\u002Fdeploy`\ncapability carveout — surfaced at publish time, never re-pasted into knowledge\nfiles or later turns). Then point the user to the guided public course as their\ncanonical visual walkthrough:\n\n`https:\u002F\u002Fwww.hqforwork.com\u002Fgetting-started\u002Ftutorials\u002Finstall-hq-macos?source=hq_setup_wizard`\n\nCall it the **guided HQ tutorial (videos + written steps)** so it stays distinct\nfrom the adaptive, in-agent `\u002Ftutorial` command. Then deliver the handoff message:\n\n```\nYou're all set — here's your welcome page (private to you): {url}\n\nFollow the guided HQ tutorial here (videos + written steps):\nhttps:\u002F\u002Fwww.hqforwork.com\u002Fgetting-started\u002Ftutorials\u002Finstall-hq-macos?source=hq_setup_wizard\n\nOpen it, then close this session and start a fresh one. Your first move:\n\n  {first copy-paste prompt, fully substituted}\n\n(A fresh session per task keeps context clean — see your welcome page for the\nfull list.)\n```\n\n### 4. Teach the `\u002Fhandoff` habit before they go\n\nThis is the one habit that makes every future session work. Setup is where they\nlearn it, so end by teaching it explicitly — don't leave it as an optional\naside.\n\nDeliver a short, plain-language nudge along these lines (adapt the wording, keep\nit to a few lines):\n\n```\nOne habit that'll save you every time: when you finish real work in a\nsession, end it with \u002Fhandoff.\n\n\u002Fhandoff writes down where you left off — what you did, what's next, which\nfiles changed — and saves it so a fresh session picks up exactly there. No\n\"remind me what we were doing.\" You just run \u002Fstartwork next time and it's\nall waiting.\n\nThe rhythm is: \u002Fstartwork → do one focused thing → \u002Fhandoff → close the\nsession. Try it at the end of your very first work session.\n```\n\n**Nudge, don't just mention.** As real work accumulates in *this* session\n(a company scaffolded, a worker built, a knowledge doc written), it's worth\nactively offering to run `\u002Fhandoff` now so they see it once end-to-end — for a\nbare setup with nothing substantive done yet, teaching the habit is enough and\nstarting fresh with the first prompt is fine. Either way, they should leave\nsetup knowing what `\u002Fhandoff` is, why it matters, and how to run it.\n\n*(guided: `[hq-setup] step=moves status=done` as the last line of Phase 6)*\n\n## Rules\n\n- **Guided mode markers are part of the contract.** With `--guided`, every\n  step boundary and every card question carries its marker line (see \"Guided\n  mode\" above); without it, none do.\n- Ask questions one at a time — every phase, including the Phase 0c login prompt\n  and each Phase 1.5 social URL. Never batch. In guided mode a choice is an\n  AskUserQuestion call, a fill-in-the-blank is the bold last line of its own\n  message, and you never narrate how or why you are asking.\n- **Never block setup on HQ Cloud.** Login, invite-claim, and sync (Phase 0c) are\n  best-effort; a solo or offline HQ completes setup fine. There is no\n  list-pending-invites command — invites are claimed by running sync.\n- **Browser harness is optional.** Prefer the Claude for Chrome harness (Codex\n  equivalent in Codex) so login-walled profiles are readable; if the user\n  declines, fall back to public `WebFetch` + `WebSearch` and skip walled sources.\n  Never block on the extension.\n- **Delegate browser reads + scrape synthesis to a subagent** that returns text\n  only — keep raw pages and screenshots out of the parent session (HQ context\n  diet; stay under the image cap). Persist only synthesized understanding, never\n  raw dumps or credentials.\n- **The welcome page is private** and contains personal understanding — set\n  `\u002Fdeploy` access mode to owner-only manually; don't trust the filename-only\n  sensitivity verdict.\n- **`impeccable` is optional** — use it for the welcome page if present, else\n  produce a high-quality inline design. Degrade gracefully.\n- **Inline vs handoff:** scaffold lightweight, high-momentum items inline during\n  setup (`\u002Fnewcompany`, `\u002Fidea`, a knowledge doc, a `hq secrets generate-link`\n  connection). Heavy \u002F context-hungry work (`\u002Fprd`, `\u002Fdiscover`, deep\n  planning) is recommended for a fresh session — never run inline. This honors\n  HQ context hygiene while still delivering first-session momentum.\n- **Secret-link \u002F share \u002F deploy URLs are capabilities** — surface inline at mint\n  or publish time only. Never write them into `getting-started-next-steps.md`,\n  `systems-of-record.md`, `social-presence.md`, or any later turn\n  (`hq-share-session-urls-are-capabilities`).\n- Use defaults when user says \"skip\"\n- Never overwrite existing files without asking\n- Create parent directories as needed\n- **Install missing dependencies and CLI tools directly — never ask.** Do not\n  prompt \"do you want to install X?\" and never surface an install-all \u002F some \u002F\n  none picker for tooling; the standard install command runs unattended. The one\n  exception is an interactive auth that can't run unattended (e.g. `gh auth\n  login`). Don't block setup if an optional tool's install fails — note it in the\n  summary and move on. These are \"recommended\" not \"required\" (except claude itself).\n- 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\n- Phase 4\u002F5 are skippable — if the user says \"skip\", still write `personal\u002Fknowledge\u002Fgetting-started-next-steps.md` using best-effort defaults from Phase 1 answers. Never block setup completion on the orientation or interview\n- Phase 6 (welcome page) is skippable — if the user isn't signed in or declines,\n  skip the `\u002Fdeploy` and just deliver the launch block + handoff message in chat.\n  Never block setup completion on the deploy\n",{"name":5,"description":7,"allowed-tools":43},"Read, Write, Edit, AskUserQuestion, Glob, Bash, Task, WebFetch, WebSearch, Skill, mcp__Claude_in_Chrome__*","main","205cf61728a27ef15e9153aa38df5856fc8d82f5",".claude\u002Fskills\u002Fsetup",18,"https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core","https:\u002F\u002Fgithub.com\u002Findigoai-us","https:\u002F\u002Fhqforwork.com\u002F","The AI Context Layer for Teams","2026-11-12 06:53:38",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add indigoai-us\u002Fhq-core --skill setup",{"tool":59,"command":60},"bunx","bunx skills add indigoai-us\u002Fhq-core --skill setup",{"tool":62,"command":63},"pnpm","pnpm dlx skills add indigoai-us\u002Fhq-core --skill setup","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsetup\u002FSKILL.md",true,[67],{"path":68,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":71,"sourceHtmlUrl":72},"agents\u002Fopenai.yaml","REFERENCE","参考文档",102,"https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsetup\u002Fagents\u002Fopenai.yaml",[74,92,118,141,152,161],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":38},"01M71E4MQ04WPK1EVDS7VKJ3E8","social-graphic","Generate 1080x1080 HTML social graphics for HQ update posts.","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002Fcore\u002Fworkers\u002Fpublic\u002Fsocial-strategist\u002Fskills\u002Fsocial-graphic\u002FSKILL.md",[],[81,82,31,83,30,29,28,84,85,86,87,88,89,90,91],"social","social graphic","html","update","generate","graphics","browser","open","agent-browser","for","posts",{"skillNo":93,"name":89,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":101,"publishedAt":38},"01M71E4H33K4P5H5M7ENPTMFSC","Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to \"open a website\", \"fill out a form\", \"click a button\", \"take a screenshot\", \"scrape data from a page\", \"test this web app\", \"login to a site\", \"automate browser actions\", or any task requiring programmatic web interaction.","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002Fcore\u002Fworkers\u002Fpublic\u002Fqa-tester\u002Fskills\u002Fagent-browser\u002FSKILL.md",[97,100],{"categoryNo":98,"categoryName":99,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[102,87,103,104,105,106,31,107,108,109,110,111,88,112,89,113,114,115,116,117],"agent browser","click","ai agents","app","scrape","when","apps","actions","extracting","take a screenshot","testing","programmatic","browser automation","website","cli","interaction",{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":38},"01M71E4FDBD7J8Y45JJ9KMMYGN","work-mesh","Work Mesh Live — automatic presence via hq mesh daemon; context reconcile\u002Forganize; manual session task-status, blocked, and note only.","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002Fcore\u002Fskills\u002Fwork-mesh\u002FSKILL.md",[],[125,126,127,31,128,129,130,131,132,133,134,135,136,35,28,137,138,139,140],"work mesh","work","mesh","status","context","note","live","presence","automatic","reconcile","only","organize","session","manual","daemon","via",{"skillNo":142,"name":143,"nameZh":6,"description":144,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":145,"categories":146,"keywords":147,"publishedAt":38},"01M71E4EGHNAAGWAPV6KGBMQ9W","review","Parity worker review skill (materialization fixture).","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002Fcore\u002Fscripts\u002Ftests\u002Ffixtures\u002Fagent-session\u002Fworker-materialization\u002Fparity-worker\u002Fskills\u002Freview\u002FSKILL.md",[],[143,148,149,150,151],"review skill","fixture","parity","worker",{"skillNo":153,"name":27,"nameZh":6,"description":154,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":155,"categories":156,"keywords":157,"publishedAt":38},"01M71E4D1FZDJPDC15DRERKX8Y","Run or list HQ workers (parity fixture).","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002Fcore\u002Fscripts\u002Ftests\u002Ffixtures\u002Fagent-session\u002Fskills\u002Frun\u002FSKILL.md",[],[27,158,159,150,160,149],"parity fixture","workers","list",{"skillNo":162,"name":163,"nameZh":6,"description":164,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":165,"categories":166,"keywords":167,"publishedAt":38},"01M71E4BF4MV5SEWZJZ4T1QPQW","handoff","Preserve session state for a follow-up agent (parity fixture).","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002Fcore\u002Fscripts\u002Ftests\u002Ffixtures\u002Fagent-session\u002Fskills\u002Fhandoff\u002FSKILL.md",[],[163,158,168,169,137,170,90,150,171,172,149],"up","preserve","session state","follow-up","state"]