Build complete agentctl documentation system

.github/workflows/ci.yml

@@ -55,6 +55,9 @@ jobs:
       - name: Run deterministic verification gate
         run: cargo xtask verify
 
+      - name: Verify canonical documentation and examples
+        run: cargo xtask docs-verify
+
       - name: Run credential-free acceptance gate
         run: cargo xtask acceptance
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,17 @@
+# Code of conduct
+
+## Our standard
+
+Contributors and maintainers must keep project spaces respectful, professional, and focused on the work. Welcome questions asked in good faith. Give specific technical feedback without personal attacks. Respect privacy, identity, background, experience level, and accessibility needs.
+
+Unacceptable behavior includes harassment, discrimination, threats, sexualized attention, doxxing, deliberate intimidation, sustained disruption, or publishing another person's private information without permission.
+
+## Scope
+
+This standard applies in repository discussions, reviews, issues, project chat, events, and public representation of the project.
+
+## Reporting
+
+Report conduct concerns privately to the repository owners through a private channel available on their GitHub organization profile. Do not use a public issue when disclosure could harm someone. Project owners will review available evidence, limit distribution, and choose a proportionate response. This document does not promise a response deadline.
+
+For security vulnerabilities, follow [SECURITY.md](SECURITY.md) instead.

README.md

@@ -68,7 +68,7 @@ CI uses the scripted fake provider. Native, mock-tested adapters cover OpenAI Re
 - `crates/agentctl-cli`: production CLI
 - `xtask`: generated artifacts and canonical verification
 
-Start with [Product](docs/PRODUCT.md), [Architecture](docs/ARCHITECTURE.md), [DSL](docs/DSL.md), [Operations](docs/OPERATIONS.md), [Container contract](docs/CONTAINER.md), [Release process](docs/RELEASE_PROCESS.md), [Limitations](docs/LIMITATIONS.md), [Security](docs/SECURITY.md), and the [generated CLI reference](docs/generated/CLI.md). Run the release-readiness layers with:
+Start with [Getting started](docs/guides/GETTING_STARTED.md), [Product](docs/PRODUCT.md), [Architecture](docs/ARCHITECTURE.md), [DSL](docs/DSL.md), [Operations](docs/OPERATIONS.md), [Container contract](docs/CONTAINER.md), [Troubleshooting](docs/guides/TROUBLESHOOTING.md), [Contributing](docs/CONTRIBUTING.md), [Limitations](docs/LIMITATIONS.md), [Security](docs/SECURITY.md), and the [generated CLI reference](docs/generated/CLI.md). Run the release-readiness layers with:
 
 ```console
 cargo xtask verify

SECURITY.md

@@ -0,0 +1,17 @@
+# Security policy
+
+## Supported line
+
+The current supported development line is the `agentctl.dev/v1alpha1` release-candidate source on the default branch. There is no stable v1 release or long-term support promise yet.
+
+## Report a vulnerability privately
+
+Use GitHub's private vulnerability reporting flow for `opensourceops/agentctl` when it is enabled. Do not open a public issue with exploit details. If the private form is unavailable, contact the repository owners through a private channel listed on the OpenSourceOps GitHub organization profile before sending sensitive details.
+
+Include the affected commit or version, impact, minimal reproduction, and suggested mitigation. Remove credentials, production prompts, database contents, and confidential artifacts. Use clearly fake values in every reproduction.
+
+The maintainers do not promise a response or remediation deadline. They will assess reports against the implemented trust boundary and coordinate disclosure when appropriate.
+
+## Public hardening questions
+
+Questions about documented boundaries that do not disclose a vulnerability may use a GitHub discussion or issue. Read [Security](docs/SECURITY.md), [Threat model](docs/THREAT_MODEL.md), and [Limitations](docs/LIMITATIONS.md) first.

docs/ARCHITECTURE.md

@@ -33,4 +33,4 @@ The workspace uses Rust edition 2024, pins Rust 1.88 as the MSRV, forbids unsafe
 
 The OCI build is multi-stage: only the optimized Rust binary enters a maintained distroless runtime with CA roots and a non-root identity. `/config` is workflow configuration, `/workspace` is the read-only working tree, `/state` holds SQLite, and `/artifacts` receives declared outputs. State must be mounted again for inspect/resume/replay. The root filesystem may be read-only. See [Container contract](CONTAINER.md) and ADR 0007.
 
-See the [ADRs](adr/) for the decisions and [Durable execution](DURABLE_EXECUTION.md) for failure semantics.
+See the [architecture diagrams](architecture/DIAGRAMS.md), [ADRs](adr/), and [Durable execution](DURABLE_EXECUTION.md) for failure semantics.

docs/CONTRIBUTING.md

@@ -1,15 +1,79 @@
 # Contributing
 
-Use the pinned Rust toolchain and keep changes scoped to the deterministic product. Before editing a public contract, add or update a fixture/test and an ADR when durability, security, compatibility, dependency direction, or protocol version changes.
+Thank you for improving `agentctl`. Keep changes narrow, add executable evidence for public behavior, and preserve the deterministic and security boundaries.
 
-```console
-cargo fmt --all
+## Before you start
+
+Read the [code of conduct](../CODE_OF_CONDUCT.md), [product definition](PRODUCT.md), [architecture](ARCHITECTURE.md), [security model](SECURITY.md), and [limitations](LIMITATIONS.md). Search existing issues before proposing new work. Use an issue to discuss large compatibility, protocol, persistence, or security changes before implementation.
+
+Do not use a public issue for a vulnerability. Follow the private process in [SECURITY.md](../SECURITY.md).
+
+## Choose work
+
+Prefer a scoped issue with expected behavior. For a bug, add a failing test that reproduces the user-visible problem before the fix. For a feature, define validation, policy, persistence, recovery, compatibility, and documentation effects.
+
+The maintainers do not promise response or review times.
+
+## Set up development
+
+Install the pinned Rust 1.88 toolchain with Rustfmt and Clippy. From the repository root:
+
+```text
+cargo build --workspace --locked
+cargo test --workspace --all-features --locked
+cargo xtask docs-verify
+```
+
+Normal tests need no provider credential. Install the pinned `cargo-deny` version documented in `.github/workflows/ci.yml` before running the complete verification gate.
+
+## Branches and commits
+
+Create a focused feature branch. Keep unrelated formatting, renames, and refactors out of the change. Write commits that explain one coherent behavior or documentation change. Generated schema and CLI reference changes belong with the source change that caused them.
+
+Do not commit runtime databases, build output, provider responses, API keys, local absolute paths, or private release evidence.
+
+## Build and test
+
+Before requesting review:
+
+```text
+cargo fmt --all -- --check
 cargo clippy --workspace --all-targets --all-features -- -D warnings
 cargo test --workspace --all-features --locked
 cargo xtask generate
+cargo xtask docs-verify
 cargo xtask verify
+cargo xtask acceptance
+git diff --check
 ```
 
-Generated schema and CLI reference must be committed. No test, example, benchmark, fuzz target, or CI job may require provider credentials. Do not add raw keys, secret CLI flags, redirects, shell-string execution, unbounded retries/turns, or implicit effects. New providers require native mapping, capabilities, normalized errors/usage/cancellation, documentation, example configuration, and mock conformance. New tools require both schemas, risk/effect/idempotency/approval metadata, policy hooks, and malicious-output tests.
+Run `cargo xtask acceptance-container` when a container, Containerfile, mount contract, signal path, filesystem behavior, or packaging boundary changes. Live OpenAI acceptance is an explicit credentialed release gate, not a normal contribution requirement.
+
+## Special changes
+
+- Actions and tools: follow [Add an action or tool](development/ADD_ACTION.md).
+- Providers: follow [Add a provider](development/ADD_PROVIDER.md).
+- MCP or A2A: add pinned-protocol mock coverage, timeouts, cancellation, policy, redaction, and ambiguous-delivery behavior.
+- Store migrations: follow [Add a store migration](development/ADD_MIGRATION.md).
+- Workflow or durable compatibility: update fixtures, generated schema, public policy, and an ADR when the decision is architectural.
+- Documentation and examples: follow [Write and verify documentation](development/DOCUMENTATION.md).
+
+## Pull request checklist
+
+- The change is linked to a clear problem.
+- Tests fail before the fix where practical and pass after it.
+- Security, policy, effect, recovery, and redaction behavior is explicit.
+- No live credential is needed by normal CI.
+- Generated files are current.
+- Public examples are executable and use fake providers or local mocks by default.
+- Compatibility and limitations are updated.
+- New public writing contains no em dash and uses precise maturity language.
+- The diff contains no unrelated cleanup.
+
+## Review expectations
+
+Reviewers focus on correctness, deterministic behavior, explicit effects, safe failure, compatibility, tests, and truthful documentation. Address each review comment with a change or a concrete technical explanation. A local pass does not replace hosted evidence for an RC.
+
+## Release process
 
-Dependencies must be registry releases with reviewed licenses and no wildcard constraints. Unsafe Rust is forbidden. Cross-platform behavior belongs in the CI matrix. Update `docs/execution` with exact evidence when finishing a release gate.
+Maintainers follow [Release process](RELEASE_PROCESS.md). Candidate promotion requires the exact remote commit to pass required hosted checks and artifact verification. Contributors must not create tags, publish packages, or describe a local build as released.

docs/OBSERVABILITY.md

@@ -1,9 +1,46 @@
 # Observability
 
-The runtime emits versioned typed events for runs, tasks, attempts, agent turns, provider/model responses, tool/effect calls, approvals, MCP/A2A operations, retries, checkpoints, state transitions, and useful database boundaries. Events carry run/task/effect and trace correlation plus phase and timestamp.
+Observability has two audiences: terminal users need a concise final result, while operators need durable evidence for diagnosis and audit. The runtime keeps those contracts separate.
+
+## CLI streams
+
+Human output is the default for interactive use. For automation, use one versioned JSON document:
+
+```bash
+agentctl run workflow.yaml --db .agentctl/runtime.db --output json --color never
+```
+
+Success writes an `agentctl.dev/cli/v1` envelope to stdout. Failure writes the same envelope shape to stderr and returns a typed exit code. Run-scoped results include run and trace IDs. JSONL progress streaming is not implemented in this release; do not parse human output or assume that each line is an event.
+
+## Durable inspection
+
+The SQLite database is the authoritative local record. Inspect a run and database without invoking a provider or repeating an effect:
+
+```bash
+agentctl inspect RUN_ID --db .agentctl/runtime.db --output json --color never
+agentctl db stats --db .agentctl/runtime.db --output json --color never
+```
+
+Inspection includes task attempts, checkpoints, effect state, approvals, provider and protocol records, ordered audit events, and trace correlation. Use `agentctl approvals list RUN_ID` when the run exited pending approval. Preserve the database and its WAL files together when the history is operational evidence.
+
+## Runtime events
+
+The runtime emits versioned typed events for runs, tasks, attempts, agent turns, provider/model responses, tool/effect calls, approvals, MCP/A2A operations, retries, checkpoints, state transitions, and useful database boundaries. Events carry run, task, effect, and trace correlation plus phase and timestamp.
 
 `agentctl-observability` provides a no-op sink, buffered test sink, and an OpenTelemetry-compatible global tracer bridge. Tracing is optional and has no role in scheduling or replay. Structured audit events are persisted separately in SQLite and ordered per run.
 
+OpenTelemetry export is an embedding concern in this release; the standalone CLI does not expose an exporter configuration flag. An application using the runtime can install the bridge and route spans through its own collector configuration. A tracing outage must not alter workflow scheduling or replay semantics.
+
+## Metrics and interpretation
+
+Usage maps input, output, reasoning, cache-read, and cache-write tokens where providers expose them. Duration, attempts, provider errors, retries, approval waits, tool counts, and action change status are available from trace and audit events. Price calculation is not fabricated when no reliable price metadata exists.
+
+When diagnosing a failure, correlate the final envelope's run and trace IDs with the persisted task, attempt, effect, and provider records. A model response is not proof that an external effect completed; use the effect record and its confirmation state.
+
+## Sensitive data
+
 Sensitive field names and registered secret values are redacted before trace attributes leave the runtime. Provider response content is not printed by the live smoke. Operators must still treat trace backends and the local database as sensitive because prompts, file content, tool output, and remote artifacts may contain confidential non-secret data.
 
-Usage maps input/output/reasoning/cache-read/cache-write tokens where providers expose them. Duration, attempts, provider errors, retries, approval waits, tool counts, and action change status are available from trace and audit events. Price calculation is not fabricated when no reliable price metadata exists.
+Keep provider credentials in environment references, never workflow inputs or command arguments. Apply access control and retention to the database, collected artifacts, CI logs, and trace backend. Before sharing diagnostics, remove credentials, prompt content, file content, remote payloads, and identifying metadata; a run ID alone is sufficient for local correlation.
+
+See [CLI output and exit codes](reference/CLI_OUTPUT.md), [local operation](guides/LOCAL_OPERATION.md), and [runtime database and migrations](reference/DATABASE.md) for the complete operating contract.

docs/OPERATIONS.md

@@ -15,7 +15,7 @@ Scheduling belongs to the external platform. `agentctl` owns deterministic execu
 
 Use absolute paths and an external overlap lock when two schedules must not affect the same resource:
 
-```cron
+```text
 */15 * * * * /usr/bin/flock -n /var/lib/agentctl/report.lock /usr/local/bin/agentctl run /etc/agentctl/report.yaml --workspace /srv/app --db /var/lib/agentctl/runtime.db --inputs-file /etc/agentctl/inputs.json --timeout-seconds 600 --output json --color never >>/var/log/agentctl/report.jsonl 2>>/var/log/agentctl/report.err
 ```