@counterposition/skill-pi 0.75.0 → 0.80.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@counterposition/skill-pi",
-  "version": "0.75.0",
+  "version": "0.80.3",
   "description": "Pi coding agent reference skill — extensions, settings, providers, SDK/RPC, packages, and .pi/ config",
   "keywords": [
     "ai-skill",

package/skills/pi/SKILL.md

@@ -53,6 +53,7 @@ Core packages on npm (source: [github.com/earendil-works/pi](https://github.com/
 - **Skills** — Markdown capability packages (`SKILL.md` + frontmatter) following the Agent Skills standard. Pi loads names + descriptions into the system prompt; bodies load on demand. → `references/skills.md`
 - **Settings** — Hierarchical JSON: project `.pi/settings.json` merges over global `~/.pi/agent/settings.json`. → `references/settings.md`
 - **Packages** — Bundles of extensions/skills/prompts/themes via npm, git, or local paths. Installed with `pi install`. → `references/packages.md`
+- **Project trust** — Pi 0.79+ asks before loading project-local settings, resources, and packages; decisions persist in `~/.pi/agent/trust.json`. `--approve`/`--no-approve` override per run; `defaultProjectTrust` sets the non-interactive fallback. → `references/settings.md`
 - **Context files & prompt templates** — Pi loads `AGENTS.md` / `CLAUDE.md` from the agent dir and from `cwd` up through ancestors. `.pi/SYSTEM.md` replaces the system prompt; `APPEND_SYSTEM.md` appends. Prompt templates in `prompts/` become slash commands. → `references/settings.md`
 - **SDK** — Programmatic embedding via `createAgentSession()`; `createAgentSessionRuntime()` for session replacement. → `references/sdk.md`
 - **Custom providers & models** — `models.json` or extension `pi.registerProvider()` for any OpenAI-/Anthropic-/Google-compatible or custom LLM endpoint. → `references/providers.md`

package/skills/pi/references/extensions.md

@@ -25,6 +25,7 @@ import { Text } from "@earendil-works/pi-tui";
 
 - Use `typebox` (1.x) for schemas.
 - Use `StringEnum` from `@earendil-works/pi-ai` for Google-compatible string enums.
+- Pi 0.80.0 moved pi-ai's old global API (`getModel`, `getModels`, `stream`, `complete`, `registerApiProvider`, ...) off the pi-ai root entrypoint to `@earendil-works/pi-ai/compat`. Extensions keep working unchanged at runtime (the extension loader aliases the root to the compat superset), but extension sources that typecheck against pi-ai's published types must import those APIs from `@earendil-works/pi-ai/compat`. `StringEnum` and the type surface remain on the root. The compat entrypoint and loader alias will be removed in a future release.
 
 ## Quick Start
 
@@ -75,14 +76,18 @@ Useful session events:
 - `session_compact`
 - `session_before_tree`
 - `session_tree`
+- `session_info_changed` — observe session display-name changes
 - `session_shutdown`
 - `resources_discover`
+- `project_trust` — user/global and CLI extensions only, fired before project resources load; return `{ trusted: "yes" | "no" | "undecided" }` (optionally `remember: true` to persist). The first yes/no decision wins and suppresses the built-in trust prompt.
+
+`session_before_compact` and `session_compact` carry `reason` and `willRetry` (Pi 0.79.10) so handlers can distinguish manual `/compact`, threshold auto-compaction, and overflow-retry compaction.
 
 `session_start` carries `event.reason` — `"startup" | "reload" | "new" | "resume" | "fork"` — and `event.previousSessionFile` for `"new"`/`"resume"`/`"fork"`. The old post-transition `session_switch` / `session_fork` events were removed; route all of those flows through `session_start`.
 
 Useful agent events:
 
-- `input`
+- `input` — carries `event.streamingBehavior` (`"steer" | "followUp" | undefined`) so handlers can distinguish idle prompts, mid-stream steers, and queued follow-ups; return `{ action: "transform" | "handled" | "continue" }`
 - `before_agent_start` — receives `event.systemPromptOptions` (a `BuildSystemPromptOptions`) so handlers can inspect the structured inputs feeding the system prompt
 - `agent_start`
 - `agent_end`
@@ -111,18 +116,25 @@ Tool results may include `terminate: true` to end the current tool batch without
 
 ## Extension Context
 
-`ctx` gives extensions access to:
+`ctx` (`ExtensionContext`) gives extensions access to:
 
 - `ctx.ui` for interactive UI hooks
+- `ctx.mode` — `"tui" | "rpc" | "json" | "print"`; gate terminal-only features on `ctx.mode === "tui"`
 - `ctx.cwd`
-- `ctx.session`
-- `ctx.sessionManager`
-- `ctx.modelRegistry`
-- `ctx.hasUI`
-- `ctx.isIdle()`
-- `ctx.abort()`
+- `ctx.sessionManager` (read-only)
+- `ctx.modelRegistry` / `ctx.model`
+- `ctx.hasUI` — `true` in TUI and RPC modes
+- `ctx.signal` — the active agent abort signal (or `undefined` when idle); pass it to `fetch`/model calls for abort-aware nested work
+- `ctx.isIdle()` / `ctx.hasPendingMessages()`
+- `ctx.abort()` / `ctx.shutdown()`
 - `ctx.getContextUsage()`
+- `ctx.compact(options?)` — trigger compaction without awaiting completion
 - `ctx.getSystemPrompt()`
+- `ctx.isProjectTrusted()` — the effective project trust decision, including temporary `--approve`/`--no-approve` decisions
+
+Use `CONFIG_DIR_NAME` (exported from `@earendil-works/pi-coding-agent`) instead of hardcoding `.pi` when building project config paths, e.g. `join(ctx.cwd, CONFIG_DIR_NAME, "my-extension.json")`.
+
+Command handlers receive `ExtensionCommandContext`, which extends the above with session-control methods that would deadlock from event handlers: `ctx.getSystemPromptOptions()` (inspect the base system-prompt inputs), `ctx.waitForIdle()`, `ctx.newSession()`, `ctx.fork()`, `ctx.switchSession()`, `ctx.navigateTree()`, and `ctx.reload()`.
 
 ## Tool Registration
 
@@ -149,6 +161,8 @@ pi.registerTool({
 });
 ```
 
+Optional prompt metadata: add `promptSnippet` to give the tool a one-line entry in the system prompt's `Available tools` list, and `promptGuidelines: string[]` to append bullets to the `Guidelines` section while the tool is active. Guidelines are appended flat with no tool-name prefix, so each bullet must name its tool (write `"Use my_tool when..."`, not `"Use this tool when..."`). `pi.getAllTools()` exposes each tool's `promptGuidelines` for attribution.
+
 Important rules:
 
 1. Truncate large output.
@@ -185,7 +199,11 @@ const editorFactory = ctx.ui.getEditorComponent();                 // wrap the a
 
 ctx.ui.setToolsExpanded(true);
 
-ctx.ui.addAutocompleteProvider((query, ctx) => /* completions */);  // stack on top of slash/path provider
+ctx.ui.addAutocompleteProvider((current) => ({    // stack on top of slash/path provider
+  triggerCharacters: ["#"],                       // optional natural triggers (Pi 0.79.1)
+  async getSuggestions(lines, cursorLine, cursorCol, options) { /* ... or delegate to current */ },
+  applyCompletion(...args) { return current.applyCompletion(...args); },
+}));
 
 const result = await ctx.ui.custom((tui, theme, keybindings, done) => {
   return new Text("Press Enter", 0, 0);

package/skills/pi/references/packages.md

@@ -16,16 +16,19 @@ pi install ./relative/path/to/package
 pi remove npm:@foo/bar
 pi uninstall npm:@foo/bar
 pi list
-pi update                 # update pi itself + all installed packages (skips pinned)
-pi update --self          # update pi only
+pi update                 # update pi only (changed in Pi 0.79.7)
+pi update --all           # update pi + packages, reconcile pinned git refs
 pi update --extensions    # update packages only
+pi update --self          # update pi only
 pi update <source>        # update one package
 pi config
 ```
 
-By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead.
+By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. `pi update` installs the exact version returned by the update check.
+
+Package commands follow the project trust flow (`pi update` never prompts); pass `--approve`/`-a` or `--no-approve`/`-na` to trust or ignore project-local settings for one command.
 
-Project installs are shareable with a team. Pi will install missing project packages automatically on startup.
+Project installs are shareable with a team. Pi will install missing project packages automatically on startup once the project is trusted.
 
 For temporary one-run testing, use `--extension` / `-e` with an npm or git source. Pi installs it into a temporary directory for that run only.
 
@@ -40,7 +43,7 @@ npm:pkg
 
 - User installs go under `~/.pi/agent/npm/`
 - Project installs go under `.pi/npm/`
-- Version-pinned installs are skipped by `pi update`
+- Version-pinned installs are skipped by `pi update --extensions` / `--all`
 - Use `npmCommand` in settings if you need a wrapper such as `mise` or `asdf`
 
 ### git
@@ -54,7 +57,7 @@ ssh://git@github.com/user/repo@v1
 
 - Global clones live in `~/.pi/agent/git/`
 - Project clones live in `.pi/git/`
-- Refs pin the package and are skipped by `pi update`
+- Refs pin the package; `pi update --extensions` / `--all` do not move them to newer refs but do reconcile the clone to the configured ref — use `pi install git:host/user/repo@new-ref` to move a pin
 - Pi runs `npm install` after clone/pull when `package.json` exists
 
 ### local paths

package/skills/pi/references/providers.md

@@ -7,7 +7,7 @@ Pi supports subscription-based providers via OAuth, API-key providers via env va
 Use `/login` in interactive mode, then select a provider. The `/login` selector is fuzzy-searchable and shows where each entry's auth comes from (`--api-key`, env var, custom provider) without leaking the secret.
 
 - Anthropic Claude Pro / Max — third-party usage draws from extra usage and is billed per token (suppress the warning via `warnings.anthropicExtraUsage`)
-- OpenAI ChatGPT Plus / Pro (Codex)
+- OpenAI ChatGPT Plus / Pro (Codex) — `/login` defaults to browser auth but can use a device-code flow for headless environments
 - GitHub Copilot
 
 Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Google Gemini CLI and Google Antigravity providers.
@@ -17,9 +17,11 @@ Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Goog
 | Provider | Env Var | `auth.json` key |
 |----------|---------|-----------------|
 | Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
+| Ant Ling | `ANT_LING_API_KEY` | `ant-ling` |
 | Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
 | OpenAI | `OPENAI_API_KEY` | `openai` |
 | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
+| NVIDIA NIM | `NVIDIA_API_KEY` | `nvidia` |
 | Google Gemini | `GEMINI_API_KEY` | `google` |
 | Mistral | `MISTRAL_API_KEY` | `mistral` |
 | Groq | `GROQ_API_KEY` | `groq` |
@@ -30,6 +32,7 @@ Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Goog
 | OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
 | Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
 | ZAI | `ZAI_API_KEY` | `zai` |
+| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` | `zai-coding-cn` |
 | OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
 | OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
 | Hugging Face | `HF_TOKEN` | `huggingface` |
@@ -49,16 +52,25 @@ Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Goog
 {
   "anthropic": { "type": "api_key", "key": "sk-ant-..." },
   "openai": { "type": "api_key", "key": "!op read 'OpenAI API Key'" },
-  "google": { "type": "api_key", "key": "GEMINI_API_KEY" },
-  "together": { "type": "api_key", "key": "TOGETHER_API_KEY" }
+  "google": { "type": "api_key", "key": "$GEMINI_API_KEY" },
+  "cloudflare-ai-gateway": {
+    "type": "api_key",
+    "key": "$CLOUDFLARE_API_KEY",
+    "env": {
+      "CLOUDFLARE_ACCOUNT_ID": "account-id",
+      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
+    }
+  }
 }
 ```
 
 `key` values can be:
 
 - A literal secret
-- An environment variable name
-- A shell command prefixed with `!`
+- `$ENV_VAR` / `${ENV_VAR}` environment interpolation (works inside larger literals). Plain uppercase names without `$` are treated as literals since Pi 0.79.4 — the old bare-env-var-name form no longer resolves.
+- A shell command prefixed with `!` (stdout is used, cached for the process lifetime)
+
+Entries may include an `env` object (Pi 0.79.5) for provider-scoped environment overrides — Cloudflare account/gateway IDs, Azure endpoints, Vertex project/location, Bedrock config, cache retention, proxies — applied without changing the project shell.
 
 ## Credential Resolution Order
 
@@ -74,8 +86,10 @@ Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Goog
 ```bash
 export AZURE_OPENAI_API_KEY=...
 export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
-# Cognitive Services endpoints are also supported and auto-normalized to /openai/v1:
+# Cognitive Services and modern Microsoft Foundry endpoint URLs are also
+# supported; root endpoints are auto-normalized to /openai/v1:
 # export AZURE_OPENAI_BASE_URL=https://your-resource.cognitiveservices.azure.com
+# export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
 # Or supply the resource name only:
 export AZURE_OPENAI_RESOURCE_NAME=your-resource
 
@@ -153,6 +167,8 @@ Use `models.json` for OpenAI-compatible, Anthropic-compatible, Google-compatible
 }
 ```
 
+`apiKey` is optional (Pi 0.80.0): omit it when auth comes from `/login`, `auth.json`, or CLI `--api-key`. Like `auth.json` keys, `apiKey` and `headers` values support `!command` execution and `$ENV_VAR` interpolation; plain uppercase strings are literals. Keyless local servers (e.g. Ollama) should keep a dummy value so their models appear in `/model`.
+
 Common `api` values:
 
 - `"openai-completions"`
@@ -168,7 +184,7 @@ Common `api` values:
 
 - `thinkingLevelMap` (Pi 0.72) replaces `compat.reasoningEffortMap`. Map pi levels (`off`/`minimal`/`low`/`medium`/`high`/`xhigh`) to provider values; use `null` to hide a level.
 - `openRouterRouting` is forwarded as-is in the OpenRouter `provider` field (fallbacks, ZDR, ignore lists, throughput/latency).
-- `compat.thinkingFormat` supports OpenAI-compatible reasoning variants: `openrouter` sends `reasoning: { effort }`, `together` sends `reasoning: { enabled }` plus `reasoning_effort` when supported, and `qwen-chat-template` targets local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking`.
+- `compat.thinkingFormat` supports OpenAI-compatible reasoning variants: `openrouter` sends `reasoning: { effort }`, `together` sends `reasoning: { enabled }` plus `reasoning_effort` when supported, `qwen-chat-template` targets local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking`, and `chat-template` (Pi 0.79.9) sends configurable `chat_template_kwargs` via `compat.chatTemplateKwargs` — e.g. `{ "thinking": { "$var": "thinking.enabled" } }` for DeepSeek models behind vLLM/Hugging Face chat templates (`"$var"` accepts `"thinking.enabled"` or `"thinking.effort"`).
 - Advanced `compat` flags exist for proxy quirks (`cacheControlFormat`, `supportsReasoningEffort`, `supportsLongCacheRetention`, `supportsEagerToolInputStreaming`, `sendSessionIdHeader`, `sendSessionAffinityHeaders`). See [Pi `docs/models.md`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md) when a proxy rejects pi's defaults.
 
 ### Context Overflow Recovery

package/skills/pi/references/sdk.md

@@ -51,9 +51,11 @@ import {
   ModelRegistry,
   SessionManager,
 } from "@earendil-works/pi-coding-agent";
-import { getModel } from "@earendil-works/pi-ai";
+import { getBuiltinModel } from "@earendil-works/pi-ai/providers/all";
 ```
 
+**pi-ai 0.80.0 API move:** the old global API (`getModel`, `getModels`, `getProviders`, `stream`, `complete`, `completeSimple`, `registerApiProvider`, `getEnvApiKey`, ...) moved off the `@earendil-works/pi-ai` root entrypoint to `@earendil-works/pi-ai/compat` (a deprecated shim slated for removal). For built-in model lookup use `getBuiltinModel(provider, modelId)` from `@earendil-works/pi-ai/providers/all`, or the provider-factory API (`createModels()` / `Models.getModel()`). Extensions loaded by Pi are unaffected at runtime — the extension loader aliases the pi-ai root to the compat superset — but standalone SDK scripts and typechecked extension sources must use the new paths. The selective `@earendil-works/pi-ai/base` / `@earendil-works/pi-agent-core/base` entrypoints introduced in 0.79.8 were removed again in 0.80.0.
+
 ## Core Options
 
 ```typescript
@@ -66,10 +68,10 @@ const { session } = await createAgentSession({
   agentDir: "~/.pi/agent",
   authStorage,
   modelRegistry,
-  model: getModel("anthropic", "claude-opus-4-7"),
+  model: getBuiltinModel("anthropic", "claude-opus-4-8"),
   thinkingLevel: "medium",
   scopedModels: [
-    { model: getModel("anthropic", "claude-opus-4-7"), thinkingLevel: "high" },
+    { model: getBuiltinModel("anthropic", "claude-opus-4-8"), thinkingLevel: "high" },
   ],
   tools: ["read", "bash", "edit", "write"],
   customTools: [/* defineTool(...) entries */],
@@ -204,6 +206,18 @@ session.subscribe((event) => {
 });
 ```
 
+`compaction_end` results and RPC `compact` responses include estimated post-compaction token counts (Pi 0.79.8) so clients can show the approximate context reduction.
+
+## RPC Mode
+
+`pi --mode rpc` speaks newline-delimited JSON over stdio. Additions since Pi 0.79:
+
+- `get_entries` / `get_tree` (Pi 0.80.3) read session entries and tree snapshots over RPC.
+- `@earendil-works/pi-coding-agent/rpc-entry` (Pi 0.80.3) launches Pi directly in RPC mode from an importing process.
+- RPC extension UI request/response types are exported from the public API (Pi 0.79.0).
+- Package asset path helpers are exported from the public API (Pi 0.79.0).
+- `CONFIG_DIR_NAME` and edit diff helpers (`generateDiffString`, `generateUnifiedPatch`, `EditDiffResult`) are exported for extensions and hosts (Pi 0.79.7).
+
 ## Resource Loader Hooks
 
 `DefaultResourceLoader` supports overrides for extensions, skills, prompts, themes, and context files. Common patterns:

package/skills/pi/references/settings.md

@@ -39,14 +39,19 @@ Edit JSON directly or use `/settings` for common interactive options.
   "doubleEscapeAction": "tree",
   "treeFilterMode": "default",
   "editorPaddingX": 0,
+  "outputPad": 1,
   "autocompleteMaxVisible": 5,
-  "showHardwareCursor": false
+  "showHardwareCursor": false,
+  "externalEditor": "code --wait"
 }
 ```
 
 - `doubleEscapeAction`: `"tree"`, `"fork"`, or `"none"`
 - `treeFilterMode`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, or `"all"`
 - In `/tree`, `Shift+T` toggles timestamps on entry labels
+- `theme` also accepts `"light-name/dark-name"` (Pi 0.79.7) to switch themes automatically with the terminal color scheme; `/` is reserved in theme names for this. On first run Pi detects the terminal background and defaults to `dark` or `light`.
+- `outputPad` (Pi 0.80.3, `0` or `1`) sets horizontal padding for user messages, assistant messages, and thinking blocks.
+- `externalEditor` (Pi 0.80.3) sets the `Ctrl+G` external editor command and takes precedence over `$VISUAL`/`$EDITOR`.
 
 ## Compaction, Branch Summary, Retry
 
@@ -65,11 +70,10 @@ Edit JSON directly or use `/settings` for common interactive options.
     "enabled": true,
     "maxRetries": 3,
     "baseDelayMs": 2000,
-    "maxDelayMs": 60000,
     "provider": {
-      "timeoutMs": 0,
+      "timeoutMs": 3600000,
       "maxRetries": 0,
-      "maxRetryDelayMs": 0
+      "maxRetryDelayMs": 60000
     }
   }
 }
@@ -77,8 +81,9 @@ Edit JSON directly or use `/settings` for common interactive options.
 
 Notes:
 
-- `retry.maxDelayMs = 0` disables the cap on server-requested retry delays.
-- `retry.provider.*` (Pi 0.70.1) controls the underlying provider SDK's request timeout and retry/backoff — useful for slow local LLMs and flaky proxies. Pi forwards these into `streamSimple` request options when set.
+- `retry.maxRetries` (default `3`) and `retry.baseDelayMs` (default `2000`) govern Pi's own agent-level retry with exponential backoff.
+- `retry.provider.*` controls the underlying provider SDK's request timeout and retry/backoff — useful for slow local LLMs and flaky proxies. `retry.provider.timeoutMs` sets the SDK request timeout; `retry.provider.maxRetries` defaults to `0` (keep it there unless you need SDK-level retries, since raising it can let provider retries swallow usage-limit errors before Pi handles them).
+- `retry.provider.maxRetryDelayMs` (default `60000`) caps how long a server-requested retry delay can be before the request fails immediately with an informative error; set to `0` to disable the cap. The old top-level `retry.maxDelayMs` was renamed to this and is auto-migrated.
 - `branchSummary.skipPrompt` skips the confirmation step when navigating with `/tree`.
 
 ## Message Delivery
@@ -87,12 +92,18 @@ Notes:
 {
   "steeringMode": "one-at-a-time",
   "followUpMode": "one-at-a-time",
-  "transport": "sse"
+  "transport": "auto",
+  "httpIdleTimeoutMs": 300000,
+  "websocketConnectTimeoutMs": 15000,
+  "httpProxy": "http://127.0.0.1:7890"
 }
 ```
 
 - `steeringMode` and `followUpMode`: `"all"` or `"one-at-a-time"`
-- `transport`: `"sse"`, `"websocket"`, or `"auto"`
+- `transport` (default `"auto"`): `"sse"`, `"websocket"`, `"websocket-cached"`, or `"auto"` — the preferred transport for providers that support several
+- `httpIdleTimeoutMs` (default `300000`) is the HTTP header/body idle timeout, also applied as the default SDK request timeout for providers that support it (e.g. OpenAI Codex WebSocket waits, llama.cpp). Set to `0` to disable.
+- `websocketConnectTimeoutMs` (default `15000`) bounds the WebSocket connect/open handshake. Set to `0` to disable.
+- `httpProxy` (Pi 0.79.5, global settings only) is applied as `HTTP_PROXY` and `HTTPS_PROXY` for Pi-managed HTTP clients.
 
 ## Terminal, Images, and Shell
 
@@ -143,6 +154,21 @@ Notes:
 
 When multiple sources specify a session directory, `--session-dir` takes precedence over `sessionDir` in settings. Pi 0.65.0 removed the old `session_directory` extension/settings hook.
 
+## Project Trust
+
+Since Pi 0.79.0, project-local settings, resources, and packages (`.pi/` settings/extensions/skills/prompts/themes, project packages) only load after the project is trusted. `AGENTS.md` / `CLAUDE.md` context files load regardless of trust. Trust is a loading gate, not a sandbox.
+
+```json
+{
+  "defaultProjectTrust": "ask"
+}
+```
+
+- Interactive mode prompts on first use; `/trust` saves a decision (written to `~/.pi/agent/trust.json`; restart Pi to apply).
+- `--approve`/`-a` and `--no-approve`/`-na` override trust for one run, including for `pi install` and other package commands. `pi update` never prompts.
+- Non-interactive modes (`-p`, `--mode json`, `--mode rpc`) never prompt. Without a saved decision they follow `defaultProjectTrust` (global setting only): `"ask"` (default) and `"never"` skip project resources; `"always"` trusts them.
+- Extensions can decide or defer trust via the `project_trust` event and inspect the outcome with `ctx.isProjectTrusted()` — see `references/extensions.md`.
+
 ## Resources
 
 These settings control what Pi loads from disk or packages:
@@ -218,12 +244,15 @@ pi [options] [@files...] [messages...]
 -c, --continue                   continue most recent session
 -r, --resume                     browse and select
 --session <path|id>
+--session-id <id>                use an exact project-local session id, creating it if missing
 --fork <path|id>
 --session-dir <dir>
+-n, --name <name>                set the session display name at startup
 --no-session                     ephemeral
 
 # tools and resources
 --tools <list>, -t               name allowlist (read,bash,edit,write,grep,find,ls,...)
+--exclude-tools <list>, -xt      disable specific built-in/extension/custom tools, keep the rest
 --no-tools, -nt                  disable everything
 --no-builtin-tools, -nbt         disable built-ins, keep extension/custom
 -e, --extension <source>         repeatable; npm/git/path
@@ -233,6 +262,11 @@ pi [options] [@files...] [messages...]
 --no-extensions / --no-skills / --no-prompt-templates / --no-themes
 --no-context-files, -nc          skip AGENTS.md / CLAUDE.md discovery
 
+# trust and network
+-a, --approve                    trust project-local files for this run
+-na, --no-approve                ignore project-local files for this run
+--offline                        disable startup network operations (same as PI_OFFLINE=1)
+
 # prompts and misc
 --system-prompt <text>           replace default
 --append-system-prompt <text>    repeatable; appended with double newlines
@@ -248,11 +282,11 @@ pi [options] [@files...] [messages...]
 | `PI_PACKAGE_DIR` | Override package storage directory |
 | `PI_SKIP_VERSION_CHECK` | Skip the `pi.dev` latest-version request at startup |
 | `PI_OFFLINE` | Disable all startup network operations (update checks, telemetry) |
-| `PI_TELEMETRY` | Force install telemetry on/off (`1`/`0`); does not gate update checks |
+| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers (`1`/`0`); does not gate update checks |
 | `PI_CACHE_RETENTION` | Set to `long` for extended prompt-cache retention where supported |
 | `PI_OAUTH_CALLBACK_HOST` | Bind the OAuth callback server to a custom interface |
 | `PI_CODING_AGENT=true` | Set automatically at startup so subprocesses can detect Pi |
-| `VISUAL`, `EDITOR` | External editor for `Ctrl+G` |
+| `VISUAL`, `EDITOR` | External editor for `Ctrl+G` (the `externalEditor` setting takes precedence) |
 | Provider API key env vars | See `references/providers.md` |
 
 ## Practical Notes

package/skills/pi/references/skills.md

@@ -18,7 +18,7 @@ Pi discovers skills from:
 - Global:
   - `~/.pi/agent/skills/`
   - `~/.agents/skills/`
-- Project:
+- Project (loaded only after the project is trusted; see project trust in `references/settings.md`):
   - `.pi/skills/`
   - `.agents/skills/` in `cwd` and ancestor directories
 - Packages: