This repository is the reviewed public projection of an internal monorepo, not an ordinary workspace. Every published file is listed in release/public-source.json, and upstream changes arrive through a three-way merge described in docs/source-sync.md. Moving or renaming files therefore has a cost that a normal repository does not have: it shows up as a conflict or an unreviewed new file at the next synchronization. Prefer changing content over changing layout.
packages/— first-party workspace packages.packages/agent-modules/*is a second level of packages, not a package itself.third_party/— vendored upstream packages (pi-mono,sandbox-runtime) with their own licenses. Their test suites are not part of this distribution's verification.release/— machine-read release contracts.extraction.jsonpins the source baseline and package scope,public-source.jsonis the file inventory,dependency-licenses.jsonrecords declared dependency licenses. Build, type-check, test resolution, and source checks all read from here.docs/— human-readable documentation and supporting media.scripts/— build and verification tooling. Shared constants live inscripts/lib/; import them instead of repeating literal paths or lists.test/— repository-level tests andvitest-suites.json, the declaration of every Vitest file this distribution runs.
Do not edit these by hand; regenerate them and commit the result.
| File | Regenerate with | Checked by |
|---|---|---|
release/public-source.json |
node scripts/source-inventory.mjs --write |
pnpm check:source |
tsconfig.standalone.json (the paths block) |
pnpm gen:tsconfig |
pnpm check:tsconfig |
Review added, removed, and renamed files before regenerating the inventory: recording a file does not make it suitable for publication. Content-only edits to existing files do not require inventory regeneration. Keep private review material, verification reports, and temporary artifacts outside the repository; the inventory scans the working tree, including untracked files outside its explicit exclusions.
Use a feature branch and submit a pull request; do not push directly to the default branch. See CONTRIBUTING.md for contribution and review requirements.
Name new branches by the purpose of the change: feat/<short-description> for features, fix/<short-description> for bug fixes, and corresponding prefixes such as docs/, refactor/, test/, or chore/ for other work. Use concise English descriptions in lowercase kebab-case, for example feat/provider-limits or fix/session-restore. Do not use agent or tool names as branch prefixes, including codex/. Follow an explicitly requested branch name when one is provided.
Never merge internal Git history or cherry-pick internal commits into this repository. Follow docs/source-sync.md, keep unreviewed candidates outside the repository, and apply reviewed files individually. Advance release/extraction.json's sourceRevision only after reviewing all differences for the selected source revision.
| Concern | Declared in | Consumed by |
|---|---|---|
| Package scope | release/extraction.json (packageRoots) |
build, type-check paths, Vitest aliases, source check, source sync |
| Package export → source file | each package's exports via scripts/lib/package-exports.mjs |
tsconfig.standalone.json, vitest.oss.config.mjs |
| Vitest files per gate | test/vitest-suites.json |
vitest.oss.config.mjs, scripts/run-vitest-suite.mjs |
| Retired source paths | scripts/lib/retired-sources.mjs |
check:source (must not exist), check:standalone (must not be bundled) |
| Documentation-only classification | scripts/ci-changes.mjs |
source verification, release audit |
| Source archive validation/extraction | scripts/lib/source-archive.mjs |
source export, candidate validation |
Adding a workspace package: add it to pnpm-workspace.yaml and to packageRoots in release/extraction.json, then run pnpm gen:tsconfig and node scripts/source-inventory.mjs --write.
Changing package exports: run pnpm gen:tsconfig after adding or changing an export subpath.
Adding a Vitest file: add its path to the appropriate group in test/vitest-suites.json. Do not hard-code Vitest file paths in package.json scripts or the Vitest config. Repository-level node:test suites remain in their existing gates; add workflow safety and release-tool regressions to test/source-sync.test.mjs.
Adding a verification gate: add a step to scripts/verify.mjs, with platforms when it cannot run everywhere. Do not add steps to the workflow file.
Do not reference internal hosts, generated IDL, or private services; check:source catches known patterns but does not replace publication review. Do not restore paths listed in scripts/lib/retired-sources.mjs or remove supported capabilities to make standalone checks pass. Do not commit account data, sessions, logs, credentials, or real user content; use temporary data directories and synthetic test inputs. Documentation and commit messages are written in English; preserve the required languages of localized product strings and bundled runtime prompts. See CONTRIBUTING.md.
packages/webui is a browser client with its own operating guide. Before changing anything under it,
read packages/webui/AGENTS.md — the layering rules, the gates each kind of change needs, the test
conventions and the fork's branch and issue workflow — and packages/webui/docs/README.md for the
architecture, module map and decision log. Its issue tracker conventions and triage labels are
packages/webui/docs/agents/.
Repository-wide contributor workflows live in .agents/skills/ and are listed in CONTRIBUTING.md.