lynx-agent 1.0.0__tar.gz

lynx_agent-1.0.0/.gitignore

@@ -0,0 +1,42 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.venv/
+venv/
+env/
+
+.lynx/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+.DS_Store
+.idea/
+.vscode/
+
+# Locally generated by `lynx init` in the repo root — never commit.
+/policy.yaml
+/lynx.toml
+/demo-workspace/
+/data/
+
+# Wheel/sdist build outputs
+dist/
+*.whl
+*.tar.gz
+
+# Internal working docs — research notes, planning, scratch.
+# Never gets committed; see internal/README.md for what lives there.
+/internal/
+

lynx_agent-1.0.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to Lynx will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- (nothing yet — open a PR!)
+
+### Changed
+- (nothing yet)
+
+### Fixed
+- (nothing yet)
+
+## [1.0.0] — 2026-06-09
+
+First public release. All of the below shipped together; this is the surface area covered by the v1.0 SemVer commitment.
+
+### Core
+
+- Kernel types: `Task`, `Run`, `Step`, `ActionRequest`, `Decision`, `AuditEvent`, `ToolMetadata`, `ExecutionContext`, `Principal`, `Budget`, `ModelCall`, `ActionResult`.
+- Policy compiler + Policy Decision Point (PDP) — pure, deterministic, content-addressed bundles.
+- Action Mediator (PEP) — five verdicts: `allow`, `deny`, `dry_run`, `approve_required`, `transform`.
+- Scheduler with pre-execution checkpointing; crash-resume + approval-resume both correctly implemented.
+- Hash-chained audit log with tamper detection (`lynx audit verify`).
+
+### Public SDK
+
+- `@tool` decorator + `.shadow` for dry-run twins.
+- `Runtime.run / resume / replay / approve / deny`.
+- `Agent` protocol — one method, `async def step(conversation) -> ToolCall | FinalAnswer`.
+
+### Adapters
+
+- `lynx.adapters.anthropic_sdk.ClaudeAgent`
+- `lynx.adapters.openai_sdk.OpenAIAgent`
+- `lynx.adapters.langgraph_adapter.LangGraphAgent`
+- `lynx.adapters.crewai_adapter.CrewAIAgent`
+- `lynx.adapters.mcp.register_mcp_server`
+
+### Storage
+
+- `lynx.stores.sqlite.SQLiteStore` — full implementation, default.
+- `lynx.stores.postgres.PostgresStore` — production backend (Tasks / Runs / Audit; Steps + Approvals follow same translation pattern).
+
+### Shadow library
+
+- `lynx.shadows.shell_shadow`
+- `lynx.shadows.write_file_shadow`, `delete_file_shadow`
+- `lynx.shadows.sql_shadow`
+- `lynx.shadows.http_shadow` (with built-in `Authorization` header redaction)
+
+### Sandbox
+
+- `lynx.sandbox.run_in_subprocess` — POSIX subprocess sandbox with `RLIMIT_CPU`, `RLIMIT_AS`, stripped env, timeout.
+
+### Observability
+
+- `lynx.observability.enable_prometheus`
+- `lynx.observability.enable_otel`
+
+### CLI
+
+- `lynx init / run / resume / ps / trace / approvals / approve / deny / audit verify / audit export / policy lint / policy bundle-id`
+
+### Documentation
+
+- Onboarding: `why-lynx.md`, `getting-started.md`, `concepts.md`, `cookbook.md`, `faq.md`.
+- Reference: `01-data-model.md`, `02-policy-language.md`, `03-sdk-and-cli.md`.
+- Threat model: `threat-model.md` (STRIDE-style).
+- 12 runnable examples: simple → complex → advanced → complete → integrations (FastAPI / Flask / Django).
+
+### Quality bar
+
+- 57 tests, ~1.2s suite, 9-job CI matrix (Linux / macOS / Windows × Python 3.11 / 3.12 / 3.13) + coverage.
+- ruff lint + format clean. `mypy --strict` runs (currently soft-gated on the test matrix; will be hard-gated in v1.1).
+- Apache-2.0 licensed. PEP 561 typed (`py.typed`). PEP 639 license metadata.
+
+### Public API surface guaranteed by SemVer
+
+- `lynx.tool`, `lynx.runtime`, `lynx.Runtime`, `lynx.shadow`, `lynx.allow/deny/dry_run/approve_required/transform/rule`.
+- `lynx.Agent`, `lynx.Message`, `lynx.ToolCall`, `lynx.FinalAnswer`, `lynx.AgentAction`.
+- `lynx.Task`, `lynx.Run`, `lynx.Step`, `lynx.ActionRequest`, `lynx.Decision`, `lynx.AuditEvent`, `lynx.Verdict`, `lynx.RunStatus`, `lynx.Principal`, `lynx.Budget`, `lynx.ToolMetadata`, `lynx.ExecutionContext`, `lynx.ModelCall`, `lynx.ActionResult`.
+- Adapters and stores have their own public-class interfaces guaranteed.
+- The YAML policy v1 grammar.
+- The CLI command surface and exit codes.
+
+Internal modules (`lynx.core.*`) are NOT part of the public API and may change in any minor release.
+
+[Unreleased]: https://github.com/hadihonarvar/lynx/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/hadihonarvar/lynx/releases/tag/v1.0.0

lynx_agent-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and leaders pledge to make participation in the Lynx community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers via [GitHub Security Advisories](https://github.com/hadihonarvar/lynx/security/advisories/new) (any "Conduct" report routes to maintainers privately). All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

lynx_agent-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to Lynx
+
+Thanks for considering a contribution. This document covers what to do and what to expect.
+
+## Quick setup
+
+```bash
+git clone https://github.com/<your-fork>/lynx
+cd lynx
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+make all          # fmt + lint + type + test — should be green
+```
+
+## Filing issues
+
+Open an issue using one of the [templates](.github/ISSUE_TEMPLATE/) — `bug`, `feature`, or `question`. The more reproduction info you include, the faster we can act.
+
+## Proposing changes
+
+1. **Open an issue first** for non-trivial changes — saves you wasted effort if the design doesn't fit. Trivial fixes (typos, small bugs, clearer error messages) can skip straight to a PR.
+2. **Branch from `main`**, with a name like `fix/policy-regex-timeout` or `feat/postgres-store`.
+3. **One logical change per PR.** Smaller PRs land faster.
+4. **Tests required** for new behavior. Bug fixes should include a regression test.
+5. **Update docs** when you change the public API or CLI surface.
+6. **Run `make all` locally** before pushing. CI runs the same checks; saving a round-trip helps.
+
+## Architecture rules
+
+These are load-bearing — please don't break them:
+
+1. **`core/` has zero I/O.** It's pure functions and state machines. If you need to do I/O, it goes in `stores/`, `adapters/`, `transports/`, or `cli/`.
+2. **The PDP is deterministic.** No network, no clocks read inside policy evaluation, no random. Same input must always produce the same `Decision`.
+3. **The audit chain is append-only.** If you find yourself wanting to mutate a past `AuditEvent`, you're solving the wrong problem.
+4. **Tools must be async.** A sync tool is `asyncio.to_thread(...)` away from being async; please wrap rather than introducing sync paths into the kernel.
+5. **No breaking changes to the public API in patch releases.** We follow SemVer strictly from v1.0 onwards.
+
+## Adding a new adapter
+
+The smallest viable PR for a new framework adapter:
+
+1. `src/lynx/adapters/<framework>.py` — a class that satisfies the `Agent` protocol (`async def step(conversation) -> ToolCall | FinalAnswer`).
+2. `tests/test_adapter_<framework>.py` — mock the framework's client; assert the message translation + tool-call extraction.
+3. `examples/<framework>_demo.py` — a runnable demo using the new adapter.
+4. Update the README's adapter list.
+
+## Adding a new shadow
+
+`src/lynx/shadows/<name>.py` — one or more `async def name_shadow(*args) -> dict` functions that return previews without side effects.
+
+## Coding style
+
+- Python 3.11+
+- `ruff` for lint + format
+- `mypy --strict` for types
+- One blank line between methods, two between top-level definitions
+- Docstrings on every public function — short and useful, not ceremonial
+
+## Commit messages
+
+Conventional Commits style:
+
+- `fix: policy regex denial-of-service guard`
+- `feat(stores): postgres backend`
+- `docs: clarify approve flow`
+- `test: cover budget exhaustion`
+- `chore: bump ruff to 0.6`
+
+## Release process
+
+Maintainers only:
+
+1. Update `CHANGELOG.md`
+2. Bump version in `pyproject.toml` and `src/lynx/__init__.py`
+3. `git tag vX.Y.Z` + push tag
+4. GitHub Actions handles wheel build + PyPI publish via OIDC trusted publishing
+
+## Code of conduct
+
+By participating you agree to follow the [Contributor Covenant](CODE_OF_CONDUCT.md). In short: be kind, be patient, assume good intent, and call out behavior that crosses lines.
+
+## Security issues
+
+Do **not** open public issues for security vulnerabilities. Follow the process in [SECURITY.md](SECURITY.md).
+
+## Licensing
+
+By contributing, you agree your contributions will be licensed under the Apache License 2.0.

lynx_agent-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Lynx contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lynx_agent-1.0.0/Makefile

@@ -0,0 +1,23 @@
+.PHONY: install test lint type fmt all clean
+
+install:
+	pip install -e ".[dev]"
+
+test:
+	pytest -v
+
+lint:
+	ruff check src tests
+
+fmt:
+	ruff format src tests
+	ruff check --fix src tests
+
+type:
+	mypy src
+
+all: fmt lint type test
+
+clean:
+	rm -rf build dist *.egg-info .pytest_cache .mypy_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} +

lynx_agent-1.0.0/PKG-INFO

@@ -0,0 +1,343 @@
+Metadata-Version: 2.4
+Name: lynx-agent
+Version: 1.0.0
+Summary: Framework-agnostic runtime that makes any AI agent safe and reliable enough to put in production: policy-gated execution, durable checkpointing, hash-chained audit.
+Project-URL: Homepage, https://github.com/hadihonarvar/lynx
+Project-URL: Repository, https://github.com/hadihonarvar/lynx
+Project-URL: Documentation, https://github.com/hadihonarvar/lynx/tree/main/docs
+Project-URL: Issues, https://github.com/hadihonarvar/lynx/issues
+Project-URL: Changelog, https://github.com/hadihonarvar/lynx/blob/main/CHANGELOG.md
+Author: Lynx contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agentic,agents,ai,audit,claude,crewai,durable-execution,langgraph,llm,mcp,openai,policy,reliability
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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 :: Implementation :: CPython
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: msgpack>=1.0
+Requires-Dist: python-ulid>=2.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typing-extensions>=4.5
+Provides-Extra: all
+Requires-Dist: anthropic>=0.30; extra == 'all'
+Requires-Dist: crewai>=0.40; extra == 'all'
+Requires-Dist: langgraph>=0.2; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: openai>=1.40; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'all'
+Requires-Dist: prometheus-client>=0.20; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.40; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
+Description-Content-Type: text/markdown
+
+# Lynx
+
+**Make any AI agent safe and reliable enough to put in production.** Open-source Python runtime that wraps any agent (LangGraph, CrewAI, OpenAI Agents SDK, Anthropic Agent SDK, or a plain Python loop) and gives you three things every team currently rebuilds from scratch:
+
+1. **Policy-gated execution** — every tool call passes through a declarative YAML policy engine. Dry-run, deny, transform, or require human approval.
+2. **Durable execution** — every step is checkpointed before its side effect. Crash mid-run, resume exactly where you left off, no double-execution.
+3. **Hash-chained audit log** — content-addressed, tamper-evident, regulator-grade trail of every decision and action.
+
+> Think *Envoy + Temporal + OPA, but for AI agents.*
+
+---
+
+## Why
+
+Agent reliability is the #1 unmet need in 2026 (Gartner: 40% of agentic AI projects will fail). Capabilities are up, reliability is lagging. Real incidents from the last 12 months:
+
+- An AI agent **deleted a developer's entire `D:` drive** when asked to clear a cache folder.
+- An AI agent **wiped a production AWS environment**, causing a 13-hour outage.
+- Meta's AI safety director was unable to stop her own agent from **deleting her inbox**.
+- An n8n v2.4.7→v2.6.3 upgrade silently **broke function-calling schemas** across the user base.
+
+Every team building agents reinvents the same scaffolding: retry logic, dry-runs, approval flows, audit trails. **Lynx is the missing layer.**
+
+---
+
+## Quickstart (under 2 minutes)
+
+```bash
+pip install lynx-agent
+lynx init
+```
+
+```python
+# my_agent.py
+import asyncio
+from lynx import tool, runtime, ToolCall, FinalAnswer, Message
+
+@tool(cost="low", reversible=False, scope=["filesystem:write"])
+async def shell(cmd: str) -> str:
+    proc = await asyncio.create_subprocess_shell(
+        cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+    )
+    out, err = await proc.communicate()
+    return (out + err).decode()
+
+@shell.shadow
+async def _shell_shadow(cmd: str) -> dict:
+    return {"would_run": cmd}
+
+class MyAgent:
+    """Replace with any LLM-backed agent."""
+    async def step(self, conversation):
+        # Pretend the LLM proposed a dangerous command
+        return ToolCall(tool="shell", args={"cmd": "rm -rf /"}, call_id="c1")
+
+async def main():
+    result = await runtime.run(
+        MyAgent(),
+        task="clean up the workspace",
+        policy="./policy.yaml",
+    )
+    print(result.status, result.final_answer)
+
+asyncio.run(main())
+```
+
+```bash
+$ python my_agent.py
+$ lynx ps                    # list runs
+$ lynx trace <run_id>        # see every step + policy decision
+$ lynx audit verify <run_id> # verify the hash chain
+```
+
+The default policy will **deny** the `rm -rf /` and feed the denial back to the agent as a tool result, so the agent can retry with something safer.
+
+---
+
+## How it works
+
+```
+                ┌────────────────────────────────────────────────┐
+                │  Agent (LangGraph / CrewAI / SDK / any)        │
+                └──────────────────┬─────────────────────────────┘
+                                   │ proposed tool call
+                                   ▼
+              ╔════════════════════════════════════════════════╗
+              ║                  AGENT RUNTIME                 ║
+              ║  ┌────────────┐  ┌────────────┐  ┌──────────┐  ║
+              ║  │  Scheduler │→ │ Policy PDP │→ │ Mediator │  ║
+              ║  │ (durable)  │  │  (pure)    │  │  (PEP)   │  ║
+              ║  └────────────┘  └────────────┘  └──────────┘  ║
+              ║          ↓             ↓              ↓        ║
+              ║  ┌──────────────────────────────────────────┐  ║
+              ║  │      SQLite journal + audit chain        │  ║
+              ║  └──────────────────────────────────────────┘  ║
+              ╚════════════════════════════════════════════════╝
+                                   │ approved + recorded
+                                   ▼
+              ┌────────────────────────────────────────────────┐
+              │ Real world (shell, browser, DB, AWS, etc.)     │
+              └────────────────────────────────────────────────┘
+```
+
+Every action passes through the **Mediator**. The PDP returns one of five verdicts (`allow`, `deny`, `dry_run`, `approve_required`, `transform`). The Mediator dispatches accordingly. Before any side effect, a checkpoint is written. Every step emits a hash-chained audit event.
+
+---
+
+## Policy example
+
+```yaml
+# policy.yaml
+version: 1
+defaults:
+  on_missing_shadow: approve_required
+  on_no_match: deny
+
+rules:
+  - id: read-only-allow
+    match: { declared.scope.contains_any: ["filesystem:read", "net:read"] }
+    decision: allow
+
+  - id: shell-rm-rf-root
+    match:
+      tool: shell
+      args.cmd.matches: '^\s*rm\s+(-[rRf]+\s+)+/(\s|$)'
+    decision: deny
+    reason: "rm -rf / is never allowed"
+
+  - id: prod-mutations-need-approval
+    match:
+      context.environment: prod
+      declared.scope.contains_any: ["filesystem:write", "db:write", "cloud:write"]
+    decision: approve_required
+    approvers: ["@oncall"]
+
+  - id: irreversible-dry-run-first
+    match: { declared.reversible: false }
+    decision: dry_run
+```
+
+Three layers, increasing expressiveness:
+1. **YAML rules** — 80% of cases
+2. **Predicates** — reusable named patterns
+3. **Python escape hatch** — `@policy.rule` for edge cases
+
+See `docs/02-policy-language.md` for the full grammar.
+
+---
+
+## CLI
+
+```
+lynx init                    # set up a project
+lynx run <script>            # run an agent script
+lynx ps                      # list recent runs
+lynx trace <run-id>          # step-by-step trace
+lynx approvals               # list pending approvals
+lynx approve <approval-id>   # approve a pending request
+lynx audit verify <run-id>   # verify the hash chain
+lynx audit export <run-id>   # emit jsonl for compliance
+lynx policy lint             # validate policy.yaml
+lynx policy bundle-id        # content-addressed bundle ID
+```
+
+---
+
+## Repo layout
+
+```
+lynx/
+├── docs/
+│   ├── 00-execution-plan.md      ← read first
+│   ├── 01-data-model.md
+│   ├── 02-policy-language.md
+│   └── 03-sdk-and-cli.md
+├── src/lynx/
+│   ├── core/                     ← pure kernel, no I/O
+│   │   ├── types.py
+│   │   ├── policy.py             ← PDP
+│   │   ├── mediator.py           ← PEP
+│   │   └── scheduler.py          ← step loop
+│   ├── stores/                   ← pluggable I/O
+│   │   └── sqlite.py
+│   ├── cli/main.py
+│   ├── decorators.py             ← @tool, @shadow
+│   ├── policy.py                 ← top-level re-exports
+│   ├── runtime.py                ← public Runtime facade
+│   └── sdk.py                    ← Agent protocol + Message types
+├── tests/
+├── examples/
+│   └── hello_agent.py
+└── pyproject.toml
+```
+
+**Architectural rule:** `core/` has zero I/O. All I/O lives in `stores/`, `adapters/`, and `cli/`. This is why the PDP runs in microseconds, why tests are flake-free, and why upgrading from SQLite to Postgres to a gRPC sidecar is a deployment change, not a rewrite.
+
+---
+
+## Roadmap
+
+- **v0.1 (this release)** — MVP: SQLite, YAML policy, allow/deny/approve/dry_run/transform, audit chain, CLI, scripted agent example.
+- **v0.5** — Crash-resume durability, shadow library (shell, SQL, HTTP, AWS), `replay --edit`.
+- **v1.0** — LangGraph / CrewAI / OpenAI Agents SDK / MCP adapters; Postgres store; webhook & Slack approval transports; gRPC sidecar mode; HSM-signed audit.
+- **v1.5** — Control plane: multi-tenant policy distribution, dashboards, cross-run analytics, governance. (Commercial layer.)
+
+See `docs/00-execution-plan.md` for the week-by-week plan.
+
+---
+
+## Performance
+
+| What | Number |
+|------|--------|
+| Policy evaluation (typical, ≤100 rules) | ~100 µs / call |
+| Policy evaluation (worst case, 1000 rules) | ~1 ms / call |
+| End-to-end overhead per step | ~3 ms (SQLite-bound) |
+| Test suite | 57 tests in 1.1 s |
+
+For real agents where each step is a 500 ms – 5 s LLM call, Lynx's overhead is under 1%. Reproducible numbers in [`benchmarks/`](benchmarks/README.md).
+
+---
+
+## Documentation
+
+Start here if you're new:
+
+| Doc | What it answers |
+|-----|----------------|
+| [Why Lynx](docs/why-lynx.md) | When should I use this? When shouldn't I? |
+| [Getting started](docs/getting-started.md) | 5-minute walkthrough from install to first denial |
+| [Concepts](docs/concepts.md) | Vocabulary: Tool, Policy, Verdict, Run, AuditEvent |
+| [Policy cookbook](docs/cookbook.md) | Copy-pasteable rules for common patterns |
+| [FAQ](docs/faq.md) | Common first-time questions |
+
+Reference docs:
+
+| Doc | What it covers |
+|-----|----------------|
+| [Data model](docs/01-data-model.md) | The six core types + SQLite schema |
+| [Policy language](docs/02-policy-language.md) | Full YAML grammar + predicates + Python escape hatch |
+| [SDK + CLI](docs/03-sdk-and-cli.md) | The public Python API + every CLI command |
+| [Threat model](docs/threat-model.md) | STRIDE analysis + guarantees + non-goals |
+| [How v0.1 was built](docs/00-execution-plan.md) | The MVP execution plan (historical) |
+
+Examples:
+
+| Demo | What it shows |
+|------|--------------|
+| [`hello_agent.py`](examples/hello_agent.py) | Minimal scripted agent — the smallest end-to-end loop |
+| [`file_janitor.py`](examples/file_janitor.py) | Real filesystem demo: allow / deny / dry_run with real files |
+| [`refund_agent.py`](examples/refund_agent.py) | Customer-support refund agent — demonstrates `approve_required` |
+| [`claude_janitor.py`](examples/claude_janitor.py) | Real Claude agent driving the file demo |
+| [`openai_janitor.py`](examples/openai_janitor.py) | Same demo, OpenAI GPT |
+| [`fastapi_server.py`](examples/fastapi_server.py) | Drop-in FastAPI integration |
+
+See [`examples/README.md`](examples/README.md) for the full index + how to run them.
+
+---
+
+## Status
+
+Alpha. APIs may change before v1.0. Use in production at your own risk; report issues liberally.
+
+---
+
+## License
+
+Apache 2.0.