> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openscaffold.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard with your agent

> Hand this page to Claude Code and it sets up OpenScaffold and your first deployment.

You do the three things your agent can't: click **Approve**, restart Claude Code once, and tell it which customer. It does the rest.

## Copy this into Claude Code

```text Prompt theme={null}
Onboard me to OpenScaffold. Read the agent playbook at
https://docs.openscaffold.ai/agent-onboarding and follow it exactly.

Run the machine steps yourself. When a step needs my browser or a restart,
stop, print exactly what I need to do, and wait for me to confirm.
Do not guess the customer's name or which files to use: ask me.

Finish by showing me the briefing for my first deployment.
```

Run it from any folder. Your agent handles setup, sign-in, the first deployment and its plan. Using Cursor or Codex? Connect it with [one link or command](https://docs.openscaffold.ai/coding-agents.md) first.

## Or onboard yourself

```bash theme={null}
npx @openscaffold/cli login
```

Approve in the browser, restart Claude Code, then tell it in plain words: *"Set up a deployment for \<customer> from these files: …"* Or create the deployment at [app.openscaffold.ai](https://app.openscaffold.ai) and press **Start Claude Code**.

## Agent playbook

This section is the contract a coding agent follows. People can skip to [Troubleshooting](#troubleshooting).

Two steps need the person: approving the browser sign-in, and restarting Claude Code so the tools load. Don't try to work around either. Do everything else yourself.

**1. Preflight**

```bash theme={null}
node --version
```

Require Node 22 or newer. If it's older, tell the user and stop.

**2. Check the setup**

```bash theme={null}
npx -y @openscaffold/cli status --json
```

Read-only and safe to repeat.

* `ready: true` means signed in with Claude Code connected: go to step 5.
* `workspace: null`, `server: "revoked"` or anything missing: go to step 3.
* `server: "down"`: tell the user their server isn't answering, show them the report's `next` advice, and stop.

**3. Sign in**

```bash theme={null}
npx -y @openscaffold/cli login
```

It opens the browser and prints a URL and a code. Show both to the user and ask them to click **Approve**; the command finishes on its own once they do (the link expires after 10 minutes). Never approve on their behalf.

Login connects Claude Code: the MCP server, a session hook and the `/os-*` commands. Nothing is written into any repo. Login ends by printing the same report as step 2, so you don't need to run status again.

**4. Restart Claude Code**

Claude Code loads OpenScaffold's tools when a session starts. Tell the user, verbatim: *"Restart Claude Code (exit, then run `claude` again) and say 'continue onboarding'."* Then stop.

**5. Confirm the tools**

Call the `list_deployments` tool. If it isn't available, the session wasn't restarted: repeat step 4.

If the customer already has a deployment, call `use_deployment` and don't create another. If its `harness_version` is set, it already has a plan: call `get_briefing`, show it, and you're done. If it's null, go to step 6 but skip `create_deployment`: just add the customer's material.

**6. Create the first deployment**

Ask the user for the customer's name, and which files or folder hold their material: call transcripts, ticket exports, email threads, docs.

Call `create_deployment` with the name (unless step 5 found one), then `add_document` once per file, with its type, title and text. Only add files the user named. If their team has connected Gmail, Slack or other tools, tell them they can feed this deployment from Sources at app.openscaffold.ai instead.

**7. Build the plan and show the briefing**

Call `generate_harness`. If it says documents are still being read, wait a minute and call it again. It runs for a minute or two. Call `get_briefing` once a minute, at most five times, until it shows a plan.

If it still says "No plan yet", generation stopped: call `generate_harness` once more and wait the same way. If that fails too, tell the user it didn't finish and to check the deployment's Activity at app.openscaffold.ai; don't keep retrying.

Once the plan exists, show the user the briefing: the goal, the must-haves, the rules and the open questions, each with where it came from.

### Rules

* Never invent the customer's name, requirements or files. Ask.
* One deployment per customer engagement. If it already exists, use it; don't create a second.
* Only add files the user named. Never upload anything else from their machine.
* Every command here is safe to re-run. When unsure where you are, run `npx -y @openscaffold/cli status --json` again.
* Don't edit `~/.claude` or credentials by hand, and don't call internal APIs.

## Troubleshooting

> **Status says the server isn't answering**
>
> The login points at a server that's down, often a local dev server. Start it, or sign in to the hosted app instead (a plain `login` reuses the saved server):
>
> ```bash theme={null}
> OPENSCAFFOLD_URL=https://app.openscaffold.ai npx @openscaffold/cli login
> ```

> **The login link expired**
>
> Links last 10 minutes and work once. Run `npx @openscaffold/cli login` again.

> **The tools aren't there after login**
>
> Claude Code loads them at session start. Restart it and continue.

> **Claude Code isn't on PATH**
>
> Login prints the exact `claude mcp add` command to run yourself; status shows the MCP server as unknown until then.

> **"No findings yet" from generate\_harness**
>
> The documents had nothing the plan could use, or were empty. Add the customer's calls, tickets or emails and try again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.