# 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, each project uses its own isolated workspace under `~/.launchchair/projects`.

## 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 or from an approved `launchchair login` browser flow.
- 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`:

```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/project-workspace.mjs" -o "$HOME/launchchair-agent/project-workspace.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
```

## CLI

The npm CLI is the recommended setup path for Codex Desktop and Claude Desktop. It can log in through LaunchChair, save the token locally, print paste-ready MCP config, write Claude Desktop config, and start the local bridge.

```bash
npm install -g @launchchair/agent
launchchair login
launchchair setup codex
launchchair setup claude
launchchair bind --project-id PROJECT_UUID --cwd /absolute/path/to/verified-clone
launchchair projects --query LeafLore
launchchair create --name SignalLift --one-liner "Distribution workspace for technical founders" --project-type b2b --idempotency-key signallift-v1
launchchair run-once
launchchair bridge
launchchair mcp-config codex --ui-fields
```

If Codex Desktop is being configured through the custom MCP form instead of `~/.codex/config.toml`, run:

```bash
launchchair setup codex --copy-config
```

## Environment Variables

```bash
LAUNCHCHAIR_BASE_URL="https://www.launchchair.io"
LAUNCHCHAIR_PROJECT_ID="optional project UUID; omit or leave blank if creating or discovering a project"
```

`launchchair login` is the recommended token path. It saves the token to `~/.launchchair/config.json`, and `launchchair mcp-server` reads that saved token. Use `LAUNCHCHAIR_AGENT_TOKEN` only as a manual fallback when browser login is skipped or a per-client token override is needed.
The packaged MCP and local bridges also read the same saved CLI config as a fallback, so a desktop MCP launch should not require pasting a token into Codex or Claude config after browser login. Guided setup verifies standards-compliant MCP initialize and tool discovery before it reports success.

For Codex Desktop local runs, choose the runner globally and bind each project clone independently:

```bash
LC_AGENT_ROUTER_GPT_TARGET="codex"
LC_AGENT_ROUTER_CODEX_TARGET="codex"
launchchair bind --project-id PROJECT_UUID --cwd /absolute/path/to/verified-clone
```

For Claude Desktop plus Claude Code local runs:

```bash
LC_AGENT_ROUTER_GPT_TARGET="claude_code"
LC_AGENT_ROUTER_CODEX_TARGET="claude_code"
launchchair bind --project-id PROJECT_UUID --cwd /absolute/path/to/verified-clone
```

Pre-code work uses an isolated per-project scratch folder. After Stack Setup records the GitHub repository, the bridge auto-detects matching clones in standard repo folders and verifies the Git `origin`. If needed, clone the repo and run `launchchair bind`; code-changing runs fail closed until that verification succeeds.

## MCP Server Config Example

```toml
[mcp_servers.launchchair]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/launchchair-cli.mjs", "mcp-server"]
required = false
startup_timeout_sec = 45
tool_timeout_sec = 3600
default_tools_approval_mode = "approve"

[mcp_servers.launchchair.env]
LAUNCHCHAIR_BASE_URL = "https://www.launchchair.io"
LAUNCHCHAIR_CONFIG_DIR = "/absolute/path/to/.launchchair"
LAUNCHCHAIR_PROJECT_ID = ""
LC_AGENT_ROUTER_GPT_TARGET = "codex"
LC_AGENT_ROUTER_CODEX_TARGET = "codex"

# Optional fallback if launchchair login was skipped:
# LAUNCHCHAIR_AGENT_TOKEN = "<full lc_at token from Settings API Access>"
```

Prefer `launchchair setup codex` so the CLI writes native config and verifies MCP tool discovery. Use `launchchair bind --project-id PROJECT_UUID --cwd /absolute/path/to/verified-clone` after cloning when automatic discovery cannot locate the repo. Use `launchchair mcp-config codex --ui-fields` only for manual custom-form setup.

## 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.
8. When the user asks for validation scores or wants to compare ideas, call `launchchair_get_scorecards`. Report validation scorecards separately from generated direction-option scores.

## 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
- running/rerunning Feature Definition and User & Feature Validation for score-based feature comparison
- reading Product or Feature validation scorecards with `launchchair_get_scorecards`
- 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
- Product-track manual QA requires a human when LaunchChair explicitly returns that checkpoint; Feature-track QA should be executed by the agent with matching evidence whenever the local runtime is available
- 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
- Feature score-based validation using Feature Pain Score, Pattern Saturation Score, and Feature Opportunity Score

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

For Feature projects, the three Feature validation scorecards evaluate the idea. The two generated wedge-direction scores rank the narrow opportunities inside that idea; they are not the Feature validation scores. User & Feature Validation selects the wedge first, then Feature Blueprint generates and selects exactly two concrete feature directions. Every wedge and Feature direction must be grounded in four evidence pillars: ICP complaint themes, delight themes, substitute behaviors, and competitor gaps. Never collapse those decisions or answer a request for Feature validation scores with direction-option scores alone. When comparing multiple Feature ideas, run each through User & Feature Validation, call `launchchair_get_scorecards` for each project, maximize Feature Pain and Feature Opportunity, minimize Pattern Saturation, and prefer ideas that pass every returned recommended threshold.

## 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
- Product-track manual QA, or Feature QA that is genuinely blocked by unavailable credentials, external authorization, or an inaccessible runtime
- a human product choice that the token cannot save

Do not claim that SQL migrations, production deploys, billing setup, or QA are complete unless you have verified evidence. For Feature projects, run the available QA yourself and return matching `executionEvidence.agentQaChecks` instead of handing runnable checks back to the user.

## 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
launchchair 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 QA complete without matching evidence. For Feature projects, produce that evidence by running the repository-native or browser checks whenever possible.
- Do not search the whole filesystem for LaunchChair source when the public docs and MCP tools are available.