@sage-protocol/pi-adapter 0.2.2 → 0.3.1

package/extensions/index.ts

@@ -13,9 +13,92 @@ import {
 type ExtensionApi = {
   on: (eventName: string, handler: (event: any, ctx: any) => Promise<any> | any) => void;
   registerTool: (tool: any) => void;
+  registerCommand: (name: string, options: { description: string; handler: (args: string, ctx: any) => Promise<void> | void }) => void;
   sendMessage: (message: any, options?: any) => void;
 };
 
+// ── Sage widget state machine ──
+// Three independent layers that merge into widget lines without clobbering.
+// Baseline persists across turns; suggestions and subagents are transient
+// (cleared at start of each before_agent_start).
+
+interface WidgetLayer {
+  lines: string[];
+  updatedAt: number;
+}
+
+class SageWidgetState {
+  baseline: WidgetLayer | null = null;
+  suggestions: WidgetLayer | null = null;
+  subagents: WidgetLayer | null = null;
+
+  /** Clear transient layers at the start of each turn. */
+  clearTransients(): void {
+    this.suggestions = null;
+    this.subagents = null;
+  }
+
+  /** Replace the baseline (static counts, active libs, exposed skills). */
+  setBaseline(text: string): void {
+    this.baseline = { lines: text.split('\n').filter(Boolean), updatedAt: Date.now() };
+  }
+
+  /** Add suggestion count/skills to the transient layer. */
+  setSuggestions(keys: string[]): void {
+    if (keys.length === 0) {
+      this.suggestions = null;
+      return;
+    }
+    const names = keys.map(k => k.startsWith('##') ? k.replace(/^##\s*/, '') : k);
+    const line = names.length === 1
+      ? `↳ suggested: ${names[0]}`
+      : `↳ ${names.length} suggested: ${names.slice(0, 6).join(', ')}${names.length > 6 ? ` +${names.length - 6} more` : ''}`;
+    this.suggestions = { lines: [line], updatedAt: Date.now() };
+  }
+
+  /** Add resolved subagent skill count to the transient layer. */
+  setSubagents(keys: string[]): void {
+    if (keys.length === 0) {
+      this.subagents = null;
+      return;
+    }
+    this.subagents = {
+      lines: [`↳ ${keys.length} subagent: ${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ` +${keys.length - 4} more` : ''}`],
+      updatedAt: Date.now(),
+    };
+  }
+
+  /** Merge all layers into widget lines. */
+  render(): string[] {
+    const output: string[] = [];
+    if (this.baseline) output.push(...this.baseline.lines);
+    if (this.suggestions) output.push(...this.suggestions.lines);
+    if (this.subagents) output.push(...this.subagents.lines);
+    return output;
+  }
+
+  /** Push rendered output to the Pi widget. */
+  updateWidget(ui: any): void {
+    if (!ui?.setWidget) return;
+    const lines = this.render();
+    if (lines.length === 0) return;
+    ui.setWidget('sage', lines);
+  }
+}
+
+/** Extract skill keys from Sage suggestion output. */
+function parseSuggestionKeys(text: string): string[] {
+  const keys: string[] = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('-')) continue;
+    // Match patterns like: "- code-audit" or "- code-audit (code-audit)" or "- code-audit - desc"
+    const m = trimmed.match(/^-\s+(\S+?)(?:\s+\(|$|\s+-)/);
+    if (m) keys.push(m[1]);
+  }
+  return keys;
+}
+
 function parseBoolean(value: string | undefined, fallback: boolean): boolean {
   if (value === undefined) return fallback;
   const normalized = value.trim().toLowerCase();
@@ -226,6 +309,61 @@ function extractUsage(message: any): { input?: string; output?: string } {
   };
 }
 
+function normalizeSkillPath(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.replace(/^file:\/\//, '').replace(/\\+/g, '/').replace(/\/+/g, '/').toLowerCase();
+}
+
+function skillNameFromPath(path: string): string | null {
+  const normalized = normalizeSkillPath(path);
+  if (!normalized || !normalized.endsWith('/skill.md')) return null;
+  const parts = normalized.split('/').filter(Boolean);
+  if (parts.length < 2) return null;
+  return parts[parts.length - 2] ?? null;
+}
+
+function extractSkillCommandName(text: unknown): string | null {
+  if (typeof text !== 'string') return null;
+  const match = text.trim().match(/^\/skill:([a-z0-9][a-z0-9-]*)\b/i);
+  return match?.[1]?.toLowerCase() ?? null;
+}
+
+function extractReadPath(input: unknown): string | null {
+  if (!input || typeof input !== 'object') return null;
+  const obj = input as Record<string, unknown>;
+  const raw = obj.file_path ?? obj.path;
+  return typeof raw === 'string' && raw.trim() ? raw.trim() : null;
+}
+
+function refreshSkillPathIndex(skills: unknown, skillPathToName: Map<string, string>): void {
+  if (!Array.isArray(skills)) return;
+
+  for (const item of skills) {
+    if (!item || typeof item !== 'object') continue;
+    const skill = item as Record<string, unknown>;
+    const name = typeof skill.name === 'string' && skill.name.trim()
+      ? skill.name.trim().toLowerCase()
+      : null;
+    if (!name) continue;
+
+    for (const key of ['filePath', 'file_path', 'path', 'location']) {
+      const normalized = normalizeSkillPath(skill[key]);
+      if (normalized) skillPathToName.set(normalized, name);
+    }
+
+    const baseDir = normalizeSkillPath(skill.baseDir ?? skill.dir ?? skill.directory);
+    if (baseDir) skillPathToName.set(`${baseDir}/skill.md`, name);
+  }
+}
+
+function skillNameFromReadEvent(event: any, skillPathToName: Map<string, string>): string | null {
+  const path = extractReadPath(event?.input ?? event?.args);
+  const normalized = normalizeSkillPath(path);
+  if (!normalized || !normalized.endsWith('/skill.md')) return null;
+  return skillPathToName.get(normalized) ?? skillNameFromPath(normalized);
+}
 
 /**
  * Behavior-aware suggestion enrichment (Option A).
@@ -406,6 +544,7 @@ function formatBehaviorSuggestion(behavior: BehaviorMatch, prompt: string): stri
 export default function sagePiAdapterExtension(pi: ExtensionApi): void {
   const showHookMessages = parseBoolean(process.env.SAGE_SHOW_HOOK_MESSAGES, false);
   const allowBashSageCli = parseBoolean(process.env.SAGE_ALLOW_BASH_CLI, true);
+  const enableBehaviorEnrich = parseBoolean(process.env.SAGE_BEHAVIOR_ENRICH, false);
   const config: SageP2Config = {
     sageBin: process.env.SAGE_BIN ?? 'sage',
     sageProfile: process.env.SAGE_PROFILE,
@@ -454,12 +593,12 @@ export default function sagePiAdapterExtension(pi: ExtensionApi): void {
     label: 'Sage: Behavior',
     promptSnippet: 'Resolve and execute a Sage behavior plan (multi-skill workflow chain)',
     description:
-      'Resolve a behavior key into a multi-skill execution plan and render it as a structured ' +
-      'controller prompt. Behaviors chain multiple skills into a linear workflow — e.g., ' +
-      'entry-plan-review chains: sage → reverse-interviewing → pre-mortem → ceo-plan-review → ' +
-      'plan-eng-review → openprose → confidence-calibration. ' +
+      'Resolve and execute a Sage behavior: a multi-skill workflow whose resolved steps are ' +
+      'coordinated by the Pi behavior executor. Behaviors chain multiple skills into a linear ' +
+      'workflow — e.g., entry-plan-review chains: sage → reverse-interviewing → pre-mortem → ' +
+      'ceo-plan-review → plan-eng-review → openprose → confidence-calibration. ' +
       'Call with key=\'entry-plan-review\' and task=\'Review my implementation plan\'. ' +
-      'The tool returns a structured execution plan for the agent to follow step by step.',
+      'The tool returns the executor payload/result for the resolved skill chain.',
     parameters: {
       type: 'object' as const,
       properties: {
@@ -525,6 +664,38 @@ export default function sagePiAdapterExtension(pi: ExtensionApi): void {
     },
   });
 
+  // Command: manually inspect Sage context injection
+  pi.registerCommand('sage-context', {
+    description: 'Show the Sage session context and loaded skills',
+    handler: async (_args: string, ctx: any) => {
+      const sessionId = getSessionId(ctx);
+      let output = '';
+
+      try {
+        const context = await hookRuntime.getSessionContext(sessionId);
+        if (context) {
+          output += '## Injected Sage Context (hidden from UI)\n```\n' +
+            (context.length > 2000 ? context.slice(0, 2000) + '\n... (truncated)' : context) +
+            '\n```\n\n';
+        }
+      } catch {
+        output += '(sage skill context --format pi failed)\n\n';
+      }
+
+      try {
+        const summary = await hookRuntime.getSkillVisibilitySummary();
+        if (summary) {
+          output += '## Visible Summary\n' + summary + '\n\n';
+        }
+      } catch {
+        output += '(library summary failed)\n\n';
+      }
+
+      output += 'Tip: set SAGE_SHOW_HOOK_MESSAGES=1 to see context in the UI.';
+      ctx.ui.notify(output, 'info');
+    },
+  });
+
   // ---------------------------------------------------------------------------
   // System prompt injection: Sage-first routing for Pi sessions
   // ---------------------------------------------------------------------------
@@ -534,8 +705,8 @@ export default function sagePiAdapterExtension(pi: ExtensionApi): void {
   // Tier 2: Full usage patterns injected once at session_start (below).
   // Tier 3: Complete CLI reference available on-demand via sage_status({}).
   //
-  // This per-turn string is a minimal guardrail that complements tool-level docs.
-  // It does NOT repeat usage patterns — those are in Tier 2 (session_start).
+  // This per-turn string is intentionally small. Do not prepend the full
+  // `sage skill context` output here; that belongs in Tier 2 only.
   const SAGE_PER_TURN_GUARDRAIL = `
 [Sage Tools - Internet Access]
 You have sage_search, sage_execute, and sage_status tools for internet and external service access.
@@ -544,9 +715,9 @@ Sage internal tools are available immediately. Only external MCP servers need li
 `.trim();
 
   // Tier 2: Full Sage protocol context injected ONCE at session_start.
-  // Includes skill trigger workflow, external research patterns, hub management,
-  // library/DAO/bounty recipes, and best practices — everything the model needs
-  // to use Sage effectively, but only needs to see once per session.
+  // Prefer the dynamic CLI context because it is generated from the canonical
+  // Sage runtime templates. Keep the static block as a fallback only; appending
+  // both creates duplicate routing instructions in every Pi session.
   const SAGE_SESSION_CONTEXT = `
 ## Sage MCP + CLI Routing
 
@@ -587,30 +758,77 @@ Use these tools proactively when the user asks about current events, needs docum
 
   let lastPrompt = '';
   let lastSuggestionAt = 0;
+  const skillPathToName = new Map<string, string>();
+  const pendingInputSkillUses = new Set<string>();
+  let usedSkillsThisTurn = new Set<string>();
+  let pendingReadToolSkills = new Map<string, string>();
+  let currentPromptPreview = '';
+  let toolErrorSeenThisTurn = false;
+  const autoRecordSkillOutcome = parseBoolean(process.env.SAGE_AUTO_SKILL_OUTCOME, true);
+
+  // Sage widget state — baseline + per-turn transients
+  const sageWidget = new SageWidgetState();
+
+  const rememberSkillUse = (skillName: string | null | undefined): void => {
+    const normalized = typeof skillName === 'string' ? skillName.trim().toLowerCase() : '';
+    if (normalized) usedSkillsThisTurn.add(normalized);
+  };
+
   pi.on('session_start', async (_event, ctx) => {
     const sessionId = getSessionId(ctx);
 
-    // Tier 2: Inject full Sage protocol context once at session start.
-    // This includes skill trigger workflow, external tool patterns, recipes,
-    // and best practices — everything the model needs but only sees once.
+    // Inject full Sage protocol context once at session start.
     let fullContext = SAGE_SESSION_CONTEXT;
     try {
       const dynamicContext = await hookRuntime.getSessionContext(sessionId);
       if (dynamicContext.trim()) {
-        fullContext = `${dynamicContext.trim()}\n\n${SAGE_SESSION_CONTEXT}`;
+        fullContext = dynamicContext.trim();
       }
     } catch {
-      // Keep static SAGE_SESSION_CONTEXT as fallback
+      // Keep static SAGE_SESSION_CONTEXT as fallback.
     }
 
     pi.sendMessage(
       {
         customType: 'sage-session-context',
         content: fullContext,
-        display: showHookMessages,
+        display: false,
       },
       { deliverAs: 'nextTurn' }
     );
+
+    // Update persistent skill widget via state machine.
+    // Fetch baseline once, render, and update widget.
+    try {
+      const summary = await hookRuntime.getSkillVisibilitySummary();
+      if (summary) {
+        sageWidget.setBaseline(summary);
+        sageWidget.updateWidget(ctx.ui);
+      }
+    } catch {
+      // Non-blocking.
+    }
+
+    // Fallback: hook message for non-TUI modes
+    if (!ctx.ui?.setWidget) {
+      try {
+        const summary = await hookRuntime.getSkillVisibilitySummary();
+        if (summary) {
+          pi.sendMessage(
+            { customType: 'sage-loaded', content: summary, display: true },
+            { deliverAs: 'nextTurn' }
+          );
+        }
+      } catch {
+        // Non-blocking.
+      }
+    }
+  });
+
+  pi.on('input', async (event) => {
+    const skillName = extractSkillCommandName(event?.text);
+    if (skillName) pendingInputSkillUses.add(skillName);
+    return { action: 'continue' };
   });
 
   pi.on('before_agent_start', async (event, ctx) => {
@@ -619,36 +837,28 @@ Use these tools proactively when the user asks about current events, needs docum
     const continuationPrompt = isContinuationPrompt(prompt);
 
     const sessionId = getSessionId(ctx);
+    refreshSkillPathIndex(event?.systemPromptOptions?.skills, skillPathToName);
+    usedSkillsThisTurn = new Set(pendingInputSkillUses);
+    pendingInputSkillUses.clear();
+    pendingReadToolSkills = new Map<string, string>();
+    currentPromptPreview = prompt.slice(0, 240);
+    toolErrorSeenThisTurn = false;
+
+    // Clear per-turn transient widget layers
+    sageWidget.clearTransients();
+
     await hookRuntime.capturePrompt(prompt, sessionId);
 
     // --- System prompt injection (EVERY turn) ---
     // Pi resets to _baseSystemPrompt if result.systemPrompt is undefined,
-    // so we must always return the modified prompt to keep Sage docs active.
+    // so we must always return the modified prompt to keep the compact Sage
+    // guardrail active. Keep this block small: the full Sage context is sent
+    // once during session_start.
     let modifiedSystemPrompt: string | undefined;
     if (injectToolDocs) {
       const currentSystemPrompt = typeof event?.systemPrompt === 'string' ? event.systemPrompt : '';
       if (currentSystemPrompt) {
         let docs = SAGE_PER_TURN_GUARDRAIL;
-        try {
-          const sessionContext = await hookRuntime.getSessionContext(sessionId);
-          if (sessionContext.trim()) {
-            docs = `${sessionContext.trim()}\n\n${SAGE_PER_TURN_GUARDRAIL}`;
-          }
-        } catch {
-          // Session-context injection is best-effort — never block the turn.
-        }
-
-        // Dynamic identity context: wallet, libraries, skill counts.
-        // Cached for 60s so the CLI cost is negligible per-turn.
-        try {
-          const identity = await hookRuntime.getIdentityContext();
-          if (identity) {
-            docs = `${identity}\n\n${docs}`;
-          }
-        } catch {
-          // Identity injection is best-effort — never block the turn.
-        }
-
         modifiedSystemPrompt = currentSystemPrompt + '\n\n' + docs;
       }
     }
@@ -706,6 +916,9 @@ Use these tools proactively when the user asks about current events, needs docum
               skillBlocks.push(`\n--- Sage Skill: ${name} ---\n${content}\n--- End Skill: ${name} ---`);
             }
             modifiedSystemPrompt += '\n\n[Auto-resolved Sage Skills]\n' + skillBlocks.join('\n');
+
+            // Track for widget — rendered at end of before_agent_start
+            sageWidget.setSubagents([...resolved.keys()]);
           }
         } catch {
           // Non-blocking — subagent proceeds without injected skills
@@ -726,11 +939,8 @@ Use these tools proactively when the user asks about current events, needs docum
 
       let suggestions = await hookRuntime.suggestSkill(prompt, sessionId);
 
-      // Option A: Enrich suggestions with behavior chain info when a
-      // behavior entrypoint matches. This gives the model both options
-      // (full chain via sage_behavior OR individual skill via use_skill)
-      // and lists all steps for false-positive assessment.
-      if (suggestions.trim()) {
+      // Behavior enrichment — opt-in via SAGE_BEHAVIOR_ENRICH=1
+      if (suggestions.trim() && enableBehaviorEnrich) {
         try {
           suggestions = await enrichSuggestionsWithBehaviors(suggestions, prompt, bridge);
         } catch {
@@ -744,9 +954,17 @@ Use these tools proactively when the user asks about current events, needs docum
           content: suggestions,
           display: showHookMessages,
         };
+
+        // Update widget with suggestion skill names
+        const suggestedKeys = parseSuggestionKeys(suggestions);
+        sageWidget.setSuggestions(suggestedKeys);
       }
     }
 
+    // Always push current widget state after processing suggestions.
+    // Transients may have been cleared or set; render them now.
+    sageWidget.updateWidget(ctx.ui);
+
     // Return combined result if either system prompt or message changed
     if (modifiedSystemPrompt || suggestionMessage) {
       const result: Record<string, unknown> = {};
@@ -756,6 +974,28 @@ Use these tools proactively when the user asks about current events, needs docum
     }
   });
 
+  pi.on('agent_end', async (_event, ctx) => {
+    const usedSkills = [...usedSkillsThisTurn];
+    if (usedSkills.length === 0) return;
+
+    const sessionId = getSessionId(ctx);
+    await hookRuntime.recordSuggestionUse(usedSkills, sessionId);
+
+    if (autoRecordSkillOutcome) {
+      const status = toolErrorSeenThisTurn ? 'failed' : 'passed';
+      await Promise.allSettled(
+        usedSkills.map((skillName) =>
+          hookRuntime.recordExecutionOutcome(skillName, status, currentPromptPreview, sessionId)
+        )
+      );
+    }
+
+    usedSkillsThisTurn = new Set<string>();
+    pendingReadToolSkills = new Map<string, string>();
+    currentPromptPreview = '';
+    toolErrorSeenThisTurn = false;
+  });
+
   pi.on('message_end', async (event, ctx) => {
     const message = event?.message;
     if (!message || typeof message !== 'object') return;
@@ -773,7 +1013,15 @@ Use these tools proactively when the user asks about current events, needs docum
 
   pi.on('tool_call', async (event, ctx) => {
     const toolName = typeof event?.toolName === 'string' ? event.toolName : '';
-    if (!toolName || toolName.startsWith('sage_')) return;
+    if (!toolName) return;
+
+    if (toolName === 'read') {
+      const skillName = skillNameFromReadEvent(event, skillPathToName);
+      const toolCallId = typeof event?.toolCallId === 'string' ? event.toolCallId : '';
+      if (skillName && toolCallId) pendingReadToolSkills.set(toolCallId, skillName);
+    }
+
+    if (toolName.startsWith('sage_')) return;
 
     const toolInput =
       event?.input && typeof event.input === 'object'
@@ -855,7 +1103,18 @@ Use these tools proactively when the user asks about current events, needs docum
 
   pi.on('tool_result', async (event, ctx) => {
     const toolName = typeof event?.toolName === 'string' ? event.toolName : '';
-    if (!toolName || toolName.startsWith('sage_')) return;
+    if (!toolName) return;
+
+    if (Boolean(event?.isError)) toolErrorSeenThisTurn = true;
+
+    if (toolName === 'read' && !Boolean(event?.isError)) {
+      const toolCallId = typeof event?.toolCallId === 'string' ? event.toolCallId : '';
+      const skillName = skillNameFromReadEvent(event, skillPathToName) ?? pendingReadToolSkills.get(toolCallId);
+      rememberSkillUse(skillName);
+      if (toolCallId) pendingReadToolSkills.delete(toolCallId);
+    }
+
+    if (toolName.startsWith('sage_')) return;
 
     const toolInput =
       event?.input && typeof event.input === 'object'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/pi-adapter",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Sage Protocol MCP integration for pi coding agent",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,7 +38,7 @@
     "@sinclair/typebox": "^0.34.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": ">=0.61.0 <0.65.0"
+    "@earendil-works/pi-coding-agent": ">=0.64.0 <0.80.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/skills/sage-bridge/SKILL.md

@@ -50,6 +50,11 @@ sage_status({})
 
 Returns bridge health, wallet connection, network, and session info.
 
+If `sage_status` reports a degraded or unavailable bridge, do not keep retrying
+silently. Tell the user the Sage MCP bridge is unavailable and suggest
+restarting Pi/Sage bridge or verifying `sage mcp start`. Only suggest
+`sage daemon start` when the reported failure is specifically daemon reachability.
+
 ---
 
 ## Behavior Loop
@@ -85,13 +90,40 @@ sage_search({ domain: "rlm", action: "stats" })
 **5. Earn & Collaborate** — Publish, vote, tip, bounty.
 
 ```bash
-sage library push my-library
+sage library push my-library --bump patch
 sage governance proposals vote 1 for
 sage bounties list
 ```
 
 ---
 
+## Choose a Sage distribution surface by intent
+
+Do not collapse every write path into a generic idea of "publish." Choose the smallest surface that matches the actual goal:
+
+- **P2P** — sync trusted machines/agents privately.
+- **Shared library** — collaborate privately with explicit members/invites.
+- **Personal cloud** — host a creator-controlled canonical library; it starts private by default.
+- **Public personal cloud** — make a hosted library publicly discoverable only when the user explicitly asks, with `sage library visibility <library-id> public`.
+- **Marketplace** — sell a polished public personal library as a packaged capability.
+- **DAO promotion** — make a library canonical for a group/community and unlock curation, legitimacy, on-chain reputation, tips, bounties, and community-driven improvement.
+
+**Governance chooser**
+- **personal DAO** — fastest operator-controlled canon
+- **team DAO** — trusted shared stewardship
+- **community DAO** — strongest public curation and legitimacy
+
+Pi routing rules:
+- If the user says **direct share** or **share privately**, think **shared library** first.
+- If the goal is trusted fleet propagation, think **P2P**, not governance.
+- If the goal is creator-controlled hosting, think **personal cloud** and remember it is private by default.
+- If the goal is public web/discovery access, confirm explicit intent before making a library public.
+- If the goal is monetization, think **marketplace**.
+- If the goal is public canon, stronger provenance, future bounties, and repeated community improvement, think **DAO promotion**.
+- If one surface is clearly implied, proactively suggest it instead of waiting for the user to name the exact Sage term.
+- Install/expose is local harness visibility only; do not treat it as publishing.
+- Public feeds/search should only advertise anonymously readable prompts and skills; keep owner-only, unpinned, expired, or otherwise non-openable CIDs out of public discovery until republished or made public.
+
 ## When to Trigger
 
 Proactively search Sage when:
@@ -131,7 +163,7 @@ Recommended `.pi/settings.json` shape in a local monorepo:
     "-../.agents/skills/frontend-design/SKILL.md",
     "-~/.pi/agent/skills/prompt-builder/SKILL.md",
     "-~/.pi/agent/skills/sage/SKILL.md",
-    "-~/.pi/agent/skills/sage-codebase/SKILL.md"
+    "-~/.pi/agent/skills/sage-workflow/SKILL.md"
   ],
   "enableSkillCommands": true
 }
@@ -190,8 +222,9 @@ sage library list
 sage library create <name>
 sage library skill add <path> -l <library>
 sage library prompt add <name> -l <library> --file <path>
-sage library push <library>
+sage library push <library> --bump patch
 sage library promote <library> --dao 0x... --collection default --yes
+# Use `major`, `minor`, or `patch` for `--bump`; exact SemVer and `status --across` are not current CLI commands.
 sage library discover
 sage library sync
 ```
@@ -237,7 +270,9 @@ sage social post "message"
 ```bash
 sage wallet balance
 sage wallet current
-sage wallet connect privy
+sage wallet create sage-wallet
+sage wallet connect ows -n sage-wallet
+sage wallet connect privy --device-code
 sage wallet delegate
 sage delegation create --delegation-profile voter
 sage delegation list
@@ -247,7 +282,9 @@ sage agent register
 sage agent quickstart
 ```
 
-`sage wallet delegate` is ERC20Votes self-delegation for governance voting power. `sage delegation ...` is ERC-7710 scoped agent delegation management.
+Preserve the user's already-working wallet/session preference when one exists. The examples above show common direct-wallet and provider-session paths, not a requirement to force one provider.
+
+`sage wallet delegate` is ERC20Votes self-delegation for governance voting power. `sage delegation ...` is scoped agent delegation management.
 
 ### RLM Capture
 
@@ -274,6 +311,7 @@ sage mcp call <tool> --args '{...}'
 ## Common Pitfalls
 
 - **Hook mode vs query mode**: `sage suggest hook skill` reads the `PROMPT` environment variable or stdin — don't pass the prompt as a positional argument.
+- **Bridge vs daemon wording**: Pi primarily talks to Sage through the MCP bridge. When `sage_status` shows bridge degradation, say "Sage MCP bridge unavailable" and verify `sage mcp start`; don't default to daemon-start advice unless the daemon is the reported failure.
 - **`external/search` requires `tool_name`**: Always include `tool_name` in params when searching via external domain (e.g., `tool_name: "web_search"`).
 - **Domain routing**: Each domain has its own set of actions. Use `sage_search({ domain: "help", action: "list" })` to discover available actions.
 - **Legacy commands removed**: Do not use `sage dao ...`, `sage proposals ...`, or `sage ipfs ...` — these are replaced by `sage governance dao ...`, `sage governance proposals ...`, and `sage config ipfs ...`.