@cursor/july 0.1.1

package/docs/reference/hooks.md

@@ -0,0 +1,74 @@
+---
+title: "Hooks"
+description: "Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."
+---
+
+# Hooks
+
+A hook is an observe-only subscriber to the session event stream. Hooks
+run after each event is recorded and fanned out (file persistence flushes
+in the background). That makes them the home for audit logging, metrics,
+mirroring transcripts into your own store, and maintaining derived state.
+Handler errors are logged and never fatal. A hook can't modify events or
+block a turn.
+
+Author `agent/hooks/<name>.ts` with `defineHook` from
+`@cursor/july/hooks`:
+
+```ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.completed"(event, ctx) {
+      console.log("turn done", ctx.session.id, event.data.usage);
+    },
+    async "turn.failed"(event, ctx) {
+      // page, count, or record
+    },
+  },
+});
+```
+
+Keys are event types (the full list is in the
+[event vocabulary](./sessions.md#the-event-vocabulary)), or `"*"` for
+everything. Handlers receive the event with its envelope (`index`,
+`sessionId`, `turnId?`, `at`) and a context carrying read-only
+`ctx.session` info.
+
+## Hooks, channel events, evals, or A/B?
+
+All of them consume the same stream, for different jobs:
+
+| | Hooks | Channel `events` | Evals | A/B (`defineAB`) |
+| --- | --- | --- | --- | --- |
+| Scope | every session on the agent | sessions the channel owns | one test turn | every live session; enrollment at creation, metrics on each turn |
+| Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory | `ab.assigned` + fold stream → `onSample` |
+| Can affect the run | no | yes, it owns the surface | n/a | yes through arm instructions or `session.abs`; collection is observe-only |
+| Authored at | `agent/hooks/*.ts` | channel config | `evals/**/*.eval.ts` | [`agent/ab.ts` or `agent/ab/*.ts`](../ab.md) |
+
+## Patterns
+
+Usage metering: subscribe to `turn.completed` and forward
+`event.data.usage` (token counts) to your metrics system.
+
+Failure alerting: `turn.failed` carries the message, and
+`ctx.session.id` points at the trace.
+
+Derived state: `agent.bound` fires when the Cursor SDK agent id is known
+(`bc-…` on cloud). A PR agent can record PR → agent id from it in a
+hook, so later webhook wakes resume the same cloud conversation.
+
+Transcript export: subscribe to `"*"` and append to your own store. The
+NDJSON envelope is already ordered and replayable.
+
+## What's next
+
+Continue with these pages:
+
+- [Sessions and streaming](./sessions.md): every event a hook can see
+- [Deployment](../deployment.md#observability): hooks as the metrics
+  export path
+- [Channels](./channels.md#events): the delivery-side counterpart
+- [Live A/B metrics](../ab.md): sticky variants over the same event
+  stream

package/docs/reference/http-api.md

@@ -0,0 +1,219 @@
+---
+title: "HTTP API"
+description: "Every route the server mounts: sessions, approvals, deterministic tool calls, discovery, the MCP endpoint, and dev-mode dispatch."
+---
+
+# HTTP API reference
+
+Every agentkit host speaks the same stable HTTP API. In the default
+multi-agent layout each agent is namespaced under its slug
+(`/<slug>/v1/session`, `/<slug>/playground`), with host-level routes at
+the root. With `--mode single`, one agent serves the same surface
+unslugged (`/v1/*`).
+
+Unless noted otherwise, routes run the agent's HTTP auth chain: the
+default is `localDevStrict()` (loopback only), replaced by `bearerAuth` under
+`--bearer-token` or `allowAll()` under `--allow-anonymous`. Session
+routes also require the caller to be the session's owner (`403`
+otherwise). Errors return JSON
+`{ ok: false, error: "<code>", message? }` with a matching HTTP status.
+
+## Host-level routes (multi-agent mode)
+
+These routes live at the host root, above any agent. The two index
+routes exist only while the playground is enabled (`--no-playground`
+removes them) and run no auth. The documentation site is mounted in
+both layouts and removed by `--no-docs`.
+
+| Route                      | What it does                                                                                                                 |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `GET /`                    | A web index of every mounted agent, linking to playgrounds (playground only)                                                 |
+| `GET /v1/agents`           | The JSON index of mounted agents (playground only, no auth)                                                                  |
+| `GET /docs`, `GET /docs/*` | This documentation, served as a static site (both layouts, no auth)                                                          |
+| `GET /v1/health`           | Host-level liveness, no auth; made for ALB/ECS checks                                                                        |
+| `POST /v1/webhooks/github` | Loopback-only trigger endpoint that fans a GitHub-shaped payload out to every mounted GitHub channel (used by local tooling) |
+
+## Start a session
+
+`POST /v1/session` opens a durable conversation.
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/session \
+  -H 'content-type: application/json' \
+  -d '{"message":"What can you do?"}'
+# {"ok":true,"sessionId":"ses_…","continuationToken":"http:…",
+#  "playgroundUrl":"…?sessionId=ses_…","traceUrl":"…/v1/session/ses_…/events"}
+```
+
+The response returns as soon as the message is accepted; follow the
+stream for progress. The continuation token is the follow-up credential,
+and `playgroundUrl` deep-links the session in the playground.
+
+## Send a follow-up
+
+`POST /v1/session/:sessionId` continues an existing conversation.
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_… \
+  -H 'content-type: application/json' \
+  -d '{"continuationToken":"http:…","message":"Make it shorter."}'
+```
+
+Works for any chat session, including ones created by custom channels.
+Each accepted follow-up rotates the token, and the response carries the
+new one. Sending to a busy session interrupts the in-flight turn, waits
+for it to settle, then sends; when the turn can't be interrupted (for
+example, concurrent follow-ups racing), the request returns
+`409 session_busy`.
+
+Expect `409` on a stale token, an uninterruptible busy session, or a
+task/schedule session (those aren't followable), and `403` when the
+caller isn't the session owner.
+
+## Stream a session
+
+`GET /v1/session/:sessionId/stream` is the live NDJSON feed.
+
+```bash
+curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
+```
+
+One NDJSON event per line, from `startIndex`, then following live. The
+default is `0`: omitting the parameter replays the entire recorded
+stream before following. Pass the last index you've seen plus one to
+resume without duplicates. The stream is durable and reconnectable. For
+the vocabulary, see
+[Sessions](./sessions.md#the-event-vocabulary).
+
+`GET /v1/session/:sessionId/events` returns the same content as a
+one-shot dump with no live follow.
+
+## Stop and list
+
+`POST /v1/session/:sessionId/stop` interrupts the in-flight turn without
+sending a new message. `GET /v1/sessions` lists sessions owned by the
+calling principal. Under `serve --dev` on loopback it includes all
+sessions, which is how webhook and schedule sessions show up in the
+playground.
+
+## Approvals
+
+Two routes list and resolve parked tool calls.
+
+| Route                                           | What it does                                                   |
+| ----------------------------------------------- | -------------------------------------------------------------- |
+| `GET /v1/session/:sessionId/approvals`          | Pending human-in-the-loop tool approvals                       |
+| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one: `{"decision":"approve"}` or `{"decision":"deny"}` |
+
+For the lifecycle, see [Human-in-the-loop](../guides/human-in-the-loop.md).
+
+## Call a tool directly
+
+`POST /v1/tools/:toolName` runs a server tool with no model turn.
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
+  -H 'content-type: application/json' \
+  -d '{"input":{"prUrl":"https://github.com/acme/checkout/pull/42"}}'
+# {"ok":true,"toolName":"inspect_pr","callId":"tool_inspect_pr_…",
+#  "isError":false,"result":{…},"durationMs":12}
+```
+
+It runs an authored server tool in-process: schema-validated, no model
+turn. An optional `"sessionId"` in the body runs it inside an existing
+session and records it on that session's stream (`409 session_busy`
+while a turn runs). Agent-execution tools are rejected with `400`, and
+unknown tools with `404` and the list of available names. For the
+semantics, see [Tools](./tools.md#call-a-tool-without-a-model-turn).
+
+## Discovery and meta
+
+Five read-only routes describe the running agent.
+
+| Route                  | What it does                                                                                                                                                                             |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /v1/info`         | The manifest snapshot: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics; the same shape as `agentkit info --json` |
+| `GET /v1/health`       | Per-agent liveness, no auth                                                                                                                                                              |
+| `GET /v1/meta`         | SPA bootstrap: agent name, dev flag, base path (no auth)                                                                                                                                 |
+| `GET /v1/logs?after=N` | Recent server log lines from the ring buffer, with a polling cursor                                                                                                                      |
+| `GET /v1/abs`          | [Live A/B metrics](../ab.md): per-session assignments and aggregate arm totals folded from durable event streams (`config` reports `maxPlaygroundSessions` / `durableSamples` / `durableSnapshots` from `agent/ab.config.ts`) |
+
+## Custom channel routes
+
+Authored routes mount under `/v1/channels/<id>` with the methods, paths,
+and Zod schemas the channel declared (a
+`POST /<slug>/v1/channels/drive` route, say). Bodies are validated before
+handlers run (`400` on schema violations), and each channel's auth chain
+applies. The GitHub channel verifies `X-Hub-Signature-256` when a
+secret is configured. See [Channels](./channels.md).
+
+## MCP endpoint
+
+`/v1/mcp` serves the Model Context Protocol over streamable HTTP
+(stateless; POST carries the protocol, and GET/DELETE return
+spec-compliant 405s). The tools are `ask` (delegate a message, bounded
+waits), `check` (poll a running session), and `call_tool` (deterministic
+server-tool passthrough, present when the agent has server tools). The
+route runs the same auth chain as the session API. See
+[Agent-to-agent](../guides/agent-to-agent.md).
+
+## Playground eval routes
+
+Always registered (including production / non-`--dev` serves). The playground
+Evals tab uses these:
+
+| Route                           | What it does                                                                                               |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `GET /v1/dev/evals`             | List discovered eval datapoints and project config as `{ evals, config }` (`config` includes `maxPlaygroundRuns`, `durableRuns`) |
+| `GET /v1/dev/evals/runs`        | List recent run snapshots (newest first) as `{ runs, activeRunId? }` for playground rehydrate              |
+| `POST /v1/dev/evals/runs`       | Start an eval run (`{filterIds?, tags?}`); `202` with a snapshot, `404` when nothing matches, `409` when one is running |
+| `GET /v1/dev/evals/runs/:runId` | Poll a run's progress                                                                                      |
+
+Eval runs are asynchronous. Poll the run route for case progress and
+the final `completed` or `failed` status. Batch errors appear on the
+snapshot returned by the poll. Entries within `filterIds` and `tags`
+use OR semantics. When both fields are present, a case must match one
+entry from each field. Without `persistRuns` in `evals.config.ts`,
+listed runs are process-memory only (capped by `maxPlaygroundRuns`).
+
+## Dev-mode routes
+
+These routes exist only under `serve --dev`.
+
+| Route                                | What it does                                                                                               |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `POST /v1/dev/schedules/:scheduleId` | Dispatch a schedule by hand, exactly once, through the production path. Returns `{scheduleId, sessionIds}` |
+| `GET /v1/dev/reminders`              | List reminders                                                                                             |
+| `POST /v1/dev/reminders/:reminderId` | Fire a reminder by hand                                                                                    |
+
+Schedules and reminders never fire automatically in dev mode. These
+routes are the only way they run, which keeps iteration deterministic.
+
+## Playground assets
+
+`GET /playground` and `GET /playground/assets/:file` serve the static
+SPA bundle (omitted with `--no-playground`). The playground calls the
+JSON API above and has no privileged surface.
+
+## Status codes
+
+Error responses use a small, consistent set of status codes.
+
+| Code  | Meaning here                                                                                                               |
+| ----- | -------------------------------------------------------------------------------------------------------------------------- |
+| `400` | Schema-invalid body or query, agent-execution tool called on the host, malformed request                                   |
+| `401` | No auth policy admitted the request                                                                                        |
+| `403` | Authenticated, but not the session owner                                                                                   |
+| `404` | Unknown session, tool, schedule, reminder, or eval run; no eval datapoints match a run request                              |
+| `405` | Wrong method (GET on the MCP endpoint, say)                                                                                |
+| `409` | Stale continuation token, busy session (`session_busy`), a non-followable task session, or an eval run already in progress |
+| `202` | Accepted for background work (GitHub `{ task }` hooks, eval runs)                                                          |
+
+## What's next
+
+Continue with these pages:
+
+- [Sessions and streaming](./sessions.md): the handles and events these
+  routes traffic in
+- [Channels](./channels.md): authoring your own routes
+- [Deployment](../deployment.md): auth on real hosts

package/docs/reference/instructions.md

@@ -0,0 +1,77 @@
+---
+title: "Instructions"
+description: "The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up."
+---
+
+# Instructions
+
+`agent/instructions.md` is the always-on system prompt. It's the one
+piece of prose the model sees on every turn. It's required on the root
+agent; subagents may inline `instructions` in their `agent.ts` instead.
+
+## Authoring forms
+
+Three forms cover every case.
+
+| Form | Reach for it when |
+| --- | --- |
+| `agent/instructions.md` | Plain Markdown for most agents. |
+| `agent/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a plain string. |
+| `agent/instructions/` directory | A long prompt split across files, composed in filename order. |
+
+```ts
+// agent/instructions.ts
+import { defineInstructions } from "@cursor/july";
+
+export default defineInstructions({
+  markdown: `You are the on-call assistant for ${process.env.TEAM_NAME}.`,
+});
+```
+
+## How instructions reach the model
+
+On the local runtime, instructions land in the session workspace as
+`AGENTS.md`, and the harness loads them natively. On the cloud runtime,
+they're prepended to the first prompt, because the cloud VM doesn't
+share the local session workspace.
+
+The local workspace is a real Cursor project directory, so the harness
+may also load ambient `AGENTS.md` and `.cursor` config from ancestor
+directories. [Agent config → Local cwd](./agent-config.md#local-cwd)
+covers controlling that.
+
+## Best Practices
+
+Keep them a few lines: identity, when to use which tool, output shape.
+The [quickstart weather agent](../quickstart.md) is the pattern:
+
+```md
+# Weather agent
+
+You are a concise weather assistant.
+
+- Use `get_weather` before answering questions about current weather.
+- Tell the user the weather data is simulated.
+- Keep replies to two sentences or fewer.
+```
+
+- Name the tools and the decision rule ("use X before answering about
+  Y"), not general encouragement.
+- State the output contract: length, format, fences. That contract is
+  what your [evals](../evals.md) gate.
+- Move procedures to [skills](./skills.md). A multi-step workflow the
+  model only sometimes needs belongs in `agent/skills/`, where it loads
+  on demand and keeps the always-on prompt small.
+
+Instructions are the third lever in the
+[hillclimbing loop](../hillclimbing.md), after host preparation and evidence
+shape. If a fixture keeps failing, look there before rewriting prose.
+
+## What's next
+
+Continue with these pages:
+
+- [Skills](./skills.md): procedures the model loads only when relevant
+- [Agent config](./agent-config.md): the file next to this one
+- [Hillclimbing](../hillclimbing.md): iterating on instructions with
+  evidence

package/docs/reference/playground.md

@@ -0,0 +1,67 @@
+---
+title: "Playground"
+description: "The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."
+---
+
+# Playground
+
+Every served agent ships with a web playground at
+`http://127.0.0.1:3000/<slug>/playground` (or `/playground` in single
+mode): a static SPA over the same public HTTP API, made for manual
+testing, demos, and reading sessions. Every call it makes runs the
+normal route auth chain, so anything you can do in the playground you
+can also do with curl.
+
+## What it does
+
+The playground covers the whole manual-testing loop.
+
+- **Chat** with the agent. Text and reasoning stream live, rendered as
+  markdown with syntax highlighting, and tool calls appear inline with
+  their arguments, output, and error state as the `actions.requested` /
+  `action.result` events arrive.
+- **Slash commands**: custom channel routes become composer commands
+  (a `drive` route becomes `/drive <pr-url>`), derived from the schemas
+  on `GET /v1/info`, with `/help` and autocomplete.
+- **Try** any channel route from the Agent surface. The modal remembers
+  your last body per endpoint and has Copy curl, and a successful Try
+  opens the created session.
+- **Sessions**: browse every session (chat, custom-channel, schedule
+  tasks) and replay their durable event streams. Search by session ID
+  to filter the list, or press Enter to open an ID directly. "Open
+  trace" renders any `events.ndjson` file.
+- **Approvals**: parked `needsApproval` tool calls render Approve /
+  Deny buttons.
+- **Evals**: list and run filesystem evals from the browser (backed by
+  `/v1/dev/evals`). Schedule hand-dispatch still requires `--dev`.
+- **The surface**: inspect the discovered tools, skills, subagents, MCP
+  connections, channels, and hooks.
+- **Raw NDJSON pane**: flip it on to see the exact wire events.
+- **Logs tab**: recent server log lines, polled from `GET /v1/logs`.
+- **A/Bs tab**: per-session and aggregate
+  [live A/B metrics](../ab.md) from `GET /v1/abs` (folds durable
+  `ab.assigned` plus turn and tool events; no separate store).
+
+In multi-agent mode each agent has its own playground at
+`/<slug>/playground`, and `/` is an index of them all.
+
+## Share it beyond localhost
+
+The default `localDevStrict()` auth admits direct loopback calls only
+and rejects proxy-forwarding headers, so a tunnel or LAN address won't
+work
+until you pass `--bearer-token <secret>` (or
+`serve(dir, { authToken })`). Open the playground on the remote device
+and paste the token into the token field in the navbar. `--allow-anonymous` is the
+demo-only alternative for trusted networks.
+
+## What's next
+
+Continue with these pages:
+
+- [HTTP API](./http-api.md): everything the playground calls
+- [Sessions and streaming](./sessions.md): the streams it renders
+- [Human-in-the-loop](../guides/human-in-the-loop.md): the approval
+  buttons in context
+- [Live A/B metrics](../ab.md): the assignments and results in the A/Bs
+  tab

package/docs/reference/project-layout.md

@@ -0,0 +1,119 @@
+---
+title: "Project layout"
+description: "The folder structure under agent/ and the path-derived naming rule."
+---
+
+# Project layout
+
+agentkit builds an agent by walking the filesystem under `agent/`.
+Each folder has a defined purpose. The path a file lands in determines
+how agentkit loads it.
+
+## Folder structure
+
+For the capabilities below, identity usually comes from the path. A/B
+experiments can override their file-derived name.
+
+| Path | Resolves to |
+| --- | --- |
+| `agent/tools/approve_pr.ts` | tool `approve_pr` |
+| `agent/mcp-connections/linear.ts` | MCP connection `linear` |
+| `agent/skills/pr-review.md` | skill `pr-review` |
+| `agent/subagents/reviewer/` | subagent `reviewer` |
+| `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
+| `agent/ab.ts` | A/B experiment `ab` unless `name` overrides it |
+| `agent/ab/concise.ts` | A/B experiment `concise` unless `name` overrides it |
+
+The root agent takes its name from `package.json` `name`, falling back
+to the directory name. When serving multiple agents, the slug is the
+directory name and must match `[A-Za-z0-9][A-Za-z0-9_-]*` (and not the
+reserved `v1`, `playground`, or `docs` segments).
+
+## Full project layout
+
+A full project looks like this.
+
+```text
+my-agent/
+├── package.json
+├── agent/
+│   ├── agent.ts               # runtime config (model, runtime, cloud/local)
+│   ├── instructions.md        # always-on system prompt (required)
+│   ├── tools/
+│   │   └── approve_pr.ts      # one typed tool per file
+│   ├── skills/
+│   │   └── pr-review.md       # on-demand procedures (SKILL.md convention)
+│   ├── mcp-connections/
+│   │   └── linear.ts          # tools from external MCP servers
+│   ├── subagents/
+│   │   └── reviewer/          # child agents (agent.ts + instructions.md)
+│   ├── channels/
+│   │   ├── webhook.ts         # custom HTTP surfaces
+│   │   ├── slack.ts           # the Slack channel pack
+│   │   └── github.ts          # the GitHub webhook channel pack
+│   ├── hooks/
+│   │   └── audit.ts           # observe the runtime event stream
+│   ├── ab.ts                  # optional live A/B experiment
+│   ├── ab/
+│   │   └── concise.ts         # optional: more experiments
+│   ├── schedules/
+│   │   └── heartbeat.md       # cron-driven runs
+│   ├── sandbox/workspace/     # files seeded into each session's workspace
+│   └── lib/                   # shared code (import-only, never discovered)
+└── evals/
+    ├── evals.config.ts        # required when evals exist (maxConcurrency)
+    └── readiness.eval.ts      # filesystem evals
+```
+
+Evals live in `evals/` at the project root, a sibling of `agent/`, never
+inside it. `agent/evals/` is silently ignored. See
+[Evals](../evals.md).
+
+## Folder reference
+
+Each path maps to a capability and a reference page.
+
+| Path | What it is | Reference |
+| --- | --- | --- |
+| `agent/agent.ts` | `defineAgent({ model?, runtime?, cloud?, local? })`; the model defaults to `grok-4.5` with `effort=high`, `fast=true` | [Agent config](./agent-config.md) |
+| `agent/instructions.md` | Always-on system prompt, required on the root agent (`.ts` and directory forms exist) | [Instructions](./instructions.md) |
+| `agent/tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (a script that runs where the agent runs) | [Tools](./tools.md) |
+| `agent/skills/*` | SKILL.md-convention procedures, loaded on demand | [Skills](./skills.md) |
+| `agent/mcp-connections/<name>.ts` | MCP servers, available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) | [MCP connections](./connections.md) |
+| `agent/subagents/<id>/` | Child agent directory; `description` required | [Subagents](./subagents.md) |
+| `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
+| `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
+| `agent/ab.ts`, `agent/ab/*.ts` | `defineAB` experiments with sticky variants and live metrics | [Live A/B metrics](../ab.md) |
+| `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](./schedules.md) |
+| `agent/lib/` | Import-only shared code, never discovered | None |
+| `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` | [Evals](../evals.md) |
+
+`agent/lib/` is the only place for shared code. Everything else under
+`agent/` is discovery surface. A stray `.ts` file in one of these
+folders is treated as a definition.
+
+## Why didn't agentkit discover my file?
+
+Run `agentkit validate --dir .` and `agentkit info --dir .`.
+`validate` prints diagnostics, and `serve` refuses to start on
+error-severity ones. Warnings, such as cloud runtime combined with
+local-only capabilities, print but don't block. `info` lists the discovered
+surface, so a missing tool or channel shows up immediately. From
+there, check the folder reference: the file is usually in the wrong directory
+or has the wrong extension.
+
+```bash
+agentkit validate --dir .    # diagnostics; non-zero exit on errors
+agentkit info --dir .        # human-readable surface
+agentkit info --dir . --json # machine-readable manifest (same shape as GET /v1/info)
+```
+
+## What's next
+
+Continue with these pages:
+
+- [Agent config](./agent-config.md): the runtime config at the root
+- [Tools](./tools.md): add typed actions under `agent/tools/`
+- [Live A/B metrics](../ab.md): compare variants from `agent/ab.ts` or
+  `agent/ab/`
+- [Concepts](../concepts.md): why the filesystem is the interface