pi-autotalk 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -4,10 +4,34 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
-## [0.1.0] - YYYY-MM-DD
+## [0.1.3] - 2026-06-18
+
+### Fixed
+
+- Release pipeline recovery: `publish.yml` now runs `npm publish --provenance` so npm Trusted Publishing (GitHub Actions OIDC) authenticates correctly. Without provenance, auto-release could create tags and GitHub Releases while npm publish failed with `E404`.
+
+### Changed
+
+- Maintainer release docs (`docs/release.md`, README) now point maintainers at the post-release verification checklist for GitHub release state and npm `latest` after every version bump.
+
+## [0.1.2] - 2026-06-06
+
+### Fixed
+
+- Auto-release workflow was added in 0.1.1 but version never changed in that commit, preventing npm publish. This release bumps the version so auto-release triggers and publishes to npm.
+
+## [0.1.1] - 2026-06-03
+
+### Changed
+
+- Removed stale template docs (`examples.md`, `github-template.md`, `repository-settings.md`, `template-checklist.md`, `typescript.md`) that referenced non-existent files and commands.
+- Updated README Package contents to reflect remaining docs.
+
+## [0.1.0] - 2025-06-01
 
 ### Added
 
-- Initial Pi package template.
-- Example extension, Agent Skill, prompt, and theme.
+- Initial pi-autotalk MVP: timed AutoTalk brainstorming from the editor input.
+- Commands: `/autotalk:on`, `/autotalk:off`, `/autotalk:mode`, `/autotalk:settings`.
+- Settings persistence and validation.
 - CI and npm Trusted Publishing workflow.

package/README.md

@@ -1,6 +1,7 @@
 # Pi AutoTalk
 
 [![CI](https://github.com/eiei114/pi-autotalk/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-autotalk/actions/workflows/ci.yml)
+[![Auto Release](https://github.com/eiei114/pi-autotalk/actions/workflows/auto-release.yml/badge.svg)](https://github.com/eiei114/pi-autotalk/actions/workflows/auto-release.yml)
 [![Publish](https://github.com/eiei114/pi-autotalk/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-autotalk/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/pi-autotalk.svg)](https://www.npmjs.com/package/pi-autotalk)
 [![npm downloads](https://img.shields.io/npm/dm/pi-autotalk.svg)](https://www.npmjs.com/package/pi-autotalk)
@@ -70,7 +71,7 @@ If the editor is empty, AutoTalk sends a one-shot continuation prompt:
 
 ```text
 [AutoTalk]
-入力欄が空です。ここまでの流れから、次に考える問いを1つ出してください。
+The editor is empty. From the conversation so far, ask one question to think about next.
 ```
 
 That empty prompt is sent only once. It resets after a real non-empty thought memo is sent.
@@ -90,11 +91,11 @@ Non-empty editor text is sent like this:
 
 ```text
 [AutoTalk]
-これは自動送信されたユーザーの思考メモです。
-アイデアを広げ、論点を整理し、次の問いを1つ出してください。
-明示依頼でない限り、ファイル編集・コマンド実行・外部送信はしないでください。
+This is an automatically sent user thought memo.
+Expand the ideas, organize the key points, and ask one follow-up question.
+Unless explicitly requested, do not edit files, run commands, or send external messages.
 
---- 思考メモ ---
+--- Thought memo ---
 {editor text}
 ```
 
@@ -178,7 +179,7 @@ Useful commands:
 | `extensions/index.ts` | Pi extension entrypoint and command/timer wiring. |
 | `lib/autotalk.ts` | Settings validation, persistence, and message formatting helpers. |
 | `tests/` | Node test suite for package metadata, formatting, settings, and registration. |
-| `docs/` | Release and template maintenance docs. |
+| `docs/` | Release and publishing docs. |
 
 ## Development
 
@@ -213,14 +214,22 @@ For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
 
 ## Release
 
-This package is set up for npm Trusted Publishing, so no `NPM_TOKEN` is required.
+This package uses npm Trusted Publishing (OIDC). No `NPM_TOKEN` is required.
+
+On merge to `main` with a `package.json` version bump, `.github/workflows/auto-release.yml` creates the `v*` tag and GitHub release, then dispatches `.github/workflows/publish.yml` to publish to npm.
+
+Maintainer flow:
 
 ```bash
-npm version patch
-git push --follow-tags
+npm version patch   # or minor/major — updates package.json, package-lock.json (if present), creates a git commit and tag by default
+git push origin main
 ```
 
-See [`docs/release.md`](docs/release.md) for setup details.
+You can also bump `version` in `package.json` in a PR; after merge, auto-release handles tagging and publish.
+
+After merge, run the [post-release verification checklist](docs/release.md#post-release-verification-checklist) in `docs/release.md` to confirm the GitHub tag/release, Publish Package workflow, and npm `latest` all match the new version. A green auto-release run alone is not proof npm received the package.
+
+See [`docs/release.md`](docs/release.md) for setup, recovery, and verification details.
 
 ## Links
 
@@ -230,4 +239,4 @@ See [`docs/release.md`](docs/release.md) for setup details.
 
 ## License
 
-MIT
+MIT

package/docs/release.md

@@ -1,38 +1,303 @@
 # Release
 
-This package uses npm Trusted Publishing with GitHub Actions OIDC.
+This package publishes to npm with **npm Trusted Publishing (GitHub Actions OIDC)**.
 
-Do not add `NPM_TOKEN` or long-lived npm tokens to GitHub Secrets.
+Do **not** add `NPM_TOKEN` or any long-lived npm token to GitHub Secrets. The
+publish step authenticates via an OIDC token minted by GitHub Actions and linked
+to this package on npmjs.com.
+
+> **Release pipeline recovery (`0.1.3`):** Prior drift (GitHub at `v0.1.2`, npm
+> `latest` at `0.1.0`) was caused by `publish.yml` running `npm publish` without
+> `--provenance`, so OIDC Trusted Publishing never authenticated. `0.1.3` fixes
+> the workflow and is the supported path to bring npm `latest` back in sync.
+> After merge, run the [verification checklist](#post-release-verification-checklist)
+> below. Historical drift details remain in [Known release drift](#known-release-drift--2026-06-investigation).
+
+## Model
+
+Two workflows cooperate:
+
+- `.github/workflows/auto-release.yml` — on push to `main` that increases
+  `package.json#version`, creates tag `v<version>`, creates the GitHub Release,
+  then dispatches `publish.yml` at that ref.
+- `.github/workflows/publish.yml` — checks out the ref, runs CI, then publishes
+  to npm. It triggers on `push: tags v*` (manual `npm version` + push) **and** on
+  `workflow_dispatch` from `auto-release.yml`.
+
+The critical handoff is the last hop: auto-release can succeed (tag + release
+created, publish dispatched) while the dispatched `publish.yml` still fails at
+`npm publish`. A green auto-release run is **not** proof that npm received the
+package — always run the [verification checklist](#post-release-verification-checklist).
 
 ## One-time npm setup
 
-On npmjs.com, configure Trusted Publishing for this package:
+On npmjs.com, configure Trusted Publishing for this package (`eiei114/pi-autotalk`):
 
 - Publisher: GitHub Actions
-- Repository: this GitHub repository
+- Repository: `eiei114/pi-autotalk`
 - Workflow filename: `publish.yml`
+- (Optional) Environment: leave unset unless you pin one in the workflow
+
+This must be done **before** the first automated publish. If 0.1.0 was published
+manually with a local login, the Trusted Publisher link may have never been
+created — verify it during [recovery](#recovery-github-release-exists-but-npm-latest-is-stale).
 
 ## Publish
 
+### Automated (recommended)
+
+1. Bump `version` in `package.json` and update `CHANGELOG.md` in the same change
+   (e.g. via a PR; the CI `version:check` guard requires a matching CHANGELOG
+   entry when the version increases).
+2. Merge to `main`.
+3. `auto-release.yml` detects the version increase, creates tag `v<version>` and
+   a GitHub Release, then runs `gh workflow run publish.yml --ref v<version>`.
+4. `publish.yml` checks out that ref, runs CI, and publishes via OIDC.
+5. Run the [verification checklist](#post-release-verification-checklist).
+
+### Manual tag (fallback)
+
 ```bash
-npm version patch
-git push --follow-tags
+npm version patch        # or minor / major
+git push origin main --follow-tags
 ```
 
-The `v*` tag triggers `.github/workflows/publish.yml`, which runs CI and publishes to npm.
+A `v*` tag push triggers `publish.yml` directly. Use this for a one-off release
+when you do not want to rely on auto-release. Still run the verification
+checklist afterward.
+
+## Post-release verification checklist
+
+Run **after every version bump**, whether automated or manual. A release is only
+"done" when npm `latest` equals the new version.
+
+Replace `<v>` with the version (e.g. `0.1.2`) and `<V>` with the tag (e.g. `v0.1.2`).
+
+- [ ] **Auto Release ran and succeeded** on the `main` commit that bumped the
+      version.
+      `gh run list --workflow=auto-release.yml --limit 5`
+- [ ] **Tag `<V>` exists** on the remote and points at the bump commit.
+      `git ls-remote --tags origin 'v*'`  →  must list `<V>`
+- [ ] **GitHub Release `<V>` exists** and is published (not draft, not prerelease).
+      `gh release view <V>`
+- [ ] **Publish Package ran for `<V>`** and its conclusion is `success`. This is
+      the run auto-release dispatched (event `workflow_dispatch`, branch `<V>`).
+      `gh run list --workflow=publish.yml --limit 10`
+- [ ] If Publish Package **failed**, open the run and read the `Run npm publish`
+      step log. The most common failure is `npm error code E404 ... PUT
+      https://registry.npmjs.org/pi-autotalk - Not found` (see
+      [Recovery](#recovery-github-release-exists-but-npm-latest-is-stale)).
+      `gh run view <run-id> --log`
+- [ ] **npm `latest` equals `<v>`.**
+      `npm view pi-autotalk version`
+- [ ] **npm shows `<v>` in `time`.**
+      `npm view pi-autotalk time --json`
+
+One-liner snapshot for a quick diff after release:
+
+```bash
+node -p "require('./package.json').version"   # repo
+git ls-remote --tags origin 'v*'              # tags
+gh release list --limit 5                     # releases
+gh run list --workflow=publish.yml --limit 5  # publish runs
+npm view pi-autotalk version                  # npm latest
+```
+
+A release is healthy **iff** the repo version, the newest `v*` tag, the newest
+GitHub Release, the newest successful Publish run, and npm `latest` all agree.
+
+## Recovery: GitHub release exists but npm latest is stale
+
+Use this when a tag + GitHub Release exist for `<V>` but `npm view
+pi-autotalk version` returns an older version. This matches the 2026-06 drift.
+
+### 1. Confirm and scope the drift
+
+```bash
+npm view pi-autotalk version          # current npm latest
+npm view pi-autotalk time --json      # every published version + dates
+git ls-remote --tags origin 'v*'      # every GitHub tag
+gh release list                       # every GitHub Release
+```
+
+Any tag `<V>` with no matching entry in npm `time` is a missing publish. List
+them; you will republish each missing version.
+
+### 2. Find why the publish failed
+
+Find the Publish Package run that auto-release dispatched for `<V>` (event
+`workflow_dispatch`, branch `<V>`):
+
+```bash
+gh run list --workflow=publish.yml --branch <V> --limit 5
+gh run view <run-id> --log           # read the "Run npm publish" step
+```
+
+For the 2026-06 drift the failing run was `27050120988` and the error was:
+
+```bash
+npm error code E404
+npm error 404 Not Found - PUT https://registry.npmjs.org/pi-autotalk - Not found
+npm error 404  'pi-autotalk@0.1.2' is not in this registry.
+```
+
+The most likely root cause (this repo's model is Trusted Publishing, no token):
+
+- `publish.yml` runs `npm publish` **without `--provenance`** and exposes **no
+  `NODE_AUTH_TOKEN`**. npm Trusted Publishing via GitHub Actions OIDC is only
+  exercised when the publish runs with `--provenance`; without it the npm CLI
+  never mints the OIDC token, the PUT is effectively unauthenticated, and npm
+  returns `E404` (it hides package existence from unauthenticated callers).
+- Rule out the secondary cause: the **Trusted Publisher is not registered on
+  npmjs.com**, or is scoped to the wrong workflow file / trigger. On npmjs.com
+  open the package → Settings → Trusted Publishers and confirm: repository
+  `eiei114/pi-autotalk`, workflow filename `publish.yml`. Because 0.1.0 was
+  published with a manual login, this link may have never been created.
+
+### 3. Fix the publish path before republishing
+
+Pick the fix that matches this repo's model (Trusted Publishing):
+
+- Ensure `publish.yml` publishes with provenance (`npm publish --provenance`)
+  and that the job still has `permissions: id-token: write`. This is fixed on
+  `main` starting with `0.1.3`.
+- Confirm the Trusted Publisher registration on npmjs.com (step 2).
+
+(If you ever move away from Trusted Publishing, the alternative is to set an npm
+automation token in `NPM_TOKEN` and expose `NODE_AUTH_TOKEN: ${{
+secrets.NPM_TOKEN }}` on the publish step. This repo deliberately does **not** do
+that.)
+
+Do the fix on `main` first and verify with a real release before republishing
+historical versions — otherwise every republish will fail the same way.
+
+### 4. Republish the missing version(s)
+
+Each missing version must be published from its **own** tagged commit (npm
+rejects re-publishing a version, and you cannot publish `0.1.2` from the `0.1.1`
+tree). For each `<V>` that exists as a tag but not on npm:
+
+```bash
+# Re-dispatch publish.yml at the existing tag (mirrors what auto-release does).
+gh workflow run publish.yml --ref <V> -f ref=<V>
+
+# Watch the run.
+gh run list --workflow=publish.yml --branch <V> --limit 3
+gh run watch <run-id>
+```
+
+`--ref <V>` checks out the tagged commit, so the published `package.json`
+version matches the tag. Do **not** create new tags or bump the version for a
+recovery publish — you are publishing a version that already exists on GitHub.
+
+For the 2026-06 drift, repeat for `v0.1.1` and `v0.1.2` if both should appear on
+npm; if only the newest matters, publish `v0.1.2` and accept the `0.1.1` gap
+(document it here under [Known release drift](#known-release-drift--2026-06-investigation)).
+
+### 5. Confirm npm and fix the `latest` dist-tag
+
+```bash
+npm view pi-autotalk version          # should now be <v>
+npm view pi-autotalk dist-tags        # latest should point at <v>
+```
+
+`npm publish` moves `latest` to the highest published version automatically. If
+it is wrong (e.g. you published an older missing version after a newer one),
+repoint it explicitly:
+
+```bash
+npm dist-tag add pi-autotalk@<v> latest
+```
+
+### 6. Notes and caveats
+
+- npm only allows `unpublish` within 72 hours of publish, and only when nothing
+  depends on the version. Prefer `npm deprecate pi-autotalk@<v> "reason"` over
+  unpublish for old versions.
+- You cannot republish a version that is already on npm. If a partial publish
+  created the version but `latest` is wrong, fix the dist-tag, do not republish.
+- A failed `Publish Package` run leaves **no** artifact on npm — retrying the
+  same version is safe and expected.
+
+## Known release drift — 2026-06 investigation
+
+Snapshot taken 2026-06-14. Concrete versions, dates, and SHAs so future audits
+are not relative-time ambiguous.
+
+| Artifact | Value | Observed |
+|---|---|---|
+| `package.json` version (main HEAD) | `0.1.2` | commit `bdd0807`, merged 2026-06-06 |
+| Git tags (local + remote) | `v0.1.2` only | points at `bdd0807`; created 2026-06-06T02:30:07Z |
+| GitHub Releases | `v0.1.2` only | published 2026-06-06T02:30:16Z |
+| npm `latest` dist-tag | `0.1.0` | — |
+| npm published versions | `0.1.0` only | `0.1.0` published 2026-05-31T02:52:46Z; registry not modified since |
+| npm package maintainer | `eiei114` | — |
+
+**Drift:** GitHub and `package.json` are at `v0.1.2`; npm `latest` is `0.1.0`.
+`0.1.1` and `0.1.2` exist on GitHub but were never published to npm.
+
+### How each version reached its current state
+
+- **`0.1.0`** — published to npm 2026-05-31T02:52:46Z. The auto-release and
+  publish workflows did not exist yet (auto-release was added in commit
+  `03073d8`, 2026-06-06). 0.1.0 was therefore a **manual** publish by the
+  maintainer, not a workflow publish. No `v0.1.0` tag and no GitHub Release were
+  created.
+- **`0.1.1`** — `version` set to `0.1.1` in `package.json` at commit `34e2a2a`
+  (2026-06-03). Auto-release did not exist yet, so the bump was never observed:
+  no tag, no release, no publish. npm never received 0.1.1.
+- **`0.1.2`** — bump at commit `3f32c88`, merged to `main` as `bdd0807`
+  (2026-06-06T02:30Z). Auto-release ran and **succeeded**: it created tag
+  `v0.1.2`, GitHub Release `v0.1.2`, and dispatched `publish.yml` at `v0.1.2`
+  (run `27050120988`, event `workflow_dispatch`). That Publish Package run
+  **failed** at the `Run npm publish` step with `npm error code E404 / 404 Not
+  Found - PUT https://registry.npmjs.org/pi-autotalk`. Every preceding step
+  (checkout, setup-node, `npm ci`, typecheck, test, `pack:check`) passed and the
+  tarball was built correctly (`pi-autotalk@0.1.2`, 7 files, 7.6 kB).
+
+### Most likely failure point
+
+The break is the **last hop**: `npm publish` inside `publish.yml`.
+
+- `publish.yml` runs `npm publish` with no `--provenance` and exposes no
+  `NODE_AUTH_TOKEN`. With the Trusted Publishing model there is no token secret
+  by design.
+- npm Trusted Publishing via GitHub Actions OIDC is only exercised when the
+  publish runs **with `--provenance`**. Without it the npm CLI never mints the
+  OIDC token, the PUT is effectively anonymous, and npm returns `E404`.
+- Secondary cause to rule out during recovery: the Trusted Publisher is not
+  registered on npmjs.com, or is scoped to the wrong workflow file / trigger
+  (e.g. registered for `push: tags` only, not `workflow_dispatch`). Because
+  `0.1.0` was published manually, the link may have never been created.
+
+The fix, verification, and republish steps are in
+[Recovery](#recovery-github-release-exists-but-npm-latest-is-stale). No version
+bump, CHANGELOG entry, tag, or npm publish was performed as part of this
+investigation slice — it is documentation only; the actual republish is a
+separate, explicitly approved action.
 
 ## GitHub Actions requirements
 
-- `permissions: id-token: write`
+- `permissions: id-token: write` on the publish job
 - GitHub-hosted runner
 - No `NPM_TOKEN`
-- `npm publish` from the configured workflow file
+- `npm publish` (with `--provenance` for Trusted Publishing) from the configured
+  workflow file (`publish.yml`)
+
+## Local prerelease dry run
+
+```bash
+npm run ci            # typecheck + tests + pack:check
+npm pack --dry-run    # confirm only intended files are included
+```
 
 ## First release checklist
 
-- [ ] `package.json` name is final
+- [ ] `package.json` name is final (`pi-autotalk`)
 - [ ] `repository.url` points to the real GitHub repository
-- [ ] npm Trusted Publisher is configured
+- [ ] npm Trusted Publisher is configured on npmjs.com (repo + `publish.yml`)
 - [ ] `npm run ci` passes
 - [ ] `npm pack --dry-run` contains only intended files
-- [ ] `CHANGELOG.md` has the release date
+- [ ] `CHANGELOG.md` has the release date
+- [ ] First automated publish passes the
+      [verification checklist](#post-release-verification-checklist)

package/lib/autotalk.ts

@@ -20,14 +20,17 @@ export const DEFAULT_SETTINGS: AutoTalkSettings = {
   deliveryMode: "followUp",
 };
 
+/** Path to the global AutoTalk settings JSON file under `~/.pi`. */
 export function getSettingsPath(): string {
   return join(homedir(), ".pi", "agent", "extensions", "autotalk", "settings.json");
 }
 
+/** Returns true when `value` is a supported AutoTalk delivery mode. */
 export function isDeliveryMode(value: unknown): value is DeliveryMode {
   return value === "followUp" || value === "steer";
 }
 
+/** Coerces unknown persisted settings into a valid `AutoTalkSettings` object. */
 export function normalizeSettings(value: unknown): AutoTalkSettings {
   if (!value || typeof value !== "object") return { ...DEFAULT_SETTINGS };
 
@@ -40,6 +43,7 @@ export function normalizeSettings(value: unknown): AutoTalkSettings {
   return { intervalSec, deliveryMode };
 }
 
+/** Parses an interval in seconds; returns `undefined` when out of range or invalid. */
 export function normalizeInterval(value: unknown): number | undefined {
   if (typeof value === "string" && value.trim() !== "") {
     return normalizeInterval(Number(value));
@@ -50,6 +54,7 @@ export function normalizeInterval(value: unknown): number | undefined {
   return value;
 }
 
+/** Loads settings from disk, falling back to defaults when the file is missing or invalid. */
 export async function loadSettings(path = getSettingsPath()): Promise<AutoTalkSettings> {
   try {
     const text = await readFile(path, "utf8");
@@ -59,6 +64,7 @@ export async function loadSettings(path = getSettingsPath()): Promise<AutoTalkSe
   }
 }
 
+/** Persists settings as formatted JSON, creating parent directories when needed. */
 export async function saveSettings(
   settings: AutoTalkSettings,
   path = getSettingsPath(),
@@ -68,17 +74,19 @@ export async function saveSettings(
 `, "utf8");
 }
 
+/** Wraps editor text in the AutoTalk thought-memo prompt sent to the agent. */
 export function formatThoughtMemo(text: string): string {
   return `[AutoTalk]
-これは自動送信されたユーザーの思考メモです。
-アイデアを広げ、論点を整理し、次の問いを1つ出してください。
-明示依頼でない限り、ファイル編集・コマンド実行・外部送信はしないでください。
+This is an automatically sent user thought memo.
+Expand the ideas, organize the key points, and ask one follow-up question.
+Unless explicitly requested, do not edit files, run commands, or send external messages.
 
---- 思考メモ ---
+--- Thought memo ---
 ${text}`;
 }
 
+/** Returns the one-shot empty-editor continuation prompt. */
 export function formatEmptyPrompt(): string {
   return `[AutoTalk]
-入力欄が空です。ここまでの流れから、次に考える問いを1つ出してください。`;
+The editor is empty. From the conversation so far, ask one question to think about next.`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-autotalk",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "A Pi extension for timed AutoTalk brainstorming from the editor input.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,8 @@
     "typecheck": "tsc --noEmit",
     "test": "node --test tests/*.test.mjs",
     "ci": "npm run typecheck && npm test && npm run pack:check",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "version:check": "node scripts/check-version-bump.mjs"
   },
   "pi": {
     "extensions": [
@@ -48,7 +49,7 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "latest",
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.9.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,43 +0,0 @@
-# GitHub Template Repository
-
-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
-```

package/docs/repository-settings.md

@@ -1,41 +0,0 @@
-# Repository Settings
-
-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,85 +0,0 @@
-# Template Setup Checklist
-
-このテンプレートから新しい Pi 拡張OSSを作った後に埋めること。
-
-## 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/` を消す
-- [ ] サンプル名を実名に変える
-
-## 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` に公開対象だけを入れる
-
-## GitHub Template repo
-
-- [ ] `gh repo create --template OWNER/pi-extension-template` で作成できることを確認する
-- [ ] public/privateどちらの作成例もdocsに載せる
-
-## CI / Release
-
-- [ ] `npm run ci` が通る
-- [ ] `npm pack --dry-run` が通る
-- [ ] npm Trusted Publishing を設定する
-- [ ] `NPM_TOKEN` を使っていないことを確認する
-- [ ] tag publish が動くことを初回リリースで確認する
-
-## npm page
-
-- [ ] npm package URL を README に追加する
-- [ ] npm description が適切に表示されるか確認する
-- [ ] provenance が付いているか確認する
-- [ ] 不要なファイルが package に含まれていないか確認する
-
-## Before first release
-
-- [ ] サンプルコードを実機 Pi でロードする
-- [ ] `pi install git:github.com/OWNER/REPO` を試す
-- [ ] `pi -e .` を試す
-- [ ] README のコマンドがコピペで動くか確認する
-- [ ] CHANGELOG に `0.1.0` を書く

package/docs/typescript.md

@@ -1,75 +0,0 @@
-# TypeScript Guide
-
-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.