AGENTS.md@crates/nac-managed git:20260827.24bc4a5A

Immutable. This exact content is served forever at /api/v1/blob/ef954434e4da3eaa.

# nac-managed guide

`nac-managed` is the optional managed-host bounded context. It owns managed
configuration, generic secret administration, GitHub authentication and
repository discovery, durable clone operations, Git/process workflow, and
managed readiness facts. It is usable and testable without HTTP or the agent
harness.

## Invariants and dependency restrictions

- The crate must not depend on `nac-server` or `nac-core`. Depend only on narrow
  shared contracts/infrastructure and ordinary provider libraries.
- Managed behavior is opt-in. Missing managed configuration must not change
  ordinary NAC startup or session behavior.
- Secret reads remain internal snapshots; public administration surfaces expose
  names/status, never values. Exact-value redaction and file ownership/mode
  guarantees are preserved.
- GitHub credentials, Exa secrets, and model-provider credentials keep their
  distinct ownership. The command-environment provider exposes only the narrow
  spawn snapshot required by consumers.
- Clone operations are durable and cancellable. State transitions, progress,
  reconciliation, cleanup, destination policy, and project publication ordering
  remain testable without Axum.
- Project creation crosses `ProjectRegistrar`; do not import server managers or
  core project storage to avoid the port.
- Readiness reports facts. Delivery decides HTTP status/shape and deployment
  wiring decides which facts are required.

## Starting points

- `configuration.rs` — host config, secret store and command-environment
  implementation.
- `github.rs` — provider transport, device auth/token lifecycle, repository and
  branch discovery.
- `github_credential_store.rs` — owner-only token persistence and locking.
- `clone_workflow.rs` — application-facing clone state, publication ordering,
  reconciliation, and `ProjectRegistrar` port.
- `clone_operation_store.rs` — durable operation records, destination leases,
  and staging ownership markers.
- `clone_process.rs` — supervised Git execution, cancellation, bounded progress,
  token masking, and remote identity validation.
- `readiness.rs` — provider-independent readiness facts.
- `lib.rs` — intentionally small explicit facade over private modules.

`github.rs` is a deliberate 851-line exception: one auditable provider client
keeps OAuth/device/refresh retry policy, authenticated pagination, SAML/revoked-
credential handling, and provider wire decoding together. Credential files are
still isolated behind `github_credential_store.rs`; do not add clone, HTTP
delivery, or unrelated provider behavior to the client.

## Verification

```sh
make crate-check CRATE=nac-managed
make crate-test CRATE=nac-managed
cargo test --locked -p nac-server managed
make test-managed-image-contract
```

Provider transport tests should inject local/fake transport. Live credentials
are never required for the ordinary test suite. Production owners use sibling
`*_tests.rs` modules so provider/workflow code remains readable.

## Generated artifacts and placement mistakes

OpenAPI derives are feature-gated annotations, not a delivery dependency. This
crate owns no generated frontend files or container assets.

Do not place Exa web search/fetch here; it is a native tool/provider family.
Do not add Axum handlers, React models, server session managers, model loops, or
workspace session lifecycle. Do not make readiness mutate the host to satisfy a
check.