# AGENTS.md
## How To Use The Docs
Do not treat this file as the architecture. It is the entry point.
Before changing an area, read the relevant source record:
- Editor architecture and ownership: `docs/arch.md`
- Active target state and known gaps: `docs/target_arch.md`
- Authority model: `docs/authority.md`
- Plugin runtime: `docs/plugins/runtime.md`
- Plugin security: `docs/plugins/security.md`
- Plugin tests and capability checklist: `docs/plugins/testing.md`
- Supply-chain and Wasm loading policy: `docs/supply-chain.md`
Update docs only when the change affects a durable decision, compatibility
surface, security boundary, or active plan. Avoid restating docs in progress
notes; link to the source record and record only what changed.
## Standing Engineering Rules
Work in coherent, reviewable slices. Prefer the repo's existing patterns and
local helper APIs. Preserve public contracts and compatibility surfaces unless
the active plan explicitly changes them.
Keep editor semantics in pure Rust modules first. Use ECS as typed
orchestration, and keep authoritative mutation at owner boundaries.
For plugins, assume untrusted guests and default-deny authority. New
capabilities must be named, documented, tested, redacted, and owner-mediated
before becoming runtime behavior.
Prefer concrete Rust types that own invariants. Add traits, shared ownership,
locking, spawned tasks, or erased errors only when the boundary actually calls
for them.
## Verification
Run the narrowest meaningful tests after each slice, then the broadest practical
check for the touched area before finishing. The default broad gate is:
```sh
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
```
Use focused commands when they are the right slice check, but report exactly
what ran.
## Helen Elenchus Workflow
At a real boundary, choose a Conventional Commit subject line and pass it to the
Helen elenchus command:
```sh
helen elenchus "<type>(<scope>): <imperative subject>"
```
Examples:
```sh
helen elenchus "refactor(plugin): Preserve intent queue attribution"
helen elenchus "fix(editor): Reject stale selection anchors"
helen elenchus "test(plugin): Cover denied capability diagnostics"
```
Use the same subject line you want in git history. Include a Conventional
Commit type such as `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, or
`perf`; include a scope when it clarifies the touched area.
Helen is the external verification, review, and commit boundary for this repo.
If it fails, stop and summarize the failure and recommended next step. Do not
work around the gate.
Keep the commit subject quoted. In `zsh`, an unquoted subject like
`fix(editor): Reject stale selection anchors` can fail because of the
parentheses.