# LaunchChair Agent Bootstrap

This file is for fresh agent chats that need to use the LaunchChair Agent API or MCP bridge without wasting time searching an empty repo.

## Core Rule

Use LaunchChair first for product, research, validation, positioning, pricing, MVP blueprint, and phase-loop work. Do not inspect the local repo first unless the user is in Stack Setup, Build MVP, Design and Landing Page implementation, or another code-changing phase.

Fresh LaunchChair projects often do not have a local repo yet. Before Stack Setup, the configured runner folder may be empty on purpose.

## Public Docs To Read

- Agent API docs: https://www.launchchair.io/docs/agent-api
- MCP setup docs: https://www.launchchair.io/docs/mcp
- Optional CLI docs: https://www.launchchair.io/docs/cli
- Public machine-readable catalog: https://www.launchchair.io/api/agent/v1/docs
- Bridge file catalog: https://www.launchchair.io/api/agent/v1/bridge

## Security Rules

- Never print a LaunchChair token.
- Never paste a LaunchChair token into public docs, issue comments, screenshots, or chat summaries.
- Real tokens come from LaunchChair Settings -> API Access.
- Public docs and artifacts contain placeholders only.
- If you inspect env files, confirm whether token variables exist without showing their values.
- If the user asks you to create or continue a LaunchChair project and the configured token permits it, do not ask for extra confirmation before using LaunchChair MCP/API tools. The token scope is the authorization boundary.
- Ask for confirmation only for external account authorization, production SQL execution, destructive local file actions, or shell commands that the client sandbox requires the user to approve.

## Bridge And Runner Files

Download these into a stable local folder such as `~/launchchair-agent` or `~/.hermes/launchchair-mcp`:

```bash
mkdir -p "$HOME/launchchair-agent"
curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/local-bridge.mjs" -o "$HOME/launchchair-agent/local-bridge.mjs"
curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/launchchair-cli.mjs" -o "$HOME/launchchair-agent/launchchair-cli.mjs"
curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/mcp-bridge-server.mjs" -o "$HOME/launchchair-agent/mcp-bridge-server.mjs"
curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/runner-command.mjs" -o "$HOME/launchchair-agent/runner-command.mjs"
curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/codex-runner.mjs" -o "$HOME/launchchair-agent/codex-runner.mjs"
curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/claude-code-runner.mjs" -o "$HOME/launchchair-agent/claude-code-runner.mjs"
curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/chatgpt-runner.mjs" -o "$HOME/launchchair-agent/chatgpt-runner.mjs"
curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/claude-runner.mjs" -o "$HOME/launchchair-agent/claude-runner.mjs"
curl -fsSL "https://www.launchchair.io/agent-artifacts/AGENTS.md" -o "$HOME/launchchair-agent/AGENTS.md"
chmod +x "$HOME/launchchair-agent"/*.mjs
LAUNCHCHAIR_AGENT_WORKDIR="${LC_AGENT_CODEX_CWD:-${LC_AGENT_CLAUDE_CODE_CWD:-$PWD}}"
if [ -d "$LAUNCHCHAIR_AGENT_WORKDIR" ] && [ ! -f "$LAUNCHCHAIR_AGENT_WORKDIR/AGENTS.md" ]; then
  printf '%s\n' \
    '# LaunchChair Agent Bootstrap Pointer' \
    '' \
    'Before searching this repo, read ~/launchchair-agent/AGENTS.md.' \
    'Use LaunchChair MCP/API first for product phases, project discovery, project creation, and phase loops.' \
    'Do not ask for extra confirmation before using LaunchChair MCP/API when the user already requested the action and the token permits it.' \
    'Only inspect this repo for Stack Setup, Build MVP, Design/Landing Page, SEO implementation, smoke testing, security review, or code remediation.' \
    > "$LAUNCHCHAIR_AGENT_WORKDIR/AGENTS.md"
fi
```

The final block creates a tiny project-local `AGENTS.md` pointer only when the target folder does not already have one. It helps fresh Codex chats auto-load the LaunchChair instructions without overwriting a real project instruction file.

## Optional CLI

MCP-only setup is still supported. Use `mcp-bridge-server.mjs` when the desktop agent exposes LaunchChair MCP tools. Use `launchchair-cli.mjs` when you need quick diagnostics, project discovery, retry-safe project creation, MCP config output, or a simple way to start the local bridge.

```bash
node "$HOME/launchchair-agent/launchchair-cli.mjs" doctor
node "$HOME/launchchair-agent/launchchair-cli.mjs" projects --query LeafLore
node "$HOME/launchchair-agent/launchchair-cli.mjs" create --name SignalLift --one-liner "Distribution workspace for technical founders" --project-type b2b --idempotency-key signallift-v1
node "$HOME/launchchair-agent/launchchair-cli.mjs" run-once
node "$HOME/launchchair-agent/launchchair-cli.mjs" bridge
node "$HOME/launchchair-agent/launchchair-cli.mjs" mcp-config codex
```

## Required Environment Variables

```bash
LAUNCHCHAIR_BASE_URL="https://www.launchchair.io"
LAUNCHCHAIR_AGENT_TOKEN="<full lc_at token from LaunchChair Settings API Access>"
LAUNCHCHAIR_PROJECT_ID="optional project UUID; omit or leave blank if creating or discovering a project"
```

For Codex Desktop local runs:

```bash
LC_AGENT_ROUTER_GPT_TARGET="codex"
LC_AGENT_ROUTER_CODEX_TARGET="codex"
LC_AGENT_CODEX_CWD="/absolute/path/to/the-folder-codex-should-build-into"
```

For Claude Desktop plus Claude Code local runs:

```bash
LC_AGENT_ROUTER_GPT_TARGET="claude_code"
LC_AGENT_ROUTER_CODEX_TARGET="claude_code"
LC_AGENT_CLAUDE_CODE_CWD="/absolute/path/to/the-folder-claude-code-should-build-into"
```

The build folder can be an empty scratch folder until Stack Setup creates or records the GitHub repository. After Stack Setup, the user should clone the generated repo locally or update the runner CWD to the cloned repo path.

## MCP Server Config Example

```toml
[mcp_servers.launchchair]
command = "node"
args = ["/Users/you/launchchair-agent/mcp-bridge-server.mjs"]

[mcp_servers.launchchair.env]
LAUNCHCHAIR_BASE_URL = "https://www.launchchair.io"
LAUNCHCHAIR_AGENT_TOKEN = "<full lc_at token from Settings API Access>"
LAUNCHCHAIR_PROJECT_ID = ""
LC_AGENT_ROUTER_GPT_TARGET = "codex"
LC_AGENT_ROUTER_CODEX_TARGET = "codex"
LC_AGENT_CODEX_CWD = "/absolute/path/to/the-folder-codex-should-build-into"
```

## What To Do First In A Fresh Chat

1. If LaunchChair MCP tools are available, call `launchchair_heartbeat`.
2. Call `launchchair_status` to confirm token, bridge, runner, and project context.
3. If `LAUNCHCHAIR_PROJECT_ID` is blank and the user named a project, call `launchchair_list_projects` and select the matching project.
4. If the user asks to create a new LaunchChair project, call `launchchair_create_project`.
5. If the user clicked Run with agent in LaunchChair, call `launchchair_run_once`.
6. If the user asks to advance the product workflow, call `launchchair_continue_project`.
7. If LaunchChair asks for a user-choice bucket such as wedge, pricing, or feature direction, call `launchchair_select_choice`. Do not use generic SPEC_UPDATE apply for user-choice buckets.

## Consent Behavior

Do not ask the user for repeated permission to perform normal LaunchChair project-loop work when the user already requested it and the token allows it.

Safe LaunchChair MCP/API actions that should not need another user confirmation:

- creating a LaunchChair project with `launchchair_create_project`
- listing accessible LaunchChair projects with `launchchair_list_projects`
- continuing a project loop with `launchchair_continue_project`
- selecting a generated wedge, pricing, or feature direction with `launchchair_select_choice`
- running/rerunning Product Ideation, Market Validation, Positioning, Pricing, and MVP Blueprint buckets
- returning phase synthesis links and selected choices

Stop and ask only when:

- the local client sandbox asks the user to approve a shell command
- the user must authorize GitHub, Vercel, Supabase, Stripe, or another external account
- production SQL must be executed
- manual QA testing notes must be completed by a human
- a destructive local filesystem action is required
- the token is missing a required scope

If Codex asks for permission to run the local bridge fallback command, tell the user they can choose "Yes, and don't ask again for commands that start with ..." for the LaunchChair bridge command prefix. Prefer exposed MCP tools when available because MCP tool calls avoid shell-command permission prompts.

## When To Avoid Repo Inspection

Do not start with `ls`, `rg`, dependency inspection, or nearby repo searches when the user asks for:

- product ideation
- market validation
- ICP research
- wedge selection
- positioning and pricing
- MVP blueprint
- LaunchChair project creation
- LaunchChair phase loops
- score-based reruns such as ICP Pain Score, Market Saturation Score, or Wedge Opportunity Score

Those are LaunchChair project-state tasks, not local repo tasks.

## When Repo Inspection Is Correct

Inspect the repo when the current LaunchChair work is:

- Stack Setup local readiness
- Build MVP cards
- Design and Landing Page implementation
- SEO, GEO, AEO implementation against an existing app
- smoke testing, security review, or code remediation

For Build MVP work, read the repo `AGENTS.md` first if it exists, then inspect the files named in the LaunchChair build prompt.

## Human Checkpoints

Stop and give the user a direct LaunchChair link when LaunchChair needs:

- GitHub authorization or repo selection
- Vercel account, team, project, or domain selection
- Supabase project selection or SQL execution
- Stripe account authorization
- manual QA testing notes
- a human product choice that the token cannot save

Do not claim that SQL migrations, production deploys, billing setup, or manual QA are complete unless you have verified evidence.

## Progress Reporting

Keep chat updates short. Report:

- the LaunchChair project name and phase
- the bucket or card being worked
- choices selected, especially wedge, pricing, and feature direction
- phase synthesis links returned by LaunchChair
- exact user checkpoints with links to the relevant LaunchChair page or build-card tab

Avoid long explanations of local file searching when LaunchChair MCP tools are available.

## Common Commands

Run a full project loop:

```text
Call launchchair_continue_project with projectId, maxSteps, and optional stopPhaseKey.
```

Create a project from a new idea:

```text
Call launchchair_create_project with projectName, oneLiner, projectType, and ideaSnapshot.
```

Find a project by name:

```text
Call launchchair_list_projects with query set to the user-provided project name.
```

Run one queued UI job:

```text
Call launchchair_run_once.
```

Run one queued UI job from CLI:

```bash
node "$HOME/launchchair-agent/launchchair-cli.mjs" run-once
```

Select a generated wedge:

```text
Call launchchair_select_choice with domain="wedge" and optionTitle or optionId.
```

## Do Not Do This

- Do not brute-force project state by writing arbitrary JSON Patch to `projects.spec_json`.
- Do not use generic SPEC_UPDATE for user-choice buckets.
- Do not invent missing Supabase, Vercel, GitHub, or Stripe access.
- Do not run production SQL without explicit user authorization and a known project ref.
- Do not mark manual QA complete unless LaunchChair or the user provides matching evidence.
- Do not search the whole filesystem for LaunchChair source when the public docs and MCP tools are available.