Add README + Quickstart sections for agent execution

README.md

@@ -0,0 +1,97 @@
+# Prose Contracts — Syslog Solution LLC
+
+Operating contracts for Hermes agents. Each `.prose.md` file defines a **responsibility** (recurring duty) or **template** (scaffold) that agents can execute via OpenProse or follow manually.
+
+## How Agents Run These Contracts
+
+### Option A: Via OpenProse CLI (preferred)
+
+```bash
+prose run <contract-name> [param1=value1 param2=value2 ...]
+```
+
+**Examples:**
+
+```bash
+# Run a memory audit with default parameters
+prose run memory-audit-maintenance
+
+# Run a memory audit with custom threshold
+prose run memory-audit-maintenance memory_threshold=90 verify_configs=true
+
+# Configure a new agent with the template
+prose run hermes-config-template agent_name=syslog-devops default_model=claude-sonnet-4
+
+# Configure an agent with a different auxiliary model
+prose run hermes-config-template agent_name=syslog-code default_model=qwen3.6-27B-code auxiliary_model=gemma-4-12b
+```
+
+### Option B: Manual Execution
+
+If `prose` CLI isn't available, any agent can:
+1. Fetch the raw contract: `curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/<filename>`
+2. Read the **Execution** section
+3. Follow the steps
+
+**Example for fetching:**
+```bash
+curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/memory-audit-maintenance.prose.md
+```
+
+## Available Contracts
+
+### Responsibilities (Recurring Duties)
+
+| Contract | What It Does | When To Run |
+|---|---|---|
+| `memory-audit-maintenance` | Audits & reorganizes an agent's native memory (MEMORY.md, USER.md). Categorizes entries, moves rules to skills, verifies configs, frees up char budget. | Memory >85% usage or user request: "memory audit" |
+| `zulip-health` | Checks Zulip connectivity, message flow, and bot responsiveness. | On Zulip issues or periodic health check |
+| `litellm-health` | Verifies LiteLLM proxy connectivity, model availability, and key rotation. | On inference failures or periodic check |
+| `litellm-self-heal` | Attempts to fix common LiteLLM issues (key rotation, restart, config reload). | When litellm-health reports failures |
+| `zulip-mention-reliability` | Diagnoses and fixes @mention detection issues in Zulip. | On missed @mention reports |
+| `pm2-self-heal` | Restarts crashed PM2 processes and verifies recovery. | On PM2 process failure |
+
+### Templates (Scaffolds)
+
+| Contract | What It Does | Parameters |
+|---|---|---|
+| `hermes-config-template` | Generates a standard Hermes config for any agent. Enforces shared infra (Firecrawl, SearXNG, RA-H OS MCP, LiteLLM) while keeping model choices flexible. | `agent_name` (required), `default_model`, `default_provider`, `fallback_model`, `auxiliary_model` |
+
+### Scripts
+
+| File | What It Does |
+|---|---|
+| `pm2-self-heal.sh` | Shell script to restart crashed PM2 processes (companion to the prose contract) |
+
+## Contract Structure
+
+Every `.prose.md` file has the same structure:
+
+```
+---
+kind: <responsibility | template>
+name: <unique-name>
+description: ...
+---
+
+## Maintains        — What state the contract tracks
+## Parameters       — Tunable inputs (with defaults)
+## Continuity       — When to run (triggers & cadence)
+## Success Criteria — How to know it worked
+## Remembers        — What to learn between runs
+## <Type> Rules     — Inviolable rules for execution
+## Execution        — Step-by-step instructions
+## Example Output   — What a good run looks like
+```
+
+## Adding New Contracts
+
+1. Create a `.prose.md` file following the structure above
+2. Push to this repo
+3. The contract is immediately available for any agent to `prose run`
+
+## Repository
+
+- **URL:** https://git.sysloggh.net/SyslogSolution/prose-contracts
+- **Branch:** master
+- **Auth:** mumuni-bot (write access via PAT)

hermes-config-template.prose.md

@@ -33,6 +33,67 @@ description: >
 - extra_auxiliary: array — Additional auxiliary tasks to configure (vision, compression, etc.)
 - output_dir: string — Where to write the config (default: "~/.hermes/profiles/<agent_name>/config.yaml")
 
+## Quickstart — How to Run This Contract
+
+### For the Agent Running This Contract
+
+Read this section first. It tells you exactly what to do.
+
+**When to run:**
+- Setting up a **new agent profile** for the first time
+- An **existing profile** is missing web search, firecrawl, or MCP configs
+- User says: `"apply the config template"` or `"fix my infra config"`
+- User says: `"configure <agent_name> with <model>"`
+
+**How to run (via OpenProse CLI):**
+```bash
+# Minimal — only agent name required
+prose run hermes-config-template agent_name=syslog-code
+
+# Full control
+prose run hermes-config-template \
+  agent_name=syslog-devops \
+  default_model=claude-sonnet-4 \
+  auxiliary_model=gemma-4-12b \
+  fallback_model=deepseek-chat \
+  fallback_provider=deepseek
+```
+
+### How to Follow the Template (Manual)
+
+If `prose` CLI is not available:
+
+1. **Fetch this contract:** `curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/hermes-config-template.prose.md`
+2. **Open the target config.yaml** — the profile you're updating
+3. **Compare** each of the 5 required sections below against what exists in the profile
+4. **For each section:**
+   - If it says **SHARED INFRA — DO NOT CHANGE**: Copy the value exactly as shown
+   - If it says **USER CHOOSES**: Use the agent's assigned model/provider
+   - If missing entirely: Add the full section
+5. **Verify** every endpoint responds (see Verification section at the end)
+6. **Restart** the gateway
+
+### Decision Tree
+
+```
+What kind of profile is this?
+├── Main profile (~/.hermes/config.yaml)
+│   └── Replace web.*, mcp_servers.*, compression.*, auxiliary.*, custom_providers.*
+│   └── model.default + fallback: use current values (USER CHOOSES)
+│
+├── Worker profile (~/.hermes/profiles/<name>/config.yaml)
+│   ├── Does it have web.search_backend?
+│   │   ├── NO → Add the full web.* section (copy exactly)
+│   │   └── YES → Verify it points to the right IP
+│   ├── Does it have mcp_servers.ra-h-os?
+│   │   ├── NO → Add mcp_servers.* section (copy exactly)
+│   │   └── YES → Verify URL
+│   └── model.default: USE the worker's assigned model (don't copy main)
+│
+└── Non-Syslog profile (personal/lifestyle agent)
+    └── Skip — use default Hermes config or Tanko's config instead
+```
+
 ## Infrastructure Stack
 
 This template provisions the following shared infrastructure. Every agent should point to the same endpoints unless explicitly overridden.

memory-audit-maintenance.prose.md

@@ -8,6 +8,42 @@ description: >
   exceeds 85% or on explicit user request ("memory audit", "memory maintenance").
 ---
 
+## Quickstart — How to Run This Contract
+
+### For the Agent Running This Contract
+
+Read this section first. It tells you exactly what to do.
+
+**When to run:**
+- User says: `"memory audit"`, `"memory maintenance"`, `"clean up memory"`, `"memory is full"`
+- You detect that your `memory` store usage exceeds 85% in a write attempt
+- It's been 2+ weeks since the last audit
+
+**How to run (via OpenProse CLI):**
+```bash
+# Default — 85% threshold, verify configs, compress entries
+prose run memory-audit-maintenance
+
+# Softer audit — only flag issues, don't rewrite files
+prose run memory-audit-maintenance compress_entries=false
+
+# Hard audit — stricter limits
+prose run memory-audit-maintenance memory_threshold=90 max_memory_chars=800 max_user_chars=300
+```
+
+### How to Follow the Template (Manual)
+
+If `prose` CLI is not available:
+
+1. **Read both memory files:** `cat ~/.hermes/memories/MEMORY.md` and `cat ~/.hermes/memories/USER.md`
+2. **Check in-memory usage:** Use the `memory` tool with no args
+3. **Categorize every entry** using the Categorization Guide below
+4. **Rewrite MEMORY.md** — technical configs only, 800–1,100 chars max
+5. **Rewrite USER.md** — identity + preferences only, 300–500 chars max
+6. **Verify live configs** — curl each endpoint, check each model
+7. **Sync in-memory** — Add summary markers (or just leave file as source of truth)
+8. **Report** using the Example Output template at the bottom
+
 ## Maintains
 
 - last_audit: timestamp — When the last full audit was completed