@preapexis/pi-kit 1.2.1 → 1.2.2

package/AGENTS.md

@@ -1,20 +1,111 @@
-# AGENTS.md
+# Agent Guidelines: preapexis-pi-kit
+
+## Project Summary
+
+`preapexis-pi-kit` is a personal Pi coding-agent package that bundles TypeScript extensions, prompt templates, reusable skills, and UI themes for the [Pi Agent Harness](https://github.com/earendil-works/pi). It adds safety guards, status displays, prompt workflows, and custom branding to AI-assisted coding sessions.
+
+Published to npm as `@preapexis/pi-kit`.
+
+## Tech Stack
+
+- **Language:** TypeScript (ES2022, NodeNext module resolution)
+- **Runtime:** Node.js
+- **Test runner:** Vitest
+- **Package manager:** npm
+- **Peer dependency:** `@earendil-works/pi-coding-agent`
+
+## Project Map
+
+| Path               | Purpose                                                                                                   |
+| ------------------ | --------------------------------------------------------------------------------------------------------- |
+| `AGENTS.md`        | Core rules and guidance for agents working in this repository. Read this first before any edit.           |
+| `README.md`        | Public documentation, installation instructions, and usage guide.                                         |
+| `package.json`     | Pi package manifest. Declares `pi.extensions`, `pi.prompts`, `pi.skills`, and `pi.themes`.                |
+| `CHANGELOG.md`     | Version history and release notes.                                                                        |
+| `LICENSE`          | ISC license.                                                                                              |
+| `settings.json`    | Local Pi settings (`theme`, `defaultProjectTrust`). Not published as part of the package manifest.        |
+| `tsconfig.json`    | TypeScript configuration covering `extensions/**/*.ts`, `tests/**/*.ts`, and `vitest.config.ts`.          |
+| `vitest.config.ts` | Vitest test runner configuration (Node environment, globals enabled).                                     |
+| `extensions/`      | TypeScript Pi extensions. Each file exports a default function receiving `ExtensionAPI`.                  |
+| `prompts/`         | Markdown prompt templates. The filename (without `.md`) becomes a slash command.                          |
+| `skills/`          | Reusable skills. Each skill lives in its own subfolder containing a `SKILL.md` with frontmatter.          |
+| `themes/`          | JSON theme files for Pi UI. Each file must have `name`, `vars`, `colors`, and `$schema`.                  |
+| `tests/`           | Vitest test suite validating package structure, extension syntax, prompt conventions, skills, and themes. |
+| `scripts/`         | Development helper scripts. Currently contains `git-release.mjs`.                                         |
+| `docs/`            | Project documentation. `docs/plans/` is the target directory for `/save-plan`.                            |
+
+## Common Task Map
+
+| Task                        | Read These Files First                                                                        |
+| --------------------------- | --------------------------------------------------------------------------------------------- |
+| Change branding/UI          | `extensions/brand-ui.ts`, `themes/`                                                           |
+| Change update behavior      | `extensions/update.ts`                                                                        |
+| Change safety behavior      | `extensions/safety.ts`, `extensions/git-guard.ts`, `extensions/workspace-guard.ts`            |
+| Change footer/status        | `extensions/status.ts`, `extensions/usage-tracker.ts`                                         |
+| Change prompt workflows     | `extensions/prompts.ts`, `prompts/`                                                           |
+| Change sound cues           | `extensions/sound-cues.ts`                                                                    |
+| Change workspace boundaries | `extensions/workspace-guard.ts`                                                               |
+| Add a new extension         | `AGENTS.md` (Extension Rules), `tests/extensions.test.ts`, then create `extensions/<name>.ts` |
+| Add a new prompt            | `AGENTS.md` (Prompt Rules), `tests/prompts.test.ts`, then create `prompts/<name>.md`          |
+| Add a new skill             | `AGENTS.md` (Skill Rules), `tests/skills.test.ts`, then create `skills/<name>/SKILL.md`       |
+| Add a new theme             | `tests/themes.test.ts`, then create `themes/<name>.json`                                      |
+| Release a new version       | `scripts/git-release.mjs`, `package.json`, `CHANGELOG.md`, `.github/workflows/publish.yml`    |
+
+## Development Commands
+
+| Command              | Purpose                                                                        |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `npm test`           | Run the full Vitest test suite (structure, syntax, and validation tests).      |
+| `npm run test:watch` | Run Vitest in watch mode.                                                      |
+| `npm run git`        | Run the interactive git-release script (bumps version, commits, tags, pushes). |
+| `pi install -l .`    | Install this package locally into Pi for development testing.                  |
+| `/reload`            | Reload Pi after installing, updating, or changing extensions.                  |
+
+## Coding Conventions
+
+- **Language:** TypeScript with strict mode enabled.
+- **Module system:** ES modules (`"type": "module"`), NodeNext resolution.
+- **Extension pattern:** Each extension exports a default function receiving `ExtensionAPI`.
+- **Naming:** Use clear, explicit names. Prefer `kebab-case` for filenames.
+- **Error handling:** Extensions use `ctx.hasUI` checks before UI operations; fall back to `console.log` or blocking when UI is unavailable.
+- **Testing:** Tests are in `tests/` using Vitest. Tests validate structural constraints (default exports, frontmatter, valid JSON) rather than deep behavioral logic.
+- **Dependencies:** Do not add dependencies unless explicitly approved. The package has no runtime dependencies; only `typescript` and `vitest` as devDependencies.
+- **Comments:** Avoid comments that only repeat the code. Use JSDoc for extension-level documentation.
 
-Guidance for AI agents working in this repository.
+## Safety Rules
+
+Agents must avoid:
+
+- reading or editing `.env` files
+- editing `.git`
+- editing `node_modules`
+- editing build output such as `dist`, `build`, `out`, or `coverage`
+- changing lockfiles unless the user approves
+- running package install/remove commands unless the user approves
+- running destructive Git commands (`git push --force`, `git reset --hard`, `git clean -fd`)
+- running destructive shell commands
+- running commands that leave the workspace without approval
 
-## Project
+Before risky edits, check whether the repo is dirty. Avoid overwriting user work.
 
-This repository is `preapexis-pi-kit`, a personal Pi coding-agent package.
+The `scripts/git-release.mjs` script performs `git push` and may create tags; review its behavior before running in a dirty worktree.
 
-It contains:
+## Architecture Notes
 
-- `extensions/` — TypeScript Pi extensions.
-- `prompts/` — prompt templates that become slash commands.
-- `skills/` — reusable skills, each in its own folder with a `SKILL.md`.
-- `themes/` — Pi UI themes.
-- `package.json` — declares this repository as a Pi package.
+- **Extension API:** All extensions consume `@earendil-works/pi-coding-agent`'s `ExtensionAPI`. They hook into lifecycle events (`session_start`, `before_agent_start`, `tool_call`, `agent_end`) and register slash commands.
+- **System prompt injection:** `safety.ts`, `workspace-guard.ts`, and potentially other extensions append rules to the agent system prompt via `before_agent_start`.
+- **UI availability:** Extensions must check `ctx.hasUI` before calling `ctx.ui.notify`, `ctx.ui.confirm`, `ctx.ui.select`, or `ctx.ui.setStatus`.
+- **Workspace boundary:** `workspace-guard.ts` locks the workspace root at `session_start` and blocks tool calls targeting outside paths.
+- **Git checkpointing:** `git-guard.ts` creates `pi-checkpoint-<branch>-<timestamp>` branches before risky edits when the working tree is dirty.
+- **Separation of concerns:**
+  - Git branch display belongs in `git-guard.ts`.
+  - Model, mode, repo trust, and test status belong in `status.ts`.
+  - Risky non-Git shell command protection belongs in `safety.ts`.
+  - Prompt menu belongs in `prompts.ts`.
 
-## Core Rules
+## Agent Rules
+
+### Core Rules
 
 - Keep changes small, focused, and reviewable.
 - Read existing files before editing them.
@@ -25,7 +116,7 @@ It contains:
 - Do not rewrite Git history.
 - Do not edit secrets, `.env` files, `.git`, build output, or generated files.
 
-## Package Structure Rules
+### Package Structure Rules
 
 The Pi package should continue to use this structure:
 
@@ -57,9 +148,7 @@ skills/
 
 Do not place skill files directly inside `skills/` unless Pi explicitly supports that format.
 
-## Extension Rules
-
-Extensions are TypeScript files in `extensions/`.
+### Extension Rules
 
 Current expected extensions:
 
@@ -69,20 +158,13 @@ Current expected extensions:
 - `prompts.ts` — `/prompts` menu.
 - `brand-ui.ts` — custom UI branding.
 
-Avoid duplicate responsibilities:
-
-- Git branch display belongs in `git-guard.ts`.
-- Model, mode, repo trust, and test status belong in `status.ts`.
-- Risky non-Git shell command protection belongs in `safety.ts`.
-- Prompt menu belongs in `prompts.ts`.
+Avoid duplicate responsibilities (see Architecture Notes).
 
 Do not reintroduce duplicate `/plan`, `/commit`, `/security`, or similar commands in extensions if matching prompt files already exist.
 
-## Prompt Rules
+### Prompt Rules
 
-Prompt files live in `prompts/`.
-
-The filename becomes the slash command.
+Prompt files live in `prompts/`. The filename becomes the slash command.
 
 Examples:
 
@@ -112,7 +194,7 @@ Prompt behavior rules:
 - Save-plan prompt should save plans under `docs/plans/`.
 - Do not edit `AGENTS.md` from a prompt unless the user approves.
 
-## Skill Rules
+### Skill Rules
 
 Skill files must start with valid frontmatter:
 
@@ -127,31 +209,7 @@ Do not add an extra `---` after the frontmatter.
 
 Keep skills focused and reusable.
 
-Good skill categories for this repo:
-
-- safe coding
-- frontend onboarding
-- frontend quality review
-- component implementation
-
-## Safety Rules
-
-Agents must avoid:
-
-- reading or editing `.env` files
-- editing `.git`
-- editing `node_modules`
-- editing build output such as `dist`, `build`, `out`, or `coverage`
-- changing lockfiles unless the user approves
-- running package install/remove commands unless the user approves
-- running destructive Git commands
-- running destructive shell commands
-
-If a task is unclear, ask questions before editing.
-
-Ask only important questions. If the task is clear, continue.
-
-## Verification
+### Verification
 
 When code changes are made, run the narrowest relevant check if available:
 
@@ -164,25 +222,7 @@ If checks cannot be run, explain why.
 
 Do not claim tests passed unless they were actually run.
 
-## Git Rules
-
-Before risky edits, check whether the repo is dirty.
-
-Dirty means there are uncommitted changes.
-
-Avoid overwriting user work.
-
-Do not run:
-
-```bash
-git push --force
-git reset --hard
-git clean -fd
-```
-
-unless the user explicitly approves and the safety extension allows it.
-
-## README Rules
+### README Rules
 
 Keep `README.md` aligned with the actual files.
 
@@ -190,10 +230,38 @@ If an extension, prompt, skill, or theme is renamed, update the README.
 
 Avoid mentioning removed files such as `team.ts` or old names such as `workflow.ts` if they no longer exist.
 
-## Style
+### Style
 
 - Use clear, simple language.
 - Prefer plain Markdown.
 - Avoid unnecessary complexity.
 - Avoid adding comments that only repeat the code.
 - Prefer explicit names over clever names.
+
+### Clarification
+
+If a task is unclear, ask questions before editing.
+
+Ask only important questions. If the task is clear, continue.
+
+Do not edit files until the user answers clarification questions.
+
+## Open Questions
+
+None.
+
+## Inspection Notes
+
+All important files were inspected:
+
+- Root files: `package.json`, `README.md`, `CHANGELOG.md`, `LICENSE`, `settings.json`, `tsconfig.json`, `vitest.config.ts`, `.gitignore`
+- Extensions: all 9 files in `extensions/`
+- Prompts: all 8 files in `prompts/`
+- Skills: all 4 `SKILL.md` files
+- Themes: all 4 JSON files
+- Tests: all 6 test files plus `tests/helpers.ts`
+- Scripts: `scripts/git-release.mjs`
+- CI/CD: `.github/workflows/publish.yml`
+- Editor configs: `.vscode/settings.json`, `.pi/settings.json`
+
+Not inspected in detail: individual theme JSON internals (only structure was validated via tests), and the full `node_modules/` tree (not relevant).

package/docs/PROJECT_MAP.md

@@ -0,0 +1,228 @@
+# Project Map
+
+## Purpose
+
+`preapexis-pi-kit` is a personal Pi coding-agent package that bundles TypeScript extensions, prompt templates, reusable skills, and UI themes for the [Pi Agent Harness](https://github.com/earendil-works/pi). It adds safety guards, status displays, prompt workflows, and custom branding to AI-assisted coding sessions.
+
+## Important Files
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Core rules and guidance for agents working in this repository. Read this first before any edit. |
+| `README.md` | Public documentation, installation instructions, and usage guide. |
+| `package.json` | Pi package manifest. Declares `pi.extensions`, `pi.prompts`, `pi.skills`, and `pi.themes`. Also defines npm scripts and dev dependencies. |
+| `CHANGELOG.md` | Version history and release notes. |
+| `LICENSE` | ISC license. |
+| `settings.json` | Local Pi settings (`theme`, `defaultProjectTrust`). Not published as part of the package manifest. |
+| `tsconfig.json` | TypeScript configuration covering `extensions/**/*.ts`, `tests/**/*.ts`, and `vitest.config.ts`. |
+| `vitest.config.ts` | Vitest test runner configuration (Node environment, globals enabled). |
+| `.gitignore` | Git ignore rules. |
+
+## Directory Map
+
+| Directory | Purpose |
+|-----------|---------|
+| `extensions/` | TypeScript Pi extensions. Each file exports a default function receiving `ExtensionAPI`. |
+| `prompts/` | Markdown prompt templates. The filename (without `.md`) becomes a slash command. |
+| `skills/` | Reusable skills. Each skill lives in its own subfolder containing a `SKILL.md` with frontmatter. |
+| `themes/` | JSON theme files for Pi UI. Each file must have `name`, `vars`, `colors`, and `$schema`. |
+| `tests/` | Vitest test suite validating package structure, extension syntax, prompt conventions, skills, and themes. |
+| `scripts/` | Development helper scripts. |
+| `docs/` | Project documentation. Currently contains this map. `docs/plans/` is the target directory for `/save-plan`. |
+
+## Extension Map
+
+### `extensions/brand-ui.ts`
+- **Slash commands:** none
+- **UI/status changes:** Custom PreApeXis terminal branding and visual UI customization.
+- **Safety behavior:** none
+- **When to edit:** Changing branding, colors, or terminal UI styling.
+
+### `extensions/git-guard.ts`
+- **Slash commands:** none
+- **UI/status changes:** May show dirty-worktree warnings and checkpoint-branch notifications.
+- **Safety behavior:** Warns on dirty Git worktrees; blocks `git push --force`; confirms `git reset --hard`; creates checkpoint branches before risky edits.
+- **When to edit:** Changing Git-specific safety behavior or checkpoint logic.
+
+### `extensions/prompts.ts`
+- **Slash commands:** `/prompts`
+- **UI/status changes:** Displays a menu listing available prompt workflows.
+- **Safety behavior:** none
+- **When to edit:** Adding or removing prompt workflows, or changing how the menu is rendered.
+
+### `extensions/safety.ts`
+- **Slash commands:** none
+- **UI/status changes:** none
+- **Safety behavior:** Blocks risky shell commands; prevents reading/editing `.env` files; blocks edits to `node_modules`, build output, `.git` internals, and generated files; requires confirmation for package install/remove commands; injects safety and clarification rules into the agent system prompt.
+- **When to edit:** Changing general (non-Git) safety rules or protected path lists.
+
+### `extensions/sound-cues.ts`
+- **Slash commands:** `/sound-on`, `/sound-off`, `/sound-test`
+- **UI/status changes:** none
+- **Safety behavior:** none
+- **When to edit:** Changing sound cue triggers or audio behavior.
+
+### `extensions/status.ts`
+- **Slash commands:** `/test-pass`, `/test-fail`, `/test-none`
+- **UI/status changes:** Shows compact kit status in the footer (e.g., `kit: safe · trusted · tests:none`).
+- **Safety behavior:** none
+- **When to edit:** Changing footer display format or status indicators.
+
+### `extensions/update.ts`
+- **Slash commands:** `/update`
+- **UI/status changes:** Displays an update menu for Pi, this kit, or project packages.
+- **Safety behavior:** none
+- **When to edit:** Changing update behavior or menu options.
+
+### `extensions/usage-tracker.ts`
+- **Slash commands:** `/usage`, `/usage-reset`
+- **UI/status changes:** May display session token usage and estimated cost.
+- **Safety behavior:** none
+- **When to edit:** Changing usage tracking logic or cost estimation.
+
+### `extensions/workspace-guard.ts`
+- **Slash commands:** `/workspace-root`
+- **UI/status changes:** Sets status indicator `workspace: locked` on session start.
+- **Safety behavior:** Blocks file operations (`read`, `write`, `edit`, `ls`, `grep`, `find`) and `bash` commands that target paths outside the workspace root; injects workspace-boundary rules into the agent system prompt.
+- **When to edit:** Changing workspace boundary behavior or outside-access confirmation logic.
+
+## Prompt Map
+
+| Slash command | File path | Purpose | When to use it |
+|---------------|-----------|---------|----------------|
+| `/commit` | `prompts/commit.md` | Suggests a conventional commit message from current Git changes. Does not commit automatically. | After making changes and before committing. |
+| `/implement` | `prompts/implement.md` | Implements a saved or pasted plan. May edit files. Should follow the plan closely and ask if unclear. | After `/plan` and `/save-plan` (or when a plan is provided). |
+| `/init` | `prompts/init.md` | Inspects a repository and creates an onboarding report. Read-only. | When opening a new repo or unfamiliar feature area. |
+| `/plan` | `prompts/plan.md` | Creates a read-only implementation plan with batches, model choice, effort guidance, and risk level. | Before starting implementation work. |
+| `/repo-map` | `prompts/repo-map.md` | Creates or updates `docs/PROJECT_MAP.md`. Read-only for source files. | When the project structure has changed or a map is missing. |
+| `/review-safe` | `prompts/review-safe.md` | Runs a read-only project review. | When wanting a general code or project review. |
+| `/save-plan` | `prompts/save-plan.md` | Saves a generated plan as a markdown file under `docs/plans/`. | After `/plan` to persist the plan. |
+| `/security` | `prompts/security.md` | Runs a read-only security review. | When reviewing for security issues. |
+
+## Skill Map
+
+| Skill name | File path | Purpose | When it should activate |
+|------------|-----------|---------|------------------------|
+| `component-implementation` | `skills/component-implementation/SKILL.md` | Builds or modifies frontend components using existing patterns, styling, accessibility rules, and test conventions. | When creating or modifying frontend UI components. |
+| `frontend-onboarding` | `skills/frontend-onboarding/SKILL.md` | Understands frontend app structure, framework, routing, build tools, styling system, and test setup. Read-only unless asked. | When starting work in an unfamiliar frontend repo or feature area. |
+| `frontend-quality` | `skills/frontend-quality/SKILL.md` | Reviews frontend code for accessibility, responsiveness, performance, UX states, browser behavior, and maintainability. Read-only unless asked. | When reviewing or improving frontend quality. |
+| `safe-coding` | `skills/safe-coding/SKILL.md` | Applies safe, reviewable coding practices: small diffs, pre-read, no secrets, no lockfiles, post-edit verification. | When modifying any file in a codebase. |
+
+## Theme Map
+
+| Theme | File path |
+|-------|-----------|
+| Latte Review | `themes/latte-review.json` |
+| Neon Guardian | `themes/neon-guardian.json` |
+| Safe Dark | `themes/safe-dark.json` |
+| Tokyo Midnight | `themes/tokyo-midnight.json` |
+
+## Common Tasks
+
+### Change branding/UI
+Read:
+- `extensions/brand-ui.ts`
+- `themes/`
+
+### Change update behavior
+Read:
+- `extensions/update.ts`
+
+### Change safety behavior
+Read:
+- `extensions/safety.ts`
+- `extensions/git-guard.ts`
+- `extensions/workspace-guard.ts`
+
+### Change footer/status
+Read:
+- `extensions/status.ts`
+- `extensions/usage-tracker.ts`
+
+### Change prompt workflows
+Read:
+- `extensions/prompts.ts`
+- `prompts/`
+
+### Change sound cues
+Read:
+- `extensions/sound-cues.ts`
+
+### Change workspace boundaries
+Read:
+- `extensions/workspace-guard.ts`
+
+### Add a new extension
+Read first:
+- `AGENTS.md` (Extension Rules)
+- `tests/extensions.test.ts`
+Then create:
+- `extensions/<name>.ts`
+
+### Add a new prompt
+Read first:
+- `AGENTS.md` (Prompt Rules)
+- `tests/prompts.test.ts`
+Then create:
+- `prompts/<name>.md`
+Update:
+- `extensions/prompts.ts` (if the prompt should appear in the `/prompts` menu)
+
+### Add a new skill
+Read first:
+- `AGENTS.md` (Skill Rules)
+- `tests/skills.test.ts`
+Then create:
+- `skills/<name>/SKILL.md`
+
+### Add a new theme
+Read first:
+- `tests/themes.test.ts`
+Then create:
+- `themes/<name>.json`
+
+### Release a new version
+Read:
+- `scripts/git-release.mjs`
+- `package.json`
+- `CHANGELOG.md`
+
+## Common Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm test` | Run the full Vitest test suite (structure, syntax, and validation tests). |
+| `npm run test:watch` | Run Vitest in watch mode. |
+| `npm run git` | Run the interactive git-release script (bumps version, commits, tags, pushes). |
+| `pi install -l .` | Install this package locally into Pi for development testing. |
+| `/reload` | Reload Pi after installing, updating, or changing extensions. |
+
+## Safety Notes
+
+- **Do not edit `.env` files** — blocked by `extensions/safety.ts`.
+- **Do not edit `.git` internals** — blocked by `extensions/safety.ts`.
+- **Do not edit `node_modules`** — blocked by `extensions/safety.ts`.
+- **Do not edit build output** (`dist`, `build`, `out`, `coverage`) — blocked by `extensions/safety.ts`.
+- **Do not change lockfiles** unless the user explicitly approves.
+- **Do not run destructive Git commands** (`git push --force`, `git reset --hard`, `git clean -fd`) without explicit user approval — guarded by `extensions/git-guard.ts`.
+- **Do not run commands leaving the workspace** without approval — guarded by `extensions/workspace-guard.ts`.
+- **`scripts/git-release.mjs`** performs `git push` and may create tags; review its behavior before running in a dirty worktree.
+
+## Agent Rules
+
+- Read `AGENTS.md` before making any edits.
+- Keep changes small, focused, and reviewable.
+- Read existing files before editing them.
+- Preserve existing behavior unless explicitly asked to change it.
+- Match the style already used in the repo.
+- Do not add dependencies unless explicitly approved.
+- Do not delete files unless explicitly approved.
+- Do not rewrite Git history.
+- Each skill must live in its own folder under `skills/`.
+- Prompt filenames become slash commands; do not create `prompts/prompts.md` because `/prompts` is provided by `extensions/prompts.ts`.
+- Extensions must export a default function receiving `ExtensionAPI`.
+- Run `npm test` after structural changes to extensions, prompts, skills, or themes.
+- Update `README.md` and `CHANGELOG.md` when adding or renaming public features.
+- Planning and review prompts should remain read-only.
+- The `/commit` prompt must suggest a message only; it must not commit automatically.
+- The `/save-plan` prompt should save plans under `docs/plans/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preapexis/pi-kit",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Personal Pi coding-agent kit with safety extensions, status UI, prompt workflows, skills, and themes.",
   "keywords": [
     "pi-package",

package/prompts/init.md

@@ -1,194 +1,228 @@
-# Initialize Repository Understanding
+# Initialize Agent Guidelines
 
-Your job is to deeply inspect this repository and create or update an `AGENTS.md` file that captures everything Pi needs to know to work effectively in this codebase.
+Your job is to create or update the root `AGENTS.md` file for this repository.
 
-If the repository is large, inspect the most important files first and clearly mention what was not inspected.
+This prompt must **not** duplicate the full repository map. The detailed repository map belongs in:
+
+`docs/PROJECT_MAP.md`
+
+If `docs/PROJECT_MAP.md` exists, read it and use it as the main source for repository structure.
+
+If `docs/PROJECT_MAP.md` does not exist, do **not** create a large project map inside `AGENTS.md`. Instead, inspect only the most important project files and add a note in `AGENTS.md` saying that `/repo-map` should be run to generate `docs/PROJECT_MAP.md`.
 
 ## Goal
 
-Create a useful `AGENTS.md` file so future Pi sessions can quickly understand:
+Create a concise, useful `AGENTS.md` file that tells future Pi agents:
 
 - what this project does
-- where important files live
+- which repository map file to read
 - which commands to run
 - which files are risky
-- which files to inspect for common tasks
-- what rules agents should follow
+- which files to inspect first for common tasks
+- what rules agents must follow
+
+`AGENTS.md` should be short, scannable, and task-focused.
+
+It should act as an **agent operating guide**, not a full file inventory.
+
+## Important Rule
+
+Do not copy the full contents of `docs/PROJECT_MAP.md` into `AGENTS.md`.
+
+Instead, summarize only the most important paths and link to it.
+
+Good:
+
+- For the full repository map, read `docs/PROJECT_MAP.md`.
+
+Bad:
+
+- Listing every source file, prompt file, skill file, theme file, test file, and config file again inside `AGENTS.md`.
 
 ## Steps
 
-1. **Check for an existing `AGENTS.md`**
+1. Check for an existing `AGENTS.md`
    - If it exists, read it first.
-   - Preserve anything that is still accurate and relevant.
-   - Do not remove existing project-specific rules unless they are clearly outdated.
-   - Merge new findings with the existing content.
+   - Preserve accurate project-specific rules.
+   - Remove duplicated or overly detailed file inventory if it is already covered by `docs/PROJECT_MAP.md`.
+   - Keep the file concise.
+
+2. Check for `docs/PROJECT_MAP.md`
+   - If it exists, read it.
+   - Use it to understand the project structure.
+   - Reference it from `AGENTS.md`.
+   - Do not duplicate it.
 
-2. **Read the codebase thoroughly**
+3. Read key project files
 
-   Read important files such as:
+   Read only the files needed to create good agent guidance:
    - `README.md`
    - `package.json`
-   - `pyproject.toml`
-   - `go.mod`
-   - `Cargo.toml`
-   - `pom.xml`
-   - `build.gradle`
-   - `CONTRIBUTING.md`
-   - `docs/`
-   - `.github/workflows/`
-   - `docker-compose.yml`
-   - `Dockerfile`
-   - config files such as:
+   - `AGENTS.md`, if present
+   - `docs/PROJECT_MAP.md`, if present
+   - `.github/workflows/`, if present
+   - important config files such as:
      - `tsconfig.json`
-     - `vite.config.*`
-     - `next.config.*`
-     - `webpack.config.*`
      - `eslint.config.*`
      - `prettier.config.*`
-   - main source directories such as:
-     - `src/`
-     - `app/`
-     - `lib/`
-     - `packages/`
+
+   - main package directories such as:
      - `extensions/`
      - `prompts/`
      - `skills/`
      - `themes/`
-   - test files and test configuration
-   - `.env.example` files only
+     - `tests/`
 
    Do not read actual `.env` files.
 
-3. **Identify the project structure**
-
-   Find:
-   - main entry points
-   - important directories and their purposes
-   - config files
-   - generated/build output directories
-   - files that should be treated carefully
-
-4. **Detect the development workflow**
+4. Detect the development workflow
 
    Find commands for:
    - install
-   - dev
-   - build
    - test
-   - lint
    - typecheck
-   - format
-   - reload or local development, if applicable
+   - release
+   - local Pi usage
+   - package publishing, if applicable
 
-5. **Identify safety risks**
+5. Identify safety risks
 
    Look for:
-   - secrets or env files
-   - deployment files
-   - database migrations
-   - production config
-   - generated files
+   - auth files
+   - env files
+   - GitHub Actions publishing workflows
+   - release scripts
+   - package version files
    - lockfiles
-   - destructive scripts
-   - commands that should require confirmation
+   - destructive commands
+   - workspace boundary rules
 
-6. **Infer coding conventions**
+6. Create or update `AGENTS.md`
 
-   Look for:
-   - language/framework
-   - naming style
-   - error handling style
-   - testing style
-   - API conventions
-   - dependency management
-   - state management and data flow, if applicable
+   Use this structure:
 
-7. **Create a task-focused project map inside `AGENTS.md`**
+   # Agent Guidelines: <project name>
 
-   Add a section that tells future agents where to look first for common tasks.
+   ## Project Summary
+
+   Briefly explain what this project does.
+
+   ## Start Here
+
+   Tell future agents which files to read first.
+
+   Include:
+   - `README.md`
+   - `docs/PROJECT_MAP.md`, if present
+   - `package.json`
+   - key task-specific files
+
+   If `docs/PROJECT_MAP.md` is missing, say:
+   - Run `/repo-map` to generate `docs/PROJECT_MAP.md`.
+
+   ## Repository Map
+
+   Keep this section short.
+
+   If `docs/PROJECT_MAP.md` exists, write:
+   - Full repository map: `docs/PROJECT_MAP.md`
+
+   Then include only a small high-level table, not a full inventory.
 
    Example:
-   - For branding/UI changes, read `extensions/brand-ui.ts`.
-   - For update behavior, read `extensions/update.ts`.
-   - For safety behavior, read `extensions/safety.ts` and `extensions/git-guard.ts`.
-   - For prompt workflows, read `prompts/`.
-   - For skills, read `skills/<skill-name>/SKILL.md`.
 
-## Output
+   | Path          | Purpose                |
+   | ------------- | ---------------------- |
+   | `extensions/` | Pi extension modules   |
+   | `prompts/`    | Slash prompt workflows |
+   | `skills/`     | Packaged Pi skills     |
+   | `themes/`     | Pi themes              |
+   | `tests/`      | Vitest tests           |
 
-Create or update `AGENTS.md` in the repository root with this structure:
+   ## Common Task Map
 
-```markdown
-# Agent Guidelines: <project name>
+   Keep this task-focused.
 
-## Project Summary
+   Example:
 
-Briefly explain what this project does.
+   | Task                    | Read These Files First                                                             |
+   | ----------------------- | ---------------------------------------------------------------------------------- |
+   | Change branding/UI      | `extensions/brand-ui.ts`, `themes/`                                                |
+   | Change update behavior  | `extensions/update.ts`                                                             |
+   | Change safety behavior  | `extensions/safety.ts`, `extensions/git-guard.ts`, `extensions/workspace-guard.ts` |
+   | Change prompt workflows | `prompts/`, `extensions/prompts.ts`                                                |
+   | Change LiteLLM provider | `extensions/litellm-provider.ts`                                                   |
+   | Change release behavior | `scripts/git-release.mjs`, `.github/workflows/`                                    |
 
-## Tech Stack
+   ## Development Commands
 
-Languages, frameworks, libraries, and tools.
+   Include only commands that are present in the project.
 
-## Project Map
+   Example:
 
-| Path   | Purpose          |
-| ------ | ---------------- |
-| `src/` | Main source code |
+   | Command                       | Purpose                                        |
+   | ----------------------------- | ---------------------------------------------- |
+   | `npm test`                    | Run tests                                      |
+   | `npm run git --msg="message"` | Commit, optionally bump version, tag, and push |
 
-## Common Task Map
+   ## Coding Conventions
 
-| Task                   | Read These Files First                            |
-| ---------------------- | ------------------------------------------------- |
-| Change branding/UI     | `extensions/brand-ui.ts`, `themes/`               |
-| Change update behavior | `extensions/update.ts`                            |
-| Change safety behavior | `extensions/safety.ts`, `extensions/git-guard.ts` |
+   Summarize important conventions only.
 
-## Development Commands
+   Include language, module style, formatting style, testing style, and extension patterns.
 
-| Command    | Purpose   |
-| ---------- | --------- |
-| `npm test` | Run tests |
+   ## Safety Rules
 
-## Coding Conventions
+   Include rules agents must follow.
 
-Naming, error handling, testing, API patterns, state management.
+   Mention:
+   - Do not read `.env` files.
+   - Do not expose secrets.
+   - Do not modify files outside the current workspace unless explicitly allowed.
+   - Be careful with release scripts, npm publishing, GitHub workflows, and package version files.
+   - Ask before destructive Git commands.
+   - Do not duplicate `docs/PROJECT_MAP.md` inside `AGENTS.md`.
 
-## Safety Rules
+   ## Architecture Notes
 
-Files, directories, and commands to treat carefully.
+   Summarize important architecture patterns.
 
-## Architecture Notes
+   Keep this short.
 
-Key patterns, data flow, important abstractions.
+   ## Agent Rules
 
-## Agent Rules
+   Include direct rules for future agents.
 
-Repo-specific rules for AI agents working in this codebase.
+   Example:
+   - Prefer editing existing extension files over creating duplicates.
+   - Keep `AGENTS.md` concise.
+   - Put detailed repository mapping in `docs/PROJECT_MAP.md`.
+   - Do not add GitHub install instructions if this package should be installed from npm.
+   - Do not duplicate Pi’s built-in status/footer information.
+   - Keep workspace guard behavior strict by default.
 
-## Open Questions
+   ## Open Questions
 
-Anything unclear or missing.
+   List anything unclear.
 
-## Inspection Notes
+   ## Inspection Notes
 
-Mention important areas that were not inspected.
-```
-````
+   Mention what was inspected and what was not inspected.
 
-## Rules
+## Output Rules
 
-- Be thorough but concise.
-- `AGENTS.md` should be scannable.
+- Only create or update `AGENTS.md`.
+- Do not modify source code.
+- Do not modify `docs/PROJECT_MAP.md`.
+- Do not create a second project map inside `AGENTS.md`.
+- Keep `AGENTS.md` concise.
+- Prefer references to `docs/PROJECT_MAP.md` over duplicated file lists.
 - Do not include secrets, API keys, tokens, passwords, or sensitive data.
 - Do not read actual `.env` files.
-- If `AGENTS.md` already exists, merge with it instead of blindly replacing it.
-- Focus on information that helps an AI agent write better code.
-- Prefer specific file paths over vague explanations.
-- Do not modify source code during initialization.
-- Only create or update `AGENTS.md`.
-- After creating or updating `AGENTS.md`, report:
-  - file path
-  - what sections were added or updated
-  - anything that was unclear
 
+After updating `AGENTS.md`, report:
 
+- file path
+- sections added or updated
+- whether `docs/PROJECT_MAP.md` was found and used
+- anything unclear