@pikaa-ai/pikaa 0.3.1 → 0.3.5

package/skills/pi-agent/references/termux.md

@@ -1,31 +0,0 @@
-# Termux Setup
-
-Source: https://pi.dev/docs/latest/termux
-
-Pi runs on Android through Termux.
-
-## Prerequisites
-
-Install Termux from GitHub or F-Droid, not Google Play. Install Termux:API for clipboard and device integrations.
-
-## Install
-
-```bash
-pkg update && pkg upgrade
-pkg install nodejs termux-api git
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent
-mkdir -p ~/.pi/agent
-pi
-```
-
-## Clipboard
-
-Pi uses `termux-clipboard-set` and `termux-clipboard-get` when available. Image clipboard is not supported in Termux.
-
-## Useful `AGENTS.md` Context
-
-Add Termux environment notes to `~/.pi/agent/AGENTS.md`: OS is Android/Termux, home is `/data/data/com.termux/files/home`, prefix is `/data/data/com.termux/files/usr`, shared storage is `/storage/emulated/0`, use `termux-open-url`, `termux-open`, `termux-share`, `termux-notification`, and clipboard commands where appropriate.
-
-## Limitations and Troubleshooting
-
-No image clipboard. Some optional native binaries may be unavailable on Android ARM64. Run `termux-setup-storage` once for `/storage/emulated/0`. If npm fails, try `npm cache clean --force`.

package/skills/pi-agent/references/themes.md

@@ -1,69 +0,0 @@
-# Themes
-
-Source: https://pi.dev/docs/latest/themes
-
-Themes are JSON files defining TUI colors.
-
-## Locations
-
-- Built-in: `dark`, `light`
-- Global: `~/.pi/agent/themes/*.json`
-- Project: `.pi/themes/*.json` (only after project trust)
-- Packages: `themes/` directories or `pi.themes` entries in `package.json`
-- Settings: `themes` array
-- CLI: `--theme <path>` (repeatable) loads a theme file; `--use-theme <name[/name]>` selects the initial theme for one run
-
-Disable discovery with `--no-themes`. Select via `/settings` or `{"theme": "my-theme"}`. On first run Pi detects the terminal background and defaults to `dark` or `light`. Editing the active custom theme file hot-reloads it for immediate feedback.
-
-`--use-theme light` starts a run with that theme without changing the saved setting; `--use-theme light/dark` uses `lightTheme/darkTheme` syntax to follow terminal appearance. Picking another theme later in `/settings` applies immediately and saves normally.
-
-## Format
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
-  "name": "my-theme",
-  "vars": { "primary": "#00aaff", "secondary": 242 },
-  "colors": { "accent": "primary", "muted": "secondary", "text": "" }
-}
-```
-
-- `name` is required, must be unique, and must not contain `/`.
-- `vars` is optional — reusable colors referenced by name from `colors`.
-- `colors` must define all 51 required tokens. Optional tokens fall back: `thinkingMax` → `thinkingXhigh`, `scrollbarThumb` and `searchMatchBg` → `selectedBg`, `searchMatchText` → `text`.
-- `$schema` enables editor auto-completion and validation.
-
-## Color Tokens (51 required + 4 optional)
-
-- **Core UI (11)**: `accent`, `border`, `borderAccent`, `borderMuted`, `success`, `error`, `warning`, `muted`, `dim`, `text`, `thinkingText`
-- **Backgrounds & content (11 required + 3 optional)**: `selectedBg`, `userMessageBg`, `userMessageText`, `customMessageBg`, `customMessageText`, `customMessageLabel`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `toolTitle`, `toolOutput`, plus optional `scrollbarThumb` (fullscreen scrollbar thumb), `searchMatchBg`, and `searchMatchText` (transcript search). Non-current search matches render `searchMatchText` on `searchMatchBg` with an underline; the current match reverses that pair and uses bold.
-- **Markdown (10)**: `mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet`
-- **Tool diffs (3)**: `toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext`
-- **Syntax (9)**: `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation`
-- **Thinking level borders (6 required + 1 optional)**: `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, and optional `thinkingMax`
-- **Bash mode (1)**: `bashMode`
-
-## HTML Export (optional)
-
-```json
-{ "export": { "pageBg": "#18181e", "cardBg": "#1e1e24", "infoBg": "#3c3728" } }
-```
-
-Controls `/export` HTML output. If omitted, colors are derived from `userMessageBg`.
-
-## Color Values
-
-| Format | Example | Notes |
-|---|---|---|
-| Hex | `"#ff0000"` | 6-digit RGB |
-| 256-color | `39` | xterm palette index 0–255 |
-| Variable | `"primary"` | Reference to a `vars` entry |
-| Default | `""` | Terminal default color |
-
-256-color ranges: `0-15` basic ANSI (terminal-dependent), `16-231` the 6×6×6 RGB cube (`16 + 36R + 6G + B`), `232-255` grayscale.
-
-Pi emits 24-bit RGB; older 256-color terminals get the nearest approximation. Check truecolor with `echo $COLORTERM`. In VS Code set `terminal.integrated.minimumContrastRatio` to `1` for accurate colors.
-
-## Tips
-
-Dark terminals want bright saturated colors with higher contrast; light terminals want darker muted colors. Start from a base palette (Nord, Gruvbox, Tokyo Night) in `vars` and reference it consistently. Test against different message types, tool states, markdown, and long wrapped text. Built-in themes to copy: `src/modes/interactive/theme/dark.json` and `light.json`.

package/skills/pi-agent/references/tmux.md

@@ -1,44 +0,0 @@
-# tmux Setup
-
-Source: https://pi.dev/docs/latest/tmux
-
-tmux strips modifier information from some keys by default, so without configuration `Shift+Enter` and `Ctrl+Enter` are indistinguishable from plain `Enter`.
-
-## Recommended Configuration
-
-Add to `~/.tmux.conf`:
-
-```tmux
-set -g extended-keys on
-set -g extended-keys-format csi-u
-```
-
-Then restart tmux fully:
-
-```bash
-tmux kill-server
-tmux
-```
-
-Pi requests extended key reporting automatically when the Kitty keyboard protocol is unavailable. `extended-keys-format csi-u` requires **tmux 3.5 or later** (check with `tmux -V`). With tmux 3.2–3.4, omit that line; Pi still supports tmux's default xterm `modifyOtherKeys` format.
-
-## Why csi-u
-
-With only `set -g extended-keys on`, tmux defaults to `extended-keys-format xterm` and forwards modified keys as `modifyOtherKeys` sequences — `Ctrl+C` as `ESC [27;5;99~`, `Ctrl+Enter` as `ESC [27;5;13~`. With `csi-u` the same keys arrive as `ESC [99;5u` and `ESC [13;5u`. Pi supports both formats; `csi-u` is the recommended setup.
-
-## What It Fixes
-
-`ESC` below is the escape byte (`0x1b`).
-
-| Key | Without extended keys | With `csi-u` |
-|---|---|---|
-| Enter | `CR` | `CR` |
-| Shift+Enter | `CR` | `ESC [13;2u` |
-| Ctrl+Enter | `CR` | `ESC [13;5u` |
-| Alt/Option+Enter | `ESC CR` | `ESC [13;3u` |
-
-This affects the default bindings (Enter to submit, Shift+Enter for newline) and any custom keybindings using modified Enter.
-
-## Requirements
-
-tmux 3.5+ for `extended-keys-format csi-u`, plus a terminal emulator that supports extended keys: Ghostty, Kitty, iTerm2, WezTerm, or Windows Terminal.

package/skills/pi-agent/references/tui.md

@@ -1,97 +0,0 @@
-# TUI Components
-
-Source: https://pi.dev/docs/latest/tui
-
-Extensions and custom tools render custom terminal UI through `@earendil-works/pi-tui`.
-
-## Component Interface
-
-```ts
-interface Component {
-  render(width: number): string[];
-  handleInput?(data: string): void;
-  wantsKeyRelease?: boolean;   // receive key release events (Kitty protocol)
-  invalidate(): void;          // clear cached render state; called on theme changes
-}
-```
-
-Each line from `render(width)` **must not exceed `width`**. The TUI appends a full SGR reset and OSC 8 reset at the end of every rendered line, so styles do not carry across lines — reapply styles per line or use `wrapTextWithAnsi()`.
-
-Width helpers: `visibleWidth(str)` (ignores ANSI), `truncateToWidth(str, width, ellipsis?)`, `wrapTextWithAnsi(str, width)`.
-
-## Focusable and IME
-
-Components that draw a text cursor should implement `Focusable { focused: boolean }`. When focused, the TUI sets `focused = true`, scans output for `CURSOR_MARKER` (a zero-width APC sequence emitted right before the fake cursor), and positions the hardware cursor there. The cursor stays hidden by default; some terminals need it visible for IME candidate windows — enable with `showHardwareCursor`, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The built-in `Editor` and `Input` already implement this.
-
-Container components (dialogs, selectors) that embed an `Input`/`Editor` must implement `Focusable` and propagate `focused` to the child, or IME candidate windows appear in the wrong place.
-
-## Usage
-
-```ts
-const result = await ctx.ui.custom<string | null>((tui, theme, keybindings, done) =>
-  new MyComponent({ theme, keybindings, onChange: () => tui.requestRender(), onSelect: done, onCancel: () => done(null) })
-);
-```
-
-The same call works inside a custom tool's `execute(toolCallId, params, signal, onUpdate, ctx)`. Returning a plain `{ render, invalidate, handleInput }` object is also fine.
-
-## Overlays
-
-Pass `{ overlay: true }` to render on top of existing content without clearing the screen. `overlayOptions` controls layout:
-
-- Size: `width`, `minWidth`, `maxHeight` (numbers or percentage strings)
-- Position: `anchor` (9 positions, default `"center"`), `offsetX`/`offsetY`, or `row`/`col`
-- Margins: `margin` (number or `{ top, right, bottom, left }`)
-- Responsive: `visible(termWidth, termHeight)`
-
-`onHandle: (handle) => …` gives `focus()` (focus and bring to front), `unfocus()` (release input to the normal fallback), `unfocus({ target })` (hand input to a specific component, or `null` for none), `setHidden(true|false)`, and `hide()` (permanent removal).
-
-A focused visible overlay keeps input ownership across temporary non-overlay UI and can reclaim input when that UI closes. Overlay components are disposed when closed — never reuse a reference; call the show function again to re-show.
-
-## Built-in Components
-
-Import from `@earendil-works/pi-tui`: `Text` (multi-line with word wrapping, `new Text(content, paddingX, paddingY, bgFn?)`, `setText()`), `Box` (padding + background, `addChild`, `setBgFn`), `Container` (vertical grouping, `addChild`/`removeChild`/`clear`), `Spacer(lines)`, `Markdown(text, paddingX, paddingY, theme)`, `Image(base64, mimeType, theme, { maxWidthCells, maxHeightCells })` (Kitty, iTerm2, Ghostty, WezTerm, Warp), `SelectList(items, visibleCount, theme)` with `SelectItem { value, label, description? }`, `SettingsList(items, visibleCount, theme, onChange, onClose, { enableSearch })` with `SettingItem { id, label, currentValue, values }`, plus `AutocompleteItem` types.
-
-From `@earendil-works/pi-coding-agent`: `DynamicBorder`, `BorderedLoader` (spinner + abort signal + `onAbort`), `CustomEditor`, `getMarkdownTheme()`, `getSettingsListTheme()`, `keyHint`/`keyText`/`rawKeyHint`, `highlightCode`, `getLanguageFromPath`.
-
-## Keyboard Input
-
-```ts
-import { matchesKey, Key } from "@earendil-works/pi-tui";
-
-if (matchesKey(data, Key.up)) { /* ... */ }
-if (matchesKey(data, Key.ctrl("c"))) { /* ... */ }
-```
-
-`Key.enter`, `Key.escape`, `Key.tab`, `Key.space`, `Key.backspace`, `Key.delete`, `Key.home`, `Key.end`, arrows, and modifier helpers `Key.ctrl`, `Key.shift`, `Key.alt`, `Key.ctrlShift`. String literals (`"enter"`, `"ctrl+c"`, `"shift+tab"`) also work.
-
-## Theming
-
-Use the `theme` passed into the callback or renderer — never import a global theme. `theme.fg(color, text)` covers general (`text`, `accent`, `muted`, `dim`, `searchMatchText`), status (`success`, `error`, `warning`), borders (`border`, `borderAccent`, `borderMuted`), messages (`userMessageText`, `customMessageText`, `customMessageLabel`), tools (`toolTitle`, `toolOutput`), diffs (`toolDiffAdded`/`Removed`/`Context`), markdown (`md*`), syntax (`syntax*`), thinking levels (`thinkingOff`…`thinkingMax`), and `bashMode`. `theme.bg(color, text)` covers `selectedBg`, `searchMatchBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`. Text styles: `theme.bold`, `theme.italic`, `theme.strikethrough`.
-
-Components that pre-bake theme colors into cached strings must rebuild that content in `invalidate()` — clearing a render cache is not enough. This applies to `theme.fg`/`theme.bg` strings stored in child components, `highlightCode()` output, and child trees that embed colors. It is unnecessary when you pass theme callbacks that run at render time, for simple containers, or for stateless render.
-
-## Common Patterns
-
-1. **Selection dialog** — `SelectList` framed with `DynamicBorder`, `onSelect`/`onCancel` calling `done`.
-2. **Async with cancel** — `BorderedLoader(tui, theme, "Fetching…")`, pass `loader.signal` to the async work, `loader.onAbort = () => done(null)`.
-3. **Settings toggles** — `SettingsList` with `getSettingsListTheme()`.
-4. **Persistent status** — `ctx.ui.setStatus("my-ext", text)`; clear with `undefined`.
-5. **Working indicator** — `ctx.ui.setWorkingIndicator({ frames, intervalMs })`; `{ frames: [] }` hides it, no argument restores the default spinner. Frames render verbatim, so add colors yourself. Compaction and retry loaders keep built-in styling. `setWorkingMessage()` and `setWorkingVisible()` control the loader row.
-6. **Widgets** — `ctx.ui.setWidget(key, lines | factory, { placement: "aboveEditor" | "belowEditor" })`; `undefined` clears.
-7. **Custom footer** — `ctx.ui.setFooter((tui, theme, footerData) => ({ render, invalidate, dispose }))`. `footerData.getGitBranch()`, `getExtensionStatuses()`, and `onBranchChange(cb)` expose data extensions cannot otherwise reach; token stats come from `ctx.sessionManager.getBranch()` and `ctx.model`. `setFooter(undefined)` restores the default.
-8. **Custom editor** — extend `CustomEditor` (not base `Editor`) so app keybindings still work, call `super.handleInput(data)` for keys you do not handle, and install with `ctx.ui.setEditorComponent((tui, theme, keybindings) => new MyEditor(...))`. Capture `ctx.ui.getEditorComponent()` first to wrap another extension's editor; `setEditorComponent(undefined)` restores the default.
-
-## Key Rules
-
-1. Respect `render(width)` on every line.
-2. Always use the `theme` from the callback; type `DynamicBorder` color params explicitly (`(s: string) => theme.fg("accent", s)`).
-3. Call `tui.requestRender()` after state changes in `handleInput`.
-4. Implement `invalidate()` on custom components and their child trees.
-5. Propagate focus to embedded inputs.
-6. Reuse `SelectList`, `SettingsList`, and `BorderedLoader` before building primitives.
-7. Guard TUI features in non-TUI modes (`ctx.mode === "tui"`).
-
-## Debug Logging
-
-`PI_TUI_WRITE_LOG=/tmp/tui-ansi.log` captures the raw ANSI stream written to stdout.

package/skills/pi-agent/references/usage.md

@@ -1,129 +0,0 @@
-# Using Pi
-
-Source: https://pi.dev/docs/latest/usage
-
-## Interface
-
-Interactive mode has four areas: startup header (shortcuts, loaded context files, prompt templates, skills, extensions), messages, editor, and footer. The footer shows cwd, session name, token/cache usage, cost, context usage, and current model; totals include assistant responses, usage reported by tools, and summary generation. The editor border indicates thinking level. Built-in UI (`/settings`) or extension UI can temporarily replace the editor.
-
-## Editor Features
-
-| Feature | How |
-|---|---|
-| File reference | Type `@` to fuzzy-search project files |
-| Path completion | Tab |
-| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
-| Copy response | Ctrl+X copies the last assistant message; in `/tree` it copies the selected message |
-| Images | Paste with Ctrl+V (Alt+V on Windows), or drag into the terminal |
-| Shell command | `!command` runs and sends output to the model |
-| Hidden shell command | `!!command` runs without sending output to the model |
-| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
-
-## Slash Commands
-
-| Command | Description |
-|---|---|
-| `/login`, `/logout` | Manage OAuth or API-key credentials |
-| `/llama` | Download, load, unload llama.cpp router models (`references/llama-cpp.md`) |
-| `/model` | Switch models |
-| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
-| `/settings` | Thinking level, theme, message delivery, transport |
-| `/resume`, `/new`, `/name <name>`, `/session` | Session management |
-| `/tree` | Jump to any point in the session and continue from there |
-| `/trust` | Save project trust decision for future sessions |
-| `/fork`, `/clone` | New session from a previous user message / duplicate active branch |
-| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
-| `/copy` | Copy last assistant message to clipboard |
-| `/export [file]` | Export session to HTML or JSONL |
-| `/import <file>` | Import and resume a session from a JSONL file |
-| `/share` | Upload as private GitHub gist with shareable HTML link |
-| `/reload` | Reload keybindings, extensions, skills, prompts, themes, context files |
-| `/hotkeys`, `/changelog`, `/quit` | Shortcuts, version history, quit |
-
-Skills are available as `/skill:name`; prompt templates expand as `/templatename`; extensions can register custom commands.
-
-## Message Queue
-
-- Enter queues a steering message, delivered after the current assistant turn finishes its tool calls.
-- Alt+Enter queues a follow-up message, delivered after the agent finishes all work.
-- Escape aborts and restores queued messages to the editor; Alt+Up retrieves them.
-- `steeringMode` and `followUpMode` control one-at-a-time vs all-at-once delivery.
-
-On Windows Terminal, Alt+Enter is fullscreen by default — remap it (`references/terminal-setup.md`).
-
-## Context and System Prompt Files
-
-Pi loads `AGENTS.md` or `CLAUDE.md` from `~/.pi/agent/AGENTS.md`, parent directories walking up from cwd, and the current directory. A directory containing `AGENTS.override.md` contributes that file instead of its `AGENTS.md`/`CLAUDE.md`; other directories still layer normally. Disable with `--no-context-files` / `-nc`.
-
-Replace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent/SYSTEM.md` (global). Append instead of replacing with `APPEND_SYSTEM.md` in either location.
-
-## Project Trust
-
-Interactive startup asks before trusting a project folder that has project-local settings, resources, or project `.agents/skills` and no saved decision for that folder or a parent in `~/.pi/agent/trust.json`. Before the decision, Pi loads only context files, user/global extensions, and CLI `-e` extensions so they can handle `project_trust`. Non-interactive modes (`-p`, `--mode json`, `--mode rpc`) never prompt and follow `defaultProjectTrust` (`ask` default, `never`, `always`); `--approve`/`-a` and `--no-approve`/`-na` override for one run. `/trust` saves a decision (including for the immediate parent folder) to `trust.json` without reloading the session. `pi config` and package commands use the same flow, except `pi update` never prompts.
-
-## Exporting and Sharing
-
-`/export [file]` writes HTML; `/share` uploads a private GitHub gist with a shareable HTML link. `badlogic/pi-share-hf` publishes sessions to Hugging Face datasets for research.
-
-## CLI Modes
-
-```bash
-pi [options] [@files...] [messages...]
-pi -p "prompt"                # print and exit
-pi --mode json "prompt"       # JSONL event stream
-pi --mode rpc                 # RPC over stdin/stdout
-pi --export <in> [out]        # export a session to HTML
-```
-
-Print mode reads piped stdin and merges it into the initial prompt.
-
-## Package Commands
-
-```bash
-pi install <source> [-l]     # -l writes to project settings
-pi remove <source> [-l]      # pi uninstall is an alias
-pi update [source|self|pi]   # update pi only, or one package source
-pi update --all              # pi + packages; reconcile pinned git refs
-pi update --extensions       # packages only
-pi update --models           # refresh model catalogs only
-pi update --self             # update pi only
-pi update --extension <src>  # update one package
-pi list                      # list installed packages
-pi config                    # enable/disable package resources
-```
-
-## Options
-
-Model: `--provider <name>`, `--model <pattern>` (supports `provider/id` and `:<thinking>`), `--api-key`, `--thinking <off|minimal|low|medium|high|xhigh|max>`, `--models <patterns>`, `--list-models [search]`.
-
-Session: `-c/--continue`, `-r/--resume`, `--session <path|id>`, `--fork <path|id>`, `--session-dir`, `--no-session`, `-n/--name`.
-
-Tools: `-t/--tools`, `-xt/--exclude-tools`, `-nbt/--no-builtin-tools` (keeps extension/custom tools), `-nt/--no-tools`. Built-ins: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
-
-Resources: `-e/--extension <source>` (path, npm, or git; repeatable), `--no-extensions`, `--skill`, `--no-skills`, `--prompt-template`, `--no-prompt-templates`, `--theme`, `--no-themes`, `-nc/--no-context-files`. Combine `--no-*` with explicit flags to load exactly what you need: `pi --no-extensions -e ./my-extension.ts`.
-
-Other: `--system-prompt <text>` (context files and skills are still appended), `--append-system-prompt`, `--tui-mode <regular|fullscreen>`, `--use-theme <name[/name]>` (initial theme for this run only), `--verbose`, `-a/--approve`, `-na/--no-approve`, `-h/--help`, `-v/--version`.
-
-## Fullscreen TUI Mode
-
-`--tui-mode fullscreen` (experimental) scrolls the transcript inside the terminal viewport while queued messages, working status, extension widgets, editor, and footer stay pinned at the bottom. Mouse/trackpad input scrolls the region under the pointer, and keyboard viewport actions (`tui.altScreen.*` in `references/keybindings.md`) stay available. Inline images work in terminals supporting the Kitty graphics protocol (Kitty, Ghostty); iTerm2 renders text placeholders instead. `regular` mode uses the main screen and terminal-owned scrollback. Switch at runtime and set the default in `/settings`; `fullscreenExitOutput` controls whether exiting prints the final transcript or only the resume hint.
-
-File arguments: prefix with `@` to include in the message (`pi @code.ts @test.ts "Review these"`).
-
-Environment variables are documented separately in `references/environment-variables.md`.
-
-## Examples
-
-```bash
-pi "List all .ts files in src/"
-pi --name "release audit" -p "Audit this repository"
-pi --model openai/gpt-4o "Help me refactor"
-pi --model sonnet:high "Solve this complex problem"
-pi --models "claude-*,gpt-4o"
-pi --tools read,grep,find,ls -p "Review the code"
-pi --exclude-tools ask_question
-```
-
-## Design Principles
-
-Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages. It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. Build or install those workflows as extensions/packages, or use external tools such as containers and tmux.

package/skills/pi-agent/references/windows.md

@@ -1,23 +0,0 @@
-# Windows Setup
-
-Source: https://pi.dev/docs/latest/windows
-
-Pi requires a bash shell on Windows. It checks, in order:
-
-1. Custom path from `~/.pi/agent/settings.json`
-2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
-3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
-
-[Git for Windows](https://git-scm.com/download/win) is sufficient for most users.
-
-## Custom Shell Path
-
-```json
-{
-  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
-}
-```
-
-The value is JSON, so each literal backslash in the Windows path must be doubled.
-
-Related Windows notes: Ctrl+Enter for multi-line input, Alt+V to paste images, `app.suspend` has no default binding (`references/keybindings.md`), and Alt+Enter must be remapped away from fullscreen (`references/terminal-setup.md`).

package/skills/pkpd-modeling/assets/nca-reporting-checklist.md

@@ -1,72 +0,0 @@
-# NCA reporting checklist
-
-An NCA result is uninterpretable — and irreproducible — unless every item below is stated. Most
-disagreements between two analyses of the same data resolve to one of the first four.
-
-## The four conventions that change the answer
-
-- [ ] **Trapezoidal rule**: linear / linear-up-log-down / log-linear
-- [ ] **BLQ handling**, stated separately for each position:
-  - leading (before the first quantifiable sample): [ zero / excluded ]
-  - embedded: [ zero / LLOQ÷2 / excluded ]
-  - trailing: [ excluded / other ]
-- [ ] **Lambda_z selection**: the rule, the minimum number of points, whether Tmax was excluded, and
-      the window and point count actually used **for each subject**
-- [ ] **AUCinf basis**: observed Clast or predicted Clast
-
-## Data
-
-- [ ] Analyte, matrix, assay, LLOQ, and the bioanalytical validation report reference
-- [ ] Actual elapsed times used, not nominal — and nominal times used only for grouping
-- [ ] Dose actually administered per subject, including any deviations
-- [ ] Records excluded, with the reason, and confirmation the criteria were set before unblinding
-- [ ] Deviations in sampling time above [ ]% of the nominal time, and how they were handled
-
-## Parameters reported
-
-- [ ] Cmax and Tmax as **observed** values, never interpolated
-- [ ] AUClast, AUCinf (both observed- and predicted-based, or one with the basis stated)
-- [ ] % AUC extrapolated, per subject
-- [ ] lambda_z, t½, and the number of points and time span of the terminal fit, per subject
-- [ ] CL or CL/F, Vz or Vz/F — with `/F` used for every extravascular route
-- [ ] Vss **only** for intravenous data
-- [ ] At steady state: AUC(0-tau), Cavg, Cmin, PTF%, accumulation ratio — and **not** AUCinf
-- [ ] Partial AUCs, if pre-specified, with their intervals
-
-## Terminal-phase quality, per subject
-
-- [ ] Adjusted r-squared of the lambda_z regression
-- [ ] Span ratio (window duration ÷ t½); flag below 2
-- [ ] % AUC extrapolated; flag above 20%
-- [ ] Number of points in the fit; flag below 3
-- [ ] Subjects for whom lambda_z was not estimable, and how they were handled in the summary
-
-## Summary statistics
-
-- [ ] Exposure metrics (AUC, Cmax) as **geometric mean and geometric CV%**
-- [ ] Tmax as **median and range**
-- [ ] Arithmetic mean, SD and CV% alongside, if wanted, but not instead
-- [ ] n for each parameter, since it differs when lambda_z fails for some subjects
-
-## Presentation
-
-- [ ] Individual concentration-time profiles on both linear and semi-logarithmic axes
-- [ ] Mean profiles with a stated rule for handling BLQ in the mean
-- [ ] A table of individual parameters, not only summary statistics
-
-## Method and provenance
-
-- [ ] Software and version
-- [ ] Units for every parameter, and confirmation that dose and concentration units are consistent
-- [ ] Whether the analysis was pre-specified, and the reference to the plan
-- [ ] Any deviation from the plan, with its reason
-
-## The traps this checklist exists to catch
-
-1. Reporting AUCinf from a truncated steady-state profile.
-2. Interpolating Cmax, or reporting a mean Tmax.
-3. Quoting Vz as if it were Vss, or reporting Vss from oral data.
-4. Applying one BLQ rule to the test arm and another to the reference.
-5. Presenting arithmetic means for AUC and Cmax.
-6. Summarising across subjects without saying that lambda_z failed for some of them.
-7. Omitting the lambda_z window, which makes the half-life unreproducible.

package/skills/pkpd-modeling/assets/popk-analysis-plan.md

@@ -1,136 +0,0 @@
-# Population Pharmacokinetic Analysis Plan
-
-> Template. Every bracketed field is a decision to make and record **before** the analysis starts.
-> A plan written after the modelling is not an analysis plan, and the difference is visible to a
-> reviewer.
-
-**Study/programme:** [ ]  **Compound:** [ ]  **Plan version and date:** [ ]
-**Author:** [ ]  **Reviewers:** [ ]
-
----
-
-## 1. Objectives
-
-Primary objective: [ ]
-
-Each objective must name the decision it informs — a dose for the next study, a label statement, a
-covariate adjustment, a waiver. "Characterise the population pharmacokinetics" is not an objective;
-it is an activity.
-
-Secondary objectives: [ ]
-
-**Intended use of the model:** [ ] — regulators evaluate a model against its intended use, and the
-required rigour follows from it.
-
-## 2. Data
-
-| Item | Specification |
-| --- | --- |
-| Studies included | [ ] |
-| Analysis population | [ ] |
-| Analyte and matrix | [ ] |
-| Assay and LLOQ | [ ] (see the bioanalytical validation report) |
-| Time reference | actual elapsed time from the most recent dose |
-| Dataset specification | [ reference the document ] |
-| Derivation script | [ path / repository ] |
-
-**Exclusions**, defined now and applied blind to the model:
-
-- [ ] Records with no matching dose record
-- [ ] Concentrations flagged by the bioanalytical laboratory
-- [ ] Subjects with documented non-compliance
-- [ ] Pre-dose concentrations in a first-dose profile above [ ]% of Cmax
-- [ ] Other: [ ]
-
-**BLQ handling:** [ M1 / M3 / other ]. Justification: [ ]. Expected BLQ fraction: [ ]%.
-If the observed BLQ fraction exceeds [ ]%, the method changes to M3.
-
-**Missing covariates:** [ imputation rule, or exclusion ]. Missingness will be tabulated before
-imputation.
-
-## 3. Software
-
-| | |
-| --- | --- |
-| Estimation | [ NONMEM 7.x / Monolix / nlmixr2 ] version [ ] |
-| Orchestration and post-processing | [ Pharmpy / PsN / R ] version [ ] |
-| Estimation method | [ FOCE-I / SAEM followed by IMP ] |
-| Environment | [ container / lockfile reference ] |
-
-## 4. Structural model
-
-Starting point: [ ] compartments, [ ] absorption, [ ] elimination.
-
-Candidate structures to be evaluated: [ ]
-
-Parameterisation is clearance-based (CL, V, Q, Vp) in all candidates.
-
-Selection criteria, in this order: physiological plausibility; residual patterns; likelihood-ratio
-test for nested models (ΔOFV > [3.84] at 1 df); BIC; parameter precision. **An extra compartment
-whose intercompartmental clearance has RSE above [50]% is not retained regardless of the objective
-function.**
-
-## 5. Between-subject and between-occasion variability
-
-- IIV on: [ ] Distribution: [ exponential ]
-- Correlations estimated between: [ ]
-- IOV on: [ ], with an occasion defined as [ ]
-- Rule for removing a variance component: [ ]
-
-## 6. Residual error
-
-Candidates: [ proportional / additive / combined / log-transform-both-sides ]. Separate error
-models by [ study / assay / matrix ]: [ yes / no, with justification ].
-
-## 7. Covariate model
-
-**Covariates included a priori on mechanistic grounds, not tested:**
-
-- Body size: allometric scaling on CL (exponent [0.75], [fixed]) and V (exponent [1.0], [fixed])
-- Maturation, if paediatric subjects are included: [ function, parameters, fixed or estimated ]
-- Other: [ ]
-
-**Covariates to be evaluated:**
-
-| Covariate | Parameter(s) | Functional form | Rationale |
-| --- | --- | --- | --- |
-| [ ] | [ ] | [ ] | [ ] |
-
-**Procedure:** [ stepwise covariate modelling / full model estimation ].
-If stepwise: forward inclusion at p < [0.05] (ΔOFV > 3.84), backward elimination at p < [0.001]
-(ΔOFV > 10.83). Note that stepwise selection biases effect sizes upward and narrows intervals; a
-full-model approach is preferred where the objective is to quantify an effect.
-
-Clinical relevance threshold: a covariate effect is reported as relevant if it changes [ exposure
-metric ] by more than [ ]% across the [5th–95th] percentile of the covariate.
-
-## 8. Model evaluation
-
-- Goodness-of-fit: DV vs PRED and IPRED; CWRES vs time and vs PRED; |IWRES| vs IPRED
-- Eta shrinkage reported for every eta; covariate plots not interpreted above [30]% shrinkage
-- Prediction-corrected VPC, [ n ] replicates, stratified by [ ]
-- NPDE with tests of mean, variance and normality
-- Parameter uncertainty by [ covariance step / bootstrap (n = ) / SIR / log-likelihood profiling ]
-- Condition number reported; above 1000 is treated as ill-conditioned
-
-**Acceptance criteria for the final model:** [ ]
-
-## 9. Simulations
-
-Purpose: [ ]  Scenarios: [ ]  Replicates: [ ]  Population sampled from: [ ]
-Uncertainty in fixed effects propagated: [ yes / no ]  Endpoint summarised: [ ]
-
-## 10. Deviations
-
-Any departure from this plan is recorded in the report with its reason and the date it was decided.
-Post hoc analyses are labelled as such and reported separately from the pre-specified analysis.
-
----
-
-**Approvals**
-
-| Role | Name | Signature | Date |
-| --- | --- | --- | --- |
-| Author | | | |
-| Reviewer | | | |
-| Clinical pharmacology | | | |