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) |
| Verification pipeline | scripts/verify.mjs |
GitHub CI, pnpm verify |
| 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.
pnpm verify runs the same gates as CI in the same order; pnpm verify --list shows which apply on the current platform. Run it before opening a pull request. Individual gates such as pnpm typecheck, pnpm build, and pnpm test:byok remain available for iteration.
The full profile is the local default. platform omits only duplicate type checking. Use pnpm verify --profile docs only when every changed path qualifies under scripts/ci-changes.mjs; it runs source inventory, generated-path, source-export, and release-tool checks. AGENTS.md, bundled runtime prompts, and release/ changes do not qualify for that profile. archive skips Git export for source archives; the candidate workflow authenticates the archive before invoking it. Keep profile selection in the shared verifier.
Source export reads committed HEAD and rejects uncommitted tracked changes. During editing, run the relevant individual gates; run the complete applicable profile on the reviewed commit with a clean tracked working tree before opening a PR. Report the checks actually run and any blocked or untested boundaries. Offline tests do not establish live-service or cross-platform acceptance.
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.