@dp-pcs/ogp 0.4.2 → 0.4.3

package/skills/ogp-expose/SKILL.md

@@ -1,6 +1,6 @@
 ---
 skill_name: ogp-expose
-version: 0.3.0
+version: 0.4.0
 description: Expose OGP via a public HTTPS endpoint, usually a stable Cloudflare hostname or named tunnel. Use when the user wants to verify or fix gateway reachability, align `gatewayUrl` with the real public endpoint, or set up temporary cloudflared/ngrok exposure for testing.
 trigger: Use when the user wants to expose their OGP daemon to the internet, get a public URL for federation, or set up a tunnel for peer discovery.
 requires:
@@ -74,6 +74,101 @@ ogp --for hermes status
 
 Use `--for <framework>` on all exposure and verification commands when the target is not obvious.
 
+## Guided Wizard
+
+Follow this decision order every time:
+
+1. **Cloudflare named tunnel + stable hostname** if the user has a domain on Cloudflare or wants a durable production URL.
+2. **ngrok** if they need a stable-enough ad hoc URL and already have ngrok/auth configured.
+3. **Temporary Cloudflare quick tunnel** only for fast testing when the URL can change on restart.
+
+Ask or determine these three facts first:
+
+1. Which framework is being exposed (`openclaw`, `hermes`, or another configured framework)?
+2. Does the user want a **stable long-lived URL** or just a **temporary test URL**?
+3. Do they already have **Cloudflare DNS/domain control** or **ngrok auth** available?
+
+Then route them through exactly one branch below instead of mixing options.
+
+## Branch 1: Stable Cloudflare Named Tunnel
+
+Choose this when the user wants the recommended path.
+
+Checklist:
+
+1. Confirm the framework and its daemon port.
+2. Choose the canonical hostname that should become `gatewayUrl`.
+3. Create or verify the named tunnel.
+4. Route DNS to the tunnel.
+5. Point ingress at the correct local daemon port.
+6. Set `gatewayUrl` to the same public hostname.
+7. Verify local card, public card, and config all agree.
+
+Primary repo doc:
+
+- `docs/cloudflare-named-tunnel-setup.md`
+
+Use that doc as the copy-paste path instead of rewriting the steps from scratch.
+
+Success criteria:
+
+- The public `/.well-known/ogp` card loads.
+- Its `gatewayUrl` matches the intended hostname.
+- Its public key matches the local daemon card.
+
+## Branch 2: ngrok
+
+Choose this when the user wants something faster than named Cloudflare but more intentional than a throwaway quick tunnel.
+
+Checklist:
+
+1. Confirm ngrok is installed and authenticated.
+2. Start the tunnel against the correct local daemon port.
+3. Capture the HTTPS URL.
+4. Update `gatewayUrl` to that URL only if it is the intended endpoint for current federation.
+5. Verify the public `/.well-known/ogp` card.
+
+Use this command path:
+
+```bash
+ogp --for openclaw expose --method ngrok
+```
+
+## Branch 3: Temporary Cloudflare Quick Tunnel
+
+Choose this only for short-lived testing.
+
+Checklist:
+
+1. Start the quick tunnel on the correct daemon port.
+2. Copy the temporary HTTPS URL.
+3. Warn that it changes on restart.
+4. Update `gatewayUrl` only if the user is intentionally federating against this temporary URL.
+5. Verify the public `/.well-known/ogp` card before testing federation.
+
+Use this command path:
+
+```bash
+ogp --for openclaw expose
+```
+
+## Verification Flow
+
+Always end with this verification sequence:
+
+```bash
+curl -s http://127.0.0.1:<daemon-port>/.well-known/ogp
+curl -s https://your-public-hostname/.well-known/ogp
+```
+
+Confirm:
+
+1. Public key matches local.
+2. Public `gatewayUrl` matches config `gatewayUrl`.
+3. The framework/port behind the hostname is the one the user intended.
+
+If any of those disagree, do not treat the gateway as ready for federation.
+
 ## Recommended Production Baseline
 
 Prefer one stable HTTPS hostname per framework:
@@ -133,9 +228,9 @@ Sign up at https://ngrok.com and get your auth token:
 ngrok config add-authtoken <your-token>
 ```
 
-## Usage
+## Command Reference
 
-### Expose with Cloudflared (Temporary / Ad Hoc)
+### Temporary Cloudflare Quick Tunnel
 
 ```bash
 ogp --for openclaw expose
@@ -152,7 +247,7 @@ This will:
 # Set "gatewayUrl" to the URL shown by cloudflared only if this temporary URL is the intended canonical endpoint
 ```
 
-### Expose with ngrok (Fallback Only)
+### ngrok Tunnel
 
 ```bash
 ogp --for openclaw expose --method ngrok
@@ -169,9 +264,9 @@ This will:
 # Set "gatewayUrl" to the ngrok URL
 ```
 
-## Complete Setup Workflow
+## Worked Flows
 
-### First-time or Temporary Setup
+### Temporary Exposure Flow
 
 1. **Run OGP setup:**
    ```bash
@@ -209,7 +304,7 @@ This will:
    curl https://your-tunnel-url/.well-known/ogp
    ```
 
-### Permanent Setup with Cloudflared Named Tunnel
+### Stable Named Tunnel Flow
 
 For production use, create a permanent cloudflared tunnel:
 
@@ -253,7 +348,7 @@ Then make sure each framework config uses its own canonical hostname:
 }
 ```
 
-## Comparison: Cloudflared vs ngrok
+## Selection Notes
 
 ### Cloudflared / Stable Hostname
 **Pros:**

package/skills/ogp-project/SKILL.md

@@ -1,21 +1,22 @@
 ---
 skill_name: ogp-project
-version: 2.1.0
+version: 2.2.0
 description: >
   Tool-agnostic project collaboration for AI assistants. Users keep their own tools
   (Linear, Jira, Obsidian, GitHub, iCloud, local files — anything). This skill makes
   agents aware of what each collaborator's agent knows and where it lives, so agents
-  can query each other proactively rather than making the human relay information.
-  Supports project creation with context interviews, freeform activity logging,
-  proactive pre-task peer checks, and cross-peer summarization.
+  can query each other through OGP project boundaries rather than making the human
+  relay information. Supports project creation with context interviews, freeform
+  activity logging, project-topic agent-comms, and cross-peer queries.
 trigger: >
   Use when the user wants to create, manage, log to, or summarize OGP projects.
-  ALSO use proactively — before starting any project-related work — to check shared
-  project state and query peer agents. Triggers on natural logging phrases like
+  ALSO use proactively when project context is clearly relevant — check local project
+  state first and query peer agents when that would reduce human relay or duplicate
+  work. Triggers on natural logging phrases like
   "remember this for project X", "account for this", "make note of", "track this",
   "jot this down", "save this to", "document this" when a project context is active or named.
-  The goal is to eliminate human-as-messenger friction: agents surface conflicts and
-  overlaps automatically so users don't have to ask.
+  The goal is to reduce human-as-messenger friction while preserving federation and
+  project boundaries.
 requires:
   bins:
     - ogp
@@ -56,22 +57,30 @@ Full documentation: https://github.com/dp-pcs/ogp
 
 ## The Core Idea
 
-People work differently. One person tracks tasks in Linear, keeps notes in GitHub, stores files locally. Another uses a different issue tracker, writes in Obsidian, stores files in iCloud. In the past, collaboration meant forcing everyone onto the same tools.
+Federation is the base relationship in OGP. A project is an optional collaboration boundary layered on top of that federation.
 
-**This skill changes that.** Each user keeps their own tools and workflow. Their agent knows what they're working on and where everything lives. When two people collaborate on a project, their agents communicate directly — surfacing conflicts, sharing context, and answering each other's questions — without the human having to relay anything.
+People work differently. One person tracks tasks in Linear, keeps notes in GitHub, stores files locally. Another uses a different issue tracker, writes in Obsidian, stores files in iCloud. The project model is meant to let both people keep those tools while their agents exchange high-level project context through OGP.
+
+The important distinction is that a project is **not** "everyone must use the same repo" and **not** "share everything verbatim." It is a bounded context for collaboration:
+
+- log high-level facts such as decisions, progress, blockers, questions, and important context
+- let agents ask each other about that context over federation
+- preserve visibility boundaries when project membership is broader than pairwise federation
+
+That means a project can include multiple collaborators even when they are not all federated with each other. OGP should help each side coordinate through their own agent and tools, not force a full mesh of shared systems.
 
 The human-as-messenger problem:
 > Coworker wants to know something → asks you → you ask your agent → agent finds answer → you tell coworker
 
-What this skill enables:
-> Coworker's agent asks your agent → answer flows back → coworker just knows
+What this skill is aiming for:
+> Coworker's agent asks your agent about project context → answer flows back with the right policy and boundaries
 
 ---
 
 ## When to Use
 
 - User wants to create a new OGP project with contextual setup
-- **User is about to start work on something project-related** → check shared state first (see Proactive Pre-Task Check below)
+- User is about to start work on something project-related and it is worth checking local or peer project context first
 - User expresses logging intent: "add this to project X", "log that", "remember this", "track this", etc.
 - User asks about project status, activity, or what a collaborator has been working on
 - A peer agent sends a query about something in your project context
@@ -87,30 +96,35 @@ What this skill enables:
 
 ### 2. Freeform Activity Logging
 - Monitors for logging intent (any natural phrasing)
-- Logs decisions, progress, blockers, context — all queryable later
-- Auto-registers project ID as agent-comms topic for all approved peers
+- Logs high-level decisions, progress, blockers, questions, and context — all queryable later
+- Auto-registers project ID as agent-comms topic for approved peers who are explicit project members
 
-### 3. Proactive Pre-Task Check ← KEY BEHAVIOR
-- Before starting project-related work, automatically check local state AND ping peer agents
-- Surfaces "heads up — your collaborator is already working on that" moments
-- Eliminates duplicate work and uncovers conflicts early
+### 3. Project-Aware Coordination Workflow
+- Before starting project-related work, the agent should consider checking local state first
+- If the question or task depends on collaborator context, query the relevant peer agent on the project topic
+- Surface "heads up — your collaborator already logged something relevant" moments when they are actually found
 
 ### 4. Peer Response Policy Awareness
 - Peer agents have their own response policies (auto-answer vs. escalate to human)
 - Your agent respects those policies and adjusts behavior accordingly
 - This preserves each user's autonomy over how their agent handles interruptions
 
-### 5. Cross-Peer Summarization
-- Unified view of contributions across local + all peer agents
-- Deduplication and synthesis
+### 5. Cross-Peer Querying
+- Query peer project state when that context would help answer a question or avoid duplicate work
+- Summarize the relevant result for the user instead of dumping raw logs by default
+
+### 6. Current Implementation Boundary
+- The CLI and daemon currently provide project CRUD, contribution logging, peer project queries, and project-topic agent-comms
+- The "check peers before starting work" behavior is a workflow expectation for the agent using this skill, not a daemon-enforced guarantee
+- Multi-party project visibility rules are still evolving; do not assume that project membership automatically implies transitive sharing between peers
 
 ---
 
-## Proactive Pre-Task Check (MANDATORY)
+## Suggested Pre-Task Check
 
-**This is the most important behavior in this skill.**
+Use this flow when project context is likely to matter. Treat it as recommended agent behavior, not as a guaranteed runtime mechanism.
 
-Whenever the user expresses intent to start work on something project-related, run this flow BEFORE starting:
+Whenever the user expresses intent to start work on something project-related, consider this flow before starting:
 
 ### Step 1: Check local project state
 ```bash
@@ -121,9 +135,9 @@ ogp --for openclaw project query <project-id> --limit 20
 ogp --for openclaw project query <project-id> --search "<keywords from user's intent>"
 ```
 
-### Step 2: Query peer agents
+### Step 2: Query relevant peer agents
 ```bash
-# For each approved peer in the project, ask if they know anything relevant
+# Ask the specific collaborator whose context is likely to matter
 ogp --for openclaw federation agent <peer-id> <project-id> "My user is about to start working on <what they said>. Anything I should know before we begin?"
 ```
 
@@ -260,7 +274,7 @@ Ask these questions conversationally — not as a form. Let the user's answers l
 *(peer IDs, names, or email addresses of collaborators)*
 
 - If answered → `ogp --for openclaw project contribute <id> context.collaborators "<names/peer-ids>"`
-- Agent behavior unlocked: Know who to ping during pre-task checks. Know whose agent to query when looking for context.
+- Agent behavior unlocked: Know who to ping during pre-task checks and whose agent to query when looking for context.
 - Also offer: *"Want me to send them a federation invite?"* — if yes, run `ogp --for openclaw project request-join <peer-id> <project-id> <name>`
 - If skipped → no peer checks until collaborators are added later
 
@@ -289,7 +303,7 @@ After the interview, summarize what you now know:
   👥 Collaborators: <answer or "none yet">
 
 For anything I don't know yet, you can tell me later and I'll update the project context.
-I'll check this context before starting any work on this project.
+I'll use this context when project questions come up and can check it before starting related work.
 ```
 
 > **Why this matters:** The `context.*` entries do two jobs. They tell peer agents where your stuff lives (so they know what to ask you about). And they tell YOUR agent where to actually look when answering questions — not just what's been logged to `projects.json`.
@@ -487,11 +501,11 @@ ogp --for openclaw federation send <peer-id> message '{"text":"ping"}'
 **Data Flow:**
 ```
 User says something project-related
-  → Agent checks local project state (ogp --for <framework> project query)
-  → Agent pings peer agents (ogp --for <framework> federation agent)
-  → Surfaces conflicts/info before starting
+  → Agent may check local project state (ogp --for <framework> project query)
+  → Agent may ping relevant peer agents (ogp --for <framework> federation agent)
+  → Surfaces relevant conflicts/info before or during work
   → Logs outcomes (ogp --for <framework> project contribute)
-  → Federation syncs to peers
+  → Shares or queries peer context through project-aware federation flows when appropriate
 ```
 
 **The tool-agnostic principle:**