Add actionable roadmap and agent guidance

AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md
+
+This repository is `geth`, a Rust monorepo for a personal, local-first,
+Iroh-based mesh runtime. It is not the Ethereum geth client.
+
+`geth` has one executable only:
+
+- daemon mode: `geth daemon run`
+- control mode: `geth status`, `geth node ...`, `geth cas ...`, etc.
+
+Do not add separate `gethd` or `gethctl` binaries.
+
+## Core Invariants
+
+- All remote geth node-to-node communication must be over Iroh.
+- SSH is not a geth transport and must not become a fallback transport.
+- SSH keys are admin trust anchors and ecosystem integration points.
+- SSH certificate flows and SSH proxying are geth-managed workflows carried by
+  local control now and Iroh later.
+- The daemon owns the Iroh endpoint, local identity, local metadata store,
+  resource registry, module routing, and synchronized data structures.
+- Discovery is untrusted and never grants capabilities or trust.
+- Authorization is resource-scoped and capability-based.
+- Signed data must use deterministic canonical encoding, not arbitrary JSON.
+- Bearer secrets may grant resource-specific access but must not create trusted
+  node identity or trust graph mutation rights.
+
+## Workspace Shape
+
+- Binary crate: `crates/geth`
+- CLI definitions and formatting: `crates/geth-cli`
+- Daemon orchestration and local control: `crates/geth-node`
+- Local JSONL control protocol: `crates/geth-control`
+- Shared newtypes: `crates/geth-types`
+- Canonical encoding/hash helpers: `crates/geth-codec`
+- Config/path handling: `crates/geth-config`
+- Local SQLite metadata store: `crates/geth-store`
+- Local CAS: `crates/geth-cas`
+- SSH trust/cert models: `crates/geth-ssh-identity`
+
+Keep crates focused. Do not create a `geth-common` crate.
+
+## Implementation Rules
+
+- Prefer existing crate boundaries and patterns.
+- Libraries should use `thiserror`; binaries may use `anyhow`.
+- Keep async only where it is useful.
+- Treat network and control inputs as untrusted.
+- Do not implement complex cryptographic protocols casually. Add types,
+  roadmap notes, and explicit non-claims when a feature is only scaffolded.
+- Do not claim Keyhive/BeeKEM-level security properties until they are actually
+  designed, implemented, and tested.
+- User service installation must target user service managers, not system
+  service managers.
+
+## Testing Requirements
+
+Every behavior change should include tests proportional to risk:
+
+- Add unit tests for pure data models, reducers, encoders, path generation, and
+  command builders.
+- Add integration tests for CLI/daemon behavior when practical.
+- Use temp directories and temp `GETH_HOME` values.
+- Avoid tests that require privileged services, real YubiKeys, real network
+  relays, or host service-manager mutation.
+- For platform-specific behavior, use generated-definition tests or cfg guards.
+
+Before finishing a code change, run at least:
+
+```sh
+cargo fmt --all -- --check
+cargo check --workspace --all-targets
+cargo test --workspace
+```
+
+Also run clippy when reasonable:
+
+```sh
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+If a command cannot be run, state why in the final report.
+
+## Documentation And Roadmap
+
+Keep documentation updated with behavior changes:
+
+- Update `README.md` for user-visible commands or workflows.
+- Update `docs/architecture.md` for architectural boundaries or invariants.
+- Add or update ADRs in `docs/adr/` for durable decisions.
+- Update `docs/roadmap.md` whenever a feature is added, completed, split, or
+  deferred.
+
+Roadmap items should be actionable and checkable:
+
+- Use `[ ]`, `[~]`, or `[x]`.
+- Include acceptance criteria.
+- Split vague items before implementation.
+- Do not mark an item done unless the acceptance criteria are met or revised
+  honestly.
+
+## Current Feature Boundaries
+
+- Local daemon, local control socket, local identity, local store, local CAS,
+  SSH certificate metadata, revocation metadata, and user service definitions
+  exist.
+- Iroh, cr-sqlite, iroh-docs, iroh-gossip, iroh-blobs, Automerge sync, real auth
+  enforcement, OpenSSH KRL generation, and Keyhive/BeeKEM-style authorization are
+  future roadmap items unless implemented later.