docs(skills): trusted publishing is live, not deferred — plus a first-publish runbook

[coderdan]

What

skills/stash-supply-chain-security/SKILL.md still described npm provenance attestations and OIDC trusted publishing as deferred follow-up work, and told readers release.yml needs NPM_TOKEN dropped. Both landed a while ago — release.yml publishes with no token at all, and published tarballs carry SLSA provenance:

$ npm view @cipherstash/stack-drizzle@1.0.0-rc.4 --json | grep -A3 attestations
    "attestations": {
      "url": "https://registry.npmjs.org/-/npm/v1/attestations/...",
      "provenance": { "predicateType": "https://slsa.dev/provenance/v1" }

Since skills ship inside the stash tarball and are copied into customer repos by installSkills(), a stale section here is wrong guidance in someone else's codebase, not just an internal note.

Changes

• Replaced the "What's Deferred (Follow-Up PR)" block with a Publishing — OIDC trusted publishing + provenance section documenting what's actually in place, plus the constraints that are easy to undo by accident:
  • permissions: id-token: write — mints the OIDC token
  • runs-on: ubuntu-latest, never self-hosted — npm rejects provenance from non-GitHub-hosted runners with E422
  • never set NPM_TOKEN — changesets/action writes a token .npmrc that shadows OIDC and fails every publish with E404 (OIDC trusted publishing E404 when publishing scoped packages from changesets/action npm/cli#8976)
  • npm ≥ 11.5.1 / Node ≥ 22.14
  • no Actions cache in a credential-bearing job (enforced by scripts/lint-no-workflow-caching.mjs)
• Added a runbook: publishing a package name for the first time. A trusted publisher is configured per package on npmjs.com, so it can only be attached to a package that already exists — a brand-new name can't be released by release.yml on its own and needs a manual placeholder publish first. Covers pnpm publish (not npm publish, because of workspace:* deps), the bootstrap tag, deprecating the placeholder, cleaning the tag up afterwards, and the publishConfig.access requirement.
• Fixed the 2FA paragraph, which pointed at the now-deleted "Deferred" section. 2FA still matters for the manual operations OIDC can't cover (claiming a name, npm deprecate, npm dist-tag).
• Frontmatter description and "When to Use This Skill" updated so the skill triggers on release.yml and first-publish work.

Why now

@cipherstash/stack-prisma (renamed from @cipherstash/prisma-next in #844) has never been published:

$ npm view @cipherstash/stack-prisma version
npm error code E404 - GET https://registry.npmjs.org/@cipherstash%2fstack-prisma - Not found

So the GA release run can't publish it — no package, no trusted-publisher config, nothing for the OIDC token to match — and the result would be a partial release: the rest of the fixed group at 1.0.0 with the Prisma adapter missing. That's the same reason stack-drizzle and stack-supabase carry 0.0.0 placeholders; those versions have no attestations, their rc builds do, which confirms the placeholders were name-claiming rather than cosmetic.

Written up as a GA blocker on #661 (comment: #661 (comment)). This PR is the durable half — so the next new package doesn't rediscover it at release time.

Testing

Docs-only. pnpm run code:check reports no errors (pre-existing warnings only, which is what CI gates on).

Changeset

stash patch — skills/ ships in the stash tarball, so a skills-only change is user-facing.

[changeset-bot]

🦋 Changeset detected

Latest commit: b7e9fdf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
stash	Patch
@cipherstash/basic-example	Patch
@cipherstash/e2e	Patch
@cipherstash/stack	Patch
@cipherstash/stack-drizzle	Patch
@cipherstash/stack-supabase	Patch
@cipherstash/stack-prisma	Patch
@cipherstash/wizard	Patch
@cipherstash/bench	Patch
@cipherstash/migrate	Patch
@cipherstash/test-kit	Patch
@cipherstash/prisma-example	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Review limit reached

@coderdan, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 17 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 944bac01-d654-46ab-a504-f5123e4105cf

📥 Commits

Reviewing files that changed from the base of the PR and between 6ae01ea and b7e9fdf.

📒 Files selected for processing (2)

• .changeset/tall-moons-yawn.md
• skills/stash-supply-chain-security/SKILL.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderdan]

Documentation correction.

[auxesis]

Thanks for this @coderdan.