@vegastack/skills 0.16.0 → 0.16.2

package/README.md

@@ -2,17 +2,25 @@
 
 Installer for VegaStack Agent Skills — a family of self-contained skills for Claude Code, Codex, and Hermes, shipped in one integrity-checked package.
 
+Install the whole dev workflow, once per machine:
+
+```sh
+npx @vegastack/skills add --group dev-skills --global
+```
+
+`--global` is the recommended install: the skills land in your home directory and are available in every project you open. Drop it for a project-local install when a repository should carry its own copy.
+
+See what else is bundled:
+
 ```sh
-npx @vegastack/skills list                      # what is bundled, by group
-npx @vegastack/skills add --group dev-skills    # the whole dev workflow, one command
-npx @vegastack/skills add dev-architect         # or a single skill
+npx @vegastack/skills list
 ```
 
 ## Skills in this package
 
 ### `dev-skills` — the issue-driven dev workflow
 
-Install the family with `add --group dev-skills`.
+Install the family with `add --group dev-skills --global`.
 
 | Skill | What it does |
 |---|---|
@@ -58,13 +66,46 @@ These operate on the vegastack-skills repository itself and do nothing useful in
 
 A `--group` or `--all` install is **one transaction**: every skill is checked and staged before any of them is committed, so if one fails, none are installed and the destination is left exactly as it was.
 
+The ten dev-workflow skills:
+
+```sh
+npx @vegastack/skills add --group dev-skills --global
+```
+
+Everything worth installing outside this repo:
+
+```sh
+npx @vegastack/skills add --all --global
+```
+
+Check the family against the manifest:
+
 ```sh
-npx @vegastack/skills add --group dev-skills    # the ten dev-workflow skills
-npx @vegastack/skills add --all                 # everything worth installing in your project
-npx @vegastack/skills verify --group dev-skills # check the family against the manifest
-npx @vegastack/skills remove --group dev-skills # uninstall it again
+npx @vegastack/skills verify --group dev-skills --global
 ```
 
+Uninstall it again:
+
+```sh
+npx @vegastack/skills remove --group dev-skills --global
+```
+
+## Upgrading and health checks
+
+Upgrade to the latest release. `--force` is required because `add` refuses to overwrite an installed copy that differs from the bundle rather than silently discarding local edits:
+
+```sh
+npx @vegastack/skills@latest add --group dev-skills --global --force
+```
+
+Diagnose an install — integrity across all skills, plus installed-vs-latest version:
+
+```sh
+npx @vegastack/skills doctor --global
+```
+
+Run `doctor` without `--global` from inside a project to additionally check that project's `.vegastack/dev.md` profile; the global run skips that check, since the profile is per-project by design.
+
 ## Flags
 
 | Flag | Meaning |
@@ -82,18 +123,22 @@ npx @vegastack/skills remove --group dev-skills # uninstall it again
 
 `--all` and `--agent all` are different axes and are easy to confuse: `--all` chooses **which skills**, `--agent all` chooses **which agent runtimes**. `add --all --agent all --global` is valid and means every installable skill, on every runtime, in your home directory.
 
-Agent targeting is automatic: the CLI detects which agents you have (`~/.claude`, `~/.codex`/`~/.agents`, `~/.hermes`) and targets them without asking — `--agent` overrides. A numbered picker appears only when nothing is detected. Installs are project-local by default; pass `--global` for the home directory (required for Hermes).
+Agent targeting is automatic: the CLI detects which agents you have (`~/.claude`, `~/.codex`/`~/.agents`, `~/.hermes`) and targets them without asking — `--agent` overrides. A numbered picker appears only when nothing is detected.
 
 ## Agent surfaces
 
-| Agent | Project install | Global install |
+`--global` is the recommended install and the only one that can cover all three runtimes at once. `--project` is the flag default, so pass `--global` explicitly.
+
+| Agent | Global install (recommended) | Project install |
 |---|---|---|
-| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
-| Codex | `.agents/skills/` | `~/.agents/skills/` |
-| Hermes | — (Hermes discovers skills globally only) | `~/.hermes/skills/` |
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
+| Codex | `~/.agents/skills/` | `.agents/skills/` |
+| Hermes | `~/.hermes/skills/` | — (Hermes discovers skills globally only) |
 
 `--agent hermes` therefore requires `--global`; `--agent all` on a project install covers codex+claude and prints a notice about hermes.
 
+Prefer a project install when a repository should carry its own copy — so collaborators get the same skills from a checkout, or so one project can pin a version while the rest of the machine moves on. Pick one or the other per skill rather than both: in Claude Code a personal (global) skill takes precedence over a project one, so a project-local copy would not override a global install of the same skill.
+
 ## Integrity model
 
 The package ships a checksum manifest that is verified at install and by `verify` — it proves the installed bytes match what was packed, not who published it. Publisher identity is attested separately by npm provenance, generated by the trusted-publishing release pipeline. Verify it with `npm audit signatures` or on the package's npm page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/skills",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Installer and verifier for VegaStack Agent Skills (Claude Code, Codex, and Hermes)",
   "license": "MIT",
   "type": "module",

package/skill/dev-architect/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-chronicle/SKILL.md

@@ -20,7 +20,7 @@ Nearest neighbors: `dev-implement` writes the entries at hand-back (the write ru
 - **Changed:** <the user-visible changes, simple words — sub-bullets or one ·-separated line>
 - **Decisions:** <register lines it produced, or "none">
 
-— approved by operator (<username>) · built by <agent> · branch <name>
+— approved by (<username>) · built by <agent> · branch <name>
 ```
 
 - Titles name the outcome ("Invoice reminders now chase late payers"), never the mechanism ("add reminderAt column"). The issue reference is a full markdown link to `…/issues/<n>` (correct for PRs too — GitHub redirects); a bare `#N` never appears anywhere in an entry, because file views don't auto-link it.

package/skill/dev-chronicle/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-debug/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-implement/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-intake/SKILL.md

@@ -55,7 +55,7 @@ Before posting any brief, run `node <path-to-this-skill>/scripts/brief-lint.mjs
 
 - A new issue starts at `needs-operator`, plus its scope label; add `risky` when it touches security, money, user data, or production. (Names come from dev.md's `labels:` knob.)
 - Approval is only the operator's explicit words, clearly tied to the issue. Labels, silence, or time never create approval.
-- Record it as one approval marker comment per conventions — `scope=brief`, or `scope=brief+plan` when the inline plan was posted with it — quoting the operator's words in the operator (username) format. That comment is what preflight verifies.
+- Record it as one approval marker comment per conventions — `scope=brief`, or `scope=brief+plan` when the inline plan was posted with it — quoting the operator's words in the (username) format. That comment is what preflight verifies.
 - Then flip the state: `research` and `quick-build` → `ready`; `full-plan` → `needs-plan` (dev-plan takes it from there).
 - An issue with an unresolved Assumptions entry cannot leave `needs-operator` — resolve every entry (confirmed, corrected, or moved to a spike) first; the section is deleted once resolved.
 - A directional decision this work settles — one passing the Decisions test in dev.md — is proposed as one register line on the operator's yes; `dev-ship` records at merge.

package/skill/dev-intake/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-plan/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-review/assets/review-known-patterns.md.template

@@ -10,7 +10,7 @@ Format, one entry per pattern:
 - **Pattern:** <what the reviewer keeps flagging, concretely — code shape, file area>
 - **Why it's safe here:** <the project fact that makes it a false positive>
 - **Still flag if:** <the exception that makes it a real finding after all>
-- **Origin:** <date + issue where the dismissal happened — operator (<username>)>
+- **Origin:** <date + issue where the dismissal happened — (<username>)>
 ```
 
 The four fields are LIST ITEMS — this file is read in a repo's file view, where single newlines soft-wrap into one paragraph; bullets are what guarantee a line per field. Appended entries (dev-implement's corrections loop) keep the same shape.

package/skill/dev-review/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-setup/assets/dev-profile.md.template

@@ -68,7 +68,7 @@ mobile: {{no | flutter (separate repo)}}
 
 Record a decision only when it is directional — it steers work beyond this issue: a real alternative was rejected; it constrains work not yet written; and no dev.md line, lint rule, or guard can enforce it instead (if one can, write the rule). Feature requests, one-off fixes, and routine implementation choices never qualify. Every entry needs the user's explicit yes. One line in the register (`decisions:` knob), append-only, no other metadata:
 
-- DD-MM-YYYY operator (github-username) — the decision
+- DD-MM-YYYY (github-username) — the decision
 
 ## Stop and ask
 

package/skill/dev-setup/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-ship/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-status/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/skill-maintainer/references/release-ops.md

@@ -24,8 +24,8 @@ profile carries a schema version to validate against.
 ## Release flow (tag-driven)
 
 1. Every PR that changes released behavior lands with a changeset — a `.changeset/<slug>.md` written directly, since the `changeset` add prompt is interactive (`bunx changeset version` at release time is the only CLI use) — whose bump follows the table above and whose shape follows dev-implement's changelog rule.
-2. Maintainer, at release time: `bunx changeset version` (applies changesets to `packages/cli/package.json` and the changelog), then `bun install` so any dependency changes riding along reach the lockfile, commit. That install does **not** update the workspace's own version inside `bun.lock`: measured on the bun the root `packageManager` line pins, the recorded version is left unchanged by a plain install, by `--force`, and even by `--lockfile-only`, so it sits at an older number indefinitely. `bun install --frozen-lockfile`, which CI and the release workflow both run, passes with it, and nothing in this repo reads it: `packages/cli/package.json` is the single release identity. Never hand-edit the lockfile to "correct" it. The release record is `packages/cli/CHANGELOG.md`, changesets-written — never by hand; the root `CHANGELOG.md` is the frozen pre-0.3.0 record pointing there.
-3. Tag the release commit `v<version>`, push the tag.
+2. Maintainer, at release time: `bunx changeset version` (applies changesets to `packages/cli/package.json` and the changelog), then `bun install` so any dependency changes riding along reach the lockfile, commit on a `chore/release-<version>` branch and open its PR — main is branch-protected with no admin exemption, so the bump reaches main by merge and never by direct push. That install does **not** update the workspace's own version inside `bun.lock`: measured on the bun the root `packageManager` line pins, the recorded version is left unchanged by a plain install, by `--force`, and even by `--lockfile-only`, so it sits at an older number indefinitely. `bun install --frozen-lockfile`, which CI and the release workflow both run, passes with it, and nothing in this repo reads it: `packages/cli/package.json` is the single release identity. Never hand-edit the lockfile to "correct" it. The release record is `packages/cli/CHANGELOG.md`, changesets-written — never by hand; the root `CHANGELOG.md` is the frozen pre-0.3.0 record pointing there.
+3. Merge the release PR on the operator's word, pull main, then tag that merged commit `v<version>` and push the tag. Tags are not branch-protected, so the tag push is unaffected.
 4. The release workflow runs on the tag: `bun run check`, tag↔version guard, `npm publish` via trusted publishing (OIDC, token-free, provenance by default; idempotently skipped if already on the registry), SBOM, GitHub release. Never pass `--provenance` explicitly — it conflicts with trusted-publishing config.
 
 Contributors do not bump versions in PRs; releases are maintainer-driven.
@@ -34,7 +34,7 @@ Contributors do not bump versions in PRs; releases are maintainer-driven.
 
 `npm unpublish` is limited to 72 hours and breaks pinned consumers — it is not the rollback mechanism.
 
-1. **Roll forward:** revert the offending commits on `main`, changeset, tag, release the previous known-good content as a **new patch version**.
+1. **Roll forward:** revert the offending commits through a PR onto `main` (protection applies to reverts too), changeset, tag, release the previous known-good content as a **new patch version**.
 2. **Deprecate the bad version:** `npm deprecate @vegastack/skills@<bad> "Broken — use <new>"`.
 3. Unpublish only if the bad version leaked secrets or is actively harmful, still within 72 hours, and always *in addition to* steps 1–2, never instead.
 

package/skill/skillify/assets/templates/README.md.template

@@ -5,8 +5,10 @@ TODO: one-paragraph summary for humans and agents browsing the repo. The agent e
 ## Install
 
 ```sh
-npx @vegastack/skills add {{name}}{{groupInstallLine}}
+npx @vegastack/skills add {{name}} --global
 ```
+{{groupInstallBlock}}
+`--global` installs into your home directory, where the skill is available in every project; drop it for a project-local install.
 
 ## What's in this skill
 

package/skill/skillify/scripts/scaffold-skill.mjs

@@ -222,28 +222,37 @@ export async function scaffoldSkill({ name, dir, group = null, write = false, no
   // Every refusal belongs in this pre-flight. wireReadme runs after the tree is renamed into
   // place and the packaging entry written, so anything discovered there would leave a half-wired
   // skill on disk while reporting a refusal - or, worse, report success with no row at all.
-  // When a README exists, its row target must be resolvable BEFORE the tree is staged, so a
-  // refusal writes nothing. A wholly absent README or packaging.json keeps the documented
-  // degrade-to-`skipped:` contract (skillify's README, and the bare-repo test) - tightening that
-  // is a behaviour change of its own, tracked separately.
+  // Both wiring targets a scaffolded skill cannot do without must therefore be resolvable BEFORE
+  // the tree is staged: an absent one is a refusal, not a `skipped:` status, because a skill with
+  // no README row or no packaging entry is exactly the state structure.mjs check blocks. Only
+  // `.changeset/` still degrades to `skipped:` - a missing changeset breaks no check.
   const readmePath = join(repoRoot, 'README.md')
-  if ((await entryAt(readmePath))?.isFile()) {
-    const lines = (await readFile(readmePath, 'utf8')).split('\n')
-    const rowTarget = findRowInsertion(lines, group, groupHeading)
-    if (rowTarget?.missingSection) {
-      throw new Error(`README.md has no "### ${groupHeading}" section for group "${group}" - create it with structure.mjs create-group`)
-    }
-    if (!rowTarget) {
-      throw new Error(`README.md has no ${group ? `table under "### ${groupHeading}"` : 'ungrouped Skills table'} to add a row to - every skill needs its row, so refusing rather than scaffolding a skill the structure check would block`)
-    }
+  if (!(await entryAt(readmePath))?.isFile()) {
+    throw new Error(`README.md not found at ${readmePath} - every skill needs its Skills-table row, so refusing rather than scaffolding a skill the structure check would block`)
+  }
+  const lines = (await readFile(readmePath, 'utf8')).split('\n')
+  const rowTarget = findRowInsertion(lines, group, groupHeading)
+  if (rowTarget?.missingSection) {
+    throw new Error(`README.md has no "### ${groupHeading}" section for group "${group}" - create it with structure.mjs create-group`)
+  }
+  if (!rowTarget) {
+    throw new Error(`README.md has no ${group ? `table under "### ${groupHeading}"` : 'ungrouped Skills table'} to add a row to - every skill needs its row, so refusing rather than scaffolding a skill the structure check would block`)
+  }
+
+  const packagingPath = join(repoRoot, 'packages/cli/packaging.json')
+  if (!(await entryAt(packagingPath))?.isFile()) {
+    throw new Error(`packages/cli/packaging.json not found at ${packagingPath} - every skill needs its packaging entry, so refusing rather than scaffolding a skill the structure check would block`)
   }
 
   // The generated test imports the repo validator by relative path, so its depth follows the
   // skill's: skills/<name>/tests/ is three levels up, skills/<group>/<name>/tests/ is four.
   const validatorPath = `${group ? '../../../..' : '../../..'}/packages/cli/scripts/validate-skill.mjs`
-  // Only a grouped skill gets the family-install line; an ungrouped one would otherwise ship a
-  // command naming a group that does not exist.
-  const groupInstallLine = group ? `\nnpx @vegastack/skills add --group ${group}   # or the whole ${group} family` : ''
+  // Only a grouped skill gets the family-install block; an ungrouped one would otherwise ship a
+  // command naming a group that does not exist. It is its own fence, not a second line in the
+  // first one: pasting a shared fence would run the alternative too.
+  const groupInstallBlock = group
+    ? `\nOr the whole ${group} family at once:\n\n\`\`\`sh\nnpx @vegastack/skills add --group ${group} --global\n\`\`\`\n`
+    : ''
 
   const outputs = templateFiles.map(([source, output]) => [source, output ?? `tests/${name}.test.ts`])
   const plan = { name, group, target, files: outputs.map(([, output]) => output), wrote: false }
@@ -258,7 +267,7 @@ export async function scaffoldSkill({ name, dir, group = null, write = false, no
         .replaceAll('{{name}}', name)
         .replaceAll('{{date}}', date)
         .replaceAll('{{validatorPath}}', validatorPath)
-        .replaceAll('{{groupInstallLine}}', groupInstallLine)
+        .replaceAll('{{groupInstallBlock}}', groupInstallBlock)
       const destination = join(staging, output)
       await mkdir(dirname(destination), { recursive: true })
       await writeFile(destination, rendered)

package/skill-integrity.json

@@ -8,7 +8,7 @@
         "SKILL.md": "74150dde2d3c83598769a4c9f8cd295a7496d9eb9a5e920a29cba8464eb58128",
         "agents/openai.yaml": "99023b056d5c568ff3acc059e5bb7a4e6cfa5261cd0d35a525407f9e159de562",
         "references/ai-agents.md": "565e5d480f7e342adf43f9b864ab4cb66b7e513f0ea676de66909fe0ccd95988",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/data.md": "781d3ae7d3bca0b269c123a10013226f3878503dd1224ee526edd102bfc270f0",
         "references/infra.md": "a6d07c5e9ea67788edac7b80742a5588a1f019e387163bfdab531314fb54d009",
         "references/mobile.md": "b6ee481df810f3fd5466487848287ceeb33ac98bf6db0bc2d65c4d6fa397284f",
@@ -25,9 +25,9 @@
       "group": "dev-skills",
       "repoOnly": false,
       "files": {
-        "SKILL.md": "23c6266758726d6435de38cb0cc142a94a0b55f2329f7ab6404e42fa5d0dee3a",
+        "SKILL.md": "2bd58c19cdb5a55d7fefdfcd1748054aba403ff9d5161030e36a65f3b2e69b05",
         "agents/openai.yaml": "765b12e17b7fce88c53ca0fae735bf0efceb843cc3703b91bc1801ab5cac06b4",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "refresh/REFRESH.md": "760e66642eec426cd5ab2319613e817adf5bbd7b64c8eaa22dd13497351bf9c1",
         "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04"
       }
@@ -38,7 +38,7 @@
       "files": {
         "SKILL.md": "38ba9e67c00925f4e4738be333dc398218008df929fcf17b61398966ce4deee1",
         "agents/openai.yaml": "4aa52b5c620b0bf4de7f1609867956ce762d83dc4297ab5670a68c206ae63075",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/loop-ladder.md": "ddcb45ec2241bc5dc25936348074cdcc8f9af848e90b363351a7faf97007c256",
         "refresh/REFRESH.md": "70816e44c8d6a5d11b73eb40762e6d8931724517e0b4c138eb07bc8e91b45008",
         "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04"
@@ -50,7 +50,7 @@
       "files": {
         "SKILL.md": "f79f4d312f6c03ffdcf2e2fd44169e48520445900389e2d469c0946811be3801",
         "agents/openai.yaml": "1abab383deca54d32749fd9156f9a6211fe96e02e0166dc8a16ff8459ac31b74",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/ledger-and-resume.md": "5e3deae2af67735940564e04adcbc23c0c0dc86da2f6c80d68b8c1207c8f5900",
         "refresh/REFRESH.md": "7b854109d897b78b3055bf1ab89517afdca65c12eb65a4d009141e3ee11cf58f",
         "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74",
@@ -63,10 +63,10 @@
       "group": "dev-skills",
       "repoOnly": false,
       "files": {
-        "SKILL.md": "4754383297822d3f6e0ad8a391ac76499d83c74f424b90b928199d6c2649dc71",
+        "SKILL.md": "08126d2c631051bf92d400dd678b8f75af1ee7905b1c389e030e4ca435f2c548",
         "agents/openai.yaml": "5473d2d3efffc518c07dfa8e6788c6535a5054ceca696119c5856ad265ef5581",
         "references/brief-template.md": "906c6b805f9737755f4d4b34fd16d4296924b95039379ea86bc59973949d9823",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "refresh/REFRESH.md": "bb5265cee98c243c775c3e5fbc59de4b84ab54e828f3290d7c19e47291d66f71",
         "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74",
         "scripts/brief-lint.mjs": "7202def7c3a8b0049e67d60602a4c652d3c99f5fa1711080fd46b94ff4dc3684"
@@ -78,7 +78,7 @@
       "files": {
         "SKILL.md": "eb2ce1542b1769fa6e7d9dc7be9fc9c84df8b353ded16e39e1e578ee372c1aca",
         "agents/openai.yaml": "4b9ccc9870b4eafb73c1bc4492a0b5a530097bbcbae11dbf3235160f4f05587b",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/plan-format.md": "a915acce2fc447e685077756aeb94fdc3f84139800703034987b8409971493db",
         "refresh/REFRESH.md": "e22830102db9cf7c6db1e8fea9e73b7845b77e59da0d44e186a6b26d6dc9ebe1",
         "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04",
@@ -91,8 +91,8 @@
       "files": {
         "SKILL.md": "561e0232d20fc7e6893b38a4c3d7deb41862d60d7b545a98d3ce7ba1d3c7ac06",
         "agents/openai.yaml": "3f35d3dc60f179d4ac2526997c4d10173ba3018d06f0dbe77e209ce2978fa702",
-        "assets/review-known-patterns.md.template": "2fe7dbcc4d0eeac542e7624111130265b2bb4f08806f20dbd2087842cbb22b5c",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "assets/review-known-patterns.md.template": "7747b807ed18c4c8bf8acdc6481b2f7f27914d932d757c7243a32a41a18d32c5",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/cross-agent.md": "3541715d0563703373ea3d93582119b80356d1cbdee19ce17f958c0f7c914884",
         "references/dispatch-prompts.md": "cb8134a7b6ff9e20ec4db02d0af2f8767f71bf13fa9a21b28b7a586c2747ec1d",
         "references/security-axis.md": "e207071fc48f761f2deb24c73ef4f5ebcf28c130264dab7c3061ae6c0eee6543",
@@ -108,8 +108,8 @@
         "SKILL.md": "4b29049b8ce165fb03f554c8784e095cbe97cef16752b57b86321352a1017ce7",
         "agents/openai.yaml": "be790c04fdf910e71642cfadf1a7c07c217bf7fad18581610feb4c31a79651f2",
         "assets/agents-section.md.template": "6c9591d50f73e1e05e78c8969c7836767432cf32487af7205b2cb9f4a410440e",
-        "assets/dev-profile.md.template": "b42b633b5e236bd8448648c2475978488afcac23c99342619a71670abbd7122c",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "assets/dev-profile.md.template": "26e244b488d181e23ff4b49addd9ab519c8f5d43e2d914638033648a7ca5bd3a",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/harness-facts.md": "2be1d81f6a616d40dc865aaeefaf53c61bc13ade4ba1de8fb406c520bf15be40",
         "references/stack-playbooks.md": "8f457c3d0f96e3c99d745b04332590fdf8af53a9694541181d9c878ae0718ea2",
         "refresh/REFRESH.md": "debda6ab96e899dd7e38309f714e9d65a3fbc53fd8ca68b8156f1348226c87b9",
@@ -122,7 +122,7 @@
       "files": {
         "SKILL.md": "aa3bd8b0a1ac076309190f2008896f24ebe1216352872ff428c1b88b55c06e65",
         "agents/openai.yaml": "8f18cfd505131557eb4c9f7b7f54e9069f787be4c162403fc30253eed49a06ea",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/runbook.md": "5cbf3f89b2fcad1a2873f729b6c1a027566344d5dffcb799ed1d039e76b3e679",
         "refresh/REFRESH.md": "06894b54fcbde12d3b5804523f20d5544ba1a18bb5e36960caa4f98454c6203e",
         "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74",
@@ -135,7 +135,7 @@
       "files": {
         "SKILL.md": "56415c2f69bb1a2fcb488b9846a20e632eb902b05c5b2b58ae9206d3eaffd77b",
         "agents/openai.yaml": "72435947f5afef0c8a2c170e987b14fe6057b174318c16b6b538ae8d129791fb",
-        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "refresh/REFRESH.md": "52aee9bae64d8342e127704d1db282e43ed57c101148727bf10172d6cb975bfa",
         "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04",
         "scripts/status.mjs": "bc56d0b5d996676cfccb752d9d77d0e9e7d64932741cd39d6a503e9761fbe34d"
@@ -147,7 +147,7 @@
       "files": {
         "SKILL.md": "1733d2f1fa756cbb37c74ecee0d48ddd9abf31155c4dd72eba10af31c33d88ec",
         "agents/openai.yaml": "0b89d4e6416cf20b448f5322f3d7433cfde333d2b4a05b42ed53db3759701fb4",
-        "references/release-ops.md": "b5df1922b34daf7751c332c019a0ea770a48283aaa2e25f83c9851bef47999b1",
+        "references/release-ops.md": "d213f66976e24942560d611582d27409f8ba4392886b4663d7dfbc7d395ef2ef",
         "references/standards.md": "b44122822a320a305728ee023ed8e3140bf87aaaef400a43d45b778e53ad2c02",
         "refresh/REFRESH.md": "d3ba44be2c264b849d8a815111c049e782720428d5d0c5cea23998b05e50d58f",
         "refresh/sources.json": "4977152381d53555196ac676f95e61b4eaa301309a17560da5cda722010eb80f"
@@ -159,7 +159,7 @@
       "files": {
         "SKILL.md": "310ac32ff4d557cc166a470fd1866060dfc5f03898e8ff3da9c406b84580742b",
         "agents/openai.yaml": "df320cf32a8db06c213f7892844dab810b7e96cfbf32502d25185d4a4167ef87",
-        "assets/templates/README.md.template": "49dccb4e9b5bdb07c254f9142502b3fd11fd5b083d8661b0ae6a567dec79de74",
+        "assets/templates/README.md.template": "74750e59514bff2211b043f6584ed75271529ff4b304e82b207c282396d3e2a1",
         "assets/templates/REFRESH.md.template": "ff86afade565d668333e7f6d0432213760fd68a62b8ba22897a8601b74c94ac0",
         "assets/templates/SKILL.md.template": "b038775f97b13b54227fe41a767a48cdaa922a93d1732f22c2d1d79bff52ca00",
         "assets/templates/openai.yaml.template": "2fbf488369825109d6cad4f17e7b729a40d9e3c43c7f01bc5dfa16361d59c086",
@@ -170,7 +170,7 @@
         "references/eval-playbook.md": "1f463dfea8d69b7022712776794369892643aa020186fe3a3707c493a6c2d4e9",
         "refresh/REFRESH.md": "695f3283b27c14accf4095137898ce1f6dc40749483c5a5705e80aa9693f08c2",
         "refresh/sources.json": "e554e80c72c16dc70587361804db9e0cf2716c128820b2612d5983a009b2b242",
-        "scripts/scaffold-skill.mjs": "8bc3314f800fcff0bf5f797fdd82424ceb16a45ac03c4ee0eebcc416dfc41b97"
+        "scripts/scaffold-skill.mjs": "d9edbe912ca20aad29afe1b0b904f85bbc4c9bfefb2c75e2986949ce00cb7fae"
       }
     }
   }