Skip to content

Commit 941933c

Browse files
kveykvey
authored
Add a VitePress docs website built from docs/ (#146)
1 parent 8091a15 commit 941933c

65 files changed

Lines changed: 7874 additions & 12 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Builds the docs website (Next.js + Fumadocs, content from docs/) and
2+
# deploys it to GitHub Pages.
3+
#
4+
# Requires Pages to be enabled for the repository with "GitHub Actions" as the
5+
# source (Settings → Pages → Build and deployment → Source).
6+
name: Docs
7+
8+
on:
9+
push:
10+
branches: [main]
11+
paths:
12+
- "docs/**"
13+
- "website/**"
14+
- ".github/workflows/docs.yml"
15+
workflow_dispatch:
16+
17+
permissions:
18+
contents: read
19+
pages: write
20+
id-token: write
21+
22+
# Allow one concurrent deployment, but don't cancel an in-flight production
23+
# deploy — let it finish and deploy the newer build after.
24+
concurrency:
25+
group: pages
26+
cancel-in-progress: false
27+
28+
jobs:
29+
build:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v4
33+
- uses: actions/setup-node@v4
34+
with:
35+
node-version: 22
36+
cache: npm
37+
cache-dependency-path: website/package-lock.json
38+
- name: Install dependencies
39+
run: npm ci
40+
working-directory: website
41+
- name: Build site
42+
run: npm run build
43+
working-directory: website
44+
env:
45+
# Project pages are served under /<repo>. Drop this (or set it to
46+
# empty) if the site moves to a custom domain.
47+
DOCS_BASE_PATH: /chidori
48+
- uses: actions/upload-pages-artifact@v3
49+
with:
50+
path: website/out
51+
52+
deploy:
53+
needs: build
54+
runs-on: ubuntu-latest
55+
environment:
56+
name: github-pages
57+
url: ${{ steps.deployment.outputs.page_url }}
58+
steps:
59+
- id: deployment
60+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,12 @@ sdk/python/dist/
5151
# Node
5252
node_modules/
5353

54+
# Docs website (Next.js + Fumadocs) build output and generated sources
55+
/website/.next/
56+
/website/out/
57+
/website/.source/
58+
/website/next-env.d.ts
59+
5460
# Secrets / local env
5561
.env
5662
.envrc

‎README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -407,9 +407,22 @@ deterministic, replayable, and testable for free.
407407

408408
## 📚 Documentation
409409

410+
The docs are plain markdown in [`docs/`](./docs) and also build into a
411+
searchable website ([`website/`](./website), Next.js + Fumadocs). To browse
412+
them locally:
413+
414+
```bash
415+
cd website && npm install && npm run dev
416+
```
417+
410418
| Topic | What's there |
411419
|---|---|
412420
| [Getting started & demos](./docs/getting-started.md) | Demo picker, inspecting a run, human-in-the-loop walkthrough, example agents |
421+
| [Your first agent](./docs/your-first-agent.md) | Fifteen-minute tutorial: write an agent, pause it for approval, replay it for $0, check it into CI |
422+
| [Common patterns](./docs/patterns.md) | Task-oriented recipes: approval gates, tool loops, fan-out, webhooks, scheduled agents, checkpoint tests |
423+
| [FAQ](./docs/faq.md) | Python support, Node, providers, comparisons, data locality, troubleshooting |
424+
| [Host API reference](./docs/host-api.md) | Every `chidori.*` method, option by option — plus providers, streaming events, and runtime policy |
425+
| [CLI reference](./docs/cli.md) | Every subcommand: run/chat/serve, resume/verify/trace, branches, packages, approval postures |
413426
| [Core concepts & host API](./docs/core-concepts.md) | Host function reference, streaming prompt progress, prompt caching |
414427
| [Running modes](./docs/running-modes.md) | One-shot CLI, HTTP server + session API, event-driven agents |
415428
| [How replay works](./docs/replay.md) | Record/checkpoint/replay model and SDK replay |

‎docs/README.md‎

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,34 @@
11
# Chidori documentation
22

3+
Everything here is plain markdown, readable on GitHub as-is. The same files
4+
are the content source for the docs website in [`website/`](../website),
5+
built with [Next.js](https://nextjs.org) + [Fumadocs](https://fumadocs.dev):
6+
7+
```bash
8+
cd website
9+
npm install
10+
npm run dev # local dev server with live reload
11+
npm run build # static site in website/out
12+
```
13+
14+
The site is deployed to GitHub Pages by
15+
[`.github/workflows/docs.yml`](../.github/workflows/docs.yml) on every push to
16+
`main` that touches `docs/` or `website/`.
17+
18+
Conventions for writing pages:
19+
20+
- Every page carries a small YAML frontmatter block with its sidebar `title`;
21+
keep the `# H1` in the body too — that's what renders, on GitHub and on the
22+
site.
23+
- Sidebar order and section groupings live in `meta.json` (and
24+
`posts/meta.json`).
25+
- Keep writing ordinary relative links (`./other-page.md`,
26+
`../examples/...`); the build rewrites in-docs links to site routes and
27+
out-of-docs links to GitHub URLs.
28+
- Write plain CommonMark, not MDX — `{` and `<` in prose stay literal.
29+
This README and `posts/harness-engineering-thread.md` are excluded from
30+
the site.
31+
332
This directory mixes two audiences. **Using Chidori** is the path for agent
433
authors and operators; **Engineering notes** are internal design records —
534
useful history and rationale, but not tutorials, and some describe work that
@@ -11,21 +40,34 @@ Start here, roughly in order:
1140

1241
| Doc | What it covers |
1342
|---|---|
14-
| [getting-started.md](./getting-started.md) | Install, first agent, first replay |
43+
| [getting-started.md](./getting-started.md) | Install, run the demos, inspect a durable run |
44+
| [your-first-agent.md](./your-first-agent.md) | Tutorial: write an agent, pause it, replay it for $0, check it into CI |
1545
| [core-concepts.md](./core-concepts.md) | Host calls, the call log, safepoints |
46+
| [patterns.md](./patterns.md) | Task-oriented recipes: which primitive fits which job |
47+
| [faq.md](./faq.md) | Python support, Node, providers, comparisons, data locality, troubleshooting |
1648
| [replay.md](./replay.md) | Record, replay, resume, divergence rules |
1749
| [running-modes.md](./running-modes.md) | `run` vs `serve`, policy profiles, `--trusted` |
1850
| [signals.md](./signals.md) | Named signals: pause for humans or other agents |
1951
| [branching-execution.md](./branching-execution.md) | `chidori.branch` sub-runs |
2052
| [actors.md](./actors.md) | Supervised, message-passing agent processes |
2153
| [detached-agents.md](./detached-agents.md) | Long-lived agents outside a session |
2254
| [context-management.md](./context-management.md) | Conversation and context windows |
23-
| [value-checkpoints.md](./value-checkpoints.md) | `durableStep`: bounding replay cost |
55+
| [memory.md](./memory.md) | `chidori.memory`: persistent cross-run key-value storage |
56+
| [template.md](./template.md) | `chidori.template`: Jinja prompt rendering |
57+
| [value-checkpoints.md](./value-checkpoints.md) | `chidori.step`: bounding replay cost |
2458
| [durable-storage.md](./durable-storage.md) | Run persistence, time travel (`--until-seq`) |
2559
| [package-management.md](./package-management.md) | Imports, `node:` builtins, npm packages |
2660
| [sandbox-model.md](./sandbox-model.md) | The security model and its guarantees |
61+
| [observing-with-tael.md](./observing-with-tael.md) | OTLP export, run↔trace correlation, golden cases |
2762
| [deployment.md](./deployment.md) | Serving agents in production |
2863

64+
## Reference
65+
66+
| Doc | What it covers |
67+
|---|---|
68+
| [host-api.md](./host-api.md) | Every `chidori.*` method, option by option; providers; runtime policy |
69+
| [cli.md](./cli.md) | Every subcommand and the approval postures |
70+
2971
## Engineering notes (internal)
3072

3173
Design records for contributors. Status headers inside each file are

‎docs/actors.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
title: "Actors"
3+
description: "Supervised, message-passing agent processes: spawn, send, receive, join, restart strategies, and supervision trees."
4+
---
5+
16
# Actors: supervised, message-passing agent processes
27

38
Actors let one agent run start other agent modules as long-lived, concurrent,

‎docs/ai-sdk-gap-analysis.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
title: "AI SDK Gap Analysis"
3+
description: "Feature comparison against the Vercel AI SDK."
4+
---
5+
16
# Chidori vs. Vercel AI SDK Gap Analysis
27

38
This note compares Chidori's current functionality against the Vercel AI SDK

‎docs/architecture.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
title: "Architecture"
3+
description: "Engine and runtime layering: the high-level component map and repository layout."
4+
---
5+
16
# Architecture & project structure
27

38
A high-level map of the runtime.

‎docs/branching-execution.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
title: "Branching Execution"
3+
description: "chidori.branch sub-runs: fork a run into per-strategy variants from the current state and compare every outcome."
4+
---
5+
16
# Branching execution
27

38
`chidori.branch(variants)` lets an agent **fork itself mid-run** into N

‎docs/captured-effects-vfs-crypto-timers.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
title: "Captured Effects"
3+
description: "Captured-effect surfaces: networking, the virtual filesystem, crypto, and timers."
4+
---
5+
16
# Captured Effects: Virtual Filesystem, Crypto, and Timers
27

38
## Implementation status (Phases 1–4 landed)

‎docs/cli.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: "CLI Reference"
3+
description: "Every chidori subcommand — run, serve, resume, verify, trace, chat, branches, packages — and the approval postures that govern them."
4+
---
5+
6+
# CLI reference
7+
8+
One binary, no runtime dependencies. This page lists every subcommand with
9+
its job and the doc that covers it in depth.
10+
11+
## Scaffolding and exploring
12+
13+
| Command | What it does |
14+
|---|---|
15+
| `chidori init [dir] --template docs\|chat\|worker` | Scaffold a starter project (agent + README; the `docs` template bundles a docs corpus to chat with). Omit `--template` to pick interactively. |
16+
| `chidori demo` | Interactive picker over the runnable examples, including no-key demos. |
17+
| `chidori check <agent.ts>` | Validate an agent file without running it. |
18+
| `chidori model-login` | Zero-setup OpenRouter fallback — prompts work without configuring a provider key. |
19+
20+
## Running
21+
22+
| Command | What it does |
23+
|---|---|
24+
| `chidori run <agent.ts> --input key=value` | One-shot run. `--input` takes `key=value` pairs or a JSON object; `--model` sets the run's default model; `--stream` emits NDJSON progress events; `--trace` prints the call log as it grows. |
25+
| `chidori chat [agent.ts]` | Interactive multi-turn REPL backed by `conversation()`. With no file, chats with the model directly (`--system`, `--model`); with a conversational agent file, chats through it. Each turn is a durable host call; prior turns replay for free, so only the newest message reaches the provider. `--resume <session_id>` reprints the transcript for $0 and continues the same session. |
26+
| `chidori serve <agent.ts> --port 8080` | HTTP session server: sessions, pause/resume, signals, SSE streaming ([Running Modes](./running-modes.md)). In production, set `CHIDORI_API_KEY` for bearer auth and see the [Deployment](./deployment.md) checklist. |
27+
| `chidori serve --port 8080` | Fleet-only server (no agent file): hosts detached agents; sessions must name an agent. |
28+
29+
## Replay, resume, and testing
30+
31+
| Command | What it does |
32+
|---|---|
33+
| `chidori resume <agent.ts> <run_id>` | Replay a recorded run byte-for-byte with zero model calls; the run's recorded model applies automatically (`--model` overrides). A crashed run replays to the frontier of its log and continues live. |
34+
| `chidori resume … --trusted` | Crash recovery of a trusted tool-using run — same posture flags as `run`; continuation journals into the same run dir. |
35+
| `chidori resume … --allow-source-change` | Edit-and-resume: replay against edited code, divergence-checked ([divergence rules](./replay.md)). |
36+
| `chidori verify <agent.ts> <run_id>` | Checkpoint-as-test: replay with **no provider** and a **deny-all policy**; asserts completion with byte-identical output. Exit 0 = pass. Built for CI. Journaled workspace writes do re-materialize on disk (same bytes, fresh mtime). |
37+
| `chidori trace <run_id>` | Print a run's call log — every prompt, tool call, and effect, with token counts and cost (including prompt-cache read/write totals). |
38+
| `chidori stats` | Usage and cost totals, including prompt-cache read/write tokens. |
39+
| `chidori snapshot <run_id>` | Print `runtime.snapshot.json` metadata (never raw VM snapshot bytes). |
40+
41+
Run journals live under `.chidori/runs/<run_id>/` next to the agent file;
42+
pass `--dir <path>` when tracing from elsewhere.
43+
44+
## Branches
45+
46+
| Command | What it does |
47+
|---|---|
48+
| `chidori branches <run-id>` | List a run's persisted branch stores. |
49+
| `chidori branch-resume <run-id> <branch-id> --value "…"` | Answer a paused `input()` inside a branch. |
50+
| `chidori branch-rerun <run-id> <branch-id>` | Re-run a branch's (possibly edited) `source.ts` from its fork-time anchor. |
51+
52+
See [Branching Execution](./branching-execution.md).
53+
54+
## Packages
55+
56+
| Command | What it does |
57+
|---|---|
58+
| `chidori add <pkg>` | Add an npm dependency — content-addressed store, SHA-512 verification, JSONL lockfile, no Node. |
59+
| `chidori install` | Install dependencies from the lockfile. |
60+
| `chidori remove <pkg>` | Remove a dependency. |
61+
62+
See [Package Management](./package-management.md).
63+
64+
## Approval postures
65+
66+
The posture decides what happens when an agent reaches a *powerful* effect —
67+
network access, `chidori.tool` calls, workspace mutations. LLM prompts and
68+
pure compute are never gated.
69+
70+
| Context | Default behavior |
71+
|---|---|
72+
| `chidori run` (interactive) | **Ask**: y/a/N approval at the terminal per gated effect (`a` allows that target for the rest of the run). |
73+
| `chidori run` (no terminal: scripts, CI) | **Fail closed** — pass `--trusted` or configure a policy. |
74+
| `chidori serve` | **Deny by default** (`untrusted` profile) unless `--trusted` or explicit `CHIDORI_POLICY*` configuration; read-only workspace introspection stays allowed. `--untrusted` forces the deny profile over any env configuration. |
75+
76+
Full model: [Running Modes](./running-modes.md) and the
77+
[Sandbox Model](./sandbox-model.md).

0 commit comments

Comments
 (0)