# Usage Guide

## Requirements

- Node project using `@earendil-works/pi-coding-agent`
- Sage CLI installed and on `PATH` (`sage`)
- See [earendil-works/pi](https://github.com/earendil-works/pi) and [sage-protocol/sage](https://github.com/sage-protocol/sage)

## Integration Modes

1. **pi CLI extension** — `pi install npm:@sage-protocol/pi-adapter` (no source changes)
2. **SDK embedding** — `createSageSessionConfig(...)` for harness source owners

## pi CLI Mode

```bash
pi install npm:@sage-protocol/pi-adapter
pi list  # verify installed
```

Restart pi and use normally. What loads automatically:

- custom tools: `sage_search`, `sage_execute`, `sage_status`, `sage_behavior`
- skill suggestions: `sage suggest hook skill` (per-turn)
- capture hooks: `sage capture hook prompt/response`
- security hooks: `sage security scan-hook` (pre/post tool)

## SDK Integration

```typescript
import { createAgentSession, createCodingTools } from '@earendil-works/pi-coding-agent';
import { createSageSessionConfig } from '@sage-protocol/pi-adapter';

const sage = await createSageSessionConfig({
  sageBin: 'sage',
  source: 'pi-agent-core',
  suggestLimit: 3,
});

const { session } = await createAgentSession({
  model,
  tools: sage.wrapToolsWithSecurity(createCodingTools(cwd)),
  customTools: sage.customTools,
});

const disposeSageHooks = sage.setupHooks(session);
// on teardown: disposeSageHooks()
```

## Plugin Pattern

```typescript
export async function setupSagePlugin(runtime) {
  const sage = await createSageSessionConfig({ source: 'pi-agent-core' });
  const { session } = await runtime.makeSession({
    model: runtime.model,
    tools: sage.wrapToolsWithSecurity(runtime.tools),
    customTools: sage.customTools,
  });
  const dispose = sage.setupHooks(session);
  return {
    session,
    dispose: async () => { dispose(); await sage.mcpBridge.stop(); },
  };
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SAGE_BIN` | `sage` | Path to sage CLI |
| `SAGE_PROFILE` | — | Sage config profile (e.g. `testnet`) |
| `SAGE_SUGGEST_LIMIT` | `3` | Max skill suggestions per turn |
| `SAGE_SUGGEST_DEBOUNCE_MS` | `800` | Minimum ms between suggestions |
| `SAGE_SECURITY_HOOKS` | `1` | Enable pre/post tool security scanning |
| `SAGE_RLM_FEEDBACK` | `1` | Enable prompt/response capture |
| `SAGE_SHOW_HOOK_MESSAGES` | `0` | Display hook messages in chat UI |
| `SAGE_ALLOW_BASH_CLI` | `1` | Allow direct `sage ...` bash calls |
| `SAGE_BEHAVIOR_ENRICH` | `0` | Enable behavior chain enrichment on suggestions |
| `SAGE_AUTO_RESOLVE_SKILLS` | `1` | Auto-resolve skill content for subagents |
| `SAGE_INJECT_TOOL_DOCS` | `1` | Inject Sage tool guardrails per-turn |

### Skill Quality Annotations

The widget automatically annotates suggested skills with execution quality data from the Sage daemon. No extra configuration needed — just ensure the daemon is running (`sage daemon start`).

Annotations appear when the daemon has ≥3 recorded execution outcomes per skill:

- `✓` — ≥70% pass rate (reliable)
- `⚠` — 40-70% pass rate (mixed)
- `✗` — <40% pass rate (harmful — skipped in subagent contexts)
- (none) — insufficient data

Quality data is cached for the session lifetime. Skills with <30% pass rate and ≥3 samples are skipped during subagent auto-resolve.

## Project Config

For monorepo development, keep pi thin — point at the Sage Pi export surface:

```json
{
  "packages": [
    "../packages/sage-pi-adapter",
    {
      "source": "../packages/sage-pi-export",
      "skills": ["skills/*/SKILL.md"]
    }
  ],
  "enableSkillCommands": true
}
```