developer.md

Developer documentation

Useful files to read:

• Top-level README
• Local development instructions (coding, building, deployment, testing)
• Deployment instructions for testnet/mainnet
• Technical architecture
• Trust config is chain-scoped — read before touching trusted-source config or debugging a suspiciously-zero aggregate
• code-level READMEs in each package (hardhat/, sdk/, ui/, etc.)
• specs/tech/subsystems/ for your subsystem

Feedback loops (AKA tests)

• verifier-run automated.lint (or npm run lint) to run various linters and record the result
• verifier-run automated.build (or npm run build) to make sure everything builds and type-checks and record the result
• verifier-run automated.test-fast (or npm run test:fast) to run the fast suite (docs inventory, SDK unit tests, Hardhat tests, integration-test harness unit tests, and UI Vitest; no Docker/indexer/Playwright)
• verifier-run automated.test-full (or npm run test) to run the full suite (takes many minutes!)
• npm run test:seed:implication-regression --workspace=fake-data-generation after editing curated seed statements or proliferation variants. This checks the saved implication-attester decision corpus against the current statement IDs and text. If it fails because statements changed, run npm run gen:seed:implications:verify --workspace=fake-data-generation -- --review-output fake-data-generation/output/seed-implication-review.json to produce the focused packet of only new/changed implication pairs that need human review. See fake-data-generation/README.md.

Note that the build and tests are run by the Git pre-commit hook, and the whole thing takes a few minutes to run, so if you're ready to commit and the only thing left to do is run the build and the tests, it's okay to just attempt to commit and make sure it goes through; no need to run the whole test suite only to have it run again when you commit immediately afterward.

Verifier report / operational health checks

The project has a verifier workspace in /verifier. If asked for a basic project status, run npm run verifier:status: it refreshes the cheap fast validation loop and refreshes root (which both rolls up the dashboard and writes its report.md narrative). For the all-in-one report that also prints the narrative, run npm run verifier:go. If asked for a verifier report, run npm run verifier:report to print the latest stored top-level root dashboard result. If asked to run the verifier in the idempotent/due-only sense, run npm run verifier:run (verifier-scheduler); expensive checks are manual-triggered and will not rerun unless explicitly forced. Cheap liveness/coverage checks are scheduled automatically by that loop. To force a specific check or pass, use verifier-run <checkId> or the npm shortcuts. npm run verifier:fast (alias: verifier:pr) is the fresh fast loop: it reruns the cheap required leaves (lint, build, fast tests, indexer canaries, deterministic AI fixtures) before rolling up validation.pr; use npm run verifier:fast:rollup (alias: verifier:pr:rollup) only when you intentionally want the pure rollup over stored child results. Note that npm run verifier:state is an alias of verifier:root (some docs use one name, some the other). Other useful shortcuts include npm run verifier:functionality, npm run verifier:docs, npm run verifier:product, npm run verifier:security, and npm run verifier:root. If the scheduler is supervised continuously, install an external cron heartbeat using npm run verifier:heartbeat.

The project .envrc sets VERIFIER_WORKSPACE=verifier so --workspace is automatic from the repo root.

Branch structure: See workflow/branching.md. Briefly: work on feature branches; commits directly on dev or master are blocked by hooks. Feature-branch commits run the quick suite, and merges into master are gated by the full suite.

LSP (Language Server Protocol)

This project has LSP infrastructure set up for the pi coding agent (pi-lsp-extension):

• TypeScript — Root tsconfig.json is a single include-based TypeScript program over the package source globs (no root project references and no "composite" convention). The UI package has its own ui/tsconfig*.json split for app/node builds.
• Solidity — @nomicfoundation/solidity-language-server configured in .pi-lsp.json; .sol extension mapping added to pi-lsp-extension's language map.
• .pi-lsp.json configures the Solidity server and enables eager startup for both TypeScript and Solidity.

When adding new workspace packages, add the package to the root package.json workspaces and add its source globs to the root tsconfig.json include list if it should be part of the repo-wide TypeScript feedback loop. When a new language needs LSP support, both the language map (pi-lsp-extension/src/shared/language-map.ts in the global npm install) and .pi-lsp.json may need updating.