Pop Obsidian

POP Super-Obsidian — Plugin Orchestration Protocol

The POP protocol enables real-time orchestration of multi-step pipelines through Obsidian. It connects Claude (orchestrator), Obsidian (vault + UI), and the Rust TUI (monitoring dashboard) via JSON-RPC over WebSocket at ws://127.0.0.1:8088.

Protocol Overview

POP operates in 5 phases, each with specific JSON-RPC message types:

Phase 1: Discovery

Message: GET_PLUGIN_MANIFEST Purpose: Ask the Obsidian plugin what capabilities are installed.

{
  "jsonrpc": "2.0",
  "method": "GET_PLUGIN_MANIFEST",
  "id": 1
}

Response: Returns a manifest of all installed Obsidian plugins with their exposed actions. Use this to understand what the vault can do before constructing a pipeline.

Phase 2: Orchestration

Message: EXECUTE_PIPELINE Purpose: Send a named pipeline with steps to execute.

{
  "jsonrpc": "2.0",
  "method": "EXECUTE_PIPELINE",
  "params": {
    "pipeline": "idea-to-publish",
    "steps": [
      {"id": "spark", "action": "create_note", "params": {"title": "...", "content": "..."}},
      {"id": "expand", "action": "ai_expand", "params": {"note_id": "$spark.output.id"}},
      {"id": "visual", "action": "generate_figure", "params": {"note_id": "$expand.output.id"}},
      {"id": "verify", "action": "wave_check", "params": {"content": "$expand.output.content"}},
      {"id": "assemble", "action": "merge_notes", "params": {"ids": ["$spark", "$expand", "$visual"]}},
      {"id": "export", "action": "export_pdf", "params": {"note_id": "$assemble.output.id"}}
    ],
    "coherence_threshold": 0.85,
    "atom_token": "$ATOM_TOKEN_RESONANCE"
  },
  "id": 2
}

Step references: Use $step_id.output.field to reference outputs from previous steps. This creates a DAG of dependencies that the orchestrator resolves in topological order.

Phase 3: Progress

Message: STEP_COMPLETE Direction: Obsidian → Claude (notification)

{
  "jsonrpc": "2.0",
  "method": "STEP_COMPLETE",
  "params": {
    "pipeline_id": "...",
    "step_id": "expand",
    "status": "complete",
    "output": {"id": "note-abc", "content": "..."},
    "wave_score": 0.91,
    "duration_ms": 1250
  }
}

Each step completion is forwarded to the Rust TUI for real-time gauge updates.

Phase 4: Coherence

Message: COHERENCE_REPORT Purpose: Full pipeline coherence assessment after all steps complete.

{
  "jsonrpc": "2.0",
  "method": "COHERENCE_REPORT",
  "params": {
    "pipeline_id": "...",
    "overall_score": 0.89,
    "step_scores": {"spark": 0.92, "expand": 0.91, "visual": 0.87, "verify": 0.93},
    "conservation_check": {"alpha": 7, "omega": 8, "sum": 15, "valid": true},
    "atom_trail_id": "ATOM-2026-02-16-..."
  }
}

If overall_score < coherence_threshold, the pipeline is flagged for review.

Phase 5: Error

Message: PIPELINE_FAILED Direction: Either direction (any party can signal failure)

{
  "jsonrpc": "2.0",
  "method": "PIPELINE_FAILED",
  "params": {
    "pipeline_id": "...",
    "failed_step": "visual",
    "error": "Figure generation timed out",
    "partial_outputs": {"spark": "...", "expand": "..."},
    "recovery": "retry_step"
  }
}

Recovery options: retry_step, skip_step, abort, rollback

Built-in Pipelines

Read references/pipeline-templates.md for full pipeline definitions.

Quick Reference

Connection Architecture

Claude (Orchestrator)
    ↓ JSON-RPC
ws://127.0.0.1:8088
    ↓
Rust WebSocket Bridge (crates/websocket-bridge)
    ├── → Obsidian Plugin (vault operations)
    ├── → Rust TUI (crates/tui — monitoring dashboard)
    └── → WAVE Scorer (coherence at each transition)

The Rust bridge is the central hub. It:

1. Receives EXECUTE_PIPELINE from Claude
2. Dispatches steps to Obsidian
3. Receives STEP_COMPLETE from Obsidian
4. Forwards telemetry to the TUI
5. Runs WAVE checks at transitions
6. Sends COHERENCE_REPORT back to Claude

Authentication

All POP messages include an ATOM token for authentication:

• $ATOM_TOKEN_RESONANCE — generated via atom_tag_generate
• Token encodes: session ID, agent identity, coherence threshold, conservation proof
• Five-strand anyon braid topology (see docs/ATOM_AUTH.md)

Implementing the Obsidian Side

The Obsidian plugin needs to:

1. Listen on ws://127.0.0.1:8088 for incoming connections
2. Expose GET_PLUGIN_MANIFEST with all installed plugin actions
3. Handle EXECUTE_PIPELINE by running steps against the vault
4. Report STEP_COMPLETE after each step with outputs and timing
5. Generate COHERENCE_REPORT using vault content analysis

For the TypeScript implementation details, read references/protocol-spec.md.