pi-baton 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [Unreleased]
+
+### Changed
+
+- Bump package version to `0.7.3` for the next patch release.
+
+## [0.7.2] - 2026-07-04
+
+### Added
+
+- `/baton:status` now shows the most recent finished run summary (state, last step, iteration, run directory) after a run reaches `completed` or `failed`, with clear finished-run framing instead of the no-active-run message.
+
+- Buy Me a Coffee sponsor button in README and native GitHub funding link via `.github/FUNDING.yml`.
+
+### Changed
+
+- Merged Dependabot PR #14: bump `@earendil-works/pi-ai` devDependency from 0.78.1 to 0.80.2 (type-check clean, 57/57 tests passing).
+- Removed leftover template scaffolding (`prompts/`, `themes/`, `skills/`).
+- Deleted stale template bootstrap docs (`docs/examples.md`, `docs/github-template.md`, `docs/repository-settings.md`, `docs/typescript.md`, `docs/template-checklist.md`) that shipped to npm consumers describing non-existent commands.
+- Updated ROADMAP.md to reflect current version (0.7.2), test count (57), and seed completion status for S-101, S-102, S-103, S-105.
+
 ## [0.7.1] - 2026-06-27
 
 ### Changed
@@ -128,3 +149,4 @@ This project follows semantic versioning.
 - Initial Pi package template.
 - Example extension, Agent Skill, prompt, and theme.
 - CI and npm Trusted Publishing workflow.
+

package/README.md

@@ -11,6 +11,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
 [![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
+<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
 
 > Run YAML-defined review loops in Pi with per-step model switching and isolated step context.
 
@@ -36,7 +37,7 @@ pi install npm:pi-baton
 Pin a specific version when you want reproducible installs:
 
 ```bash
-pi install npm:pi-baton@0.7.1
+pi install npm:pi-baton@0.7.3
 ```
 
 Install into the current project instead of your user Pi settings:
@@ -134,7 +135,7 @@ steps:
 | `agents/` | Builtin `worker` and `reviewer` subagent definitions |
 | `workflows/` | Builtin `default-review-loop.yaml` |
 | `assets/` | README / package branding assets |
-| `docs/` | Release and maintainer docs |
+| `docs/` | Release and maintainer documentation |
 
 ## Development
 

package/docs/incidents/2026-07-04-publish-duplicate-version.md

@@ -0,0 +1,249 @@
+# Incident — 2026-07-04 `Publish to npm` failed with duplicate-version E403
+
+> Status: **investigation report only.** No release workflow, package version,
+> CHANGELOG, npm registry state, or release was changed to produce this document.
+> Correction options below are proposals for a separate follow-up issue.
+
+## Summary
+
+The `Publish to npm` run
+[28704529442](https://github.com/eiei114/pi-baton/actions/runs/28704529442)
+(`v0.7.2`, dispatched 2026-07-04) failed at the final `npm publish` step with:
+
+```text
+npm error code E403
+npm error 403 403 Forbidden - PUT https://registry.npmjs.org/pi-baton
+npm error 403 You cannot publish over the previously published versions: 0.7.2.
+```
+
+**Root cause (classification: trigger/configuration):** a version-bump push to
+`main` fans out into **two concurrent `publish.yml` runs** for the same version,
+keyed by **different concurrency groups** so they are not serialized. The
+"Skip already published version" guard is a non-atomic check-then-publish
+(TOCTOU) and was defeated by ~11s of npm registry propagation latency, so the
+losing run reached `npm publish` after the winning run had already published
+`0.7.2`.
+
+This is **not** an authentication / Trusted Publishing failure (OIDC provenance
+was signed successfully) and **not** a duplicate-version-at-dispatch (the version
+was unpublished when the run started).
+
+**Impact:** none on the registry. `pi-baton@0.7.2` is correctly published and is
+`dist-tags.latest`. The failed run is a harmless duplicate that lost the race.
+
+## Evidence
+
+### Failed run
+
+| Field | Value |
+| --- | --- |
+| Run | [`Publish to npm` · 28704529442](https://github.com/eiei114/pi-baton/actions/runs/28704529442) |
+| Workflow | `.github/workflows/publish.yml` |
+| Event / trigger | `workflow_dispatch` |
+| Ref checked out | `v0.7.2` (tag), via `actions/checkout@v7` (`ref: v0.7.2`) |
+| Package | `pi-baton@0.7.2` |
+| Started / failed | 2026-07-04T11:18:38Z / 2026-07-04T11:19:11Z |
+| Failed step | `Publish to npm` (`npm publish --access public`) |
+| Conclusion | failure, exit code 1 |
+
+Step-by-step status (from the run): `Set up job`, `Checkout`, `Setup Node.js`,
+`Ensure npm supports trusted publishing`, `Install dependencies`, `Validate
+package`, `Skip already published version` all **passed**; `Publish to npm`
+**failed**.
+
+Failure output excerpt (from the failed step log):
+
+```text
+npm notice 📦  pi-baton@0.7.2
+...
+npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
+npm notice publish Signed provenance statement with source and build information from GitHub Actions
+npm notice publish Provenance statement published to transparency log: https://search.sigstore.dev/?logIndex=2069634820
+npm error code E403
+npm error 403 403 Forbidden - PUT https://registry.npmjs.org/pi-baton - You cannot publish over the previously published versions: 0.7.2.
+npm error A complete log of this run can be found in: /home/runner/.npm/_logs/2026-07-04T11_19_08_227Z-debug-0.log
+##[error]Process completed with exit code 1.
+```
+
+Note: provenance **was** signed (Trusted Publishing / OIDC worked); the failure is
+the publish PUT, not authentication.
+
+### Who dispatched it (trigger chain)
+
+The `workflow_dispatch` run was dispatched by the `Auto Release` workflow, not by
+a human clicking "Run workflow" in the UI:
+
+- PR #25 (`chore/sponsor-funding-patch-20260704`) merged to `main` at
+  **11:18:31Z**, bumping `package.json` to `0.7.2`.
+- The merge push fired two workflows on `main`:
+  - [`Publish to npm` · 28704526901](https://github.com/eiei114/pi-baton/actions/runs/28704526901)
+    (event `push`, ref `refs/heads/main`) — **success**.
+  - [`Auto Release` · 28704526903](https://github.com/eiei114/pi-baton/actions/runs/28704526903)
+    (event `push`, ref `refs/heads/main`) — **success**.
+- `Auto Release` detected the version bump, created tag `v0.7.2` and the GitHub
+  Release (11:18:35–37Z), then ran its final step:
+  `gh workflow run publish.yml --ref v0.7.2 -f ref=v0.7.2`
+  (log: `Run TAG="v0.7.2"` → `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`).
+- That dispatch produced the failed run **28704529442** at **11:18:38Z**.
+
+So a single version-bump merge produced **two** `publish.yml` runs for `0.7.2`:
+one from the `push` trigger (main) and one from `Auto Release`'s explicit
+`workflow_dispatch` (v0.7.2). This double-trigger is consistent with the design
+documented in [`docs/release.md`](../release.md) (the push trigger and the
+auto-release handoff both fire; the tag/`release.published` triggers are
+unreliable for `GITHUB_TOKEN`-created tags, which is why auto-release dispatches
+explicitly).
+
+### Race timeline (all times UTC)
+
+| Time | Run | Event |
+| --- | --- | --- |
+| 11:18:31 | 28704526901 / 28704526903 | merge push to `main` fires `publish.yml` (push) + `auto-release.yml` |
+| 11:18:35–37 | 28704526903 | `Auto Release` creates tag `v0.7.2`, release, dispatches `publish.yml` |
+| 11:18:38 | 28704529442 | dispatched `publish.yml` (v0.7.2) starts — the failed run |
+| 11:18:52 | 28704526901 | skip guard says `Publishing pi-baton@0.7.2.` (0.7.2 not yet on npm) |
+| **11:18:56** | **28704526901** | **`+ pi-baton@0.7.2` — push run publishes 0.7.2** |
+| 11:19:07 | 28704529442 | skip guard runs `npm view pi-baton@0.7.2 version` → **404** (skip=false) |
+| 11:19:08 | 28704529442 | prints `Publishing pi-baton@0.7.2.`, starts `npm publish` |
+| 11:19:11 | 28704529442 | `E403` — cannot publish over `0.7.2` (already published 11s earlier) |
+
+The decisive detail: the failed run's `npm view pi-baton@0.7.2 version` returned
+**404 at 11:19:07**, ~11 seconds **after** the push run actually published
+`0.7.2` at 11:18:56. The skip guard therefore proceeded, and `npm publish` hit
+the real-time conflict.
+
+### npm public state (read-only)
+
+```console
+$ npm view pi-baton version dist-tags.latest
+0.7.2
+{ latest: '0.7.2' }
+
+$ npm view pi-baton time --json
+{
+  "0.7.2": "2026-07-04T11:18:56.171Z",
+  ...
+}
+```
+
+The `0.7.2` timestamp was published by the winning push run (28704526901).
+
+`pi-baton@0.7.2` is present, is `dist-tags.latest`, and was published at
+11:18:56Z — i.e. by the parallel push run (28704526901), not by the failed run.
+Published versions: `0.2.2, 0.2.3, 0.3.0, 0.4.0, 0.5.0, 0.6.0, 0.7.0, 0.7.1,
+0.7.2`. No registry correction is needed.
+
+## Cause classification
+
+**Trigger / configuration** — specifically a concurrent-duplicate-publish race:
+
+1. **Double trigger for one version bump.** A `package.json` version bump on
+   `main` fires `publish.yml` twice: once via the `push` (branches: `main`,
+   paths: `package.json`) trigger, and once via `auto-release.yml`'s explicit
+   `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`.
+2. **Concurrency groups do not collide.** `publish.yml` uses
+   `group: npm-publish-${{ github.event.inputs.ref || github.ref }}`:
+   - push run → `npm-publish-refs/heads/main`
+   - dispatch run → `npm-publish-v0.7.2`
+   
+   Different keys ⇒ `concurrency` does not serialize the two runs; they execute
+   in parallel for the same version.
+3. **Non-atomic idempotency guard (TOCTOU).** "Skip already published version"
+   runs `npm view <name>@<version>` and, on 404, proceeds to `npm publish` in a
+   later step. There is no lock between check and publish, and `npm view` reads
+   registry metadata that lags the actual publish (here by ~11s). The losing run
+   therefore sees "not published", then loses the race to `npm publish`.
+
+Explicitly **not** the cause:
+
+- **Duplicate-version at dispatch.** No — `0.7.2` was not on npm when the run was
+  dispatched (11:18:38) or when its skip guard ran (the guard returned 404).
+- **Trusted Publishing / authentication.** No — provenance was signed
+  successfully, `permissions.id-token: write` is set, `registry-url` is correct,
+  and no `NPM_TOKEN` is used (Trusted Publishing). Auth was healthy.
+
+## Reproducible non-publish check
+
+These commands are **read-only** — they do not publish, rerun the workflow, or
+touch the registry/versions. They reproduce the diagnosis from a clean checkout.
+
+```bash
+# 1) Confirm 0.7.2 is published and is latest (read-only registry query).
+npm view pi-baton version                # -> 0.7.2
+npm view pi-baton dist-tags.latest       # -> 0.7.2
+npm view pi-baton@0.7.2 time --json      # -> "0.7.2": "2026-07-04T11:18:56.171Z"
+
+# 2) Show the two concurrent publish runs produced by one version-bump merge.
+#    (--created takes a date, not a full timestamp.)
+gh run list --repo eiei114/pi-baton --workflow "Publish to npm" \
+  --created 2026-07-04 --limit 10 \
+  --json databaseId,event,headBranch,conclusion,createdAt
+# Expect both:
+#   28704526901  push             main    success   (published 0.7.2)
+#   28704529442  workflow_dispatch v0.7.2 failure   (E403 duplicate)
+
+# 3) Show the dispatch origin (Auto Release triggered the failed run).
+gh run view 28704526903 --repo eiei114/pi-baton --log \
+  | grep -E 'gh workflow run publish.yml|released=true|TAG="v0.7.2"'
+
+# 4) Prove the two runs had DIFFERENT concurrency groups (so they raced).
+#    publish.yml: group: npm-publish-${{ github.event.inputs.ref || github.ref }}
+#    push run     -> github.event.inputs.ref is unset, github.ref = refs/heads/main
+#                    => "npm-publish-refs/heads/main"
+#    dispatch run -> github.event.inputs.ref = "v0.7.2"  (-f ref=v0.7.2)
+#                    => "npm-publish-v0.7.2"
+node -e '
+const g = (ref, inputRef) => `npm-publish-${inputRef || ref}`;
+console.log("push    :", g("refs/heads/main", undefined));
+console.log("dispatch:", g("refs/tags/v0.7.2", "v0.7.2"));
+console.log("collide :", g("refs/heads/main", undefined) === g("refs/tags/v0.7.2", "v0.7.2"));
+'
+# => push    : npm-publish-refs/heads/main
+# => dispatch: npm-publish-v0.7.2
+# => collide : false
+```
+
+## Minimal safe correction options
+
+None of these are applied here — they are candidates for a **separate
+correction issue** (release/publish workflows remain human-owned). Listed from
+smallest/safest to largest behavior change.
+
+- **Option A — make `npm publish` idempotent (recommended, smallest).** In the
+  `Publish to npm` step, treat the specific "cannot publish over the previously
+  published versions" `E403` as success instead of failure. This makes the
+  workflow resilient to the double-trigger race regardless of concurrency or
+  propagation lag. Scope the match to that exact message so genuine permission
+  errors still fail. Sketch (not applied):
+
+  ```bash
+  set +e
+  npm publish --access public 2>&1 | tee /tmp/publish.log
+  status=${PIPESTATUS[0]}
+  set -e
+  if [ "$status" -ne 0 ] && grep -Eq 'cannot publish over the previously published versions' /tmp/publish.log; then
+    echo "Version already published; treating publish as success."
+    exit 0
+  fi
+  exit "$status"
+  ```
+
+- **Option B — serialize the two runs via one concurrency group.** Replace the
+  ref-keyed group with a single constant group (e.g. `group: npm-publish`) and
+  keep `cancel-in-progress: false`, so the push run and the auto-release dispatch
+  queue instead of racing. Best combined with Option A, since the skip guard is
+  still non-atomic. Avoid `cancel-in-progress: true` here — cancelling mid-publish
+  risks a partial publish.
+
+- **Option C — collapse to a single handoff path.** Remove the `push`
+  (`branches: [main]`, `paths: [package.json]`) trigger from `publish.yml` so a
+  version bump publishes only via `auto-release.yml`'s explicit dispatch (the path
+  `docs/release.md` already describes as the reliable one). Largest behavior
+  change; needs validation that the manual tag / `release.published` /
+  `workflow_dispatch` entry points still cover intended cases.
+
+## Out of scope for this issue (enforced)
+
+Per the issue brief, this slice intentionally does **not**: edit release/publish
+workflows, publish a package, rerun the workflow, change the package version, or
+update the CHANGELOG. A safe correction should be tracked in a follow-up issue.

package/extensions/index.ts

@@ -5,7 +5,12 @@ import { MissingAgentsError, validateWorkflowAgents } from "../lib/agents.ts";
 import { ensureBatonScaffolding } from "../lib/paths.ts";
 import { formatRunResultSummary, runContinuous } from "../lib/run-engine.ts";
 import { createRunUiController } from "../lib/run-ui.ts";
-import { ActiveRunGuardError, createIdleRun, loadActiveRun } from "../lib/run-store.ts";
+import {
+  ActiveRunGuardError,
+  createIdleRun,
+  loadActiveRun,
+  loadMostRecentTerminalRun,
+} from "../lib/run-store.ts";
 import { NO_ACTIVE_RUN_MESSAGE, formatStatusSummary } from "../lib/status.ts";
 import { createSubagentRunner } from "../lib/subagent-runner.ts";
 import { WorkflowNameCollisionError, createWorkflowScaffold } from "../lib/workflow-scaffold.ts";
@@ -185,7 +190,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("baton:status", {
     description: "Show the active Baton run summary",
     handler: async (_args, ctx) => {
-      const manifest = await loadActiveRun(ctx.cwd);
+      const manifest = (await loadActiveRun(ctx.cwd)) ?? (await loadMostRecentTerminalRun(ctx.cwd));
       if (!manifest) {
         ctx.ui.notify(NO_ACTIVE_RUN_MESSAGE, "info");
         return;

package/lib/run-store.ts

@@ -41,13 +41,32 @@ export async function readRunManifest(cwd: string, runId: string): Promise<RunMa
   return readJson<RunManifest>(getRunManifestPath(cwd, runId));
 }
 
+function isTerminalRunState(state: RunState): boolean {
+  return state === "completed" || state === "failed";
+}
+
 export async function loadActiveRun(cwd: string): Promise<RunManifest | null> {
   const pointer = await readActiveRunPointer(cwd);
-  if (!pointer) return null;
+  if (!pointer?.runId) return null;
+
+  try {
+    const manifest = await readRunManifest(cwd, pointer.runId);
+    if (isTerminalRunState(manifest.state)) {
+      return null;
+    }
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+export async function loadMostRecentTerminalRun(cwd: string): Promise<RunManifest | null> {
+  const pointer = await readActiveRunPointer(cwd);
+  if (!pointer?.runId) return null;
 
   try {
     const manifest = await readRunManifest(cwd, pointer.runId);
-    if (manifest.state === "completed" || manifest.state === "failed") {
+    if (!isTerminalRunState(manifest.state)) {
       return null;
     }
     return manifest;

package/lib/status.ts

@@ -1,7 +1,17 @@
 import type { RunManifest } from "./types.ts";
 
+function isTerminalRunState(state: RunManifest["state"]): boolean {
+  return state === "completed" || state === "failed";
+}
+
 export function formatStatusSummary(manifest: RunManifest): string {
-  return [
+  const lines: string[] = [];
+
+  if (isTerminalRunState(manifest.state)) {
+    lines.push(`This Baton run has finished (${manifest.state}).`);
+  }
+
+  lines.push(
     `workflow: ${manifest.workflowName}`,
     `task brief: ${manifest.taskBrief}`,
     `last step: ${manifest.lastStep ?? "(none)"}`,
@@ -9,7 +19,9 @@ export function formatStatusSummary(manifest: RunManifest): string {
     `run state: ${manifest.state}`,
     `iteration count: ${manifest.iteration}`,
     `run directory: .pi/baton/runs/${manifest.id}`,
-  ].join("\n");
+  );
+
+  return lines.join("\n");
 }
 
 export const NO_ACTIVE_RUN_MESSAGE =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-baton",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Pi-native workflow baton runner with per-step model switching and isolated step context.",
   "type": "module",
   "engines": {
@@ -58,8 +58,8 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "latest",
-    "@earendil-works/pi-coding-agent": "latest",
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
     "typebox": "latest",
     "@types/node": "^26.0.1",
     "typescript": "^6.0.3"

package/docs/examples.md

@@ -1,49 +0,0 @@
-# Examples
-
-This template ships one minimal example for each Pi package resource type.
-
-## Extension
-
-`extensions/hello.ts` registers:
-
-- `/template-hello`
-- a small session status indicator
-
-Try it with:
-
-```bash
-pi -e .
-```
-
-Then run:
-
-```txt
-/template-hello YourName
-```
-
-## Agent Skill
-
-`skills/example-skill/SKILL.md` demonstrates a minimal Agent Skill.
-
-Replace it with your real workflow instructions.
-
-## Prompt template
-
-`prompts/example.md` demonstrates a tiny prompt template with one variable.
-
-## Theme
-
-`themes/example-theme.json` is a placeholder theme. Replace it or remove `themes/` if your package does not ship themes.
-
-## Typed custom tool
-
-`extensions/index.ts` registers:
-
-- `/template-info`
-- `template_greet` custom tool
-
-The tool demonstrates:
-
-- TypeBox object parameters
-- a string enum schema via `StringEnum`
-- shared logic imported from `lib/greeting.ts`

package/docs/github-template.md

@@ -1,63 +0,0 @@
-# GitHub Template Repository
-
-> **Template bootstrap doc.** Use while setting up a new repo from this template. Delete this file or merge any project-specific steps into README / Vault notes once setup is done, unless it still adds maintainer value.
-
-## Recommended development flow
-
-After generating a repo from this template, use this default order:
-
-```txt
-Vault notes -> PRD -> Issues -> implement -> ci/check -> release -> save learnings
-```
-
-In practice:
-
-1. Create Vault notes under `4_Project/<ProjectName>/`.
-2. Add `CONTEXT.md`, `README.md`, `ROADMAP.md`, `Docs/`, `Issues/`, and `Progress/`.
-3. Write the PRD in `Docs/`.
-4. Split approved issue files into `Issues/`.
-5. Implement in the OSS repo created from this template.
-6. Run CI and package checks before release.
-7. Save release notes and follow-up decisions back to the Vault project.
-
-Enable template mode on the source repository:
-
-```txt
-GitHub repo → Settings → General → Template repository
-```
-
-Create a public repository from the template:
-
-```bash
-gh repo create OWNER/new-pi-extension \
-  --public \
-  --template OWNER/pi-extension-template \
-  --clone
-```
-
-Create a private repository from the template:
-
-```bash
-gh repo create OWNER/new-pi-extension \
-  --private \
-  --template OWNER/pi-extension-template \
-  --clone
-```
-
-Include all branches if needed:
-
-```bash
-gh repo create OWNER/new-pi-extension \
-  --public \
-  --template OWNER/pi-extension-template \
-  --include-all-branches \
-  --clone
-```
-
-After creation:
-
-```bash
-cd new-pi-extension
-npm install
-npm run ci
-```\n

package/docs/repository-settings.md

@@ -1,43 +0,0 @@
-# Repository Settings
-
-> **Template bootstrap doc.** Use while configuring GitHub About, topics, and branch protection after generating a repo. Delete this file or merge needed settings into README once setup is done, unless it still adds maintainer value.
-
-Use this file after creating a real repository from the template.
-
-## GitHub About
-
-Suggested fields:
-
-- Description: one-line pitch for the Pi package
-- Website: npm package URL or project docs URL
-- Topics:
-  - `pi`
-  - `pi-package`
-  - `agent-skill`
-  - `typescript`
-
-## Template mode
-
-If this repository itself should be reusable as a template:
-
-```txt
-Settings → General → Template repository
-```
-
-## Branch protection
-
-Recommended for public packages:
-
-- Require pull request before merging
-- Require status checks to pass
-- Require `CI` workflow
-- Block force pushes on the default branch
-
-## npm package page
-
-After first publish:
-
-- Confirm README renders correctly
-- Confirm package provenance appears
-- Confirm package contents are intentional
-- Add npm URL to GitHub About and README

package/docs/template-checklist.md

@@ -1,140 +0,0 @@
-# Template Setup Checklist
-
-このテンプレートから新しい Pi 拡張OSSを作った後に埋めること。
-
-## Recommended flow
-
-- [ ] Vault project notes を `4_Project/<ProjectName>/` に作る
-- [ ] `CONTEXT.md` / `README.md` / `ROADMAP.md` / `Docs/` / `Issues/` / `Progress/` を揃える
-- [ ] PRD を `4_Project/<ProjectName>/Docs/` に置く
-- [ ] approved issue を `4_Project/<ProjectName>/Issues/` に切る
-- [ ] OSS repo 側で実装する
-- [ ] `npm run ci` / `npm test` / `npm pack --dry-run` を通す
-- [ ] release 後に Vault へ learnings / release notes を戻す
-
-## Repository
-
-- [ ] GitHub repository name を決める
-- [ ] GitHub About 欄を書く
-- [ ] GitHub topics を設定する
-  - [ ] `pi`
-  - [ ] `pi-package`
-  - [ ] `agent-skill`
-  - [ ] `typescript`
-- [ ] GitHub Settingsで `Template repository` をONにする
-- [ ] Repository URL を `package.json` に反映する
-- [ ] README の `OWNER/REPO` を実リポジトリに置き換える
-
-## Package metadata
-
-- [ ] `package.json` の `name` を変更する
-- [ ] `description` を書く
-- [ ] `author` を入れる
-- [ ] `repository.url` を埋める
-- [ ] `bugs.url` を埋める
-- [ ] `homepage` を埋める
-- [ ] `keywords` を見直す
-- [ ] `LICENSE` の年・名前を更新する
-
-## README placeholders
-
-- [ ] `PACKAGE_DISPLAY_NAME` を置き換える
-- [ ] `PACKAGE_NAME` を置き換える
-- [ ] `OWNER/REPO` を置き換える
-- [ ] one-line pitch を書く
-- [ ] feature list を書く
-- [ ] quick start command を実コマンドにする
-- [ ] npm URL を確認する
-- [ ] GitHub URL を確認する
-
-## Pi package manifest
-
-- [ ] `pi.extensions` に公開する拡張だけを残す
-- [ ] `pi.skills` に公開する skill だけを残す
-- [ ] 不要なら `prompts/` を消す
-- [ ] 不要なら `themes/` を消す
-- [ ] サンプル名を実名に変える
-
-## Documentation
-
-`docs/` は固定6ファイル必須ではない。README を正とし、価値がある doc だけ残す。
-
-### Required root files (public)
-
-- [ ] `README.md` — GitHub/npm の入口。Install / Quick start / Release / Security を含める
-- [ ] `LICENSE`
-- [ ] `SECURITY.md`
-- [ ] `CHANGELOG.md`
-- [ ] Release 手順が README と workflow で明確（Trusted Publishing 設定含む）
-
-### Recommended public docs (keep when useful)
-
-- [ ] `docs/examples.md` — 例が README に載り切らないとき
-- [ ] `docs/release.md` — Trusted Publishing や release 手順の詳細が README だけでは足りないとき
-- [ ] `docs/usage.md` — 使い方が README に載り切らないとき（必要なら新規作成）
-
-### Optional maintainer docs
-
-- [ ] `docs/template-checklist.md` — このファイル。成熟 repo では README からの主ナビにしない。不要なら削除可
-
-### Post-generation cleanup (delete or merge template setup docs)
-
-テンプレート生成直後の bootstrap 用。プロジェクト固有の価値がなければ削除し、必要な内容は README / `docs/release.md` / `docs/examples.md` に統合する。
-
-- [ ] `docs/github-template.md` を削除するか、固有の手順だけ README / Vault に移す
-- [ ] `docs/repository-settings.md` を削除するか、About/topics など必要分だけ README に移す
-- [ ] `docs/typescript.md` を削除するか、TypeScript 方針は README Development に要約する
-- [ ] README の Docs 節から、削除したファイルへのリンクを外す
-- [ ] `package.json` の `files` から、削除した `docs/` パスを外す（残す doc だけ明示する）
-
-## TypeScript
-
-- [ ] `extensions/index.ts` を実装に合わせて更新する
-- [ ] `extensions/hello.ts` が不要なら削除する
-- [ ] 共通ロジックを `lib/` に切り出す
-- [ ] `strict: true` を維持する
-- [ ] custom tool parameters は TypeBox schema で定義する
-- [ ] string choices は `StringEnum` helper を使う
-- [ ] runtime dependency は `dependencies`、Pi提供packageは `peerDependencies` に置く
-- [ ] `package.json.files` に公開対象だけを入れる
-- [ ] 詳細はセットアップ中だけ `docs/typescript.md` を参照し、不要なら post-generation cleanup で削除
-
-## GitHub Template repo
-
-- [ ] `gh repo create --template OWNER/pi-extension-template` で作成できることを確認する
-- [ ] public/privateどちらの作成例もdocsに載せる（`docs/github-template.md` を残す場合）
-
-## CI / Release
-
-- [ ] `npm run ci` が通る
-- [ ] `npm pack --dry-run` が通る
-- [ ] npm Trusted Publishing を設定する
-- [ ] npm Trusted Publisher の workflow filename が `publish.yml` になっている
-- [ ] `NPM_TOKEN` を使っていないことを確認する
-- [ ] `auto-release.yml` が `main` の version bump から tag/release を作ることを確認する
-- [ ] `publish.yml` が `workflow_dispatch` と `release.published` に対応していることを確認する
-- [ ] 初回リリースで npm provenance が付いているか確認する
-
-### Workflow handoff guard
-
-- [ ] `.github/workflows/auto-release.yml` exists before first release
-- [ ] `.github/workflows/publish.yml` exists before first release
-- [ ] `auto-release.yml` has `permissions: actions: write` and `contents: write`
-- [ ] `publish.yml` has `permissions: id-token: write` for npm Trusted Publishing
-- [ ] Auto release explicitly hands off to publish: `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`, or `publish.yml` has an equivalent `workflow_run` / `repository_dispatch` trigger
-- [ ] Do not rely only on `push.tags` or `release.published` when the tag/release is created by `GITHUB_TOKEN`; that can leave npm unchanged after merge
-
-## npm page
-
-- [ ] npm package URL を README に追加する
-- [ ] npm description が適切に表示されるか確認する
-- [ ] provenance が付いているか確認する
-- [ ] 不要なファイルが package に含まれていないか確認する（`npm pack --dry-run` で `docs/` の残し方も確認）
-
-## Before first release
-
-- [ ] サンプルコードを実機 Pi でロードする
-- [ ] `pi install git:github.com/OWNER/REPO` を試す
-- [ ] `pi -e .` を試す
-- [ ] README のコマンドがコピペで動くか確認する
-- [ ] CHANGELOG に `0.1.0` を書く

package/docs/typescript.md

@@ -1,77 +0,0 @@
-# TypeScript Guide
-
-> **Template bootstrap doc.** Use while learning this template's TypeScript layout and dependency rules. Delete this file or summarize the policies you keep in README Development once setup is done, unless it still adds maintainer value.
-
-This is a TypeScript-first Pi package template.
-
-## Layout
-
-```txt
-extensions/*.ts      Pi extension entrypoints
-lib/*.ts             Shared TypeScript helpers
-skills/*/SKILL.md    Agent Skills
-prompts/*.md         Prompt templates
-themes/*.json        Themes
-tests/*.test.mjs     Smoke tests
-tests/*.test.ts      Optional TypeScript tests if you add a TS test runner
-```
-
-Pi loads TypeScript extensions directly, so no build step is required for normal use.
-
-## Strict mode
-
-`tsconfig.json` keeps `strict: true`. Prefer fixing types over loosening compiler options.
-
-## Extension entrypoints
-
-Two entrypoint styles are shown:
-
-- `extensions/hello.ts`: single-file extension
-- `extensions/index.ts`: index-style extension that imports shared code from `lib/`
-
-For larger packages, keep entrypoints thin and put reusable logic in `lib/`.
-
-## TypeBox schemas
-
-Use TypeBox schemas for custom tool parameters.
-
-```ts
-import { Type } from "typebox";
-
-const parameters = Type.Object({
-  name: Type.String({ description: "Name to greet" }),
-});
-```
-
-## String enums
-
-For string choices, use the local `StringEnum` helper from `lib/schema.ts`.
-
-```ts
-import { StringEnum } from "../lib/schema.ts";
-
-const mode = StringEnum(["short", "friendly"], {
-  description: "Greeting style",
-});
-```
-
-This emits a JSON Schema `enum`, which is friendlier to model providers than a union of string literals.
-
-## Runtime dependencies vs peer dependencies
-
-Pi bundles core packages for extension authors. Keep Pi-provided packages as `peerDependencies` and also install them as `devDependencies` for local typechecking.
-
-Use `peerDependencies` for:
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-ai`
-- `@earendil-works/pi-tui`
-- `typebox`
-
-Use `dependencies` for runtime packages your extension imports that Pi does not provide.
-
-Use `devDependencies` for local-only tools such as TypeScript, test runners, and linters.
-
-## Package contents
-
-Control npm package contents with `package.json` `files`. Prefer this over `.npmignore` so the published package stays explicit.