# Herma
Public MCP and /api/preview require no key. Private /v1 routing and management require scoped hmk_ credentials. Personal assistants are supported. Read /connect.json; tracked artifact persistence uses your own Tessera tan_ session or tsk_ key.

> Context-shimming AI middleware for configurable coding harnesses -- intercepts requests via keyword, semantic, or micromodel rules to respond directly or shim caller-isolated noun, verb, and URI context before LLM execution.

- Base URL: https://herma.ta-amps.workers.dev
- Full Reference: https://herma.ta-amps.workers.dev/llms-full.txt
- Agent Card: https://herma.ta-amps.workers.dev/.well-known/agent-card.json
- Stateless MCP JSON-RPC: POST https://herma.ta-amps.workers.dev/mcp
- Read-Only Preview: POST https://herma.ta-amps.workers.dev/api/preview
- Health: GET https://herma.ta-amps.workers.dev/healthz

## Core Authenticated Endpoints (`hmk_` Harness Key Required)
- `POST /v1/handshake`: Negotiate Surface Handshake v1.0 limits (`X-Surface-Id`).
- `POST /v1/conversations/turn`, `GET /v1/conversations/{id}`: Optional typed work dialogue using caller-visible work contracts, expected_version and request_id. Returns a clarification, proposal or blocker with executed:false. Check work_conversations.enabled in /connect.json; requires hmk_ route scope.
- `POST /v1/dry-run`: Inspect caller-isolated augmented payload, matches, entities, and receipt.
- `POST /v1/chat/completions`, `POST /v1/responses`, `POST /v1/messages`: Multi-wire shim or direct-response proxy.
- `GET|POST /v1/context`, `GET /v1/provisions`, `PUT|DELETE /v1/provisions/{prov_id}`: Caller-scoped atomic CAS CRUD (`system_builtin` protected with 403).
- `GET /v1/memory`, `POST /v1/outcomes`, `GET /v1/insights`: Deterministic Anti-RAG working entity memory and reviewable candidate rules.

## Starter Builtin Provisions (`caller_scope = system_builtin`)
- `PROV-DIRECT-NOUN-VERB-SCHEMA` (`respond_directly`, priority 350): Responds directly to natural-language Task and Task-Object or canonical noun/verb schema lookups from Herma's context database without calling an upstream LLM.
- `PROV-TESSERA-FENCING` (`shim_context`, priority 300): Shims monotonic fencing-token, idempotent receipt, CAS version rules, and atomic noun/verb definitions whenever swarm queue or shared-state code is touched.
- `PROV-RISK-REVIEW-NON-ACCUSATORY` (`shim_context`, priority 280): Ensures fraud/harm analysis stays strictly non-accusatory, verifies SYNTHETIC markers, and routes T3/T4 decisions to human reviewers.
- `PROV-HARNESS-FEEDS-GUIDE` (`shim_context`, priority 275): Shims structured guidance on encapsulating Feed Task Objects, HarnessTax token overhead, and receipt-backed benchmarks across Harness Square / Harness2, OpenCode, Pi, and Muse Code.
- `PROV-LORA-MEMORY-ROUTING` (`shim_context`, priority 270): Shims the engineering decision rule separating zero-weight Herma context shimming, Muse Glimmer 30B PEFT LoRAs as parametric memory, and frontier Muse passthrough.
- `PROV-NGO-HUMAN-BOUNDARY` (`shim_context`, priority 260): Triggered via Tier-3 micromodel classifier whenever an agent designs nonprofit/helpline workflows, enforcing human-only boundaries and drafter != reviewer.
- `PROV-EDGE-ORIGIN-LOCKDOWN` (`shim_context`, priority 240): Injects constant-time x-edge-auth origin verification, cookie stripping, and strict HSTS/CSP rules when editing deployment or Worker edge code.

## Security & Isolation Invariants
- Multi-caller non-poisoning: custom provisions, context entries, receipts, working entities, and outcomes are strictly partitioned by `caller_scope = key:<key_id>`.
- Builtin protection: non-admin attempts to overwrite or delete `system_builtin` provisions or context entries return `403 builtin_protected`.
- Admin key lockdown: `/v1/admin/keys` requires bootstrap/admin secret (`403 admin_required` for ordinary `configure` keys).
- Layer-1 Governance Lens: refuses `status:quarantined` items, verifies SHA-256 on `tessera://blobs/<sha>`, and enforces `visibility_scope`, `allowed_surfaces`, and `X-Herma-Cohort`.
- Standard mode only: refuses `contributor` and `*-contributor` model identifiers (`403 contributor_tier_refused`).