1st-pi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 est7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# 1st-pi
+
+[est7](https://github.com/est7) 的 [Pi](https://pi.dev) coding agent preset。
+
+这是一个 Pi Package，用来统一打包和分发常用的 **extensions / skills / prompts / themes**。安装后，Pi 会自动加载本仓库资源以及声明的 bundled Pi packages。
+
+> **Security:** Pi packages 拥有完整系统权限。Extensions 可以执行任意代码，skills 可以指示模型执行操作。安装第三方包前请审阅源码。
+
+## 安装
+
+### GitHub
+
+```bash
+pi install git:github.com/est7/1st-pi
+# 或
+pi install https://github.com/est7/1st-pi
+```
+
+### 本地开发
+
+```bash
+pi install /absolute/path/to/1st-pi
+# 当前目录
+pi install .
+```
+
+### npm
+
+```bash
+pi install npm:1st-pi
+```
+
+仅在当前会话试用，不写入 settings：
+
+```bash
+pi -e .
+pi -e git:github.com/est7/1st-pi
+```
+
+安装为项目级依赖，写入 `.pi/settings.json`：
+
+```bash
+pi install -l .
+```
+
+## 管理
+
+```bash
+pi list
+pi config
+pi update --extensions
+pi remove git:github.com/est7/1st-pi
+```
+
+## 目录结构
+
+```text
+1st-pi/
+├── package.json          # Pi package manifest
+├── extensions/           # 本地 UI 与 community package thin adapters
+├── skills/               # skills/<name>/SKILL.md
+├── prompts/              # Markdown prompt templates
+└── themes/               # 从 pi-everforest-tui 同步并校验的 theme resources
+```
+
+## 添加自己的资源
+
+- `extensions/*.ts`：自定义工具、命令、事件和 UI
+- `skills/<name>/SKILL.md`：可自动发现或通过 `/skill:name` 调用的技能
+- `prompts/*.md`：通过 `/文件名` 调用的提示词模板
+
+修改资源后，在 Pi 中运行 `/reload`，或重新执行：
+
+```bash
+pi -e .
+```
+
+## Everforest themes
+
+本 preset 通过独立 package [`pi-everforest-tui`](https://github.com/est7/pi-everforest-tui) 提供两个 Ghostty Everforest Soft 风格的 Pi TUI theme：
+
+- `everforest-tui-dark`
+- `everforest-tui-light`
+
+Preset 默认开启以下 TUI 增强，session 中持久化的个人选择优先于 preset 默认值：
+
+- phase-aware working indicator
+- 仅在工作期间出现的 status（idle 不显示，不重复 model）
+- 响应式 cockpit footer 与完整 segment 的 extension statuses
+- 连续 Everforest 彩虹 editor 边框与具名 session badge
+
+相关命令：
+
+```text
+/everforest             # 搜索全部 extension、prompt、skill commands
+/everforest-tui         # 打开交互式 TUI 设置
+/everforest-theme-lab   # 预览主题语义色、Markdown、diff、syntax 与 thinking states
+```
+
+也可直接执行 `/everforest-tui all on|off` 或针对 `indicator`、`status`、`footer`、`rainbow` 单独设置。
+
+可在 `/settings` 中手动选择 theme。要像 Ghostty 一样随终端背景自动切换，在 Pi 的 `settings.json` 中设置：
+
+```json
+{
+  "theme": "everforest-tui-light/everforest-tui-dark"
+}
+```
+
+斜杠前是 light theme，斜杠后是 dark theme。
+
+## Custom header
+
+`extensions/custom-header.ts` 使用 `1st-agent` ASCII wordmark 替换 Pi 默认启动 header。需要临时恢复默认 header 时运行：
+
+```text
+/builtin-header
+```
+
+## 内置依赖
+
+| 包 | 功能 |
+|---|---|
+| [pi-web-access](https://www.npmjs.com/package/pi-web-access) | Web 搜索、URL/GitHub/YouTube 访问及 librarian skill |
+| [pi-init](https://www.npmjs.com/package/pi-init) | 生成或更新 `AGENTS.md` 的 init skill |
+| [pi-mcp-adapter](https://www.npmjs.com/package/pi-mcp-adapter) | MCP 协议适配 |
+| [pi-everforest-tui](https://www.npmjs.com/package/pi-everforest-tui) | Everforest light/dark themes 与可选 TUI 增强 |
+| [pi-session-name](https://www.npmjs.com/package/pi-session-name) | 自动生成会话标题并同步终端标题 |
+| [@juicesharp/rpiv-ask-user-question](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question) | 多问题、选项预览和自由输入的结构化提问 UI |
+| [@narumitw/pi-goal](https://www.npmjs.com/package/@narumitw/pi-goal) | Session-scoped `/goal` 持续执行与完成/阻塞门禁 |
+| [pi-observational-memory](https://www.npmjs.com/package/pi-observational-memory) | 跨压缩保留 observations/reflections 的长会话记忆 |
+| [@ff-labs/pi-fff](https://www.npmjs.com/package/@ff-labs/pi-fff) | 本地 Rust 模糊文件/内容搜索与 `@` 自动补全 |
+| [pi-readseek](https://www.npmjs.com/package/pi-readseek) | Parser-backed code map/search、definition/reference、hashline edit 与 workspace rename；其 edit 可进行带警告的 fuzzy anchor relocation，不等同于严格 stale rejection |
+| [pi-btw](https://www.npmjs.com/package/pi-btw) | 不污染主上下文的并行 `/btw` 旁路对话 |
+| [@mrclrchtr/supi-context](https://www.npmjs.com/package/@mrclrchtr/supi-context) | `/supi-context` 上下文组成与 token 占用报告 |
+| [@tintinweb/pi-subagents](https://www.npmjs.com/package/@tintinweb/pi-subagents) | Claude Code 风格 sub-agents |
+| [@tintinweb/pi-tasks](https://www.npmjs.com/package/@tintinweb/pi-tasks) | Task tracking 与协作 |
+| [@quintinshaw/pi-dynamic-workflows](https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows) | 动态 workflows |
+
+这些包位于普通 npm `dependencies`，安装 preset 时由 npm 获取，不会塞入 `1st-pi` tarball。`extensions/packages/*.ts` 是只负责调用 dependency extension entrypoint 的 thin adapters；因此依赖可以正常 hoist，同时 Pi manifest 只引用本包内稳定路径。FFF 也会由 npm 在 macOS、Linux 和 Windows 上选择正确的原生 binary。
+
+Themes 以及 `pi-init` / `pi-web-access` skills 是发布所需的静态资源，会从锁定依赖同步到本包。更新 dependencies 后运行：
+
+```bash
+npm run sync:resources
+npm run check:resources
+```
+
+`prepack` 会执行相同校验，防止静态副本与依赖版本漂移。
+
+TUI 与 tool ownership：
+
+- `pi-everforest-tui`：全局主题、editor chrome、working/status/footer、Command Center 与 Theme Lab
+- `@ff-labs/pi-fff`：preset 默认使用 `override` mode，由 FFF 接管 `find`、`grep` 与 `@` autocomplete
+- `pi-readseek`：通过 `readseek.replacedTools` 接管 `read`、`edit`、`write`；结构导航和 hashline 工具继续使用 `readSeek_*` 名称，不与 FFF 争夺 `grep`
+- Pi built-ins：继续负责 `bash`、`ls` 及其原生渲染
+- `pi-mcp-adapter`：负责 MCP 工具与渲染
+- Tasks、Subagents、Workflows、Goal、BTW、Context 与 Memory：继续使用各 package 自己的领域 UI
+
+`pi-tool-display` 已移除，因为它会注册同名的 `read/edit/write/find/grep` overrides，与 Readseek/FFF 形成双重 owner。
+
+要启用上述 Readseek ownership，在 `~/.pi/agent/settings.json` 中加入：
+
+```json
+{
+  "readseek": {
+    "replacedTools": ["read", "edit", "write"]
+  }
+}
+```
+
+`grep` 不加入该数组，因为它由 FFF 接管。修改后运行 `/reload`。
+
+## Preset maintenance skill
+
+添加或移除 community extension 时使用：
+
+```text
+/skill:add-extension-to-1st-agent
+```
+
+该 SOP 覆盖 license/compatibility/ownership gate、thin adapter、README 同步、hoisted npm 安装、native binary、tarball size 与 clean-room smoke tests。
+
+## 发布
+
+```bash
+npm login
+npm publish
+```
+
+发布前建议检查包内容：
+
+```bash
+npm pack --dry-run
+```
+
+## License
+
+MIT

package/extensions/custom-header.ts

@@ -0,0 +1,157 @@
+/**
+ * 1st Agent Header
+ *
+ * Replaces Pi's built-in header with a branded welcome panel.
+ */
+
+import { basename } from "node:path";
+import { VERSION, type ExtensionAPI, type Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+const WORDMARK = [
+	"   ___     __                               __ ",
+	"  <  /____/ /_      ____ _____ ____  ____  / /_",
+	"  / / ___/ __/_____/ __ `/ __ `/ _ \\/ __ \\/ __/",
+	" / (__  ) /_/_____/ /_/ / /_/ /  __/ / / / /_  ",
+	"/_/____/\\__/      \\__,_/\\__, /\\___/_/ /_/\\__/  ",
+	"                       /____/",
+];
+
+const MASCOT = [
+	"    ▄▄▄    ",
+	"  ▄█████▄  ",
+	" ▐██ ◉ ██▌ ",
+	"  ▀█████▀  ",
+	"   ▀█ █▀   ",
+	"    ▀ ▀    ",
+];
+
+const MAX_PANEL_WIDTH = 110;
+const WORDMARK_WIDTH = Math.max(...WORDMARK.map((line) => visibleWidth(line)));
+const MASCOT_WIDTH = Math.max(...MASCOT.map((line) => visibleWidth(line)));
+
+type Alignment = "left" | "center";
+
+interface HeaderMeta {
+	cwd: string;
+	model: string;
+	thinking: string;
+}
+
+function colorizeWordmark(theme: Theme, line: string): string {
+	const paddedLine = line.padEnd(WORDMARK_WIDTH);
+	const firstBreak = Math.min(18, paddedLine.length);
+	const secondBreak = Math.min(36, paddedLine.length);
+
+	return [
+		theme.fg("warning", paddedLine.slice(0, firstBreak)),
+		theme.fg("accent", paddedLine.slice(firstBreak, secondBreak)),
+		theme.fg("success", paddedLine.slice(secondBreak)),
+	].join("");
+}
+
+function colorizeMascot(theme: Theme, line: string, row: number): string {
+	const colors = ["warning", "warning", "accent", "accent", "success", "success"] as const;
+	return theme.bold(theme.fg(colors[row], line.padEnd(MASCOT_WIDTH)));
+}
+
+function panelLine(theme: Theme, content: string, innerWidth: number, alignment: Alignment = "left"): string {
+	const clipped = truncateToWidth(content, innerWidth, "");
+	const padding = Math.max(0, innerWidth - visibleWidth(clipped));
+	const leftPadding = alignment === "center" ? Math.floor(padding / 2) : Math.min(1, padding);
+	const rightPadding = padding - leftPadding;
+
+	return [
+		theme.fg("borderAccent", "│"),
+		" ".repeat(leftPadding),
+		clipped,
+		" ".repeat(rightPadding),
+		theme.fg("borderAccent", "│"),
+	].join("");
+}
+
+function topBorder(theme: Theme, innerWidth: number): string {
+	const title = " 1ST AGENT ";
+	const prefix = "╭───";
+	const suffix = "╮";
+	const fill = Math.max(0, innerWidth + 2 - visibleWidth(prefix) - visibleWidth(title) - visibleWidth(suffix));
+
+	if (fill === 0) return theme.fg("borderAccent", `╭${"─".repeat(innerWidth)}╮`);
+
+	return [
+		theme.fg("borderAccent", prefix),
+		theme.bold(theme.fg("warning", title)),
+		theme.fg("borderAccent", `${"─".repeat(fill)}${suffix}`),
+	].join("");
+}
+
+function divider(theme: Theme, innerWidth: number): string {
+	return theme.fg("borderAccent", `├${"─".repeat(innerWidth)}┤`);
+}
+
+function bottomBorder(theme: Theme, innerWidth: number): string {
+	return theme.fg("borderAccent", `╰${"─".repeat(innerWidth)}╯`);
+}
+
+function buildHeader(theme: Theme, width: number, meta: HeaderMeta): string[] {
+	if (width < 2) return [];
+
+	const panelWidth = Math.min(width, MAX_PANEL_WIDTH);
+	const innerWidth = panelWidth - 2;
+	const lockupWidth = MASCOT_WIDTH + 3 + WORDMARK_WIDTH;
+	const showMascot = innerWidth >= lockupWidth + 4;
+	const lines = ["", topBorder(theme, innerWidth), panelLine(theme, "", innerWidth)];
+
+	for (let row = 0; row < WORDMARK.length; row++) {
+		const wordmark = colorizeWordmark(theme, WORDMARK[row]);
+		const lockup = showMascot ? `${colorizeMascot(theme, MASCOT[row], row)}   ${wordmark}` : wordmark;
+		lines.push(panelLine(theme, lockup, innerWidth, "center"));
+	}
+
+	lines.push(panelLine(theme, "", innerWidth));
+	lines.push(divider(theme, innerWidth));
+	lines.push(
+		panelLine(
+			theme,
+			`${theme.bold(theme.fg("accent", "EST7"))}${theme.fg("dim", " // FIELD UNIT 01 // FIRST IN, LAST OUT")}`,
+			innerWidth,
+			"center",
+		),
+	);
+	lines.push(
+		panelLine(
+			theme,
+			theme.fg("muted", `${meta.cwd}  ·  ${meta.model}  ·  thinking ${meta.thinking}  ·  π v${VERSION}`),
+			innerWidth,
+			"center",
+		),
+	);
+	lines.push(bottomBorder(theme, innerWidth), "");
+
+	return lines;
+}
+
+export default function customHeader(pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+
+		const meta: HeaderMeta = {
+			cwd: basename(ctx.cwd) || ctx.cwd,
+			model: ctx.model?.id ?? "no model",
+			thinking: pi.getThinkingLevel(),
+		};
+
+		ctx.ui.setHeader((_tui, theme) => ({
+			render: (width: number) => buildHeader(theme, width, meta),
+			invalidate() {},
+		}));
+	});
+
+	pi.registerCommand("builtin-header", {
+		description: "Restore Pi's built-in header",
+		handler: async (_args, ctx) => {
+			ctx.ui.setHeader(undefined);
+			ctx.ui.notify("Built-in header restored", "info");
+		},
+	});
+}

package/extensions/everforest-defaults.ts

@@ -0,0 +1,17 @@
+/**
+ * 1st-pi defaults for the bundled pi-everforest-tui package.
+ *
+ * Standalone installs stay opt-in. Fresh 1st-pi sessions start with the full
+ * Everforest TUI experience, while session-persisted user choices still win.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function everforestDefaults(pi: ExtensionAPI) {
+	pi.events.emit("everforest-tui:defaults", {
+		indicator: true,
+		status: true,
+		footer: true,
+		rainbow: true,
+	});
+}

package/extensions/packages/ask-user.ts

@@ -0,0 +1 @@
+export { default } from "@juicesharp/rpiv-ask-user-question";

package/extensions/packages/btw.ts

@@ -0,0 +1 @@
+export { default } from "pi-btw/extensions/btw.ts";

package/extensions/packages/everforest.ts

@@ -0,0 +1 @@
+export { default } from "pi-everforest-tui/extensions/everforest-tui.ts";

package/extensions/packages/fff.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerFff from "@ff-labs/pi-fff/src/index.ts";
+
+export default function fffAdapter(pi: ExtensionAPI): void {
+  const configuredMode = process.env.PI_FFF_MODE;
+  if (!configuredMode) process.env.PI_FFF_MODE = "override";
+  try {
+    registerFff(pi);
+  } finally {
+    if (!configuredMode) delete process.env.PI_FFF_MODE;
+  }
+}

package/extensions/packages/goal.ts

@@ -0,0 +1 @@
+export { default } from "@narumitw/pi-goal/src/goal.ts";

package/extensions/packages/mcp-adapter.ts

@@ -0,0 +1 @@
+export { default } from "pi-mcp-adapter/index.ts";

package/extensions/packages/observational-memory.ts

@@ -0,0 +1 @@
+export { default } from "pi-observational-memory/src/index.ts";

package/extensions/packages/readseek.ts

@@ -0,0 +1 @@
+export { default } from "pi-readseek";

package/extensions/packages/session-name.ts

@@ -0,0 +1 @@
+export { default } from "pi-session-name/src/index.ts";

package/extensions/packages/subagents.ts

@@ -0,0 +1 @@
+export { default } from "@tintinweb/pi-subagents/src/index.ts";

package/extensions/packages/supi-context.ts

@@ -0,0 +1 @@
+export { default } from "@mrclrchtr/supi-context/extension";

package/extensions/packages/tasks.ts

@@ -0,0 +1 @@
+export { default } from "@tintinweb/pi-tasks/src/index.ts";

package/extensions/packages/web-access.ts

@@ -0,0 +1 @@
+export { default } from "pi-web-access/index.ts";

package/extensions/packages/workflow.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default async function workflowAdapter(pi: ExtensionAPI): Promise<void> {
+  const packageEntry = import.meta.resolve("@quintinshaw/pi-dynamic-workflows");
+  const extensionUrl = new URL("../extensions/workflow.ts", packageEntry);
+  const { default: registerWorkflow } = await import(extensionUrl.href);
+  registerWorkflow(pi);
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "1st-pi",
+  "version": "0.1.0",
+  "description": "est7's Pi coding agent preset — skills, extensions, prompts, and themes.",
+  "license": "MIT",
+  "author": "est7",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-agent",
+    "preset",
+    "skills",
+    "extensions",
+    "prompts",
+    "themes"
+  ],
+  "files": [
+    "extensions",
+    "skills",
+    "prompts",
+    "themes",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/est7/1st-pi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/est7/1st-pi/issues"
+  },
+  "homepage": "https://github.com/est7/1st-pi#readme",
+  "dependencies": {
+    "@ff-labs/pi-fff": "^0.9.6",
+    "@juicesharp/rpiv-ask-user-question": "^1.20.0",
+    "@mrclrchtr/supi-context": "^2.4.0",
+    "@narumitw/pi-goal": "^0.15.1",
+    "@quintinshaw/pi-dynamic-workflows": "^2.13.1",
+    "@tintinweb/pi-subagents": "^0.14.1",
+    "@tintinweb/pi-tasks": "^0.7.1",
+    "pi-btw": "^0.4.1",
+    "pi-everforest-tui": "^0.2.0",
+    "pi-init": "^1.0.0",
+    "pi-mcp-adapter": "^2.11.0",
+    "pi-observational-memory": "^3.0.3",
+    "pi-readseek": "^0.6.6",
+    "pi-session-name": "^0.1.2",
+    "pi-web-access": "^0.13.0"
+  },
+  "scripts": {
+    "sync:resources": "node scripts/sync-package-resources.mjs",
+    "check:resources": "node scripts/sync-package-resources.mjs --check",
+    "prepack": "npm run check:resources",
+    "pack:dry-run": "npm pack --dry-run --json"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/packages/workflow.ts",
+      "./extensions/packages/everforest.ts",
+      "./extensions/everforest-defaults.ts",
+      "./extensions/custom-header.ts",
+      "./extensions/packages/ask-user.ts",
+      "./extensions/packages/goal.ts",
+      "./extensions/packages/observational-memory.ts",
+      "./extensions/packages/fff.ts",
+      "./extensions/packages/readseek.ts",
+      "./extensions/packages/btw.ts",
+      "./extensions/packages/supi-context.ts",
+      "./extensions/packages/web-access.ts",
+      "./extensions/packages/mcp-adapter.ts",
+      "./extensions/packages/session-name.ts",
+      "./extensions/packages/tasks.ts",
+      "./extensions/packages/subagents.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  }
+}

package/skills/add-extension-to-1st-agent/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: add-extension-to-1st-agent
+description: Add, update, trial, or remove a community Pi extension in the 1st-pi preset without creating duplicate owners, bloating the tarball, breaking hoisted npm installs, or drifting the README. Use whenever changing 1st-pi package dependencies or extension inventory.
+---
+
+# Add an extension to 1st-pi
+
+Follow this SOP; do not add a package from its README alone.
+
+## 1. Gate the candidate
+
+Check the published package and primary source:
+
+- npm version, license, repository, engines, peer dependencies, install scripts
+- upstream Pi/Node compatibility and native platform coverage
+- maintenance and release recency
+- tool, command, editor, footer, renderer, persistence, and domain ownership overlap
+
+Reject duplicate owners unless the user explicitly chooses which existing owner to remove or disable.
+
+## 2. Install as a normal dependency
+
+```bash
+npm install <package>@<version>
+```
+
+Do **not** add `bundledDependencies`. npm installs runtime dependencies; bundling their transitive graph bloats the preset.
+
+## 3. Add a thin adapter
+
+Create `extensions/packages/<name>.ts`:
+
+```ts
+export { default } from "<package-or-exported-subpath>";
+```
+
+Reference that local adapter explicitly in `package.json#pi.extensions`. Keep owner-sensitive ordering explicit. If package exports block its extension subpath, resolve its public entry and use the smallest documented dynamic adapter; do not copy the package implementation.
+
+Static skills/themes needed by Pi must live inside this package. Add them to `scripts/sync-package-resources.mjs` so `npm run check:resources` prevents dependency drift.
+
+## 4. Resolve ownership before testing
+
+For every built-in or shared surface, record one owner only:
+
+- tool names such as `read`, `edit`, `write`, `find`, `grep`
+- tool/diff renderers
+- editor factory, footer, status, and overlays
+- memory, tasks, subagents, workflows, goals, and context analysis
+
+Never rely on load order to hide a registration conflict. Remove, disable, or configure the losing owner deliberately.
+
+## 5. Keep documentation synchronized
+
+Update `README.md` in the same change:
+
+- dependency inventory and purpose
+- defaults and commands/tools
+- ownership and overlap decisions
+- native, license, fuzzy/stale, telemetry, or external-process caveats
+- removal instructions when configuration persists outside the package
+
+Update relevant audits when a prior recommendation or ownership baseline changed.
+
+## 6. Verify both layouts
+
+Run:
+
+```bash
+npm run check:resources
+npm audit --omit=dev
+npm pack --dry-run --json
+git diff --check
+```
+
+Then verify:
+
+1. local source: `pi --no-extensions -e .`
+2. packed tarball installed into a fresh npm project with dependencies hoisted beside `1st-pi`
+3. Pi loading the installed `node_modules/1st-pi`
+4. no extension/tool/command conflicts
+5. native binary availability on the current platform
+6. package size remains within the small preset budget
+7. `/reload` and the candidate's primary command/tool path
+
+A startup-only test is insufficient for mutating, native, persistence, or network behavior; exercise its risky path in a disposable fixture.
+
+## 7. Finish or revert
+
+If verification passes, commit dependency, lockfile, adapter, resources, tests, and README together. If it fails, remove the package and adapter completely; do not leave disabled or undocumented inventory behind.

package/skills/init/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: init
+description: Initialize or update AGENTS.md. Guides the agent to autonomously analyze the codebase and generate a high-quality context file.
+---
+
+# Init Skill
+
+This skill defines the standard for creating an `AGENTS.md` file. Instead of following a rigid script, use your judgment and exploration tools to understand the project deeply before documenting it.
+
+## Objective
+Create a "readme for robots" (`AGENTS.md`) that accelerates understanding for future AI sessions. It must include the project's stack, structure, workflows, and coding standards.
+
+## Workflow
+
+### 1. Autonomous Discovery
+Explore the repository to build a mental model of the project. You determine which files to read.
+
+*   **Identify Stack**: Determine the languages, frameworks, and build tools in use.
+*   **Extract Workflows**: Find the commands for **installing dependencies**, **running tests**, **building**, and **starting** the project.
+*   **Map Structure**: Understand the layout. identify source roots, test directories, and documentation.
+*   **Infer Conventions**: Read sample source files to identify coding styles, formatting rules (prettier/eslint/ruff), and architectural patterns (e.g., "functional components", "repository pattern").
+
+### 2. Synthesize & Generate
+Create or update `AGENTS.md` with your findings.
+
+#### Target Structure (Template)
+Use this structure as a baseline, but adapt it if the project has unique needs.
+
+```markdown
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** {CURRENT_DATE}
+
+## OVERVIEW
+Project: **{PROJECT_NAME}**
+Stack: {TECHNOLOGIES_AND_VERSIONS}
+
+## STRUCTURE
+{TREE_VIEW_OR_KEY_DIRECTORIES_LIST}
+*   `{DIR}`: {DESCRIPTION}
+
+## COMMANDS
+| Action | Command |
+|--------|---------|
+| Install| `{CMD}` |
+| Test   | `{CMD}` |
+| Build  | `{CMD}` |
+| Run    | `{CMD}` |
+
+## CODING STANDARDS
+*   **Language**: {LANGUAGE_DETAILS}
+*   **Style**: {OBSERVED_PATTERNS}
+*   **Rules**: {LINTER_OR_FORMATTER_INFO}
+
+## WHERE TO LOOK
+*   **Source**: `{PATH}`
+*   **Tests**: `{PATH}`
+*   **Docs**: `{PATH}`
+
+## NOTES
+*   {CRITICAL_CONTEXT_OR_GOTCHAS}
+```
+
+### 3. Integration
+*   **Update intelligently**: If `AGENTS.md` exists, read it first. Merge new insights without overwriting human-authored context.
+*   **Context sharing**: If meaningful, mention other context files found (e.g., `.cursorrules`, `CLAUDE.md`).

package/skills/librarian/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: librarian
+description: Research open-source libraries with evidence-backed answers and GitHub permalinks. Use when the user asks about library internals, needs implementation details with source code references, wants to understand why something was changed, or needs authoritative answers backed by actual code. Excels at navigating large open-source repos and providing citations to exact lines of code.
+---
+
+# Librarian
+
+Answer questions about open-source libraries by finding evidence with GitHub permalinks. Every claim backed by actual code.
+
+## Execution Model
+
+Pi executes tool calls sequentially, even when you emit multiple calls in one turn. But batching independent calls in a single turn still saves LLM round-trips (~5-10s each). Use these patterns:
+
+| Pattern | When | Actually parallel? |
+|---------|------|-------------------|
+| Batch tool calls in one turn | Independent ops (web_search + fetch_content + read) | No, but saves round-trips |
+| `fetch_content({ urls: [...] })` | Multiple URLs to fetch | Yes (3 concurrent) |
+| Bash with `&` + `wait` | Multiple git/gh commands | Yes (OS-level) |
+
+## Step 1: Classify the Request
+
+Before doing anything, classify the request to pick the right research strategy.
+
+| Type | Trigger | Primary Approach |
+|------|---------|-----------------|
+| **Conceptual** | "How do I use X?", "Best practice for Y?" | web_search + fetch_content (README/docs) |
+| **Implementation** | "How does X implement Y?", "Show me the source" | fetch_content (clone) + code search |
+| **Context/History** | "Why was this changed?", "History of X?" | git log + git blame + issue/PR search |
+| **Comprehensive** | Complex or ambiguous requests, "deep dive" | All of the above |
+
+## Step 2: Research by Type
+
+### Conceptual Questions
+
+Batch these in one turn:
+
+1. **web_search**: `"library-name topic"` via Perplexity for recent articles and discussions
+2. **fetch_content**: the library's GitHub repo URL to clone and check README, docs, or examples
+
+Synthesize web results + repo docs. Cite official documentation and link to relevant source files.
+
+### Implementation Questions
+
+The core workflow -- clone, find, permalink:
+
+1. **fetch_content** the GitHub repo URL -- this clones it locally and returns the file tree
+2. Use **bash** to search the cloned repo: `grep -rn "function_name"`, `find . -name "*.ts"`
+3. Use **read** to examine specific files once you've located them
+4. Get the commit SHA: `cd /tmp/pi-github-repos/owner/repo && git rev-parse HEAD`
+5. Construct permalink: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`
+
+Batch the initial calls: fetch_content (clone) + web_search (recent discussions) in one turn. Then dig into the clone with grep/read once it's available.
+
+### Context/History Questions
+
+Use git operations on the cloned repo:
+
+```bash
+cd /tmp/pi-github-repos/owner/repo
+
+# Recent changes to a specific file
+git log --oneline -n 20 -- path/to/file.ts
+
+# Who changed what and when
+git blame -L 10,30 path/to/file.ts
+
+# Full diff for a specific commit
+git show <sha> -- path/to/file.ts
+
+# Search commit messages
+git log --oneline --grep="keyword" -n 10
+```
+
+For issues and PRs, use bash:
+
+```bash
+# Search issues
+gh search issues "keyword" --repo owner/repo --state all --limit 10
+
+# Search merged PRs
+gh search prs "keyword" --repo owner/repo --state merged --limit 10
+
+# View specific issue/PR with comments
+gh issue view <number> --repo owner/repo --comments
+gh pr view <number> --repo owner/repo --comments
+
+# Release notes
+gh api repos/owner/repo/releases --jq '.[0:5] | .[].tag_name'
+```
+
+### Comprehensive Research
+
+Combine everything. Batch these in one turn:
+
+1. **web_search**: recent articles and discussions
+2. **fetch_content**: clone the repo (or multiple repos if comparing)
+3. **bash**: `gh search issues "keyword" --repo owner/repo --limit 10 & gh search prs "keyword" --repo owner/repo --state merged --limit 10 & wait`
+
+Then dig into the clone with grep, read, git blame, git log as needed.
+
+## Step 3: Construct Permalinks
+
+Permalinks are the whole point. They make your answers citable and verifiable.
+
+```
+https://github.com/<owner>/<repo>/blob/<commit-sha>/<filepath>#L<start>-L<end>
+```
+
+Getting the SHA from a cloned repo:
+
+```bash
+cd /tmp/pi-github-repos/owner/repo && git rev-parse HEAD
+```
+
+Getting the SHA from a tag:
+
+```bash
+gh api repos/owner/repo/git/refs/tags/v1.0.0 --jq '.object.sha'
+```
+
+Always use full commit SHAs, not branch names. Branch links break when code changes. Permalinks don't.
+
+## Step 4: Cite Everything
+
+Every code-related claim needs a permalink. Format:
+
+```markdown
+The stale time check happens in [`notifyManager.ts`](https://github.com/TanStack/query/blob/abc123/packages/query-core/src/notifyManager.ts#L42-L50):
+
+\`\`\`typescript
+function isStale(query: Query, staleTime: number): boolean {
+  return query.state.dataUpdatedAt + staleTime < Date.now()
+}
+\`\`\`
+```
+
+For conceptual answers, link to official docs and relevant source files. For implementation answers, every function/class reference should have a permalink.
+
+## Video Analysis
+
+For questions about video tutorials, conference talks, or screen recordings:
+
+```typescript
+// Full extraction (transcript + visual descriptions)
+fetch_content({ url: "https://youtube.com/watch?v=abc" })
+
+// Ask a specific question about a video
+fetch_content({ url: "https://youtube.com/watch?v=abc", prompt: "What libraries are imported in this tutorial?" })
+
+// Single frame at a known moment
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41" })
+
+// Range scan for visual discovery
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00" })
+
+// Custom density across a range
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00", frames: 3 })
+
+// Whole-video sampling
+fetch_content({ url: "https://youtube.com/watch?v=abc", frames: 6 })
+
+// Analyze a local recording
+fetch_content({ url: "/path/to/demo.mp4", prompt: "What error message appears on screen?" })
+
+// Batch multiple videos with the same question
+fetch_content({
+  urls: ["https://youtube.com/watch?v=abc", "https://youtube.com/watch?v=def"],
+  prompt: "What packages are installed?"
+})
+```
+
+Use single timestamps for known moments, ranges for visual scanning, and frames-alone for a quick overview of the whole video.
+
+The `prompt` parameter only applies to video content (YouTube URLs and local video files). For non-video URLs, it's ignored.
+
+## Failure Recovery
+
+| Failure | Recovery |
+|---------|----------|
+| grep finds nothing | Broaden the query, try concept names instead of exact function names |
+| gh CLI rate limited | Use the already-cloned repo in /tmp/pi-github-repos/ for git operations |
+| Repo too large to clone | fetch_content returns an API-only view automatically; use that or add `forceClone: true` |
+| File not found in clone | Branch name with slashes may have misresolved; list the repo tree and navigate manually |
+| Uncertain about implementation | State your uncertainty explicitly, propose a hypothesis, show what evidence you did find |
+| Video extraction fails | Ensure Chrome is signed into gemini.google.com (free) or set GEMINI_API_KEY |
+| Page returns 403/bot block | Gemini fallback triggers automatically; no action needed if Gemini is configured |
+| web_search fails | Check provider config; try explicit `provider: "gemini"` if Perplexity key is missing |
+
+## Guidelines
+
+- Vary search queries when running multiple searches -- different angles, not the same pattern repeated
+- Prefer recent sources; filter out outdated results when they conflict with newer information
+- For version-specific questions, clone the tagged version: `fetch_content("https://github.com/owner/repo/tree/v1.0.0")`
+- When the repo is already cloned from a previous fetch_content call, reuse it -- check the path before cloning again
+- Answer directly. Skip preamble like "I'll help you with..." -- go straight to findings

package/themes/everforest-tui-dark.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "everforest-tui-dark",
+  "vars": {
+    "base": "#323d43",
+    "mantle": "#2d353b",
+    "surface0": "#3a464c",
+    "surface1": "#434f55",
+    "surface2": "#4b565c",
+    "text": "#d3c6aa",
+    "subtext1": "#c3bea9",
+    "subtext0": "#b0b5a4",
+    "overlay": "#a7afa3",
+    "red": "#e67e80",
+    "orange": "#e69875",
+    "yellow": "#dbbc7f",
+    "green": "#a7c080",
+    "aqua": "#83c092",
+    "blue": "#7fbbb3",
+    "purple": "#d699b6",
+    "redBg": "#4b3f42",
+    "greenBg": "#3f4b43",
+    "blueBg": "#39464c"
+  },
+  "colors": {
+    "accent": "aqua",
+    "border": "blue",
+    "borderAccent": "aqua",
+    "borderMuted": "surface2",
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "muted": "subtext0",
+    "dim": "overlay",
+    "text": "text",
+    "thinkingText": "subtext1",
+    "selectedBg": "surface1",
+    "userMessageBg": "surface0",
+    "userMessageText": "text",
+    "customMessageBg": "mantle",
+    "customMessageText": "text",
+    "customMessageLabel": "purple",
+    "toolPendingBg": "blueBg",
+    "toolSuccessBg": "greenBg",
+    "toolErrorBg": "redBg",
+    "toolTitle": "blue",
+    "toolOutput": "subtext1",
+    "mdHeading": "yellow",
+    "mdLink": "blue",
+    "mdLinkUrl": "subtext0",
+    "mdCode": "aqua",
+    "mdCodeBlock": "green",
+    "mdCodeBlockBorder": "surface2",
+    "mdQuote": "subtext0",
+    "mdQuoteBorder": "surface2",
+    "mdHr": "surface2",
+    "mdListBullet": "aqua",
+    "toolDiffAdded": "green",
+    "toolDiffRemoved": "red",
+    "toolDiffContext": "subtext0",
+    "syntaxComment": "subtext0",
+    "syntaxKeyword": "red",
+    "syntaxFunction": "green",
+    "syntaxVariable": "blue",
+    "syntaxString": "aqua",
+    "syntaxNumber": "purple",
+    "syntaxType": "yellow",
+    "syntaxOperator": "orange",
+    "syntaxPunctuation": "text",
+    "thinkingOff": "surface2",
+    "thinkingMinimal": "overlay",
+    "thinkingLow": "blue",
+    "thinkingMedium": "aqua",
+    "thinkingHigh": "purple",
+    "thinkingXhigh": "red",
+    "thinkingMax": "orange",
+    "bashMode": "green"
+  },
+  "export": {
+    "pageBg": "#323d43",
+    "cardBg": "#2d353b",
+    "infoBg": "#3a464c"
+  }
+}

package/themes/everforest-tui-light.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "everforest-tui-light",
+  "vars": {
+    "base": "#f8f0dc",
+    "mantle": "#f3ead3",
+    "surface0": "#eee7d2",
+    "surface1": "#e5dfc5",
+    "surface2": "#dfddc8",
+    "text": "#5c6a72",
+    "subtext1": "#5c6a72",
+    "subtext0": "#596a66",
+    "overlay": "#65756f",
+    "red": "#f85552",
+    "orange": "#f57d26",
+    "yellow": "#dfa000",
+    "green": "#8da101",
+    "aqua": "#35a77c",
+    "blue": "#3a94c5",
+    "purple": "#df69ba",
+    "redBg": "#f4e3df",
+    "greenBg": "#edf0df",
+    "blueBg": "#e7edf0"
+  },
+  "colors": {
+    "accent": "aqua",
+    "border": "blue",
+    "borderAccent": "aqua",
+    "borderMuted": "surface2",
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "muted": "subtext0",
+    "dim": "overlay",
+    "text": "text",
+    "thinkingText": "subtext1",
+    "selectedBg": "surface1",
+    "userMessageBg": "surface0",
+    "userMessageText": "text",
+    "customMessageBg": "mantle",
+    "customMessageText": "text",
+    "customMessageLabel": "purple",
+    "toolPendingBg": "blueBg",
+    "toolSuccessBg": "greenBg",
+    "toolErrorBg": "redBg",
+    "toolTitle": "blue",
+    "toolOutput": "subtext1",
+    "mdHeading": "yellow",
+    "mdLink": "blue",
+    "mdLinkUrl": "subtext0",
+    "mdCode": "aqua",
+    "mdCodeBlock": "green",
+    "mdCodeBlockBorder": "surface2",
+    "mdQuote": "subtext0",
+    "mdQuoteBorder": "surface2",
+    "mdHr": "surface2",
+    "mdListBullet": "aqua",
+    "toolDiffAdded": "green",
+    "toolDiffRemoved": "red",
+    "toolDiffContext": "subtext0",
+    "syntaxComment": "subtext0",
+    "syntaxKeyword": "red",
+    "syntaxFunction": "green",
+    "syntaxVariable": "blue",
+    "syntaxString": "aqua",
+    "syntaxNumber": "purple",
+    "syntaxType": "yellow",
+    "syntaxOperator": "orange",
+    "syntaxPunctuation": "text",
+    "thinkingOff": "surface2",
+    "thinkingMinimal": "overlay",
+    "thinkingLow": "blue",
+    "thinkingMedium": "aqua",
+    "thinkingHigh": "purple",
+    "thinkingXhigh": "red",
+    "thinkingMax": "orange",
+    "bashMode": "green"
+  },
+  "export": {
+    "pageBg": "#f8f0dc",
+    "cardBg": "#f3ead3",
+    "infoBg": "#eee7d2"
+  }
+}