tenuo-claude-code 0.2.0__tar.gz → 0.2.2__tar.gz

{tenuo_claude_code-0.2.0 → tenuo_claude_code-0.2.2}/.gitignore

@@ -24,7 +24,7 @@ tenuo.advanced.yaml
 demo/sandbox/out.txt
 demo/sandbox/_probe.txt
 
-# Local-only presentation notes (optional; not part of the public repo)
+# Local-only presentation notes (gitignored — keep your own copy; see demo/docs/README.md)
 demo/docs/PRESENTATION.md
 
 # OS / editor

{tenuo_claude_code-0.2.0 → tenuo_claude_code-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tenuo-claude-code
-Version: 0.2.0
+Version: 0.2.2
 Summary: Tenuo governance for Claude Code — warrants, hooks, MCP proxy, and Cloud lifecycle
 Project-URL: Homepage, https://tenuo.ai
 Project-URL: Repository, https://github.com/tenuo-ai/claude-governance
@@ -30,8 +30,6 @@ Description-Content-Type: text/markdown
 
 # Tenuo for Claude Code
 
-PyPI package: [`tenuo-claude-code`](https://pypi.org/project/tenuo-claude-code/) · CLI: `tenuo-claude`, `tenuo-admin`
-
 [![PyPI](https://img.shields.io/pypi/v/tenuo-claude-code)](https://pypi.org/project/tenuo-claude-code/)
 [![Python](https://img.shields.io/pypi/pyversions/tenuo-claude-code)](https://pypi.org/project/tenuo-claude-code/)
 [![CI](https://github.com/tenuo-ai/claude-governance/actions/workflows/ci.yml/badge.svg)](https://github.com/tenuo-ai/claude-governance/actions/workflows/ci.yml)
@@ -53,9 +51,21 @@ mkdir my-project && cd my-project
 tenuo-claude bootstrap
 ```
 
-Open Claude Code here when `verify` passes. No Claude? `bootstrap` + `verify` is enough to prove enforcement.
+When `verify` passes, open Claude Code in this directory.
+
+**Native authorizer (no Docker):**
+
+```bash
+tenuo-claude install-authorizer
+tenuo-claude bootstrap
+```
+
+If Docker is not installed, `bootstrap` uses the native authorizer automatically. If Docker is installed and you want native anyway:
 
-No Docker, or prefer native? Run `tenuo-claude install-authorizer` once, then `bootstrap`. Without Docker, the CLI uses native automatically. To force native while Docker is running, set `TENUO_AUTHORIZER_BACKEND=native` before `bootstrap`.
+```bash
+export TENUO_AUTHORIZER_BACKEND=native
+tenuo-claude bootstrap
+```
 
 ### Where to go next
 
@@ -63,15 +73,16 @@ No Docker, or prefer native? Run `tenuo-claude install-authorizer` once, then `b
 |-----------------|------------|
 | Day-to-day commands, ports, CLI reference | [Use the tool](#use-the-tool-pypi) |
 | Edit or replace the example policy | [Policy](#policy-tenuoyaml) |
-| Clone, hack, or run the sample project | [Build from source](#build-from-source) |
+| Clone the repo or run the sample project | [Build from source](#build-from-source) |
 | Connect to Tenuo Cloud | [Cloud mode](#cloud-mode) |
 | Review security posture | [Security](#security) |
 | Plan org-wide rollout | [Talk to us](https://tenuo.ai/early-access.html) |
+| Something failed during setup | [Troubleshooting (Q&A)](docs/TROUBLESHOOTING.md) |
 | Implementation depth | [docs/DETAILS.md](docs/DETAILS.md) |
 
 ## How it works
 
-![Architecture](docs/images/tenuo_claude_code_architecture.svg)
+![Architecture](https://raw.githubusercontent.com/tenuo-ai/claude-governance/main/docs/images/tenuo_claude_code_architecture.png)
 
 ```
 tenuo.yaml  →  init/up  →  warrant + authorizer + hooks + MCP proxy
@@ -87,41 +98,42 @@ tenuo.yaml  →  init/up  →  warrant + authorizer + hooks + MCP proxy
 
 **Native tools** (Read, Bash, WebFetch, and the rest) go through a PreToolUse hook. **MCP tools** go through a proxy in place of the downstream server. At `init`, Tenuo mints a **session warrant**; each call must prove it holds that warrant before the authorizer allows the action.
 
-Both paths use the same warrant and authorizer.
-
 More: [docs/DETAILS.md](docs/DETAILS.md)
 
 ## Prerequisites
 
 - Python ≥ 3.10
-- **Authorizer runtime** (pick one):
-  - **Docker:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) or your engine, then `tenuo-claude up`. Pulls the pinned `tenuo/authorizer` image. Default when Docker is running.
-  - **Native (no Docker):** `tenuo-claude install-authorizer`, then `tenuo-claude up --native`. First run: add `--install`. Override the binary with `TENUO_AUTHORIZER_BIN`. Set `TENUO_AUTHORIZER_SKIP_VERSION=1` only for local dev builds.
-
-  Without Docker, `bootstrap` uses native. Run `install-authorizer` first. To force native while Docker is running, set `TENUO_AUTHORIZER_BACKEND=native`.
-- [Claude Code](https://code.claude.com/docs) for live agent use. Optional: `verify` works without it.
+- **Authorizer runtime** (use one):
+  - **Docker** (default when the daemon is running): [Docker Desktop](https://www.docker.com/products/docker-desktop/) or your engine, then `tenuo-claude up`. Uses the pinned `tenuo/authorizer` image.
+  - **Native** (no Docker): run `tenuo-claude install-authorizer`, then `tenuo-claude up --native`. On first run, add `--install`. Override the binary with `TENUO_AUTHORIZER_BIN`. Set `TENUO_AUTHORIZER_SKIP_VERSION=1` only for local dev builds.
+  - To force native while Docker is installed, set `TENUO_AUTHORIZER_BACKEND=native` before `bootstrap` or `up`.
+- [Claude Code](https://code.claude.com/docs) — Tenuo wires PreToolUse hooks and MCP proxy at `init`.
 
-**Local mode:** no Tenuo Cloud account. Good for one project or evaluation.
+**Local mode:** no Tenuo Cloud account. Suitable for single-project evaluation.
 
-**Cloud mode:** [cloud.tenuo.ai](https://cloud.tenuo.ai) tenant for tenant-root warrants, central audit, fleet revocation, and org-wide rollout ([Cloud mode](#cloud-mode)).
+**Cloud mode:** requires a [cloud.tenuo.ai](https://cloud.tenuo.ai) tenant for tenant-root warrants, central audit, fleet revocation, and org-wide rollout ([Cloud mode](#cloud-mode)).
 
 ---
 
 ## Use the tool (PyPI)
 
-After [Try it](#try-it), you have an example `tenuo.yaml`, a running authorizer, and passing `verify`. Stay in that project directory for every command below.
+After [Try it](#try-it), you have an example `tenuo.yaml`, a running authorizer, and passing `verify`.
 
 ### Day to day
 
 | When | Command |
 |------|---------|
-| Start work | `tenuo-claude up` or `tenuo-claude up --native` |
-| You edited `tenuo.yaml` | `tenuo-claude refresh` |
-| Something broken | `tenuo-claude check` |
+| Start work (Cloud) | `tenuo-claude check && tenuo-claude up` |
+| Start work (local only) | `tenuo-claude up` or `tenuo-claude up --native` |
+| `check` reports cloud bindings failure | `tenuo-admin setup`, then `check && up` again |
+| You edited `tenuo.yaml` | `tenuo-claude refresh` (local); Cloud capability changes also need `tenuo-admin setup` |
+| Diagnose setup | `tenuo-claude check` |
 | See decisions | `tenuo-claude audit` |
 | Stop authorizer | `tenuo-claude down` |
 
-If you always use native without Docker, set `TENUO_AUTHORIZER_BACKEND=native` in your shell so plain `up` picks the host binary.
+See [Troubleshooting (Q&A)](docs/TROUBLESHOOTING.md) for common errors.
+
+If you always use the native authorizer without Docker, set `TENUO_AUTHORIZER_BACKEND=native` in your shell so plain `up` selects the host binary.
 
 ### Port conflicts
 
@@ -148,13 +160,15 @@ tenuo-claude up
 tenuo-claude verify
 ```
 
-Use `--native` when not running Docker. First native run: add `--install`. Or run `tenuo-claude onboard --local`.
+Use `--native` when Docker is not available. On the first native run, add `--install`. Alternatively, run `tenuo-claude onboard --local` for an interactive setup.
 
 ### Reference demo
 
 Sample policy, MCP stub, and scripted tour in [demo/](demo/). The shipped `demo/tenuo.yaml` is richer than the bootstrap example; Cloud and approval overlays may already be present.
 
-**First time, local only** (no `.state/cloud.env` yet):
+From repo root: `uv venv && uv sync && source .venv/bin/activate`, then:
+
+**First time, local only** (no `.state/cloud.env`):
 
 ```bash
 cd demo
@@ -162,18 +176,37 @@ tenuo-claude bootstrap
 tenuo-claude demo
 ```
 
-**Already Cloud-configured** (`.state/cloud.env` or `tenuo.cloud.yaml` present): do not run plain `bootstrap`. It switches to local mode and moves Cloud files aside. Use:
+**First time, Cloud** (recommended for the reference demo with receipts):
 
 ```bash
 cd demo
-tenuo-claude up
+tenuo-claude bootstrap --cloud
+# or: tenuo-claude onboard --cloud
+tenuo-claude demo
+```
+
+Paste Quick Connect (**Authorizer Only**) into `.state/cloud.env` and tenant-admin
+key into `~/.tenuo/admin.env` when prompted. See [Cloud mode](#cloud-mode).
+
+**Already Cloud-configured** (`.state/cloud.env` or `tenuo.cloud.yaml` present):
+
+Do **not** run plain `bootstrap` — it switches to local mode and moves Cloud files
+aside. Use:
+
+```bash
+cd demo
+tenuo-claude check && tenuo-claude up
 tenuo-claude verify
 tenuo-claude demo
 ```
 
+If `check` fails on **cloud bindings** → `tenuo-admin setup`, then retry.
+
 For human approval: [Cloud mode § Human approval](#human-approval-cloud), then `tenuo-claude demo --advanced --live-approval`.
 
-If you ran local `bootstrap` on a Cloud setup by mistake, restore `.state/cloud.env` and overlays from backup, then run `tenuo-admin setup` to re-claim the holder key.
+If plain `bootstrap` was run on a Cloud-configured project, restore `.state/cloud.env`
+and policy overlays from backup, then `tenuo-admin setup`. See
+[Troubleshooting](docs/TROUBLESHOOTING.md).
 
 From a git checkout, see [Build from source](#build-from-source).
 
@@ -186,21 +219,21 @@ From a git checkout, see [Build from source](#build-from-source).
 | `up` / `down` | Start / stop authorizer. `up` flags: `--native`, `--docker`, `--install` (native, first run) |
 | `install-authorizer` | Install `tenuo-authorizer` to `~/.tenuo/bin` (no manual `cargo`) |
 | `refresh` | Re-apply `tenuo.yaml` (restarts authorizer if up) |
-| `check` | Preflight: deps, credentials, wiring drift |
-| `verify [--deep]` | Policy self-test against the authorizer |
+| `check` | Preflight: deps, credentials, wiring drift, Cloud binding probe |
+| `verify [--deep]` | Policy self-test against the authorizer (no agent session required) |
 | `status` | Warrant, posture, Cloud summary |
 | `onboard` | Interactive local or Cloud setup wizard |
 | `bench [--json]` | Per-tool-call overhead |
 | `audit [--tail N]` | Receipt trail |
 | `revoke` | Revoke session warrant |
 
-See also: [Policy](#policy-tenuoyaml) · [Cloud mode](#cloud-mode) · [docs/DETAILS.md](docs/DETAILS.md)
+See also: [Policy](#policy-tenuoyaml) · [Cloud mode](#cloud-mode) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [docs/DETAILS.md](docs/DETAILS.md)
 
 ---
 
 ## Build from source
 
-For hacking on the CLI, running the reference demo from git, or using `./bin/tenuo-claude` instead of a PyPI install.
+For local development, the reference demo from git, or `./bin/tenuo-claude` instead of a PyPI install.
 
 ```bash
 git clone https://github.com/tenuo-ai/claude-governance.git
@@ -224,13 +257,14 @@ Run commands via the repo launcher or editable install:
 
 ```bash
 cd demo
-tenuo-claude up          # if Cloud is already wired; see Reference demo above
+tenuo-claude check && tenuo-claude up   # Cloud; see Reference demo if check fails
 tenuo-claude demo
 ```
 
-First local-only run: `tenuo-claude bootstrap` instead of `up`, only when `.state/cloud.env` is absent.
+First local-only run (no `.state/cloud.env`): use `tenuo-claude bootstrap` instead.
+First Cloud run: `tenuo-claude bootstrap --cloud` or `onboard --cloud`.
 
-Use `tenuo-claude up --native` instead of plain `up` if you are not running Docker.
+Use `tenuo-claude up --native` when Docker is not available.
 
 Open Claude Code in `demo/`. See [demo/README.md](demo/README.md) and [Reference demo](#reference-demo) above.
 
@@ -294,8 +328,6 @@ Use Cloud when you need organization-scale governance, not just a single laptop:
   every tool call at the hook and MCP proxy. Engineers cannot disable it with local
   Claude permission edits or `--dangerously-skip-permissions`
 
-Local mode (no Cloud account) remains fully supported for evaluation and single-project use.
-
 ### Cloud quickstart
 
 Two keys, two files. Runtime never sees the admin key:
@@ -307,9 +339,7 @@ Two keys, two files. Runtime never sees the admin key:
 
 **Do not** put the tenant-admin key in `.state/cloud.env` or your shell when running `tenuo-claude up`. Runtime refuses to start if an admin key is reachable.
 
-**Fresh project**
-
-Creates an example `tenuo.yaml` if none exists.
+**Fresh project** (creates `tenuo.yaml` if none exists):
 
 ```bash
 pip install tenuo-claude-code
@@ -317,9 +347,7 @@ mkdir my-project && cd my-project
 tenuo-claude bootstrap --cloud
 ```
 
-Requires a Quick Connect token (`tenuo_ct_…`). The wizard prompts for it. Using explicit Cloud URL + API key instead? Use the manual setup block below; `bootstrap --cloud` expects Quick Connect.
-
-Prompts for credentials, then runs `init`, `tenuo-admin setup`, `up`, and `verify`. Pass a tenant-admin key to run setup in the same step.
+The wizard prompts for a Quick Connect token (`tenuo_ct_…`), then runs `init`, `tenuo-admin setup`, `up`, and `verify`. For an explicit Cloud URL and API key without Quick Connect, use the manual setup block below.
 
 Non-interactive:
 
@@ -329,7 +357,7 @@ tenuo-claude bootstrap --cloud --yes \
   --admin-key "tc_…"
 ```
 
-Omit `--admin-key` if `tenuo-admin setup` already ran. Prefer flags over `export TENUO_ADMIN_KEY`. A lingering admin key in the shell makes later `tenuo-claude up` fail.
+Omit `--admin-key` if `tenuo-admin setup` already ran. Pass credentials with flags rather than `export TENUO_ADMIN_KEY`. Unset the admin key before `tenuo-claude up`; an admin key in the runtime environment causes startup to fail.
 
 One-shot env vars for CI:
 
@@ -347,9 +375,9 @@ cd my-project
 tenuo-claude onboard --cloud
 ```
 
-Without providing an admin key to the wizard, have an admin run `tenuo-admin setup` before `up`, or place the admin key in `~/.tenuo/admin.env` and run it yourself.
+If you do not pass an admin key to the wizard, run `tenuo-admin setup` before `up`, or place the admin key in `~/.tenuo/admin.env` and run setup yourself.
 
-Manual equivalent. Credential templates in [templates/](templates/):
+**Manual setup** (equivalent to the wizard). Credential templates are in [templates/](templates/):
 
 ```bash
 cd my-project
@@ -359,13 +387,21 @@ mkdir -p .state ~/.tenuo
 
 tenuo-claude init --cloud
 tenuo-admin setup
-tenuo-claude up
+tenuo-claude check && tenuo-claude up
 tenuo-claude verify
 ```
 
-### Success looks like
+**Every session** (after onboarding):
+
+```bash
+tenuo-claude check && tenuo-claude up
+```
+
+If `check` reports **cloud bindings** failure, run `tenuo-admin setup` and retry.
 
-After onboarding:
+### Verify onboarding
+
+After onboarding, run:
 
 ```bash
 tenuo-claude status
@@ -373,11 +409,14 @@ tenuo-claude check
 tenuo-admin show
 ```
 
-You should see: authorizer up, cloud profile merged, a trigger id in `tenuo-admin show`, and CHECK OK with no admin key in runtime env.
+You should see: authorizer up, cloud profile merged, a trigger id in `tenuo-admin show`, **cloud bindings — trigger fire dry-run OK**, and CHECK OK with no admin key in runtime env.
 
 Re-run `tenuo-admin setup` when Cloud capabilities change — setup syncs the local
-gateway and reloads the authorizer when it is already running. Re-run
-`tenuo-claude refresh` for local-only policy edits (no Cloud trigger change).
+gateway, reconciles agent/trigger/holder bindings, and reloads the authorizer when
+it is already running. Re-run `tenuo-claude refresh` for local-only policy edits (no
+Cloud trigger change).
+
+Stuck? [Troubleshooting (Q&A)](docs/TROUBLESHOOTING.md).
 
 ### Human approval (Cloud)
 
@@ -394,8 +433,8 @@ Both use the same session approval policy and the same hook/proxy approval workf
 
 1. Configure a notification channel and identity binding in Cloud ([channels](https://docs.tenuo.ai/guides/adding-channels),
    [identity bindings](https://docs.tenuo.ai/integrations/identity-bindings)).
-2. Add approval gates in policy. Prefer `cloud.approver_identity_id` for team/shared
-   configs; `cloud.approver_identity` (display name) is fine for demos and quickstarts.
+2. Add approval gates in policy. Use `cloud.approver_identity_id` for team and
+   shared configs. Use `cloud.approver_identity` (display name) for demos only.
    See [templates/tenuo.yaml.advanced.example](templates/tenuo.yaml.advanced.example).
 3. Wire Cloud and re-run setup:
 
@@ -406,14 +445,14 @@ tenuo-claude up            # if authorizer was down
 tenuo-claude verify
 ```
 
-For a quick demo, display-name lookup is still supported:
+For demos, display-name lookup is supported:
 
 ```bash
 tenuo-claude onboard --cloud --advanced --approver "Alice Example"
 ```
 
-If multiple Cloud identities share a display name, setup will ask you to use
-`--approver-id` / `cloud.approver_identity_id`.
+If multiple Cloud identities share a display name, use `--approver-id` or
+`cloud.approver_identity_id` in policy.
 
 Reference demo:
 
@@ -432,9 +471,7 @@ Details: [docs/DETAILS.md § Human approval](docs/DETAILS.md#human-approval-clou
 
 ## Security
 
-Tenuo works **alongside** Claude Code permissions. It does not replace managed settings.
-
-You still deploy hooks. Tenuo adds a signed session warrant, a local authorizer on every tool call, and a decision log per call. Policy is one file (`tenuo.yaml`).
+Tenuo works **alongside** Claude Code permissions — it does not replace managed settings. `tenuo-claude init` wires a PreToolUse hook and MCP proxy; the authorizer enforces the session warrant on every tool call and logs a receipt. Policy is one file (`tenuo.yaml`).
 
 ### vs. Claude Code permissions
 
@@ -448,7 +485,7 @@ You still deploy hooks. Tenuo adds a signed session warrant, a local authorizer
 | Org-wide deployment | Per-user settings; users can edit local hooks | Managed settings + shared policy; hook/proxy enforcement is not user-editable |
 | `--dangerously-skip-permissions` | Bypasses Claude permission prompts | Hook and MCP proxy still enforce the warrant |
 
-That flag skips Claude's permission UI, not the warrant.
+`--dangerously-skip-permissions` skips Claude's permission UI, not the warrant.
 
 Org admins can block it in managed settings (`disableBypassPermissionsMode`).
 
@@ -465,7 +502,7 @@ For teams that need a **global configuration engineers cannot bypass**:
 
 ### Receipts
 
-Every governed tool call must prove possession of the session key (proof-of-possession) when asking the authorizer for allow/deny.
+Every governed tool call carries a proof-of-possession signature; the authorizer verifies it before returning allow/deny.
 
 What you can **read back** depends on mode:
 
@@ -483,7 +520,7 @@ In `mode: audit`, denials show as `WOULD-DENY` in `audit` output (`shadow: true`
 
 These are the non-repudiable receipts for compliance and fleet audit, not the local JSONL file.
 
-![Authorization receipts in Tenuo Cloud](docs/images/cloud-audit-stream.png)
+![Authorization receipts in Tenuo Cloud](https://raw.githubusercontent.com/tenuo-ai/claude-governance/main/docs/images/cloud-audit-stream.png)
 
 More: [docs/DETAILS.md § Receipts](docs/DETAILS.md#receipts).
 
@@ -506,11 +543,25 @@ Runtime refuses to start if an admin key is in the environment.
    in version control, and the [Cloud capabilities above](#cloud-mode). See
    [Tenuo Cloud docs](https://docs.tenuo.ai).
 
-### Scope and fail-closed
+### Scope and boundaries
+
+Tenuo governs **model-invoked tool calls**: Read, Bash, WebFetch, MCP tools,
+subagent spawns, and the rest of the PreToolUse hook path. Each call is checked
+against the signed session warrant before it runs.
+
+**Agent Bash is in scope.** When the model uses the Bash tool, PreToolUse fires and
+the authorizer applies your policy.
+
+**TUI `!` shell is outside this scope.** In Claude Code, typing `!` in the input
+box runs a command the **operator** typed. The model cannot invoke that path.
+Prompt injection and tool overreach stay on the governed PreToolUse path; they do
+not reach `!`.
+
+Details: [docs/DETAILS.md § Agent tools vs operator shell](docs/DETAILS.md#agent-tools-vs-operator-shell).
 
-Governance covers agent tool calls (Read, Bash, MCP, subagent spawns), not interactive `!` shell in the Claude TUI ([Map vs Territory](https://niyikiza.com/posts/map-territory/)).
+### Fail-closed
 
-Missing or broken `tenuo.yaml` denies every call until restored.
+Missing or broken `tenuo.yaml` denies every governed tool call until restored.
 
 Keys and credentials in `.state/` must be owner-only (`0600` in a `0700` directory).