# Index of herma

Every file in this repo with a one-line description taken from the file itself. Generated by `scripts/build_index.py`; run `make index` after adding files, never edit by hand.

## Top level (10)

| File | What it is |
|---|---|
| [.gitignore](.gitignore) |  |
| [AGENTS.md](AGENTS.md) | AGENTS.md -- Herma Hard Rules |
| [CHANGELOG.md](CHANGELOG.md) | Changelog |
| [LICENSE](LICENSE) | MIT License |
| [Makefile](Makefile) | Herma. |
| [README.md](README.md) | Herma |
| [architecture.json](architecture.json) | herma |
| [package.json](package.json) | herma-worker |
| [pyproject.toml](pyproject.toml) |  |
| [vitest.config.mjs](vitest.config.mjs) |  |

## .claude/ (2)

| File | What it is |
|---|---|
| [.claude/hooks/guard.py](.claude/hooks/guard.py) | Claude Code PreToolUse guard: enforces the hard rules in every permission mode. |
| [.claude/settings.json](.claude/settings.json) | JSON object: $schema, permissions, hooks |

## .github/ (1)

| File | What it is |
|---|---|
| [.github/workflows/ci.yml](.github/workflows/ci.yml) |  |

## deploy/ (15)

| File | What it is |
|---|---|
| [deploy/bootstrap-hosting.sh](deploy/bootstrap-hosting.sh) | One-time hosting setup for one service on Fly.io behind a Cloudflare Worker: the Fly app and its |
| [deploy/cloudflare/agent_access.js](deploy/cloudflare/agent_access.js) |  |
| [deploy/cloudflare/agent_start.js](deploy/cloudflare/agent_start.js) | Versioned onboarding instructions. |
| [deploy/cloudflare/conversation.js](deploy/cloudflare/conversation.js) | Typed proposals only. |
| [deploy/cloudflare/conversation_data.json](deploy/cloudflare/conversation_data.json) | JSON object: categories, schemas, system_prompt |
| [deploy/cloudflare/conversation_state.js](deploy/cloudflare/conversation_state.js) | Conversation coordination, not a work queue. |
| [deploy/cloudflare/d1-herma.sql](deploy/cloudflare/d1-herma.sql) | Persistent Cloudflare D1 caller-isolated schema for Herma context-shimming AI middleware (ta-amps-herma). |
| [deploy/cloudflare/entry.js](deploy/cloudflare/entry.js) |  |
| [deploy/cloudflare/herma_engine.js](deploy/cloudflare/herma_engine.js) | Context-shimming 3-tier trigger engine, multi-caller isolation, governance lens, |
| [deploy/cloudflare/provider_diagnostics.js](deploy/cloudflare/provider_diagnostics.js) | Fixed provider-reported categories only. |
| [deploy/cloudflare/provider_health.js](deploy/cloudflare/provider_health.js) | Deterministic shared availability inside the existing operator allowance coordinator. |
| [deploy/cloudflare/worker.js](deploy/cloudflare/worker.js) |  |
| [deploy/cloudflare/wrangler.jsonc](deploy/cloudflare/wrangler.jsonc) | Herma Cloud Worker: 24/7 context-shimming AI middleware on Cloudflare Workers + D1 (ta-amps-herma) |
| [deploy/fly/Dockerfile](deploy/fly/Dockerfile) |  |
| [deploy/fly/fly.toml](deploy/fly/fly.toml) |  |

## docs/ (12)

| File | What it is |
|---|---|
| [docs/WORKER-FIRST-EXECUTION.md](docs/WORKER-FIRST-EXECUTION.md) | Worker-first execution and private work |
| [docs/access-modes.md](docs/access-modes.md) | External agent access |
| [docs/agent-troubleshooting.md](docs/agent-troubleshooting.md) | Bilateral agent communication |
| [docs/architecture.md](docs/architecture.md) | Architecture |
| [docs/conversations.md](docs/conversations.md) | Typed work conversations |
| [docs/design-and-evidence.md](docs/design-and-evidence.md) | Design decisions and measured limits |
| [docs/evidence/conversation-observations.json](docs/evidence/conversation-observations.json) | JSON object: schema_version, observed_date, scope, provider_credentials, runs, source_run_fingerprint |
| [docs/evidence/native-hosted-observation.json](docs/evidence/native-hosted-observation.json) | JSON object: schema_version, observed_date, harness, provider, model, mode |
| [docs/handoff.md](docs/handoff.md) | Handoff & Status |
| [docs/harnesses.md](docs/harnesses.md) | Connecting Configurable Agentic Coding Harnesses |
| [docs/setup.md](docs/setup.md) | Setup, Context Database, Backing Stores & Cloudflare Deployment |
| [docs/summary.md](docs/summary.md) | Summary |

## examples/ (7)

| File | What it is |
|---|---|
| [examples/provisions/PROV-DIRECT-NOUN-VERB-SCHEMA.json](examples/provisions/PROV-DIRECT-NOUN-VERB-SCHEMA.json) | Direct Canonical Noun & Verb Schema Lookup |
| [examples/provisions/PROV-EDGE-ORIGIN-LOCKDOWN.json](examples/provisions/PROV-EDGE-ORIGIN-LOCKDOWN.json) | Cloudflare Worker x-edge-auth & Security Header Contract |
| [examples/provisions/PROV-NGO-HUMAN-BOUNDARY.json](examples/provisions/PROV-NGO-HUMAN-BOUNDARY.json) | NGO Kit Human-Only Crisis & Two-Donor Review Boundary |
| [examples/provisions/PROV-SHAMASH-NON-ACCUSATORY.json](examples/provisions/PROV-SHAMASH-NON-ACCUSATORY.json) | Non-Accusatory Risk Indicators & Synthetic Bundle Guard |
| [examples/provisions/PROV-TESSERA-FENCING.json](examples/provisions/PROV-TESSERA-FENCING.json) | Tessera Atomic Lease Fencing & Compare-and-Set Storage |
| [examples/provisions/README.md](examples/provisions/README.md) | Example Provisions & Atomic Noun/Verb Context |
| [examples/provisions/context/CONTEXT-TESSERA-NOUNS-VERBS.json](examples/provisions/context/CONTEXT-TESSERA-NOUNS-VERBS.json) | JSON object: entries |

## herma/ (28)

| File | What it is |
|---|---|
| [herma/__init__.py](herma/__init__.py) | Herma: context-shimming AI middleware for configurable coding harnesses. |
| [herma/agent_access.py](herma/agent_access.py) | Bounded, stateless browser-agent transport; bearer authorization stays in each route. |
| [herma/api/__init__.py](herma/api/__init__.py) | FastAPI HTTP service and read-only console pages for Herma. |
| [herma/api/app.py](herma/api/app.py) | FastAPI application for Herma middleware (:7730). |
| [herma/api/pages.py](herma/api/pages.py) | Server-rendered HTML console, SVG brand chrome, interactive preview script, and discovery specs. |
| [herma/cli.py](herma/cli.py) | Command-line interface for Herma: seed, keys, context, dry-run, 3-tier demo, and serve. |
| [herma/conversation.py](herma/conversation.py) | Scoped dialogue producing typed proposals; execution stays in the caller's harness. |
| [herma/conversation_contracts.py](herma/conversation_contracts.py) | Typed, caller-configured work contracts and validated conversational proposals. |
| [herma/conversation_provider.py](herma/conversation_provider.py) | Bounded provider calls with fixed credential destinations and explicit tool schemas. |
| [herma/conversation_schema.py](herma/conversation_schema.py) | Bounded JSON Schema profile shared with the Worker conversation validator. |
| [herma/conversation_state.py](herma/conversation_state.py) | Durable caller isolation, per-turn CAS and pre-call conversation budgets. |
| [herma/decision_provider.py](herma/decision_provider.py) | Pure Jev wire adapter for authorized workers; no transport or server fallback. |
| [herma/errors.py](herma/errors.py) | Typed errors mapped deterministically to RFC 9457 problem+json HTTP responses. |
| [herma/harness_gate.py](herma/harness_gate.py) | Configurable-harness access gate: authenticates scoped agent and personal-assistant clients. |
| [herma/injector.py](herma/injector.py) | Extracts signals and deterministic entities from payloads and shims rules, URIs, and noun/verb context. |
| [herma/memory.py](herma/memory.py) | Deterministic Anti-RAG top-of-mind entity extraction and candidate rule synthesis (0 LLM calls). |
| [herma/profiles.py](herma/profiles.py) | Adaptive CallerProfile shimming lenses, deterministic strategy ranking, and budget enforcement. |
| [herma/provider_diagnostics.py](herma/provider_diagnostics.py) | Bounded provider-reported error categories, never raw messages or identifiers. |
| [herma/provider_health.py](herma/provider_health.py) | Deterministic operator availability inside the existing provider allowance lifecycle. |
| [herma/provider_plan.py](herma/provider_plan.py) | Explicit provider-plan nouns and per-caller operator grants; selection adds no work authority. |
| [herma/proxy.py](herma/proxy.py) | Context-shimming interception, direct-response short-circuiting, and upstream LLM forwarding. |
| [herma/schemas.py](herma/schemas.py) | Strict Pydantic schemas for provisions, context entries, triggers, memory, outcomes, and receipts. |
| [herma/store.py](herma/store.py) | SQLite WAL caller-isolated store, atomic CAS, governance lens, entity memory, and outcome telemetry. |
| [herma/triggers/__init__.py](herma/triggers/__init__.py) | Three-tier trigger evaluation: keyword (~0 ms), semantic (~1-5 ms), and micromodel. |
| [herma/triggers/engine.py](herma/triggers/engine.py) | Orchestrates Tier-1 (keyword), Tier-2 (semantic), and Tier-3 (micromodel) triggers. |
| [herma/triggers/keyword.py](herma/triggers/keyword.py) | Tier-1 deterministic trigger (~0 ms): keywords, bounded regexes, path globs, and tool names. |
| [herma/triggers/micromodel.py](herma/triggers/micromodel.py) | Tier-3 micromodel router trigger: fast tiny/cloud classifier with deterministic offline fallback. |
| [herma/triggers/semantic.py](herma/triggers/semantic.py) | Tier-2 semantic similarity trigger (~1-5 ms): hybrid concept + subword cosine + optional embeddings. |

## scripts/ (4)

| File | What it is |
|---|---|
| [scripts/build_conversation_data.py](scripts/build_conversation_data.py) | Export canonical category guidance and the prompt for the Worker, without model calls. |
| [scripts/build_index.py](scripts/build_index.py) | Build this repo's indexes from its own files. |
| [scripts/check_architecture.py](scripts/check_architecture.py) | Check that architecture.json still describes this repo truthfully. |
| [scripts/check_public.py](scripts/check_public.py) | Fail if a file headed for a public repo holds a secret or a private name. |

## test/ (5)

| File | What it is |
|---|---|
| [test/conversation.test.js](test/conversation.test.js) |  |
| [test/provider_diagnostics.test.js](test/provider_diagnostics.test.js) |  |
| [test/provider_grants.test.js](test/provider_grants.test.js) |  |
| [test/provider_health.test.js](test/provider_health.test.js) |  |
| [test/triggers.test.js](test/triggers.test.js) |  |

## tests/ (19)

| File | What it is |
|---|---|
| [tests/conftest.py](tests/conftest.py) | Synthetic operator grants for managed conversation tests; no provider is ever contacted. |
| [tests/test_api_and_proxy.py](tests/test_api_and_proxy.py) | Tests for multi-protocol payload augmentation, deduplication, edge lockdown, and HTTP endpoints. |
| [tests/test_cli_demo.py](tests/test_cli_demo.py) | The CI demo verifies the supported client policy and its real provision pipeline. |
| [tests/test_conversation.py](tests/test_conversation.py) | Typed proposals, caller isolation, budget fencing and real HTTP provider contracts. |
| [tests/test_conversation_schema_parity.py](tests/test_conversation_schema_parity.py) | Cross-runtime fixtures for the portable conversation schema boundary. |
| [tests/test_conversation_storage.py](tests/test_conversation_storage.py) | Real SQLite failures stop paid rotation, seal the turn and keep evidence for reconciliation. |
| [tests/test_decision_provider.py](tests/test_decision_provider.py) | Jev is a typed worker decision protocol, not a generative fallback. |
| [tests/test_external_access_security.py](tests/test_external_access_security.py) | Regression proofs for scoped personal-assistant access and fail-closed fabric imports. |
| [tests/test_harness_gate_and_store.py](tests/test_harness_gate_and_store.py) | Tests for configurable-harness access gate, CAS store, Tessera sync, and remote handshake sync. |
| [tests/test_herma.py](tests/test_herma.py) | Tests for multi-caller isolation, CAS, governance lens, entity memory, insights, preview, and MCP parity. |
| [tests/test_index_portability.py](tests/test_index_portability.py) | The index CLI produces the same bytes in differently named checkouts. |
| [tests/test_provider_accounting.py](tests/test_provider_accounting.py) | Known skips do not spend allowance; nonfinal provider outcomes keep reservations. |
| [tests/test_provider_contracts.py](tests/test_provider_contracts.py) | Provider selection, native generation and exception allowance stay explicit. |
| [tests/test_provider_diagnostics.py](tests/test_provider_diagnostics.py) | Provider error evidence is bounded, private and never a raw response echo. |
| [tests/test_provider_grants.py](tests/test_provider_grants.py) | Operator spending grants name exact callers, and one upstream model is one identity. |
| [tests/test_provider_health.py](tests/test_provider_health.py) | Shared operator limits admit one funded, explicitly authorized recovery probe. |
| [tests/test_provider_plan.py](tests/test_provider_plan.py) | Explicit private plans may advance providers without losing charged attempts. |
| [tests/test_runtime_parity.py](tests/test_runtime_parity.py) | Python and the Worker make identical spending, identity and parsing decisions. |
| [tests/test_triggers.py](tests/test_triggers.py) | Tests for Tier-1 (keyword/regex/path/tool), Tier-2 (semantic), and Tier-3 (micromodel) triggers. |