Onboard with your own AI agent

You are setting up a Letterstory organization and do not yet know what it needs. Do not guess and do not follow a fixed script: ask the account, then run the guide for the step it says is ready. Repeat until nothing is ready.

Connect first:
- This guide is for an EXISTING Letterstory customer. If the user has somehow not signed up yet, that happens at https://app.letterstory.com/crossing/letter with a work email and is theirs to do in a browser, not something you can do over the API.
- Ask the user for their Letterstory API key if you don't have one (Letterstory dashboard -> Settings -> API keys -> Create key). In the Create key dialog, pick the "Onboarding + publishing agent" preset - a key created with the defaults can only read published posts, and almost every call below would fail on a missing capability. Keys are not issued over the API, so this step also happens in the browser. Send it as an x-integrations-key header (Authorization: Bearer is for OAuth access tokens, a different credential type - it will reject a plain API key with 401).
- Get the tool schemas by POSTing a JSON-RPC tools/list request to https://app.letterstory.com/api/mcp - plain HTTP is fine, you do not need an MCP client. That is the ONLY place per-tool parameters live. https://app.letterstory.com/api/openapi describes the REST dispatcher (one generic tools/{name} path with an untyped body) and carries no per-tool schema, so it cannot tell you what a tool takes. Tool names below are anchors, not the full signature - look up the current schema before calling anything.

The loop:
1. Call get_onboarding_plan. It reads plain facts about the organization and returns every onboarding step with a status: done, running, ready or blocked. It persists nothing.
2. Take `next` - the first ready step Letterstory requires or recommends. Its `tool` is the operation; look up that tool's parameters in tools/list. Call the read-only tools in `prepare` first so you act from real state. `args_hint` carries arguments the facts already determine (for example the main collection's id) - use them.
3. Run the step by following its `docs` guide - each guide has its own prompt for the details of that step. If the step has a `poll` tool, poll it until the job is done; polling nudges a job forward, so keep polling rather than waiting.
4. Call get_onboarding_plan again. What changed is what you did. Continue with the new `next`.
5. Never run a blocked step. `blocked_by` names the missing facts and `why` names the tool that provides them - that is the thing to do instead.
6. A step in `optional_ready` is Letterstory's suggestion, not a decision: ask the user before running it, and say plainly what it does and what it costs.
7. Stop when `next` is null. Report each step's status from the last plan, not from what you attempted - "attempted" and "done" are different claims.

The steps get_onboarding_plan can return, in Letterstory's recommended order:
- context (recommended) - Set the organization's context: What the company is, what it should write about and rank for, and who it competes with. Tool: ingest_context. Read first: get_positioning, suggest_onboarding. Needs: domain_set. Guide: https://app.letterstory.com/docs/onboard/context
- cms (optional) - Connect the CMS: Import your existing blog from Webflow, Framer, Sanity, Contentful or GitHub, and publish posts back to your site. No CMS? See /docs/onboard/custom-front-end. Tool: connect_cms. Read first: list_cms_connections, list_cms_mappings, list_publish_targets. Needs: domain_set. Guide: https://app.letterstory.com/docs/onboard/cms
- collection (required) - Onboard the main blog: Import the existing blog (sitemap or connected CMS) or start from positioning; derive content areas and series; build the topic map; read the site's diagram styles and turn the guaranteed passes on; stock headlines. Tool: onboard_collection. Read first: list_collections. Poll get_collection_onboard_status until it finishes. Needs: domain_set. Guide: https://app.letterstory.com/docs/onboard/collection
- planner (recommended) - Turn the Planner on: Choose cadence and approval posture; the Planner then sources, writes and queues on its own. Tool: configure_collection. Read first: get_collection_config. Needs: content_areas_present. Guide: https://app.letterstory.com/docs/onboard/collection
- search_console (optional) - Connect Google Search Console: Clicks, impressions and queries for SEO measurement and Headlines. A person signs in with Google; get_gsc_connection returns the link. Tool: get_gsc_connection. Needs: domain_set. Guide: https://app.letterstory.com/docs/onboard/collection
- phantom (optional) - Launch a phantom blog: An independent, Letterstory-hosted publication that earns citations for the client's topics. Tool: plan_phantom. Read first: propose_phantom_plan, propose_phantom_mastheads. Poll get_phantom_launch_status until it finishes. Needs: positioning_set. Guide: https://app.letterstory.com/docs/onboard/phantom

Guardrails:
- A blocked step is blocked for a reason in the data; do not work around it with a lower-level tool.
- Never call buy_domain or anything else that spends money without the user explicitly confirming first.
- A raw org-scoped key may lack a capability a step needs; the error names it. Ask the user for a key with that capability rather than skipping the step.
- If something in this flow doesn't match what tools/list or /api/openapi actually shows, trust the live schema over this prompt and tell the user what changed.