@manhquy/flow-skill 0.1.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+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.1] — 2026-07-12
+
+Initial release candidate. 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.
+- **installer:** dropped `EACCES` from `withRetry` — POSIX permission errors are almost never transient; retrying only masked the honest error with ~1.3 s of latency.
+- **installer:** dropped the post-copy `assertNoSymlinks(destDir)` walk — it would have rejected legitimate Windows NTFS junctions users may have placed under their skills tree. The source-side scan is the actual security control.
+- **detect:** `~/foo` template resolution now uses `path.join(...)` so Windows dests no longer surface mixed separators in `--json` output.
+- **cli:** removed the aspirational "hit Ctrl+C twice to hard-exit" branch — synchronous install loop cannot be preempted by signal handlers, and the second-strike `process.exit(130)` would have leaked the current install's advisory lock.
+- **workflow:** `npm pack --dry-run --json` now runs with `--ignore-scripts` so `prepack` stdout does not corrupt the JSON audit payload.
+- **workflow:** pre-release semver can never be published to dist-tag `latest` (belt-and-suspenders guard alongside the tag-name auto-derivation).
+- **workflow:** `child_process` guard narrowed to import statements only — the old verb-based regex false-hit `RegExp.prototype.exec` and code comments containing "exec".
+- **docs:** README EN + VN now recommend `@rc` (dist-tag) during the RC window and explain why `@0.1.x` will not resolve to a pre-release. Full JSONL event/field/exit-code contract table added. Troubleshooting section covers `EBUSY`/stale lock/version pin/Node floor.
+- **docs:** dropped stale `import.meta.dirname` justification for the Node ≥20.11 floor — the real reasons are `node:util.parseArgs` (stable) and `node:test`.
+- **docs:** SECURITY.md reframes `skills-manifest.json` as a completeness signal, not a tamper-detection primitive (that role belongs to npm provenance).
+- **package.json:** dropped stale `opencode` keyword — no opencode target is shipped.
+
+### Pre-publish critical fixes (caught during first live `npm publish` attempt)
+- **`package.json.bin`**: value was `./bin/cli.mjs` — npm strips the leading `./` and warns "invalid and removed", meaning the published tarball would have shipped with NO `flow-skill` executable. `npx @manhquy/flow-skill` would have failed to find the command. Fixed to `bin/cli.mjs` per `npm pkg fix`.
+- **Tarball weight**: `skills/flow/harness/__pycache__/` was shipping 9 Python bytecode files (~230 KB) — regenerated at runtime, different for each Python minor. `scripts/sync.mjs` now filters `__pycache__/`, `*.pyc`, `*.pyo`, and OS junk during copy. Both the copy and the completeness check share one predicate so the counts still line up. Tarball dropped 786 KB → 553 KB unpacked (298 KB → 198 KB gzipped).
+
+### Publish-path corrections (research-driven, 2026-07 npm docs)
+- **engines:** bumped from `>=20.11.0` → `>=22.14.0`. Node 20 reached end-of-life April 2026, and npm OIDC Trusted Publisher (the whole point of our publish workflow) requires npm >=11.5.1 which ships bundled with Node 22.14+. Older Node bundles npm 10.x which fails the OIDC handshake with a misleading 404. Runtime version guard in `bin/cli.mjs` matches.
+- **workflow:** `.github/workflows/publish-npm-wrapper.yml` `node-version` bumped from `20.11` → `22`, plus an explicit `npm install -g npm@latest` step so the runner always has the OIDC-capable npm.
+- **CI:** new `.github/workflows/ci.yml` — cross-OS matrix (`ubuntu-latest × macos-latest × windows-latest`) × Node `[22, 24]`. Runs on push/PR touching `npm-wrapper/**` or the skill content. Includes tarball-size gate and the `child_process` import guard.
+
+### Additional test coverage
+- `test/lock-atomicity.test.mjs` — 9 tests locking down the audit-fix regressions: `acquireLock` `wx` semantics, corrupted lock reclamation, `withRetry` no-longer-retries `EACCES`, `withRetry` still retries `EBUSY`/`EPERM`/`ENOTEMPTY`, `detect.mjs` OS-separator normalization for Claude and Antigravity dests.
+
+### Developer tooling
+- `scripts/smoke.mjs` — post-publish end-to-end verifier. Runs `npm view` for version + provenance, then `--help`, `--dry-run --json`, and a real install into a scratch `$HOME`. Invoke as `npm run smoke -- <version>`.
+- `.github/ISSUE_TEMPLATE/bug-report-npm-wrapper.yml` + `.github/PULL_REQUEST_TEMPLATE.md` — structured intake.
+
+### Added
+- `npx @manhquy/flow-skill` installer for 4 coding-agent targets: Claude Code, Codex CLI, Agents home, Antigravity (CLI + IDE).
+- Interactive multi-select prompt via `@clack/prompts` when stdin/stdout are TTY.
+- Non-interactive flags: `--yes`, `--target`/`-t` (repeatable + comma form), `--all`, `--project`, `--dir`, `--json`, `--dry-run`, `--help`.
+- JSONL streaming (`--json`) with `plan`, `install:start`, `install:done`, and `summary` events.
+- Pure Node install path — no shell/PowerShell spawn, single code path across macOS/Linux/Windows.
+- Semantic parity with upstream `install.sh:24-27`: clean 6 subdirs (`runner`, `_templates`, `law`, `references`, `harness`, `playbooks`) then merge-copy. User files outside those subdirs are preserved.
+- Defense: symlink rejection at sync and install time. Advisory lock to reduce concurrent-run races. `EBUSY`/`EPERM`/`ENOTEMPTY`/`EACCES` retry with 100/300/900 ms backoff.
+- `chmod +x` on `runner/flow.sh` (parity with `install.sh:27`; no-op on Windows NTFS).
+- `--project` scope enforced to Claude only (agent-contract limitation).
+- 35 tests via `node:test` across 4 suites — installer semantics, detection markers, CLI black-box smoke, TOCTOU + retry lock-atomicity regression suite.
+- Runtime Node version guard (>=22.14.0) — floor set by npm OIDC Trusted Publisher requirements (npm >=11.5.1 ships with Node 22.14+) and by Node 20 reaching end-of-life April 2026; `engines` in `package.json` matches.
+
+### Security
+- Bundled `skills/flow` synced from upstream `flow-skill` repo via `scripts/sync.mjs`; `skills-manifest.json` records file count + list for post-hoc verification.
+- No `postinstall` hook. `prepack` runs `sync.mjs` on the dev machine only and is not in the published tarball.
+- GitHub Actions trusted publishing: OIDC-only, required-reviewer environment, `npm publish --provenance` (SLSA Level 2).
+- README and docs pin `@0.1.x` semver rather than `@latest`.
+
+### Notes
+- v0.1.0-rc.N is a pre-release channel. Test explicitly with `npx @manhquy/flow-skill@0.1.0-rc.1`. Pinning `@0.1.x` does not fetch pre-release versions.
+- Promotion criterion from rc → stable v0.1.0: 7 days with no critical bug reports, all success criteria (documented in the project's plan artifact) manually verified across macOS + Linux + Windows, and at least one external tester install.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 manhquy <manhquy.mqy@gmail.com>
+
+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,152 @@
+# @manhquy/flow-skill
+
+One-command installer that copies the [flow](https://github.com/manhquydev/flow-skill) skill into your coding agent(s).
+
+- 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.
+
+## 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)
+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).
+
+## Non-interactive
+
+```
+# Default selection (Claude + anything detected)
+npx @manhquy/flow-skill@rc --yes
+
+# Explicit targets
+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
+npx @manhquy/flow-skill@rc --yes --all
+
+# Project scope (Claude only — see below)
+npx @manhquy/flow-skill@rc --yes --project --dir .
+
+# CI-friendly JSONL output
+npx @manhquy/flow-skill@rc --yes --all --dry-run --json
+```
+
+## Targets
+
+| Name | Label | Destination | Detection marker |
+|---|---|---|---|
+| `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` |
+| `antigravity` | Antigravity (CLI + IDE) | `~/.gemini/antigravity-cli/skills/flow` **and** `~/.gemini/config/skills/flow` | `~/.gemini/antigravity-cli` **or** `~/.gemini/config/skills` |
+
+`--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
+
+- Claude Code: type `/flow`.
+- Codex CLI: type `$flow` (restart Codex once to load).
+- Antigravity: `/flow` in the IDE.
+- Diagnostics: run `/flow doctor` from your agent.
+
+## Uninstall
+
+Delete the target directories:
+
+```
+# Global installs
+rm -rf ~/.claude/skills/flow
+rm -rf ~/.codex/skills/flow
+rm -rf ~/.agents/skills/flow
+rm -rf ~/.gemini/antigravity-cli/skills/flow
+rm -rf ~/.gemini/config/skills/flow
+
+# Project scope (only Claude)
+rm -rf <project>/.claude/skills/flow
+```
+
+## Troubleshooting
+
+- **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).
+
+## 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":"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}
+```
+
+`--json --dry-run` emits only the `plan` event. `--json` implies non-interactive; do not combine with a TTY prompt session.
+
+### Event contract
+
+| Event | Required fields | Notes |
+|---|---|---|
+| `plan` | `version` (string), `dryRun` (bool), `scope` (`global`\|`project`), `targets` (string[]) | Always the first event. |
+| `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`. |
+| `error` | `message` (string), `exitCode` (int) | Emitted only when the process crashes before completing a normal flow (e.g. missing bundled skill). Then exits with `exitCode`. |
+
+Exit codes: `0` success · `1` at least one target failed · `2` invalid usage (bad target name, `--project` with a non-Claude target, missing bundled skill) · `130` `SIGINT` (Ctrl+C).
+
+The contract is additive within `0.1.x`. New optional fields may appear; existing fields will not be renamed or removed.
+
+## Requirements
+
+- Node.js **>= 22.14.0** — Node 20 reached end-of-life in April 2026, and the publish workflow requires npm >=11.5.1 (bundled with Node 22.14+) for OIDC Trusted Publisher support
+
+## Provenance
+
+Every version published from the CI workflow carries an [npm provenance](https://docs.npmjs.com/generating-provenance-statements) attestation (SLSA Build Level 2). Verify with:
+
+```
+npm view @manhquy/flow-skill@<version> dist.attestations.provenance
+```
+
+> **RC-window exception**: `v0.1.0-rc.1` was published manually from a developer machine to bootstrap npm's Trusted Publisher registration (Trusted Publisher cannot bind to a package that does not exist yet). npm does not generate provenance for publishes outside supported CI. All subsequent versions (`v0.1.0-rc.2` onward) publish through the workflow and are attested.
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for the threat model, what the installer will and will not do, and how to report issues.
+
+## License
+
+MIT © 2026 manhquy

package/README_VN.md

@@ -0,0 +1,134 @@
+# @manhquy/flow-skill
+
+Trình cài đặt một-lệnh sao chép skill [flow](https://github.com/manhquydev/flow-skill) vào (các) coding agent của bạn.
+
+- Pure Node — chạy trên macOS, Linux, Windows (cmd, PowerShell 5.1/7, Git Bash) với cùng một code path.
+- Multi-select tương tác hoặc chế độ CI không tương tác.
+- 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)
+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).
+
+## Non-interactive
+
+```
+# Chọn mặc định (Claude + những agent detect được)
+npx @manhquy/flow-skill@rc --yes
+
+# Target rõ ràng
+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
+npx @manhquy/flow-skill@rc --yes --all
+
+# Project scope (chỉ Claude — xem bên dưới)
+npx @manhquy/flow-skill@rc --yes --project --dir .
+
+# JSONL cho CI
+npx @manhquy/flow-skill@rc --yes --all --dry-run --json
+```
+
+## Targets
+
+| Tên | Nhãn | Đích | Marker phát hiện |
+|---|---|---|---|
+| `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` |
+| `antigravity` | Antigravity (CLI + IDE) | `~/.gemini/antigravity-cli/skills/flow` **và** `~/.gemini/config/skills/flow` | `~/.gemini/antigravity-cli` **hoặc** `~/.gemini/config/skills` |
+
+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
+
+- Claude Code: gõ `/flow`.
+- Codex CLI: gõ `$flow` (restart Codex 1 lần để load).
+- Antigravity: `/flow` trong IDE.
+- Chẩn đoán: chạy `/flow doctor` từ agent.
+
+## Gỡ cài đặt
+
+Xóa dir target:
+
+```
+# Global installs
+rm -rf ~/.claude/skills/flow
+rm -rf ~/.codex/skills/flow
+rm -rf ~/.agents/skills/flow
+rm -rf ~/.gemini/antigravity-cli/skills/flow
+rm -rf ~/.gemini/config/skills/flow
+
+# Project scope (chỉ Claude)
+rm -rf <project>/.claude/skills/flow
+```
+
+## JSONL contract
+
+`--json` stream một JSON object mỗi dòng. Xem [README.md § JSONL contract](./README.md#jsonl-contract) cho bảng đầy đủ event/field/exit code. Tóm tắt:
+
+- `plan` — event đầu tiên; chứa `version`, `dryRun`, `scope`, `targets`.
+- `install:start` / `install:done` — một cặp mỗi target; `install:done.result` = `success` hoặc `failed`.
+- `summary` — event cuối cùng; `success`, `total`, `attempted`, `installed`, `failed`, `skipped`, `aborted`.
+- Exit codes: `0` OK · `1` ≥1 target fail · `2` sai flag/target · `130` Ctrl+C.
+
+Hợp đồng additive trong `0.1.x` — field mới có thể thêm, field cũ không rename/xóa.
+
+## Troubleshooting
+
+- **`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.
+
+## Yêu cầu
+
+- Node.js **>= 22.14.0** — Node 20 hết vòng đời từ 4/2026, và publish workflow cần npm >=11.5.1 (bundle theo Node 22.14+) cho OIDC Trusted Publisher
+
+## Provenance
+
+Mỗi phiên bản publish có [npm provenance](https://docs.npmjs.com/generating-provenance-statements) attestation. Verify:
+
+```
+npm view @manhquy/flow-skill@<version> dist.attestations.provenance
+```
+
+## 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.
+
+## License
+
+MIT © 2026 manhquy

package/SECURITY.md

@@ -0,0 +1,69 @@
+# Security policy
+
+## Threat model
+
+`@manhquy/flow-skill` is a **file-copy installer** written in pure Node.js. When you run `npx @manhquy/flow-skill`, the process:
+
+- copies files from the tarball into one or more agent home directories, and
+- exits.
+
+There are no network calls, no shell/PowerShell invocations, no `postinstall` hooks, and no long-running daemons.
+
+## What the installer WILL NOT do
+
+- Run any script from the Internet at install time.
+- Touch `settings.json`, `permissions`, `allowedMcpServers`, hooks, or any marketplace config.
+- Modify MCP config, shell rc, PATH, or environment variables.
+- Log in to npm, mint tokens, or publish anything.
+- Log, save, or commit tokens, passwords, OTPs, or private keys.
+- Touch any path outside the explicit list below:
+  - `<home>/.claude/skills/flow`
+  - `<home>/.codex/skills/flow`
+  - `<home>/.agents/skills/flow`
+  - `<home>/.gemini/antigravity-cli/skills/flow`
+  - `<home>/.gemini/config/skills/flow`
+  - `<project>/.claude/skills/flow` when `--project` is used
+- Spawn `bash`, `sh`, `pwsh`, `powershell.exe`, or any child process (pure Node `node:fs`).
+
+## What the installer WILL do
+
+For each destination the user selects, the installer performs (parity with the upstream `install.sh:24-27` contract):
+
+1. Acquire a best-effort advisory lock: `<parent>/.flow-skill.installing.lock`. If the file exists and its recorded PID is alive, refuse and exit `2`.
+2. Recursively scan the bundled source `skills/flow/`. If any symbolic link is present, refuse and exit — an upstream-planted symlink is treated as hostile.
+3. `mkdir -p` the destination.
+4. `rm -rf` these six subdirectories inside the destination (if present): `runner/`, `_templates/`, `law/`, `references/`, `harness/`, `playbooks/`.
+5. Recursively copy `skills/flow/` into the destination with `dereference: false` and `errorOnBrokenSymbolicLinks: true`.
+6. Rescan the destination for symlinks (defense-in-depth). Abort if any found.
+7. `chmod 755` the destination's `runner/flow.sh` if it exists.
+8. Release the lock.
+
+Any file **outside those six subdirectories** at the destination is preserved. You may drop personal notes, custom playbooks in a different directory, etc., alongside the installed skill — the installer will not touch them.
+
+## Known v0.1 limitations
+
+These match the behavior of the upstream `install.sh`; they are documented rather than hidden.
+
+- **Not atomic across a full run.** `SIGINT` (Ctrl+C) mid-copy or a hard crash may leave a destination in an inconsistent state. Re-running the installer fixes it. The advisory lock reduces (but does not eliminate) the risk of two concurrent runs racing.
+- **Antigravity has two destinations.** If the first install succeeds and the second fails, the first is **not** rolled back — matching the upstream `install.sh:52-53` behavior. The `install:done` and `summary` JSONL events report the partial state.
+- **Windows `EBUSY`.** If a running agent (Claude Code, Codex, Antigravity IDE) holds a file handle inside the destination, `rm`/`cp` retries 3× with backoff (100/300/900 ms). If it still fails, the installer reports the target and asks you to close the agent.
+
+## Supply chain
+
+- **Trusted publishing.** Every version is published from a tag-triggered GitHub Actions workflow (`.github/workflows/publish-npm-wrapper.yml`, or `workflow_dispatch` for validation) behind a required-reviewer environment gate. No long-lived npm token exists in CI; auth is via OIDC.
+- **Provenance.** npm attaches an SLSA Build Level 2 attestation to every version published from the workflow. Verify with:
+  ```
+  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.
+- **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).
+- **No `postinstall`.** `package.json` has no `postinstall` script. `prepack` (dev-only) is not in the shipped tarball.
+
+## Reporting a security issue
+
+- Preferred: [GitHub Security Advisory](https://github.com/manhquydev/flow-skill/security/advisories/new)
+- Email: `manhquy.mqy@gmail.com` (subject: `[flow-skill security]`)
+
+Please do not publish exploits before a fix ships. Best-effort response SLA for v0.1.