docs(coding-agent): update README intro, add packages/prompt-templates/themes docs

- Rewrote README intro to emphasize extensibility and pi packages
- Added Pi Packages section to README
- Created docs/packages.md covering install, sources, manifest, filtering
- Created docs/prompt-templates.md covering format and arguments
- Created docs/themes.md with overview linking to theme.md

packages/coding-agent/README.md

@@ -9,9 +9,11 @@
   <a href="https://github.com/badlogic/pi-mono/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/badlogic/pi-mono/ci.yml?style=flat-square&branch=main" /></a>
 </p>
 
-A terminal-based coding agent with multi-model support, mid-session model switching, and a simple CLI for headless coding tasks.
+Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Pi Packages](#pi-packages) and share them with others via npm or git.
 
-Works on Linux, macOS, and Windows (requires bash; see [Windows Setup](#windows-setup)). [Separately maintained port](https://github.com/VaclavSynacek/pi-coding-agent-termux) works on Termux/Android.
+Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow.
+
+Pi runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps. See [clawdbot/clawdbot](https://github.com/clawdbot/clawdbot) for a real-world SDK integration.
 
 ## Table of Contents
 
@@ -42,6 +44,7 @@ Works on Linux, macOS, and Windows (requires bash; see [Windows Setup](#windows-
   - [Prompt Templates](#prompt-templates)
   - [Skills](#skills)
   - [Extensions](#extensions)
+  - [Pi Packages](#pi-packages)
 - [CLI Reference](#cli-reference)
 - [Tools](#tools)
 - [Programmatic Usage](#programmatic-usage)
@@ -1283,6 +1286,12 @@ await ctx.ui.custom((tui, theme, done) => ({
 > See [docs/tui.md](docs/tui.md) for TUI components and custom rendering.
 > See [examples/extensions/](examples/extensions/) for working examples.
 
+### Pi Packages
+
+Pi packages bundle extensions, skills, prompt templates, and themes for sharing through npm or git. A package can declare resources in `package.json` under the `pi` key, or use the conventional `extensions/`, `skills/`, `prompts/`, and `themes/` directories. Install packages with `pi install` and manage them in the `packages` settings array.
+
+See [docs/packages.md](docs/packages.md) for package structure, filtering, and install behavior.
+
 ---
 
 ## CLI Reference

packages/coding-agent/docs/packages.md

@@ -0,0 +1,158 @@
+> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
+
+# Pi Packages
+
+Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories.
+
+## Table of Contents
+
+- [Install and Manage](#install-and-manage)
+- [Package Sources](#package-sources)
+- [Creating a Pi Package](#creating-a-pi-package)
+- [Package Structure](#package-structure)
+- [Package Filtering](#package-filtering)
+- [Enable and Disable Resources](#enable-and-disable-resources)
+- [Scope and Deduplication](#scope-and-deduplication)
+
+## Install and Manage
+
+```bash
+pi install npm:@foo/bar@1.0.0
+pi install git:github.com/user/repo@v1
+pi install https://github.com/user/repo  # raw URLs work too
+
+pi remove npm:@foo/bar
+pi list    # show installed packages from settings
+pi update  # update all non-pinned packages
+```
+
+By default, `install` and `remove` write to global settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup.
+
+To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
+
+```bash
+pi -e npm:@foo/bar
+pi -e git:github.com/user/repo
+```
+
+## Package Sources
+
+Pi accepts three source types in settings and `pi install`.
+
+### npm
+
+```
+npm:@scope/pkg@1.2.3
+npm:pkg
+```
+
+- Versioned specs are pinned and skipped by `pi update`.
+- Global installs use `npm install -g`.
+- Project installs go under `.pi/npm/`.
+
+### git
+
+```
+git:github.com/user/repo@v1
+https://github.com/user/repo@v1
+```
+
+- Raw `https://` URLs work without the `git:` prefix.
+- Refs pin the package and skip `pi update`.
+- Cloned to `~/.pi/agent/git/<host>/<path>` (global) or `.pi/git/<host>/<path>` (project).
+- Runs `npm install` after clone or pull if `package.json` exists.
+
+### Local Paths
+
+```
+/absolute/path/to/package
+./relative/path/to/package
+```
+
+Local paths work in settings but not with `pi install`. If the path is a file, it loads as a single extension. If it is a directory, pi loads resources using package rules.
+
+## Creating a Pi Package
+
+Add a `pi` manifest to `package.json` or use conventional directories. Include the `pi-package` keyword for discoverability.
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
+}
+```
+
+Paths are relative to the package root. Arrays support glob patterns and `!exclusions`.
+
+## Package Structure
+
+### Convention Directories
+
+If no `pi` manifest is present, pi auto-discovers resources from these directories:
+
+- `extensions/` loads `.ts` and `.js` files
+- `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
+- `prompts/` loads `.md` files
+- `themes/` loads `.json` files
+
+### Bundling Other Pi Packages
+
+Bundle other pi packages by adding them as dependencies and listing them in `bundledDependencies`. Reference their resources via `node_modules/` paths.
+
+```json
+{
+  "dependencies": {
+    "shitty-extensions": "^1.0.1"
+  },
+  "bundledDependencies": ["shitty-extensions"],
+  "pi": {
+    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
+    "skills": ["skills", "node_modules/shitty-extensions/skills"]
+  }
+}
+```
+
+`bundledDependencies` embeds the package in the published tarball, keeping paths stable. See `pi-package-test` for a working example.
+
+## Package Filtering
+
+Filter what a package loads using the object form in settings:
+
+```json
+{
+  "packages": [
+    "npm:simple-pkg",
+    {
+      "source": "npm:my-package",
+      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
+      "skills": [],
+      "prompts": ["prompts/review.md"],
+      "themes": ["+themes/legacy.json"]
+    }
+  ]
+}
+```
+
+- Omit a key to load all of that type.
+- Use `[]` to load none of that type.
+- `!pattern` excludes matches.
+- `+pattern` force-includes, even if excluded by manifest.
+- Filters layer on top of the manifest. They narrow down what is already allowed.
+
+## Enable and Disable Resources
+
+Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.
+
+## Scope and Deduplication
+
+Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:
+
+- npm: package name
+- git: repository URL without ref
+- local: resolved absolute path

packages/coding-agent/docs/prompt-templates.md

@@ -0,0 +1,57 @@
+> pi can create prompt templates. Ask it to build one for your workflow.
+
+# Prompt Templates
+
+Prompt templates are Markdown snippets that expand into full prompts when you type `/name` in the editor.
+
+## Locations
+
+Pi loads prompt templates from:
+
+- Global: `~/.pi/agent/prompts/*.md`
+- Project: `.pi/prompts/*.md`
+- Packages: `prompts/` directories or `pi.prompts` entries in `package.json`
+- Settings: `prompts` array with files or directories
+- CLI: `--prompt-template <path>` (repeatable)
+
+Disable discovery with `--no-prompt-templates`.
+
+## Format
+
+```markdown
+---
+description: Review staged git changes
+---
+Review the staged changes (`git diff --cached`). Focus on:
+- Bugs and logic errors
+- Security issues
+- Error handling gaps
+```
+
+- The filename becomes the command name. `review.md` becomes `/review`.
+- `description` is optional. If missing, the first non-empty line is used.
+
+## Arguments
+
+Templates support positional arguments and simple slicing:
+
+- `$1`, `$2`, ... positional args
+- `$@` or `$ARGUMENTS` for all args joined
+- `${@:N}` for args from the Nth position (1-indexed)
+- `${@:N:L}` for `L` args starting at N
+
+Example:
+
+```markdown
+---
+description: Create a component
+---
+Create a React component named $1 with features: $@
+```
+
+Usage: `/component Button "onClick handler" "disabled support"`
+
+## Loading Rules
+
+- Template discovery in `prompts/` is non-recursive.
+- If you want templates in subdirectories, add them explicitly via `prompts` settings or a package manifest.

packages/coding-agent/docs/themes.md

@@ -0,0 +1,46 @@
+> pi can create themes. Ask it to build one for your setup.
+
+# Themes
+
+Themes are JSON files that define colors for the TUI. You can select themes in `/settings` or via `settings.json`.
+
+## Locations
+
+Pi loads themes from:
+
+- Built-in: `dark`, `light`
+- Global: `~/.pi/agent/themes/*.json`
+- Project: `.pi/themes/*.json`
+- Packages: `themes/` directories or `pi.themes` entries in `package.json`
+- Settings: `themes` array with files or directories
+- CLI: `--theme <path>` (repeatable)
+
+Disable discovery with `--no-themes`.
+
+## Format
+
+Themes use this structure:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/theme-schema.json",
+  "name": "my-theme",
+  "vars": {
+    "accent": "#00aaff",
+    "muted": 242
+  },
+  "colors": {
+    "accent": "accent",
+    "muted": "muted",
+    "text": "",
+    "userMessageBg": "#2d2d30",
+    "toolSuccessBg": "#1e2e1e"
+  }
+}
+```
+
+- `name` is required and must be unique.
+- `vars` is optional. It lets you reuse colors.
+- `colors` must define all required tokens.
+
+See [theme.md](theme.md) for the full token list, color formats, and validation details.