capability-compiler 0.1.0__tar.gz

capability_compiler-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+.claude/
+implementation_plan.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Local state
+*.sqlite3
+*.db
+capability-compiler.toml
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Secrets — never commit
+.env
+.env.*
+

capability_compiler-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Capability Compiler Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

capability_compiler-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.5
+Name: capability-compiler
+Version: 0.1.0
+Summary: Turn any software into an API for AI: compile interaction trajectories into verified, reusable capabilities exposed via Python, CLI, and MCP.
+Project-URL: Homepage, https://github.com/capability-compiler/capability-compiler
+Project-URL: Documentation, https://github.com/capability-compiler/capability-compiler/tree/main/docs
+Project-URL: Issues, https://github.com/capability-compiler/capability-compiler/issues
+Author: Capability Compiler Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,automation,browser-automation,capability-learning,gui-agents,llm,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: platformdirs<5,>=4.2
+Requires-Dist: pydantic-settings<3,>=2.3
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: anthropic
+Requires-Dist: httpx>=0.27; extra == 'anthropic'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.45; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: models
+Requires-Dist: httpx>=0.27; extra == 'models'
+Provides-Extra: ollama
+Requires-Dist: httpx>=0.27; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: httpx>=0.27; extra == 'openai'
+Provides-Extra: sqlite
+Description-Content-Type: text/markdown
+
+# Capability Compiler
+
+> **Turn any software into an API for AI.**
+
+Capability Compiler observes black-box software, explores it safely, and
+compiles interaction trajectories into **verified, reusable capabilities** —
+exposed to any LLM through Python APIs, the `cc` CLI, and the Model Context
+Protocol (MCP). Fully local-first: the default configuration runs offline
+with no account and no telemetry.
+
+```text
+UNKNOWN SOFTWARE ─▶ OBSERVE ─▶ EXPLORE ─▶ COMPILE ─▶ VERIFY ─▶ REUSE
+                                                                  │
+                                          ┌───────────────────────┼───────────────────────┐
+                                          ▼                       ▼                       ▼
+                                    `cc execute`           `cc serve` (MCP)         Python API
+```
+
+## What does this do?
+
+Capability Compiler records how an application responds to actions, classifies
+those responses with deterministic semantic-state diffs, and turns the result
+into a typed, versioned, permission-scoped **Capability** artifact — a unit
+of reusable software control that any LLM can call via MCP. The output is
+*executable without an LLM in the loop*: it carries inputs, preconditions,
+postconditions, verifiers, and confidence derived from execution evidence.
+
+## Why does it exist?
+
+Every adjacent project — record/replay tools, GUI-agent libraries, skill
+distributors — stops one or two steps short of the full pipeline. Capability
+Compiler ships the whole pipeline as a **compiler**, with the properties
+compilers have: determinism where possible, typed artifacts, reproducible
+outputs, and versioned inputs/outputs. See
+[`docs/research/differentiation.md`](docs/research/differentiation.md) for
+the detailed thesis, and [`docs/research/landscape.md`](docs/research/landscape.md)
+for the ecosystem map that motivated it.
+
+Five differentiators in one line each:
+
+1. **Trajectories → parameterized capabilities** (not replays, not prompts).
+2. **Verification manufactured, not hand-written** (synthesized from the
+   observed state diffs).
+3. **Cross-run element re-anchoring** (semantic refs survive DOM drift).
+4. **Trust data attached to executable artifacts** (fingerprint,
+   provenance, evidence-based score, deny-by-default permissions).
+5. **Local-first, offline-complete** (mock provider runs the whole pipeline
+   with zero network).
+
+## Quick start
+
+```bash
+# 1. Install (Python 3.11+; MCP transport included by default)
+pip install capability-compiler                  # everything except adapters/providers below
+pip install capability-compiler[browser]         # add the Playwright adapter
+pip install capability-compiler[models]          # add Anthropic / OpenAI / Ollama providers
+
+# 2. Verify the install
+cc doctor
+
+# 3. Inspect effective configuration
+cc config show
+
+# 4. Learn a capability from a local app (fake adapter, no browser needed)
+cc learn "export a pdf" --adapter fake --name export_pdf
+
+# 5. Run it through the gate-ordered executor
+cc execute export_pdf --key format=pdf --key file_name=report.pdf
+
+# 6. Browse what you have
+cc capabilities
+cc inspect export_pdf
+
+# 7. Serve every capability as MCP tools (stdio for editor clients)
+cc serve --transport stdio
+cc serve --transport http --host 127.0.0.1 --port 8765 --token "$CC_MCP_TOKEN"
+```
+
+Every command supports `--json` for machine-readable output. Pass `--verbose`
+(`-v`) at the top level to bump logging to DEBUG; set `CC_DEBUG=1` to print
+full tracebacks instead of structured error messages.
+
+### Python quick start
+
+```python
+import asyncio
+from capability_compiler import Compiler, CompilerSettings, CapabilityRegistry
+
+async def main() -> None:
+    compiler = Compiler()                    # offline-safe defaults (mock provider)
+    async with compiler:                     # connect/disconnect bracket
+        observation = await compiler.observe()
+        report = await compiler.explore(max_steps=20)
+        if compiler.exploration and compiler.exploration.trajectories:
+            capability = await compiler.synthesize(
+                compiler.exploration.trajectories[-1],
+                goal_hint="export a pdf",
+            )
+            registry = CapabilityRegistry.from_settings(CompilerSettings())
+            await registry.save(capability)
+            result = await compiler.execute(capability, {"format": "pdf"})
+            print(result.status.value, result.duration_ms)
+
+asyncio.run(main())
+```
+
+## Architecture summary
+
+The framework is layered so each phase delivers a coherent unit and each
+later phase builds on a stable contract from the previous one.
+
+| Layer | Module | Contract | Notes |
+|---|---|---|---|
+| Domain models | `capability_compiler.models` | Pydantic v2 data contracts | Single source of truth for capabilities, trajectories, actions, observations |
+| Errors | `capability_compiler.errors` | `CapabilityCompilerError` + 9-way `FailureCategory` taxonomy | Every failure classifies exactly once |
+| Logging | `capability_compiler.logging` | Structured JSON or human formatter; secret redaction filter | Never logs API keys, even under odd key names |
+| Config | `capability_compiler.config` | Layered settings (defaults → TOML → `CC_*__*` env) | API keys only ever resolved from env vars |
+| Adapters | `capability_compiler.adapters` | `EnvironmentAdapter` protocol | `fake` (offline), `browser` (Playwright), `desktop` (skeleton) |
+| Providers | `capability_compiler.providers` | `ModelProvider` protocol | `mock`, `ollama`, `anthropic`, `openai`, `openai_compatible` |
+| Recording | `capability_compiler.recording` | `TrajectoryRecorder` + `Replayer` | Every action carries before/after state ids |
+| Perception | `capability_compiler.perception` | `SemanticState` + `StateDiff` (deterministic, no model) | `semantic-v1` fingerprint algorithm |
+| Exploration | `capability_compiler.exploration` | `ExplorationEngine` + `ActionSemanticsEngine` | Effect-first naming; UNKNOWN beats hallucination |
+| Synthesis | `capability_compiler.synthesis` | `CapabilitySynthesizer` | Trajectory → typed, templatized capability |
+| Runtime | `capability_compiler.runtime` | `CapabilityExecutor` (8-gate ordered) | Validate → permissions → confirm → preconditions → procedure → postconditions → record |
+| Verification | `capability_compiler.verification` | 8 verifier kinds (`state`, `dom`, `accessibility`, `file`, `visual`, `schema`, `custom`, `composite`) | Never accepts "exit code 0" as success |
+| Refinement | `capability_compiler.refinement` | `SelfImprovementEngine` + `CapabilityRepairer` | Deterministic repairs promoted only on test-pass |
+| Storage | `capability_compiler.storage` | `CapabilityStore` protocol | `FileCapabilityStore` (atomic writes + integrity check) and `SqliteCapabilityStore` |
+| Registry | `capability_compiler.registry` | `CapabilityRegistry` + `Permission` bitfield | Search, summaries, risk tagging, version-aware rollback |
+| Compiler | `capability_compiler.compiler` | The `Compiler` facade | Wires + supervises — algorithms live in engines |
+| CLI | `capability_compiler.cli` | The `cc` command | `version`, `doctor`, `config`, `capabilities`, `inspect`, `learn`, `execute`, `serve`, `benchmark` |
+| Server | `capability_compiler.server` | MCP transports (`stdio` and streamable `http`) | Bearer-token auth on the HTTP transport |
+
+The full overview lives at [`docs/architecture.md`](docs/architecture.md).
+Subsystem deep-dives live in [`docs/architecture/`](docs/architecture/).
+
+## Security posture
+
+Capability Compiler is **deny-by-default** at every layer:
+
+- `security.allow_network` and `security.allow_shell` both default to `false`.
+- `allowed_read_roots` and `allowed_write_roots` default to empty lists
+  (filesystem scope is opt-in per capability).
+- The browser adapter blocks navigation to non-loopback URLs unless
+  `security.allow_network=true`; failed navigation becomes a structured
+  `PERMISSION_DENIED`, never a crash.
+- API keys are referenced by env-var *name* in config; values are resolved at
+  call time and never persisted. The logging layer redacts by key name
+  (`api_key`, `token`, `secret`, `password`, `authorization`, `cookie`,
+  `credential`, `session_id`) and by value pattern (`Bearer …`, `sk-…`,
+  `gh[pousr]_…`) as a second line of defense.
+- Destructive capabilities (`permissions.destructive=true` or
+  `risk ≥ HIGH`) require explicit user confirmation by default; the CLI
+  prompts on a TTY and the executor accepts `confirmed=True` to skip.
+- Capabilities are **pure data** (JSON-serializable Pydantic models).
+  Nothing in a stored capability is ever evaluated as code.
+
+The complete threat model, scope of promises, and explicit non-goals are in
+[`SECURITY.md`](SECURITY.md). Local-first design choices are explained in
+[`docs/concepts/local-first.md`](docs/concepts/local-first.md).
+
+## How to contribute / how to extend
+
+Capability Compiler ships pluggable protocols at every cross-cutting
+boundary; subclasses are not required (Protocols are structural).
+
+| To add … | Use … |
+|---|---|
+| A new environment (browser, desktop, mobile, CLI) | `register_adapter(kind, factory)` in `capability_compiler.adapters.base` |
+| A new model backend (new vendor, new on-prem) | `register_provider(name, factory)` in `capability_compiler.providers.base` |
+| A new persistence backend (Redis, Postgres, S3) | Implement the `CapabilityStore` protocol in `capability_compiler.storage.base` |
+| A new check on capability outcomes | `register_verifier(kind, factory)` in `capability_compiler.verification.base` |
+| A new CLI command | Append a Typer command module under `src/capability_compiler/cli/` and register it in `main.py` |
+
+The differentiation thesis ([`docs/research/differentiation.md`](docs/research/differentiation.md))
+is the source of intent — please read it before opening a feature PR.
+The master plan ([`docs/master-plan.md`](docs/master-plan.md)) defines
+what is in scope and what is not. Development setup, test layout, and CI
+gates are in [`docs/ci.md`](docs/ci.md).
+
+## Benchmarks
+
+Capability Compiler ships an internal **CapabilityBench** suite used for
+sanity checks and gate reporting. It runs against the in-memory `fake`
+adapter so it never touches the network, a real OS, or a browser. See
+[`docs/benchmarks.md`](docs/benchmarks.md) for what is and isn't measured.
+
+## Documentation index
+
+- Concepts — [`docs/concepts/exploration.md`](docs/concepts/exploration.md),
+  [`docs/concepts/local-first.md`](docs/concepts/local-first.md)
+- Architecture — [`docs/architecture.md`](docs/architecture.md),
+  [`docs/architecture/registry.md`](docs/architecture/registry.md),
+  [`docs/architecture/mcp.md`](docs/architecture/mcp.md)
+- Adapters — [`docs/adapters/browser.md`](docs/adapters/browser.md)
+- Model providers — [`docs/models.md`](docs/models.md)
+- CLI reference — [`docs/cli/commands.md`](docs/cli/commands.md)
+- Benchmarks — [`docs/benchmarks.md`](docs/benchmarks.md)
+- CI / `cc doctor` — [`docs/ci.md`](docs/ci.md)
+- Research — [`docs/research/landscape.md`](docs/research/landscape.md),
+  [`docs/research/differentiation.md`](docs/research/differentiation.md)
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Acknowledgments
+
+Capability Compiler stands on the shoulders of projects whose work the
+[`docs/research/landscape.md`](docs/research/landscape.md) map credits in
+detail. The full production-readiness release was authored by the
+Capability Compiler contributors; see
+[`CHANGELOG.md`](CHANGELOG.md) for what shipped in each phase.

capability_compiler-0.1.0/README.md

@@ -0,0 +1,212 @@
+# Capability Compiler
+
+> **Turn any software into an API for AI.**
+
+Capability Compiler observes black-box software, explores it safely, and
+compiles interaction trajectories into **verified, reusable capabilities** —
+exposed to any LLM through Python APIs, the `cc` CLI, and the Model Context
+Protocol (MCP). Fully local-first: the default configuration runs offline
+with no account and no telemetry.
+
+```text
+UNKNOWN SOFTWARE ─▶ OBSERVE ─▶ EXPLORE ─▶ COMPILE ─▶ VERIFY ─▶ REUSE
+                                                                  │
+                                          ┌───────────────────────┼───────────────────────┐
+                                          ▼                       ▼                       ▼
+                                    `cc execute`           `cc serve` (MCP)         Python API
+```
+
+## What does this do?
+
+Capability Compiler records how an application responds to actions, classifies
+those responses with deterministic semantic-state diffs, and turns the result
+into a typed, versioned, permission-scoped **Capability** artifact — a unit
+of reusable software control that any LLM can call via MCP. The output is
+*executable without an LLM in the loop*: it carries inputs, preconditions,
+postconditions, verifiers, and confidence derived from execution evidence.
+
+## Why does it exist?
+
+Every adjacent project — record/replay tools, GUI-agent libraries, skill
+distributors — stops one or two steps short of the full pipeline. Capability
+Compiler ships the whole pipeline as a **compiler**, with the properties
+compilers have: determinism where possible, typed artifacts, reproducible
+outputs, and versioned inputs/outputs. See
+[`docs/research/differentiation.md`](docs/research/differentiation.md) for
+the detailed thesis, and [`docs/research/landscape.md`](docs/research/landscape.md)
+for the ecosystem map that motivated it.
+
+Five differentiators in one line each:
+
+1. **Trajectories → parameterized capabilities** (not replays, not prompts).
+2. **Verification manufactured, not hand-written** (synthesized from the
+   observed state diffs).
+3. **Cross-run element re-anchoring** (semantic refs survive DOM drift).
+4. **Trust data attached to executable artifacts** (fingerprint,
+   provenance, evidence-based score, deny-by-default permissions).
+5. **Local-first, offline-complete** (mock provider runs the whole pipeline
+   with zero network).
+
+## Quick start
+
+```bash
+# 1. Install (Python 3.11+; MCP transport included by default)
+pip install capability-compiler                  # everything except adapters/providers below
+pip install capability-compiler[browser]         # add the Playwright adapter
+pip install capability-compiler[models]          # add Anthropic / OpenAI / Ollama providers
+
+# 2. Verify the install
+cc doctor
+
+# 3. Inspect effective configuration
+cc config show
+
+# 4. Learn a capability from a local app (fake adapter, no browser needed)
+cc learn "export a pdf" --adapter fake --name export_pdf
+
+# 5. Run it through the gate-ordered executor
+cc execute export_pdf --key format=pdf --key file_name=report.pdf
+
+# 6. Browse what you have
+cc capabilities
+cc inspect export_pdf
+
+# 7. Serve every capability as MCP tools (stdio for editor clients)
+cc serve --transport stdio
+cc serve --transport http --host 127.0.0.1 --port 8765 --token "$CC_MCP_TOKEN"
+```
+
+Every command supports `--json` for machine-readable output. Pass `--verbose`
+(`-v`) at the top level to bump logging to DEBUG; set `CC_DEBUG=1` to print
+full tracebacks instead of structured error messages.
+
+### Python quick start
+
+```python
+import asyncio
+from capability_compiler import Compiler, CompilerSettings, CapabilityRegistry
+
+async def main() -> None:
+    compiler = Compiler()                    # offline-safe defaults (mock provider)
+    async with compiler:                     # connect/disconnect bracket
+        observation = await compiler.observe()
+        report = await compiler.explore(max_steps=20)
+        if compiler.exploration and compiler.exploration.trajectories:
+            capability = await compiler.synthesize(
+                compiler.exploration.trajectories[-1],
+                goal_hint="export a pdf",
+            )
+            registry = CapabilityRegistry.from_settings(CompilerSettings())
+            await registry.save(capability)
+            result = await compiler.execute(capability, {"format": "pdf"})
+            print(result.status.value, result.duration_ms)
+
+asyncio.run(main())
+```
+
+## Architecture summary
+
+The framework is layered so each phase delivers a coherent unit and each
+later phase builds on a stable contract from the previous one.
+
+| Layer | Module | Contract | Notes |
+|---|---|---|---|
+| Domain models | `capability_compiler.models` | Pydantic v2 data contracts | Single source of truth for capabilities, trajectories, actions, observations |
+| Errors | `capability_compiler.errors` | `CapabilityCompilerError` + 9-way `FailureCategory` taxonomy | Every failure classifies exactly once |
+| Logging | `capability_compiler.logging` | Structured JSON or human formatter; secret redaction filter | Never logs API keys, even under odd key names |
+| Config | `capability_compiler.config` | Layered settings (defaults → TOML → `CC_*__*` env) | API keys only ever resolved from env vars |
+| Adapters | `capability_compiler.adapters` | `EnvironmentAdapter` protocol | `fake` (offline), `browser` (Playwright), `desktop` (skeleton) |
+| Providers | `capability_compiler.providers` | `ModelProvider` protocol | `mock`, `ollama`, `anthropic`, `openai`, `openai_compatible` |
+| Recording | `capability_compiler.recording` | `TrajectoryRecorder` + `Replayer` | Every action carries before/after state ids |
+| Perception | `capability_compiler.perception` | `SemanticState` + `StateDiff` (deterministic, no model) | `semantic-v1` fingerprint algorithm |
+| Exploration | `capability_compiler.exploration` | `ExplorationEngine` + `ActionSemanticsEngine` | Effect-first naming; UNKNOWN beats hallucination |
+| Synthesis | `capability_compiler.synthesis` | `CapabilitySynthesizer` | Trajectory → typed, templatized capability |
+| Runtime | `capability_compiler.runtime` | `CapabilityExecutor` (8-gate ordered) | Validate → permissions → confirm → preconditions → procedure → postconditions → record |
+| Verification | `capability_compiler.verification` | 8 verifier kinds (`state`, `dom`, `accessibility`, `file`, `visual`, `schema`, `custom`, `composite`) | Never accepts "exit code 0" as success |
+| Refinement | `capability_compiler.refinement` | `SelfImprovementEngine` + `CapabilityRepairer` | Deterministic repairs promoted only on test-pass |
+| Storage | `capability_compiler.storage` | `CapabilityStore` protocol | `FileCapabilityStore` (atomic writes + integrity check) and `SqliteCapabilityStore` |
+| Registry | `capability_compiler.registry` | `CapabilityRegistry` + `Permission` bitfield | Search, summaries, risk tagging, version-aware rollback |
+| Compiler | `capability_compiler.compiler` | The `Compiler` facade | Wires + supervises — algorithms live in engines |
+| CLI | `capability_compiler.cli` | The `cc` command | `version`, `doctor`, `config`, `capabilities`, `inspect`, `learn`, `execute`, `serve`, `benchmark` |
+| Server | `capability_compiler.server` | MCP transports (`stdio` and streamable `http`) | Bearer-token auth on the HTTP transport |
+
+The full overview lives at [`docs/architecture.md`](docs/architecture.md).
+Subsystem deep-dives live in [`docs/architecture/`](docs/architecture/).
+
+## Security posture
+
+Capability Compiler is **deny-by-default** at every layer:
+
+- `security.allow_network` and `security.allow_shell` both default to `false`.
+- `allowed_read_roots` and `allowed_write_roots` default to empty lists
+  (filesystem scope is opt-in per capability).
+- The browser adapter blocks navigation to non-loopback URLs unless
+  `security.allow_network=true`; failed navigation becomes a structured
+  `PERMISSION_DENIED`, never a crash.
+- API keys are referenced by env-var *name* in config; values are resolved at
+  call time and never persisted. The logging layer redacts by key name
+  (`api_key`, `token`, `secret`, `password`, `authorization`, `cookie`,
+  `credential`, `session_id`) and by value pattern (`Bearer …`, `sk-…`,
+  `gh[pousr]_…`) as a second line of defense.
+- Destructive capabilities (`permissions.destructive=true` or
+  `risk ≥ HIGH`) require explicit user confirmation by default; the CLI
+  prompts on a TTY and the executor accepts `confirmed=True` to skip.
+- Capabilities are **pure data** (JSON-serializable Pydantic models).
+  Nothing in a stored capability is ever evaluated as code.
+
+The complete threat model, scope of promises, and explicit non-goals are in
+[`SECURITY.md`](SECURITY.md). Local-first design choices are explained in
+[`docs/concepts/local-first.md`](docs/concepts/local-first.md).
+
+## How to contribute / how to extend
+
+Capability Compiler ships pluggable protocols at every cross-cutting
+boundary; subclasses are not required (Protocols are structural).
+
+| To add … | Use … |
+|---|---|
+| A new environment (browser, desktop, mobile, CLI) | `register_adapter(kind, factory)` in `capability_compiler.adapters.base` |
+| A new model backend (new vendor, new on-prem) | `register_provider(name, factory)` in `capability_compiler.providers.base` |
+| A new persistence backend (Redis, Postgres, S3) | Implement the `CapabilityStore` protocol in `capability_compiler.storage.base` |
+| A new check on capability outcomes | `register_verifier(kind, factory)` in `capability_compiler.verification.base` |
+| A new CLI command | Append a Typer command module under `src/capability_compiler/cli/` and register it in `main.py` |
+
+The differentiation thesis ([`docs/research/differentiation.md`](docs/research/differentiation.md))
+is the source of intent — please read it before opening a feature PR.
+The master plan ([`docs/master-plan.md`](docs/master-plan.md)) defines
+what is in scope and what is not. Development setup, test layout, and CI
+gates are in [`docs/ci.md`](docs/ci.md).
+
+## Benchmarks
+
+Capability Compiler ships an internal **CapabilityBench** suite used for
+sanity checks and gate reporting. It runs against the in-memory `fake`
+adapter so it never touches the network, a real OS, or a browser. See
+[`docs/benchmarks.md`](docs/benchmarks.md) for what is and isn't measured.
+
+## Documentation index
+
+- Concepts — [`docs/concepts/exploration.md`](docs/concepts/exploration.md),
+  [`docs/concepts/local-first.md`](docs/concepts/local-first.md)
+- Architecture — [`docs/architecture.md`](docs/architecture.md),
+  [`docs/architecture/registry.md`](docs/architecture/registry.md),
+  [`docs/architecture/mcp.md`](docs/architecture/mcp.md)
+- Adapters — [`docs/adapters/browser.md`](docs/adapters/browser.md)
+- Model providers — [`docs/models.md`](docs/models.md)
+- CLI reference — [`docs/cli/commands.md`](docs/cli/commands.md)
+- Benchmarks — [`docs/benchmarks.md`](docs/benchmarks.md)
+- CI / `cc doctor` — [`docs/ci.md`](docs/ci.md)
+- Research — [`docs/research/landscape.md`](docs/research/landscape.md),
+  [`docs/research/differentiation.md`](docs/research/differentiation.md)
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Acknowledgments
+
+Capability Compiler stands on the shoulders of projects whose work the
+[`docs/research/landscape.md`](docs/research/landscape.md) map credits in
+detail. The full production-readiness release was authored by the
+Capability Compiler contributors; see
+[`CHANGELOG.md`](CHANGELOG.md) for what shipped in each phase.

capability_compiler-0.1.0/docs/adapters/browser.md

@@ -0,0 +1,88 @@
+# Browser Adapter
+
+> Status: **Phase 2 — production-ready for local/loopback targets.**
+> Playwright-based; requires the `browser` extra: `pip install capability-compiler[browser]`
+> then `python -m playwright install chromium`.
+
+## What it does
+
+Wraps Playwright's async API behind the
+[`EnvironmentAdapter`](../architecture.md#extension-points-phase-1-contracts-filled-later)
+protocol:
+
+| Verb | Implementation |
+|---|---|
+| `connect(url?)` | launch browser + context + page, navigate, remember start URL |
+| `observe(screenshot=True)` | one normalized `Observation` (see below) |
+| `execute(action)` | map domain action → Playwright call via semantic target resolution |
+| `reset()` | best-effort return to the start URL |
+| `resolve_target(target)` | `ActionTarget` → Playwright `Locator` |
+
+## Observation composition
+
+- **Accessibility tree** — `page.aria_snapshot()` YAML parsed into
+  `AccessibilityNode` (parser validated byte-exact against Playwright 1.62
+  output; the legacy `page.accessibility` API is gone in current Playwright).
+  Used for state identity *inspection*, exploration, and repair — **not**
+  fingerprinted (Chromium updates its a11y tree asynchronously; that race
+  made fingerprints nondeterministic — pinned by tests).
+- **Interactive elements** — an in-page read-only scan (roles, best-effort
+  accessible names, values, visibility, enabledness, bounding boxes) with
+  stable positional ids `e1..eN` in document order.
+- **Structure** — URL, title, DOM hash (diagnostics only), and a
+  whitespace-normalized **visible-text digest** (the deterministic content
+  identity that catches non-interactive changes the element scan cannot
+  see).
+- **Screenshot** — content-hashed artifact written under the storage
+  artifacts dir; large images stay on disk, small ones inline base64.
+
+## Target resolution order (drift-resilient by construction)
+
+```
+ref (element id from an observation)
+  → role + name + ordinal among identical role+name matches
+  → explicit target.role / target.name
+  → CSS/XPath selector
+  → coordinates (last resort, recorded for debugging)
+```
+
+When a `ref` misses the cached observation (first action after navigation,
+stale page), the adapter re-observes once and retries — the seed of the
+Phase-6 re-anchoring mechanism. Strict-mode ambiguity is preserved:
+duplicate `role+name` elements are disambiguated by recorded ordinal, not by
+guessing.
+
+## Security
+
+- **Navigation policy** (`url_allowed`): `file:`/`data:`/`about:`/`blob:` and
+  loopback hosts are always allowed; **any other host requires
+  `security.allow_network = true`** (default false). Failed navigation is a
+  `PERMISSION_DENIED` action result, never a crash.
+- Page content is untrusted data. The scan is read-only; nothing from the
+  page is ever evaluated as code.
+- Screenshots may contain injected-instruction text; downstream model
+  consumers must treat them as data (enforced by provider prompt design).
+
+## Determinism notes (hard-won)
+
+| Source of instability | Resolution |
+|---|---|
+| a11y tree async updates | excluded from fingerprint |
+| `page.content()` attribute placement | DOM hash diagnostics-only; visible-text digest instead |
+| duplicate-named elements | ordinal disambiguation from scan order |
+| replay after navigation | ref-miss → re-observe → retry once |
+
+All four are pinned by tests (`test_e2e_record_replay.py`,
+`test_browser_adapter.py`).
+
+## Usage
+
+```python
+from capability_compiler import CompilerSettings
+from capability_compiler.adapters import create_adapter
+
+settings = CompilerSettings()
+adapter = create_adapter("browser", settings)
+await adapter.connect("file:///path/to/app.html")
+observation = await adapter.observe()
+```

capability_compiler-0.1.0/docs/architecture/README.md

@@ -0,0 +1,17 @@
+# Architecture — subsystem index
+
+> Detailed design notes for the cross-cutting subsystems of Capability Compiler.
+> The top-level architecture overview is in [`../architecture.md`](../architecture.md);
+> these files go deeper on registry, MCP, and the rationale behind them.
+
+| Subsystem | Document |
+|---|---|
+| Capability registry | [`registry.md`](registry.md) — backends, search, summaries, permissions, authorization |
+| MCP integration | [`mcp.md`](mcp.md) — transports, tool + result schema, authentication |
+| Local-first design | [`../concepts/local-first.md`](../concepts/local-first.md) |
+| Exploration pipeline | [`../concepts/exploration.md`](../concepts/exploration.md) |
+
+The implementation follows the eight-phase plan in
+[`../master-plan.md`](../master-plan.md). Every subsystem module ships with
+its own docstring describing the contract; the docs here narrate *why* and
+*how* the contracts compose into the framework.