docs: commit all Phase 6 documentation updates and OpenSpec archives
- devops docs: 8 files updated for Phase 6 state; field-trial.md added (946-line runbook) - developer docs: api-reference (50+ endpoints), quick-start, 5 existing guides updated, 5 new guides added - engineering docs: all 12 files updated (services, architecture, SDK guide, testing, overview) - OpenSpec archives: phase-7-devops-field-trial, developer-docs-phase6-update, engineering-docs-phase6-update - VALIDATOR.md + scripts/start-validator.sh: V&V Architect tooling added - .gitignore: exclude session artifacts, build artifacts, and agent workspaces Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SentryAgent.ai Developer
@@ -0,0 +1,212 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user