feat: prepare agen crates for publication

crates/agen/docs/architecture.md

@@ -0,0 +1,62 @@
+# agen architecture
+
+`agen` separates orchestration, event projection, and provider transport so applications can replace an LLM client without changing the turn loop or tool model.
+
+```text
+┌────────────────────────────────────────────┐
+│ Engine                                     │
+│ turn loop · interceptors · tool execution  │
+│ typed state: Mutable → Locked → Mutable    │
+└─────────────────────┬──────────────────────┘
+                      │
+┌─────────────────────▼──────────────────────┐
+│ Timeline                                   │
+│ event dispatch · block collectors          │
+└─────────────────────┬──────────────────────┘
+                      │
+┌─────────────────────▼──────────────────────┐
+│ LlmClient                                  │
+│ transport · provider wire-format schemes   │
+└────────────────────────────────────────────┘
+```
+
+## Main modules
+
+| Module | Responsibility |
+|---|---|
+| `engine` | Turn execution, pause/resume, retries, tool integration, and callbacks |
+| `state` | Sealed `Mutable` and `Locked` type-state markers |
+| `interceptor` | Application-owned control decisions at orchestration boundaries |
+| `tool` / `tool_server` | Tool metadata, registration, execution, and bounded output |
+| `timeline` | Streaming event dispatch, handlers, and block assembly |
+| `llm_client` | Provider-neutral request, response, auth, transport, and scheme contracts |
+| `providers` | Optional higher-level provider adapters such as the `codex` feature |
+| `prune` / `token_counter` | Cache-aware history reduction and token estimation |
+| `usage_record` | Request and token usage accounting |
+
+## Request flow
+
+```text
+Engine history
+  → provider-neutral Request
+    → Scheme::build_request
+      → Provider transport
+```
+
+## Response flow
+
+```text
+streaming response bytes
+  → Scheme event parsing
+    → unified Event values
+      → Timeline handlers and collectors
+        → Engine history/tool decisions
+```
+
+## Type state and cache protection
+
+`Engine<C, Mutable>` permits configuration and history editing. `Engine::run` or `Engine::lock` commits the current prefix and produces `Engine<C, Locked>`. The locked engine may append turns without mutating the committed prefix. `Engine::unlock` explicitly returns to mutable state when an application accepts losing that cache guarantee.
+
+## Public surface
+
+The 0.2 series exposes the low-level client, timeline, tool, pruning, and usage modules because custom clients and orchestration hosts build directly on them. These APIs are intentionally provider-neutral but remain pre-1.0 and may change in later minor releases.

crates/agen/docs/requirements.md

@@ -0,0 +1,39 @@
+# agen requirements
+
+## R1: Turn execution and continuation
+
+- `Engine::run` starts a turn and loops through provider output and tool calls.
+- An `Interceptor` may continue, cancel, or pause work at defined orchestration boundaries.
+- `Engine::resume` continues paused generation without fabricating another user message.
+- Cancellation and provider errors are represented as typed `EngineError` values.
+
+## R2: Explicit cache-preserving state
+
+- `Engine<C, Mutable>` permits configuration and history edits.
+- `Engine::run` or `Engine::lock` transitions to `Engine<C, Locked>` and records the committed prefix.
+- A locked engine appends turns but cannot mutate that prefix through mutable-only APIs.
+- `Engine::unlock` explicitly abandons the lock before configuration or history changes.
+
+## R3: Tool declarations and execution
+
+- `#[tool_registry]` generates a schema and `Tool` implementation for methods marked `#[tool]`.
+- `#[description = "..."]` supplies argument descriptions in generated JSON Schema.
+- Generated code resolves its runtime and helper dependencies through `::agen`.
+- Invalid and duplicate marker attributes produce compile errors rather than panics.
+- Tools execute through `ToolServer` with typed context, errors, and output limits.
+
+## R4: Provider-neutral orchestration
+
+- `LlmClient` is the boundary between the engine and provider-specific transport.
+- Request/response schemes translate provider wire formats into shared request and event types.
+- Interceptors, tool execution, timeline collection, and pruning stay above the provider transport.
+- Provider-specific capabilities are optional features when they require additional policy or dependencies.
+
+## R5: Publication quality
+
+- crates.io metadata includes license, repository, documentation, README, categories, keywords, and MSRV.
+- The default feature set and each optional feature compile and test independently.
+- Macro expansion compiles in a downstream-style integration test without direct helper dependencies.
+- rustdoc builds without dependency documentation.
+- Package contents are explicitly bounded and exclude credentialed fixture-recording utilities.
+- `cargo package` and `cargo publish --dry-run` are run for `agen-macros` before `agen` because the main package depends on its companion package.