AGENTS.md - mdk

Repository-level rules and routing for coding agents. README.md is the human overview (what each crate is, how the layers fit); don't duplicate it here.

The canonical protocol specification lives in github.com/marmot-protocol/marmot. This repo owns the Rust implementation, its architecture notes, conformance fixtures, formal models, and diagnostics.

Nested AGENTS.md files add rules for their subtree. Read the nearest one before editing.

MDK and host-app ownership

MDK owns shared product logic and authoritative state; White Noise Android is a minimal display and Android platform layer. Follow the host-app boundary before adding behavior or bindings.

Where to go

Landing changes

Every change reaches master through the merge queue; nobody pushes to master or bypasses the queue. Verification and review happen locally, the PR carries the change, and the queue runs the full CI matrix on the exact commit that lands. Follow .agents/skills/land-change: targeted tests plus the end-to-end smoke, two independent cross-model reviews of the local diff (.agents/skills/review-local) until both recommend merge, a short PR, enqueue as soon as the pre-check passes, and own the queue result until the change merges.

Documentation

• README.md files are for humans: what it is, how to use it, where to go next. AGENTS.md files are for agents: boundaries, invariants, code map, editing rules, verification. Keep agent directives out of READMEs and tutorials out of AGENTS.md; link instead of duplicating.
• When you add, rename, or remove a crate, binary, just recipe, or user-facing command, update the root README.md crate map and the affected crate README in the same change.
• Do not add CLAUDE.md files or CLAUDE.md symlinks; AGENTS.md is the single agent-instruction file.
• Shared agent skills live in .agents/skills/<name>/SKILL.md, which Codex and Cursor read. Claude Code reads only .claude/skills, so that path is a symlink to ../.agents/skills; keep it, and add skills to .agents/skills only.

Invariants

• Keep the engine generic over S: cgka_traits::StorageProvider.
• Keep transport-specific code out of crates/cgka-engine, crates/traits, and storage crates.
• Keep SQLite persistence one database per Marmot account-device identity.
• Keep Tamarin model names, Rust test names, and vector names easy to grep across layers.
• Keep protocol principles and app-component documents implementation-neutral in marmot-protocol/marmot. Local engine, storage, queue, and diagnostic notes belong in architecture docs or crate docs here.
• Keep MLS group ids distinct from transport routing ids. GroupId is opaque MLS group id bytes; OpenMLS-generated ids are 16 bytes today, but spec surfaces that bind raw MLS group ids length-prefix them because they are variable-length. nostr_group_id / transport_group_id is the 32-byte Nostr routing handle. Do not apply the 32-byte Nostr route-id rule to GroupId validation, FFI parsing, storage lookups, or CLI/app group-id filters.
• Keep tracing/logging privacy-safe: explicit crate/module target and method fields, aggregate values only, and no account ids, group ids, message ids, relay URLs, pubkeys, payloads, ciphertext, plaintext, or key material. See docs/marmot-architecture/overview/observability.md.
• Create local files, sockets, and databases restrictive-by-construction via crates/fs-private (or equivalent posture with an on-disk mode test), and release their file locks explicitly before a host suspends (MarmotAppRuntime::shutdown_and_close); see docs/marmot-architecture/overview/local-artifact-safety.md.
• Route every outbound connection through the host-safety dial discipline: validate each resolved address with cgka_traits::app_components::reject_non_public_ip, pin the validated address, choose TLS trust from config (never a resolved IP), apply a connect timeout, and gate loopback behind an explicit dev flag. See docs/marmot-architecture/overview/dial-safety.md.
• Never dial or adopt hosts on the centralized retired-relay denylist. Retired relays must not be used for discovery, bootstrap, examples, or runtime traffic; keep exact endpoint literals confined to the denylist and rejection regression tests.
• Keep multi-step state changes torn-write-free: validate before mutating, compensate every applied step on the error path, record intent before external side effects, and never confirm work that reached no one. See docs/marmot-architecture/overview/multi-step-state-changes.md.
• Treat workspace and conformance-fixture version bumps as manual release operations. Never change the root workspace version, workspace package versions in Cargo.lock, or vector conformance_version values during feature, fix, binding, or review-feedback work unless the user explicitly requests that version bump. The post-release move of master to the next X.Y.0-dev is one of those release operations; see release.md#development-versions.
• Keep binding READMEs and complete method references current with API changes; run just binding-docs-gate. Starting with 0.10.2, every release requires concise docs/release/<version>.md notes and a detailed docs/integration/<version>.md companion, indexed and linked both ways. Follow release.md#release-documentation: distinguish required changes, new defaults, optional adoption and automatic fixes; preserve supported lower-level APIs and exact artifact provenance. Post-tag documentation uses a supplement commit, never a moved release tag.
• Title GitHub Releases with the version first so release lists group by cohort: whole-workspace v<version> - MDK, WN Agent v<version> - wn-agent, and MarmotKit v<version> - MarmotKit.
• Prefer just release-all <version> for a full MDK/WN Agent/MarmotKit cohort release, or just release-all-draft <version> when releases should stay draft for manual publication.
• Sign every commit before pushing. This repository accepts only cryptographically signed commits; configure Git SSH signing (or another accepted signing method) and verify the signature locally.

Verification

GitHub CI is the full gate. Local verification proves your change and stays scoped to it: several agents usually build on the same machine, so workspace-wide builds and suites run locally only when a rule below calls for one. By default, CI runs a pre-check of a few minutes on a PR: fmt, the static gates (including the tracing audit), cargo audit, clippy (default and --all-features), the WASM build, and the workspace tests with the precheck nextest profile. That profile stops each test after half a second and counts it as passed, so it catches only a test that fails quickly; unless the PR carries ci:full, your local tests are the only signal from the slower tests before the merge queue. The merge queue runs the whole matrix (every crate's tests, the simulator, and the C, iOS and Windows lanes) and is the merge gate; the ci:full label runs that matrix on a PR, ci:apple adds only the iOS lane. Master pushes only refresh CI's Rust caches, and only when a dependency or toolchain input changes.

While iterating, run only the test you are working on. Before each push, run once:

cargo fmt --all
cargo clippy -p <crate> --all-targets --all-features --locked -- -D warnings   # each crate you changed
cargo nextest run -p <crate> -E 'test(<area>)'                                 # tests covering the change

• Take test scope and required features from the nearest AGENTS.md Verification section. Run the tests you added or edited plus the test binary or module covering the code you changed; run a whole crate's suite only when the change is crate-wide.
• Run the just gates the nearest AGENTS.md names for the files you touched. Outside crates: .github/workflows/ and CI scripts → just ci-path-classifier-gate; installers and install docs → just agent-install-docs-gate and just install-example-sha256-gate; new or renamed paths → just naming-gate.
• When CI fails, reproduce the failing test by name (cargo nextest run -p <crate> -E 'test(=<name>)') instead of rerunning a suite or the whole gate.

Widen only for these changes:

• A pub item other crates use (type, field, enum variant, trait, signature, feature): run CI's lint once, cargo clippy --workspace --all-targets --all-features --locked -- -D warnings. It compiles every dependent and the feature-gated test targets (test-crash-hooks, test-policy-overrides) that default builds skip. Test only the dependents whose behavior you changed.
• Shared build inputs (Cargo.toml, Cargo.lock, rust-toolchain.toml, .cargo/, Justfile, vendor/) or .github/workflows/: just fast-ci once.
• Convergence, delivery, branch-selection, or multi-client behavior: just simulator-smoke (the merge-queue lane selection).
• Formal model: just tamarin.

Do not run just ci, just test, cargo test --workspace, --features conformance-slow, benchmarks, or the convergence lanes locally unless the user asks; they duplicate CI. just fast-ci is fmt, the static gates, and CI's two workspace clippy passes, so it is not a per-push default.

Exception: for an initial cohort-release PR limited to version fields, workspace package versions in Cargo.lock, vector conformance_version values, changelogs, release/integration documentation, README/install version pins, and other release metadata, run only just release-pr-preflight <version>, then open the PR and let GitHub CI provide the compile/test signal. Do not run just fast-ci, just test, just ci, Tamarin, benchmarks, binding bundle builds, or artifact builds before opening that PR. If preparing the release exposes an implementation or workflow defect, fix it in a separate PR with the normal targeted verification instead of expanding the metadata PR. After the metadata PR is merged and required CI succeeds, run just release-all <version> to build and publish the cohort.

The install-example gate renders all six installer --help surfaces and checks release guidance plus workflow-generated notes for download, sibling .sha256 verification (shasum or sha256sum), then local execution. It also rejects new download-to-shell examples in tracked Markdown, shell, and workflow files.