@spilno/herald-mcp 1.28.0 → 1.28.2

package/README.md

@@ -18,157 +18,144 @@ AI agents start fresh each session. Herald gives them memory:
 ## Quick Start
 
 ```bash
-# One command setup for Claude Desktop
+cd your-project
 npx @spilno/herald-mcp init
+```
+
+**That's it.** Context is derived from your folder path automatically. Zero config.
+
+Then start Claude Code and say `herald health` to verify.
 
-# Or install globally
-npm install -g @spilno/herald-mcp
-herald-mcp init
+## Init Options
+
+```bash
+npx @spilno/herald-mcp init [options]
 ```
 
-Done. Herald is now available to Claude.
+| Option | Description |
+|--------|-------------|
+| `--force`, `-f` | Overwrite existing config |
+| `--no-claude-md` | Skip CLAUDE.md modification |
+| `--help`, `-h` | Show help |
+
+Context tags are derived automatically from your folder path - no configuration needed.
 
 ## Core Tools
 
 | Tool | Purpose |
 |------|---------|
-| `herald_predict` | Generate structure from natural language |
-| `herald_refine` | Refine predictions with feedback |
 | `herald_patterns` | Query what worked before |
 | `herald_reflect` | Capture patterns and antipatterns |
+| `herald_predict` | Generate structure from natural language |
+| `herald_refine` | Refine predictions with feedback |
 | `herald_feedback` | Reinforce helpful patterns |
 
-### Pattern Memory
-
-```
-AI: herald_patterns()
-→ Returns: patterns that worked, antipatterns to avoid
+## Pattern Capture
 
-AI: herald_predict("create safety assessment module")
-→ Returns: structured prediction based on accumulated patterns
+When something works or fails, capture it:
 
-User: "That worked well"
-AI: herald_reflect(feeling="success", insight="field grouping approach")
-→ Pattern captured, weight increased
+```
+User: "Herald reflect - that was smooth"
+Claude: "What specifically worked?"
+User: "The ASCII visualization approach"
+→ Pattern captured, available in future sessions
+
+User: "Herald reflect - that was rough"
+Claude: "What went wrong?"
+User: "Forgot to check existing tests before refactoring"
+→ Antipattern captured, Claude will avoid this
 ```
 
-## Session Flow
-
-```bash
-# Start a session
-herald-mcp predict "create incident report module"
-
-# Refine iteratively
-herald-mcp refine "add witness section"
-herald-mcp refine "require photos for severity > 3"
+## How Context Works
 
-# Accept when satisfied
-herald-mcp observe yes
+Herald derives context **automatically** from your working directory:
 
-# Resume anytime
-herald-mcp resume
 ```
-
-## Configuration
-
-### Claude Desktop / Claude Code
-
-```json
-{
-  "mcpServers": {
-    "herald": {
-      "command": "npx",
-      "args": ["@spilno/herald-mcp"],
-      "env": {
-        "HERALD_API_URL": "https://getceda.com"
-      }
-    }
-  }
-}
+~/Documents/acme-corp/safety-app
+                ↓
+Tags: ["acme-corp", "safety-app"]
 ```
 
-### Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `HERALD_API_URL` | Yes | CEDA server (default: https://getceda.com) |
-| `HERALD_COMPANY` | No | Multi-tenant company context |
-| `HERALD_PROJECT` | No | Project context |
-| `HERALD_USER` | No | User context |
+Patterns are matched by **tag overlap**, not rigid hierarchy:
+- Your patterns in `project-a` can help in `project-b` if they share tags
+- No need to configure company/project/user upfront
+- Structure emerges from usage, not configuration
 
-## Multi-Tenant Isolation
+## Pattern Reach
 
-Patterns are isolated by context:
+Patterns expand organically through adoption:
 
 ```
-Company A patterns → Only visible to Company A
-Project X patterns → Only visible to Project X users
+CREATOR  →  Only you see it
+    ↓
+TAGS     →  Users with overlapping context tags see it
+    ↓
+GLOBAL   →  Everyone sees it (anonymized)
 ```
 
-Set context via environment or headers:
-```bash
-export HERALD_COMPANY=acme
-export HERALD_PROJECT=safety-modules
-```
+Reach expands when others validate your patterns work for them too.
 
-## Herald Context Sync
+## Configuration
 
-Herald instances share insights across contexts:
+### Files Created by Init
 
-| Tool | Purpose |
+| File | Purpose |
 |------|---------|
-| `herald_context_status` | Check status of Herald instances |
-| `herald_share_insight` | Share pattern to other contexts |
-| `herald_query_insights` | Query shared insights |
-| `herald_sync` | Flush local buffer to cloud |
+| `.claude/settings.local.json` | MCP server configuration |
+| `CLAUDE.md` | Project instructions with Herald integration |
 
-## Chat Mode
+### Environment Variables
 
-For humans who prefer conversation:
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CEDA_URL` | `https://getceda.com` | CEDA backend URL |
+| `HERALD_USER` | System username | User identity (optional override) |
 
-```bash
-herald-mcp chat
-```
+## Troubleshooting
 
-```
-You: I need a permit-to-work module
-Herald: I've designed a Permit-to-Work module with 5 sections...
+### Old version loading after update
+
+If `herald health` shows an old version after updating:
+
+```bash
+# Clear npx cache
+rm -rf ~/.npm/_npx/*
 
-You: Add gas testing checklist
-Herald: Added gas testing to Pre-Work Safety section...
+# Verify latest version
+npm view @spilno/herald-mcp version
 
-You: Perfect
-Herald: Module accepted and saved.
+# Restart Claude Code
 ```
 
-## Command Reference
+The `@latest` tag can be cached by npx. Clearing the cache forces a fresh fetch.
+
+### Verify installation
 
 ```bash
-herald-mcp init          # Setup for Claude Desktop
-herald-mcp chat          # Interactive conversation mode
-herald-mcp predict <signal>  # Generate prediction
-herald-mcp refine <signal>   # Refine current prediction
-herald-mcp resume        # Resume last session
-herald-mcp observe <yes|no>  # Accept or reject prediction
-herald-mcp new           # Start fresh session
-herald-mcp health        # Check CEDA connection
-herald-mcp stats         # Show loaded patterns
+# Check what npm registry has
+npm view @spilno/herald-mcp version
+
+# Should match what herald health shows
 ```
 
 ## Architecture
 
 ```
 ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│   AI Agent  │────▶│   Herald    │────▶│    CEDA     │
-│ (Claude/    │     │   (MCP)     │     │  (Pattern   │
-│  Devin/etc) │◀────│             │◀────│   Memory)   │
+│   Claude    │────▶│   Herald    │────▶│    CEDA     │
+│   Code      │     │   (MCP)     │     │  (Pattern   │
+│             │◀────│             │◀────│   Memory)   │
 └─────────────┘     └─────────────┘     └─────────────┘
-                           │
-                    ┌──────┴──────┐
-                    │ Patterns    │
-                    │ Antipatterns│
-                    │ Feedback    │
+       │                   │
+       │            ┌──────┴──────┐
+       │            │ Tags        │
+       └───────────▶│ Patterns    │
+                    │ Reach       │
                     └─────────────┘
+
+Context derived from folder path → Tags
+Patterns matched by tag overlap
+Reach expands through adoption
 ```
 
 ## What is CEDA?
@@ -193,4 +180,4 @@ MIT
 
 ---
 
-*Herald v1.20.0 — Pattern memory for AI agents*
+*Herald v1.28.2 — Pattern memory for AI agents*

package/dist/index.js

@@ -42,7 +42,7 @@ const HERALD_VAULT = process.env.HERALD_VAULT || "";
 const AEGIS_OFFSPRING_PATH = process.env.AEGIS_OFFSPRING_PATH || join(homedir(), "Documents", "aegis_ceda", "_offspring");
 // Cloud mode: Use CEDA API for offspring communication instead of local files
 const OFFSPRING_CLOUD_MODE = process.env.HERALD_OFFSPRING_CLOUD === "true";
-const VERSION = "1.28.0";
+const VERSION = "1.28.2";
 // Self-routing description - teaches Claude when to call Herald
 const HERALD_DESCRIPTION = `AI-native pattern learning for CEDA.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spilno/herald-mcp",
-  "version": "1.28.0",
+  "version": "1.28.2",
   "description": "Herald MCP - AI-native interface to CEDA (Cognitive Event-Driven Architecture)",
   "main": "dist/index.js",
   "type": "module",