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
@@ -0,0 +1,196 @@
|
||||
---
|
||||
type: reference
|
||||
title: AGENTS.md Format Specification
|
||||
description: Canonical structure and conventions for the system-level instruction file that governs agent behavior during configuration sessions.
|
||||
tags:
|
||||
- agents-md
|
||||
- configuration
|
||||
- progressive-disclosure
|
||||
- core-contract
|
||||
- unverified
|
||||
timestamp: 2026-01-15
|
||||
---
|
||||
|
||||
# AGENTS.md Format Specification
|
||||
|
||||
This document defines the canonical structure and conventions for the `AGENTS.md` file located at `/home/dank/.pi/AGENTS.md`. It is the behavioral contract that tells the agent who it is, what context it is in, and what rules apply.
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
`AGENTS.md` is a **progressive disclosure instruction file**. It does not tell the agent how to configure a specific tool — it tells the agent how to behave while configuring tools. Think of it as the difference between a recipe and a cookbook. The recipe tells you what to do with eggplant. The cookbook tells you how to think about cooking.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
The file follows a strict top-to-bottom structure:
|
||||
|
||||
```
|
||||
# Title — Context Label
|
||||
## Context Declaration
|
||||
## Your Role: Persona
|
||||
## Progressive Disclosure (header)
|
||||
---
|
||||
### Layer N: <Title>
|
||||
<Content>
|
||||
---
|
||||
### Layer N+1: <Title>
|
||||
<Content>
|
||||
---
|
||||
## Summary
|
||||
```
|
||||
|
||||
### Section Order (Mandatory)
|
||||
|
||||
| Order | Section | Description |
|
||||
|-------|---------|-------------|
|
||||
| 1 | `# Title — Context Label` | One-line title with context label in em-dash. Example: `AGENTS.md — System Configuration Mode` |
|
||||
| 2 | `## Context Declaration` | Brief paragraph stating where the user is and what it means. Must mention the directory path. |
|
||||
| 3 | `## Your Role: <Persona>` | Persona definition with bullet-point traits. Keep it tight — 4-6 bullets max. |
|
||||
| 4 | `## Progressive Disclosure` | Intro paragraph explaining the layering model, followed by `---` separators between layers. |
|
||||
| 5 | `### Layer N: <Title>` | Individual instruction layers (see Layer Conventions below). |
|
||||
| 6 | `## Summary` | Compact table of all layers as quick-reference rows. |
|
||||
|
||||
---
|
||||
|
||||
## Layer Conventions
|
||||
|
||||
### Naming
|
||||
|
||||
- Layers are numbered sequentially starting from 1.
|
||||
- Use decimal sub-numbers for inserted layers (for example, `Layer 1.5`) to preserve ordering when new layers are added between existing ones.
|
||||
- Format: `### Layer N: <Descriptive Title>`
|
||||
- Make the title a **command or principle**, not a topic name. Prefer:
|
||||
- `Verify Before You Commit — Deterministic Check First`
|
||||
- `The Mandatory Documentation Fetch Protocol`
|
||||
- NOT `Documentation`
|
||||
- NOT `Package Installation`
|
||||
|
||||
### Content Structure
|
||||
|
||||
Give each layer this content:
|
||||
|
||||
1. **Opening callout** (if the rule is critical): Bold `**This is non-negotiable.**` or `**MANDATORY:**` prefix.
|
||||
2. **Definition**: What the rule/concept is. One paragraph, plain English.
|
||||
3. **Workflow or steps**: Numbered lists for procedural instructions.
|
||||
4. **Examples**: Code blocks, commands, or concrete scenarios.
|
||||
5. **Scope**: When the rule applies (and when it does not).
|
||||
6. **Common mistakes** (optional): `❌` prefixed anti-patterns.
|
||||
7. **Correct behavior** (optional): `✅` prefixed patterns.
|
||||
|
||||
### Layer Ordering Principle
|
||||
|
||||
Layers are ordered by **priority and dependency**, not alphabetical:
|
||||
|
||||
1. **Context layers** first (who you are, where you are)
|
||||
2. **Pre-flight / safety layers** next (verification, documentation checks)
|
||||
3. **Domain-specific layers** after that (tool rules, package rules, etc.)
|
||||
4. **Emergency / fallback layers** last
|
||||
|
||||
A layer that gates another layer must come before the layer it gates. (for example, "check docs exist" comes before "fetch docs if missing".)
|
||||
|
||||
---
|
||||
|
||||
## Summary Table Conventions
|
||||
|
||||
The `## Summary` section at the bottom is a **quick-reference table** that maps each layer to its action.
|
||||
|
||||
### Format
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
|
||||
| Context | Action |
|
||||
|---------|--------|
|
||||
| <Short layer title> | **<One-line action>** — <Optional detail>. |
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- Every layer must have exactly one row in the summary.
|
||||
- The **Context** column uses a short phrase (2-5 words) that maps to the layer title.
|
||||
- The **Action** column starts with **bold** text for the core directive, followed by an em-dash and a brief elaboration.
|
||||
- Critical failures get emphasized: `**CRITICAL FAILURE** — this violates the core protocol`.
|
||||
- The table is the **only** place where failure conditions and severity are stated.
|
||||
- Rows are ordered to match layer numbering.
|
||||
|
||||
---
|
||||
|
||||
## Section Formatting
|
||||
|
||||
### Code Blocks
|
||||
|
||||
- Use triple backtick code blocks for commands, scripts, and configuration examples.
|
||||
- Specify the language for syntax highlighting: ````bash`, ````json`, ````text`.
|
||||
- Include inline comments in code blocks explaining what is right vs. wrong.
|
||||
- Use `# CORRECT` and `# WRONG` comment labels for contrast examples.
|
||||
|
||||
### Lists
|
||||
|
||||
- Use **numbered lists** for sequential steps (workflows, protocols).
|
||||
- Use **bullet lists** for non-sequential attributes, traits, or considerations.
|
||||
- Use `❌` and `✅` prefixed bullets for anti-patterns vs. correct patterns.
|
||||
|
||||
### Emphasis
|
||||
|
||||
- Use `**bold**` for critical directives and failure conditions.
|
||||
- Use `**bold**` in the Summary table for the core action phrase.
|
||||
- Use backticks for file paths, commands, and config keys.
|
||||
- Use `>` blockquotes sparingly — reserved for ASCII workflow diagrams.
|
||||
|
||||
### ASCII Workflow Diagrams
|
||||
|
||||
For critical decision flows, use ASCII art inside blockquotes:
|
||||
|
||||
```
|
||||
User Request → Check index.md → Docs exist? → YES: Proceed
|
||||
↓
|
||||
NO: STOP → Fetch → Verify → Proceed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding New Layers
|
||||
|
||||
When adding a new behavioral rule:
|
||||
|
||||
1. **Determine placement**: Where does this layer fit in the priority/dependency order?
|
||||
2. **Assign a number**: If inserting between existing layers, use a decimal (for example, `Layer 2.5`). If appending, use the next integer.
|
||||
3. **Write the layer** following the Content Structure conventions above.
|
||||
4. **Add a summary row**: Insert a matching row in the Summary table at the correct position.
|
||||
5. **Verify ordering**: Ensure the layer order matches the dependency chain (gating layers before gated layers).
|
||||
|
||||
---
|
||||
|
||||
## What NOT to Include
|
||||
|
||||
| Do Not | Why |
|
||||
|--------|-----|
|
||||
| Tool-specific configuration syntax | That belongs in `/docs/tools/<tool-name>/` |
|
||||
| Long reference tables | Keep the Summary table concise; details belong in layer content |
|
||||
| More than 10 layers | If you need more, the file is too big — consider splitting or consolidating |
|
||||
| Narrative prose | Make every sentence actionable or declarative |
|
||||
| Personal opinions or preferences | This is a system contract, not a blog post |
|
||||
|
||||
---
|
||||
|
||||
## File Metadata
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Path | `/home/dank/.pi/AGENTS.md` |
|
||||
| Format | Markdown (GitHub Flavored) |
|
||||
| Max layers | 10 (soft limit) |
|
||||
| Max file size | ~15 KB (soft limit — if larger, consolidate) |
|
||||
| Encoding | UTF-8 |
|
||||
| Line endings | Unix (LF) |
|
||||
|
||||
---
|
||||
|
||||
## Revision History
|
||||
|
||||
| Version | Date | Change |
|
||||
|---------|------|--------|
|
||||
| 1.0 | 2026-07-09 | Initial specification — defines structure, layer conventions, summary format, and add/remove procedures |
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
type: reference
|
||||
title: AGENTS.md Index
|
||||
description: Overview of the cached tool documentation system — how it works, why the pre-flight check matters, and how to add new entries.
|
||||
tags:
|
||||
- documentation
|
||||
- index
|
||||
- pre-flight-check
|
||||
- meta
|
||||
timestamp: 2026-01-15
|
||||
---
|
||||
|
||||
# pi Documentation Index
|
||||
|
||||
This directory (`/home/dank/.pi/agent/docs/`) contains cached documentation for tools used during system configuration. It is the agent's primary reference before touching any configuration file.
|
||||
|
||||
---
|
||||
|
||||
## How to Use
|
||||
|
||||
Before configuring any tool, check whether documentation already exists here. If it does not, a subagent **must** be spawned to fetch documentation before proceeding.
|
||||
|
||||
This is not a suggestion. It is the difference between "I remember how to configure this" and "I will need to re-read the docs for the third time this week."
|
||||
|
||||
---
|
||||
|
||||
## Available Tool Documentation
|
||||
|
||||
### Core
|
||||
|
||||
* [AGENTS.md Format](agents-md-format.md) — Structure specification for the system-level instruction file: layer conventions, naming, summary table format, and add/remove procedures.
|
||||
|
||||
### Tools
|
||||
|
||||
* [Ghostty Terminal](../tools/ghostty/index.md) — GPU-accelerated terminal emulator. Complete configuration reference with 100+ options organized by category, CLI actions, keybindings, shaders, and default bindings.
|
||||
* [llama.cpp Server](../tools/llama-cpp/index.md) — LLM inference server. GGUF format, build guides (CPU/CUDA/Metal/Vulkan), server CLI options, API endpoints, Docker setup, and curl examples.
|
||||
* [Linux Power Management](../tools/linux-power-management.md) — Systemd sleep configuration, kernel sleep states, NVIDIA GPU suspend/resume, diagnostic tools, kernel parameters, and automated testing procedures.
|
||||
* [Niri](../tools/niri/index.md) — Scrollable-tiling Wayland compositor. Full keybind cheat sheet, configuration syntax, window management, workspace navigation, and action reference.
|
||||
|
||||
### Pi Packages
|
||||
|
||||
* [pi-browser-use](../packages/pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with `browser_` prefix, full config reference, session modes, vision model setup, and tool augmentation docs.
|
||||
* [pi-permission-system](../packages/pi-permission-system.md) — 10 docs covering permission enforcement, config reference, session approvals, cross-extension API, subagent integration, troubleshooting, and migration guides.
|
||||
|
||||
### Skills
|
||||
|
||||
* [Npx Skills](../skills/npx-skills.md) — Distribution and installation patterns for agent skills via npm, package structure, SKILL.md frontmatter, discovery rules, and the Agent Skills specification.
|
||||
* [Vercel Labs `skills` CLI](../skills/vercel-skills.md) — CLI meta-installer for cross-agent skill distribution, supporting 68+ agents, with add/use/find/list/update/remove commands.
|
||||
|
||||
### References
|
||||
|
||||
* [OKF v0.1 Specification](../references/okf-spec.md) — Complete specification for OKF knowledge bundles: bundle structure, frontmatter fields, concept documents, index/log files, cross-linking, and conformance rules.
|
||||
* [OKF Bundle Maintenance](../references/okf-maintenance.md) — Bundle maintenance: log.md format, frontmatter discipline, one-concept-per-file, staleness detection, and automation strategies.
|
||||
|
||||
---
|
||||
|
||||
## Adding New Tool Documentation
|
||||
|
||||
When a subagent fetches documentation for a new tool:
|
||||
|
||||
1. Save it to `tools/<tool-name>/index.md` (multi-file) or `tools/<tool-name>.md` (small, single-concept).
|
||||
2. Add an entry to this index table.
|
||||
3. Include a brief description of what the document covers.
|
||||
4. Add YAML frontmatter with `type` and `description`.
|
||||
5. Update `log.md` with the change.
|
||||
|
||||
---
|
||||
|
||||
## Index Format
|
||||
|
||||
Give each row this content:
|
||||
|
||||
- **Tool** — the tool or technology name
|
||||
- **File / Path** — relative path within this directory
|
||||
- **Status** — for example, "Complete", "Partial", "Needs Update"
|
||||
@@ -0,0 +1,13 @@
|
||||
# Core Documentation
|
||||
|
||||
These files define the structural conventions that govern the pi agent system itself. They are the grammar rules — boring until you break them, then devastating.
|
||||
|
||||
## Concept Files
|
||||
|
||||
* [AGENTS.md Format Specification](agents-md-format.md) — Canonical structure and conventions for the system-level instruction file that governs agent behavior.
|
||||
* [AGENTS.md Index](index-doc.md) — Overview of the cached tool documentation system and how to add new entries.
|
||||
* [Pi Settings System](settings.md) — Current system configuration: providers, models, packages, subagent overrides, and runtime options.
|
||||
|
||||
## Change Tracking
|
||||
|
||||
* [Bundle Change Log](log.md) — Chronological update history.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
type: changelog
|
||||
title: Core Bundle Change Log
|
||||
description: Change log for the core documentation directory — tracks migrations and structural changes.
|
||||
tags:
|
||||
- core
|
||||
- changelog
|
||||
- okf
|
||||
timestamp: 2026-07-18
|
||||
---
|
||||
|
||||
# Core Bundle Change Log
|
||||
|
||||
## 2026-07-18
|
||||
- **Migration**: Converted `index.md` (root) to `core/index-doc.md` — moved root bundle index into core domain
|
||||
- **Migration**: Converted `agents-md-format.md` (root) to `core/agents-md-format.md` — agents-md format belongs in core
|
||||
- **Creation**: Established `core/` directory with `index.md` as the domain entry point
|
||||
- **Creation**: This change log for tracking core directory modifications
|
||||
|
||||
## 2026-07-15
|
||||
- **Initialization**: OKF v0.1 conversion of the entire docs bundle — frontmatter applied, structure established, first `log.md` entries created
|
||||
@@ -0,0 +1,240 @@
|
||||
---
|
||||
type: reference
|
||||
title: Pi Settings System (settings.json)
|
||||
description: Complete reference for pi's main configuration file — providers, models, packages, subagent overrides, and runtime options.
|
||||
tags:
|
||||
- settings
|
||||
- configuration
|
||||
- json
|
||||
- providers
|
||||
- models
|
||||
- subagents
|
||||
verified: 2026-08-28
|
||||
timestamp: 2026-08-28
|
||||
---
|
||||
|
||||
# pi Settings System (`settings.json`)
|
||||
|
||||
`settings.json` is pi's main configuration file. It determines which models the agent talks to, which packages load, how subagents behave, and general runtime preferences.
|
||||
|
||||
**Location:** `/home/dank/.pi/agent/settings.json`
|
||||
|
||||
**Format:** JSON.
|
||||
|
||||
---
|
||||
|
||||
## Current Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"lastChangelogVersion": "0.84.3",
|
||||
"theme": "dark",
|
||||
"defaultProvider": "llamacpp (dankclaw)",
|
||||
"defaultModel": "frank-default-large",
|
||||
"defaultThinkingLevel": "medium",
|
||||
"hideThinkingBlock": false,
|
||||
"subagents": {
|
||||
"defaultModel": "frank-default-small",
|
||||
"defaultThinking": "max",
|
||||
"agentOverrides": {
|
||||
"scout": { "model": "frank-default-small" },
|
||||
"researcher": { "model": "frank-default-small" },
|
||||
"planner": { "model": "frank-default-large" },
|
||||
"worker": { "model": "frank-default-large" },
|
||||
"reviewer": { "model": "frank-default-large" },
|
||||
"oracle": { "model": "frank-default-large" },
|
||||
"context-builder": { "model": "frank-default-large" }
|
||||
},
|
||||
"watchdog": { "enabled": true }
|
||||
},
|
||||
"packages": [
|
||||
"npm:@wierdbytes/pi-peon",
|
||||
"npm:pi-web-access",
|
||||
"npm:@narumitw/pi-worktree",
|
||||
"npm:@juicesharp/rpiv-todo",
|
||||
"npm:@juicesharp/rpiv-ask-user-question",
|
||||
"npm:@ff-labs/pi-fff",
|
||||
"npm:pi-intercom",
|
||||
"npm:@juicesharp/rpiv-btw",
|
||||
"npm:@xynogen/pix-pretty",
|
||||
"npm:@xynogen/pix-bash",
|
||||
"npm:@xynogen/pix-ssh",
|
||||
"npm:@xynogen/pix-write",
|
||||
"npm:@xynogen/pix-sudo",
|
||||
"npm:@xynogen/pix-read",
|
||||
"npm:@xynogen/pix-ls",
|
||||
"npm:@xynogen/pix-edit"
|
||||
],
|
||||
"enableSkillCommands": true,
|
||||
"autocompleteMaxVisible": 10,
|
||||
"terminal": { "showTerminalProgress": true },
|
||||
"steeringMode": "one-at-a-time",
|
||||
"transport": "auto",
|
||||
"httpIdleTimeoutMs": 0,
|
||||
"retry": {
|
||||
"enabled": true,
|
||||
"maxRetries": 3,
|
||||
"baseDelayMs": 10000
|
||||
},
|
||||
"markdown": { "mermaid": "streaming" },
|
||||
"fullscreenScrollbar": "always",
|
||||
"tuiMode": "fullscreen",
|
||||
"warnings": { "anthropicExtraUsage": false },
|
||||
"treeFilterMode": "default",
|
||||
"doubleEscapeAction": "none",
|
||||
"enabledModels": [
|
||||
"llamacpp (dankserver)/frank-default-small",
|
||||
"llamacpp (dankclaw)/frank-default-large",
|
||||
"openrouter/~deepseek/deepseek-v4-flash-latest",
|
||||
"openrouter/openai/gpt-5.6-luna"
|
||||
],
|
||||
"outputPad": 1,
|
||||
"editorPaddingX": 0,
|
||||
"modelThinkingLevels": {
|
||||
"llamacpp (dankclaw)/frank-default-large": "medium",
|
||||
"llamacpp (dankserver)/frank-default-small": "medium"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Top-Level Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `lastChangelogVersion` | string | No | Schema version. Incremented on schema changes. Mismatch triggers a migration prompt. |
|
||||
| `theme` | string | No | UI theme. Values: `"dark"`, `"light"`. |
|
||||
| `defaultProvider` | string | **Yes** | Provider name from `models.json`. Pi will not start without a valid provider. |
|
||||
| `defaultModel` | string | **Yes** | Model ID within the default provider. Must match an `id` in `models.json`. |
|
||||
| `defaultThinkingLevel` | string | No | Default reasoning depth: `"off"`, `"low"`, `"medium"`, `"high"`, `"max"`. |
|
||||
| `hideThinkingBlock` | boolean | No | If `true`, the agent's chain-of-thought is hidden in the TUI. |
|
||||
| `packages` | string[] | No | Installed pi packages. Format: `npm:<package-name>`. |
|
||||
| `subagents` | object | No | Subagent configuration. Controls model selection per agent role. |
|
||||
| `enableSkillCommands` | boolean | No | Enable skill command triggers. |
|
||||
| `autocompleteMaxVisible` | number | No | Max visible autocomplete suggestions. |
|
||||
| `terminal` | object | No | Terminal display options. |
|
||||
| `steeringMode` | string | No | Agent steering mode (e.g. `"one-at-a-time"`). |
|
||||
| `transport` | string | No | Transport protocol (`"auto"`, etc.). |
|
||||
| `httpIdleTimeoutMs` | number | No | HTTP idle timeout in milliseconds. |
|
||||
| `retry` | object | No | Retry configuration with backoff. |
|
||||
| `markdown` | object | No | Markdown rendering options (e.g. mermaid mode). |
|
||||
| `fullscreenScrollbar` | string | No | Scrollbar visibility mode. |
|
||||
| `tuiMode` | string | No | TUI display mode. |
|
||||
| `warnings` | object | No | Warning suppression settings. |
|
||||
| `treeFilterMode` | string | No | File tree filtering mode. |
|
||||
| `doubleEscapeAction` | string | No | Double-escape key action. |
|
||||
| `enabledModels` | string[] | No | List of all available model IDs for switching. |
|
||||
| `outputPad` | number | No | Output padding. |
|
||||
| `editorPaddingX` | number | No | Editor X padding. |
|
||||
| `modelThinkingLevels` | object | No | Per-model thinking level overrides. |
|
||||
|
||||
---
|
||||
|
||||
## Subagent Configuration
|
||||
|
||||
The `subagents` block controls which models subagents use and how they reason.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `defaultModel` | string | Fallback model for subagents without an explicit override. |
|
||||
| `defaultThinking` | string | Default reasoning depth for subagents. |
|
||||
| `agentOverrides` | object | Per-role model assignments. Keys are agent roles. |
|
||||
| `watchdog.enabled` | boolean | Enable the watchdog system that monitors subagent health. |
|
||||
|
||||
### Agent Roles and Model Assignments
|
||||
|
||||
| Role | Model | Purpose |
|
||||
|------|-------|---------|
|
||||
| `scout` | `frank-default-small` | Quick exploration tasks |
|
||||
| `researcher` | `frank-default-small` | Web research and information gathering |
|
||||
| `planner` | `frank-default-large` | Task planning and decomposition |
|
||||
| `worker` | `frank-default-large` | Heavy implementation work |
|
||||
| `reviewer` | `frank-default-large` | Code and document review |
|
||||
| `oracle` | `frank-default-large` | Complex reasoning and analysis |
|
||||
| `context-builder` | `frank-default-large` | Building context for other agents |
|
||||
|
||||
---
|
||||
|
||||
## Retry
|
||||
|
||||
Automatic agent-level retries use exponential backoff. The current configuration allows three retries with delays of **10 seconds, 20 seconds, and 40 seconds**.
|
||||
|
||||
```json
|
||||
{
|
||||
"retry": {
|
||||
"enabled": true,
|
||||
"maxRetries": 3,
|
||||
"baseDelayMs": 10000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provider Configuration
|
||||
|
||||
**Location:** `~/.pi/agent/models.json`
|
||||
|
||||
Providers define where pi gets its LLM. The default provider is specified in `settings.json` and the provider definitions live in `models.json`.
|
||||
|
||||
Currently configured providers:
|
||||
|
||||
| Provider | Base URL | Model | GPU |
|
||||
|----------|----------|-------|-----|
|
||||
| `llamacpp (dankserver)` | `http://192.168.0.235:7770/v1` | `frank-default-small` (Qwen3.6-35B-A3B FP8, moe-cache 2048) | RTX 3090 |
|
||||
| `llamacpp (dankclaw)` | `http://192.168.0.143:7770/v1` | `frank-default-large` (Qwen3.8-Flash-Next Q4_0 ROCmFP4 Strix) | RTX 4070 Max-Q |
|
||||
|
||||
See [[models|models]] for the complete `models.json` reference.
|
||||
|
||||
---
|
||||
|
||||
## Package Configuration
|
||||
|
||||
**Location:** `~/.pi/agent/settings.json` (via `packages` array) + `~/.pi/agent/npm/` (on-disk)
|
||||
|
||||
Each package entry is a specifier string. The format is `npm:<package-name>`. When pi starts, it:
|
||||
|
||||
1. Reads the `packages` array from `settings.json`
|
||||
2. Checks `~/.pi/agent/npm/node_modules/<name>/` for each package
|
||||
3. Loads extensions, skills, prompts, and themes from each package
|
||||
|
||||
Currently installed:
|
||||
|
||||
| Package | Version | Description |
|
||||
|---------|---------|-------------|
|
||||
| `@wierdbytes/pi-peon` | 0.1.1 | CESP/OpenPeon sound-pack player for pi lifecycle events |
|
||||
| `pi-web-access` | 0.22.0 | Web search, URL fetching, GitHub cloning, PDF extraction, YouTube understanding |
|
||||
| `@narumitw/pi-worktree` | 0.51.6 | Worktree management for git-based parallel development |
|
||||
| `@juicesharp/rpiv-todo` | 2.7.1 | Todo/task management package |
|
||||
| `@juicesharp/rpiv-ask-user-question` | 2.7.1 | Interactive user question prompts |
|
||||
| `@ff-labs/pi-fff` | 0.10.5 | File/flow functions |
|
||||
| `pi-intercom` | 0.12.0 | Inter-process communication |
|
||||
| `@juicesharp/rpiv-btw` | 2.7.1 | Between-task utilities |
|
||||
| `@xynogen/pix-pretty` | 1.18.1 | Code formatting |
|
||||
| `@xynogen/pix-bash` | 0.2.1 | Bash shell utilities |
|
||||
| `@xynogen/pix-ssh` | 0.2.6 | SSH management |
|
||||
| `@xynogen/pix-write` | 0.2.1 | File writing utilities |
|
||||
| `@xynogen/pix-sudo` | 0.3.20 | Privileged operations |
|
||||
| `@xynogen/pix-read` | 0.2.1 | File reading utilities |
|
||||
| `@xynogen/pix-ls` | 0.2.1 | Directory listing |
|
||||
| `@xynogen/pix-edit` | 0.2.1 | File editing utilities |
|
||||
|
||||
See [packages](../packages/index.md) for full package documentation.
|
||||
|
||||
---
|
||||
|
||||
## Migration
|
||||
|
||||
When `lastChangelogVersion` is behind pi's internal version, pi prompts for migration. The migration updates the JSON structure while preserving values. Back up before migrating.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [pi](../pi/index.md) — Pi configuration overview
|
||||
- [[models|models]] — Provider and model definitions
|
||||
- [packages](../packages/index.md) — Installed package documentation
|
||||
- [[skills|skills]] — Installed skill documentation
|
||||
Reference in New Issue
Block a user