Architecture and decisions

This directory has two layers: decision docs (how agents-cli works and which choices must survive a refactor) and guides (how-to references for each subsystem). Use agents <group> --help or the generated command index for exact syntax, and the product README for onboarding.

Read the decision docs in this order:

1. Architecture — ownership and process boundaries.
2. Concepts — the domain model and vocabulary.
3. Resources and execution — inputs and the one launch path.
4. Sessions, fleet, and orchestration.
5. Automation, interfaces, and secrets.
6. Observability, share, distribution, behavioral specifications, and benchmarks (measured numbers; not Linear).

Decision docs contain boundaries, owners, data flow, state transitions, invariants, failure behavior, and accepted tradeoffs — not walkthroughs or recipes.

Guides (how-to)

Subsystem references, complementary to the decision docs above. Restored after an over-aggressive docs sweep removed them (2026-08-25); kept concise.

• Execution & fleet: ssh-transport, hosts, version-management, resource-sync, self-healing
• Tools: browser, computer, pty
• Orchestration: teams, routines, monitors, cloud
• Resources: hooks, subagents, plugins, profiles (+ profiles/)
• State & security: secrets-agent-process-model, secrets-trust-boundaries, credential-management, projects, watchdog, menubar, terminal-engine

command-index.md, command-index.json, and command-reference.html are generated from the Commander tree. Never edit them by hand.