docs: canonical root AGENTS.md — workspace map, Definition of Done, conventions

AGENTS.md

@@ -0,0 +1,199 @@
+# AGENTS.md
+
+Standards for anyone — human or coding agent — working in this repository: the
+workspace map, the Definition of Done, and the conventions that keep changes
+consistent.
+
+## What this is (and isn't)
+
+This is the **repo-root contributor/agent standards doc** — how to find your
+way around the Dawn monorepo, what "done" means for a change, and the rules
+that keep the codebase consistent. It's the canonical entrypoint; see
+[Cross-links](#cross-links) for how it relates to `CONTRIBUTING.md` and
+`CONTRIBUTORS.md`.
+
+**This is not** the runtime `workspace/AGENTS.md` capability. Dawn ships a
+built-in capability
+(`packages/core/src/capabilities/built-in/agents-md.ts`) that auto-injects the
+contents of an **app's** `<appRoot>/workspace/AGENTS.md` into that agent's
+system prompt as its persistent "# Memory" — re-read every turn, updated by
+the agent itself via `writeFile`. That's an end-user Dawn app feature,
+documented at [dawnai.org/docs/memory](https://dawnai.org/docs/memory). The
+name collision is real: this file (repo root, for contributors) and that file
+(inside a generated app's `workspace/`, for the agent at runtime) share a
+filename but nothing else. If you're looking for the runtime feature, this
+isn't it.
+
+## Workspace map
+
+Every `packages/*` directory is a pnpm workspace member (verify: `pnpm -r list --depth -1`). One-line purpose is each package's own `README.md` first line.
+
+**Core framework**
+
+| Package | Purpose |
+|---|---|
+| `@dawn-ai/sdk` | The author-facing TypeScript SDK — `agent()`, `defineMiddleware()`, `allow()`/`reject()`, and the type primitives the CLI consumes. |
+| `@dawn-ai/core` | Filesystem-based route discovery, app config loading, state-field resolution, and typegen primitives that the Dawn CLI builds on. |
+| `@dawn-ai/cli` | The `dawn` CLI — local HMR dev runtime, route execution, validation, typegen, and the build step that produces LangSmith deployment artifacts. |
+| `@dawn-ai/langgraph` | LangGraph runtime adapters and route module contracts (`graphAdapter`, `workflowAdapter`, `defineEntry`) used by the CLI. |
+| `@dawn-ai/langchain` | LangChain backend adapters — materializes `chain` routes and provider-aware `agent` routes (tool conversion, streaming, retry). |
+
+**Capabilities & integrations**
+
+| Package | Purpose |
+|---|---|
+| `@dawn-ai/ag-ui` | AG-UI protocol translation for Dawn's local runtime — maps runtime stream chunks to AG-UI events and back, so CopilotKit and other AG-UI clients can drive Dawn agents. |
+| `@dawn-ai/permissions` | Permission and access-control primitives for Dawn agents — gating tool and resource access at runtime. |
+| `@dawn-ai/workspace` | Filesystem-backed workspace utilities for Dawn agents — reading, writing, and managing files in an agent's working directory. |
+| `@dawn-ai/sandbox` | Reference sandbox providers for Dawn workspace execution — a Docker-backed `SandboxProvider` that redirects the workspace filesystem and shell tools into a per-thread isolated environment. |
+| `@dawn-ai/vite-plugin` | Vite plugin for Dawn's typegen pipeline (extracts tool types and generates route ambient declarations). |
+
+**Storage & memory**
+
+| Package | Purpose |
+|---|---|
+| `@dawn-ai/memory` | Deterministic long-term memory storage and recall for Dawn's typed `memory.ts` capability — the storage/ranking layer under `@dawn-ai/core`. |
+| `@dawn-ai/memory-pgvector` | Postgres + pgvector backend for Dawn's typed long-term memory store, for deployments where SQLite is too local (multiple instances, shared DB, HNSW retrieval at scale). |
+| `@dawn-ai/sqlite-storage` | SQLite-backed storage adapter for Dawn — durable persistence for agent state and runtime data. |
+
+**Testing & evals**
+
+| Package | Purpose |
+|---|---|
+| `@dawn-ai/testing` | Testing utilities for Dawn apps — helpers for exercising routes, tools, and agent behavior in unit and scenario tests. |
+| `@dawn-ai/evals` | Evaluation harness for Dawn agents — running and scoring agent behavior against datasets and scenarios. |
+
+**Scaffolding & tooling**
+
+| Package | Purpose |
+|---|---|
+| `create-dawn-ai-app` | Scaffold a new Dawn app — generates a working application from the supported starter templates with Dawn's canonical layout wired for local development. |
+| `@dawn-ai/devkit` | Internal scaffold templates and dev-time tooling shared between `@dawn-ai/cli` and `create-dawn-ai-app`. |
+| `@dawn-ai/config-typescript` | Shared TypeScript compiler configurations (`base`, `library`, `node`, `nextjs`) for Dawn workspace packages. |
+| `@dawn-ai/config-biome` | Shared Biome lint/format configuration used by Dawn workspace packages. |
+
+**Apps**
+
+| Package | Purpose |
+|---|---|
+| `@dawn-ai/web` (`apps/web`) | The documentation website (dawnai.org) and its content/nav. |
+
+**Examples** (`examples/*`, pnpm workspace members; consume Dawn via `workspace:*` and are typechecked in CI)
+
+| Package | Purpose |
+|---|---|
+| `@dawn-example/chat-server` / `@dawn-example/chat-web` (`examples/chat`) | Foundational agent-harness primitives (filesystem + bash) end-to-end, plus planning, skills, subagents, workspace, and HITL permissions, with a disposable smoke-test web client. |
+| `@dawn-example/memory` (`examples/memory/server`) | Long-term memory with a backend-switchable store — zero-setup SQLite by default, Postgres + pgvector via `DATABASE_URL`, hybrid keyword + vector recall via `OPENAI_API_KEY`. |
+| `@dawn-example/research-server` / `@dawn-example/research-web` (`examples/research`) | The flagship deep-research assistant example — routes, tools, subagents, memory, planning, offloading, HITL permissions, and an optional Docker sandbox. |
+
+Note: `examples/chat/package.json` and `examples/research/package.json` are
+orchestration-only (`private: true`, one level above `server`/`web`) and are
+**not** themselves pnpm workspace members — the actual members are the
+`server`/`web` subdirectories, matched by the `examples/*/*` glob in
+`pnpm-workspace.yaml`.
+
+**Charts** (Helm charts under `charts/`, not pnpm workspace members)
+
+| Chart | Purpose |
+|---|---|
+| `charts/dawn-app` | Runs a built Dawn app image (from `langgraphjs dockerfile`) on Kubernetes as a Deployment + Service, with optional Ingress, HorizontalPodAutoscaler, and PodDisruptionBudget, wired to the in-cluster `kubernetesSandbox` orchestrator ServiceAccount. |
+| `charts/dawn-sandbox-infra` | Cluster-side infrastructure for the Dawn `kubernetesSandbox` provider — namespace, least-privilege RBAC, default-deny egress, quotas/limits, Pod Security Standards, and a PVC reaper. |
+
+`test/` and `scripts/` are repo-level (verification lanes and workspace
+scripts respectively) — not workspace packages.
+
+## Definition of Done
+
+The exact gates a change must pass are the `validate` job in
+`.github/workflows/ci.yml`, in order:
+
+1. `pnpm lint`
+2. `pnpm check:build-cache`
+3. `pnpm build`
+4. `pnpm typecheck`
+5. `pnpm test`
+6. `node scripts/check-docs.mjs`
+7. `pnpm pack:check`
+8. `pnpm verify:harness:self-test`
+9. `pnpm verify:harness:framework`
+10. `pnpm verify:harness:runtime`
+11. `pnpm verify:harness:smoke`
+
+On pull requests, a separate `changesets` job also runs
+`node scripts/check-changesets.mjs` to require a changeset for user-facing
+package changes.
+
+Run `pnpm ci:validate` locally to approximate this lane (it exists as a
+script in the root `package.json`). It runs the same lint → build-cache →
+build → typecheck → test → docs-check → pack-check → harness sequence, plus a
+few extra local-only release-script unit tests
+(`test:release-publish`, `test:upload-release-assets`,
+`test:backfill-release-tags`) that aren't separate CI steps.
+
+**Gated lanes** — these run as separate CI jobs behind env flags or dedicated
+infrastructure, not part of `validate`, and aren't required for most PRs:
+`sandbox-docker` (`DAWN_TEST_DOCKER=1`), `pgvector-docker`
+(`DAWN_TEST_PGVECTOR=1`), `sandbox-k8s` (`DAWN_TEST_K8S=1`, kind + Calico),
+`sandbox-k8s-e2e` / `sandbox-docker-e2e` (`DAWN_TEST_SMOKE_E2E=1`, full-arc
+deployed-app smoke), `chart-validate` (Helm lint + kubeconform), and
+`chart-apply-smoke` (kind install smoke).
+
+## Conventions
+
+- **Changesets are a fixed group, patch on 0.x.** All publishable packages
+  release together (`.changeset/config.json`'s `fixed` group). On a 0.x train
+  a `minor` bump takes every package to `1.0.0` — use `patch` unless you
+  intend a real 1.0 release.
+- **`exactOptionalPropertyTypes: true`.** Never assign `{ x: undefined }` to
+  an optional field; use a conditional spread (`...(x !== undefined ? { x } : {})`)
+  instead, or the type checker will reject it.
+- **Never run bare `biome check --write`.** It mass-reformats the whole
+  workspace. Use `pnpm lint` (or `pnpm lint:fix` to auto-fix), or scope Biome
+  to the files you changed.
+- **Import specifiers: `src/` uses `.js`, `test/` uses `.ts`.** This is
+  NodeNext ESM — source files import sibling `src/*.ts` modules with a `.js`
+  extension; test files import with `.ts`. Follow the existing pattern in the
+  package you're editing.
+- **Examples/docs/scaffolds use gpt-5-family models only** (canonical default
+  `gpt-5-mini`; no `gpt-4o`, though it stays in the provider registry,
+  validation tests, and recorded fixtures). This is a project convention, not
+  currently enforced by `scripts/check-docs.mjs` — check it by eye when
+  touching examples.
+- **Branch per PR; pin before dispatching parallel/subagent work.** In a
+  multi-worktree setup, a subagent's commits can land on a detached HEAD
+  tracking the wrong branch if the feature branch isn't checked out first.
+- **Build before running anything against `dist/`.** Packages compile
+  `src/*.ts` to a gitignored `dist/`, and consumers import the built output —
+  a stale or skewed `dist/` (from a branch switch or a per-package filtered
+  build) produces false negatives in ad-hoc scripts. Run `pnpm build` first;
+  see `CONTRIBUTING.md`'s "Build before running anything against `dist/`".
+- **Banned doc phrases.** `scripts/check-docs.mjs` greps `README.md`,
+  `CONTRIBUTING.md`, `CONTRIBUTORS.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`,
+  `apps/web/app`, `apps/web/content`, `docs/` (excluding
+  `docs/superpowers/`), and `packages/` for stale or overstated wording —
+  e.g. the retired `dawn-ai.org` domain, provider-prefixed model ids
+  (`openai:gpt...`), the old `agent.bindTools` / `.dawn/generated` /
+  `auto-bound`/`auto-registered` phrasing, and claims like "byte-identical"
+  or "speaks the LangSmith protocol natively" that overstate local/prod
+  parity. This file (`AGENTS.md`) isn't in that scanned set, but keep it
+  honest anyway — see the `forbiddenContent` list in
+  `scripts/check-docs.mjs` for the exact patterns.
+- **Always run commands from the repo root.** Turbo and workspace-package
+  resolution assume it.
+
+## Where things live
+
+- Docs site content: `apps/web/content/docs/*.mdx` (nav registered in
+  `apps/web/app/components/docs/nav.ts`).
+- Specs, plans, audits, runbooks: `docs/superpowers/`.
+- CI: `.github/workflows/ci.yml`.
+- Changeset config (fixed group, patch-on-0.x): `.changeset/config.json`.
+
+## Cross-links
+
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — the public PR path: setup, issues,
+  PRs, CLA/DCO, code of conduct.
+- [`CONTRIBUTORS.md`](./CONTRIBUTORS.md) — internal monorepo guide: local
+  setup, the `--mode internal` scaffold path, and verification lanes. Its
+  per-package responsibilities point back at the workspace map above.
+- [`README.md`](./README.md) — project overview and quickstart.

CONTRIBUTING.md

@@ -2,6 +2,8 @@
 
 Thanks for helping improve Dawn. This guide covers the public contribution path for issues, pull requests, and package changes. For detailed monorepo layout, package ownership, and verification lanes, see [CONTRIBUTORS.md](./CONTRIBUTORS.md).
 
+Standards, the workspace map, and the Definition of Done for any change live in [AGENTS.md](./AGENTS.md) — read that first.
+
 ## Development Setup
 
 Use Node.js `>=22.12.0` and pnpm `10.33.0`.

CONTRIBUTORS.md

@@ -4,6 +4,8 @@
 
 This guide is for engineers working inside the Dawn monorepo. It covers the current repo layout, package boundaries, local setup, verification commands, and where the living documentation lives.
 
+Canonical standards (workspace map, Definition of Done, and conventions) live in [AGENTS.md](./AGENTS.md); see that first.
+
 ## Repository Layout
 
 - `apps/web` contains the documentation website and user-facing docs pages.
@@ -14,14 +16,11 @@ This guide is for engineers working inside the Dawn monorepo. It covers the curr
 
 ## Package Responsibilities
 
-- `@dawn-ai/core` owns app discovery, config loading, validation, and route type generation.
-- `@dawn-ai/sdk` owns the author-facing contract: types, helpers, runtime context, middleware, and tool authoring.
-- `@dawn-ai/langgraph` owns LangGraph-specific route module contracts and adapter code.
-- `@dawn-ai/langchain` owns LCEL chain support and provider-aware `agent()` materialization.
-- `@dawn-ai/cli` owns the user-facing commands and the local runtime behavior.
-- `create-dawn-ai-app` owns app scaffolding.
-- `@dawn-ai/devkit` owns shared template and file-generation helpers.
-- `@dawn-ai/config-typescript` and `@dawn-ai/config-biome` own the shared workspace configuration packages.
+See the [workspace map in AGENTS.md](./AGENTS.md#workspace-map) for the full,
+current list of all 19 `packages/*` plus apps, examples, and charts — this
+section used to duplicate a partial list and drifted out of date. Keep the
+map in `AGENTS.md` current when a package is added or its scope changes;
+don't re-list packages here.
 
 ## Local Setup
 

README.md

@@ -190,7 +190,7 @@ The built-in `agent()` route materializes to a LangChain chat model. Dawn infers
 
 ---
 
-Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Repo layout and dev commands in [CONTRIBUTORS.md](./CONTRIBUTORS.md). Security: [SECURITY.md](./SECURITY.md). Please follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
+Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Repo layout and dev commands in [CONTRIBUTORS.md](./CONTRIBUTORS.md). Standards, workspace map, and Definition of Done in [AGENTS.md](./AGENTS.md). Security: [SECURITY.md](./SECURITY.md). Please follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
 
 ## License
 

docs/superpowers/plans/2026-07-12-agents-md.md

@@ -0,0 +1,69 @@
+# Root `AGENTS.md` — implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax.
+
+**Goal:** A canonical repo-root `AGENTS.md` — workspace map + Definition of Done + first-class conventions — cross-linked from README/CONTRIBUTING/CONTRIBUTORS.
+
+**Architecture:** A single markdown file at repo root plus three one-line cross-links. Pure docs, zero runtime risk.
+
+**Spec:** `docs/superpowers/specs/2026-07-12-agents-md-design.md`
+
+---
+
+## Task 1: Write `AGENTS.md`
+
+**Files:**
+- Create: `AGENTS.md` (repo root)
+
+- [ ] **Step 1: Write the file** with these sections (content from the spec; verify every fact against the repo as you write):
+
+  1. **"What this is (and isn't)"** — one paragraph: repo-root contributor/agent standards. Explicit callout that this is NOT the runtime `workspace/AGENTS.md` agent-memory capability (`packages/core/src/capabilities/built-in/agents-md.ts`), which injects an *app's* `workspace/AGENTS.md` into the agent prompt — link `/docs/sandbox` or the capabilities docs for that.
+  2. **Workspace map** — grouped table `package → one-line purpose`. Generate the list by reading each `packages/*/package.json` name + the first line of each `packages/*/README.md` (do not trust the spec's list blindly — re-derive so it's current). Groups: Core framework / Capabilities & integrations / Storage & memory / Testing & evals / Scaffolding & tooling / Apps / Examples / Charts. Note `test/` + `scripts/` are repo-level, not packages.
+  3. **Definition of Done** — the exact gates from `.github/workflows/ci.yml` `validate` job (read it, list the step `run:` commands in order: `pnpm lint`, `pnpm check:build-cache`, `pnpm build`, `pnpm typecheck`, `pnpm test`, `node scripts/check-docs.mjs`, `pnpm pack:check`, `pnpm verify:harness:self-test`, `verify:harness:framework`, `verify:harness:runtime`, `verify:harness:smoke`) + the `changesets` gate. Mention the gated lanes (`sandbox-docker`, `pgvector-docker`, `sandbox-k8s`, `sandbox-{docker,k8s}-e2e`, `chart-validate`, `chart-apply-smoke`) run behind env flags. State: `pnpm ci:validate` approximates the DoD locally (confirm this script exists in root `package.json`).
+  4. **Conventions** — each a rule + one-line why: fixed-group changesets → `patch` on 0.x (a `minor` bumps all to 1.0.0); `exactOptionalPropertyTypes` → conditional-spread optionals; never bare `biome check --write` (use `pnpm lint`); `src`→`.js` / `test`→`.ts` import specifiers (NodeNext); `model:` examples must be gpt-5 family (`check-docs.mjs` enforces); branch-per-PR + pin the branch before dispatching parallel agents; build before running against `dist/` (link `CONTRIBUTING.md`); banned doc phrases (`check-docs.mjs`); run commands from repo root.
+  5. **Where things live** — docs site (`apps/web/content/docs/*.mdx`), specs/plans (`docs/superpowers/`), CI (`.github/workflows/ci.yml`), changeset config (`.changeset/config.json`).
+  6. **See also** — links to `CONTRIBUTING.md`, `CONTRIBUTORS.md`, `README.md`.
+
+  No banned phrases (mirror the `check-docs.mjs` ban list even though AGENTS.md isn't scanned — keep it honest). Any `model:` mention → gpt-5 family.
+
+- [ ] **Step 2: Verify facts**
+
+  Run and reconcile the doc against reality:
+  - `ls packages` and `for d in packages/*; do node -e "console.log(require('./$d/package.json').name)"; done` — every package appears in the map.
+  - `grep -nE "run:" .github/workflows/ci.yml` under the `validate:` job — every gate is listed.
+  - Confirm `ci:validate` in root `package.json`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add AGENTS.md
+git commit -m "docs: canonical root AGENTS.md — workspace map, Definition of Done, conventions"
+```
+
+---
+
+## Task 2: Cross-links
+
+**Files:**
+- Modify: `README.md`, `CONTRIBUTING.md`, `CONTRIBUTORS.md`
+
+- [ ] **Step 1:** Add a one-line link to `AGENTS.md` as the canonical standards entrypoint near the top of each:
+  - `README.md` — in the contributing/dev section (find where it points at CONTRIBUTING).
+  - `CONTRIBUTING.md` — a line under the intro: standards + workspace map live in `AGENTS.md`.
+  - `CONTRIBUTORS.md` — point its per-package responsibilities at the `AGENTS.md` workspace map (so the two lists don't diverge); keep its scaffold-internal/local-setup content.
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add README.md CONTRIBUTING.md CONTRIBUTORS.md
+git commit -m "docs: link AGENTS.md as the canonical standards entrypoint"
+```
+
+---
+
+## Task 3: Verify + PR
+
+- [ ] **Step 1:** `node scripts/check-docs.mjs` → must PASS (AGENTS.md is not under `apps/web/content/docs`, so it should not need nav registration — confirm no failure). Run `pnpm lint` (a root markdown file shouldn't trip Biome, but confirm).
+- [ ] **Step 2:** Rebase on `origin/main`, push branch, open PR. No changeset (no `packages/**` change). Watch `validate` + advisory review; address findings.
+
+**Notes for executor:** Branch is its own (e.g. `docs/agents-md`); pin before any subagent dispatch. This is docs-only — no TDD tests, but every claim must be verified against the live repo (that's the "test").