@manhquy/flow-skill 0.1.0-rc.1 → 0.1.0-rc.3

package/CHANGELOG.md

@@ -2,9 +2,142 @@
 
 All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [0.1.0-rc.3] — 2026-07-18
+
+Ships the same skill product **v0.22.0** as rc.2, plus pipeline/UX fixes found after the first
+OIDC publish + independent verification.
+
+### Fixed
+- **Nightly registry health false-red:** `scripts/smoke.mjs` ran `npx` from inside
+  `npm-wrapper/`, so npx resolved the **local workspace package** instead of the registry
+  (`flow-skill: not found`) even when the published package was healthy. Smoke now uses an
+  empty temp cwd + `npx --package=… flow-skill`; nightly runs from `$RUNNER_TEMP`.
+- **CI bash-suite Windows cancelled at 15m:** full 33-suite run needs ~20–25m on Windows Git
+  Bash (measured run `29630992330` — mid-`test_flow_eval` when cut). `timeout-minutes` is now
+  **30 on windows-latest**, 15 elsewhere. `tests/run_all.sh` prints per-suite `wall_s`.
+- **`promote_to`:** early-exit before install/test (no full job burn); input description states
+  it is **manual-only** (OIDC cannot `npm dist-tag add` — E401 on run `29556075144`).
+
+### Added
+- Dual-version UX: `--help` shows `flow-skill v<pkg> (ships skill v<skill>)`; JSONL `plan`
+  event gains additive `skillVersion`. Unit tests pin values from `package.json` + `SKILL.md`.
+
+### Changed
+- `bin/cli.mjs` git mode `100755` (executable bit in tarball).
+
+## [0.1.0-rc.2] — 2026-07-17 — LIVE (published 2026-07-17, `latest` + `rc` both point here)
+
+Ships `skills/flow` v0.22.0 (concierge front-door + standalone native rituals — see the root
+repo's CHANGELOG.md `## 0.22.0` entry for the full skill-content changelog). This wrapper
+release fixes the actual reported installer bug, adds a 5th install target (Cursor), and fixes
+two hardening items found while verifying it all.
+
+### Fixed — the reported symptom (A0)
+- **Antigravity users installing via `npx` got no guidance and saw a silent `/flow`-not-found.**
+  A freshly-installed skill isn't discovered by an agent until it reloads; the post-install
+  summary line only ever told Claude + Codex users what to do. Every installed target now gets
+  its own restart/reload hint (`bin/cli.mjs`'s `doneLine()`, `install.sh`, `install.ps1` — all
+  three entry points, built from the actual installed-targets list, not a static string).
+
+### Fixed — hardening found during verification
+- `scripts/sync.mjs` baked an **absolute local filesystem path** (e.g. `D:\project\flow\...`)
+  into `skills-manifest.json`'s `source` field, and that file ships inside the published
+  tarball (`package.json` `files:`) — leaking local machine layout and being non-reproducible
+  across dev machines/CI. Now emits a repo-relative `"../skills/flow"` (or a literal
+  `"$FLOW_SKILL_SRC (override)"` marker when the env override is used).
+- `pretest: node scripts/sync.mjs` — the bundled `skills/flow/` tree is gitignored
+  (regenerated by `npm run sync`/`prepack`); a fresh checkout now gets it automatically before
+  `npm test` instead of failing with a missing/stale bundle.
+- `--test-concurrency=1` pinned on the `test` script — the two new real (non-dry-run) CLI
+  install tests below, run in parallel with `lock-atomicity.test.mjs`'s own child-process
+  spawns, intermittently starved on Windows (spurious non-zero exit unrelated to any of the
+  three files' own logic, confirmed by serialized re-runs going 38/38 green repeatedly vs an
+  occasional false-red in parallel). Total suite time impact: negligible (~1-2s).
+
+### Added — 5th install target: Cursor
+- New `cursor` target → `~/.cursor/skills/flow`. **Marker is `.cursor/skills`, never bare
+  `.cursor`** — the bare dir holds unrelated editor config (settings, caches, `argv.json`) that
+  exists for every Cursor user, and a bare marker would have silently auto-installed flow under
+  `--yes` for anyone with Cursor installed at all (the exact false-positive class the existing
+  Antigravity `~/.gemini` guard already dodges).
+- **Path confirmed by a live probe on the dev machine, not documentation/web research**: found a
+  real pre-existing symlink `~/.cursor/skills/find-skills -> ~/.agents/skills/find-skills`,
+  empirically proving Cursor's actual skill-read location and that it already consumes content
+  from the universal Agent-Skills home (see below).
+- `agents` target relabeled "Agents home — universal Agent-Skills home" — it's the shared
+  directory the open Agent Skills standard ([agentskills.io](https://agentskills.io), Anthropic,
+  now stewarded by the Agentic AI Foundation) defines, which spec-compliant tools beyond this
+  installer's named targets (Cursor confirmed; ~30 others per the standard's adoption) can read.
+- **Honesty limit, not overclaim**: Cursor has no discoverable headless CLI (`cursor agent --help`
+  falls through to generic IDE flags, no `-p`/`exec` print-mode). Unlike Antigravity (`agy -p`)
+  and Codex (`codex exec`), the installed skill's *runner execution* inside Cursor is not
+  independently live-verified here — install correctness is (real scratch-`$HOME` test, content
+  lands at the confirmed path). README/CHANGELOG say "install verified, runner not yet
+  independently confirmed" rather than claiming parity with the other two targets.
+- `--all` now installs 5 targets; every "4 target(s)" mention across `--help`, both root READMEs,
+  and both npm-wrapper READMEs updated to 5 (the count in `--help` is now derived from
+  `TARGETS.length` so it cannot drift again).
+
+### Added — tests
+- `test/detect.test.mjs`: 2 new cases — bare `.cursor` does NOT trigger detection (the
+  false-positive regression guard), `.cursor/skills` present → detected at the confirmed dest.
+- `test/cli.test.mjs`: three REAL (non-dry-run, scratch-`$HOME`) installs asserting the Done-line
+  restart hint — `antigravity` alone, `cursor` alone (this one caught a real bug: the Done-line
+  printed empty for a cursor-only install because Cursor wasn't yet in `RESTART_HINTS` when it
+  was written — fixed same-session), and `claude,codex` (proving the old Codex hint survives and
+  no unrelated agent line leaks in).
+- `test/sync-manifest.test.mjs`: asserts `skills-manifest.json.source` is never an absolute path.
+- `tests/test_flow_antigravity_integration.sh` (root repo bash suite): 4 new assertions —
+  both `install.sh` and `install.ps1` carry the Antigravity restart/reload hint, and the old
+  hardcoded Claude+Codex-only Done line is gone from both.
+
+### Fixed — CI publish guard (found on the actual first real run of this workflow)
+- `publish-npm-wrapper.yml`'s `Guard — assert no NODE_AUTH_TOKEN present (OIDC only)` step
+  **hard-failed every run, including this release's first attempt** (run `29554226397`,
+  2026-07-17). Root-caused via a temporary diagnostic step (added, run 3×, removed same
+  session): `NODE_AUTH_TOKEN` is unset right after `actions/checkout@v4` but becomes a real
+  short-lived OIDC-exchanged value the instant `actions/setup-node@v4` runs with
+  `registry-url` set — that's the current `actions/setup-node@v4` (a moving tag) doing its own
+  native npm OIDC handling, not a leaked static secret. The guard's 2026-07-12 design assumed
+  the older model where `npm publish` alone performed the OIDC exchange with nothing set
+  beforehand; it never matched real `actions/setup-node@v4` behavior and had a 0% pass rate
+  since the day it was written. **Removed** — see the workflow file's inline comment for the
+  full evidence chain.
+- **npm Trusted Publisher was never actually bound** on npmjs.com for this package (confirmed:
+  first real publish attempt after the guard fix still 404'd — `PUT
+  .../@manhquy%2fflow-skill — Not found`). The 2026-07-12 runbook flagged this config as `TBD`
+  and it was never closed out. Configured now: `owner=manhquydev`, `repo=flow-skill`,
+  `workflow=publish-npm-wrapper.yml`, `environment=npm-publish`. `npm publish --provenance`
+  now succeeds via pure OIDC — confirmed live, SLSA attestation present.
+- **`npm dist-tag add` does NOT work via OIDC** (confirmed live: `E401 Unable to authenticate`
+  even immediately after a successful OIDC-authenticated publish in the same job). npm has not
+  extended Trusted Publishing to this endpoint yet (matches
+  `plans/reports/researcher-260712-1006-npm-trusted-publisher-first-publish-edge-cases-report.md`
+  item #12, "OIDC support in development", no ship date). Promoting `0.1.0-rc.2` to `latest`
+  required the same manual Granular-Access-Token-with-Bypass-2FA flow used for the rc.1
+  bootstrap publish — see `RELEASE_CHECKLIST.md` for the exact steps and why this account
+  (created 2026-07-11, after npm's Sept-2025 TOTP-enrollment cutoff) has no other CLI-auth path
+  for write operations.
+
+### Release command (already run for this release)
+```
+cd npm-wrapper && npm test   # confirmed green first
+git tag npm@0.1.0-rc.2 && git push origin npm@0.1.0-rc.2   # triggered the workflow (after the guard fix + TP config above)
+```
+
 ## [0.1.0-rc.1] — 2026-07-12
 
-Initial release candidate. Ships to the `rc` npm dist-tag.
+**LIVE on npm**: https://www.npmjs.com/package/@manhquy/flow-skill
+
+Initial release candidate. Published manually to bootstrap npm Trusted Publisher (which requires the package to exist first). rc.2+ will be published from CI with OIDC + SLSA L2 provenance.
+
+Publish details (for the record):
+- Method: Granular Access Token with `Bypass 2FA` (created + used + revoked within 60s from the maintainer's local machine).
+- No provenance on this bootstrap version (`npm publish --provenance` requires a supported CI environment; laptop publish is not).
+- Dist-tags at publish: `{rc: 0.1.0-rc.1, latest: 0.1.0-rc.1}` — npm auto-populated `latest` on first publish. Docs advise pinning `@rc` or `@0.1.0-rc.1` explicitly.
+- Tarball: 76 files, 203 KB gzipped, 566 KB unpacked.
+
+Ships to the `rc` npm dist-tag.
 
 ### Post-implementation audit fixes (before first publish)
 - **installer:** `acquireLock` was TOCTOU-racy — switched to atomic `writeFileSync(..., { flag: 'wx' })` so two `npx` runs cannot both acquire.

package/README.md

@@ -5,41 +5,26 @@ One-command installer that copies the [flow](https://github.com/manhquydev/flow-
 - Pure Node — works on macOS, Linux, and Windows (cmd, PowerShell 5.1/7, Git Bash) with the same code path.
 - Interactive multi-select or non-interactive CI mode.
 - Preserves any user-added files in the destination outside the 6 subdirs the skill owns.
-- Ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) via GitHub Actions trusted publishing (from rc.2+).
-
-## Status — 2026-07-12
-
-- ✅ Code complete, 35/35 tests green, CI matrix green (ubuntu/macos/windows × Node 22/24).
-- ⏳ Not yet on npm registry. Repo public + renamed; transfer to `manhquy` account pending accept; first publish (`v0.1.0-rc.1`, manual, no provenance) queued.
-- ➡️ Once published, this section will disappear and `npx @manhquy/flow-skill@rc` becomes the canonical install path.
+- Ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) via GitHub Actions trusted publishing **starting with rc.2** — rc.1 was a manual bootstrap because npm Trusted Publisher cannot bind to a package that does not yet exist.
 
 ## Install
 
-**A. From the git repo (works today, no npm registry needed)**
-
-```bash
-git clone https://github.com/manhquydev/flow-skill.git
-cd flow-skill/npm-wrapper
-npm install
-npm run sync          # materializes skills/flow from ../skills/flow
-npm link              # exposes `flow-skill` as a global command
-
-flow-skill --yes --all --dry-run --json   # smoke check
-flow-skill                                # interactive install
 ```
-
-To remove: `npm unlink -g @manhquy/flow-skill`.
-
-**B. Via npx (once published)**
-
-```
-# Pre-release channel (RC candidate — will exist after first publish)
+# Pre-release channel (current — v0.1.0-rc.3, ships skill v0.22.0)
 npx @manhquy/flow-skill@rc
 ```
 
 An interactive prompt asks which agents to install to. Pick one or more, confirm, done.
 
-> **RC phase**: pin `@rc` (dist-tag) or a specific version like `@0.1.0-rc.1`. `npx @manhquy/flow-skill@0.1.x` will start working after stable `0.1.0` is published — semver ranges do **not** match pre-release tuples by default. See [SECURITY.md](./SECURITY.md).
+> **RC phase**: pin `@rc` (dist-tag) or a specific version like `@0.1.0-rc.3`. `npx @manhquy/flow-skill@0.1.x` will start working after stable `0.1.0` is published — semver ranges do **not** match pre-release tuples by default. See [SECURITY.md](./SECURITY.md).
+>
+> **`npm i` alone is not enough.** `npm install @manhquy/flow-skill` only adds the installer
+> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill@rc` or
+> `npx flow-skill` after install) to copy the skill into agent homes.
+>
+> **Two version axes:** package `version` in this folder is the **installer** (e.g. `0.1.0-rc.3`).
+> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.22.0`).
+> `--help` and the JSONL `plan` event expose both (`version` + `skillVersion`).
 
 ## Non-interactive
 
@@ -51,7 +36,7 @@ npx @manhquy/flow-skill@rc --yes
 npx @manhquy/flow-skill@rc --yes -t claude -t codex
 npx @manhquy/flow-skill@rc --yes -t claude,codex           # comma form OK
 
-# Force all four targets even if not detected
+# Force all five targets even if not detected
 npx @manhquy/flow-skill@rc --yes --all
 
 # Project scope (Claude only — see below)
@@ -67,16 +52,25 @@ npx @manhquy/flow-skill@rc --yes --all --dry-run --json
 |---|---|---|---|
 | `claude` | Claude Code | `~/.claude/skills/flow` | any presence of `~/.claude` (Claude is always pre-checked) |
 | `codex` | Codex CLI | `~/.codex/skills/flow` | `~/.codex/skills` |
-| `agents` | Agents home | `~/.agents/skills/flow` | `~/.agents/skills` |
+| `agents` | Agents home — also the universal [Agent-Skills](https://agentskills.io) home other spec-compliant tools read | `~/.agents/skills/flow` | `~/.agents/skills` |
 | `antigravity` | Antigravity (CLI + IDE) | `~/.gemini/antigravity-cli/skills/flow` **and** `~/.gemini/config/skills/flow` | `~/.gemini/antigravity-cli` **or** `~/.gemini/config/skills` |
+| `cursor` | Cursor | `~/.cursor/skills/flow` | `~/.cursor/skills` (never the bare `~/.cursor` config dir every Cursor user has) |
 
 `--project` scope writes to `<dir>/.claude/skills/flow` and supports only the `claude` target. Combining `--project` with a non-Claude target exits with code `2`.
 
 ## After install
 
+A freshly-installed skill isn't discovered by an agent until it reloads — the installer's final
+line tells you exactly what to do for whichever targets you installed:
+
 - Claude Code: type `/flow`.
-- Codex CLI: type `$flow` (restart Codex once to load).
-- Antigravity: `/flow` in the IDE.
+- Codex CLI: type `$flow` (restart Codex once to load a new skill).
+- Antigravity: restart/reload the IDE (or restart `agy`) to load the new skill, then type `/flow`.
+- Agents home (`~/.agents/skills/`): restart/reload your tool if it does not auto-detect new skills.
+- Cursor: **install verified, live runner execution not yet independently confirmed** — Cursor
+  has no headless CLI probe available for automated verification (unlike Antigravity's `agy -p`
+  or Codex's `codex exec`); restart/reload Cursor after install and check the Agent panel for
+  the `flow` skill.
 - Diagnostics: run `/flow doctor` from your agent.
 
 ## Uninstall
@@ -100,14 +94,16 @@ rm -rf <project>/.claude/skills/flow
 - **Windows `EBUSY` / `EPERM` mid-install**: an agent (Claude Code, Codex, Antigravity IDE) is holding a file inside the destination. Close the agent and re-run. The installer already retries with 100/300/900 ms backoff before surfacing the error.
 - **Stale advisory lock**: a prior run crashed. The next run detects the dead PID and reclaims the lock automatically. If it does not (very rare — the recorded PID was recycled by another live process), delete `<parent-of-dest>/.flow-skill.installing.lock`.
 - **`No matching version found` on `@0.1.x`**: you are trying to install a pre-release version through a stable range. Use `@rc` (dist-tag) or an explicit `@0.1.0-rc.N` until stable `0.1.0` ships.
-- **Node too old** (`requires Node.js >=20.11.0`): upgrade with your preferred version manager (`nvm install 20`, `fnm install 20`, or Node's official installer).
+- **`No matching version found` on `@0.22.0`**: that is the **skill product** version, not the npm package version. Use `@rc` / `@0.1.0-rc.N` (installer) — skill content version is printed by `--help` as `ships skill v…`.
+- **Installed package but agent has no `/flow`**: `npm i` does not run the installer. Run `npx @manhquy/flow-skill@rc` (or `npx flow-skill` if already installed) and restart the agent.
+- **Node too old** (`requires Node.js >=22.14.0`): upgrade with your preferred version manager (`nvm install 22`, `fnm install 22`, or Node's official installer). Node 20 reached end-of-life April 2026; npm OIDC Trusted Publishing needs npm >=11.5.1 which bundles with Node 22.14+.
 
 ## JSONL contract
 
 `--json` streams one JSON object per line:
 
 ```jsonl
-{"event":"plan","version":"0.1.0-rc.1","dryRun":false,"scope":"global","targets":["claude","codex"]}
+{"event":"plan","version":"0.1.0-rc.3","skillVersion":"0.22.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
 {"event":"install:start","target":"claude","dests":["~/.claude/skills/flow"]}
 {"event":"install:done","target":"claude","dests":["~/.claude/skills/flow"],"result":"success","error":null,"warnings":[]}
 {"event":"summary","success":true,"total":2,"attempted":2,"installed":2,"failed":0,"skipped":0,"aborted":false}
@@ -119,7 +115,7 @@ rm -rf <project>/.claude/skills/flow
 
 | Event | Required fields | Notes |
 |---|---|---|
-| `plan` | `version` (string), `dryRun` (bool), `scope` (`global`\|`project`), `targets` (string[]) | Always the first event. |
+| `plan` | `version` (string), `dryRun` (bool), `scope` (`global`\|`project`), `targets` (string[]), optional `skillVersion` (string\|null) | Always the first event. `version` = npm package; `skillVersion` = bundled `SKILL.md` product version. |
 | `install:start` | `target` (string), `dests` (string[]) | One per selected target. |
 | `install:done` | `target`, `dests`, `result` (`success`\|`failed`), `error` (string\|null), `warnings` (string[]) | Fired after each target. `error` is `null` on success. |
 | `summary` | `success` (bool), `total`, `attempted`, `installed`, `failed`, `skipped`, `aborted` (bool) | Always the last event. Counts sum: `attempted = installed + failed`; `skipped = total - attempted`. |

package/README_VN.md

@@ -7,39 +7,16 @@ Trình cài đặt một-lệnh sao chép skill [flow](https://github.com/manhqu
 - Bảo toàn file người dùng đã thêm ngoài 6 subdir mà skill sở hữu.
 - Ship kèm [npm provenance](https://docs.npmjs.com/generating-provenance-statements) qua GitHub Actions trusted publishing (từ rc.2+).
 
-## Tình trạng — 2026-07-12
-
-- ✅ Code hoàn thiện, 35/35 test xanh, CI matrix xanh (ubuntu/macos/windows × Node 22/24).
-- ⏳ Chưa lên npm registry. Repo đã public + đã rename; transfer sang `manhquy` account đang chờ accept; first publish (`v0.1.0-rc.1`, thủ công, không có provenance) đang queued.
-- ➡️ Sau khi publish, section này sẽ biến mất và `npx @manhquy/flow-skill@rc` thành lệnh cài chính thức.
-
 ## Cài đặt
 
-**A. Từ git repo (chạy được ngay, không cần npm registry)**
-
-```bash
-git clone https://github.com/manhquydev/flow-skill.git
-cd flow-skill/npm-wrapper
-npm install
-npm run sync          # materialize skills/flow từ ../skills/flow
-npm link              # expose `flow-skill` như global command
-
-flow-skill --yes --all --dry-run --json   # smoke check
-flow-skill                                # cài tương tác
-```
-
-Gỡ: `npm unlink -g @manhquy/flow-skill`.
-
-**B. Qua npx (sau khi publish)**
-
 ```
-# Kênh pre-release (RC candidate — sẽ tồn tại sau first publish)
+# Kênh pre-release (hiện tại — v0.1.0-rc.2)
 npx @manhquy/flow-skill@rc
 ```
 
 Prompt tương tác hỏi cài vào agent nào. Chọn một hoặc nhiều, xác nhận, xong.
 
-> **Giai đoạn RC**: pin `@rc` (dist-tag) hoặc phiên bản cụ thể `@0.1.0-rc.1`. `npx @manhquy/flow-skill@0.1.x` chỉ dùng được sau khi stable `0.1.0` publish — semver range **không** match pre-release theo mặc định. Xem [SECURITY.md](./SECURITY.md).
+> **Giai đoạn RC**: pin `@rc` (dist-tag) hoặc phiên bản cụ thể `@0.1.0-rc.2`. `npx @manhquy/flow-skill@0.1.x` chỉ dùng được sau khi stable `0.1.0` publish — semver range **không** match pre-release theo mặc định. Xem [SECURITY.md](./SECURITY.md).
 
 ## Non-interactive
 
@@ -51,7 +28,7 @@ npx @manhquy/flow-skill@rc --yes
 npx @manhquy/flow-skill@rc --yes -t claude -t codex
 npx @manhquy/flow-skill@rc --yes -t claude,codex           # Dạng comma OK
 
-# Ép cài cả 4 target dù không detect
+# Ép cài cả 5 target dù không detect
 npx @manhquy/flow-skill@rc --yes --all
 
 # Project scope (chỉ Claude — xem bên dưới)
@@ -67,16 +44,24 @@ npx @manhquy/flow-skill@rc --yes --all --dry-run --json
 |---|---|---|---|
 | `claude` | Claude Code | `~/.claude/skills/flow` | bất kỳ presence của `~/.claude` (Claude luôn pre-check) |
 | `codex` | Codex CLI | `~/.codex/skills/flow` | `~/.codex/skills` |
-| `agents` | Agents home | `~/.agents/skills/flow` | `~/.agents/skills` |
+| `agents` | Agents home — cũng là thư mục [Agent-Skills](https://agentskills.io) chung mà các tool tuân chuẩn khác đọc | `~/.agents/skills/flow` | `~/.agents/skills` |
 | `antigravity` | Antigravity (CLI + IDE) | `~/.gemini/antigravity-cli/skills/flow` **và** `~/.gemini/config/skills/flow` | `~/.gemini/antigravity-cli` **hoặc** `~/.gemini/config/skills` |
+| `cursor` | Cursor | `~/.cursor/skills/flow` | `~/.cursor/skills` (không bao giờ dùng thư mục config `~/.cursor` trần — ai dùng Cursor cũng có) |
 
 Scope `--project` ghi vào `<dir>/.claude/skills/flow` và chỉ hỗ trợ target `claude`. Kết hợp `--project` với target khác → exit code `2`.
 
 ## Sau khi cài
 
+Skill vừa cài xong sẽ không được agent nhận ra cho tới khi agent reload — dòng cuối cùng của
+installer nói rõ việc cần làm cho đúng target đã cài:
+
 - Claude Code: gõ `/flow`.
-- Codex CLI: gõ `$flow` (restart Codex 1 lần để load).
-- Antigravity: `/flow` trong IDE.
+- Codex CLI: gõ `$flow` (restart Codex 1 lần để load skill mới).
+- Antigravity: restart/reload IDE (hoặc restart `agy`) để load skill mới, rồi gõ `/flow`.
+- Agents home: restart/reload tool nếu nó không tự nhận skill mới.
+- Cursor: **đã xác nhận cài đúng chỗ, chưa xác nhận runner chạy độc lập** — Cursor không có
+  CLI headless để tự động kiểm (khác `agy -p` của Antigravity hay `codex exec` của Codex);
+  restart/reload Cursor sau khi cài rồi kiểm tra panel Agent xem có skill `flow` không.
 - Chẩn đoán: chạy `/flow doctor` từ agent.
 
 ## Gỡ cài đặt
@@ -111,7 +96,7 @@ Hợp đồng additive trong `0.1.x` — field mới có thể thêm, field cũ
 - **`EBUSY`/`EPERM` giữa install trên Windows**: một agent đang giữ handle vào file trong destination. Đóng agent + re-run. Installer đã retry 100/300/900 ms trước khi báo error.
 - **Advisory lock cũ**: run trước crash. Run mới tự phát hiện PID dead → reclaim. Trường hợp hiếm (PID được recycle bởi process khác đang chạy): xóa `<parent-of-dest>/.flow-skill.installing.lock`.
 - **`No matching version found` với `@0.1.x`**: cài pre-release qua stable range. Dùng `@rc` hoặc `@0.1.0-rc.N` cho tới khi stable `0.1.0` ship.
-- **Node quá cũ** (`requires Node.js >=20.11.0`): update bằng `nvm install 20`, `fnm install 20`, hoặc installer chính thức của Node.
+- **Node quá cũ** (`requires Node.js >=22.14.0`): update bằng `nvm install 22`, `fnm install 22`, hoặc installer chính thức của Node. Node 20 hết vòng đời từ 4/2026; npm OIDC Trusted Publishing cần npm >=11.5.1 (bundle theo Node 22.14+).
 
 ## Yêu cầu
 
@@ -125,6 +110,11 @@ Mỗi phiên bản publish có [npm provenance](https://docs.npmjs.com/generatin
 npm view @manhquy/flow-skill@<version> dist.attestations.provenance
 ```
 
+> **Ngoại lệ RC-window**: `v0.1.0-rc.1` được publish thủ công từ máy developer để bootstrap npm
+> Trusted Publisher (TP không thể bind tới package chưa tồn tại) — bản này không có provenance.
+> Từ `v0.1.0-rc.2` trở đi, mọi bản publish đều qua CI workflow với OIDC và có attestation
+> SLSA Build Level 2 đầy đủ.
+
 ## Bảo mật
 
 Threat model + WILL/WON'T list + kênh report — xem [SECURITY.md](./SECURITY.md). Tóm tắt: pure Node, không network call, không spawn shell/PowerShell, không postinstall hook, không chạm settings/hooks/MCP config.

package/SECURITY.md

@@ -55,7 +55,7 @@ These match the behavior of the upstream `install.sh`; they are documented rathe
   ```
   npm view @manhquy/flow-skill@<version> dist.attestations.provenance
   ```
-  **`v0.1.0-rc.1` exception**: this bootstrap version was published manually (Trusted Publisher requires the package to already exist before it can bind) and carries no attestation. All subsequent versions publish via CI and are attested. If provenance is a hard requirement for you, wait for `v0.1.0-rc.2` or later.
+  **`v0.1.0-rc.1` exception**: this bootstrap version was published manually (Trusted Publisher requires the package to already exist before it can bind) and carries no attestation. `v0.1.0-rc.2` (2026-07-17) is the first version published from CI via OIDC — confirmed live with an SLSA Build Level 2 attestation. All versions from rc.2 onward are attested; if provenance is a hard requirement, pin `@0.1.0-rc.2` or later.
 - **Publisher account.** npm 2FA `auth-and-writes` is enabled as defense-in-depth for the git + npm identity behind the workflow.
 - **Pin your version.** During the RC window use `@rc` (dist-tag) or an explicit `@0.1.0-rc.N`. After stable ships, pin `@0.1.x` (or a specific version). `@latest` invites blind updates on a package that writes to your agent home.
 - **Completeness signal (not tamper detection).** The tarball ships `skills-manifest.json` recording the synced skill's file count + list. The publish workflow re-counts the checked-out tree against this manifest to catch an incomplete sync. It is **not** a supply-chain integrity proof — that role belongs to npm provenance above. `.integrity` SHA-256 sidecar was intentionally not adopted because it would have been generated from the same source it hashed (circular trust).

package/bin/cli.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { join, resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 
-import { TARGETS, TARGET_NAMES, PKG_VERSION } from '../src/constants.mjs';
+import { TARGETS, TARGET_NAMES, PKG_VERSION, SKILL_VERSION } from '../src/constants.mjs';
 import { defaultSelection, detectAll } from '../src/detect.mjs';
 import { renderHelp } from '../src/help.mjs';
 import { install, installAntigravity } from '../src/installer.mjs';
@@ -147,6 +147,29 @@ function humanResult(target, result) {
   return `${status} ${target} -> ${dests}${err}`;
 }
 
+// v0.23 A0 fix — the reported symptom: a user installs to a non-Claude agent, opens it, types
+// /flow, and sees nothing, because a freshly-installed skill isn't discovered until the agent
+// reloads. The old static message only told Claude+Codex users what to do; every installed
+// target now gets its own line so nobody is left guessing why /flow doesn't show up.
+const RESTART_HINTS = {
+  claude: 'Claude Code: type /flow',
+  codex: 'Codex CLI: type $flow (restart Codex once to load a new skill)',
+  antigravity:
+    'Antigravity: restart/reload the IDE (or restart `agy`) to load the new skill, then type /flow',
+  agents:
+    'Agents home (~/.agents/skills/): restart/reload your tool if it does not auto-detect new skills',
+  // Cursor has no headless CLI probe (unlike Antigravity's `agy -p` or Codex's `codex exec`) to
+  // independently verify the runner loads post-install — restart/reload guidance is still the
+  // correct advice (same discovery-on-reload mechanism), just without our own live confirmation
+  // that the Agent panel picks it up. See README's "After install" section for the caveat.
+  cursor: 'Cursor: restart/reload Cursor to load the new skill, then check the Agent panel for flow',
+};
+
+function doneLine(targets) {
+  const hints = targets.map((t) => RESTART_HINTS[t]).filter(Boolean);
+  return `Done. ${hints.join('  |  ')}`;
+}
+
 async function main() {
   const rawArgs = process.argv.slice(2);
   let opts;
@@ -265,6 +288,9 @@ async function main() {
     {
       event: 'plan',
       version: PKG_VERSION,
+      // Additive: skill product version (SKILL.md). `version` stays the npm package version
+      // for back-compat with existing JSONL consumers.
+      skillVersion: SKILL_VERSION,
       dryRun: opts.dryRun,
       scope,
       targets: plan.map((p) => p.target),
@@ -346,10 +372,7 @@ async function main() {
   );
 
   if (!opts.json && success) {
-    log(
-      '\nDone. Claude Code: type /flow  |  Codex CLI: type $flow (restart Codex once).',
-      false
-    );
+    log(`\n${doneLine(plan.map((p) => p.target))}`, false);
   }
 
   // If aborted mid-loop, exit 130 (matches shell convention) instead of the generic failure.
@@ -360,6 +383,9 @@ async function main() {
 main().catch((err) => {
   // F2 — a crash inside main() must not truncate JSONL: emit a machine-parseable summary
   // before exit so CI consumers can distinguish "crashed" from "hung".
+  // Argv fallback: `--json` is a boolean flag with no alias in parseArgs config, so a raw
+  // string match on process.argv is safe today; if the flag ever gets an alias or
+  // `--json=true` form, hoist `jsonMode` to module scope from parseCliArgs instead.
   const isJson = process.argv.includes('--json');
   const message = err?.message ?? String(err);
   if (isJson) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.3",
   "description": "Install the flow skill (buildflow gated build process) into your coding agent(s) via one npx command",
   "type": "module",
   "bin": {
@@ -23,7 +23,8 @@
   "scripts": {
     "sync": "node scripts/sync.mjs",
     "prepack": "node scripts/sync.mjs",
-    "test": "node --test test/installer.test.mjs test/detect.test.mjs test/cli.test.mjs test/lock-atomicity.test.mjs",
+    "pretest": "node scripts/sync.mjs",
+    "test": "node --test --test-concurrency=1 test/installer.test.mjs test/detect.test.mjs test/cli.test.mjs test/lock-atomicity.test.mjs test/sync-manifest.test.mjs",
     "smoke": "node scripts/smoke.mjs"
   },
   "dependencies": {