chore: rename packages/ to crates/

Move all 29 workspace members from packages/<name>/ to crates/<name>/. Updates: workspace Cargo.toml (members + path deps), justfile, root CLAUDE.md, scripts/build/CARGO_INSTALL.md, docs/architecture/crates.md (renamed from packages.md), structural references in docs/architecture and docs/configuration, per-crate CLAUDE.md self-references. Historical plans, reports, and building/ docs are left untouched. No behavior change; just check-all stays green and fermata tests pass.
2026-04-30 21:58:57 +02:00
commit c62d8daea8
34 changed files with 12268 additions and 0 deletions
@@ -0,0 +1,148 @@
+# ACP Mocker - Help Feature Demo
+
+## Overview
+
+The ACP mocker now responds to the word "help" sent as a regular message in any session, returning comprehensive diagnostic information about the mocker's configuration.
+
+## Key Points
+
+### Transport Architecture
+
+**stdio is PRIMARY**: The ACP protocol uses stdio (stdin/stdout) as the primary transport method. This is how editors like Zed communicate with agents - they launch the agent as a subprocess and use JSON-RPC over stdio.
+
+**HTTP is ADDITIONAL**: HTTP transport with SSE (Server-Sent Events) is an additional capability we implemented for testing purposes. It's not the standard way editors interact with ACP agents.
+
+### Content Delivery
+
+All response content is sent via `session/update` notifications:
+- **stdio mode** (primary): Notifications are automatically written to stdout
+- **HTTP mode** (testing): Client must subscribe to SSE at `/events/{session_id}`
+
+The `session/prompt` response only contains `{"stopReason": "end_turn"}` - the actual content comes through notifications.
+
+## How to Use
+
+### 1. Start the Mocker (HTTP mode for testing)
+
+```bash
+cargo run --package dirigent_acp_mocker -- serve \
+  --fixtures packages/dirigent_acp_mocker/examples/basic.yaml \
+  --port 8080
+```
+
+### 2. Start with stdio (Primary mode, for Zed)
+
+```bash
+cargo run --package dirigent_acp_mocker -- serve \
+  --fixtures packages/dirigent_acp_mocker/examples/basic.yaml \
+  --stdio
+```
+
+Then configure Zed's `settings.json`:
+```json
+{
+  "agent_servers": {
+    "dirigent-acp-mocker": {
+      "command": "G:/dev/projects/dirigent/target/debug/dirigent-acp-mocker.exe",
+      "args": [
+        "serve",
+        "--fixtures",
+        "G:/dev/projects/dirigent/packages/dirigent_acp_mocker/examples/basic.yaml",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+
+### 3. Test via HTTP (Testing Only)
+
+```bash
+# Initialize
+curl -X POST http://localhost:8080/jsonrpc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "initialize",
+    "params": {
+      "protocolVersion": 1,
+      "clientCapabilities": {}
+    },
+    "id": 1
+  }'
+
+# Create session
+curl -X POST http://localhost:8080/jsonrpc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "session/new",
+    "params": {},
+    "id": 2
+  }'
+
+# Send "help" message (replace SESSION_ID with actual ID)
+curl -X POST http://localhost:8080/jsonrpc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "session/prompt",
+    "params": {
+      "sessionId": "SESSION_ID",
+      "prompt": [
+        {
+          "type": "text",
+          "text": "help"
+        }
+      ]
+    },
+    "id": 3
+  }'
+
+# To see the actual response content, subscribe to SSE (in separate terminal):
+curl -N http://localhost:8080/events/SESSION_ID
+```
+
+### 4. Test via Python Script
+
+```bash
+# Using the test helper
+python tools/test_help.py --port 8080
+```
+
+## What You Get
+
+When you send "help" as a message, you'll receive a diagnostic response including:
+
+- **Mocker Information**: Name, version, transport clarification
+- **Fixture Configuration**: Version, available sessions, session IDs
+- **Streaming Settings**: Enabled/disabled, chunk size, interval, jitter
+- **Responder Configuration**: Default strategy, keyword mappings, random corpus
+- **Active Sessions**: Currently active session count and IDs
+- **Transport Explanation**: Clear explanation that stdio is primary, HTTP is for testing
+- **Available Methods**: All ACP methods and extensions
+- **Keywords to Try**: List of configured keywords that trigger specific responses
+
+## Alternative: Method-Based Help
+
+You can also call `_dirigent/help` as a JSON-RPC method:
+
+```bash
+curl -X POST http://localhost:8080/jsonrpc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "_dirigent/help",
+    "id": 1
+  }'
+```
+
+This returns the same diagnostic information but as structured JSON rather than formatted markdown.
+
+## Why This Matters
+
+1. **Debugging**: Quickly check if fixtures loaded correctly
+2. **Configuration Verification**: See what keywords and responders are active
+3. **Testing**: Understand streaming settings and session state
+4. **Learning**: Get inline documentation about available methods
+5. **Transport Clarity**: Understand that stdio is primary, HTTP is for testing only