+
-
+
- Kubernetes · ServiceNow · Splunk — for AI Agents. + Kubernetes · ServiceNow · Splunk - for AI Agents.
--- @@ -25,7 +25,7 @@ **ClawForge is not another agent framework.** It is the **control plane** for managing, governing, securing, observing, auditing, and operating AI agents, MCP -servers, workflows, tools, models, and enterprise integrations — built for +servers, workflows, tools, models, and enterprise integrations - built for government entities, municipalities, and enterprise IT, security, and AI platform teams. @@ -37,7 +37,7 @@ teams. | **ClawForge** | **Enterprise / Government Agent Control Plane** | Beneath the control plane sits a high-performance, local-first **agent runtime** -written entirely in Rust — a Rust implementation of the +written entirely in Rust - a Rust implementation of the [OpenClaw](https://openclaw.ai) topology that orchestrates autonomous agents over a central WebSocket gateway, across channels (WhatsApp, Telegram, Discord, Slack), with tools, sandboxing, and memory. The `clawforge-controlplane` crate wraps that @@ -73,7 +73,7 @@ domain module: | **Security Gateway** | Pre-execution checks on every action (tool / MCP / model / data / budget / approval) + risk score | [security-gateway.md](docs/security-gateway.md) | | **MCP Governance** | Registry, approval, health, and usage tracking for MCP servers | [mcp-governance.md](docs/mcp-governance.md) | | **Agent Marketplace** | Verified, reusable internal agent templates with compliance badges | [marketplace.md](docs/marketplace.md) | -| **Enterprise Integrations** | Governed connectors (DBs, SSO, GIS, ITSM) — credentials referenced, never stored | [enterprise-integrations.md](docs/enterprise-integrations.md) | +| **Enterprise Integrations** | Governed connectors (DBs, SSO, GIS, ITSM) - credentials referenced, never stored | [enterprise-integrations.md](docs/enterprise-integrations.md) | | **Government Compliance** | PII classification, retention, approval chains, audit evidence, reporting (UAE PDPL-aware) | [government-compliance.md](docs/government-compliance.md) | ## Quick start @@ -92,9 +92,9 @@ cargo test -p clawforge-controlplane # 82 tests cargo run -p clawforge-controlplane --example demo ``` -The demo walks a single agent through the whole control plane — marketplace +The demo walks a single agent through the whole control plane - marketplace install → MCP approval → governance → security gateway → observability → -compliance report — in memory. See [docs/demo.md](docs/demo.md). +compliance report - in memory. See [docs/demo.md](docs/demo.md). ### Running the full runtime (optional) @@ -128,27 +128,27 @@ Full index: [docs/README.md](docs/README.md). ClawForge's control plane governs a complete, local-first agent runtime (Rust workspace): -- **`clawforge-core`** — central schemas (`AgentSpec`, `Message`, `Event`). -- **`clawforge-gateway` / `clawforge-daemon`** — Tokio WebSocket control plane for sessions, tools, and events. -- **`clawforge-planner` / `clawforge-executor`** — LLM provider integrations (OpenRouter, Ollama) and sandboxed action execution. -- **`clawforge-channels`** — deep adapters for Telegram, Discord, Slack, LINE, iMessage, and WhatsApp. -- **`clawforge-plugins` / `clawforge-browser` / `clawforge-understanding`** — WASM plugins, CDP browser automation, and OCR/STT/PDF media pipelines. -- **`clawforge-memory` / `clawforge-supervisor`** — vector memory for RAG and SQLite run-state persistence. +- **`clawforge-core`** - central schemas (`AgentSpec`, `Message`, `Event`). +- **`clawforge-gateway` / `clawforge-daemon`** - Tokio WebSocket control plane for sessions, tools, and events. +- **`clawforge-planner` / `clawforge-executor`** - LLM provider integrations (OpenRouter, Ollama) and sandboxed action execution. +- **`clawforge-channels`** - deep adapters for Telegram, Discord, Slack, LINE, iMessage, and WhatsApp. +- **`clawforge-plugins` / `clawforge-browser` / `clawforge-understanding`** - WASM plugins, CDP browser automation, and OCR/STT/PDF media pipelines. +- **`clawforge-memory` / `clawforge-supervisor`** - vector memory for RAG and SQLite run-state persistence. ## Security -ClawForge connects to real messaging surfaces — treat inbound messages, tool +ClawForge connects to real messaging surfaces - treat inbound messages, tool output, and MCP responses as **untrusted input**. The Security Gateway gates *capabilities* (which tool / MCP / model / data an action may use); keep untrusted execution sandboxed (the runtime supports Docker isolation). Secrets -are never stored — integrations hold credential *references* only. Read the full +are never stored - integrations hold credential *references* only. Read the full [security disclaimer](docs/security-disclaimer.md) and [limitations](docs/limitations.md) before relying on ClawForge. ## Contributing Contributions are welcome. Please read the [developer guide](docs/developer-guide.md) -and [CONTRIBUTING.md](CONTRIBUTING.md) — work in atomic, well-described commits, +and [CONTRIBUTING.md](CONTRIBUTING.md) - work in atomic, well-described commits, run `cargo test -p clawforge-controlplane` before opening a pull request, and keep documentation in step with code. diff --git a/assets/skills/coding-agent/SKILL.md b/assets/skills/coding-agent/SKILL.md index 7a672a1..320327d 100644 --- a/assets/skills/coding-agent/SKILL.md +++ b/assets/skills/coding-agent/SKILL.md @@ -271,7 +271,7 @@ bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Buil When completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'" ``` -This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes. +This triggers an immediate wake event - Skippy gets pinged in seconds, not 10 minutes. --- diff --git a/assets/skills/notion/SKILL.md b/assets/skills/notion/SKILL.md index 52b2ef5..fe48f29 100644 --- a/assets/skills/notion/SKILL.md +++ b/assets/skills/notion/SKILL.md @@ -167,6 +167,6 @@ Common property formats for database items: ## Notes - Page/database IDs are UUIDs (with or without dashes) -- The API cannot set database view filters — that's UI-only +- The API cannot set database view filters - that's UI-only - Rate limit: ~3 requests/second average - Use `is_inline: true` when creating data sources to embed them in pages diff --git a/docs/README.md b/docs/README.md index 3f4e88c..69e9584 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,12 +4,12 @@ Index of the control-plane documentation. ## Start here -- [Product positioning](product-positioning.md) — what ClawForge is (and isn't). -- [Architecture](architecture.md) — the two layers and how they relate. -- [Diagrams](diagrams.md) — architecture, lifecycle, governance, and MCP flows. -- [Installation guide](installation.md) — prerequisites, config, build & test. -- [Model providers](model-providers.md) — every supported provider and how to enable it. -- [Demo](demo.md) — runnable end-to-end walkthrough. +- [Product positioning](product-positioning.md) - what ClawForge is (and isn't). +- [Architecture](architecture.md) - the two layers and how they relate. +- [Diagrams](diagrams.md) - architecture, lifecycle, governance, and MCP flows. +- [Installation guide](installation.md) - prerequisites, config, build & test. +- [Model providers](model-providers.md) - every supported provider and how to enable it. +- [Demo](demo.md) - runnable end-to-end walkthrough. ## Capabilities diff --git a/docs/architecture.md b/docs/architecture.md index 1a475a0..2720745 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,9 +4,9 @@ ClawForge has two layers: -1. **Agent runtime** — the existing Rust workspace that *runs* agents (gateway, +1. **Agent runtime** - the existing Rust workspace that *runs* agents (gateway, planner, executor, channels, tools, memory, …). -2. **Control plane** — the `clawforge-controlplane` crate that *governs* agents +2. **Control plane** - the `clawforge-controlplane` crate that *governs* agents (registry, governance, observability, security gateway, MCP governance, marketplace, integrations, compliance). @@ -60,14 +60,14 @@ backend/controlplane/ ├── constants.rs # RiskLevel, DataAccessLevel, LifecycleStatus, product consts ├── error.rs # ControlPlaneError + Result alias ├── logging.rs # cp_info! / cp_warn! / cp_blocked! macros - ├── registry/ # Phase 2 — Agent Registry - ├── governance.rs # Phase 3 — Governance Engine - ├── observability/ # Phase 4 — metrics & execution events - ├── gateway.rs # Phase 5 — Security Gateway - ├── mcp/ # Phase 6 — MCP registry & governance - ├── marketplace.rs # Phase 7 — verified agent templates - ├── integrations/ # Phase 8 — enterprise integration registry - └── compliance/ # Phase 9 — government compliance pack + ├── registry/ # Phase 2 - Agent Registry + ├── governance.rs # Phase 3 - Governance Engine + ├── observability/ # Phase 4 - metrics & execution events + ├── gateway.rs # Phase 5 - Security Gateway + ├── mcp/ # Phase 6 - MCP registry & governance + ├── marketplace.rs # Phase 7 - verified agent templates + ├── integrations/ # Phase 8 - enterprise integration registry + └── compliance/ # Phase 9 - government compliance pack ``` (Modules land phase by phase; the table reflects the target shape.) diff --git a/docs/demo.md b/docs/demo.md index 2652f71..01b104a 100644 --- a/docs/demo.md +++ b/docs/demo.md @@ -13,14 +13,14 @@ cargo run -p clawforge-controlplane --example demo Everything runs in-memory, exercising every module in one agent's journey: -1. **Marketplace** — seeds verified listings and installs one into the Registry. -2. **MCP Governance** — registers and approves the `records-mcp` server. -3. **Governance** — submits and approves the agent, moving it `Draft → +1. **Marketplace** - seeds verified listings and installs one into the Registry. +2. **MCP Governance** - registers and approves the `records-mcp` server. +3. **Governance** - submits and approves the agent, moving it `Draft → PendingApproval → Active`. -4. **Security Gateway** — evaluates a real action (tool + MCP + data access + +4. **Security Gateway** - evaluates a real action (tool + MCP + data access + budget) and prints an allow/deny verdict with a risk score. -5. **Observability** — records the execution and prints the task success rate. -6. **Compliance** — classifies the agent (UAE PDPL, PII, retention, approval +5. **Observability** - records the execution and prints the task success rate. +6. **Compliance** - classifies the agent (UAE PDPL, PII, retention, approval chain) and prints a compliance report with findings. ## Expected output @@ -43,4 +43,4 @@ Everything runs in-memory, exercising every module in one agent's journey: The compliance findings are intentional: they show the report correctly flagging an agent that handles PII without collected evidence or a completed -approval chain — exactly the kind of gap the control plane surfaces. +approval chain - exactly the kind of gap the control plane surfaces. diff --git a/docs/diagrams.md b/docs/diagrams.md index ec8fc98..1ebfe71 100644 --- a/docs/diagrams.md +++ b/docs/diagrams.md @@ -36,7 +36,7 @@ flowchart TB ## Agent lifecycle The registry state machine. An agent can only become operational by passing -through approval — a direct `Draft → Active` jump is rejected. +through approval - a direct `Draft → Active` jump is rejected. ```mermaid stateDiagram-v2 diff --git a/docs/enterprise-integrations.md b/docs/enterprise-integrations.md index 26ef5d0..3a4ffc5 100644 --- a/docs/enterprise-integrations.md +++ b/docs/enterprise-integrations.md @@ -5,7 +5,7 @@ ClawForge governs *connections* to enterprise and government systems. The integration registry (`clawforge_controlplane::integrations`) tracks every connector, who owns it, what it is allowed to do, where its credentials live, -and whether it is approved — **without ever storing a secret**. +and whether it is approved - **without ever storing a secret**. ## Categories (`IntegrationKind`) @@ -15,7 +15,7 @@ Active Directory, SSO, API Gateway, Email, Webhook. ## Credentials are referenced, never stored `CredentialRef` records *where* a secret lives (`vault` / `env` / `sso` / -`keychain` / `none`) and the lookup `key` — never the secret material itself. +`keychain` / `none`) and the lookup `key` - never the secret material itself. This keeps the control plane out of scope for secret storage while still giving governance a complete picture of what an integration can reach. @@ -32,7 +32,7 @@ Granting `write`, `delete`, or `admin` is *elevated*. `classify_risk(kind, permissions)` computes effective risk: the higher of the category baseline (identity stores and SSO are `critical`; primary databases are `high`) and a `high` floor implied by any elevated permission. Registration escalates an -integration's risk to this baseline — it never silently downgrades an explicit +integration's risk to this baseline - it never silently downgrades an explicit level. ## API diff --git a/docs/enterprise.md b/docs/enterprise.md index ee7e255..9bff9e3 100644 --- a/docs/enterprise.md +++ b/docs/enterprise.md @@ -1,4 +1,4 @@ -# Use Case — Enterprise IT +# Use Case - Enterprise IT **Scenario:** An enterprise IT operations team wants an agent that executes approved remediation runbooks (restart services, run diagnostics) against @@ -22,7 +22,7 @@ governance.submit(/* kind: Tool, shell */)?; ``` The `servicenow-mcp` server is registered in **MCP Governance**, reviewed -(`requires_governance_review()` is true — it has a `write` tool), approved, and +(`requires_governance_review()` is true - it has a `write` tool), approved, and health-checked. ## 3. Policy & budget @@ -35,19 +35,18 @@ caps daily spend. ## 4. Guarded execution Before each remediation step the Security Gateway verifies the tool and MCP -server are allow-listed, the model matches, the action is within budget, and — -because the agent is critical-risk under a mandated gate — flags it for human +server are allow-listed, the model matches, the action is within budget, and - because the agent is critical-risk under a mandated gate - flags it for human approval. Allowed steps proceed; everything is scored and logged. ## 5. Observe the fleet Every run emits Observability events. The IT dashboard shows task success rate, tool failure rate, average latency, total cost, MCP call volume, and any blocked -executions — for this agent and across the whole fleet (`summary(None)`). +executions - for this agent and across the whole fleet (`summary(None)`). ## Why a control plane Without ClawForge this agent would run with ad-hoc credentials, no central approval, no per-action checks, and no unified audit trail. With it, IT gets **Kubernetes-style lifecycle, ServiceNow-style approvals, and Splunk-style -observability** over their agent fleet — in one place. +observability** over their agent fleet - in one place. diff --git a/docs/governance.md b/docs/governance.md index 3a1fa61..de8a1e4 100644 --- a/docs/governance.md +++ b/docs/governance.md @@ -70,7 +70,7 @@ let history = gov.history(&req.id)?; ## How it ties together -The engine deliberately does not mutate the Agent Registry itself — it records +The engine deliberately does not mutate the Agent Registry itself - it records *decisions*. The intended flow is: register an agent (`Draft`), submit it for approval, and on `Approved` move it through `PendingApproval → Active` in the registry. This keeps the source-of-truth (registry) and the decision log diff --git a/docs/government-compliance.md b/docs/government-compliance.md index a255f77..18d1d9e 100644 --- a/docs/government-compliance.md +++ b/docs/government-compliance.md @@ -18,7 +18,7 @@ PDPL by default) without hard-coding any single jurisdiction. See | `framework` | e.g. `UAE-PDPL` | | `pii_classification` | `non_pii` / `pii` / `sensitive_pii` | | `data_retention_days` | retention window; `0` = indefinite | -| `investigation_mode` | legal hold — suspends deletion, mandates evidence | +| `investigation_mode` | legal hold - suspends deletion, mandates evidence | | `export_control` | `unrestricted` / `restricted` / `prohibited` | `is_past_retention(age_days)` honours both indefinite retention and an active @@ -68,4 +68,4 @@ incomplete approval chains, and export-prohibited data lacking signed evidence. Reports are **pure functions** of data assembled from the other control-plane stores (registry, governance, gateway, integrations). Nothing is recomputed from a separate source of truth, so a report is always reproducible from the -evidence on file — exactly what an auditor or investigator needs. +evidence on file - exactly what an auditor or investigator needs. diff --git a/docs/government-municipality.md b/docs/government-municipality.md index f9f59d7..e781da5 100644 --- a/docs/government-municipality.md +++ b/docs/government-municipality.md @@ -1,4 +1,4 @@ -# Use Case — Government Municipality +# Use Case - Government Municipality **Scenario:** A municipality wants an AI agent to triage building-permit applications. The agent must read resident records (regulated PII) and is @@ -56,4 +56,4 @@ let dept = DepartmentComplianceSummary::summarize("Licensing", &[report]); The municipality can now demonstrate, with reproducible evidence, *who approved the agent, what it accessed, and that retention and export rules were enforced* -— the core of a PDPL accountability story. +- the core of a PDPL accountability story. diff --git a/docs/installation.md b/docs/installation.md index 293b91c..98a8788 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,8 +2,8 @@ ## Prerequisites -- **Rust ≥ 1.80** (workspace edition 2021) — install via [rustup](https://rustup.rs). -- **Node ≥ 20** — only needed for the React dashboard in `frontend/`. +- **Rust ≥ 1.80** (workspace edition 2021) - install via [rustup](https://rustup.rs). +- **Node ≥ 20** - only needed for the React dashboard in `frontend/`. - A C toolchain (for the bundled SQLite used by `rusqlite`). ## Get the code @@ -17,7 +17,7 @@ cd clawforge ```bash cp .env.example .env -# edit .env — at minimum set OPENROUTER_API_KEY for the runtime. +# edit .env - at minimum set OPENROUTER_API_KEY for the runtime. ``` Control-plane settings (all optional, sensible local-first defaults): diff --git a/docs/limitations.md b/docs/limitations.md index 3a9b7c6..97bcc92 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -26,7 +26,7 @@ evaluators can judge it accurately. ## Data & scale -- **Single-node SQLite.** Each store uses a local SQLite database — excellent +- **Single-node SQLite.** Each store uses a local SQLite database - excellent for local-first and small deployments, but not a clustered/HA datastore. - **No multi-tenancy.** There is no tenant isolation layer yet; an `organization` config field exists but is not enforced across stores. @@ -39,6 +39,6 @@ evaluators can judge it accurately. - **Retention is advisory.** `is_past_retention` reports when data is past due; it does not yet delete or archive anything automatically. -None of these are architectural dead-ends — they are the difference between a +None of these are architectural dead-ends - they are the difference between a solid, tested foundation and a fully operationalised platform, and each is tracked on the [roadmap](roadmap.md). diff --git a/docs/marketplace.md b/docs/marketplace.md index fcacc23..942b051 100644 --- a/docs/marketplace.md +++ b/docs/marketplace.md @@ -4,7 +4,7 @@ The marketplace (`clawforge_controlplane::marketplace`) is a **verified, internal catalogue of reusable agent templates**. Teams publish proven agent blueprints; -other teams install them as governed, registry-tracked agents — without +other teams install them as governed, registry-tracked agents - without re-engineering or re-reviewing from scratch. ## Listings @@ -21,7 +21,7 @@ A `MarketplaceAgent` listing carries identity (`name`, `description`, | `compliance` | `pending` → `compliant` → `certified` | compliance team | `is_trusted()` is true only when a listing is **verified** *and* at least -**compliant** — the bar for surfacing it as install-ready. +**compliant** - the bar for surfacing it as install-ready. ## Templates @@ -61,7 +61,7 @@ let agent = mkt.install(&listing.id, ®, "Permit Bot A", "team-a", "Licensing" `install` is the bridge to the **Agent Registry**: it stamps out a `Draft` agent from the template, which then flows through the normal governance and security lifecycle. The marketplace itself stays decoupled from agent -persistence — it is handed the registry to install into. +persistence - it is handed the registry to install into. ## Seed data diff --git a/docs/mcp-governance.md b/docs/mcp-governance.md index 788a04c..ae3d267 100644 --- a/docs/mcp-governance.md +++ b/docs/mcp-governance.md @@ -3,7 +3,7 @@  The MCP registry (`clawforge_controlplane::mcp`) governs the Model Context -Protocol servers an organisation exposes to its agents — the same discipline the +Protocol servers an organisation exposes to its agents - the same discipline the agent registry applies to agents. The Security Gateway consults agent allow-lists; this registry is the source of truth for *which MCP servers exist, who owns them, and whether they are approved*. @@ -27,8 +27,8 @@ who owns them, and whether they are approved*. A server is registered in `pending_approval` and is **not usable** until `approve`d (status `active`). `block` moves it to `blocked`. A server that -`requires_governance_review()` — high/critical risk *or* exposing sensitive -tools (network/fs/write/exec/pii) — should not be approved without scrutiny. +`requires_governance_review()` - high/critical risk *or* exposing sensitive +tools (network/fs/write/exec/pii) - should not be approved without scrutiny. ## API diff --git a/docs/observability.md b/docs/observability.md index 6df8e80..bc8176d 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -17,18 +17,18 @@ Every observable action is one `ExecutionEvent` with an `EventKind`: | `tool_call` | name, success | tool failure rate | | `model_call` | name, success | model failure rate | | `mcp_call` | name, success | MCP call count | -| `risk_event` | — | risk events | -| `hallucination` | — | hallucination flag count | -| `human_intervention` | — | intervention count | -| `approval_wait` | — | approval waiting count | -| `blocked` | — | blocked executions | +| `risk_event` | - | risk events | +| `hallucination` | - | hallucination flag count | +| `human_intervention` | - | intervention count | +| `approval_wait` | - | approval waiting count | +| `blocked` | - | blocked executions | ## Metrics (`AgentMetrics`) `task_count`, `successful_tasks`, `failed_tasks`, `tool_failure_rate`, `model_failure_rate`, `average_latency_ms`, `average_cost`, `total_cost`, `human_intervention_count`, `approval_waiting_count`, `blocked_executions`, -`risk_events`, `hallucination_flag_count`, `mcp_call_count` — plus a derived +`risk_events`, `hallucination_flag_count`, `mcp_call_count` - plus a derived `success_rate()`. ## API diff --git a/docs/product-positioning.md b/docs/product-positioning.md index fbec8a0..ab4c862 100644 --- a/docs/product-positioning.md +++ b/docs/product-positioning.md @@ -1,4 +1,4 @@ -# ClawForge — Product Positioning +# ClawForge - Product Positioning  @@ -11,7 +11,7 @@ Kubernetes + ServiceNow + Splunk for AI Agents.** ClawForge is **not** another agent framework, SDK, or model wrapper. It does not compete with the layer that *builds* or *runs* an agent. Instead it sits **above** -those agents as a control plane — the layer an organisation uses to decide *which* +those agents as a control plane - the layer an organisation uses to decide *which* agents may exist, *what* they are allowed to do, *who* approved them, *what* they actually did, and *whether* that was compliant. @@ -52,14 +52,14 @@ plane is framework-agnostic by design. ## Core capabilities (build phases) -1. **Agent Registry** — single source of truth for every agent. -2. **Governance Engine** — approval workflows with human gates and change history. -3. **Observability** — task, cost, latency, failure, and risk metrics. -4. **Security Gateway** — pre-execution checks on every agent action. -5. **MCP Governance** — registry and approval for MCP servers and their tools. -6. **Agent Marketplace** — verified, reusable internal agent templates. -7. **Enterprise Integrations** — governed connectors (databases, SSO, GIS, ITSM). -8. **Government Compliance Pack** — PII classification, retention, audit evidence, +1. **Agent Registry** - single source of truth for every agent. +2. **Governance Engine** - approval workflows with human gates and change history. +3. **Observability** - task, cost, latency, failure, and risk metrics. +4. **Security Gateway** - pre-execution checks on every agent action. +5. **MCP Governance** - registry and approval for MCP servers and their tools. +6. **Agent Marketplace** - verified, reusable internal agent templates. +7. **Enterprise Integrations** - governed connectors (databases, SSO, GIS, ITSM). +8. **Government Compliance Pack** - PII classification, retention, audit evidence, approval chains, and compliance reporting (UAE PDPL-aware). ## Final product statement diff --git a/docs/registry.md b/docs/registry.md index b630f2c..3757cec 100644 --- a/docs/registry.md +++ b/docs/registry.md @@ -37,7 +37,7 @@ Deactivated (terminal; reachable from any non-deactivated state) ``` New agents start in `Draft`. They can only reach `Active` by passing through -`PendingApproval` — the registry rejects a direct `Draft → Active` jump so an +`PendingApproval` - the registry rejects a direct `Draft → Active` jump so an agent cannot become operational without governance approval. `Blocked` and `Deactivated` are available as administrative overrides from any live state. Transition rules live in `registry::lifecycle::can_transition`. diff --git a/docs/roadmap.md b/docs/roadmap.md index a9f6676..0d09742 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -5,31 +5,31 @@ strong foundation into a production platform. ## Near term -- **HTTP/gateway surface** — expose the control-plane stores over the existing +- **HTTP/gateway surface** - expose the control-plane stores over the existing `clawforge-gateway` so the React dashboard and external tools can drive them. -- **Gateway ↔ runtime wiring** — call `SecurityGateway::evaluate` from the live +- **Gateway ↔ runtime wiring** - call `SecurityGateway::evaluate` from the live executor so checks run on real actions, and stream execution events into `ObservabilityStore`. -- **Control-plane UI** — registry, approval queue, fleet dashboard, MCP +- **Control-plane UI** - registry, approval queue, fleet dashboard, MCP catalogue, marketplace, and compliance views (see `docs/screenshots/`). ## Mid term -- **Pluggable identity** — wire the SSO/Active Directory integrations into +- **Pluggable identity** - wire the SSO/Active Directory integrations into approver authentication and role-based access for governance actions. -- **Real digital signatures** — implement signing over `AuditEvidence` +- **Real digital signatures** - implement signing over `AuditEvidence` `content_hash` (the placeholder is already in the model). -- **Policy bundles** — versioned, exportable `SecurityPolicy` / compliance +- **Policy bundles** - versioned, exportable `SecurityPolicy` / compliance policy sets per environment (`local` / `staging` / `gov-prod`). -- **Scheduled health checks** — drive `McpRegistry::record_health` from the +- **Scheduled health checks** - drive `McpRegistry::record_health` from the existing scheduler crate. ## Longer term -- **Multi-tenant** — first-class organisation/tenant isolation across all stores. -- **Additional compliance frameworks** — GDPR, NIST, ISO 27001 mappings +- **Multi-tenant** - first-class organisation/tenant isolation across all stores. +- **Additional compliance frameworks** - GDPR, NIST, ISO 27001 mappings alongside UAE PDPL. -- **Retention enforcement jobs** — act on `is_past_retention` to purge or +- **Retention enforcement jobs** - act on `is_past_retention` to purge or archive data automatically (respecting investigation holds). -- **Marketplace ratings & reviews** — populate the `rating` field from real +- **Marketplace ratings & reviews** - populate the `rating` field from real installer feedback. diff --git a/docs/screenshots/README.md b/docs/screenshots/README.md index c6ab8c1..bbc9000 100644 --- a/docs/screenshots/README.md +++ b/docs/screenshots/README.md @@ -5,13 +5,13 @@ with `npm run dev`). This folder is a placeholder for control-plane UI captures. Planned views (add PNGs here as the control-plane UI is built): -- `registry.png` — Agent Registry list with risk/lifecycle badges -- `governance.png` — Approval queue and change history -- `observability.png` — Fleet dashboard (task/cost/latency/risk) -- `gateway.png` — Security decision detail with denial reasons -- `mcp.png` — MCP server catalogue and health -- `marketplace.png` — Verified agent templates -- `compliance.png` — Department compliance summary +- `registry.png` - Agent Registry list with risk/lifecycle badges +- `governance.png` - Approval queue and change history +- `observability.png` - Fleet dashboard (task/cost/latency/risk) +- `gateway.png` - Security decision detail with denial reasons +- `mcp.png` - MCP server catalogue and health +- `marketplace.png` - Verified agent templates +- `compliance.png` - Department compliance summary -> Placeholders only — no images are committed yet. Drop captures in this folder +> Placeholders only - no images are committed yet. Drop captures in this folder > and reference them from the README once the control-plane screens are live. diff --git a/docs/security-disclaimer.md b/docs/security-disclaimer.md index 5610ef3..75d488d 100644 --- a/docs/security-disclaimer.md +++ b/docs/security-disclaimer.md @@ -9,7 +9,7 @@ compliant. Read this before relying on it. The underlying runtime connects to real messaging surfaces (WhatsApp, Telegram, Discord, Slack, …). Inbound messages, tool outputs, and MCP responses are **untrusted input** and may attempt prompt injection. The Security Gateway gates -*capabilities* (which tool/MCP/model/data an action may use) — it does not, on +*capabilities* (which tool/MCP/model/data an action may use) - it does not, on its own, sanitise content. Keep untrusted execution sandboxed (the runtime supports Docker isolation). @@ -17,7 +17,7 @@ supports Docker isolation). - It enforces the policies **you configure**. A permissive `SecurityPolicy` permits permissive behaviour. -- Approval actions currently trust the supplied actor identity — **add +- Approval actions currently trust the supplied actor identity - **add authentication/RBAC** (SSO/AD) before production. See [limitations](limitations.md). - Digital signatures over audit evidence are a **placeholder**; do not treat unsigned evidence as cryptographically attested. diff --git a/docs/security-gateway.md b/docs/security-gateway.md index 1f874fb..f1b91e6 100644 --- a/docs/security-gateway.md +++ b/docs/security-gateway.md @@ -3,17 +3,17 @@  The Security Gateway (`clawforge_controlplane::gateway`) is the enforcement -point: **every agent action is checked before execution**. It is deny-by-reason -— an action is allowed only if no check objects. +point: **every agent action is checked before execution**. It is deny-by-reason: +an action is allowed only if no check objects. ## Inputs -- **`SecurityPolicy`** — the capabilities and limits in force: human-approval +- **`SecurityPolicy`** - the capabilities and limits in force: human-approval requirement, external network / file export / database write / PII toggles, a data-sensitivity ceiling, and a budget limit. `SecurityPolicy::default()` is a conservative government-grade posture; `::permissive()` suits trusted internal automation. -- **`ActionRequest`** — the agent's current registry record plus the specifics +- **`ActionRequest`** - the agent's current registry record plus the specifics of the attempted action (tool, MCP server, model, data sensitivity, estimated cost, spend so far, and capability flags). diff --git a/docs/uae-pdpl.md b/docs/uae-pdpl.md index 218129b..1d99e2f 100644 --- a/docs/uae-pdpl.md +++ b/docs/uae-pdpl.md @@ -1,4 +1,4 @@ -# UAE PDPL — Awareness Note +# UAE PDPL - Awareness Note > **Disclaimer:** This note is an engineering aid, not legal advice. It > summarises how ClawForge's compliance pack *maps to* commonly-cited UAE diff --git a/docs/use-cases.md b/docs/use-cases.md index cb70fcd..221a096 100644 --- a/docs/use-cases.md +++ b/docs/use-cases.md @@ -9,23 +9,23 @@ How the control-plane modules combine into end-to-end workflows. Every ClawForge deployment follows the same governed lifecycle, regardless of industry: -1. **Publish or register** — a team registers an agent (or installs a verified +1. **Publish or register** - a team registers an agent (or installs a verified one from the **Marketplace**), landing it in the **Registry** as `Draft`. -2. **Govern** — the agent is submitted to the **Governance Engine**; an approver +2. **Govern** - the agent is submitted to the **Governance Engine**; an approver signs off with a recorded reason. On approval it moves to `Active`. -3. **Classify** — a **Compliance Policy** sets the agent's PII classification, +3. **Classify** - a **Compliance Policy** sets the agent's PII classification, retention, export control, and (for sensitive data) an approval chain. -4. **Run under guard** — at execution time the **Security Gateway** checks each +4. **Run under guard** - at execution time the **Security Gateway** checks each action (tool/MCP/model/data/budget/approval) and emits an allow/deny decision with a risk score; denials are logged. -5. **Observe** — every action emits **Observability** events feeding per-agent +5. **Observe** - every action emits **Observability** events feeding per-agent and fleet dashboards. -6. **Audit & report** — governance history, blocked-execution logs, integration +6. **Audit & report** - governance history, blocked-execution logs, integration audit trails, and signed **Audit Evidence** roll up into **Compliance Reports**. ```rust -// Sketch — see each module's doc for the full API. +// Sketch - see each module's doc for the full API. let agent = marketplace.install(&listing.id, ®istry, "Permit Bot", "team-a", "Licensing")?; let req = governance.submit(/* approval request for agent */)?; governance.approve(&req.id, "ciso", "meets data-access policy")?; diff --git a/orchestration/README.md b/orchestration/README.md index cbbea87..ec236a7 100644 --- a/orchestration/README.md +++ b/orchestration/README.md @@ -1,2 +1,2 @@ # Orchestration -> Phase 5: Docker, Kubernetes, Terraform — coming later. +> Phase 5: Docker, Kubernetes, Terraform - coming later. diff --git a/testing/README.md b/testing/README.md index 0f71016..ea12932 100644 --- a/testing/README.md +++ b/testing/README.md @@ -1,2 +1,2 @@ # Testing -> Phase 6: E2E, performance benchmarks, security audit — coming later. +> Phase 6: E2E, performance benchmarks, security audit - coming later.