Read one context. Stay in scope. Return receipts.

Launchfiles Agent Quickstart

External agents should use public discovery for boundaries, then use the authenticated challenge manifest as the only callable production challenge contract. Do not inspect local repos, tests, shell scripts, Vercel logs, or databases. Do not use public OpenAPI as execution authority.

1. 1

   Get a scoped challenge token from the founder.

2. 2

   Call GET /api/health.

3. 3

   Call GET /api/founder/prod-challenge-manifest with Authorization: Bearer <SCOPED_CHALLENGE_TOKEN>.

4. 4

   Create a temporary challenge product with a prod_program_suite_* slug.

5. 5

   Run a mission with POST /api/founder/run-mission.

6. 6

   Poll the returned poll_url first, or call GET /api/founder/mission-session/status?productSlug={product_slug}.

7. 7

   Inspect status, current_stage, progressTimeline, workOrders, DecisionTarget, artifacts, receipts, and handoff.

8. 8

   Cleanup the temporary challenge product with DELETE /api/founder/product.

9. 9

   Report receipt truth without claiming publish, deploy, send, spend, billing, or real-product mutation.

Forbidden in challenge mode: publish, deploy, outbound send, spend, billing mutation, real-product access, worker-secret access, and atomic tool access.

submission_receipt

request accepted only

handoff_receipt

handoff created only

artifact_verification_receipt

artifact verified only

lifecycle_execution_receipt

bounded work executed and verified

side_effect_receipt

approved side effect executed

Authenticated MCP setup (hosted + local stdio)

Launchfiles exposes a hosted authenticated MCP endpoint at /api/mcp for product resources and bounded agent tools, and keeps its local stdio servers for IDE agents. Access is authenticated only; endpoint metadata is public, but there is no anonymous or free MCP resource access.

1. 1

   Get a scoped challenge token from the founder. Founders with an active session can issue one via POST /api/founder/prod-challenge-token.

2. 2

   For hosted resources and bounded tools, connect to https://launchfiles.app/api/mcp with Authorization: Bearer <SCOPED_CHALLENGE_TOKEN>.

3. 3

   Set LAUNCHFILE_MCP_AUTH_TOKEN (or SCOPED_CHALLENGE_TOKEN) in apps/web/.env.local or in your IDE MCP server env block. Never commit tokens.

4. 4

   For orchestrator tools (launchfiles-agent), also set LAUNCHFILE_AGENT_MODE=1 and DATABASE_URL in apps/web/.env.local.

5. 5

   Configure Cursor MCP from the repo root using scripts/mcp/run_readonly_mcp.sh (resources) and scripts/mcp/run_agent_mcp.sh (tools). See .cursor/mcp.json.

6. 6

   Hosted MCP metadata is public, but resources remain authenticated. Local stdio startup is also blocked without authentication.

See /.well-known/launchfiles.json mcpIntegration and mcpQuickstart for machine-readable setup. Hosted MCP is bearer-authenticated. Challenge tokens remain workspace-, product-, and scope-bound; no approval or production side-effect tools are exposed.

Access boundaries

Public discovery surfaces describe what Launchfiles is — they do not grant execution authority, workspace access, or mutation rights. Read-only resource access is not execution. Proposal access is not approval. Route visibility is not route execution.

• public_discovery — /llms.txt, /agents, /openapi.json, /.well-known/launchfiles.json, /.well-known/launchfiles-agent.json
• authenticated_challenge_manifest — /api/founder/prod-challenge-manifest with founder session or scoped challenge token
• authenticated_local_mcp_stdio — repo-local MCP; scoped challenge token or founder internal admin required (not a public remote server)
• external_agent_readonly — sanitized context, schemas, route summaries (no internal scoring)
• customer_workspace_readonly — future workspace-scoped reads; requires auth (not live)
• customer_workspace_proposed — future proposal flows; not approval (not live)
• blocked — execute, publish, payment, and unrestricted agent execution

See /.well-known/launchfiles.json for the discovery manifest accessBoundaries section and /openapi.json for planned route boundary annotations. Authenticated challenge agents should get exact callable endpoints from /api/founder/prod-challenge-manifest, not from public OpenAPI.

Core command test

Before editing any product surface, read the current operating file and pass this check.

An agent passes only when it can identify:

• Current approved decision
• Exact work order
• Allowed scope
• Forbidden actions
• Approval boundary
• Required proof
• Latest receipt or explicit not_run
• Unresolved gates
• Launchfiles vs Launchfiles Content boundary

Scope model

Three scopes govern every agent interaction. Proposals and plans never cross into execution without a separate approval and receipt.

Object rendering law

Every launchfile object must expose exact state in the interface. Missing proof stays missing; proposals are not approvals.

Receipt requirement

No agent execution is complete without a durable receipt adjacent to the claim it supports.

run_id

Durable workflow or agent run identifier.

actor

Human, agent, or workflow actor that initiated the run.

scope

Exact approved product, paths, and systems.

inputs

Commands, artifacts, and hashes consumed.

outputs

Artifacts written and verification results.

gate_results

Deterministic or judgment gates that permitted or blocked progression.

artifact_links

Paths or URLs to durable proof objects.

side_effect_status

Whether publish, queue, schedule, or public mutation occurred.

terminal_state

completed, blocked, failed, or not_run — never inferred.

Deterministic agent context example

Fixture export only — secret-free, scoped, no mutable runtime state, no unrestricted execution language. Product-repo agents consume approved exports; they do not browse private orchestration source.

{
  "schemaVersion": "launchfile_agent_export_v0",
  "generatedAt": "2026-06-19T19:15:00+07:00",
  "sourceMode": "fixture",
  "scope": {
    "workspaceId": "workspace_launchfile_fixture",
    "productId": "product_launchfile_fixture"
  },
  "currentApprovedDecision": {
    "id": "decision_visual_direction_v2",
    "title": "Use the Verified Operating File visual direction",
    "decision": "Adopt the supplied Launchfile brand board as the V0 visual source for page and component protocol work.",
    "rationale": [
      "The file-first mark and restrained palette express operating-file, verified, controlled, and forward principles.",
      "The selected direction removes the previous visual-source blocker without authorizing production behavior."
    ],
    "authority": "fixture_founder"
  },
  "workOrder": {
    "id": "work_order_frontend_protocol_v2",
    "objective": "Make future Launchfile pages contract-led, visually coherent, proof-oriented, responsive, and agent-readable.",
    "owner": "fixture_codex",
    "allowedPaths": [
      "docs/LAUNCHFILE_*.md",
      "docs/page-contracts/**",
      "apps/launchfile-web/**",
      "__tests__/launchfile/**"
    ],
    "allowedSystems": [
      "local filesystem",
      "local app",
      "local browser",
      "local tests"
    ],
    "acceptanceCriteria": [
      "No route exists without a Page Contract.",
      "The Today route exposes fixture mode, blockers, proof, and not_run truth.",
      "The component demo shows all ten approved primitives.",
      "Typecheck, focused tests, build, and visual QA pass."
    ],
    "forbiddenActions": [
      "Deploy or provision infrastructure.",
      "Mutate a database or production system.",
      "Wire approval, execution, publishing, or legacy Content OS runtime behavior.",
      "Rename legacy Content OS runtime identifiers."
    ],
    "requiredProof": [
      "Launchfile app typecheck passes.",
      "Focused Launchfile tests pass.",
      "Launchfile production build passes.",
      "Desktop and mobile screenshots pass visual QA."
    ]
  },
  "doctrineRefs": [
    "AGENTS.md",
    "docs/LAUNCHFILE_PAGE_CREATION_PROTOCOL_V0.md",
    "docs/LAUNCHFILE_UI_COMPONENT_SPEC_V0.md",
    "docs/LAUNCHFILE_VISUAL_QA_SCORECARD_V0.md"
  ],
  "executionAuthority": {
    "mode": "execute_with_approval",
    "approvalId": "approval_visual_direction_v2",
    "allowedActions": [
      "Edit approved local docs and fixture UI files",
      "Run local verification and visual QA"
    ]
  },
  "executionTruth": {
    "state": "not_run",
    "reason": "This fixture contains no workflow run ledger; local UI work is not runtime execution proof.",
    "latestReceipt": null
  },
  "unresolvedGates": [
    {
      "id": "gate_behavior_wiring_v2",
      "gateId": "BLOCK_BEHAVIOR_WIRING",
      "outcome": "fail",
      "severity": "blocking",
      "reason": "No separate product approval, authorization model, idempotency contract, or receipt-producing mutation path exists."
    }
  ]
}

Discovery surfaces

Public agent-readable contracts and manifests. V0 — no live remote MCP server or production API mutation on these surfaces. Local stdio MCP requires authentication (see MCP setup).

• /llms.txt — agent-readable product map and boundaries
• /openapi.json — OpenAPI 3.1 draft (most routes planned)
• /.well-known/launchfiles.json — discovery manifest
• /.well-known/launchfiles-agent.json — compatible agent discovery manifest

Product modules

Launchfiles is the operating file for AI-native startups. Website Missions and Launchfiles Content are modules inside the wider product — not the master category.

Integration path

Progressive maturity from read-only context to scoped execution tools.

1. V0

   Read approved context

   Agents consume the operating file, doctrine refs, and deterministic exports like the example below.

2. Next

   Propose signals, decisions, and work orders

   Draft bounded objects for founder review without treating proposals as approved truth.

3. Later

   Execute-with-approval tools

   Run only the exact approved action with idempotency keys, expected side effects, and rollback rules.

4. Now

   Authenticated MCP (hosted + local stdio)

   Hosted product resources and bounded agent tools plus repo-local MCP for IDE agents. Hosted access requires a bearer token; no anonymous access.

5. Future expansion

   OAuth/RAR hosted access

   Replace shared or challenge bearer credentials with OAuth/RAR-bound remote access before exposing workspace data or tools.

Launchfiles / Launchfiles Content boundary