# WS3 Spec — quick-start.md

## Target file
`docs/developers/quick-start.md`

## Objective
The quick start must be updated so that creating an organization becomes Step 1, since agents
can now be scoped to an organization. All steps are renumbered accordingly. All endpoint paths
must be verified against current routes. The new step order is:

1. Clone and configure (unchanged)
2. Start infrastructure (unchanged)
3. Start the AgentIdP server (unchanged)
4. Generate a bootstrap token (unchanged)
5. **[NEW]** Create an organization
6. Register an agent (update to include `organization_id`)
7. Generate a credential (renumbered, content unchanged)
8. Issue an access token (renumbered, content unchanged)

The "What's next" section at the bottom must be updated to include new guides.

---

## Surgical edits — exact changes to make

### Edit 1 — Update the title paragraph

**Find** (exact text):
```
This guide gets you from zero to a working agent identity with a valid OAuth 2.0 access token. It takes under 5 minutes.
```

**Replace with**:
```
This guide gets you from zero to a working agent identity inside an organization, with a valid OAuth 2.0 access token. It takes under 5 minutes.
```

---

### Edit 2 — Renumber Step 4 and insert new Step 5

After the existing Step 4 section (Generate a bootstrap token), which ends with:

```
> This bootstrap token is a one-time tool for registering your first agent. Once you have an agent with credentials, use `POST /token` for all subsequent authentication.
```

Insert a `---` separator followed by the new **Step 5 — Create an organization** section:

```markdown
---

## Step 5 — Create an organization

Agents are scoped to organizations. Create one now so your agent has an `organization_id` to belong to:

```bash
curl -s -X POST http://localhost:3000/api/v1/organizations \
  -H "Authorization: Bearer $BOOTSTRAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Project",
    "slug": "my-ai-project"
  }' | jq .
```

Example response (`201 Created`):

```json
{
  "organizationId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
  "name": "My AI Project",
  "slug": "my-ai-project",
  "planTier": "free",
  "maxAgents": 10,
  "maxTokensPerMonth": 10000,
  "status": "active",
  "createdAt": "2026-04-04T09:00:00.000Z",
  "updatedAt": "2026-04-04T09:00:00.000Z"
}
```

Save the `organizationId`:

```bash
export ORG_ID="org-0a1b2c3d-e4f5-6789-abcd-ef0123456789"
```
```

---

### Edit 3 — Renumber the agent registration step

**Find** (heading only):
```
## Step 5 — Register an agent
```

**Replace with**:
```
## Step 6 — Register an agent
```

---

### Edit 4 — Update the agent registration curl command to include organization_id

**Find** (exact curl command):
```bash
curl -s -X POST http://localhost:3000/api/v1/agents \
  -H "Authorization: Bearer $BOOTSTRAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "my-first-agent@myproject.ai",
    "agentType": "custom",
    "version": "1.0.0",
    "capabilities": ["data:read"],
    "owner": "my-team",
    "deploymentEnv": "development"
  }' | jq .
```

**Replace with**:
```bash
curl -s -X POST http://localhost:3000/api/v1/agents \
  -H "Authorization: Bearer $BOOTSTRAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "my-first-agent@myproject.ai",
    "agentType": "custom",
    "version": "1.0.0",
    "capabilities": ["data:read"],
    "owner": "my-team",
    "deploymentEnv": "development",
    "organization_id": "'$ORG_ID'"
  }' | jq .
```

---

### Edit 5 — Renumber Step 6 (credential generation)

**Find** (heading only):
```
## Step 6 — Generate a credential
```

**Replace with**:
```
## Step 7 — Generate a credential
```

---

### Edit 6 — Renumber Step 7 (token issuance)

**Find** (heading only):
```
## Step 7 — Issue an access token
```

**Replace with**:
```
## Step 8 — Issue an access token
```

---

### Edit 7 — Update the "What's next" section

**Find** (entire What's next section):
```markdown
## What's next

- [Core Concepts](concepts.md) — understand AgentIdP, AGNTCY, and the agent identity model
- [Guides](guides/README.md) — step-by-step walkthroughs for credentials, tokens, and audit logs
- [API Reference](api-reference.md) — every endpoint documented with curl examples
```

**Replace with**:
```markdown
## What's next

- [Core Concepts](concepts.md) — understand AgentIdP, AGNTCY, orgs, DID, delegation, and tiers
- [Guides](guides/README.md) — step-by-step walkthroughs for all workflows
- [API Reference](api-reference.md) — every endpoint documented with curl examples

**New guides for Phase 6 features:**

- [Use the Analytics Dashboard](guides/use-analytics-dashboard.md) — query token trends and activity
- [Manage API Tiers](guides/manage-api-tiers.md) — check limits and upgrade your plan
- [A2A Delegation](guides/a2a-delegation.md) — delegate authority between agents
- [Configure Webhooks](guides/configure-webhooks.md) — subscribe to real-time events
- [AGNTCY Compliance](guides/agntcy-compliance.md) — export agent cards and generate compliance reports
```

---

## Verification checklist

The Developer must verify all curl paths in the updated file match these current routes:

| Action | Current endpoint |
|--------|-----------------|
| Create org | `POST /api/v1/organizations` |
| Register agent | `POST /api/v1/agents` |
| Generate credential | `POST /api/v1/agents/{agentId}/credentials` |
| Issue token | `POST /api/v1/token` |

The bootstrap token scopes must include `agents:write` and `organizations:write` (or the equivalent
OPA-enforced policy). The bootstrap token generation node script in Step 4 currently uses
`agents:read agents:write tokens:read audit:read`. This is unchanged — no edit needed there.