From fb389f84b211c86833e82768d381348f495c646c Mon Sep 17 00:00:00 2001 From: Robert Dean Date: Sun, 9 Nov 2025 10:41:04 -0500 Subject: [PATCH 1/3] Expand MVP RFC with architecture and planning details --- rfcs/RFC-0001-driftcore-mvp.md | 104 ++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 2 deletions(-) diff --git a/rfcs/RFC-0001-driftcore-mvp.md b/rfcs/RFC-0001-driftcore-mvp.md index 5ee325a..1f5c0e5 100644 --- a/rfcs/RFC-0001-driftcore-mvp.md +++ b/rfcs/RFC-0001-driftcore-mvp.md @@ -12,13 +12,113 @@ This RFC captures the goals, architecture, and non-goals for the DriftCore minim - Offer a containerized Drupal 11 sandbox that mirrors the metadata shared by the MCP server. - Establish a CI workflow that validates builds, static analysis, unit tests, and integration smoke tests for both packages. +## MVP Scope + +### Resources + +- `schema.entityTypes`: Canonical Drupal entity type definitions harvested via Drush and serialized as JSON Schema for the MCP resources API. +- `schema.fields`: Field storage and field instance metadata, normalized for agent consumption. +- `config.exported`: Exported Drupal configuration with checksum metadata so agents can reason about drift. +- `config.state`: Read-only snapshot of stateful configuration that is safe to surface to agents. +- `docs.guides`: Curated quick-start documentation that can be displayed directly in the copilot UI. + +### Tools + +- `drush.cacheRebuild`: Clears Drupal caches and returns status output/logging for the agent transcript. +- `drush.configExport`: Produces a tarball or directory reference that agents can download for analysis. +- `drush.entitySchema`: On-demand schema refresh for a specific entity type when the sandbox changes. +- `scaffold.module`: Generates Drupal module boilerplate in the sandbox using pluggable templates. +- `qa.runTests`: Executes the QA command chain defined under the Testing Strategy section. + +### Flagship Workflows + +1. **Metadata Inspection** – The copilot requests `schema.entityTypes` and `schema.fields`, summarizes differences against prior runs, and recommends schema-aligned code scaffolds. +2. **Safe Experimentation Loop** – The agent runner scaffolds a module, applies targeted changes, runs `qa.runTests`, and reverts the sandbox between iterations. +3. **Configuration Drift Analysis** – The copilot fetches `config.exported`, compares it to a baseline digest, and suggests remediation steps using `drush.configExport` and `drush.cacheRebuild`. + ## Architecture +``` ++----------------+ HTTP / STDIO +--------------------+ +| Copilot (UI) | <--------------------> | MCP Server API | ++----------------+ +---------+----------+ + | + | SDK Generation / Tool Calls + v + +--------+---------+ + | Agent Runner VM | + +--------+---------+ + | + | Drush / Filesystem / DB + v + +-------------+--------------+ + | Drupal 11 Sandbox (Docker) | + +----------------------------+ +``` + +### Component Overview + - **MCP Server (`@driftcore/server`)**: Provides HTTP and STDIO transports. Default resources are generated from canonical Drupal metadata and are available over `/resources`. Drush tooling is exposed via the `/tools` endpoint. -- **Agent Runner (`@driftcore/agent-runner`)**: Fetches resources from the MCP server, generates a TypeScript SDK, and executes bootstrap code inside a VM-backed sandbox. -- **Drupal Sandbox**: Docker Compose project (`examples/drupal-sandbox`) with Drupal 11 and MariaDB containers. Configuration exports are mounted for inspection. +- **Agent Runner (`@driftcore/agent-runner`)**: Fetches resources from the MCP server, generates a TypeScript SDK, and executes bootstrap code inside a VM-backed sandbox. Handles workflow orchestration and safe rollback for experiments. +- **Copilot Extension (`apps/copilot-extension`)**: Presents resources, tool results, and workflow progress to the user. Provides UX affordances for the flagship workflows. +- **Drupal Sandbox**: Docker Compose project (`examples/drupal-sandbox`) with Drupal 11 and MariaDB containers. Configuration exports are mounted for inspection and synchronization with the MCP server. - **Continuous Integration**: GitHub Actions workflow builds each package, runs type-checking lint, executes unit tests with Node's test runner, and performs smoke-level integration checks. +## Agent Runner Behavior + +- Periodically refreshes the MCP server catalog and regenerates the SDK when resource metadata changes. +- Executes workflows in isolated VM processes with explicit timeouts and resource limits. +- Persists run metadata (tool invocations, outputs, status) for observability hooks. +- Provides resumable sessions: in the event of interruption the runner can resume from the last completed step of a flagship workflow. +- Emits structured events to the copilot extension for display and to external telemetry sinks. + +## Security Defaults + +- Sandbox containers run with non-root users, readonly mounts for exported configuration, and no outbound network access by default. +- Drush commands exposed as tools are constrained to a vetted allowlist with argument validation. +- Secrets required by Drupal (database credentials, salts) are injected via `.env` files that are never surfaced through MCP resources. +- Agent runner executes user-provided code inside firecracker-style microVMs with filesystem snapshots to guarantee rollback. +- Telemetry endpoints require signed requests to prevent command injection through observability pipelines. + +## Developer Experience & Observability + +- Ship TypeScript SDKs with inline JSDoc generated from MCP resource metadata for autocompletion in editors. +- Provide verbose logging toggles (`DEBUG=driftcore:*`) covering MCP transport, tool execution, and sandbox orchestration. +- Expose Prometheus-compatible metrics from the agent runner (workflow duration, tool error rates, sandbox resets). +- Include structured audit logs for tool invocations, linked back to copilot sessions for review. +- Document common troubleshooting scenarios and CLI recipes in `docs/guides` surfaced via the `docs.guides` resource. + +## Testing Strategy + +- **Unit Tests**: Cover MCP resource serialization, tool adapters, and agent runner orchestration primitives. +- **Integration Tests**: Stand up the Drupal sandbox, run the agent runner against mock workflows, and verify end-to-end success criteria. +- **QA Command Chain**: `pnpm lint`, `pnpm test`, `pnpm --filter @driftcore/server test:integration`, and sandbox smoke tests triggered via `qa.runTests`. +- **Contract Tests**: Validate SDK generation against canonical MCP schema snapshots to ensure backwards compatibility. +- **Performance Probes**: Measure tool round-trip latency and sandbox reset times with thresholds enforced in CI. + +## Milestones + +- **M0 – Project Skeleton**: Repository setup, package workspaces, basic CI lint/test wiring. +- **M1 – MCP Foundation**: Implement core resources (`schema.entityTypes`, `config.exported`) and expose Drush tooling via HTTP. +- **M2 – Agent Runner Alpha**: SDK generation, VM sandbox execution, and the Metadata Inspection workflow. +- **M3 – Sandbox Experimentation**: Scaffold module tooling, Safe Experimentation Loop workflow, integration test coverage. +- **M4 – Observability & Hardening**: Telemetry pipelines, security defaults enforced, configuration drift workflow, release candidate readiness. + +## Versioning + +- Use semantic versioning per package with an MVP cap of `0.1.0` until workflows stabilize. +- Tag milestone completions with annotated git tags (`m0`, `m1`, …) to signal checkpoints. +- Maintain changelog entries in `CHANGELOG.md` per package, updated via PR templates. +- Enforce compatibility guarantees for MCP resource shapes and tool contracts once the MVP reaches `0.5.0`. + +## Open Questions + +- Should the MCP server stream resource diffs or require full fetches for large configuration exports? +- What is the minimum viable telemetry sink (self-hosted Loki vs. managed service) for observability launch? +- How should secrets rotation be automated for the sandbox environment without exposing credentials to agents? +- Can the agent runner reuse VM snapshots across workflows to reduce startup latency without sacrificing isolation? +- What governance process should review additions to the MCP tool allowlist to prevent privilege escalation? + ## Non-goals - Full MCP protocol compliance (message envelopes, session management) is deferred to a future iteration. From cb822f22ff535e13b7ddd371fc4511b31eed08b4 Mon Sep 17 00:00:00 2001 From: Robert Dean Date: Sun, 9 Nov 2025 16:21:43 -0500 Subject: [PATCH 2/3] Refine MVP RFC to align with latest planning --- rfcs/RFC-0001-driftcore-mvp.md | 132 ++++++++++++++++++--------------- 1 file changed, 72 insertions(+), 60 deletions(-) diff --git a/rfcs/RFC-0001-driftcore-mvp.md b/rfcs/RFC-0001-driftcore-mvp.md index 1f5c0e5..3e9cef1 100644 --- a/rfcs/RFC-0001-driftcore-mvp.md +++ b/rfcs/RFC-0001-driftcore-mvp.md @@ -2,48 +2,52 @@ ## Summary -This RFC captures the goals, architecture, and non-goals for the DriftCore minimum viable product. The MVP focuses on enabling automation agents to introspect Drupal metadata, trigger Drush commands, and experiment safely in a sandboxed Drupal 11 environment. +This RFC defines the vision, boundaries, and delivery milestones for the DriftCore minimum viable product. The MVP empowers automation agents to introspect Drupal metadata, execute vetted Drush commands, and iterate safely inside a sandboxed Drupal 11 environment while feeding actionable guidance back to a copilot interface. ## Goals -- Provide an MCP server that exposes Drupal schema and configuration as machine-readable resources (`schema.entityTypes`, `config.exported`). -- Surface Drush commands (`drush.cacheRebuild`, `drush.configExport`) through the MCP tool catalog. -- Deliver an agent runner that can generate a language SDK from the server resources and execute code safely in a sandbox. -- Offer a containerized Drupal 11 sandbox that mirrors the metadata shared by the MCP server. -- Establish a CI workflow that validates builds, static analysis, unit tests, and integration smoke tests for both packages. +- Provide a Machine Control Protocol (MCP) server that exposes Drupal schema and configuration as machine-readable resources such as `schema.entityTypes` and `config.exported`. +- Publish an allowlisted catalog of tools—including `drush.cacheRebuild`, `drush.configExport`, and scaffolding utilities—that agents can invoke through the MCP transport. +- Deliver an agent runner capable of generating a language SDK from the MCP schema, executing workflows in isolated sandboxes, and reporting progress to the copilot. +- Offer a containerized Drupal 11 sandbox that mirrors the metadata surfaced by the MCP server so agents can round-trip changes predictably. +- Establish a CI workflow that validates builds, static analysis, unit tests, and integration smoke tests across all packages. ## MVP Scope ### Resources -- `schema.entityTypes`: Canonical Drupal entity type definitions harvested via Drush and serialized as JSON Schema for the MCP resources API. -- `schema.fields`: Field storage and field instance metadata, normalized for agent consumption. -- `config.exported`: Exported Drupal configuration with checksum metadata so agents can reason about drift. -- `config.state`: Read-only snapshot of stateful configuration that is safe to surface to agents. -- `docs.guides`: Curated quick-start documentation that can be displayed directly in the copilot UI. +| Identifier | Description | Format | +| --- | --- | --- | +| `schema.entityTypes` | Canonical Drupal entity type definitions harvested via Drush and serialized for MCP consumption. | JSON Schema | +| `schema.fields` | Field storage and instance metadata normalized for agents. | JSON Schema | +| `config.exported` | Exported configuration snapshots with digests so agents can reason about drift. | TAR reference + manifest | +| `config.state` | Read-only snapshot of stateful configuration that is safe to expose (e.g., feature flags). | JSON | +| `docs.guides` | Curated quick-start and troubleshooting documentation surfaced in the copilot UI. | Markdown | ### Tools -- `drush.cacheRebuild`: Clears Drupal caches and returns status output/logging for the agent transcript. -- `drush.configExport`: Produces a tarball or directory reference that agents can download for analysis. -- `drush.entitySchema`: On-demand schema refresh for a specific entity type when the sandbox changes. -- `scaffold.module`: Generates Drupal module boilerplate in the sandbox using pluggable templates. -- `qa.runTests`: Executes the QA command chain defined under the Testing Strategy section. +| Identifier | Purpose | Notes | +| --- | --- | --- | +| `drush.cacheRebuild` | Clears Drupal caches and returns structured logs for the agent transcript. | Supports subset of flags with validation. | +| `drush.configExport` | Produces a tarball reference that agents can download for configuration diffing. | Output stored in sandbox artifacts volume. | +| `drush.entitySchema` | Triggers a schema refresh for a specific entity type when the sandbox changes. | Requires entity type argument. | +| `scaffold.module` | Generates Drupal module boilerplate using pluggable templates. | Respects sandbox namespace conventions. | +| `qa.runTests` | Executes the QA command chain defined in the Testing Strategy section. | Equivalent to running `pnpm lint && pnpm test && pnpm --filter @driftcore/server test:integration`. | ### Flagship Workflows -1. **Metadata Inspection** – The copilot requests `schema.entityTypes` and `schema.fields`, summarizes differences against prior runs, and recommends schema-aligned code scaffolds. +1. **Metadata Inspection** – The copilot requests `schema.entityTypes` and `schema.fields`, summarizes deltas versus previous runs, and recommends schema-aligned scaffolds. 2. **Safe Experimentation Loop** – The agent runner scaffolds a module, applies targeted changes, runs `qa.runTests`, and reverts the sandbox between iterations. -3. **Configuration Drift Analysis** – The copilot fetches `config.exported`, compares it to a baseline digest, and suggests remediation steps using `drush.configExport` and `drush.cacheRebuild`. +3. **Configuration Drift Analysis** – The copilot fetches `config.exported`, compares it with a baseline digest, and proposes remediation steps using `drush.configExport` and `drush.cacheRebuild`. -## Architecture +## Architecture Overview -``` +```text +----------------+ HTTP / STDIO +--------------------+ -| Copilot (UI) | <--------------------> | MCP Server API | +| Copilot (UI) | <--------------------> | MCP Server API | +----------------+ +---------+----------+ | - | SDK Generation / Tool Calls + | SDK generation / Tool calls v +--------+---------+ | Agent Runner VM | @@ -56,65 +60,73 @@ This RFC captures the goals, architecture, and non-goals for the DriftCore minim +----------------------------+ ``` -### Component Overview +### Component Listing -- **MCP Server (`@driftcore/server`)**: Provides HTTP and STDIO transports. Default resources are generated from canonical Drupal metadata and are available over `/resources`. Drush tooling is exposed via the `/tools` endpoint. -- **Agent Runner (`@driftcore/agent-runner`)**: Fetches resources from the MCP server, generates a TypeScript SDK, and executes bootstrap code inside a VM-backed sandbox. Handles workflow orchestration and safe rollback for experiments. -- **Copilot Extension (`apps/copilot-extension`)**: Presents resources, tool results, and workflow progress to the user. Provides UX affordances for the flagship workflows. -- **Drupal Sandbox**: Docker Compose project (`examples/drupal-sandbox`) with Drupal 11 and MariaDB containers. Configuration exports are mounted for inspection and synchronization with the MCP server. -- **Continuous Integration**: GitHub Actions workflow builds each package, runs type-checking lint, executes unit tests with Node's test runner, and performs smoke-level integration checks. +- **MCP Server (`@driftcore/server`)** – Provides HTTP and STDIO transports. Default resources derive from canonical Drupal metadata and are served through `/resources`. Tool adapters are exposed via `/tools` with allowlisted arguments. +- **Agent Runner (`@driftcore/agent-runner`)** – Fetches resources from the MCP server, generates a TypeScript SDK, and orchestrates workflows inside VM-backed sandboxes with rollback guarantees. +- **Copilot Extension (`apps/copilot-extension`)** – Displays resources, tool results, and workflow progress. Offers UX affordances to kick off flagship workflows and review telemetry. +- **Drupal Sandbox (`examples/drupal-sandbox`)** – Docker Compose environment with Drupal 11 and MariaDB containers. Configuration exports are mounted for inspection and synchronization with the MCP server. +- **Continuous Integration** – GitHub Actions pipeline builds each package, runs linting and unit tests, and performs smoke-level integration checks, mirroring the `qa.runTests` chain. ## Agent Runner Behavior -- Periodically refreshes the MCP server catalog and regenerates the SDK when resource metadata changes. -- Executes workflows in isolated VM processes with explicit timeouts and resource limits. -- Persists run metadata (tool invocations, outputs, status) for observability hooks. -- Provides resumable sessions: in the event of interruption the runner can resume from the last completed step of a flagship workflow. -- Emits structured events to the copilot extension for display and to external telemetry sinks. +- Polls the MCP server catalog for changes and regenerates the SDK when resource metadata shifts. +- Executes workflows in isolated microVM processes with strict CPU, memory, and wall-clock limits. +- Persists run metadata (tool invocations, outputs, and status) for observability hooks and resumability. +- Supports resumable sessions so interrupted runs restart from the last completed workflow step. +- Emits structured events consumable by the copilot extension and external telemetry sinks. ## Security Defaults -- Sandbox containers run with non-root users, readonly mounts for exported configuration, and no outbound network access by default. -- Drush commands exposed as tools are constrained to a vetted allowlist with argument validation. -- Secrets required by Drupal (database credentials, salts) are injected via `.env` files that are never surfaced through MCP resources. -- Agent runner executes user-provided code inside firecracker-style microVMs with filesystem snapshots to guarantee rollback. -- Telemetry endpoints require signed requests to prevent command injection through observability pipelines. +- Sandbox containers run as non-root users with read-only mounts for exported configuration and no outbound network access by default. +- Drush tools are constrained to a vetted allowlist, enforce argument validation, and redact sensitive output. +- Secrets required by Drupal (database credentials, salts) are injected via `.env` files that never surface through MCP resources. +- Agent-executed code runs inside snapshot-based microVMs to guarantee rollback after each workflow iteration. +- Telemetry webhooks require signed requests to prevent command injection through observability pipelines. + +## Developer Experience Expectations + +- Publish TypeScript SDKs with inline JSDoc generated from MCP resource metadata for rich autocompletion. +- Provide verbose logging toggles (`DEBUG=driftcore:*`) that cover MCP transport, tool execution, and sandbox orchestration. +- Document common troubleshooting scenarios and CLI recipes in `docs/guides`, surfaced via the `docs.guides` resource. +- Maintain examples in `examples/` demonstrating how to combine resources and tools for each flagship workflow. -## Developer Experience & Observability +## Observability Expectations -- Ship TypeScript SDKs with inline JSDoc generated from MCP resource metadata for autocompletion in editors. -- Provide verbose logging toggles (`DEBUG=driftcore:*`) covering MCP transport, tool execution, and sandbox orchestration. - Expose Prometheus-compatible metrics from the agent runner (workflow duration, tool error rates, sandbox resets). -- Include structured audit logs for tool invocations, linked back to copilot sessions for review. -- Document common troubleshooting scenarios and CLI recipes in `docs/guides` surfaced via the `docs.guides` resource. +- Emit structured audit logs for every tool invocation, linked back to copilot sessions for human review. +- Capture sandbox snapshots and workflow transcripts as artifacts accessible through the copilot UI. +- Provide alerting defaults for prolonged workflow runtimes, repeated sandbox rollbacks, and failed QA chains. ## Testing Strategy -- **Unit Tests**: Cover MCP resource serialization, tool adapters, and agent runner orchestration primitives. -- **Integration Tests**: Stand up the Drupal sandbox, run the agent runner against mock workflows, and verify end-to-end success criteria. -- **QA Command Chain**: `pnpm lint`, `pnpm test`, `pnpm --filter @driftcore/server test:integration`, and sandbox smoke tests triggered via `qa.runTests`. -- **Contract Tests**: Validate SDK generation against canonical MCP schema snapshots to ensure backwards compatibility. -- **Performance Probes**: Measure tool round-trip latency and sandbox reset times with thresholds enforced in CI. +- **Unit Tests** – Cover MCP resource serialization, tool adapters, and agent runner orchestration primitives. +- **Integration Tests** – Stand up the Drupal sandbox, run the agent runner against mock workflows, and verify end-to-end success criteria. +- **QA Command Chain** – `pnpm lint`, `pnpm test`, and `pnpm --filter @driftcore/server test:integration`, orchestrated collectively via `qa.runTests`. +- **Contract Tests** – Validate SDK generation against canonical MCP schema snapshots to ensure backward compatibility. +- **Performance Probes** – Measure tool round-trip latency and sandbox reset times with thresholds enforced in CI. -## Milestones +## Milestones (M0–M4) -- **M0 – Project Skeleton**: Repository setup, package workspaces, basic CI lint/test wiring. -- **M1 – MCP Foundation**: Implement core resources (`schema.entityTypes`, `config.exported`) and expose Drush tooling via HTTP. -- **M2 – Agent Runner Alpha**: SDK generation, VM sandbox execution, and the Metadata Inspection workflow. -- **M3 – Sandbox Experimentation**: Scaffold module tooling, Safe Experimentation Loop workflow, integration test coverage. -- **M4 – Observability & Hardening**: Telemetry pipelines, security defaults enforced, configuration drift workflow, release candidate readiness. +| Milestone | Scope | Exit Criteria | +| --- | --- | --- | +| **M0 – Project Skeleton** | Repository setup, package workspaces, and baseline CI lint/test wiring. | Lerna/PNPM workspaces defined, CI green on scaffolding commit. | +| **M1 – MCP Foundation** | Implement core resources (`schema.entityTypes`, `config.exported`) and expose Drush tooling over HTTP/STDIO. | MCP server returns canonical data; `drush.cacheRebuild` callable via MCP. | +| **M2 – Agent Runner Alpha** | SDK generation, VM sandbox execution, and Metadata Inspection workflow. | Agent runner completes Metadata Inspection end-to-end with telemetry. | +| **M3 – Sandbox Experimentation** | Module scaffolding tooling and Safe Experimentation Loop workflow plus integration coverage. | `scaffold.module` + `qa.runTests` loop succeeds inside sandbox CI job. | +| **M4 – Observability & Hardening** | Telemetry pipelines, security enforcement, configuration drift workflow, release candidate readiness. | Drift analysis workflow operational; observability dashboards populated; release notes drafted. | -## Versioning +## Versioning Strategy - Use semantic versioning per package with an MVP cap of `0.1.0` until workflows stabilize. - Tag milestone completions with annotated git tags (`m0`, `m1`, …) to signal checkpoints. -- Maintain changelog entries in `CHANGELOG.md` per package, updated via PR templates. -- Enforce compatibility guarantees for MCP resource shapes and tool contracts once the MVP reaches `0.5.0`. +- Maintain per-package changelog entries in `CHANGELOG.md`, updated through the pull-request template. +- Enforce compatibility guarantees for MCP resource shapes and tool contracts once the MVP reaches version `0.5.0`. ## Open Questions - Should the MCP server stream resource diffs or require full fetches for large configuration exports? -- What is the minimum viable telemetry sink (self-hosted Loki vs. managed service) for observability launch? +- What is the minimum viable telemetry sink (self-hosted Loki versus managed service) for launch? - How should secrets rotation be automated for the sandbox environment without exposing credentials to agents? - Can the agent runner reuse VM snapshots across workflows to reduce startup latency without sacrificing isolation? - What governance process should review additions to the MCP tool allowlist to prevent privilege escalation? @@ -122,6 +134,6 @@ This RFC captures the goals, architecture, and non-goals for the DriftCore minim ## Non-goals - Full MCP protocol compliance (message envelopes, session management) is deferred to a future iteration. -- Production-grade sandbox isolation and resource quotas. +- Production-grade sandbox isolation and resource quotas beyond the documented defaults. - Automated Drupal installation or configuration management beyond the provided example export. -- SDK generation for languages other than TypeScript. +- SDK generation for languages other than TypeScript during the MVP phase. From 937db8d4838a56c8be756c2bb1e724ce79535bb6 Mon Sep 17 00:00:00 2001 From: Robert Dean Date: Sun, 9 Nov 2025 16:42:13 -0500 Subject: [PATCH 3/3] docs: consolidate developer experience and observability --- rfcs/RFC-0001-driftcore-mvp.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/rfcs/RFC-0001-driftcore-mvp.md b/rfcs/RFC-0001-driftcore-mvp.md index 3e9cef1..1107034 100644 --- a/rfcs/RFC-0001-driftcore-mvp.md +++ b/rfcs/RFC-0001-driftcore-mvp.md @@ -84,19 +84,23 @@ This RFC defines the vision, boundaries, and delivery milestones for the DriftCo - Agent-executed code runs inside snapshot-based microVMs to guarantee rollback after each workflow iteration. - Telemetry webhooks require signed requests to prevent command injection through observability pipelines. -## Developer Experience Expectations +## Developer Experience & Observability Expectations + +### Developer Experience - Publish TypeScript SDKs with inline JSDoc generated from MCP resource metadata for rich autocompletion. - Provide verbose logging toggles (`DEBUG=driftcore:*`) that cover MCP transport, tool execution, and sandbox orchestration. - Document common troubleshooting scenarios and CLI recipes in `docs/guides`, surfaced via the `docs.guides` resource. - Maintain examples in `examples/` demonstrating how to combine resources and tools for each flagship workflow. +- Offer project generators and scaffolds (`create-driftcore-app`) that encode recommended defaults for new adopters. -## Observability Expectations +### Observability - Expose Prometheus-compatible metrics from the agent runner (workflow duration, tool error rates, sandbox resets). - Emit structured audit logs for every tool invocation, linked back to copilot sessions for human review. - Capture sandbox snapshots and workflow transcripts as artifacts accessible through the copilot UI. - Provide alerting defaults for prolonged workflow runtimes, repeated sandbox rollbacks, and failed QA chains. +- Maintain Grafana-ready dashboards and runbooks that highlight MCP latency spikes and sandbox health regressions. ## Testing Strategy