@dp-pcs/ogp 0.7.0-rc.1 → 0.7.1

package/docs/RC1-FEDERATION-TEST-CHECKLIST.md

@@ -0,0 +1,477 @@
+# OGP RC.1 Federation Test Checklist
+
+This is the real-world validation plan for `@dp-pcs/ogp@0.7.0-rc.1` across three gateways:
+
+- `OpenClaw` on `https://ogp.sarcastek.com`
+- `Hermes` on `https://hermes.sarcastek.com`
+- `Cosmo` on the AWS machine as the hub
+- `Aleph` on `https://ogp-aleph.aicoe.fit` operated by Stephen Barr
+
+The goal is not just "can they federate once?" The goal is to prove the full `rc.1` surface area behaves correctly under normal operation, restart/recovery, and obvious failure modes.
+
+## Success Criteria
+
+`rc.1` is in decent shape if all of these are true:
+
+- all three gateways answer `/.well-known/ogp` and `/federation/ping`
+- all three pairings can request, approve, exchange traffic, and remove cleanly
+- peer health transitions make sense when a daemon goes down and comes back
+- scoped access is enforced
+- agent-comms works, including reply-wait paths
+- project-intent flows work across real gateways, not just the local harness
+- multi-agent/persona routing works where advertised
+- rendezvous/invite flow works if you intend to rely on it
+- restart behavior is acceptable, including daemon and tunnel recovery
+
+## Participants
+
+Set these once in your shell while testing:
+
+```bash
+export OC_URL="https://ogp.sarcastek.com"
+export HERMES_URL="https://hermes.sarcastek.com"
+export COSMO_URL="https://david-proctor.gw.clawporate.elelem.expert"
+export ALEPH_URL="https://ogp-aleph.aicoe.fit"
+```
+
+Useful topology:
+
+| Pair | Why it matters |
+| --- | --- |
+| OpenClaw <-> Hermes | Cross-framework, same operator, easiest first smoke |
+| OpenClaw <-> Cosmo | David local gateway to AWS hub |
+| Hermes <-> Cosmo | David second local gateway to AWS hub |
+| Aleph <-> Cosmo | Stephen gateway to AWS hub |
+
+Primary `rc.1` goal for this round:
+
+- prove both David and Stephen can federate with Cosmo cleanly
+- prove Cosmo stays healthy as the shared external hub
+- prove project-intent and agent-comms traffic survives the hub topology
+
+Direct `OpenClaw/Hermes <-> Aleph` federation is optional for this round unless you specifically want a full mesh test.
+
+## 0. Preflight On Every Machine
+
+Run this before any pairwise testing:
+
+```bash
+ogp --version
+ogp --for all status
+ogp whoami
+ogp config health-check show
+curl -sS "$OC_URL/.well-known/ogp" | jq .
+curl -sS "$HERMES_URL/.well-known/ogp" | jq .
+curl -sS "$COSMO_URL/.well-known/ogp" | jq .
+curl -sS "$ALEPH_URL/.well-known/ogp" | jq .
+```
+
+Check:
+
+- version is `0.7.0-rc.1` everywhere
+- each daemon is actually listening on its configured port
+- each public URL matches the gateway's configured `gatewayUrl`
+- each gateway advertises `multi-agent-personas` in `capabilities.features`
+- each gateway advertises the expected `agents[]`
+
+### Optional: speed up health-check testing
+
+For testing, lower the heartbeat interval so you do not wait forever for state changes:
+
+```bash
+ogp config health-check interval 30000
+ogp config health-check timeout 5000
+ogp config health-check max-failures 2
+ogp stop --for all
+ogp start --for all --background
+```
+
+Expected result:
+
+- health config shows `30s / 5s / 2 failures`
+- after restart, `ogp --for all status` shows both daemons up
+
+## 1. Local Harness First
+
+Before you spend time on the three-machine test, run the existing local project-intent harness in this repo:
+
+```bash
+npm run build
+npm test -- --run
+npm run test:project-intents
+```
+
+Optional stateful run:
+
+```bash
+npm run test:project-intents -- --keep-state
+```
+
+This catches obvious regressions in:
+
+- federation request / approve
+- project create / join / contribute / query / status-peer
+- local state persistence
+
+## 2. Discovery And Liveness
+
+Run these against every public gateway:
+
+```bash
+ogp federation ping "$OC_URL"
+ogp federation ping "$HERMES_URL"
+ogp federation ping "$COSMO_URL"
+ogp federation ping "$ALEPH_URL"
+
+curl -sS "$OC_URL/.well-known/ogp" | jq '{version,displayName,gatewayUrl,features:.capabilities.features,agents}'
+curl -sS "$HERMES_URL/.well-known/ogp" | jq '{version,displayName,gatewayUrl,features:.capabilities.features,agents}'
+curl -sS "$COSMO_URL/.well-known/ogp" | jq '{version,displayName,gatewayUrl,features:.capabilities.features,agents}'
+curl -sS "$ALEPH_URL/.well-known/ogp" | jq '{version,displayName,gatewayUrl,features:.capabilities.features,agents}'
+```
+
+Expected result:
+
+- ping succeeds for all three URLs
+- each card shows `version: 0.7.0-rc.1`
+- `gatewayUrl` in the card matches the public URL you hit
+- `agents[]` looks correct for that gateway
+
+## 3. Federation Lifecycle
+
+Run this for each required hub/spoke pair.
+
+Example commands from OpenClaw -> Hermes:
+
+```bash
+ogp --for openclaw federation request "$HERMES_URL" --alias hermes-local
+ogp --for hermes federation list --status pending
+ogp --for hermes federation approve hermes-local --intents message,agent-comms,project.join,project.contribute,project.query,project.status
+ogp --for openclaw federation list
+ogp --for hermes federation list
+ogp --for openclaw federation status
+ogp --for hermes federation status
+```
+
+Repeat the same flow for:
+
+- OpenClaw -> Cosmo
+- Hermes -> Cosmo
+- Aleph -> Cosmo
+
+Expected result:
+
+- requester sees the peer move to `approved`
+- approver sees the requester move to `approved`
+- status output shows the correct alias and gateway
+- no peer lands in a weird half-approved state
+
+## 4. Health Checks And Heartbeat State
+
+After all pairs are approved, inspect the health view:
+
+```bash
+ogp --for openclaw federation status
+ogp --for hermes federation status
+```
+
+Look for:
+
+- `healthy` peers
+- a sensible `healthState` such as `established`
+- recent inbound and outbound timestamps
+
+### Failure and recovery test
+
+For one pair at a time, stop one side and watch the other side detect it:
+
+```bash
+ogp --for hermes stop
+ogp --for openclaw federation status
+sleep 70
+ogp --for openclaw federation status
+ogp --for hermes start --background
+sleep 70
+ogp --for openclaw federation status
+ogp --for hermes federation status
+```
+
+Expected result:
+
+- after enough failed heartbeats, the surviving peer marks the stopped peer degraded or down
+- after restart, health recovers back to `established`
+- `/.well-known/ogp` becomes reachable again after restart
+
+Run the same stop/restart test with Cosmo, because that is the critical shared dependency.
+
+## 5. Identity And Persona Advertisement
+
+Check that each peer advertises the expected identity and agents:
+
+```bash
+curl -sS "$OC_URL/.well-known/ogp" | jq '.agents'
+curl -sS "$HERMES_URL/.well-known/ogp" | jq '.agents'
+curl -sS "$COSMO_URL/.well-known/ogp" | jq '.agents'
+curl -sS "$ALEPH_URL/.well-known/ogp" | jq '.agents'
+```
+
+Then change local identity on one gateway and push it to an approved peer:
+
+```bash
+ogp config show-identity
+ogp federation update-identity <peer-id>
+ogp federation status
+```
+
+Expected result:
+
+- approved peers see the updated identity snapshot
+- no federation relationship breaks just because identity fields changed
+
+## 6. Basic Message Traffic
+
+Test raw message intent first:
+
+```bash
+ogp federation send <peer-id> message '{"text":"hello from rc1"}'
+ogp federation send <peer-id> task-request '{"task":"echo test","priority":"normal"}'
+ogp federation send <peer-id> status-update '{"status":"completed","source":"rc1-manual-test"}'
+```
+
+Expected result:
+
+- receiver gets the message
+- sender gets a successful transport result
+- daemon log records the request cleanly
+
+## 7. Agent-Comms
+
+First inspect policies:
+
+```bash
+ogp agent-comms policies
+ogp agent-comms activity --last 20
+```
+
+Then test real agent-comms:
+
+```bash
+ogp federation agent <peer-id> memory-management "Store this test marker"
+ogp federation agent <peer-id> queries "What gateway are you on?" --wait --timeout 60000
+ogp federation agent <peer-id> task-delegation "Return a short ack" --priority high --wait --timeout 60000
+```
+
+Expected result:
+
+- fire-and-forget delivery succeeds
+- `--wait` returns a real reply path, not just transport success
+- activity log records the interaction
+
+### Persona routing
+
+If the peer advertises more than one agent:
+
+```bash
+ogp federation agent <peer-id> queries "hello primary" --to-agent junior --wait
+ogp federation agent <peer-id> queries "hello specialist" --to-agent apollo --wait
+```
+
+Negative test:
+
+```bash
+ogp federation agent <peer-id> queries "bad persona test" --to-agent definitely-not-real --wait
+```
+
+Expected result:
+
+- valid persona IDs route successfully
+- invalid persona ID fails with a clear error
+
+## 8. Scope Enforcement
+
+Approve or grant a peer with restricted scopes, then verify allowed vs denied behavior.
+
+Example:
+
+```bash
+ogp federation grant <peer-id> --intents message --rate 20/3600
+ogp federation scopes <peer-id>
+```
+
+Now try:
+
+```bash
+ogp federation send <peer-id> message '{"text":"allowed"}'
+ogp federation agent <peer-id> memory-management "should be denied"
+ogp project query-peer <peer-id> some-project
+```
+
+Expected result:
+
+- `message` works
+- `agent-comms` fails if not granted
+- project intents fail if project scopes are not granted
+
+Then restore the broader scope set and verify those flows work again.
+
+## 9. Project Intents
+
+This is the highest-value cross-machine test after basic federation.
+
+Recommended topology for this round:
+
+- create the canonical shared project on `Cosmo`
+- have `OpenClaw`, `Hermes`, and `Aleph` join it
+- send contributions from each spoke into Cosmo
+- verify that queries against Cosmo reflect the combined state
+
+On the owner gateway:
+
+```bash
+ogp project create rc1-shared "RC1 Shared Test" --description "Real multi-gateway test"
+ogp project contribute rc1-shared note "owner bootstrap note" --local-only
+ogp project status rc1-shared
+```
+
+From a remote approved peer:
+
+```bash
+ogp project request-join <owner-peer-id> rc1-shared "RC1 Shared Test" --description "Join from remote gateway"
+ogp project query-peer <owner-peer-id> rc1-shared
+ogp project send-contribution <owner-peer-id> rc1-shared task "Remote task from rc1 test"
+ogp project send-contribution <owner-peer-id> rc1-shared decision "Remote decision from rc1 test" --metadata '{"confidence":"high"}'
+ogp project status-peer <owner-peer-id> rc1-shared
+```
+
+Run this with both remote peers joining the same project.
+
+Expected result:
+
+- pre-join query should fail or be denied
+- join succeeds and the project membership becomes visible
+- remote contributions show up on the owner gateway
+- query after join returns the new entries
+- status-peer succeeds at least at the transport level
+
+Evidence:
+
+- `ogp project status rc1-shared`
+- `~/.ogp/projects.json`
+- `~/.ogp-hermes/projects.json`
+- Cosmo's `projects.json`
+- Aleph's `projects.json`
+
+## 10. Rendezvous / Invite Flow
+
+Only run this if you intend to use rendezvous in production.
+
+From one gateway:
+
+```bash
+ogp federation invite
+```
+
+From another:
+
+```bash
+ogp federation accept <token>
+```
+
+Also test connect-by-pubkey:
+
+```bash
+ogp federation connect <pubkey>
+```
+
+Expected result:
+
+- invite token resolves and creates the same approved peer state you get from direct request/approve
+- connect-by-pubkey finds the peer and completes federation
+- rendezvous registration stays alive while the daemon is up
+
+## 11. Removal And Re-Federation
+
+For each pair:
+
+```bash
+ogp federation remove <peer-id>
+ogp federation list
+```
+
+Expected result:
+
+- removed peer is marked removed locally
+- remote side receives the removal notification on a best-effort basis
+- sending further traffic to the removed peer fails
+
+Then immediately re-request federation and make sure the pair can recover cleanly.
+
+## 12. Restart, Reboot, And Tunnel Recovery
+
+These are operational tests, not protocol tests, but they matter.
+
+### Daemon restart
+
+```bash
+ogp --for all stop
+ogp --for all start --background
+ogp --for all status
+```
+
+### Public endpoint recovery
+
+```bash
+curl -sS "$OC_URL/.well-known/ogp" | jq .version
+curl -sS "$HERMES_URL/.well-known/ogp" | jq .version
+curl -sS "$COSMO_URL/.well-known/ogp" | jq .version
+curl -sS "$ALEPH_URL/.well-known/ogp" | jq .version
+```
+
+### Tunnel validation
+
+Verify each public URL continues to map to the correct local daemon after restart.
+
+## 13. Known Local Risk To Explicitly Test
+
+On David's macOS machine, the current LaunchAgent can fail if launchd cannot find `node` for the `ogp` wrapper. That is worth an explicit reboot/login test because it will absolutely look like "tunnel is up but OGP is dead."
+
+Check:
+
+```bash
+launchctl print gui/$(id -u)/com.dp-pcs.ogp
+sed -n '1,80p' ~/.ogp/launchagent.log
+```
+
+If this still shows `env: node: No such file or directory`, autostart is not trustworthy yet.
+
+## 14. Evidence To Save Per Test Run
+
+For each major run, save:
+
+```bash
+ogp --for all status
+ogp --for openclaw federation list
+ogp --for hermes federation list
+ogp agent-comms activity --last 50
+curl -sS "$OC_URL/.well-known/ogp" | jq .
+curl -sS "$HERMES_URL/.well-known/ogp" | jq .
+curl -sS "$COSMO_URL/.well-known/ogp" | jq .
+curl -sS "$ALEPH_URL/.well-known/ogp" | jq .
+```
+
+Also keep:
+
+- `~/.ogp/daemon.log`
+- `~/.ogp-hermes/daemon.log`
+- each gateway's `peers.json`
+- each gateway's `projects.json`
+
+## Minimal Ship Gate
+
+If you do not have time to run everything, the minimum bar before treating `rc.1` as real is:
+
+1. all four public cards return `200`
+2. `OpenClaw <-> Cosmo`, `Hermes <-> Cosmo`, and `Aleph <-> Cosmo` can federate
+3. health changes on Cosmo stop/start are visible and recover from the spoke gateways
+4. one successful `agent-comms --wait` round-trip from each spoke to Cosmo
+5. one successful project join + contribution + query flow with Cosmo as the shared project owner
+6. one successful removal + re-federation cycle against Cosmo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-pcs/ogp",
-  "version": "0.7.0-rc.1",
+  "version": "0.7.1",
   "description": "Open Gateway Protocol (OGP) - Peer-to-peer federation daemon for OpenClaw AI gateways with cryptographic signatures",
   "type": "module",
   "main": "./dist/index.js",

package/scripts/completion.zsh

@@ -3,12 +3,78 @@
 # OGP zsh completion script
 # Auto-generated by ogp completion install
 
+_ogp_command_word() {
+  local i=2
+
+  while (( i <= $#words )); do
+    case "${words[i]}" in
+      --for)
+        (( i += 2 ))
+        continue
+        ;;
+      --for=*)
+        (( i += 1 ))
+        continue
+        ;;
+      -h|--help|-v|--version)
+        (( i += 1 ))
+        continue
+        ;;
+      -*)
+        (( i += 1 ))
+        continue
+        ;;
+      *)
+        print -r -- "${words[i]}"
+        return 0
+        ;;
+    esac
+  done
+
+  return 1
+}
+
+_ogp_subcommand_word() {
+  local parent="$1"
+  local seen_parent=0
+  local i=2
+
+  while (( i <= $#words )); do
+    case "${words[i]}" in
+      --for)
+        (( i += 2 ))
+        continue
+        ;;
+      --for=*)
+        (( i += 1 ))
+        continue
+        ;;
+      -*)
+        (( i += 1 ))
+        continue
+        ;;
+    esac
+
+    if (( seen_parent == 0 )); then
+      if [[ "${words[i]}" == "$parent" ]]; then
+        seen_parent=1
+      fi
+      (( i += 1 ))
+      continue
+    fi
+
+    print -r -- "${words[i]}"
+    return 0
+  done
+
+  return 1
+}
+
 _ogp() {
-  local -a frameworks peers
+  local -a frameworks
   local curcontext="$curcontext" state line
   typeset -A opt_args
 
-  # Get frameworks for --for flag
   frameworks=(${(f)"$(ogp config list --quiet 2>/dev/null)"} all)
 
   _arguments -C \
@@ -40,7 +106,7 @@ _ogp() {
       ))'
       ;;
     args)
-      case ${words[1]} in
+      case "$(_ogp_command_word)" in
         federation)
           _ogp_federation
           ;;
@@ -69,41 +135,44 @@ _ogp() {
 
 _ogp_federation() {
   local curcontext="$curcontext" state line
+  local subcmd="$(_ogp_subcommand_word federation)"
   typeset -A opt_args
 
-  _arguments '1:subcommand:((
-    list\:"List all peers"
-    status\:"Show federation status and alias mappings"
-    request\:"Send federation request to a peer"
-    connect\:"Connect to peer by public key via rendezvous"
-    invite\:"Generate invite token to share with peer"
-    accept\:"Accept peer invite token and connect"
-    approve\:"Approve pending federation request"
-    reject\:"Reject pending federation request"
-    remove\:"Remove peer from federation list"
-    alias\:"Set user-friendly alias for peer"
-    tag\:"Add tags to a peer (local categorization)"
-    untag\:"Remove tags from a peer"
-    update-identity\:"Send updated identity information to approved peer"
-    ping\:"Ping peer gateway to test connectivity"
-    send\:"Send message to federated peer"
-    scopes\:"Show scope grants for peer"
-    grant\:"Update scope grants for approved peer"
-    agent\:"Send agent-comms message to peer"
-  ))' \
-  '*::arg:->args'
+  _arguments \
+    '1:subcommand:((
+      list\:"List all peers"
+      status\:"Show federation status and alias mappings"
+      request\:"Send federation request to a peer"
+      connect\:"Connect to peer by public key via rendezvous"
+      invite\:"Generate invite token to share with peer"
+      accept\:"Accept peer invite token and connect"
+      approve\:"Approve pending federation request"
+      reject\:"Reject pending federation request"
+      remove\:"Remove peer from federation list"
+      alias\:"Set user-friendly alias for peer"
+      tag\:"Add tags to a peer (local categorization)"
+      untag\:"Remove tags from a peer"
+      update-identity\:"Send updated identity information to approved peer"
+      ping\:"Ping peer gateway to test connectivity"
+      send\:"Send message to federated peer"
+      scopes\:"Show scope grants for peer"
+      grant\:"Update scope grants for approved peer"
+      agent\:"Send agent-comms message to peer"
+    ))' \
+    '*::arg:->args'
 
   case "$state" in
     args)
-      case ${words[1]} in
+      case "$subcmd" in
         list)
           _arguments \
-            '(-s --status)'{-s,--status}'[Filter by status]:status:(pending approved rejected removed)'
+            '(-s --status)'{-s,--status}'[Filter by status]:status:(pending approved rejected removed)' \
+            '(-t --tag)'{-t,--tag}'[Filter by tag]:tag:'
           ;;
         request)
           _arguments \
             '1:peer-url:' \
-            '2:peer-id::' \
+            '2:alias::' \
             '(-a --alias)'{-a,--alias}'[User-friendly alias]:alias:' \
             '--petname[Deprecated - use --alias]:petname:'
           ;;
@@ -113,16 +182,29 @@ _ogp_federation() {
             '(-a --alias)'{-a,--alias}'[User-friendly alias]:alias:' \
             '--petname[Deprecated - use --alias]:petname:'
           ;;
-        approve)
+        approve|grant)
           _arguments \
             '1:peer-id:' \
             '--intents[Comma-separated intents to grant]:intents:' \
-            '--rate[Rate limit as requests/seconds]:rate:' \
+            '--rate[Rate limit as requests/windowSeconds]:rate:' \
             '--topics[Comma-separated topics for agent-comms]:topics:'
           ;;
-        reject|remove|scopes|alias)
+        reject|remove|scopes|update-identity)
           _arguments '1:peer-id:'
           ;;
+        alias)
+          _arguments \
+            '1:peer-id:' \
+            '2:alias:'
+          ;;
+        tag|untag)
+          _arguments \
+            '1:peer-id:' \
+            '*:tag:'
+          ;;
+        ping)
+          _arguments '1:peer-url:'
+          ;;
         send)
           _arguments \
             '1:peer-id:' \
@@ -130,13 +212,6 @@ _ogp_federation() {
             '3:payload:' \
             '--to-agent[Target a specific persona on the peer]:persona:'
           ;;
-        grant)
-          _arguments \
-            '1:peer-id:' \
-            '--intents[Comma-separated intents to grant]:intents:' \
-            '--rate[Rate limit as requests/seconds]:rate:' \
-            '--topics[Comma-separated topics for agent-comms]:topics:'
-          ;;
         agent)
           _arguments \
             '1:peer-id:' \
@@ -155,25 +230,27 @@ _ogp_federation() {
 
 _ogp_agent_comms() {
   local curcontext="$curcontext" state line
+  local subcmd="$(_ogp_subcommand_word agent-comms)"
   typeset -A opt_args
 
-  _arguments '1:subcommand:((
-    policies\:"Show response policies"
-    configure\:"Configure response policies"
-    add-topic\:"Add topic to peer response policy"
-    set-topic\:"Set topic policy for peer"
-    set-default\:"Set per-peer default level"
-    remove-topic\:"Remove topic from peer policy"
-    reset\:"Reset peer policy to global defaults"
-    activity\:"Show agent-comms activity log"
-    default\:"Set default response level for unknown topics"
-    logging\:"Enable or disable activity logging"
-  ))' \
-  '*::arg:->args'
+  _arguments \
+    '1:subcommand:((
+      policies\:"Show response policies"
+      configure\:"Configure response policies"
+      add-topic\:"Add topic to peer response policy"
+      set-topic\:"Set topic policy for peer"
+      set-default\:"Set per-peer default level"
+      remove-topic\:"Remove topic from peer policy"
+      reset\:"Reset peer policy to global defaults"
+      activity\:"Show agent-comms activity log"
+      default\:"Set default response level for unknown topics"
+      logging\:"Enable or disable activity logging"
+    ))' \
+    '*::arg:->args'
 
   case "$state" in
     args)
-      case ${words[1]} in
+      case "$subcmd" in
         policies|activity)
           _arguments '1:peer-id::'
           ;;
@@ -204,8 +281,13 @@ _ogp_agent_comms() {
             '1:peer-id:' \
             '2:level:(full summary escalate deny off)'
           ;;
-        remove-topic|reset)
-          _arguments '1:peer-id:' '2:topic::'
+        remove-topic)
+          _arguments \
+            '1:peer-id:' \
+            '2:topic:'
+          ;;
+        reset)
+          _arguments '1:peer-id:'
           ;;
         default)
           _arguments '1:level:(full summary escalate deny off)'
@@ -220,29 +302,32 @@ _ogp_agent_comms() {
 
 _ogp_config() {
   local curcontext="$curcontext" state line
-  typeset -A opt_args
   local -a frameworks
+  local subcmd="$(_ogp_subcommand_word config)"
+  typeset -A opt_args
+
   frameworks=(${(f)"$(ogp config list --quiet 2>/dev/null)"})
 
-  _arguments '1:subcommand:((
-    show\:"Show all configured frameworks and default"
-    set-default\:"Set default framework"
-    list\:"List all frameworks"
-    enable\:"Enable a framework"
-    disable\:"Disable a framework"
-    frameworks\:"Show all detected frameworks"
-    health-check\:"Manage health check configuration"
-    show-identity\:"Show current identity configuration"
-    set-identity\:"Update identity information"
-    set-tags\:"Set tags (replaces existing)"
-    add-tag\:"Add a tag"
-    remove-tag\:"Remove a tag"
-  ))' \
-  '*::arg:->args'
+  _arguments \
+    '1:subcommand:((
+      show\:"Show all configured frameworks and default"
+      set-default\:"Set default framework"
+      list\:"List all frameworks"
+      enable\:"Enable a framework"
+      disable\:"Disable a framework"
+      frameworks\:"Show all detected frameworks"
+      health-check\:"Manage health check configuration"
+      show-identity\:"Show current identity configuration"
+      set-identity\:"Update identity information"
+      set-tags\:"Set tags (replaces existing)"
+      add-tag\:"Add a tag"
+      remove-tag\:"Remove a tag"
+    ))' \
+    '*::arg:->args'
 
   case "$state" in
     args)
-      case ${words[1]} in
+      case "$subcmd" in
         set-default|enable|disable)
           _arguments "1:framework:($frameworks)"
           ;;
@@ -258,32 +343,58 @@ _ogp_config() {
             '--agent-name[Agent name]:name:' \
             '--organization[Organization name]:org:'
           ;;
+        set-tags)
+          _arguments '*:tag:'
+          ;;
+        add-tag|remove-tag)
+          _arguments '1:tag:'
+          ;;
       esac
       ;;
   esac
 }
 
 _ogp_config_health_check() {
-  _arguments '1:subcommand:((
-    show\:"Show current health check configuration"
-    interval\:"Set health check interval in milliseconds"
-    timeout\:"Set health check timeout in milliseconds"
-    max-failures\:"Set max consecutive failures before unhealthy"
-  ))' \
-  '*::arg:->args'
+  local curcontext="$curcontext" state line
+  local subcmd="$(_ogp_subcommand_word health-check)"
+  typeset -A opt_args
+
+  _arguments \
+    '1:subcommand:((
+      show\:"Show current health check configuration"
+      interval\:"Set health check interval in milliseconds"
+      timeout\:"Set health check timeout in milliseconds"
+      max-failures\:"Set max consecutive failures before unhealthy"
+    ))' \
+    '*::arg:->args'
+
+  case "$state" in
+    args)
+      case "$subcmd" in
+        interval|timeout|max-failures)
+          _arguments '1:value:'
+          ;;
+      esac
+      ;;
+  esac
 }
 
 _ogp_intent() {
-  _arguments '1:subcommand:((
-    register\:"Register new intent handler"
-    list\:"List all registered intents"
-    remove\:"Remove registered intent"
-  ))' \
-  '*::arg:->args'
+  local curcontext="$curcontext" state line
+  local subcmd="$(_ogp_subcommand_word intent)"
+  typeset -A opt_args
+
+  _arguments \
+    '1:subcommand:((
+      register\:"Register new intent handler"
+      list\:"List all registered intents"
+      remove\:"Remove registered intent"
+    ))' \
+    '*::arg:->args'
 
   case "$state" in
     args)
-      case ${words[1]} in
+      case "$subcmd" in
         register)
           _arguments \
             '1:name:' \
@@ -299,25 +410,30 @@ _ogp_intent() {
 }
 
 _ogp_project() {
-  _arguments '1:subcommand:((
-    create\:"Create new project locally"
-    join\:"Join existing project"
-    list\:"List all local projects"
-    remove\:"Remove local project"
-    contribute\:"Add contribution to project"
-    query\:"Query project contributions"
-    status\:"Show project status overview"
-    request-join\:"Request to join project from peer"
-    send-contribution\:"Send contribution to peer project"
-    query-peer\:"Query peer project contributions"
-    status-peer\:"Request project status from peer"
-    delete\:"Delete local project and all contributions"
-  ))' \
-  '*::arg:->args'
+  local curcontext="$curcontext" state line
+  local subcmd="$(_ogp_subcommand_word project)"
+  typeset -A opt_args
+
+  _arguments \
+    '1:subcommand:((
+      create\:"Create new project locally"
+      join\:"Join existing project"
+      list\:"List all local projects"
+      remove\:"Remove local project"
+      contribute\:"Add contribution to project"
+      query\:"Query project contributions"
+      status\:"Show project status overview"
+      request-join\:"Request to join project from peer"
+      send-contribution\:"Send contribution to peer project"
+      query-peer\:"Query peer project contributions"
+      status-peer\:"Request project status from peer"
+      delete\:"Delete local project and all contributions"
+    ))' \
+    '*::arg:->args'
 
   case "$state" in
     args)
-      case ${words[1]} in
+      case "$subcmd" in
         create)
           _arguments \
             '1:project-id:' \

package/scripts/render-ogp-overview-video.mjs

@@ -11,7 +11,9 @@ const renderSlidesOnly = process.argv.includes('--slides-only');
 
 const width = 1920;
 const height = 1080;
-const duration = 5.8;
+const fps = 30;
+const clipDuration = 6.8;
+const transitionDuration = 0.6;
 
 const palette = {
   ink: '#10131c',
@@ -386,32 +388,67 @@ for (const png of pngs) {
   }
 }
 
-const concatPath = join(outDir, 'slides.ffconcat');
-const concatLines = ['ffconcat version 1.0'];
+const motionProfiles = [
+  { dx: 26, dy: 14, phaseX: 0.0, phaseY: 0.5 },
+  { dx: -24, dy: 18, phaseX: 0.8, phaseY: 1.2 },
+  { dx: 20, dy: -16, phaseX: 1.4, phaseY: 0.3 },
+  { dx: -22, dy: -14, phaseX: 0.2, phaseY: 1.8 }
+];
+const transitions = [
+  'smoothleft',
+  'fadeblack',
+  'smoothup',
+  'circleopen',
+  'smoothright',
+  'wipeleft',
+  'fadegrays',
+  'diagtl',
+  'smoothdown'
+];
+
+const ffmpegArgs = ['-y'];
 for (const png of pngs) {
-  const absolutePng = resolve(png);
-  concatLines.push(`file '${absolutePng.replaceAll("'", "'\\''")}'`);
-  concatLines.push(`duration ${duration}`);
+  ffmpegArgs.push('-loop', '1', '-t', String(clipDuration), '-i', resolve(png));
+}
+
+const filterParts = [];
+for (let i = 0; i < pngs.length; i++) {
+  const profile = motionProfiles[i % motionProfiles.length];
+  filterParts.push(
+    `[${i}:v]scale=2160:1215,` +
+    `crop=${width}:${height}:` +
+    `x='(in_w-out_w)/2+(${profile.dx})*sin(t*0.42+${profile.phaseX})':` +
+    `y='(in_h-out_h)/2+(${profile.dy})*cos(t*0.34+${profile.phaseY})',` +
+    `fps=${fps},trim=duration=${clipDuration},setpts=PTS-STARTPTS[v${i}]`
+  );
+}
+
+let currentLabel = 'v0';
+for (let i = 1; i < pngs.length; i++) {
+  const offset = ((clipDuration - transitionDuration) * i).toFixed(3);
+  const nextLabel = i === pngs.length - 1 ? 'outv' : `x${i}`;
+  const transition = transitions[(i - 1) % transitions.length];
+  filterParts.push(
+    `[${currentLabel}][v${i}]xfade=transition=${transition}:duration=${transitionDuration}:offset=${offset}[${nextLabel}]`
+  );
+  currentLabel = nextLabel;
 }
-concatLines.push(`file '${resolve(pngs.at(-1)).replaceAll("'", "'\\''")}'`);
-writeFileSync(concatPath, concatLines.join('\n') + '\n');
 
-const finalVideo = join(outDir, 'ogp-overview-demo.mp4');
-execFileSync('ffmpeg', [
-  '-y',
-  '-f', 'concat',
-  '-safe', '0',
-  '-i', concatPath,
-  '-vf', 'format=yuv420p,fps=30',
-  '-r', '30',
+const animatedVideo = join(outDir, 'ogp-overview-demo-animated.mp4');
+ffmpegArgs.push(
+  '-filter_complex', filterParts.join(';'),
+  '-map', `[${currentLabel}]`,
+  '-r', String(fps),
   '-c:v', 'libx264',
   '-movflags', '+faststart',
   '-pix_fmt', 'yuv420p',
-  finalVideo
-], { stdio: 'inherit' });
+  animatedVideo
+);
+
+execFileSync('ffmpeg', ffmpegArgs, { stdio: 'inherit' });
 
-if (!existsSync(finalVideo)) {
-  throw new Error(`Render failed: ${finalVideo} was not created`);
+if (!existsSync(animatedVideo)) {
+  throw new Error(`Render failed: ${animatedVideo} was not created`);
 }
 
-console.log(`Rendered ${finalVideo}`);
+console.log(`Rendered ${animatedVideo}`);