From 4e23f5ea9912f5caa94be0765a08e8ceecca3cfd Mon Sep 17 00:00:00 2001 From: Jason Park Date: Mon, 14 Sep 2026 06:28:24 +0000 Subject: [PATCH] docs: add repository agent instructions --- AGENTS.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e3d71e0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,104 @@ +# Repository Instructions + +These instructions apply to the entire MinaGuard monorepo. + +## Repository workflow + +- Use Bun for dependency management and workspace orchestration. Preserve `bun.lock`. +- Run checked-in scripts as written, including intentional uses of `node`, `npx`, + `bunx`, or other runtimes. Do not mechanically replace them with Bun without + verifying compatibility and updating CI where needed. +- Build contracts before packages that consume their output. +- Keep changes focused. Preserve unrelated tracked changes and untracked files; + do not clean up or rewrite adjacent work without a task-related reason. +- Do not edit or commit generated build output, release binaries, compilation + caches, or vendored/submodule contents unless the task explicitly requires it. + Update the `ui/deps/o1js` submodule pointer deliberately. + +## Security and secrets + +- Never expose private keys, tokens, passwords, or complete secret environment + values. Do not commit `.env` files or place credentials in fixtures, logs, + screenshots, bundles, or documentation. +- Treat frontend integrity and deceptive signing as security-critical. Contract + safety alone does not make a compromised UI safe. +- Do not weaken fail-closed validation, signer confirmation, network-domain + separation, proposal/contract binding, or key-isolation guarantees. +- `SKIP_PROOFS`, dummy proofs, and test keys are test-only mechanisms. They are + not evidence that production proving or signing works. + +## Online and offline signing + +- Treat online and offline signing as one versioned protocol. The online UI + exports a request bundle; the offline CLI independently summarizes, validates, + builds, proves, and signs it; the online UI validates and broadcasts the signed + response. +- Review every signing-related change across all affected surfaces, including + `contracts/`, `ui/`, `offline-cli/`, `backend/`, `desktop/`, E2E tests, and + release packaging. Do not ship one side of the online/offline flow without the + corresponding updates to the other side. +- Keep transaction types, proposal construction and hashing, signed fields, + network domains, memos, fees, nonces, validation, supported operations, and + human-readable summaries synchronized across every relevant surface. +- Treat offline request and response JSON as a compatibility boundary. Preserve + compatibility or deliberately bump the format version, update producers and + consumers together, test rejection of incompatible files, and document the + migration. +- Preserve the offline-signing invariants documented in + `docs/offline-audit-guide.md`: private keys stay offline; the summary and human + confirmation occur before signing; stdout remains pure signed-response JSON; + network mismatches fail closed; and imported responses remain bound to the + expected vault and proposal. + +## Cross-package consistency + +- Changes under `contracts/src/` or to o1js must verify both testnet and mainnet + verification-key hashes. Update `contracts/.vk-hash` when the circuit changes. +- Contract and protocol changes must be reflected in the UI worker, offline CLI, + backend event decoding and types, desktop packaging, and applicable tests. +- Backend data-model changes must keep `backend/prisma/schema.prisma` and + `backend/prisma/schema.sqlite.prisma` synchronized and include the appropriate + migration. Run the schema-sync check. +- Remember that the desktop application packages the UI and a SQLite-backed + backend; relevant UI, runtime-configuration, schema, and signing changes must + be validated there as well. + +## Documentation + +- For every code change, review and update the relevant README files and + `docs/*-audit-guide.md` files in the same change. Keep cross-referenced guides, + especially `docs/ui-audit-guide.md` and `docs/offline-audit-guide.md`, + synchronized. +- If reviewed documentation does not require an edit, state which guides were + reviewed and why no update was needed in the final handoff. +- Treat implementation and tests as the source of truth. Revalidate live + deployment, hosting, firewall, and CI-runner state before making current-state + claims in documentation or reports. + +## Validation + +- Run focused tests for every changed surface and add cross-surface or E2E tests + when a shared protocol or user flow changes. Report exactly what ran and what + was skipped. +- Circuit or proving changes require an appropriate real-proof test in addition + to fast tests that use `SKIP_PROOFS`. +- Use the repository's canonical checks where applicable: + - `bun run --filter contracts typecheck` + - `bun run --filter contracts test` + - `bun run --filter backend build` + - `bun run --filter backend prisma:check-schema-sync` + - `cd backend && bun test src/tests/` + - `cd offline-cli && bun test` + - `bun run --filter ui build` + - `bun run test:ui` + - `bun run test:e2e` + +## Operations + +- Do not deploy, publish releases, reset databases, stop shared containers, + operate preview stacks, or mutate production infrastructure unless the user + explicitly requests that action. +- Treat deployment state as time-sensitive. Inspect the relevant workflows, + deployment scripts, and live controls before asserting what is active. +- Some development helpers intentionally stop colliding containers or reset + local state. Read them first and confirm their scope before running them.