@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/assets/bot-workers/setup/context/quick-reference.md

@@ -0,0 +1,199 @@
+---
+type: reference
+domain: [operations, engineering]
+status: canonical
+tags: [quick-reference, directory-structure, commands, workers, knowledge-bases]
+relates_to: []
+---
+
+# HQ Quick Reference
+
+## Directory Structure
+
+```
+HQ/
+├── .claude/commands/   # Slash commands (44)
+├── AGENTS.md           # Runtime entrypoint (symlink to .claude/CLAUDE.md)
+├── companies/          # Company-scoped resources (14 companies)
+│   └── {co}/
+│       ├── knowledge/  # Embedded git repo (company knowledge)
+│       ├── policies/   # Standing operational rules
+│       ├── repos/      # Symlinks → repos/{pub|priv}/
+│       ├── settings/   # Credentials & config
+│       ├── workers/    # Company-scoped workers
+│       ├── data/       # Exports, reports
+│       └── board.json  # OKR board
+├── core/               # System tree (canonical, shipped with HQ)
+│   ├── hooks/          # Always-on system hooks (loaded first)
+│   ├── docs/hq/        # Public HQ docs (README, CHANGELOG, MIGRATION, USER-GUIDE)
+│   ├── knowledge/
+│   │   ├── public/     # Bundled real directories tracked by hq-core
+│   │   └── private/    # Private real directories when configured
+│   ├── policies/       # Cross-cutting + command-scoped policies
+│   ├── settings/       # Orchestrator config
+│   ├── skills/         # Core skills (surface as /<skill>)
+│   └── workers/
+│       └── public/     # Shareable workers (dev-team, content-*, social-*, gardener-*, gemini-*, etc.)
+├── personal/           # User-personal overlay (mirrors core/ shape)
+│   ├── hooks/          # Always-on user-global hooks (loaded AFTER core/hooks)
+│   ├── projects/       # Personal/HQ project PRDs and brainstorms
+│   ├── knowledge/      # Read directly from personal/ (no core/ mirror)
+│   ├── policies/       # Read directly by the policy trigger hook (no core/ mirror)
+│   ├── settings/       # Read directly from personal/ (no core/ mirror)
+│   ├── skills/         # Surface as /<skill> with (project:personal) tag
+│   └── workers/        # Read directly from personal/ (no core/ mirror)
+├── repos/
+│   ├── public/         # Open-source code repos
+│   └── private/        # Private code repos
+└── workspace/
+    ├── checkpoints/    # Session saves
+    ├── orchestrator/   # Ralph loop workflow state
+    ├── reports/        # Generated reports
+    ├── social-drafts/  # Social content pipeline
+    └── threads/        # Session threads + handoff.json
+```
+
+**Personal overlay semantics.** `personal/` mirrors the shape of `core/` but is user-personal authoring space. The old reindex symlink mirror into `core/` was **retired** — `personal/{knowledge,policies,settings,workers}` are now read DIRECTLY from `personal/` by the code that consumes each (the policy trigger hook, the workers-registry generator, the session/knowledge readers), and reindex prunes any leftover mirror symlinks:
+
+| Subdir | Runtime behavior |
+|---|---|
+| `personal/hooks/<event>/*.sh` | **Loaded as a separate ordered layer** — runs after `core/hooks/<event>/` and before `core/packages/*/hooks/<event>/` |
+| `personal/skills/<skill>/SKILL.md` | Surfaces as `/<skill>` — same flat command name as a core skill. Claude Code's `.claude/commands/<subdir>/<name>.md` surfacing puts the subdirectory in the command *description* (`(project:personal)`), not the command name. Collisions with a core skill of the same name are won by whichever ordering Claude Code resolves first; rename your personal skill to disambiguate. |
+| `personal/knowledge/<entry>` | Read directly from `personal/knowledge/` (no `core/` mirror) — loads alongside core |
+| `personal/policies/<entry>` | Read directly by the policy trigger hook (no `core/policies/` mirror) — loads as global; NOT a separate precedence layer |
+| `personal/workers/<entry>` | Walked directly by the workers-registry generator (no `core/workers/` mirror) — surfaces as a worker |
+| `personal/settings/<entry>` | Read directly from `personal/settings/` (no `core/settings/` mirror) |
+
+Collision rule: with the mirror retired there is no link path to collide on. Both the personal and the core copy are read; a consumer that dedups by identity resolves same-id twins with personal first (e.g. the policy trigger hook scans `personal/policies/` ahead of `core/policies/`, so an operator's global rule wins over a same-id core copy).
+
+## Companies (14)
+
+| Company | Workers | Key Resources |
+|---------|---------|---------------|
+| {company} | cfo, analyst, infobip-admin, gtm, qa, deploy | Stripe, Gusto, Deel, QB, Shopify, Linear (acme-recover) |
+| {company} | cmo | AWS (Route 53), Linear, LinkedIn, Loops |
+| personal | x-user, invoices, social-council | Slack, Gmail, LinkedIn, X |
+| acmework | site-builder, research-agent | Stripe |
+| acmestudio | — | Band/music |
+| acme-haven | — | Artist site + admin |
+| acme-mgmt | — | Artist manager monorepo |
+| acmebrands | — | AcmeBrands AI |
+| acme-estate | — | Estate platform |
+| acmebrand | — | Shopify store |
+| acmeflow | — | Expo mobile app |
+| acmedom | — | Domain management |
+| acme-rebrand | — | GTM/growth |
+
+## Workers
+
+**Public (`core/workers/public/`):** frontend-designer, qa-tester, security-scanner, pretty-mermaid, site-builder, knowledge-tagger, exec-summary, accessibility-auditor, performance-benchmarker
+
+**Dev Team (17):** `core/workers/public/dev-team/`
+project-manager, task-executor, architect, backend-dev, database-dev, frontend-dev, infra-dev, motion-designer, code-reviewer, knowledge-curator, product-planner, dev-qa-tester, codex-engine, codex-coder, codex-reviewer, codex-debugger, reality-checker
+
+**Content Team (5):** `core/workers/public/content-*/`
+content-brand, content-sales, content-product, content-legal, content-shared
+
+**Social Team (5):** `core/workers/public/social-*/`
+social-shared, social-strategist, social-reviewer, social-publisher, social-verifier
+
+**Gardener Team (3):** `core/workers/public/gardener-team/`
+garden-scout, garden-auditor, garden-curator
+
+**Gemini Team (3):** `core/workers/public/gemini-*/`
+(gemini-coder, gemini-reviewer, gemini-frontend — install via @indigoai-us/hq-pack-gemini)
+
+**Company Workers:** Located at `companies/{co}/workers/`. See manifest.yaml for full list per company.
+
+## Commands (44)
+
+**Session:** `/startwork`, `/reanchor`, `/checkpoint`, `/handoff`, `/recover-session`, `/remember`, `/learn`
+**Handoff:** `/delegate <recipient> [project]` — transfer a project to a person or fleet agent: vault grants (verified), branch push, secrets by name, board + work-mesh reassignment, and a self-pulling pickup DM (no `/hq-sync` needed on their side). Skill: `.claude/skills/delegate/SKILL.md`; manifest spec: `core/knowledge/public/hq-core/delegation-bundle-spec.md`.
+**Workers:** `/run`, `/newworker`
+**Projects:** `/plan`, `/run-project`, `/execute-task`, `/understand-project`, `/idea`, `/goals`, `/dashboard`, `/tdd`, `/quality-gate`
+**Content:** `/contentidea`, `/suggestposts`, `/preview-post`, `/post`, `/post-results`, `/social-setup`
+**Communication:** `/email`, `/checkemail`, `/imessage`
+**Design:** `/generateimage`
+**System:** `/cleanup`, `/garden`, `/search`, `/search-reindex`, `/harness-audit`, `/model-route`, `/update-hq`
+**Company:** `/newcompany`, `/launch-brand`, `/pb-connect`, `/bootcamp-student`, `/personal-interview`
+**Linear:** `/check-linear-acme-recover`, `/{product}-prd`
+**Deploy:** `/pr`
+
+## CLI: `hq mesh` (Work Mesh Live)
+
+Presence and per-turn activity are automatic via hooks + `hq mesh daemon`. Manual verbs only: `task-status`, `blocked`, `note`. See `core/knowledge/public/hq-core/work-mesh-live.md` and `core/skills/work-mesh/`.
+
+| Command | Use |
+|---------|-----|
+| `hq mesh daemon install\|status\|doctor` | Resident presence + spool flush (replaces pack listen) |
+| `hq mesh context reconcile` (`--observation-file`/`--observation-json`) | Resolve company/project (no `--session`) |
+| `hq mesh context organize\|correct\|untracked` (`--session` / sessionId arg) | Bind, correct, or mark untracked |
+| `hq mesh context default get\|set\|clear` | Device default company |
+| `hq mesh session task-status\|blocked\|note\|flush` (`--session-id`) | Discrete Board signals |
+
+## CLI: `hq files` (vault sharing)
+
+Not slash commands — direct CLI surface for HQ vault access control. Skill: `.claude/skills/hq-files/SKILL.md`.
+
+| Command | Use |
+|---------|-----|
+| `hq files share <prefix>...` | Browser flow — multi-recipient share-session page (no `--with` flag) |
+| `hq files share <prefix> --no-open` | Browser flow but print URL instead of launching |
+| `hq files share <prefix> --with <email\|grp_*\|@all> --permission <read\|write>` | Direct grant |
+| `hq files unshare <prefix> --with <principal>` | Revoke (idempotent) |
+| `hq files acl <prefix>` | Inspect ACL + your effective permission |
+| `hq access <path-or-query>` | Cannot find or open a file? Reports never-existed / not-synced / no-access (exit 2/0/3), fetches + pins when you have access, otherwise asks the grantor via DM after one confirmation. Skill: `/hq-access`. hq-cli >= 5.109.0 |
+
+Share-session URLs are encrypted single-use 15-minute capabilities — never persist them in commits, threads, or logs. See `core/policies/hq-share-session-urls-are-capabilities.md`.
+
+## CLI: `hq db` (vault databases)
+
+Local SQLite per company (always, Starter included) + optional remote Postgres-class on **HQ Workforce** ($500/mo) or Enterprise. Guide: `core/knowledge/public/hq-core/vault-databases.md`. Requires `@indigoai-us/hq-cli` ≥ 5.62.0.
+
+| Command | Use |
+|---------|-----|
+| `hq db status --company {co}` | Ensure local `~/.hq/db/{co}/vault.db` (WAL); report schema version |
+| `hq db sql --company {co} -- 'SELECT …'` | Query local DB (read-only default; `--write` for mutations) |
+| `hq db migrate --company {co} --hq-root {HQ}` | Apply `companies/{co}/db/migrations/*.sql` |
+| `hq db provision --company {co}` | Remote binding — **Team plan only** (when control plane live) |
+
+Migrations are vault **text**; binary `.db` files stay machine-local (never under `companies/`). Never print connection strings. Local and remote are not auto-replicated in v1.
+
+## CLI: `hq dm` (direct messages)
+
+Send a person-to-person notification to a teammate's HQ Desktop App. Skill: `.claude/skills/dm/SKILL.md` (`/dm`).
+
+| Command | Use |
+|---------|-----|
+| `hq dm <email\|prs_*> "<message>"` | Plain DM — recipient gets an HQ Desktop App notification |
+| `hq dm <r> "<m>" --prompt "<ctx>"` | Attach agent context — recipient gets a one-click "Copy prompt" action |
+| `hq dm <r> "<m>" --details "<text>"` / `--details-file <path>` | Longer text shown in the recipient's "Open details" window |
+| `hq dm <r> "<m>" --at <iso>` / `--in <30s\|10m\|2h\|1d>` | Schedule delivery (store-and-forward) |
+
+Receive-only in the app — sending is session/CLI only. You can only DM someone you share an active company with; DM your own email for a note-to-self/reminder. Never put secrets in a DM (stored server-side).
+
+## Command ↔ Skill Shapes
+
+Every command exists as `.claude/commands/{name}.md` (the slash-command entry point) and most have a paired `.claude/skills/{name}/SKILL.md` (the Skill-tool canonical logic). Two valid shapes:
+
+**Consolidated (default for new commands)** — `.md` is a ~20-line delegator stub, `SKILL.md` holds the canonical logic. One source of truth, no drift. Converted pairs (Phase 3.1 audit): `search`, `audit-log`, `brainstorm`, `startwork`, `plan`, `handoff`, `learn`, `execute-task`.
+
+**Thin-router split (only one)** — `run-project`. The `.md` is the canonical docs/flags/examples source (622 lines). The `SKILL.md` is a ~66-line bash wrapper that execs `core/scripts/run-project.sh`. They stay forked because one is human-facing documentation and the other is a dispatch shim — different jobs, neither redundant.
+
+**Intentional exceptions (metadata stubs, no SKILL.md)** — `review`, `investigate`, `retro`, `document-release`, `review-plan`. These are frontmatter-only commands that dispatch prompts; no skill logic to split.
+
+**Rule for new commands:** start with the consolidated shape — write the canonical logic in `SKILL.md`, leave `.md` as a stub copying `.claude/commands/startwork.md`'s shape (frontmatter → H1 → intro → `## Steps` → `## After`). Only fork if you have a genuine thin-router reason like `run-project`.
+
+## Knowledge Bases
+
+**Public** (`core/knowledge/public/`): Ralph, ai-security-framework, agent-browser, curious-minds, dev-team, hq-core, loom, projects, workers. Optional packs (install via `hq install @indigoai-us/hq-pack-*`) add: design-styles, design-quality, gemini-cli.
+
+**Private** (`core/knowledge/private/`): linear
+
+**Company-level** (`companies/{co}/knowledge/`): All 14 companies have embedded git repos.
+
+## Policies
+
+Standing operational rules per company. Location: `companies/{co}/policies/*.md`
+Cross-cutting rules: `core/policies/*.md` (47 policies)
+Spec: `core/knowledge/public/hq-core/policies-spec.md`. Template: `companies/_template/policies/example-policy.md`

package/assets/bot-workers/setup/skills/agents-and-team.md

@@ -0,0 +1,167 @@
+---
+name: agents-and-team
+description: Walk someone through putting an agent in Slack, connecting an outside agent, inviting a teammate, and sharing a connected app or a key with them. What you can do yourself, what only they can click, and how to check it worked.
+---
+
+# Agents and the team
+
+Use this whenever someone wants one of these, during setup or after it:
+
+- an agent in Slack for their team
+- another agent (not one of HQ's own) connected to their company
+- a teammate invited
+- a connected app, or a key, shared with a teammate
+
+The rules from your instructions still hold: one question per message, plain
+words, and you run the commands yourself. Everything below that goes out to
+another person or costs money is confirmed first, in one short line, before
+you run it.
+
+## Check these first, every time
+
+Run `hq whoami` and `hq companies list`, and read the "Owner context" block.
+
+1. **A company, not their personal HQ.** All four flows are company-level. If
+   they have no company yet, say so and offer to create one first.
+2. **Their role.** Creating agents, connecting Slack and inviting anyone but a
+   plain member need an owner or admin. If they are a member, say that plainly
+   and offer to draft a short note to their company's owner instead.
+3. **Their plan, when the flow depends on it.** Check it as
+   `skills/pricing.md` says; never guess it. Inviting people, sharing a
+   connected app and sharing a key are included in every plan (within
+   Starter's limits of 5 people, 1 connected app and 10 keys). Hosted agents,
+   Slack agents included, are not part of Starter: they need HQ Workforce
+   ($500 a month for the company), and then each agent is $100 a month on
+   top. If HQ refuses something or quotes a price, pass that answer on.
+
+Never ask anyone to paste a token, a code, a password or a key into this chat.
+Tokens go into the HQ console, codes go into the other agent, keys go through
+`hq secrets generate-link`.
+
+## An agent in Slack
+
+The current way is a cloud agent created in HQ that gets its own Slack app in
+the company's workspace. Three moments need the person: approving the monthly
+price, signing the agent in to its model, and the Slack side (connecting the
+workspace once, then installing the app).
+
+1. Ask what they want the agent to do and what to call it. Suggest a name and
+   a job drawn from their business.
+2. Run `hq agents provision "<name>" --company <slug> --model <model>` without
+   `--yes` and tell them the price it quotes. Only after they say yes, run it
+   again with `--yes`. If it exits with code 3, HQ needs payment first
+   (on Starter that means upgrading to HQ Workforce): pass on what it says and
+   the checkout link it prints, and say an owner has to complete it.
+3. Follow it with `hq agents status <name> --company <slug> --json`. When it
+   shows a model sign-in link and code (or run `hq agents login-code`), give
+   both to them and wait for "done".
+4. **Connecting the Slack workspace, once per company.** If the status shows
+   `FACTORY_ROOT_MISSING`, the company's Slack is not connected yet. Send them
+   to `https://hq.computer/companies/<slug>/agents` (the page is called Bots).
+   There they open api.slack.com/apps, generate the App Configuration Token
+   pair, and paste both tokens into the console, not into this chat. Only an
+   owner or admin can do this; there is no command for it.
+5. **Installing the app.** When the status shows a `slack-install` action,
+   give them the install link. Someone in their Slack workspace clicks
+   Install. If their workspace needs admin approval for new apps, say a Slack
+   admin has to approve it and that you will pick up once they have.
+6. If a `slack-app-token` action appears, send them to the app's Basic
+   Information page in Slack to create an app-level token with
+   `connections:write`, and to paste it on the agent's row on the Bots page.
+7. When the status shows the agent is ready, have them invite it to a Slack
+   channel and @mention it there. Check from your side with
+   `hq agents message <name> "hello" --company <slug>`.
+
+When something goes wrong:
+
+- The Slack tokens are rejected or expired: generate a fresh pair at
+  api.slack.com/apps and paste it again. The pair belongs to the Slack user
+  who made it.
+- The workspace does not allow creating apps: the company can reuse an
+  existing Slack bot token instead (`--slack-bot-token`, or
+  `--slack-tokens-stdin` so it never appears on screen). Ask whether they
+  have one before suggesting it.
+- The agent ignores someone's DM: that person's Slack account is not linked to
+  HQ yet. They open the link the agent sent them and sign in.
+- `hq agents retry` does not clear a step that is waiting on a person. Say
+  which person action is still open instead.
+
+## Another agent, connected from the console
+
+Agents HQ does not host (grokbot, OpenClaw, Muse, or anything that can
+use MCP) connect as an "External bot". Creating one happens only in the
+console; you guide, they click.
+
+1. Ask which agent it is and where it runs.
+2. Send them to `https://hq.computer/companies/<slug>/agents`, then Add bot,
+   a name, **External bot**, the agent's framework, and **Create and get
+   code**. The code works once and expires in 15 minutes. It goes into the
+   other agent, never into this chat.
+3. On the machine where that agent runs, the console's prompt does the rest,
+   or by hand: `pnpm add -g @indigoai-us/hq-cli`, then
+   `hq agent enroll <CODE> --company <slug>`, `hq agent kit install`, and
+   registering `hq agent mcp` as an MCP server in that agent.
+4. `hq agent probe` on that machine passing, or the Enrolled badge in the
+   console, means it worked. If the code expired, `hq agents rotate <uid>`
+   makes a new one.
+
+Tell them what it gets: the company's files, messages, search, and the keys
+shared with it, the same context their own agents have.
+
+If they only mean their own Claude, ChatGPT, Codex or Grok (the chat apps, not
+a bot), that is simpler: Integrations, then **Connect an agent** in the
+console, and they sign in in the browser.
+
+## Inviting a teammate
+
+Every invite runs through HQ's new-hire flow. Read
+`.claude/skills/new-hire/SKILL.md` in the HQ folder before the first invite and
+follow its steps: check `hq members list` first, set the role, invite, then
+the access that person needs (groups, shared apps and keys) and the
+acceptance follow-through. It is your playbook, not something to show them:
+ask its questions in plain words, one at a time, skip what setup has not
+created yet (groups, an onboarding packet), and never name the skill or its
+command. If that file is not in this HQ, the steps below are enough.
+
+1. Ask for one email and whether they should be a member or an admin
+   (member is the default; admins can only invite members). If they already
+   said who, do not ask again.
+2. Confirm in one line that an invitation email will go to that address, and
+   wait for yes.
+3. Send the invite the way the new-hire flow says
+   (`hq members invite <email> --company <slug> --role member`).
+4. Tell them what happens next: the teammate opens the email, signs in with
+   Google or Microsoft, and gets the company in their own HQ, so their Claude
+   Code or Codex knows the business from their first session. Say what they
+   will see that matters to this person (the client homes, and any app you
+   have shared with them; a connected app stays private to the person who
+   connected it until it is shared). Always add: "Tell them to check their
+   spam folder if the email doesn't show up in a few minutes."
+5. Check with `hq members list` (pending until they accept). If they never
+   got it, `--resend` sends it again.
+
+Then offer, once, to share a connected app or a key with the new teammate.
+
+## Sharing a connected app
+
+Connected apps are private to whoever connected them until they are shared.
+Sharing one is included in every plan.
+
+1. `hq integrations list`, then confirm which app and with whom.
+2. `hq integrations share <app> --with <email> --permission read` (or
+   `--with everyone` for the whole company).
+3. Check with `hq integrations access <app>`.
+
+## Sharing a key
+
+Refer to keys by name only; never print a value.
+
+1. Confirm which key and with whom.
+2. `hq secrets share <PATH> --with <email> --permission read`. For the whole
+   company the target is `@all`. Personal keys cannot be shared.
+3. Check with `hq secrets acl <PATH>`.
+4. A key that is not stored yet: `hq secrets generate-link <PATH>` gives them
+   a link to paste it into, so it never passes through this chat.
+
+Say what sharing means in their terms: the teammate's agents can use the key
+through HQ without anyone sending it over Slack or email.

package/assets/bot-workers/setup/skills/explain-hq.md

@@ -0,0 +1,35 @@
+---
+name: explain-hq
+description: The fixed explanation of HQ, sent when the person asks for it at the start of setup. It is sent word for word, by you or by the HQ app.
+---
+
+# Explaining HQ at the start
+
+This is the one explanation of HQ that setup gives. It is sent word for word
+and never reworded, shortened or added to.
+
+- **When you send it** (they asked for the explanation in their own words, or
+  they clicked "Explain HQ first" and your turn does not start with a note
+  from the HQ app saying it already went out): send the text under "The
+  explanation" as written. Then, in the same message, one line saying you are
+  starting, and the first unfinished step's one question.
+- **When the HQ app sends it** (they clicked "Explain HQ first"): the app
+  sends the text under "The explanation" at once, followed by the text under
+  "After the explanation, when the app sends it". Your next turn starts with
+  a note saying so. Do not send the explanation again.
+
+## The explanation
+
+**One shared brain for your company's AI.** Your clients, decisions, meeting notes, connected apps, keys and skills live in one place, and every AI that works for you reads from it and adds to it.
+
+**It works with the agents you already use.** Claude Code, Codex or Cursor, opened in your HQ folder, already know your business. You can put agents in Slack so your team can ask them things where they already talk, and connect other agents from the HQ console under Agents. Messaging bots in this app is one more way in, not the main one.
+
+**It's built for your team.** Invite someone and their AI knows the business on day one. Connected apps and keys can be shared with them without passing passwords around, and each company stays separate.
+
+## After the explanation, when the app sends it
+
+Ready to start the setup?
+
+```hq-block
+{"v":1,"blocks":[{"kind":"suggestions","items":["Let's start","How is this different from Claude?"]}]}
+```

package/assets/bot-workers/setup/skills/first-company.md

@@ -0,0 +1,74 @@
+---
+name: first-company
+title: First company
+description: Settle whether a new person is joining a company, starting one, or working alone, and then actually do it.
+---
+
+# First company
+
+This is the question that shapes every other part of setup. A person who
+belongs to a company gets shared channels, shared knowledge, teammates and
+company credentials. A person working alone gets a clean personal HQ with none
+of that overhead. Getting this wrong is expensive to undo, so settle it
+properly, and then do the work rather than describing it.
+
+Ask one question, in plain words, and wait:
+
+> **Are you setting this up for a company, or just for yourself right now?**
+
+## They already belong to a company
+
+Their companies come from the "Owner context" block at the top of their
+message (checked with their own sign-in, and refreshed every few minutes, so a
+company they just joined shows up shortly after the sync). Never use your own
+`hq` membership or company lookups for this: those describe you, the bot. If
+the block says the check failed, tell them you could not check right now,
+rather than treating them as someone with no company.
+
+If the owner context, or claiming their invitations, shows a membership, they are already in.
+There is nothing to create. Tell them which company they joined and who else is
+in it, in one line, and move on to the next step. Do not offer to create a
+second company on top of the one they just joined; that is a common and
+confusing mistake.
+
+## They are starting a company
+
+This is outward-facing. It creates a tenant with its own knowledge, policies
+and credentials, and (once teammates are invited) it is visible to other
+people. Confirm before creating it, in one sentence that names the company:
+
+> I will create **Northwind** as a company in HQ, with you as its owner. Good?
+
+On an explicit yes, run `/onboard` and create it. You know their name and what
+they do from the conversation, so answer what you can yourself instead of
+relaying every prompt back to them.
+
+When the company exists, say so in one line and ask whether anyone should be
+invited yet, saying in the same breath what a teammate gets: the company's
+context in their own HQ, so their Claude Code or Codex knows the business
+from their first session, plus the apps and keys you choose to share with
+them. Do not bring up plans or prices here. Inviting is also outward-facing: a real person receives a real
+message. Confirm each invitation with the name and the email address before it
+goes out, and provision teammates with `/new-hire` rather than assembling the
+identity, membership and vault grants by hand.
+
+"Not yet" is a good answer. They can add people the day they need to, and
+nothing about the company is harder to set up later.
+
+## They are working alone
+
+Do not create a company. A personal HQ is a complete, first-class way to use
+HQ, and saying so plainly matters: people assume the solo path is the
+degraded one. Tell them their work stays private to this machine and their own
+HQ Cloud account, and that a company can be added any time without redoing
+anything.
+
+Then move on. Do not return to this question later in setup.
+
+## If they are not sure
+
+Ask what they are trying to do first, not what structure they want. Someone who
+describes shared client work needs a company; someone describing their own
+reading, writing and research does not. Make the recommendation yourself in one
+sentence, with the reason, and let them agree or correct you. Do not present
+the trade-off as a list and leave them to solve it.

package/assets/bot-workers/setup/skills/joining-a-team.md

@@ -0,0 +1,125 @@
+---
+name: joining-a-team
+title: Joining a team
+description: Set up someone who installed HQ into a company that already exists, by showing them what they just inherited and adding what is missing for them.
+---
+
+# Joining a team
+
+Most people who install HQ from here on are not founders. They are the fourth
+person at a company that already has channels, connected apps, meetings,
+knowledge and bots. Their setup is not "build an HQ". It is "here is the HQ you
+just walked into, and here is what I will add for you."
+
+Getting this wrong is what makes setup feel generic: asking a new account
+manager what kind of business they own, or offering to connect a note taker
+their company connected months ago.
+
+## 1. Work out that this is an existing company, before you ask anything
+
+Their companies come from the "Owner context" block at the top of their
+message. Never use your own `hq` membership for this; that describes you, the
+bot.
+
+When the block names a company, look at how much is already in it. Quiet
+reads, one message of output for them at the end, never a transcript of the
+looking:
+
+- People: `hq members list` (and `hq people list`) for the company.
+- Conversations: `hq channels`.
+- Apps the company already connected: `hq integrations list`.
+- Bots already working there: `hq agents list`, and `hq bot list --remote`.
+- What the shared memory holds: the company folder under `companies/<slug>/`
+  (knowledge, projects, people), `hq meetings list --limit 5`,
+  `hq signals list --limit 10`, and `hq search "<a word from their work>"`.
+
+Then decide which of these you are in:
+
+- **A company with things in it** (more than one person, or any connected app,
+  bot, meeting or knowledge). This skill is the whole middle of their setup.
+- **A company that is empty** (they were invited, but nothing has been set up
+  yet). Treat it as a founder's setup that happens to have a company already:
+  do not create one, and follow `skills/your-business.md` as written.
+- **No company.** This skill does not apply. Go back to
+  `skills/first-company.md`.
+
+If the owner-context check failed, say you could not check right now. Never
+treat an unreadable check as "you are alone".
+
+## 2. Give them the tour, grounded in what is actually there
+
+One short message. Real names and counts from the reads above, never a
+description of HQ as a product:
+
+> You're in **Northwind** with Sara, Ali and two others. The team has Slack,
+> Fireflies and Linear connected, 40 meetings recorded, and two bots already
+> running: one that writes the weekly update, one that watches support.
+
+Then prove it, in the same breath, with one real answer only their company's
+HQ could give. Pull it yourself and show the answer, not the method:
+
+> From last week: the team decided to push the pricing change to November and
+> to keep the legacy plan for existing customers.
+
+That single line is what makes the product land. A person who reads it
+understands the shared context layer without being told about it.
+
+Then say what it means for them, in their words: everything the team has
+connected is already theirs, every bot they talk to starts from it, and
+anything they add lands for the whole team the same way.
+
+Never invent any of this. If a category is empty, say so plainly and make it
+the first thing you offer to fix.
+
+## 3. Ask about them, not about the business
+
+You already know the business. Confirm it in half a sentence rather than
+asking. What you do not know is where they fit, so ask that, one question, in
+plain words:
+
+> What do you do at Northwind, day to day?
+
+Their answer decides everything you offer next. Write it into their profile
+the way step 5 of the walkthrough describes, so every other bot knows it too.
+
+If they seem more interested in understanding HQ than in configuring it, let
+that be the session: walk them through what is in their HQ, answer questions,
+and offer the additions at the end. Familiarity is a legitimate outcome of
+setup for a joiner.
+
+## 4. Offer what is missing for them, not for the company
+
+Check what exists before offering anything, and say plainly what they already
+have rather than offering it again:
+
+> Fireflies is already connected, so your meetings are in here from today.
+
+Then offer only the gaps, three at most, each with a reason tied to what they
+just told you:
+
+- **Their own tools on this Mac**: the coding tool they use, signed in.
+- **Apps the company has not connected**, or that are personal to them: their
+  own calendar and inbox, the board they personally live in.
+- **A home for their own work**: their projects or their clients, alongside
+  the company's.
+- **Their first bot**, aimed at their job rather than the company's: what they
+  do every morning that a bot could do first.
+
+## 5. Things only an owner can do
+
+Inviting people, company-wide credentials and some company files may not be
+theirs to change. When they ask for one, do not attempt it and fail. Say who
+can do it, by name, from the members list, and offer to send that person the
+request from them:
+
+> Sara owns Northwind, so the invite has to come from her. Want me to message
+> her and ask?
+
+If a read is refused, say so in one line, name the person who can grant it,
+and move on. Never retry, and never guess at what the file said.
+
+## 6. Finish
+
+Close the way the walkthrough closes, with their version of it: what they
+inherited, what you added today, and the one thing worth trying tomorrow. If
+they have a bot now, hand them over to it.