gatehouse-ai 0.1.0__tar.gz

gatehouse_ai-0.1.0/.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "includeCoAuthoredBy": false
+}

gatehouse_ai-0.1.0/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/pytest)",
+      "Bash(.venv/bin/ruff check *)",
+      "Bash(.venv/bin/ruff format *)",
+      "Bash(.venv/bin/mypy gatehouse *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git commit -q -m 'feat: add disposition types and declarative policy engine *)",
+      "Bash(.venv/bin/pytest tests/test_server.py)",
+      "Bash(.venv/bin/pytest tests/test_decorator.py)",
+      "Bash(.venv/bin/python *)",
+      "Bash(.venv/bin/gatehouse test *)",
+      "Bash(perl -pi -e 's/^version = \"0\\\\.1\\\\.0\\\\.dev0\"$/version = \"0.1.0\"/' pyproject.toml)",
+      "Bash(perl -pi -e 's/^__version__ = \"0\\\\.1\\\\.0\\\\.dev0\"$/__version__ = \"0.1.0\"/' gatehouse/__init__.py)",
+      "Bash(.venv/bin/pip install *)",
+      "Bash(.venv/bin/gatehouse --version)",
+      "Bash(git tag *)"
+    ]
+  }
+}

gatehouse_ai-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Format
+        run: ruff format --check .
+      - name: Type-check
+        run: mypy gatehouse tests
+      - name: Test
+        run: pytest

gatehouse_ai-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# OS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Environments
+.venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+node_modules/
+gatehouse-audit.jsonl
+gatehouse-approvals/

gatehouse_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to Gatehouse are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-07-09
+
+First release: the complete local gate.
+
+### Added
+
+- **Policy engine** — declarative YAML rules resolving every proposed
+  action to one binding disposition (`allow`, `deny`, `require_approval`,
+  `allow_with_flag`); agent/tool matching with wildcards; parameter
+  constraints (bounds, allowlists, patterns); `where` selection predicates
+  distinct from enforced `params`; recurring time windows; rate limits and
+  cumulative budgets scoped per session or per rolling clock window.
+  Deny by default; most restrictive candidate wins; a constraint that
+  cannot be checked counts as breached.
+- **Agent registry** — declared agents with a human owner, autonomy tier
+  (`read_only` / `supervised` / `governed` / `human_only`), explicit tool
+  grant, and credentials reference. Unregistered agents are denied before
+  policy is consulted; tiers cap what any rule may grant.
+- **Audit log** — append-only JSONL with disposition, reason, matched
+  rules, policy version and SHA-256 digest, latency, and a parameters
+  digest (never verbatim arguments). Usage counters are rebuilt from the
+  log on startup.
+- **Approval queue** — held actions with TTL; expiry fails closed;
+  resolutions (who, why, time-to-decision) are appended audit records.
+- **Policy test harness** — `*.test.yaml` scenarios with expected
+  dispositions; ordered scenarios share usage state so limit behaviour is
+  testable.
+- **CLI** — `check` (advisory, records nothing; exit codes 0/2/1),
+  `test`, `audit tail|stats`, `approvals`, `approve`, `deny`, `ui`, `run`.
+- **Web dashboard** — live disposition feed over WebSocket, approval cards
+  with countdowns, agent registry view with activity sparklines, read-only
+  policy view with test results. Localhost only, no auth.
+- **MCP proxy** (`gatehouse run`, `mcp` extra) — gates any MCP server
+  transparently; one session id per connection.
+- **`@gated` decorator** — direct Python integration; refusals raise
+  `ActionDeniedError` carrying the full evaluation.
+- **Travel-agent demo** — a scripted agent walking all four dispositions
+  through mock MCP tools, with policy tests.
+
+[0.1.0]: https://github.com/wkitcheah/gatehouse/releases/tag/v0.1.0

gatehouse_ai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Thanks for looking under the hood. Gatehouse is small on purpose; keeping
+it understandable is a feature.
+
+## Setup
+
+```bash
+python3.11 -m venv .venv && source .venv/bin/activate   # 3.11 or 3.12
+pip install -e ".[dev]"
+```
+
+The dashboard frontend only needs Node if you change it: source in `ui/`,
+built assets committed under `gatehouse/ui/` (`cd ui && npm install &&
+npm run build`). Commit the rebuilt assets with the source change.
+
+## Before every commit
+
+```bash
+pytest
+ruff check . && ruff format --check .
+mypy gatehouse tests
+```
+
+All three must pass — CI runs exactly these on Python 3.11 and 3.12.
+
+## What we hold the line on
+
+- **Deny by default; explicit allow; every disposition explainable.** Any
+  change to evaluation semantics must keep reasons exact and defensible.
+- **The policy engine stays stateless** and the audit log append-only.
+  State lives in the gate; advisory paths (`check`, the test harness)
+  record nothing.
+- **Runtime dependencies stay minimal** (pydantic, PyYAML, click). Anything
+  heavier belongs in an extra (`ui`, `mcp`). Open an issue before adding a
+  dependency.
+- **Core makes no network calls.** Integrations live in `gatehouse/adapters/`.
+- **Every rule type and tier gets positive and negative tests.** New policy
+  semantics need engine tests *and* an end-to-end exercise; a behaviour
+  that only a unit test has seen is not done.
+- **Examples run as written.** If a doc shows a command and its output,
+  both must be real.
+
+## Decisions
+
+Changes that affect policy semantics (precedence, defaults, tier
+interactions, what counts toward a limit) get an entry in
+[`docs/decisions.md`](docs/decisions.md): what was decided and why. If
+you're unsure whether your change qualifies, it does.
+
+One boundary worth knowing: tamper-evident audit mechanisms (hash chains,
+cross-signing, cryptographic binding of records to execution) are out of
+scope for this project. The audit log is ordinary structured JSONL by
+design; please don't send PRs adding cryptographic evidence schemes.
+
+## Commits
+
+Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`,
+`chore:`, `ci:`), small and self-contained, each one green.

gatehouse_ai-0.1.0/GATEHOUSE_CLAUDE.md

@@ -0,0 +1,157 @@
+# Gatehouse — a runtime policy gate for AI agents
+## Reference implementation of the Minimum Viable Control Plane (MVCP)
+
+You are helping me build Gatehouse, an open-source runtime governance layer for AI agents. This file is the project's standing context; read it fully before doing anything. **This is a public portfolio project** — code quality, documentation, and conceptual clarity matter as much as function, because its audience includes hiring managers, practitioners, and readers of my newsletter.
+
+## What Gatehouse is
+
+Gatehouse sits between an AI agent and its tools. Every action the agent proposes — a tool call, an API invocation — is intercepted and evaluated against declarative policy *before* it executes. The evaluation returns one binding disposition: **allow**, **deny**, **require_approval** (held for a human), or **allow_with_flag** (proceeds, but marked for monitoring). Every evaluation is written to a structured audit log.
+
+The conceptual grounding is published work:
+- My article "From Prevention to Control" (April 2026): the Agentic Control Plane — single choke point, agent registry, identity for non-human actors, policy engines before every action, autonomy tiering, verification gates, observability as evidence.
+- My article "From the Control Gap to the Agency Gap" (May 2026): the MVCP's five questions — Identity, Authority, Visibility, Containment, Recovery.
+- MAS's SAFR white paper (July 2026): independent industry validation; our disposition vocabulary deliberately echoes its four outcomes, with attribution in the README.
+
+Gatehouse is the working answer to the MVCP questions, and the docs must map features to those questions explicitly (`docs/mvcp-mapping.md`).
+
+## Hard constraints (never violate)
+
+1. **Patent-safe scope.** I have unrelated pending IP in tamper-evident attestation. Gatehouse must use only conventional, textbook mechanisms. Explicitly out of scope, do not implement even if it seems like an improvement: hash-chained or cryptographically tamper-evident logs; cross-device or cross-process co-signing/attestation of records; making the audit record a cryptographic precondition of execution; content-addressed evidence binding. The audit log is ordinary structured JSONL. If a feature request drifts toward "tamper-evident," stop and flag it to me instead.
+2. **Clean-room hygiene.** No code, configuration, or examples derived from any employer's systems. All examples use fictional scenarios (the demo domain is a fictional travel-booking agent, not finance-specific and not any real company).
+3. **No network calls in core.** The gate must run fully local. Integrations (webhooks) live in optional adapters.
+
+## Architecture
+
+```
+agent  ──proposed action──▶  Gatehouse  ──disposition──▶  tool / blocked / held
+                               │
+              ┌────────────────┼────────────────┐
+        agent registry    policy engine     audit log
+        (identity)        (authority)       (visibility/recovery)
+                               │
+                        approval queue
+                        (containment)
+```
+
+### Package layout (`gatehouse-ai` on PyPI, import name `gatehouse`)
+- `gatehouse/registry.py` — Agent Registry: agents are declared in config with owner, allowed tools, autonomy tier, and credentials reference. Unregistered agent → automatic deny. ("You don't exist unless you're registered.")
+- `gatehouse/policy.py` — policy engine. Declarative YAML policies: per-agent and per-tool rules; parameter constraints (numeric limits, allowlists, regex); conditions (time windows, rate limits, cumulative limits per session); autonomy tiers mapping to default dispositions:
+  - `read_only` → non-mutating tools allowed, everything else denied
+  - `supervised` → mutating actions require_approval
+  - `governed` → allowed within constraints, breaches deny or escalate
+  - `human_only` → always require_approval
+- `gatehouse/dispositions.py` — evaluation result types; every disposition carries the matched rules, the policy file digest and version, and a human-readable reason string.
+- `gatehouse/audit.py` — JSONL audit log: timestamp, agent id, tool, parameters digest, disposition, matched rules, policy version, latency, approval outcome if any. Plus `gatehouse audit tail` and `gatehouse audit stats` CLI views.
+- `gatehouse/approvals.py` — pending-approval queue with TTL; approve/deny via CLI (`gatehouse approve <id>`) and an optional webhook adapter for chat-ops.
+- `gatehouse/adapters/mcp.py` — the flagship integration: an MCP proxy. Gatehouse wraps any MCP server; the agent connects to Gatehouse instead, and every tool call is gated transparently. This makes Gatehouse usable with real agent stacks immediately.
+- `gatehouse/adapters/decorator.py` — `@gated(agent="...")` decorator for direct Python integration.
+- `gatehouse/testing.py` — policy test harness: scenario YAML files declare (agent, tool, params) → expected disposition; `gatehouse test policies/` runs them like unit tests. Policies without tests are policies waiting to be bypassed.
+- `cli.py` — `gatehouse run` (proxy mode), `gatehouse check` (one-shot evaluation), `gatehouse test`, `gatehouse audit`, `gatehouse approve|deny`, `gatehouse ui` (launch dashboard).
+- `gatehouse/server.py` + `ui/` — **web dashboard**, launched with `gatehouse ui` at localhost. FastAPI backend exposing the audit stream, approval queue, registry, and policies over REST + WebSocket; frontend is a single-page app (React + Vite + Tailwind) built into static assets and served by the backend, so end users never run npm. Four views:
+  1. **Live feed** — dispositions streaming in real time as the agent acts, color-coded (allow green, deny red, held amber, flagged blue), each expandable to show matched rules, policy version, and reason string.
+  2. **Approvals** — pending actions as cards with full context and Approve/Deny buttons plus TTL countdown; resolving a card unblocks the waiting agent instantly (WebSocket). This is the demo centerpiece: containment made visible.
+  3. **Agents** — the registry: each agent's identity, autonomy tier, allowed tools, and recent activity sparkline.
+  4. **Policies** — read-only policy viewer with the test-harness results per policy (green/red), so "policies without tests" is visible shame.
+  Design: clean, dense, dark-theme dashboard aesthetic consistent with a governance product — no gradients-and-emoji AI-slop styling; this UI will appear in screenshots, GIFs, and conference slides. WebSocket for live updates; no polling. No auth in v0.1 (localhost only, stated clearly in docs).
+
+### Demo (`examples/travel-agent/`)
+A small scripted agent (no LLM required to run; optional LLM mode) that books fictional flights and hotels through mock MCP tools. The demo script walks the four dispositions: a permitted search (allow), a booking over the price limit (deny, with the reason shown), a cancellation (require_approval — terminal waits, second window approves), and a booking to a flagged destination (allow_with_flag). This demo is the README GIF and the newsletter material.
+
+## Engineering conventions
+- Python 3.11+, `pyproject.toml`; runtime deps minimal: pydantic, PyYAML, click. MCP SDK only inside the adapter extra (`pip install gatehouse-ai[mcp]`). Ask before adding anything else.
+- Full type hints; mypy and ruff clean; pytest with high coverage on `policy.py` and `dispositions.py` — every rule type and tier gets positive and negative tests.
+- GitHub Actions CI: lint, type-check, tests on 3.11/3.12. Badge in README.
+- Docs: `README.md` (90-second pitch, architecture diagram, quickstart in 3 commands, GIF), `docs/mvcp-mapping.md`, `docs/policy-reference.md`, `docs/writing-policies.md` (tutorial), `CONTRIBUTING.md`, `CHANGELOG.md`.
+- License: MIT placeholder — **flagged for my attorney's confirmation before the repo goes public** (MIT vs Apache-2.0 patent-grant implications).
+- Conventional commits; keep history clean and honest — this repo's commit log is part of the portfolio.
+
+## Build order
+1. Core types + policy engine + dispositions, with tests (the heart; get it right first).
+2. Registry + autonomy tiers + audit log.
+3. CLI (`check`, `test`, `audit`) + policy test harness.
+4. Approval queue + CLI approvals.
+5. Web dashboard: FastAPI server + REST/WebSocket API, then the four UI views (live feed and approvals first — they're the demo).
+6. MCP proxy adapter + travel-agent demo, driven end-to-end through the dashboard.
+7. Docs, screen recording of the dashboard demo, CI polish, v0.1.0 tag.
+
+The demo recording for the README: terminal on the left running the travel agent, dashboard on the right — a deny appears in the live feed with its reason, then a cancellation lands in Approvals, the card is clicked, and the terminal proceeds. That fifteen seconds is the whole pitch.
+
+## Repository & attribution conventions
+- Sole authorship: all commits authored as me, using my personal name and personal email (`git config user.name / user.email` set locally in this repo before the first commit). Never add co-author trailers of any kind to commit messages.
+- This CLAUDE.md and any internal working notes are development-environment files, not project files: keep them out of version control via `.git/info/exclude` (not `.gitignore`, which is itself tracked and visible).
+- All tracked content — commit messages, code comments, docs, `docs/decisions.md` — is written in neutral first-person engineering voice with no references to development tooling or assistants.
+- Commit in small, reviewed increments with conventional-commit messages as each piece is completed and tested — an honest, natural history. No backdating, no squashing into artificial narratives.
+
+## Build status (updated 2026-07-09 — keep this section current)
+
+ALL SEVEN STEPS of the build order are DONE; **v0.1.0 is tagged**
+(2026-07-09). 182 tests green, ruff + strict mypy clean, CI workflow in
+`.github/workflows/ci.yml`. Docs complete: README (badge, demo section
+with recording placeholder, attribution), docs/mvcp-mapping.md,
+docs/policy-reference.md, docs/writing-policies.md (all commands
+verified), CONTRIBUTING.md, CHANGELOG.md.
+
+**Release verification (2026-07-09) — both passed:**
+- *Packaging*: sdist + wheel built (`python -m build` from repo root,
+  output in gitignored `dist/`); wheel verified to contain
+  `gatehouse/ui/*` assets and `py.typed`; installed with `[ui,mcp]` into
+  a fresh venv outside the repo; CLI, demo policy tests, wheel-served
+  dashboard, and the full travel demo (incl. MCP proxy + approval round
+  trip) all worked from the installed artifact. `dist/` was rebuilt from
+  the final tagged tree and is upload-ready (`twine upload dist/*`).
+- *Visual QA*: Playwright screenshots of all four dashboard views against
+  live demo data. Two defects found and fixed (rebuilt assets committed):
+  `break-all` → `break-words` in the live-feed detail grid, and stat
+  tiles no longer count approval-resolution records (a held action showed
+  HELD 2 once resolved). The v0.1.0 tag was re-pointed (local, pre-push)
+  to include both fixes; HEAD == v0.1.0 == the tree `dist/` was built
+  from.
+
+Remaining before the repo goes public, all user actions — **the public
+push is deliberately parked (user decision 2026-07-09)**: (1) attorney
+confirms the license — LICENSE and pyproject say MIT; the patent-grant
+trade-off was discussed on 2026-07-09 (Apache §3 grant vs MIT silence, in
+light of the pending tamper-evident-attestation IP) and **Wai Kit is
+inclined toward MIT**, so the files as they stand are likely final and
+the attorney step is confirmation, not a rework.
+(2) GitHub URL is CONFIRMED as `github.com/wkitcheah/gatehouse` and set
+everywhere; the v0.1.0 tag was re-pointed (locally, pre-push) to include
+it. (3) DONE 2026-07-11: demo recorded (18s, dashboard over terminal),
+converted to `docs/demo.gif` (2.3 MB, 1000px, path-leak-free) and
+embedded in the README; two path leaks in demo output were fixed first
+(agent.py hints, proxy status line). (4) when unparked: push + verify CI
++ PyPI publish (`twine upload dist/*`; dist/ is current with the tag). Deferred features: demo's optional LLM mode;
+webhook adapter for chat-ops approvals; session-as-lease (v0.2 candidate,
+analysed in docs/decisions.md).
+
+Step 6 additions: `gatehouse/adapters/` — `@gated` decorator
+(ActionDeniedError carries the evaluation) and the MCP proxy
+(`gatehouse run --agent X -p ... -r ... -- <server cmd>`; deny → error
+result with reason, require_approval blocks async on the queue; one
+session id minted per proxy run). `examples/travel-agent/` — scripted
+agent walks all four dispositions, demo policy + registry +
+travel.test.yaml (12 scenarios incl. salami-slicing). mypy override
+relaxes untyped-decorator checks for gatehouse.adapters.mcp only.
+
+What exists: dispositions + policy engine (`where` selects / `params`
+enforces; rate + cumulative limits with session scoping), registry, JSONL
+audit (params as digests; usage replayed from log on restart), Gate
+(+ pure `decide()` for advisory paths), approval queue (file-per-request,
+TTL fails closed, resolutions appended to audit), policy test harness
+(`*.test.yaml`), CLI (`check|test|audit|approvals|approve|deny|ui`), FastAPI
+server (REST + WS push) and the React dashboard (four views; source in
+`ui/`, built assets committed under `gatehouse/ui/`; deps in `[ui]` extra).
+
+Notable choices beyond the original brief, all recorded with rationale in
+`docs/decisions.md`: most-restrictive-wins precedence; tiers as ceilings;
+unverifiable constraint = breach; identity before authority; caller-supplied
+`session_id` (MCP adapter should derive it from the connection); advisory
+evaluation never records; `check` exit codes 0/2/1 = proceed/approval/deny.
+
+Environment: venv at `.venv`; before each commit run
+`.venv/bin/pytest && .venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy gatehouse tests`.
+Frontend rebuild: `cd ui && npm run build`. License remains MIT placeholder
+pending attorney review before the repo goes public.
+
+## Working style
+Work incrementally, keep tests green, and keep the public-audience bar in mind: clear names beat clever ones, docstrings explain *why*, and every example must run as written. When a design choice affects the policy semantics (rule precedence, deny-by-default behavior, tier interactions), surface it to me and record it in `docs/decisions.md` — those decisions are newsletter material. Default posture everywhere: **deny by default; explicit allow; every disposition explainable.**

gatehouse_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cheah Wai Kit
+
+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.

gatehouse_ai-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: gatehouse-ai
+Version: 0.1.0
+Summary: A runtime policy gate for AI agents: every tool call is evaluated against declarative policy before it executes.
+Project-URL: Homepage, https://github.com/wkitcheah/gatehouse
+Author-email: Cheah Wai Kit <wkitcheah@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,audit,governance,guardrails,policy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.111; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mcp>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: ui
+Requires-Dist: fastapi>=0.111; extra == 'ui'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# Gatehouse
+
+[![CI](https://github.com/wkitcheah/gatehouse/actions/workflows/ci.yml/badge.svg)](https://github.com/wkitcheah/gatehouse/actions/workflows/ci.yml)
+
+**A runtime policy gate for AI agents.**
+
+Gatehouse sits between an AI agent and its tools. Every action the agent
+proposes — a tool call, an API invocation — is intercepted and evaluated
+against declarative policy *before* it executes. Every evaluation resolves to
+one binding disposition:
+
+| Disposition | Meaning |
+| --- | --- |
+| `allow` | The action proceeds. |
+| `deny` | The action is blocked, with a reason. |
+| `require_approval` | The action is held until a human approves it. |
+| `allow_with_flag` | The action proceeds, but is marked for monitoring. |
+
+Every evaluation is written to a structured audit log. The default posture is
+**deny by default, explicit allow, every disposition explainable**.
+
+> **Status:** v0.1.0 — the complete local gate: engine, registry, audit,
+> approvals, CLI, dashboard, MCP proxy, and a runnable demo. Young software;
+> interfaces may still move between minor versions.
+
+## The demo in one paragraph
+
+A scripted travel agent books fictional flights through mock MCP tools with
+Gatehouse in between: a permitted search streams into the dashboard as
+`allow`, an over-budget booking comes back `deny` with the exact reason, a
+watchlisted destination proceeds as `allow_with_flag`, and a cancellation
+stops the terminal until you click **Approve** in the dashboard — then it
+completes instantly. Run it yourself:
+[examples/travel-agent](examples/travel-agent/README.md).
+
+![The travel-agent demo: an allowed search, a booking denied with its reason, a flagged destination, and a held cancellation approved from the dashboard — the terminal proceeding the moment the human decides.](docs/demo.gif)
+
+## Features
+
+- **Policy engine** — declarative YAML rules with agent/tool matching,
+  parameter constraints (bounds, allowlists, regex), selection predicates
+  (`where` selects, `params` enforces), time windows, and rate/cumulative
+  limits with per-session or rolling clock scopes. Deny by default; when
+  rules disagree, the most restrictive disposition wins.
+- **Agent registry** — agents are declared with a human owner, an autonomy
+  tier (`read_only` / `supervised` / `governed` / `human_only`), an explicit
+  tool grant, and a credentials *reference*, never a value. Unregistered
+  agents are denied before policy is consulted. Tiers are ceilings: no rule
+  can grant past them.
+- **Audit log** — append-only JSONL, one record per evaluation: disposition,
+  reason, matched rules, policy version and digest, latency. Parameters are
+  stored as a digest, not verbatim. Usage counters (budgets, rate limits) are
+  rebuilt from the log on restart, so restarting the gate never resets them.
+- **Approval queue** — `require_approval` actions are held with a TTL and
+  resolved from another process; expiry fails closed. Every resolution is an
+  appended audit record naming who decided and why.
+- **Policy test harness** — scenario files declare action → expected
+  disposition; scenarios share usage state so limit behaviour is testable.
+  Policies without tests are policies waiting to be bypassed.
+- **CLI** — `gatehouse check` (one-shot advisory evaluation, records
+  nothing), `gatehouse test`, `gatehouse audit tail|stats`,
+  `gatehouse approvals` / `approve` / `deny`, `gatehouse ui`.
+- **Web dashboard** — live disposition feed over WebSocket, approval cards
+  with TTL countdowns, the agent registry with activity sparklines, and a
+  read-only policy view with test results. Localhost only, no auth in v0.1.
+
+## Quickstart
+
+```bash
+pip install -e ".[ui]"      # from a checkout (PyPI: gatehouse-ai, once published)
+```
+
+Declare an agent and a policy:
+
+```yaml
+# agents.yaml
+agents:
+  - id: trip-planner
+    owner: you@example.test
+    tier: governed
+    allowed_tools: [search_flights, book_flight]
+```
+
+```yaml
+# policy.yaml
+version: 1
+tools:
+  search_flights: {mutating: false}
+  book_flight: {mutating: true}
+rules:
+  - id: allow-search
+    agents: [trip-planner]
+    tools: [search_flights]
+    disposition: allow
+  - id: book-within-budget
+    agents: [trip-planner]
+    tools: [book_flight]
+    disposition: allow
+    params:
+      price: {max: 500}
+    limits:
+      - {cumulative: price, max: 2000, per: session}
+```
+
+Ask the gate what would happen:
+
+```bash
+$ gatehouse check trip-planner book_flight -p policy.yaml -r agents.yaml --param price=812
+deny  trip-planner → book_flight
+  reason: rule 'book-within-budget': parameter 'price' = 812 exceeds the maximum 500.0
+```
+
+Gate any MCP server without changing the agent or the server — the agent
+connects to Gatehouse instead:
+
+```bash
+pip install "gatehouse-ai[mcp]"
+gatehouse run --agent trip-planner -p policy.yaml -r agents.yaml -- <your MCP server command>
+```
+
+Or gate plain Python calls directly:
+
+```python
+from gatehouse import ApprovalQueue, AuditLog, Gate, PolicyEngine, Registry
+from gatehouse.adapters import gated
+
+gate = Gate(
+    Registry.from_file("agents.yaml"),
+    PolicyEngine.from_file("policy.yaml"),
+    AuditLog("gatehouse-audit.jsonl"),
+    approvals=ApprovalQueue("gatehouse-approvals"),
+)
+
+@gated(gate, agent="trip-planner")
+def book_flight(price: float, destination: str) -> str:
+    ...   # only runs if the gate says so; refusals raise ActionDeniedError
+```
+
+Watch it live:
+
+```bash
+gatehouse ui -p policy.yaml -r agents.yaml    # http://127.0.0.1:8422
+```
+
+## Documentation
+
+- [Writing policies](docs/writing-policies.md) — the tutorial; every command
+  runs as written.
+- [Policy reference](docs/policy-reference.md) — every field, and the
+  evaluation semantics.
+- [MVCP mapping](docs/mvcp-mapping.md) — how each feature answers the five
+  control-plane questions: identity, authority, visibility, containment,
+  recovery.
+- [Design decisions](docs/decisions.md) — why tiers are ceilings, why an
+  uncheckable constraint is a breach, what a "session" is, and every other
+  choice that shapes the semantics, with rationale.
+
+## Background and attribution
+
+The conceptual grounding is the Agentic Control Plane ("From Prevention to
+Control") and the Minimum Viable Control Plane ("From the Control Gap to
+the Agency Gap"). The four-disposition vocabulary deliberately echoes the
+four outcomes described in the Monetary Authority of Singapore's SAFR
+white paper (July 2026) — convergent framings of the same idea: agent
+actions should resolve to a small, closed set of binding outcomes.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest && ruff check . && mypy gatehouse tests
+```
+
+The frontend source lives in `ui/`; built assets are committed under
+`gatehouse/ui/` so installed users never need npm. Rebuild with
+`cd ui && npm install && npm run build`.
+
+## License
+
+MIT