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.
2026-08-28 07:57:13 -07:00
parent 552d1ef8bf
commit 02883d3ed2
116 changed files with 13008 additions and 0 deletions
@@ -0,0 +1,15 @@
+# Pi Packages
+
+Self-contained extensions and tools bundled as npm packages, distributed via the `pi install` system. Each package contains extensions, skills, prompts, or themes.
+
+---
+
+## Concept Files
+
+* [pi-browser-use](pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with `browser_` prefix, full config reference, session modes, and vision model setup.
+* [pi-permission-system](pi-permission-system.md) — Permission enforcement and policy configuration system with 10 interconnected docs.
+
+## Cross-References
+
+- All packages are installed via `pi install npm:<name>` and loaded by pi's extension system.
+- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution mechanism and package.json manifest format.
@@ -0,0 +1,117 @@
+---
+type: reference
+title: Pi Browser Use
+description: Browser automation extension wrapping chrome-devtools-mcp with a browser_ prefix for pi-coding-agent.
+resource: https://github.com/TGYD-helige/pi
+tags:
+  - pi
+  - package
+  - browser
+  - chrome-devtools-mcp
+  - unverified
+timestamp: 2026-08-28
+---
+[pi-browser-use](https://github.com/TGYD-helige/pi) is a pi-coding-agent extension that wraps [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp), exposing all browser automation tools with a unified `browser_` prefix.
+
+**License:** Apache-2.0
+
+---
+
+## Features
+
+- **Dynamic tool discovery** — auto-proxies all upstream chrome-devtools-mcp tools with `browser_` prefix
+- **Tool description augmentation** — adds usage hints for key tools
+- **Result post-processing** — strips embedded snapshots, detects overlay/stale element issues
+- **Optional visual analysis** — `browser_analyze_screenshot` via configurable vision model
+- **Standalone mode** — runnable as independent MCP server via CLI
+
+### Requirements
+
+Node.js >= 20, Chrome (stable or newer), `@earendil-works/pi-coding-agent >= 0.74.0`.
+
+---
+
+## Installation
+
+```bash
+pi install npm:@amaster.ai/pi-browser-use
+```
+
+---
+
+## Usage
+
+### As pi-coding-agent Extension (Recommended)
+
+Auto-discovers and loads on `session_start`. Configure in `.pi/settings.json`:
+
+```json
+{
+  "pi-browser-use": {
+    "headless": true,
+    "channel": "stable",
+    "viewport": "1280x720",
+    "experimentalVision": true
+  }
+}
+```
+
+### As Standalone MCP Server
+
+```bash
+npx @amaster.ai/pi-browser-use --headless --viewport=1280x720
+```
+
+---
+
+## Configuration
+
+### Session Mode
+
+| Mode | Description |
+|------|-------------|
+| `persistent` (default) | Reuses shared profile at `~/.pi/browser-profile` |
+| `isolated` | Fresh ephemeral profile each session |
+| `existing` | Connects to running browser instance |
+
+### Browser Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `headless` | `boolean` | `false` | Run headless |
+| `channel` | `string` | — | Chrome channel: `canary`, `dev`, `beta`, `stable` |
+| `viewport` | `string` | — | Viewport size, for example `1280x720` |
+| `userDataDir` | `string` | — | Custom user data directory |
+
+### Vision Model
+
+```json
+{
+  "pi-browser-use": {
+    "visionModel": {
+      "provider": "openai",
+      "model": "gpt-4o"
+    }
+  }
+}
+```
+
+Resolves API key and base URL from the model registry automatically.
+
+---
+
+## Key Tools
+
+| Tool | Hint |
+|------|------|
+| `browser_click` | Use element uid from snapshot; UIDs invalidated after action |
+| `browser_fill` | Does not work on canvas/custom widgets |
+| `browser_press_key` | Accepts single key name only |
+| `browser_take_snapshot` | Call first to get uids, and after every state-changing action |
+
+---
+
+## Cross-References
+
+- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system.
+- See [OKF Specification](../references/okf-spec.md) for the knowledge bundle format.
@@ -0,0 +1,37 @@
+---
+type: reference
+title: Pi Permission System
+description: Permission enforcement and policy configuration system for pi-coding-agent extensions.
+resource: https://github.com/gotgenes/pi-permission-system
+tags:
+  - pi
+  - package
+  - permissions
+  - unverified
+timestamp: 2026-08-28
+---
+[pi-permission-system](https://github.com/gotgenes/pi-permission-system) is the permission enforcement and policy configuration system for pi-coding-agent extensions.
+
+---
+
+## Documentation Index
+
+| Document | File | Description |
+|----------|------|-------------|
+| Overview | README.md | Package overview, install, quick start, feature list |
+| Configuration | configuration.md | Full policy reference, runtime knobs, per-agent overrides, common recipes |
+| Session Approvals | session-approvals.md | Session-scoped rules, pattern suggestions, bash arity table |
+| Cross-Extension API | cross-extension-api.md | Service accessor, event bus, decision/UI-prompt broadcasts |
+| Subagent Integration | subagent-integration.md | Permission forwarding, coexistence with subagent extensions |
+| Frontmatter Convention | permission-frontmatter-for-subagent-extensions.md | Convention guide for subagent extension authors |
+| OpenCode Compatibility | opencode-compatibility.md | Shared concepts, divergences, porting guide |
+| Troubleshooting | troubleshooting.md | Common issues, diagnostic logging, threat model |
+| Migration: Legacy → Flat | legacy-to-flat.md | Migration from pre-v2 config layout |
+| Migration: Strict Validation | strict-config-validation.md | Strict config validation (breaking) — reading and fixing rejected configs |
+
+---
+
+## Cross-References
+
+- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system.
+- See [AGENTS.md Format](../core/agents-md-format.md) for the system-level instruction format that governs how this system is referenced in agent contracts.