docs: rebuild KB in OKF v0.1 with live-verified facts
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
This commit is contained in:
Frank committed
1 parent
552d1ef8bf
commit
02883d3ed2
116 files changed
+13008
No files matched your search
@@ -0,0 +1,29 @@
|
||||
# Pi Packages
|
||||
|
||||
Pi extends its functionality through npm packages installed via `pi install`. Each package provides extensions, skills, prompts, or themes.
|
||||
|
||||
## Installed Packages
|
||||
|
||||
| Package | Version | Description |
|
||||
|---------|---------|-------------|
|
||||
| [[pi-peon|pi-peon]] | 0.1.1 | CESP/OpenPeon sound-pack player for pi lifecycle events |
|
||||
| [[pi-web-access|pi-web-access]] | 0.22.0 | Web search, URL fetching, GitHub cloning, PDF extraction, video understanding |
|
||||
|
||||
## Core Extension
|
||||
|
||||
| Package | Version | Description |
|
||||
|---------|---------|-------------|
|
||||
| [[pi-subagents|pi-subagents]] | 0.36.0 | Core subagent delegation — chains, parallel execution, TUI clarification |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [[settings|settings]] — Package configuration in settings.json
|
||||
- [pi](../index.md) — Pi configuration overview
|
||||
|
||||
* [Pi Peon](pi-peon.md) — CESP/OpenPeon sound-pack player for pi lifecycle events — peons, GLaDOS, battlecruisers, and 300+ community sound packs.
|
||||
|
||||
* [Pi Subagents](pi-subagents.md) — Core pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification.
|
||||
|
||||
* [Pi Web Access](pi-web-access.md) — Web search, URL fetching, GitHub cloning, PDF extraction, and video understanding for Pi. Zero-config with Exa MCP.
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
type: reference
|
||||
title: Pi Peon
|
||||
description: CESP/OpenPeon sound-pack player for pi lifecycle events — peons, GLaDOS, battlecruisers, and 300+ community sound packs.
|
||||
tags:
|
||||
- pi
|
||||
- package
|
||||
- sound
|
||||
- peon
|
||||
- cesp
|
||||
- openpeon
|
||||
- unverified
|
||||
timestamp: 2026-08-28
|
||||
---
|
||||
|
||||
# Pi Peon
|
||||
|
||||
**Package:** `@wierdbytes/pi-peon`
|
||||
**Version:** 0.1.1
|
||||
**Author:** wierdbytes
|
||||
|
||||
Plays CESP/OpenPeon sound packs on pi lifecycle events. Drop a sound pack into `~/.openpeon/packs/<name>/` or install from the community registry (300+ packs).
|
||||
|
||||
---
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pi install @wierdbytes/pi-peon
|
||||
```
|
||||
|
||||
## Sound Packs
|
||||
|
||||
Installed packs in `~/.openpeon/packs/`:
|
||||
|
||||
| Pack | Theme |
|
||||
|------|-------|
|
||||
| `peon` | Warcraft III Orc Peon (default) |
|
||||
| `peasant` | Medieval peasant |
|
||||
| `sc2_scv` | StarCraft II SCV |
|
||||
| `ra2_soviet_engineer` | Red Alert 2 Soviet Engineer |
|
||||
| `sc_battlecruiser` | StarCraft Battlecruiser |
|
||||
| `zugzug` | Zugzug robot |
|
||||
|
||||
## Events
|
||||
|
||||
| pi Event | CESP Category |
|
||||
|----------|---------------|
|
||||
| `session_start` | `session.start` |
|
||||
| `agent_start` | `task.acknowledge` |
|
||||
| `agent_end` (used tools) | `task.complete` |
|
||||
| `agent_end` (no tools) | `input.required` |
|
||||
| `tool_result` (error) | `task.error` |
|
||||
| Rate limit (429) | `resource.limit` |
|
||||
| `task.progress` | `task.progress` |
|
||||
| User spam (3 msgs/5s) | `user.spam` |
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/peon` | Open settings modal |
|
||||
| `/peon status` | Print active pack + config |
|
||||
| `/peon mute` | Silence all categories |
|
||||
| `/peon unmute` | Re-enable sounds |
|
||||
| `/peon test [category]` | Play a random sound |
|
||||
| `/peon reset` | Restore default config |
|
||||
|
||||
CLI flag `--no-peon` disables playback for one session.
|
||||
|
||||
## Settings
|
||||
|
||||
The `/peon` command opens an interactive settings modal with:
|
||||
|
||||
- **Packs** — Active, available, and registry packs
|
||||
- **Volume** — Global volume control
|
||||
- **Mute** — Per-event toggles
|
||||
- **Registry browser** — Browse and install from community registry
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [packages](../../packages/index.md) — Package overview
|
||||
- [pi](../index.md) — Pi configuration
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
type: reference
|
||||
title: Pi Subagents
|
||||
description: Core pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification.
|
||||
tags:
|
||||
- pi
|
||||
- subagents
|
||||
- delegation
|
||||
- chains
|
||||
- limits
|
||||
- unverified
|
||||
timestamp: 2026-08-28
|
||||
---
|
||||
|
||||
# Pi Subagents
|
||||
|
||||
**Package:** `pi-subagents`
|
||||
**Version:** 0.36.0
|
||||
|
||||
Core pi extension for delegating tasks to subagents. Supports sequential chains, parallel execution, and TUI clarification workflows.
|
||||
|
||||
## Features
|
||||
|
||||
- **Sequential chains** — Pipeline tasks through multiple subagents
|
||||
- **Parallel execution** — Fan out independent tasks simultaneously
|
||||
- **TUI clarification** — Interactive preview and editing before execution
|
||||
- **Watchdog** — Health monitoring for subagent runs
|
||||
- **Model overrides** — Per-agent model selection
|
||||
|
||||
## Agent Roles
|
||||
|
||||
| Role | Default Model | Purpose |
|
||||
|------|---------------|---------|
|
||||
| `scout` | frank-default-small | Quick exploration |
|
||||
| `researcher` | frank-default-small | Information gathering |
|
||||
| `planner` | frank-default-large | Task planning |
|
||||
| `worker` | frank-default-large | Implementation |
|
||||
| `reviewer` | frank-default-large | Code/document review |
|
||||
| `oracle` | frank-default-large | Complex reasoning |
|
||||
| `context-builder` | frank-default-large | Context building |
|
||||
|
||||
## Parallel Execution and Limits
|
||||
|
||||
Parallel execution fans out independent tasks. The extension applies several limits to control the load.
|
||||
|
||||
| Limit | Effective value | Source |
|
||||
|-------|-----------------|--------|
|
||||
| `globalConcurrencyLimit` | **2** | `extensions/subagent/config.json` |
|
||||
| `parallel.maxTasks` | 8 | default |
|
||||
| `parallel.concurrency` | 4 | default |
|
||||
| `maxSubagentSpawnsPerSession` | unlimited | default |
|
||||
| `maxSubagentDepth` | 2 | default |
|
||||
| `turnBudget.maxTurns` | 30 | `extensions/subagent/config.json` |
|
||||
|
||||
`globalConcurrencyLimit` caps the simultaneously-running subagent tasks within one run. The default is 20. The value here is 2. Effective concurrency is the lower of the local cap and the available global slots. Per-step `concurrency` and `parallel.concurrency` still apply. A value below 1 is clamped to 1.
|
||||
|
||||
Set `globalConcurrencyLimit` in `extensions/subagent/config.json`. The file also configures `artifactDir`, `turnBudget`, and proactive skill suggestions.
|
||||
|
||||
`maxSubagentSpawnsPerSession` caps the cumulative child launches during one parent session. It counts completed and failed children, parallel task counts, static chain steps, and bounded dynamic fanout children. The default is unlimited. Set the value to `0` to disable a configured cap.
|
||||
|
||||
`maxSubagentDepth` controls nested delegation. The default is 2. Each agent can tighten the limit for its own child runs. An agent cannot relax a stricter inherited limit.
|
||||
|
||||
No per-model limit exists. All caps are global to a run or a session. They do not depend on the child model.
|
||||
|
||||
## See Also
|
||||
|
||||
- [[settings|settings]] — Subagent configuration
|
||||
- [[models|models]] — Model definitions
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
type: reference
|
||||
title: Pi Web Access
|
||||
description: Web search, URL fetching, GitHub cloning, PDF extraction, and video understanding for Pi. Zero-config with Exa MCP.
|
||||
tags:
|
||||
- pi
|
||||
- package
|
||||
- web-search
|
||||
- fetch
|
||||
- youtube
|
||||
- unverified
|
||||
timestamp: 2026-08-28
|
||||
---
|
||||
|
||||
# Pi Web Access
|
||||
|
||||
**Package:** `pi-web-access`
|
||||
**Version:** 0.22.0
|
||||
**Author:** Nico Bailon
|
||||
|
||||
Web search, content extraction, and video understanding for Pi. It calls your self-hosted SearXNG first when one is configured, and falls through to other providers.
|
||||
|
||||
> **Active setup:** `~/.pi/web-search.json` locks search to SearXNG at `http://192.168.0.143:8081` (dankclaw), permits LAN fetches via `ssrf.allowRanges`, and sets `maxInlineContentChars` to 50000. The config file is cached in memory per process — a changed file takes effect on the next Pi session.
|
||||
|
||||
---
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pi install npm:pi-web-access
|
||||
```
|
||||
|
||||
## Search Providers
|
||||
|
||||
Provider chain (in priority order, v0.22):
|
||||
|
||||
1. **SearXNG** (if configured) — Self-hosted, private search
|
||||
2. **OpenAI** — Codex subscription or API key
|
||||
3. **Exa** — Zero-config via MCP, or API key
|
||||
4. **Brave** — API key
|
||||
5. **Parallel** — API key
|
||||
6. **TinyFish** — API key
|
||||
7. **Search1API** — API key
|
||||
8. **Searchinfinity** — API key
|
||||
9. **Querit** — API key
|
||||
10. **Tavily** — API key
|
||||
11. **Jina** — API key
|
||||
12. **SERPdive** — API key
|
||||
13. **Kagi** — API key
|
||||
14. **Bocha** — API key
|
||||
15. **Ollama** — API key
|
||||
16. **Perplexity** — API key
|
||||
17. **Gemini API** — API key
|
||||
18. **Gemini Web** — Browser-cookie access
|
||||
|
||||
A single-provider field (`provider` or `searchProvider`) pins the default and takes precedence over `searchRouting`. `searchRouting.providers` plus `fallbackOn` define an explicit ordered fallback over typed failures (`transient`, `quota`, `network`, `invalid-response`).
|
||||
|
||||
## Configuration
|
||||
|
||||
**Location:** `~/.pi/web-search.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"searxngBaseUrl": "http://192.168.0.143:8081",
|
||||
"searchProvider": "searxng",
|
||||
"maxInlineContentChars": 50000,
|
||||
"workflow": "none",
|
||||
"ssrf": {
|
||||
"allowRanges": ["192.168.0.0/24"]
|
||||
},
|
||||
"openaiApiKey": "sk-...",
|
||||
"braveApiKey": "BSA_...",
|
||||
"exaApiKey": "exa-...",
|
||||
"perplexityApiKey": "pplx-...",
|
||||
"geminiApiKey": "AIza..."
|
||||
}
|
||||
```
|
||||
|
||||
Key fields:
|
||||
|
||||
- `searxngBaseUrl` — the SearXNG instance to call. Env `SEARXNG_BASE_URL` wins over this file. The client calls `GET {base}/search?q=...&format=json` with a 30 s timeout; the base URL and its redirects stay subject to the SSRF guard.
|
||||
- `searchProvider` — `searxng` locks the primary provider. `auto` picks the first available. A single-provider field wins over `searchRouting`.
|
||||
- `maxInlineContentChars` — size of each `fetch_content` / `get_search_content` content slice. Default 30000, cap 200000. Full fetched content stays stored for later retrieval.
|
||||
- `ssrf.allowRanges` — LAN CIDR ranges allowed through `fetch_content`. This blocks private IPs by default.
|
||||
- `workflow` — `none` (raw results, no browser), `summary-review` (curator window with summary draft), or `auto-summary`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### Web Search
|
||||
|
||||
```typescript
|
||||
web_search({ query: "TypeScript best practices 2025" })
|
||||
```
|
||||
|
||||
### URL Fetching
|
||||
|
||||
```typescript
|
||||
fetch_content({ url: "https://docs.example.com/guide" })
|
||||
```
|
||||
|
||||
### GitHub Cloning
|
||||
|
||||
GitHub URLs are cloned locally. The agent gets real file contents, not rendered HTML.
|
||||
|
||||
```typescript
|
||||
fetch_content({ url: "https://github.com/owner/repo" })
|
||||
```
|
||||
|
||||
### Video Understanding
|
||||
|
||||
Point at a YouTube video or local screen recording and ask questions about visual content.
|
||||
|
||||
```typescript
|
||||
// YouTube
|
||||
fetch_content({ url: "https://youtube.com/watch?v=...", prompt: "What book is shown?" })
|
||||
|
||||
// Local video
|
||||
fetch_content({ url: "/path/to/recording.mp4" })
|
||||
```
|
||||
|
||||
### PDF Extraction
|
||||
|
||||
```typescript
|
||||
fetch_content({ url: "https://example.com/paper.pdf" })
|
||||
```
|
||||
|
||||
## Optional Dependencies
|
||||
|
||||
```bash
|
||||
# Video frame extraction
|
||||
sudo pacman -S ffmpeg yt-dlp
|
||||
```
|
||||
|
||||
Without these, video analysis (transcripts, visual descriptions via Gemini) still works. Frame extraction requires ffmpeg and yt-dlp. Both are installed on dankware (verified 2026-08-28: ffmpeg n9.0.1, yt-dlp 2026.08.19).
|
||||
|
||||
GitHub URLs get special handling: `fetch_content` clones the repo locally instead of scraping HTML (root URL returns tree + README, `/blob/` returns file contents). Repos over 350 MB get an API-based view; `forceClone: true` overrides. Clones cache per session under `/tmp/pi-github-repos` and wipe on session change. Private repos need the `gh` CLI. Disable with `githubClone.enabled: false`.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Pi Packages](index.md) — Package overview
|
||||
- [Pi Configuration](../index.md) — Pi configuration
|
||||
Reference in new issue
Block a user