`clarityctl doctor` now validates daemon connectivity, compiler availability, and local build workspace readiness.

Quality commands:

```bash
npm run lint
npm run format
npm run test
npm run test:coverage
```

Legacy compatibility commands (still supported):

```bash
clarityctl add-local --source --module --wasm
clarityctl start-source --source [--module ] [--wasm ]
```

---

## Current Status

Implemented for v0.9 baseline:

- service contracts and manifest schema (`clarity.runtime/v1`)
- persistent registry (`.clarity/runtime/registry.json`)
- daemon HTTP API and status page
- add/list/start/stop/restart/introspect/remove flows
- gateway `/mcp` JSON-RPC endpoint (`initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `prompts/list`)
- built-in runtime control MCP tools (`runtime__status_summary`, `runtime__list_services`, `runtime__get_service`, `runtime__get_logs`, `runtime__start_service`, `runtime__stop_service`, `runtime__restart_service`, `runtime__refresh_interface`, `runtime__unquarantine_service`, `runtime__remove_service`, `runtime__get_audit`, `runtime__get_agent_runs`, `runtime__get_agent_events`, `runtime__validate_auth_ref`, `runtime__auth_provider_health`, `runtime__list_auth_secrets`, `runtime__set_auth_secret`, `runtime__delete_auth_secret`)
- built-in Clarity-assist MCP tools (`clarity__help`, `clarity__sources`, `clarity__project_structure`, `clarity__ensure_compiler`, `clarity__bootstrap_app`) for default-language guidance, source discovery, app scaffolding, compiler readiness/install checks, and one-call bootstrap
- gated MCP self-provisioning tools (`runtime__register_local`, `runtime__register_remote`, `runtime__register_via_url`, `runtime__apply_manifest`) protected by `CLARITY_ENABLE_MCP_PROVISIONING=1`
- stdio bridge mode via `clarityctl gateway serve --stdio`
- compiler-assisted onboarding via `clarityctl add ` (compile + register + start + introspect)
- local function execution tools for local services (`__fn__`)
- baseline remote policy controls (timeout + allowed-tools + payload-size + concurrency manifest policy + optional host allowlist)
- bootstrap writers for Codex/Claude config files
- durable runtime telemetry store (`.clarity/runtime/telemetry.json`) for events + service logs across daemon restarts
- agent orchestration observability (`agent.*` events, `/api/agents/*` APIs, UI `Agents` tab)
- deprovision endpoint/tooling with optional local artifact cleanup
- end-to-end runtime integration tests covering API/MCP registration/call/remove lifecycle

Not implemented yet:

- remote auth/policy isolation hardening for stricter multi-tenant trust boundaries
- language-level A2A effect/module integration (`std/a2a`) emitting runtime orchestration events by default

---

## Roadmap

- [x] Runtime-side compiler path (`clarityctl add `)
- [ ] Native compiler command (`clarityc start `) in `LLM-lang`
- [x] Add policy engine baseline (timeouts, allowlists, concurrency, payload limits)
- [ ] Complete remote auth/policy isolation hardening (provider backend + validation + file-secret lifecycle landed)
- [x] Add MCP self-provisioning tools (LLM can register/install services via MCP with approval + policy gates)
- [x] Add quarantine/recovery and richer health diagnostics
- [x] Add interface diffing and audit/event timeline
- [x] Add agent observability (run summaries + timeline + UI tab split)

## Progress Snapshot

| Area | Status | Notes |
| ------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Registry + lifecycle | Done | Persistent service records, start/stop/restart, health state |
| Gateway MCP transport | Done | `/mcp` JSON-RPC with list/call routing |
| Runtime as MCP control plane | Done | `runtime__*` tools for status, service ops, logs, audit, quarantine recovery |
| Stdio gateway bridge | Done | `clarityctl gateway serve --stdio` forwards to daemon gateway |
| Remote MCP proxying | Done (baseline) | Initialize/introspect/tool forwarding |
| Compiler-driven onboarding | In progress | Runtime side done; `clarityc start` exists in `LLM-lang` and delegates to `clarityctl add`; keep cross-repo contract/version alignment |
| Local function execution | Done (baseline) | `__fn__*` tools discovered from wasm exports and executed via compiler runtime |
| In-process WASM host execution | Done | Local function tools execute directly via wasm instantiate/call in runtime |
| Auth/policy hardening | In progress | Timeout/allowed-tools/payload-size/concurrency/host-allowlist baseline implemented; auth provider backend (`legacy env`, `env`, `file`, `header_env`) + validation/secret lifecycle tools added; isolation policy hardening pending |
| MCP self-provisioning | Done (gated) | `runtime__register_local`, `runtime__register_remote`, `runtime__apply_manifest` behind `CLARITY_ENABLE_MCP_PROVISIONING=1` |
| Durable audit/log persistence | Done | Events + service logs persisted to `.clarity/runtime/telemetry.json` and reloaded on daemon boot |
| Agent observability | Done (baseline) | `agent.*` event persistence, `/api/agents/*` APIs, and status UI `Agents` tab for run/timeline visibility |
| Deprovision + cleanup | Done | `DELETE /api/services/:id` and `clarityctl remove` with optional local artifact cleanup |
| Runtime integration tests | Done (baseline) | End-to-end API/MCP tests for register/start/introspect/call/remove |

---

## Spec

- Runtime spec: `docs/spec/v1/runtime-spec.md`
- Manifest schema: `schemas/mcp-service-v1.schema.json`
- Layered requirements: `docs/requirements/layered-runtime-requirements.md`
- v0.9 roadmap: `docs/roadmap/v0.9-roadmap.md`

## Remote Policy Knobs

- `add-remote --timeout-ms `: set per-service remote request timeout.
- `add-remote --allow-tools `: restrict callable remote tools.
- `add-remote --max-payload-bytes `: set max request/response payload bytes per remote service.
- `add-remote --max-concurrency `: set max concurrent in-flight remote requests per service.
- `add-remote --auth-ref `: remote auth reference (supports `legacy-name`, `env:ENV_VAR`, `file:relative/path`, `header_env:Header-Name:ENV_VAR`).
- `CLARITY_REMOTE_ALLOWED_HOSTS=host1,host2`: optional global remote host allowlist.
- `CLARITY_REMOTE_DEFAULT_TIMEOUT_MS=20000`: default timeout when manifest timeout is not set.
- `CLARITY_REMOTE_MAX_PAYLOAD_BYTES=1048576`: default max request/response payload bytes when manifest value is not set.
- `CLARITY_REMOTE_MAX_CONCURRENCY=8`: default max in-flight remote requests per service when manifest value is not set.
- `CLARITY_REMOTE_AUTH_FILE_ROOT=/absolute/path`: optional root directory for `file:` auth refs (defaults to `.clarity/secrets` under workspace).
- `CLARITY_ENABLE_MCP_PROVISIONING=1`: enable runtime MCP self-provisioning tools (`runtime__register_*`, `runtime__apply_manifest`).
- `CLARITY_ENABLE_COMPILER_INSTALL=1`: allow `clarity__ensure_compiler` to execute install commands.
- `CLARITY_COMPILER_INSTALL_ALLOWLIST=brew,apt-get`: optional installer command allowlist for `clarity__ensure_compiler`.
- `CLARITY_AUDIT_INCLUDE_LIFECYCLE=1`: include service lifecycle events in audit (`service.*`). Set `0` to log only MCP tool calls.
- `CLARITY_A2A_MAX_MESSAGE_BYTES=65536`: max accepted body size for formal A2A envelope ingestion at `POST /api/a2a/messages`.
- Runtime chat dispatch:
- `CLARITY_HITL_CHAT_MODE=auto|echo|disabled` (global default)
- per-agent overrides in manifest: `metadata.agent.chat` (`mode`, `handlerTool`)
- in `auto` mode runtime dispatches to agent-owned handler tools (local default `fn__receive_chat`, remote default `receive_chat`)
- provider keys/models should be owned by the agent implementation, not runtime

## Security Defaults

- If `CLARITYD_AUTH_TOKEN` is set, all `/api/*` and `/mcp` requests require that token via `Authorization: Bearer ` or `x-clarity-token`.
- If no token is set, runtime APIs are limited to loopback callers only.
- Status UI accepts `?token=` for local browser sessions when token auth is enabled.

## Audit And Events

- `GET /api/audit?limit=200`: latest runtime audit/events.
- `GET /api/agents/registry`: registered agent services and declared capabilities.
- `GET /api/agents/runs?limit=100`: agent run summaries.
- `GET /api/agents/events?limit=200`: recent agent timeline events.
- `GET /api/agents/runs/:runId/events?limit=200`: one-run agent timeline.
- `GET /api/a2a/capabilities`: list A2A-enabled agents and protocol profile.
- `POST /api/a2a/messages`: ingest one formal A2A envelope (`clarity.a2a.v1`) and normalize to canonical `agent.*` events.
- `POST /api/agents/events`: ingest one `agent.*` orchestration event.
- `GET /api/events`: SSE stream for live runtime events.
- Status page now includes separate `MCP` and `Agents` tabs.
- Telemetry persists across daemon restarts in `.clarity/runtime/telemetry.json`.
- Audit policy always records MCP tool invocations (`mcp.tool_called`), excludes secret payloads, and can include lifecycle events (`service.*`) via `CLARITY_AUDIT_INCLUDE_LIFECYCLE=1` (default on).
- Auth lifecycle/validation APIs:
- `GET /api/security/auth/providers`
- `GET|POST /api/security/auth/validate`
- `GET /api/security/auth/secrets`
- `POST /api/security/auth/secrets` (requires `CLARITY_ENABLE_MCP_PROVISIONING=1`)
- `DELETE /api/security/auth/secrets` (requires `CLARITY_ENABLE_MCP_PROVISIONING=1`)
- Service deprovision API:
- `DELETE /api/services/:serviceId` with optional body `{ "cleanup_artifacts": true }`

## CI/CD And GitHub

- PR CI: `.github/workflows/build.yml` (branch naming + build + lint + format + test).
- Snapshot packaging on every merge/push to `main`: `.github/workflows/snapshot.yml` (includes coverage gate and uploads snapshot artifact).
- Tagged release pipeline: `.github/workflows/release.yml` (build, test, coverage, package, checksums, GitHub Release assets).
- Automated versioning/changelog PRs: `.github/workflows/release-please.yml` (`.release-please-*.json` config).
- Security gates:
- `.github/workflows/dependency-review.yml`
- `.github/workflows/codeql.yml`
- `.github/workflows/secret-scan.yml`
- Repo automation:
- Dependabot: `.github/dependabot.yml`
- CODEOWNERS: `.github/CODEOWNERS`
- PR/Issue templates: `.github/pull_request_template.md`, `.github/ISSUE_TEMPLATE/*`
- Label sync + path labeling: `.github/workflows/labels-sync.yml`, `.github/workflows/labeler.yml`, `.github/labeler.yml`
- Optional project auto-add: `.github/workflows/project-automation.yml` (set `GH_PROJECT_URL` variable and `ADD_TO_PROJECT_PAT` secret)

### Required GitHub Settings (Manual)

- Protect `main`:
- Require pull requests before merge
- Require status checks to pass before merge
- Require branches to be up to date before merge
- Require linear history
- Merge strategy:
- Enable squash merge
- Disable merge commits
- Optional hardening:
- Restrict who can push to `main`
- Require review from Code Owners

You can apply a baseline branch-protection policy with:

```bash
./scripts/github/apply-branch-protection.sh
```

### Commit/Release Convention

- Use conventional commit prefixes so release automation can infer version bumps:
- `feat: ...`
- `fix: ...`
- `chore: ...`
- `docs: ...`
- `refactor: ...`
- Use `BREAKING CHANGE:` in commit bodies for major bumps.

## Contributing

This repo uses trunk-based development:

1. Keep `main` releasable at all times.
2. Branch from `main`, keep branches short-lived, and merge back quickly.
3. Name every branch by the expected outcome (not implementation details):
- `result/`
- `hotfix/`
- `codex/`
- (automation exception) `dependabot/*`
4. Open a PR to `main` with behavior/rationale notes.
5. Ensure CI is green (`.github/workflows/build.yml`: branch-name check + build + lint + format + test).