@dp-pcs/ogp 0.3.3 → 0.4.3

package/README.md

@@ -44,7 +44,28 @@ After installation, install the OGP skills for Claude Code:
 ogp-install-skills
 ```
 
-This auto-discovers and installs all OGP skills from the `skills/` directory.
+This auto-discovers and installs all OGP skills from the `skills/` directory. The installer now replaces each installed skill directory wholesale on upgrade so stale files from older package versions do not survive.
+
+Verify the installed copies after an upgrade:
+
+```bash
+rg -n '^version:' ~/.openclaw/skills/ogp*/SKILL.md ~/.claude/skills/ogp*/SKILL.md 2>/dev/null
+```
+
+For the current `0.4.2` release line, the changed skills should report:
+- `ogp` `2.6.0`
+- `ogp-agent-comms` `0.6.0`
+- `ogp-project` `2.2.0`
+
+### Multi-Framework Support
+
+OGP supports running alongside multiple AI frameworks (OpenClaw, Hermes, etc.) with isolated configurations. During setup, OGP automatically detects installed frameworks and creates framework-specific configurations:
+
+- **OpenClaw**: `~/.ogp-openclaw/`
+- **Hermes**: `~/.ogp-hermes/`
+- **Standalone**: `~/.ogp/`
+
+All framework configurations are managed from a central meta-config at `~/.ogp-meta/config.json`.
 
 ## Quick Start
 
@@ -56,15 +77,33 @@ Run the interactive setup wizard:
 ogp setup
 ```
 
-You'll be prompted for:
-- **Agent ID** - Which OpenClaw agent owns this gateway (auto-discovers available agents from your OpenClaw config)
-- Daemon port (default: 18790)
-- OpenClaw URL (default: http://localhost:18789)
-- OpenClaw API token
-- Your public gateway URL (can update later, or use rendezvous)
+The wizard automatically detects installed frameworks and guides you through configuration. You'll be prompted for:
+- **Framework Selection** - Which AI frameworks to enable (OpenClaw, Hermes, or standalone)
+- **Agent ID** - Which agent owns each gateway (auto-discovers from framework config)
+- Daemon port (default: 18790 for OpenClaw, 18793 for Hermes)
+- Framework URL and API credentials
+- Your public gateway URL (can update later; rendezvous is optional discovery/invite sugar, not a replacement for reachability)
 - Rendezvous configuration (optional, v0.2.14+)
 - Display name and email
 
+**Working with Multiple Frameworks:**
+
+When multiple frameworks are configured, use the `--for` flag to specify which framework:
+
+```bash
+# Use specific framework
+ogp --for openclaw federation list
+ogp --for hermes federation list
+
+# Run on all frameworks
+ogp --for all status
+
+# Set a default framework (no --for needed)
+ogp config set-default openclaw
+```
+
+If only one framework is configured, it's automatically selected (no `--for` flag needed).
+
 ### 2. Start the Daemon
 
 ```bash
@@ -77,6 +116,17 @@ Or run in the background:
 ogp start --background
 ```
 
+**Multi-framework usage:**
+
+```bash
+# Start daemon for specific framework
+ogp --for openclaw start --background
+ogp --for hermes start --background
+
+# Start all framework daemons
+ogp --for all start --background
+```
+
 ### 3. Making Your Gateway Reachable
 
 For OGP federation to work, peers need to be able to reach your gateway over the internet. If you already have a publicly accessible URL (cloud server, VPS, Clawporate gateway), just set it as your `gatewayUrl` in `~/.ogp/config.json` and you're done. Skip to step 4.
@@ -174,21 +224,45 @@ https://your-gateway-url.com/.well-known/ogp
 
 ## All Commands
 
+All commands support the `--for <framework>` flag to specify which framework configuration to use. Use `--for all` to run commands across all configured frameworks.
+
+**Quick Help:** Add `?` to any command for context-sensitive help:
+
+```bash
+ogp ?                      # Show all commands
+ogp federation ?           # Show federation commands
+ogp federation send ?      # Show send usage with examples
+```
+
+### Tab Completion
+
+Install shell completion for faster command entry:
+
+```bash
+# Bash
+ogp completion install bash
+
+# Zsh
+ogp completion install zsh
+```
+
+After installation, restart your shell or run `source ~/.bashrc` (bash) or `source ~/.zshrc` (zsh).
+
 ### Daemon Management
 
 | Command | Description |
 |---------|-------------|
-| `ogp setup` | Interactive setup wizard |
-| `ogp start` | Start daemon in foreground |
-| `ogp start --background` | Start daemon as background process |
-| `ogp stop` | Stop the daemon |
-| `ogp status` | Show daemon status and configuration |
+| `ogp setup` | Interactive setup wizard (auto-detects frameworks) |
+| `ogp start [--for <framework>]` | Start daemon in foreground |
+| `ogp start --background [--for <framework>]` | Start daemon as background process |
+| `ogp stop [--for <framework>]` | Stop the daemon |
+| `ogp status [--for <framework>]` | Show daemon status and configuration |
 
 ### Tunnel Management
 
 | Command | Description |
 |---------|-------------|
-| `ogp expose` | Launch guided tunnel setup wizard (coming soon) or start cloudflared tunnel in foreground |
+| `ogp expose` | Start a Cloudflare quick tunnel in the foreground; use the `ogp-expose` skill/doc flow for guided setup |
 | `ogp expose --background` | Run tunnel as background process |
 | `ogp expose --method ngrok` | Use ngrok instead of cloudflared |
 | `ogp expose stop` | Stop the tunnel |
@@ -200,11 +274,21 @@ https://your-gateway-url.com/.well-known/ogp
 | `ogp install` | Install LaunchAgent for auto-start on login |
 | `ogp uninstall` | Remove LaunchAgent |
 
+### Configuration Management
+
+| Command | Description |
+|---------|-------------|
+| `ogp config list` | List all configured frameworks |
+| `ogp config set-default <framework>` | Set default framework (no --for needed) |
+| `ogp config enable <framework>` | Enable a framework |
+| `ogp config disable <framework>` | Disable a framework |
+| `ogp config show [--for <framework>]` | Show current configuration |
+
 ### Federation Management
 
 | Command | Description |
 |---------|-------------|
-| `ogp federation list` | List all peers |
+| `ogp federation list [--for <framework>]` | List all peers |
 | `ogp federation list --status pending` | List pending federation requests |
 | `ogp federation list --status approved` | List approved peers |
 | `ogp federation request <url> [alias]` | Request federation (alias auto-resolves if omitted) |
@@ -255,6 +339,7 @@ When approving or granting scopes:
 
 | Command | Description |
 |---------|-------------|
+| `ogp agent-comms interview` | Re-run the delegated-authority / human-delivery interview |
 | `ogp agent-comms policies [peer-id]` | Show response policies |
 | `ogp agent-comms configure [peer-ids] [options]` | Configure response policies |
 | `ogp agent-comms add-topic <peer> <topic> [options]` | Add topic policy |
@@ -271,54 +356,57 @@ When approving or granting scopes:
 ogp federation request https://peer.example.com
 
 # Or specify a custom alias for easier reference
-ogp federation request https://peer.example.com --alias big-papa
+ogp federation request https://peer.example.com --alias apollo
+
+# Multi-framework: Request from specific framework
+ogp --for openclaw federation request https://hermes.example.com --alias hermes-gateway
 
 # Check pending requests
 ogp federation list --status pending
 
 # Approve a peer (v0.1 mode - no scope restrictions)
-ogp federation approve alice
+ogp federation approve apollo
 
 # Approve with scope grants (v0.2.0+)
-ogp federation approve alice \
+ogp federation approve apollo \
   --intents message,agent-comms \
   --rate 100/3600 \
   --topics memory-management,task-delegation
 
 # View peer scopes
-ogp federation scopes alice
+ogp federation scopes apollo
 
 # Update grants for an existing peer
-ogp federation grant alice \
+ogp federation grant apollo \
   --intents agent-comms \
   --topics project-planning
 
 # Remove a peer from federation (asymmetric tear-down)
-ogp federation remove alice
+ogp federation remove apollo
 
 # Test connectivity
 ogp federation ping https://peer.example.com
 
 # Send a simple message
-ogp federation send alice message '{"text":"Hello!"}'
+ogp federation send apollo message '{"text":"Hello!"}'
 
 # Send agent-comms (v0.2.0+)
-ogp federation agent alice memory-management "How do you persist context?"
+ogp federation agent apollo memory-management "How do you persist context?"
 
 # Send agent-comms with priority
-ogp federation agent alice task-delegation "Schedule standup" --priority high
+ogp federation agent apollo task-delegation "Schedule standup" --priority high
 
 # Send agent-comms and wait for reply
-ogp federation agent alice queries "What's the status?" --wait --timeout 60000
+ogp federation agent apollo queries "What's the status?" --wait --timeout 60000
 
 # Send a task request
-ogp federation send alice task-request '{
+ogp federation send apollo task-request '{
   "taskType": "analysis",
   "description": "Analyze recent logs"
 }'
 
 # Send a status update
-ogp federation send alice status-update '{
+ogp federation send apollo status-update '{
   "status": "completed",
   "message": "Task finished"
 }'
@@ -399,6 +487,8 @@ ogp agent-comms activity stan --last 20
 
 ## How Federation Works
 
+### Single Framework Architecture
+
 ```
 ┌─────────────┐         ┌──────────────┐         ┌─────────────┐
 │  OpenClaw   │◄────────│  OGP Daemon  │◄────────│   Remote    │
@@ -407,26 +497,55 @@ ogp agent-comms activity stan --last 20
 └─────────────┘         └──────────────┘         └─────────────┘
 ```
 
+### Multi-Framework Architecture
+
+```
+┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
+│  OpenClaw   │◄────────│  OGP Daemon      │◄────────│   Remote    │
+│  :18789     │  webhook│  :18790          │  signed │   Peer      │
+└─────────────┘         │ (~/.ogp-openclaw)│  message│  (OGP)      │
+                        └──────────────────┘         └─────────────┘
+                               ▲
+┌─────────────┐                │
+│   Hermes    │◄────────┌──────────────────┐         ┌─────────────┐
+│  :18792     │  webhook│  OGP Daemon      │◄────────│   Remote    │
+└─────────────┘         │  :18793          │  signed │   Peer      │
+                        │ (~/.ogp-hermes)  │  message│  (OGP)      │
+                        └──────────────────┘         └─────────────┘
+                               ▲
+                               │
+                        ┌──────────────────┐
+                        │   Meta Config    │
+                        │ (~/.ogp-meta/)   │
+                        │ - Framework list │
+                        │ - Default        │
+                        │ - Aliases        │
+                        └──────────────────┘
+```
+
+### Federation Flow
+
 1. **Discovery**: Peers discover each other via `/.well-known/ogp` endpoint or rendezvous server
 2. **Request**: Alice requests federation with Bob's OGP instance
 3. **Approval**: Bob approves (or rejects) the federation request
 4. **Messaging**: Approved peers can send cryptographically signed messages
 5. **Verification**: Recipient OGP daemon verifies signatures using sender's public key
-6. **Relay**: Valid messages are forwarded to the local OpenClaw agent via webhook
+6. **Relay**: Valid messages are forwarded to the local AI agent via webhook
 
 All messages are signed with Ed25519 cryptographic signatures to prevent tampering and impersonation.
 
-## Rendezvous — Zero-Config Peer Discovery (v0.2.14+)
+## Rendezvous — Optional Discovery And Invite Layer (v0.2.14+)
+
+Rendezvous is an optional convenience layer for pubkey lookup and short invite codes. It is useful when you want easier onboarding for gateways that are already publicly reachable.
 
-OGP's rendezvous service eliminates the need for manual URL exchange and tunnel configuration. Gateways auto-register by public key, enabling peers to discover and connect to each other with a single command.
+### What It Actually Solves
 
-### The Problem It Solves
+Traditional federation still requires the peer you are trying to reach to be publicly reachable. Rendezvous helps with:
+- pubkey discovery
+- short invite codes instead of sharing long URLs or raw pubkeys
+- reducing manual coordination once each gateway already has a stable public endpoint
 
-Traditional federation requires both peers to be publicly reachable and manually exchange gateway URLs. With rendezvous:
-- No tunnel setup required (ngrok, Cloudflare Tunnel, port forwarding)
-- No manual URL sharing
-- No URL rotation issues (free ngrok tiers)
-- Automatic peer discovery by public key
+Rendezvous does **not** provide NAT traversal, hole punching, or message relay.
 
 ### How It Works
 
@@ -435,7 +554,7 @@ Traditional federation requires both peers to be publicly reachable and manually
 3. Peers can look you up by public key (`GET /peer/:pubkey`) and connect directly
 4. On shutdown, your daemon auto-deregisters (`DELETE /peer/:pubkey`)
 
-The rendezvous server **never touches message content** — it only stores connection hints (IP + port). All OGP messages remain end-to-end signed between peers.
+The rendezvous server **never touches message content** — it only stores connection hints. All OGP messages remain end-to-end signed between peers.
 
 ### Configuration
 
@@ -453,7 +572,7 @@ Add the `rendezvous` block to `~/.ogp/config.json`:
 }
 ```
 
-The setup wizard (`ogp setup`) prompts for rendezvous configuration.
+Rendezvous is optional. OGP works without it if peers can share public URLs directly.
 
 **For cloud/ECS gateways behind load balancers**, set the `OGP_PUBLIC_URL` environment variable to override automatic IP detection:
 
@@ -476,7 +595,7 @@ Or add `publicUrl` to the rendezvous config:
 
 ### Federation Invite Flow (v0.2.15+)
 
-The invite flow removes the need to exchange public keys. One command generates a short-lived token; your peer uses it to connect instantly.
+The invite flow removes the need to exchange public keys manually. One command generates a short-lived token; your peer uses it to connect instantly.
 
 **Generate an invite:**
 ```bash
@@ -512,7 +631,7 @@ Connect to any peer registered on rendezvous by their public key:
 ogp federation connect <pubkey>
 ```
 
-This looks up the peer on the rendezvous server and establishes federation directly.
+This looks up the peer on the rendezvous server and establishes federation directly. The peer still needs a reachable gateway endpoint behind that lookup.
 
 ### Privacy & Self-Hosting
 
@@ -617,25 +736,26 @@ ogp federation agent stan memory-management \
 
 ### 3. Project Intent System (v0.2.0+)
 
-Collaborative project management across federated peers with activity logging and cross-peer queries.
+Projects are optional collaboration boundaries layered on top of federation. They let each person keep their own tools while their agents log high-level project context and query collaborators through OGP when needed.
 
 **Features:**
 - Create projects with contextual setup (repo, workspace, notes, collaborators)
-- Log contributions by entry type (progress, decision, blocker, context)
-- Query local and peer contributions for unified team view
-- Agent-aware: proactive logging and context loading
-- **Auto-registration (v0.2.9+)**: Project IDs auto-register as agent-comms topics for all approved peers
+- Log high-level contributions by entry type (progress, decision, blocker, context)
+- Query local and peer contributions for project-aware coordination
+- Use project IDs as agent-comms topics for collaborator questions and summaries
+- **Auto-registration (v0.2.9+)**: Project IDs auto-register as agent-comms topics for approved peers who are explicit project members
 
 **Example:**
 ```bash
-# Create project (auto-registers as agent-comms topic for all peers)
+# Create project (auto-registers as agent-comms topic for approved project members)
 ogp project create my-app "My App" --description "Expense tracker"
 
 # Log work by entry type
 ogp project contribute my-app progress "Completed authentication"
 ogp project contribute my-app decision "Using PostgreSQL"
 
-# Query peer's project
+# Ask a collaborator or query peer project state
+ogp federation agent alice my-app "My user is about to work on auth. Anything already decided?"
 ogp project query-peer alice shared-app --limit 10
 ```
 
@@ -667,9 +787,26 @@ ogp federation request https://peer.example.com --alias alice
 ogp federation request https://peer.example.com
 ```
 
-### 6. Telegram Integration (v0.2.3+)
+### 6. OpenClaw Human Delivery (v0.2.3+, refined in v0.4.2+)
+
+For OpenClaw-backed agents, OGP now prefers `POST /hooks/agent` for inbound federated work that should be interpreted and surfaced by the local agent. This lets OpenClaw run a real agent turn, apply the configured human-delivery policy, and deliver through the correct channel surface (Telegram, iMessage, etc.).
 
-Federation requests fire OpenClaw notifications via sessions_send, delivering directly to Telegram.
+When OGP needs direct session injection, it uses Gateway RPC with the correct secure WebSocket transport (`wss://`) when the OpenClaw gateway is TLS-enabled.
+
+### 6.1 Delegated-Authority Precedence (v0.4.2)
+
+Policy evaluation now follows a fixed order so more specific rules cannot be silently overwritten. The runtime in `src/daemon/notify.ts` applies:
+1. Legacy `inboundFederationPolicy` mode as a safety fallback
+2. Global default rule from the delegated-authority config
+3. Peer-specific default rule (per-peer overrides)
+4. Global message-class rule (e.g., `agent-work`, `human-relay`, `approval-request`, `status-update`)
+5. Peer message-class override for that same class
+6. Global topic-level rule
+7. Peer topic-level override
+
+Approval requests receive immediate `approval-required` handling and `human-relay` obligations are treated according to their relay mode (deliver, summarize, or approval) before human delivery is asserted. This ordering guarantees peer defaults cannot erase more specific class/topic safeguards, so `human-relay` stays strict even when a trusted peer asks for more autonomy and topic overrides continue to behave predictably.
+
+OGP now tries to pin `/hooks/agent` to the actual human session key when the local OpenClaw `hooks.allowRequestSessionKey` setting allows it (see `~/.openclaw/openclaw.json`). If the value is `false` or the requested key does not match the allowed prefixes, the hook still runs but falls back to the default hook session, so downstream heuristics must still parse peer identity from the injected payload. Native sender identity parity in Telegram therefore remains a known limitation for `v0.4.2`; the runtime will log a warning whenever it cannot request a session override so that the human knows the limitation is intentional.
 
 ### 7. Enhanced Daemon Status (v0.2.3+)
 
@@ -689,10 +826,10 @@ ogp agent-comms configure --global --topics "general,project-updates" --level su
 
 ### 9. Project Topic Auto-Registration (v0.2.9+)
 
-When you create a project, its ID is automatically registered as an agent-comms topic for all approved peers at `summary` level. When you approve a new peer, all existing local projects are auto-registered as topics for that peer.
+When you create a project, its ID is automatically registered as an agent-comms topic at `summary` level for approved peers who are explicit project members. When you approve a new peer, existing local projects are auto-registered only if that peer is already in the project's member list.
 
 ```bash
-# Creates project AND registers as topic for all peers
+# Creates project AND registers as topic for approved project members
 ogp project create my-app "My Application"
 
 # Approving a peer also registers existing projects as topics
@@ -774,6 +911,9 @@ The `off` level enables a default-deny security posture. When a topic hits `off`
 # View all policies
 ogp agent-comms policies
 
+# Re-run the delegated-authority / human-delivery interview
+ogp agent-comms interview
+
 # View policies for a specific peer
 ogp agent-comms policies stan
 
@@ -828,6 +968,10 @@ Configuration is stored in `~/.ogp/config.json`:
   "email": "you@example.com",
   "stateDir": "~/.ogp",
   "agentId": "main",
+  "humanDeliveryTarget": "telegram:123456789",
+  "inboundFederationPolicy": {
+    "mode": "summarize"
+  },
   "notifyTarget": "telegram:123456789",
   "notifyTargets": {
     "main": "telegram:123456789",
@@ -863,6 +1007,55 @@ Which agent owns this gateway? (number or ID) [1]:
 You can also specify a custom agent ID if needed.
 ```
 
+### Human Delivery Preferences (v0.4.2+)
+
+OGP has two separate questions to answer for inbound federation traffic:
+
+1. **Where should human-facing followups go?**
+2. **How should the agent behave when a peer asks it to do something?**
+
+Those should not be inferred from the currently active conversation.
+
+**Configuration fields:**
+- **`humanDeliveryTarget`**: Explicit human-facing destination for OGP-triggered followups. Examples: `telegram:123456789` or a raw session key like `agent:main:telegram:direct:123456789`.
+- **`inboundFederationPolicy.mode`**: Default behavior for how the local agent should handle inbound federated requests.
+
+For OpenClaw specifically, this configuration feeds the `/hooks/agent` delivery path. In other words:
+- `humanDeliveryTarget` tells OGP where human-facing followups should go
+- `inboundFederationPolicy.mode` tells the local agent how to treat federated requests once they arrive
+- OGP should not infer either of those from "whatever session is active right now"
+
+**Supported behavior modes:**
+- **`forward`**: Tell me everything. Forward inbound federated items to my configured channel.
+- **`summarize`**: Summarize and surface only important, actionable, or uncertain items.
+- **`autonomous`**: Act autonomously when possible, but surface blockers, approvals, or explicit relay requests.
+- **`approval-required`**: Do not act on or reply to federated requests until I explicitly approve.
+
+**Example configuration:**
+
+```json
+{
+  "agentId": "main",
+  "humanDeliveryTarget": "telegram:123456789",
+  "inboundFederationPolicy": {
+    "mode": "autonomous"
+  }
+}
+```
+
+When you run `ogp setup`, the wizard asks for both:
+- the primary human delivery target for OGP followups
+- the default inbound federation handling mode
+
+If the user wants to revisit just this part later, use:
+
+```bash
+ogp --for openclaw agent-comms interview
+ogp --for hermes agent-comms interview
+```
+
+That command re-runs the delegated-authority / human-delivery interview for the active framework without repeating the rest of first-time setup.
+
 ### Notification Routing (v0.2.28+)
 
 The `notifyTargets` field enables per-agent notification routing. When OGP sends notifications to your OpenClaw instance, it routes to specific agents based on the message context.
@@ -870,6 +1063,7 @@ The `notifyTargets` field enables per-agent notification routing. When OGP sends
 **Configuration fields:**
 - **`notifyTarget`** (legacy, string): Single notification target for all messages. Maintained for backward compatibility.
 - **`notifyTargets`** (object): Map of agent names to notification targets. Example: `{"main": "telegram:...", "scribe": "telegram:..."}`
+- **`humanDeliveryTarget`** (preferred for human-facing followups): Explicit destination for OGP-triggered notifications and relay obligations.
 
 **Example configuration with multiple agents:**
 
@@ -883,6 +1077,10 @@ The `notifyTargets` field enables per-agent notification routing. When OGP sends
   "email": "alice@example.com",
   "stateDir": "~/.ogp",
   "notifyTarget": "telegram:123456789",
+  "humanDeliveryTarget": "telegram:123456789",
+  "inboundFederationPolicy": {
+    "mode": "summarize"
+  },
   "notifyTargets": {
     "main": "telegram:123456789",
     "scribe": "telegram:987654321",
@@ -896,15 +1094,25 @@ The `notifyTargets` field enables per-agent notification routing. When OGP sends
 
 When routing notifications, OGP resolves the target in this order:
 
-1. **`notifyTargets[agent]`** — If the agent is specified and exists in `notifyTargets`, use that target
-2. **`notifyTarget`** — Fall back to the legacy single target for backward compatibility
-3. **Default** — If neither is set, the notification is sent without a specific target (OpenClaw routes to the default channel)
+1. **`humanDeliveryTarget`** — If set, use it as the explicit human-facing OGP destination
+2. **`notifyTargets[agent]`** — If the agent is specified and exists in `notifyTargets`, use that target
+3. **`notifyTarget`** — Fall back to the legacy single target for backward compatibility
+4. **Default** — If none are set, OGP falls back to the agent's default session
 
 This allows you to:
 - Route federation messages to different agents based on context
+- Explicitly separate "the agent that owns this gateway" from "the human-facing channel for OGP followups"
 - Maintain backward compatibility with existing single-agent setups
 - Gradually migrate to multi-agent routing without breaking existing configurations
 
+### OpenClaw Transport Notes
+
+If you are debugging OpenClaw integration directly:
+
+- **Hooks path**: `https://localhost:18789/hooks/agent` is the preferred local delivery path for human-facing federated work.
+- **Gateway RPC path**: when using `openclaw gateway call` against a TLS-enabled local gateway, use `wss://localhost:18789`, not `ws://localhost:18789`.
+- A plain session injection succeeding does not necessarily mean the agent has interpreted the task the way you want; `/hooks/agent` is the path designed for that agentic behavior.
+
 ### Environment Variables
 
 - `OGP_PUBLIC_URL` (v0.2.17+): Override automatic IP detection for rendezvous registration. Use this for cloud/ECS gateways behind load balancers where the detected IP differs from the public endpoint.
@@ -918,12 +1126,21 @@ This allows you to:
 
 ### State Files
 
-- `~/.ogp/keypair.json` - Ed25519 keypair (keep secure! migrated to macOS Keychain on v0.2.13+)
+- `~/.ogp/keypair.json` - Public key cache plus key material metadata. On macOS the private key lives in an instance-specific Keychain entry; on non-macOS OGP encrypts the private key at rest when `OGP_KEYPAIR_SECRET`, `openclawToken`, or `hermesWebhookSecret` is available.
 - `~/.ogp/peers.json` - Federated peer list with scope grants
 - `~/.ogp/intents.json` - Intent registry (built-in + custom)
 - `~/.ogp/projects.json` - Project contexts and contributions
 - `~/.ogp/agent-comms-config.json` - Response policies and activity log
 
+On macOS, deleting `keypair.json` by itself does **not** rotate the gateway identity if the matching private key is still present in Keychain. Use `ogp setup --reset-keypair` when you intentionally want a new identity.
+
+On non-macOS, OGP prefers this secret source order for encrypting the private key at rest:
+- `OGP_KEYPAIR_SECRET`
+- `hermesWebhookSecret`
+- `openclawToken`
+
+If no encryption secret is available, OGP falls back to legacy plaintext key storage and logs a warning. Set one of the secrets above, then run `ogp setup --reset-keypair` to harden the instance.
+
 ## Skills (Claude Code)
 
 OGP includes skills for Claude Code agents. Install them with:
@@ -932,24 +1149,45 @@ OGP includes skills for Claude Code agents. Install them with:
 ogp-install-skills
 ```
 
+After upgrading, verify the installed skill headers:
+
+```bash
+rg -n '^version:' ~/.openclaw/skills/ogp*/SKILL.md ~/.claude/skills/ogp*/SKILL.md 2>/dev/null
+```
+
+Expected changed skill versions for the `0.4.2` release line:
+- `ogp` `2.6.0`
+- `ogp-agent-comms` `0.6.0`
+- `ogp-project` `2.2.0`
+
 ### Available Skills
 
 | Skill | Purpose |
 |-------|---------|
 | **ogp** | Core protocol: federation setup, peer management, sending messages |
 | **ogp-expose** | Tunnel setup: cloudflared/ngrok configuration |
-| **ogp-agent-comms** | Interactive wizard: configure response policies per-peer |
-| **ogp-project** | Agent-aware project context: interviews, logging, cross-peer summarization |
+| **ogp-agent-comms** | Interactive wizard: configure response policies plus delegated-authority / human-delivery interview |
+| **ogp-project** | Agent-aware project context: interviews, logging, and project-aware peer coordination |
 
-Skills auto-install from the `skills/` directory. The `ogp-agent-comms` skill provides an interactive wizard for multi-peer policy configuration. The `ogp-project` skill enables conversational project management with context interviews and proactive logging.
+Skills auto-install from the `skills/` directory. The `ogp-agent-comms` skill now uses `ogp agent-comms interview` as the canonical conversational path for delegated-authority / human-delivery configuration, plus the existing per-peer policy commands. The `ogp-project` skill enables conversational project management with context interviews, high-level project logging, and project-aware peer coordination.
 
 ## Documentation
 
-- [Quick Start Guide](./docs/quickstart.md) - Detailed step-by-step setup
+### Getting Started
+- [Getting Started Guide](./docs/GETTING-STARTED.md) - Comprehensive setup guide for single and multi-framework setups
+- [Quick Start Guide](./docs/quickstart.md) - Fast-track setup for single framework
+- [CLI Reference](./docs/CLI-REFERENCE.md) - Complete command reference with examples
+- [Migration Guide](./docs/MIGRATION.md) - Upgrading from single to multi-framework setup
+
+### Core Features
 - [Federation Flow](./docs/federation-flow.md) - How federation works internally
 - [Scope Negotiation](./docs/scopes.md) - Per-peer scope configuration (v0.2.0)
 - [Agent Communications](./docs/agent-comms.md) - Agent-to-agent messaging (v0.2.0)
-- [Rendezvous & Invite Flow](./docs/rendezvous.md) - Zero-config peer discovery (v0.2.14+)
+- [Rendezvous & Invite Flow](./docs/rendezvous.md) - Optional discovery and invite service (v0.2.14+)
+
+### Advanced
+- [Multi-Framework Design](./docs/MULTI-FRAMEWORK-DESIGN.md) - Design principles for multi-framework support
+- [Multi-Framework Implementation](./docs/MULTI-FRAMEWORK-IMPL.md) - Implementation details
 - [Protocol Specification](https://github.com/dp-pcs/openclaw-federation) - Full OGP protocol spec
 
 ## Security
@@ -961,7 +1199,9 @@ Skills auto-install from the `skills/` directory. The `ogp-agent-comms` skill pr
 - **Nonce tracking**: Prevents replay attacks
 
 **Best practices:**
-- Keep `~/.ogp/keypair.json` secure with proper file permissions (`chmod 600`)
+- Treat `~/.ogp/keypair.json` as identity material even when it contains only the public key cache on macOS.
+- On macOS, remember the private key source of truth is the instance-specific Keychain entry, not `keypair.json`; use `ogp setup --reset-keypair` for intentional rotation.
+- On non-macOS, provide `OGP_KEYPAIR_SECRET` or a platform secret so OGP can encrypt the private key at rest; `chmod 600` remains enforced but is not sufficient by itself.
 - Verify peer identity out-of-band before approving federation requests
 - Always use HTTPS tunnels (never expose raw HTTP)
 - Monitor OpenClaw logs for suspicious peer activity
@@ -994,7 +1234,7 @@ src/
     projects.ts       # Project storage and management (v0.2.0+)
     intent-registry.ts # Intent definitions and custom registry
     message-handler.ts # Message verification and routing
-    notify.ts         # OpenClaw integration (sessions_send + webhooks)
+    notify.ts         # OpenClaw/Hermes delivery backends
   cli/
     setup.ts          # Setup wizard
     federation.ts     # Federation commands (scopes, agent-comms)
@@ -1011,6 +1251,22 @@ skills/
   ogp-project/      # Project context management skill
 ```
 
+## Known Issues
+
+### OpenClaw Delivery Model
+
+**Current implementation:**
+- **Primary:** `POST /hooks/agent` for inbound federated requests that should be processed by the local OpenClaw agent
+- **Fallback / sync:** `openclaw gateway call ... sessions.send` over `wss://` when direct session injection is needed
+
+Why this split exists:
+- `/hooks/agent` is the right primitive for "an external federated task arrived; let the agent interpret it, act on it, and deliver the result through the configured human channel."
+- `sessions.send` is still useful for direct session injection and compact synchronization notes, but it is not the primary delivery mechanism for human-facing federated work.
+
+Important nuance:
+- OpenClaw may still render direct session injections with sender metadata like `cli`, so OGP continues to include peer identity in message content where needed.
+- Hook-run awareness and human-DM continuity are related but not identical. OGP can mirror a compact sync note into the DM session, but the important success criterion is correct delivery and behavior, not whether raw internal transport artifacts are visible in the user-facing transcript.
+
 ## License
 
 MIT