README: surface verify-before-mutate doctrine, field trust levels, verify-before-fix pattern

- New 'Operating Doctrine (read first)' section with the .117 rule, safe-mutate wrapper usage, field trust taxonomy, and contract-native verify-before-fix flow
- Added hermes-key-enforcement to templates table
- Added stirling-pdf-agent-access to functions table
- Noted VERIFY-BEFORE-USE labels on infrastructure-control

README.md

@@ -2,6 +2,70 @@
 
 Operating contracts for Syslog agents. Each `.prose.md` file defines a **function** (callable helper), **responsibility** (recurring duty with state), or **pattern** (instantiable knowledge/template) that agents can execute via OpenProse or follow manually.
 
+## ⚠️ Operating Doctrine — Read Before Acting
+
+Two rules govern how agents interact with this repo and the infrastructure it
+describes. Internalize both before running or relying on any contract.
+
+### 1. Verify-before-mutate (the `.117` rule)
+
+**Contracts are leads to investigate, NOT facts to act on.** Live-state fields
+(IPs, ports, hostnames, credentials, container names, PIDs) drift. Before any
+mutating operation on infrastructure, verify the current state against the live
+system. On drift, halt and ask the user which value is correct — do NOT "fix"
+the live state to match a stale contract.
+
+Origin: a contract stated Zulip CT 117 was at `.117`; the live IP was `.19`.
+An agent ran `pct set` without checking `pct config` first and changed the IP
+to the wrong value, breaking Zulip. The staleness was harmless until acted on.
+
+**Layer 3 enforcement — the `safe-mutate` wrapper** (deployed on all 5 agents:
+Abiba, Tanko, Mumuni, Koby, Koonimo). ALL infrastructure mutations MUST go
+through `safe-mutate`. Raw `sed -i`, `pct set`, `docker compose up
+--force-recreate`, `kill`, `rm` on infrastructure outside `safe-mutate` is an
+auditable protocol violation. The wrapper runs a verify command, optionally
+checks an `--expect` pattern, refuses on mismatch, and logs every call to
+`/root/.safe-mutate/audit.log`.
+
+```
+safe-mutate --verify "CMD" [--expect "PATTERN"] --mutate "CMD" [--reason "WHY"]
+safe-mutate --verify "CMD" --dry-run --mutate "CMD"      # verify + show, no execute
+safe-mutate --verify "CMD" --verify-only                   # record a verification only
+```
+
+Load the `verify-before-mutate` skill (local pi skill + RA-H shared) for the
+full protocol. See knowledge graph node #604 for the post-mortem.
+
+### 2. Field trust levels
+
+Not all contract content carries the same trust:
+
+| Field type | Trust level | Examples |
+|-----------|-------------|----------|
+| **Policy** | Authoritative — trust the contract | "hardcoded harness keys forbidden", "use api_key_env" |
+| **Live state** | **Never trust — always verify** | IPs, ports, hostnames, credentials, container names, PIDs |
+| **Procedure** | Trust but adapt | command patterns are right, values may be stale |
+
+Contracts label live-state fields with `VERIFY-BEFORE-USE`. Treat any such
+field as a hint to confirm against the live system, not a fact to apply.
+
+### 3. Verify-before-fix (contract-native)
+
+Never `prose run` a fix-contract directly. Run its verifier first, read the
+verdict, lint the fixer, then run:
+
+```
+prose run <verifier>           # e.g. zulip-platform-verification → verdict
+prose lint <fixer>             # validate structure without executing
+prose preflight <fixer>        # check deps/env, no execute
+prose run <fixer>              # only after verdict + lint pass
+```
+
+`kind: responsibility` contracts VERIFY and return a verdict without making
+changes. `kind: function` contracts DO things. Forme `### Requires` →
+`### Maintains` wiring enforces this at the DAG level: a fixer that requires a
+fresh verdict cannot fire until the verifier has run.
+
 ## How Agents Run These Contracts
 
 ### Option A: Via OpenProse CLI (preferred)
@@ -63,7 +127,8 @@ Generate configs or perform a transformation on demand. No persistent state.
 
 | Contract | Description | Key Parameters |
 |---|---|---|
-| `hermes-config-template` | Standard Hermes config for any Syslog agent. Enforces shared infra (Firecrawl, SearXNG, RA-H OS MCP, LiteLLM). | `agent_name` (required), `default_model`, `auxiliary_model` |
+| `hermes-config-template` | Standard Hermes config for any Syslog agent. Enforces shared infra (Firecrawl, SearXNG, RA-H OS MCP, LiteLLM) + standardized `api_key_env` key indirection. | `agent_name` (required), `default_model`, `auxiliary_model` |
+| `hermes-key-enforcement` | **Enforcement contract** — all harness/LiteLLM providers MUST use `api_key_env`, never hardcoded keys. Includes detection query, rotation procedure, violation response. External providers (DeepSeek, OpenAI) exempt. | (none — doctrine reference) |
 
 ### Reference Documents (`kind: pattern` — read for context, not run)
 
@@ -71,7 +136,7 @@ Encode topology, architectural decisions, and lessons. You read them before plan
 
 | Contract | Description |
 |---|---|
-| `infrastructure-control` | Full topology and control pattern: 5-node Proxmox cluster, 3 Docker ecosystems, NFS storage, network verification, IP-first configuration doctrine. |
+| `infrastructure-control` | Full topology and control pattern: 5-node Proxmox cluster, 3 Docker ecosystems, NFS storage, network verification, IP-first configuration doctrine. Live-state fields marked `VERIFY-BEFORE-USE`. |
 | `pi-approval-architecture` | pi's approval model vs Hermes, available commands, architectural constraints. |
 | `zulip-adapter-lessons` | Failure modes, fixes, and patterns from building the pi Zulip extension and Hermes Zulip plugin. |
 
@@ -83,6 +148,7 @@ Called on-demand as single-render tools.
 |---|---|
 | `litellm-health` | Verifies LiteLLM inference stack health: containers, router, GPU fleet, model inference, agent keys. |
 | `infrastructure-monitoring` | Deploys Prometheus + GPU exporters + Grafana to monitor the inference fleet from CT 116. |
+| `stirling-pdf-agent-access` | Documents the Stirling-PDF API access pattern for agents — global API key, 12 operations, curl examples. Agents use the `stirling-pdf-api` shared skill for templates. |
 | `hello-world` | Minimal test contract — verifies the OpenProse execution pipeline works. |
 
 ### Scripts (`scripts/`)