pi-short-links 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: force OSC 8 for Orca/`FORCE_HYPERLINK`, shorten long assistant URLs and paths to pane-fitting markdown links.

package/LICENSE

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

package/README.md

@@ -0,0 +1,46 @@
+# Pi Short Links
+
+Shorten long URLs and absolute file paths in Pi assistant output so clickable links fit the terminal pane.
+
+## Why
+
+Long bare URLs wrap across lines. Terminals that only detect text URLs (or terminals Pi does not yet mark as OSC 8-capable) open only the first wrapped line. This package:
+
+1. Forces OSC 8 hyperlinks when `FORCE_HYPERLINK=1` or `TERM_PROGRAM=Orca`
+2. Rewrites assistant text that exceeds the pane width into short markdown links (`[host/…tail](full-url)`, `[~/dir/…/file](file://…)`)
+3. Leaves fenced code blocks untouched
+
+## Install
+
+```bash
+pi install npm:pi-short-links
+# or local dogfood
+pi install /path/to/pi-short-links
+```
+
+Add to project `.pi/settings.json` `packages`:
+
+```json
+"../../OSS/pi-short-links"
+```
+
+## Features
+
+- Pane-width-aware shortening for bare `http(s)` URLs
+- Absolute / `~/` path shortening with `file://` targets
+- Skips content inside ` ``` ` fences
+- Does not rewrite existing markdown links' destinations
+
+## Non-goals
+
+- Orca-specific wrap-join fixes
+- Public URL shorteners
+- Rewriting tool-result bodies (assistant text only in v0.1)
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+```

package/docs/examples.md

@@ -0,0 +1,134 @@
+# Examples
+
+This template ships examples for each Pi package resource type and several extension API patterns.
+
+These source files (`extensions/`, `skills/`, `prompts/`, `themes/`) are the **single source of truth**:
+the `sync:template` script copies them into the `create-pi-extension` CLI bundle before publish.
+To update what the CLI generates, edit these files and re-run `bun run sync:template`.
+Scaffold a new project to get a copy of the latest examples:
+
+```bash
+bunx create-pi-extension my-pi-package
+```
+
+Then try the examples in your scaffolded project with `pi -e .`.
+
+For a full walkthrough, see the [README](../README.md).
+
+For maintainers, see [`docs/template-sync-checklist.md`](template-sync-checklist.md) for the sync procedure before publish.
+
+## Extension
+
+`extensions/hello.ts` registers:
+
+- `/template-hello`
+- `/template-status` (TUI-only custom entry via `appendEntry` + `registerEntryRenderer`)
+- session, turn, and tool lifecycle event handlers
+- a small session status indicator
+
+Try it with:
+
+```bash
+pi -e .
+```
+
+Then run:
+
+```txt
+/template-hello YourName
+/template-status Package ready
+?template
+```
+
+## Agent Skill (package manifest)
+
+`skills/example-skill/SKILL.md` demonstrates a minimal Agent Skill. Its
+frontmatter uses the required `name` and `description` fields plus the optional
+`license` field, following the Agent Skills spec that Pi validates against
+(see `docs/skills.md`).
+
+Replace it with your real workflow instructions.
+
+## Agent Skill (extension `resources_discover`)
+
+`extensions/skill-bridge/` contributes `template-skill-bridge` at runtime:
+
+- `index.ts` returns `skillPaths` from the `resources_discover` event
+- `SKILL.md` lives beside the extension entrypoint
+
+Commands:
+
+```txt
+/template-skill-info
+/skill:template-skill-bridge
+```
+
+Use this pattern when a skill should ship with an extension instead of the top-level `skills/` directory.
+
+## Typed custom tool
+
+`extensions/index.ts` registers:
+
+- `/template-info`
+- `template_greet` custom tool
+
+The tool demonstrates:
+
+- `pi.registerTool()` with TypeBox object parameters
+- a string enum schema via `StringEnum`
+- `prepareArguments()` for legacy argument compatibility before schema validation
+- custom `renderCall` / `renderResult` rendering
+- shared logic imported from `lib/greeting.ts`
+- TUI `renderCall` / `renderResult` via `Text`
+
+## TUI component composition
+
+`extensions/tui-dashboard.ts` demonstrates composing `@earendil-works/pi-tui` primitives:
+
+- `Box` for padded, themed containers
+- `Loader` for spinner-style progress feedback
+- column-aligned tables built with shared `lib/format-table.ts` and rendered via `Text`
+
+Command:
+
+```txt
+/template-dashboard
+```
+
+`pi-tui` does not ship a dedicated `Table` or `Spinner` component; this example uses `Loader` for spinners and a small table formatter for aligned columns.
+
+## Multi-file extension layout
+
+`extensions/package-layout/` demonstrates a subdirectory extension with local modules:
+
+- `lib/config.ts` — typed configuration defaults
+- `lib/stats.ts` — resource metadata helpers
+- imports from package-wide `lib/format-table.ts`
+
+Commands:
+
+```txt
+/template-layout
+/template-layout-clear
+```
+
+## Prompt template
+
+`prompts/example.md` demonstrates a tiny prompt template with one positional
+argument (`/example <topic>`). Pi expands templates with `$1`, `$@`, and
+`${1:-default}` — it does not support Mustache-style `{{var}}` placeholders.
+
+## Theme
+
+`themes/example-theme.json` ships a complete, loadable dark theme as a starting
+point. Pi requires every theme to define all 51 color tokens, so edit the
+palette in place rather than trimming tokens. Remove `themes/` (and the
+`pi.themes` manifest entry) if your package does not ship themes.
+
+## Shared library helpers
+
+| File | Purpose |
+|---|---|
+| `lib/greeting.ts` | Greeting helpers used by `template_greet` |
+| `lib/format-table.ts` | Monospace table formatter for widgets and TUI examples |
+| `lib/config-contract.ts` | Schema-derived runtime config validation with valid/invalid contract tests |

package/docs/github-template.md

@@ -0,0 +1,63 @@
+# 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/publish-rerun-rollout.md

@@ -0,0 +1,26 @@
+# Publish rerun guard rollout
+
+Template fix: `publish.yml` now checks `https://registry.npmjs.org/<package>/<version>` before `setup-node` configures OIDC auth. Reruns for an already-published version exit green and log `publish intentionally skipped`.
+
+## Why downstream repos need this
+
+Older template copies used `npm view` after `setup-node` with `registry-url`. With npm Trusted Publishing, authenticated metadata reads can return `404` even when the version exists, so the guard misses and `npm publish` fails with `403 Forbidden - You cannot publish over the previously published versions`.
+
+## Rollout list
+
+Apply the updated `publish.yml` skip step (or merge the latest `pi-extension-template` workflow) in:
+
+- [ ] `pi-startup-picker` — failed run `28704558891` on `v0.2.2`
+- [ ] `pi-git-delegate` — failed run `28704535034` on `0.2.2`
+- [ ] `pi-baton` — failed run `28704529442` on `0.7.2`
+- [ ] `pi-widget-host` — failed run `28704568448` on `0.3.3`
+- [ ] `pi-widget-core` — failed run `28704566953` on `0.1.2`
+- [ ] `pi-handoff-clipboard` — failed run `28704536299`
+- [ ] `pi-scheduled-router` — failed run `28704552385`
+
+## Verification after rollout
+
+1. Open Actions → `Publish to npm`.
+2. Run `workflow_dispatch` on the tag for a version that is already on npm.
+3. Confirm logs contain `publish intentionally skipped`.
+4. Confirm the run is green and `npm publish` did not run.

package/docs/release.md

@@ -0,0 +1,108 @@
+# Release
+
+This repository publishes **`create-pi-extension`** to npm using Trusted Publishing with GitHub Actions OIDC.
+
+The root `pi-extension-template` package is the **template source** and is not published to npm. Only `packages/create-pi-extension` is published.
+
+Do not add `NPM_TOKEN` or long-lived npm tokens to GitHub Secrets.
+
+## One-time npm setup
+
+On npmjs.com, configure Trusted Publishing for **`create-pi-extension`**:
+
+- Publisher: GitHub Actions
+- Repository: `eiei114/pi-extension-template`
+- Workflow filename: `publish.yml`
+- Permissions: publish (and stage publish if used)
+
+Remove or update any Trusted Publisher entry that still targets the legacy root package name `pi-extension-template`.
+
+## Publish
+
+```bash
+npm version patch
+git push
+```
+
+On `main`, `.github/workflows/auto-release.yml` checks the root `package.json` **repository version**. If `v<version>` does not exist yet, it creates the tag, creates the GitHub Release, then explicitly dispatches `.github/workflows/publish.yml` for that tag.
+
+The `v*.*.*` tag also triggers `.github/workflows/publish.yml`, which syncs the bundled template, runs CI, and publishes `create-pi-extension@<version>` to npm when tags are pushed manually.
+
+Publishing also runs when a GitHub Release is published, and can be run manually from GitHub Actions with `workflow_dispatch`.
+
+`publish.yml` runs `npm run sync:template` before publish so the tarball includes the current **Bundled template** under `packages/create-pi-extension/template/`.
+
+The workflow skips `create-pi-extension@<version>` if that exact package version already exists on npm.
+
+### Rerun and manual dispatch
+
+`publish.yml` checks the public npm registry API before `setup-node` configures OIDC auth. That keeps already-published reruns green:
+
+- `workflow_dispatch` on an existing tag/ref
+- duplicate `publish.yml` runs for the same `v<version>`
+- auto-release handoff retries after a successful publish
+
+When the version already exists, the job still runs validation but logs `publish intentionally skipped` and exits without calling `npm publish`.
+
+Do not use `npm view` after `setup-node` with `registry-url` for this guard. Trusted Publishing OIDC can make authenticated metadata reads look like `404`, which leads to duplicate `E403` publish failures.
+
+See also `docs/publish-rerun-rollout.md` for downstream rollout notes.
+
+### First publish / Trusted Publisher not configured
+
+`publish.yml` logs two different situations before `npm publish`:
+
+| Registry check | Meaning | Workflow behavior |
+| --- | --- | --- |
+| `GET /create-pi-extension` returns **404** | Package name is **not registered** on npm yet | Continues to publish; logs Trusted Publisher setup guidance |
+| `GET /create-pi-extension/<version>` returns **200** | That exact version is **already published** | Logs `publish intentionally skipped` and exits green without `npm publish` |
+| Package exists, version returns **404** | New version for an existing package | Continues to publish |
+
+If Trusted Publisher is missing or still targets the legacy `pi-extension-template` package, `npm publish` fails with:
+
+```text
+npm error code E404
+npm error 404 Not Found - PUT https://registry.npmjs.org/create-pi-extension - Not found
+```
+
+That `E404` is **not** the rerun skip path. It means npm rejected the publish because the package name is not registered under your account yet, or OIDC Trusted Publishing is not authorized for `create-pi-extension` + `publish.yml`.
+
+Fix (human-owned, one-time on npmjs.com):
+
+1. Open **create-pi-extension** on npm (or create the package name under your npm org/user if npm allows pre-registration).
+2. Add **Trusted Publisher**: GitHub Actions, repository `eiei114/pi-extension-template`, workflow filename `publish.yml`, permissions **publish** (and stage publish if used).
+3. Remove or update any Trusted Publisher entry that still targets the legacy root package `pi-extension-template`.
+4. Re-run `publish.yml` via `workflow_dispatch` on the release tag/ref (for example `v0.1.7`).
+
+Do not add `NPM_TOKEN` to GitHub Secrets; this repository uses OIDC Trusted Publishing only.
+
+## Workflow guardrail
+
+Do not ship a new Pi OSS package or version bump with only `package.json` changes.
+The repository must include the release workflow pair:
+
+- `.github/workflows/auto-release.yml` creates `v<version>` tags and GitHub Releases from `main` version bumps.
+- `.github/workflows/publish.yml` syncs the template and publishes `create-pi-extension` through Trusted Publishing.
+
+Important: tags or releases created by `GITHUB_TOKEN` do not reliably fan out into another workflow through normal `push.tags` or `release.published` triggers. The template keeps publishing reliable by having `auto-release.yml` explicitly dispatch `publish.yml` after creating the tag/release. If you change the release flow, keep one explicit handoff path: `workflow_dispatch` from auto-release, `repository_dispatch`, or `workflow_run` on the auto-release workflow.
+
+## GitHub Actions requirements
+
+- `permissions: id-token: write`
+- `permissions: actions: write` on auto-release so it can dispatch `publish.yml`
+- `auto-release.yml` must call `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`, or `publish.yml` must have an equivalent explicit handoff trigger such as `workflow_run`
+- GitHub-hosted runner
+- Node.js 24, so the release job uses a current npm CLI for Trusted Publishing
+- Bun (for `sync:template` before publish)
+- No `NPM_TOKEN`
+- `npm publish` from `packages/create-pi-extension` in the configured workflow file
+
+## First release checklist
+
+- [ ] Root `package.json` version is final (synced into `create-pi-extension` on publish)
+- [ ] `packages/create-pi-extension/package.json` name is `create-pi-extension`
+- [ ] `repository.url` points to the real GitHub repository
+- [ ] npm Trusted Publisher targets `create-pi-extension` + `publish.yml`
+- [ ] `npm run ci` passes
+- [ ] `npm pack --dry-run` in `packages/create-pi-extension` contains `template/`
+- [ ] CHANGELOG.md has the release date

package/docs/repository-settings.md

@@ -0,0 +1,43 @@
+# 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

@@ -0,0 +1,164 @@
+# Template Setup Checklist
+
+このテンプレートから新しい Pi 拡張OSSを作った後に埋めること。
+
+## Start paths
+
+### Primary path: `create-pi-extension` (recommended)
+
+CLI が placeholder 置換・bootstrap doc 削除・`git init` / `bun install` を担当する。手動作業は最小限でよい。
+
+- [ ] `bunx create-pi-extension@latest <package-name>` でプロジェクトを生成する
+- [ ] CLI の next steps（`npm run ci` など）に従う
+- [ ] 下記 **Recommended flow** の Vault / PRD / Issues フローに入る
+- [ ] README / feature list / quick start をプロジェクト向けに更新する
+- [ ] `npm run ci` と `npm pack --dry-run` を通す
+
+Primary path では **Repository** / **README placeholders** / **GitHub Template repo** の多くは CLI が済ませる。残タスクはカスタマイズと release 準備。
+
+### Secondary path: GitHub Template
+
+`gh repo create --template eiei114/pi-extension-template --clone` で repo を作った場合は、以下の manual checklist を順に埋める。
+
+- [ ] `gh repo create OWNER/my-pi-package --template eiei114/pi-extension-template --clone` で作成する
+- [ ] clone先へ移動してpackage向けの標準READMEを配置する: macOS/Linuxは `cd my-pi-package && cp scaffold/package-readme.md README.md`、Windows PowerShellは `Set-Location my-pi-package; Copy-Item scaffold/package-readme.md README.md -Force`
+- [ ] 下記 **Repository** 以降のセクションをすべて確認する
+- [ ] post-generation cleanup（bootstrap docs 削除）を実施する
+
+## 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` に反映する
+- [ ] 生成先 repo では `package.json` / README 内の `OWNER/REPO` を実リポジトリに置き換える
+
+## Package metadata
+
+- [ ] `package.json` の `name` を変更する
+- [ ] `description` を書く
+- [ ] `author` を入れる
+- [ ] `repository.url` を `https://github.com/OWNER/REPO` 形式の実リポジトリ URL に置き換える
+- [ ] `bugs.url` を `https://github.com/OWNER/REPO/issues` 形式に置き換える
+- [ ] `homepage` を `https://github.com/OWNER/REPO#readme` 形式に置き換える
+- [ ] `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` が通る
+- [ ] `packages/create-pi-extension` で `npm pack --dry-run` が通り、`template/` が含まれる
+- [ ] npm Trusted Publishing を **`create-pi-extension`** に設定する（ルート `pi-extension-template` は公開しない）
+- [ ] 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
+- [ ] `publish.yml` skips already-published versions via the public npm registry API and logs `publish intentionally skipped` on reruns
+- [ ] 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` を書く