codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-ship-configure/SKILL.md

@@ -0,0 +1,296 @@
+---
+scope: org-shared
+name: cbp-ship-configure
+description: Configure shipment for one or more surfaces in the current repo — Vercel link, EAS project + eas.json scaffold, Apple credentials probe, npm publish auth check (including `codebyplan` asset-publish automation via release-please), Railway project link, Supabase access token verify; Supabase GitHub branching integration via /cbp-supabase-setup. Interactive step-by-step; never stores credentials in the repo.
+argument-hint: [--surface=<id>]
+allowed-tools: Read, Write, Edit, Bash(which *), Bash(vercel *), Bash(eas *), Bash(npm *), Bash(railway *), Bash(jq *), Bash(mkdir *), Bash(cp *), Bash(echo *), Skill(cbp-supabase-setup)
+effort: xhigh
+---
+
+# Ship Configure Command
+
+Set up shipment for a surface so `/cbp-ship` can deploy it. Each surface is configured independently — runs once per repo per surface, persists in `.codebyplan/shipment.json` `surfaces.{id}`, then never asks again unless re-invoked.
+
+## When to Use
+
+- First-time shipment setup for a fresh repo
+- Adding a new surface to an existing repo (e.g., adding mobile to a web-only project)
+- Auto-suggested by `/cbp-ship` when it detects a surface that's not configured
+- Rotating credentials (re-runs the credential check, doesn't store anything)
+
+## Arguments
+
+`$ARGUMENTS`:
+
+- `--surface=<id>` — configure one surface. Valid: `vercel-web`, `expo-mobile`, `tauri-desktop`, `npm-package`, `vscode-ext`, `railway-backend`, `supabase`
+- No args — interactive picker; lists undetected/unconfigured surfaces and asks which to set up
+
+## Instructions
+
+### Step 1 — Pick the surface
+
+If `--surface=<id>` is set, use it. Otherwise:
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/../ship/scripts/detect-surfaces.sh"
+```
+
+Show the detection result and ask which to configure via AskUserQuestion (multi-select allowed).
+
+### Step 2 — Load the surface configurator
+
+For each chosen surface, read its configurator block from this skill's reference. Each block has the same shape:
+
+1. **Prerequisites** — what the user must have before starting (e.g., Apple Developer account, Vercel team)
+2. **Probe** — non-destructive checks (CLI installed, credential reachable, account permissions)
+3. **Setup** — the interactive walkthrough
+4. **Persist** — write to `.codebyplan/shipment.json` `surfaces.{id}`
+5. **Verify** — final check that the surface is now ready for `/cbp-ship` to use
+
+References:
+
+| Surface         | Reference                                                    |
+| --------------- | ------------------------------------------------------------ |
+| vercel-web      | [reference/vercel.md](reference/vercel.md)                   |
+| expo-mobile     | [reference/expo-mobile.md](reference/expo-mobile.md)         |
+| tauri-desktop   | [reference/tauri-desktop.md](reference/tauri-desktop.md)     |
+| npm-package     | [reference/npm-package.md](reference/npm-package.md)         |
+| vscode-ext      | [reference/vscode-ext.md](reference/vscode-ext.md)           |
+| railway-backend | [reference/railway-backend.md](reference/railway-backend.md) |
+| supabase        | [reference/supabase.md](reference/supabase.md)               |
+
+**Supabase — branching integration** (run AFTER Step 5 — Verify completes for the
+supabase surface; do NOT invoke during Steps 1–4): once Step 5 has finished and
+`shipment.surfaces.supabase` is persisted, run
+`jq '.shipment.surfaces.supabase.branching_configured // empty' .codebyplan.json`.
+If empty, invoke `/cbp-supabase-setup` (GitHub integration, required-status-check,
+persistent branch). Delegate fully — do NOT duplicate steps inline. If already set,
+note as already-done in the Step 6 report.
+
+### Step 3 — Walk the user through setup, step by step
+
+This skill NEVER dumps "here's a 200-line guide, follow it." Every step is one-at-a-time, interactive:
+
+```
+Step 1/6: Check Vercel CLI is installed
+[runs: which vercel]
+✓ vercel 35.0.1 found at /usr/local/bin/vercel
+
+Step 2/6: Check you're logged in
+[runs: vercel whoami]
+✓ Logged in as midevyou
+
+Step 3/6: Link this repo to a Vercel project
+You'll run: vercel link
+This creates .vercel/project.json. Choose: existing project / create new.
+
+Press Enter when ready to run, or type 'skip' to do it yourself.
+```
+
+For commands the user must run (vsce login, npm login, eas login, supabase login — any 2FA/OTP flow), display the command and wait for the user to run it themselves, then verify by re-probing. Never run interactive auth commands via Bash.
+
+For commands that are safe to run on the user's behalf (CLI version checks, file scaffolding, JSON read/write), run them directly with the user's pre-confirmation.
+
+### Step 4 — Persist what was configured
+
+Write to `.codebyplan/shipment.json` (create the file if missing):
+
+```json
+{
+  "surfaces": {
+    "vercel-web": {
+      "configured_at": "2026-04-29T14:32:00Z",
+      "project_id": "prj_abc123",
+      "team_id": "team_xyz789",
+      "framework": "nextjs",
+      "production_branch": "main"
+    }
+  }
+}
+```
+
+The block contains references and IDs only — NO credentials, tokens, or secrets. Credentials live in:
+
+- Vercel: `~/.local/share/com.vercel.cli/auth.json` (CLI session)
+- npm: `~/.npmrc` (auth token) or 2FA per-publish
+- EAS: `~/.expo/state.json` (CLI session)
+- Apple: Keychain + ASC API key files
+- Supabase: `~/.supabase/access-token` (CLI session)
+- Railway: `~/.railway/config.json` (CLI session)
+- vsce (VS Code): `~/.vscode/.vsce` (PAT)
+
+The skill's job is to verify these credentials EXIST and are valid; never to store or copy them.
+
+### Step 5 — Verify shipment-readiness
+
+Run the verification step from the surface reference. For Vercel, this is:
+
+```bash
+vercel inspect "$(jq -r '.surfaces."vercel-web".project_id' .codebyplan/shipment.json)" 2>&1 | head -20
+```
+
+If verification passes, mark the surface as configured. If it fails, surface the error and offer to retry the failing step.
+
+### Step 6 — Report
+
+```
+## Surface configured: vercel-web
+
+Project: codebyplan-web (prj_abc123)
+Team: midevy-eu (team_xyz789)
+Framework: Next.js
+Production branch: main
+
+Saved to .codebyplan/shipment.json: surfaces.vercel-web
+
+Ready for /cbp-ship.
+```
+
+If multiple surfaces were configured, list each one's status. If any failed, list those at the end with the next-step prompt.
+
+## Re-run safety
+
+Re-running on an already-configured surface re-runs the probe (CLI installed? logged in? token still valid?) and refreshes the `.codebyplan/shipment.json` block. It does NOT replace credentials — those stay where the CLI keeps them. This is the primary path for "I rotated my npm token, does shipment still work?" — re-run, the probe catches the bad token immediately.
+
+## Special case: opt-in to release-please
+
+`release-please` is one of three versioning modes (manual, release-please, changesets). Opt-in is part of npm-package configure:
+
+```
+Step N/M: Versioning mode
+A) Manual — bump package.json version yourself before /cbp-ship
+B) release-please — GH Action opens version-bump PRs based on conventional commits (recommended for npm packages)
+C) changesets — manual changeset entries; tooling aggregates into version PRs (recommended for monorepos with many published packages)
+```
+
+If B or C, the skill scaffolds the GitHub Actions workflow + config file (`templates/workflows/release-please.yml` or `.changeset/config.json`).
+
+## Special case: `codebyplan` asset-publish automation
+
+The canonical-owner repo publishes the `codebyplan` npm package — the distribution mechanism for `scope: org-shared` skills/agents/hooks (via its `claude install|update|uninstall` subcommand group). Sibling repos consume it via `npx codebyplan claude update` (the merged CLI; package path `packages/codebyplan-package/`). This branch handles the once-per-repo setup so release-please can autopublish on merge to main. (CHK-132 consolidated the prior standalone `@codebyplan/claude` package into `codebyplan`; the legacy `@codebyplan/claude` package on npm stays un-deprecated at its last published version for backward-compat, but receives no further updates.)
+
+When the user picks `--surface=npm-package` AND the detected package is `packages/codebyplan-package`, the walkthrough runs these extra probes / scaffolds in addition to the standard npm-package configurator (see [reference/npm-package.md](reference/npm-package.md)):
+
+### Probe 1 — npm whoami
+
+```bash
+npm whoami 2>&1 || echo "RUN: npm login (need: https://www.npmjs.com/login)"
+```
+
+If 401 / not logged in, STOP and surface the login URL. Re-run after the user logs in.
+
+### Probe 2 — @codebyplan scope membership
+
+```bash
+npm access list packages @codebyplan 2>&1 | head -20
+```
+
+Confirms the logged-in account has read on the `@codebyplan` org scope. If 404 / no access:
+
+- Either the user does not belong to the `@codebyplan` org → STOP, request invitation from org owner
+- Or the scope is unclaimed → user creates the org at https://www.npmjs.com/org/create (org name `codebyplan`, free public-packages tier)
+
+### Scaffold 1 — release-please workflow
+
+If `.github/workflows/release-please.yml` is absent:
+
+```bash
+mkdir -p .github/workflows
+cp "${CLAUDE_SKILL_DIR}/../ship/templates/workflow-release-please.yml" .github/workflows/release-please.yml
+# Then replace REPLACE_WITH_INTEGRATION_BRANCH with the production branch from .codebyplan/git.json branch_config.production (typically `main`)
+```
+
+The mechanics + commit-prefix → bump-tier mapping live in [../ship/reference/release-please-overview.md](../ship/reference/release-please-overview.md).
+
+### Scaffold 2 — release-please-config.json at repo root
+
+If `release-please-config.json` is absent:
+
+```bash
+cp "${CLAUDE_SKILL_DIR}/../ship/templates/release-please-config.json" release-please-config.json
+# Then replace REPLACE_WITH_PACKAGE_NAME with codebyplan
+# Confirm `packages."."` block is replaced with `packages."packages/codebyplan-package"`
+```
+
+### Scaffold 3 — .release-please-manifest.json at repo root
+
+If `.release-please-manifest.json` is absent:
+
+```bash
+VERSION=$(jq -r '.version' packages/codebyplan-package/package.json)
+echo "{\"packages/codebyplan-package\": \"${VERSION}\"}" > .release-please-manifest.json
+```
+
+(Bootstrap version reads from `packages/codebyplan-package/package.json` `version` field at scaffold time.)
+
+### Verify — publishConfig.access on the package
+
+```bash
+jq -r '.publishConfig.access // "missing"' packages/codebyplan-package/package.json
+```
+
+Required value: `public`. If `missing` or `restricted`, instruct the user to add:
+
+```json
+{
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}
+```
+
+### Persist
+
+```json
+{
+  "surfaces": {
+    "npm-package": {
+      "packages/codebyplan-package": {
+        "package_name": "codebyplan",
+        "bin_name": "codebyplan",
+        "versioning": "release-please",
+        "publish_mode": "release-please-on-merge-to-main",
+        "access": "public"
+      }
+    }
+  }
+}
+```
+
+After this branch completes, every merge to main with `feat:` / `fix:` / `feat!:` Conventional Commits will trigger release-please to open a version-bump PR. When the maintainer merges that PR, release-please tags the release and `npm publish` runs from the workflow (auth via `NODE_AUTH_TOKEN` GH secret or OIDC trusted publishing — see [../ship/reference/npm-publish-oidc-trusted.md](../ship/reference/npm-publish-oidc-trusted.md)). Siblings then pick up the new asset content via `npx codebyplan claude update`.
+
+## Special case: Apple credentials for TestFlight
+
+Apple credential setup is by far the most error-prone step. The reference lays out:
+
+1. Apple Developer Program enrollment ($99/yr) — user-side, link only
+2. App Store Connect API key creation — user-side, walk-through
+3. Local p8 file storage — user does, skill verifies path
+4. Tauri-style p12 + signing identity — only needed if also configuring tauri-desktop
+5. EAS credentials sync — `eas credentials` walkthrough
+
+The configurator confirms each piece is reachable; it never stores them. See [reference/expo-mobile.md](reference/expo-mobile.md) and [reference/tauri-desktop.md](reference/tauri-desktop.md).
+
+## Key Rules
+
+- **Step-by-step always** — never paste a 200-line "do all of this" block; one step, wait for confirmation, next
+- **Run safe commands directly, instruct unsafe ones** — version checks and JSON edits run via Bash; auth commands and 2FA flows are user-run
+- **Never store credentials in `.codebyplan/repo.json`** — only IDs, project refs, branch names
+- **Re-running is idempotent** — re-runs refresh the probe + persist block, never overwrite credentials
+- **One surface per invocation when via `--surface`** — multi-select picker for the no-args path
+- **Verify at the end** — final probe must succeed before marking configured
+
+## Additional resources
+
+- Per-surface configurators: [reference/](reference/) — one file per surface
+- GH Actions workflow templates: [scripts/](scripts/) — scaffolded into `.github/workflows/` when versioning mode is opt-in
+- Detection script (shared with `/cbp-ship`): `${CLAUDE_PLUGIN_ROOT}/skills/ship/scripts/detect-surfaces.sh`
+
+## Integration
+
+- **Triggered by**: user invocation; auto-suggested by `/cbp-ship` when an unconfigured surface is detected
+- **Reads**: `.codebyplan/shipment.json`, repo filesystem (vercel.json, eas.json, supabase/, etc.), CLI session state via probe commands
+- **Writes**: `.codebyplan/shipment.json` `surfaces.{id}`; optionally scaffolds `eas.json`, `vercel.json`, `.github/workflows/*.yml`, `.changeset/config.json` from templates
+- **Calls**: shared detection script; per-surface CLI tools (vercel, eas, supabase, railway, npm, vsce) for probes
+- **Triggers**: returns control to user; if invoked from `/cbp-ship`, returns there for resume

package/templates/skills/cbp-ship-configure/reference/expo-mobile.md

@@ -0,0 +1,204 @@
+# Configure: expo-mobile
+
+Walkthrough for first-time Expo + EAS + TestFlight setup.
+
+## Prerequisites
+
+- Apple Developer Program enrollment ($99/yr) — https://developer.apple.com/programs/enroll/
+- Google Play Developer account ($25 one-time, optional if Android-only later)
+- Expo account (free) — https://expo.dev/signup
+- App Store Connect record for the app (created in ASC dashboard)
+
+## Probe
+
+```bash
+which npx
+npx eas-cli --version || { echo "Will install eas-cli on first use"; }
+npx eas whoami || { echo "Run: npx eas login"; exit 1; }
+```
+
+## Setup walkthrough
+
+### Step 1/9: Verify Expo account + EAS access
+
+```bash
+npx eas whoami
+```
+
+If not logged in:
+
+```
+Run: npx eas login
+Use your expo.dev account credentials.
+```
+
+### Step 2/9: Initialize EAS project
+
+```bash
+cd "$APP_PATH"
+npx eas init
+```
+
+This creates `eas.json` skeleton + adds `expo.extra.eas.projectId` to `app.json`.
+
+### Step 3/9: Configure `app.json`
+
+Verify these fields are set:
+
+```json
+{
+  "expo": {
+    "name": "Your App",
+    "slug": "your-app",
+    "version": "1.0.0",
+    "ios": {
+      "bundleIdentifier": "com.yourcompany.yourapp",
+      "buildNumber": "1"
+    },
+    "android": {
+      "package": "com.yourcompany.yourapp",
+      "versionCode": 1
+    }
+  }
+}
+```
+
+The bundle ID and package name **must match** your App Store Connect / Play Console records.
+
+### Step 4/9: Configure `eas.json`
+
+Use the template at `${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/eas.json`. Customize:
+
+```json
+{
+  "cli": { "version": ">= 5.0.0" },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal",
+      "ios": { "simulator": false },
+      "channel": "preview",
+      "autoIncrement": "buildNumber"
+    },
+    "production": {
+      "channel": "production",
+      "autoIncrement": "buildNumber"
+    }
+  },
+  "submit": {
+    "production": {
+      "ios": {
+        "appleId": "<your apple id email>",
+        "ascAppId": "<from App Store Connect — App Information → Apple ID>",
+        "appleTeamId": "<from developer.apple.com → Membership>"
+      },
+      "android": {
+        "serviceAccountKeyPath": "./google-play-service-account.json",
+        "track": "internal"
+      }
+    }
+  }
+}
+```
+
+### Step 5/9: Apple Developer credentials
+
+The skill walks the user through these one at a time:
+
+#### 5a. App Store Connect API key
+
+```
+1. Go to https://appstoreconnect.apple.com/access/api
+2. Click 'Generate API Key' (or 'Add Key' if you have access)
+3. Name it 'EAS Build', role 'App Manager'
+4. Download the .p8 file (you can only download ONCE)
+5. Note the Key ID and Issuer ID
+
+Save the .p8 file to ~/private_keys/AuthKey_<KEYID>.p8
+Reply with the Key ID and Issuer ID when ready.
+```
+
+#### 5b. Sync credentials with EAS
+
+```bash
+cd "$APP_PATH"
+npx eas credentials
+```
+
+This is interactive. The skill instructs:
+
+```
+- Select platform: iOS
+- Select build profile: production
+- Select 'Distribution Certificate' → Set up new
+- Use the App Store Connect API key from step 5a
+- Select 'Provisioning Profile' → Set up new
+
+Reply 'done' when finished.
+```
+
+#### 5c. Same for Android (if shipping Android)
+
+```
+1. Generate Service Account: https://console.cloud.google.com/iam-admin/serviceaccounts
+2. Grant 'Service Account User' role on Play Console (Users & Permissions)
+3. Download JSON key, save as ./google-play-service-account.json
+4. Add path to .gitignore (NEVER commit)
+```
+
+### Step 6/9: Persist to `.codebyplan/shipment.json`
+
+```json
+{
+  "surfaces": {
+    "expo-mobile": {
+      "configured_at": "<now>",
+      "app_path": "apps/mobile",
+      "eas_project_id": "<from app.json>",
+      "ios_bundle_id": "com.yourcompany.yourapp",
+      "android_package": "com.yourcompany.yourapp",
+      "default_testflight_group": "internal",
+      "versioning": "auto-build-number"
+    }
+  }
+}
+```
+
+### Step 7/9: Test build (dev profile)
+
+Before committing the config, verify the credential setup with a dev build:
+
+```bash
+npx eas build --profile development --platform ios --non-interactive
+```
+
+This is fast (~10 min) and confirms the iOS credential chain works without uploading to TestFlight.
+
+If it fails, the skill walks the user through `npx eas credentials` audit again.
+
+### Step 8/9: Stage `eas.json` + `app.json`
+
+The user reviews the diff and commits these files. The skill does NOT commit on the user's behalf.
+
+### Step 9/9: Verify the surface
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/ship/scripts/detect-surfaces.sh" --filter=expo-mobile | jq
+# Expect: configured: true
+```
+
+## Done
+
+Surface is ready. `/cbp-ship` will offer mobile shipment options at next checkpoint end.
+
+## Common setup issues
+
+| Symptom | Fix |
+|---|---|
+| `eas init` fails "user does not have access" | Add the user to the Expo organization: https://expo.dev/accounts/{org}/members |
+| `eas credentials` shows "Distribution Certificate is invalid" | Renew via Apple Developer; Apple revokes after team ID changes or expiry |
+| TestFlight build rejected with ITMS-90xxx | Common: missing `NSCalendarsUsageDescription` etc. in `app.json` `expo.ios.infoPlist` |
+| Bundle ID rejected | Already in use by another developer; pick a different bundle ID |

package/templates/skills/cbp-ship-configure/reference/npm-package.md

@@ -0,0 +1,165 @@
+# Configure: npm-package
+
+Walkthrough for first-time npm publish setup.
+
+> **Special case** — when the package being configured is `packages/codebyplan-package` (i.e., the `codebyplan` npm package that ships `scope: org-shared` skills/agents/hooks via its `claude` asset subcommand group), the parent SKILL.md "Special case: `codebyplan` asset-publish automation" section runs additional probes (npm whoami, npm publish auth) and scaffolds (`release-please-config.json`, `.release-please-manifest.json` at repo root) on top of the generic walkthrough below. See SKILL.md for the full extra flow. (CHK-132 consolidated the prior `@codebyplan/claude` package into `codebyplan`.)
+
+## Prerequisites
+
+- npm account (https://www.npmjs.com/signup) — free
+- 2FA enabled (mandatory for publish): npm web → Profile → 2FA Settings → "Authorization and writes"
+- For scoped packages (`@scope/pkg`): the scope owned by your account or org
+
+## Probe
+
+```bash
+which npm
+npm whoami || { echo "Run: npm login"; exit 1; }
+npm profile get tfa | grep -q "auth-and-writes" || { echo "Enable 2FA: npm profile enable-2fa auth-and-writes"; exit 1; }
+```
+
+## Setup walkthrough
+
+### Step 1/7: Pick the package
+
+If monorepo with multiple publishable packages, configure each separately. The skill detects which `package.json` files have `private: false` (or absent) and asks which to configure.
+
+### Step 2/7: Verify package.json metadata
+
+The skill checks each required field one at a time:
+
+```
+✓ name: @codebyplan/web-package
+✓ version: 0.1.0
+✗ description: missing — what does this package do?
+✓ keywords: [...]
+✗ repository: missing — public GH URL?
+✓ license: MIT
+✗ author: missing
+```
+
+For each missing/wrong field, the skill prompts and writes the answer.
+
+### Step 3/7: Verify entrypoints
+
+```bash
+cd "$PKG_PATH"
+MAIN=$(jq -r .main package.json)
+[ -f "$MAIN" ] || echo "WARN: main entry $MAIN missing — needs build first"
+
+# Better: exports map
+EXPORTS=$(jq -r '.exports."."' package.json)
+[ "$EXPORTS" != "null" ] || echo "Recommend adding exports map for ESM/CJS dual support"
+```
+
+If `exports` is missing, suggest:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"]
+}
+```
+
+### Step 4/7: Run package validators
+
+```bash
+cd "$PKG_PATH"
+npm pack --dry-run     # what's in the tarball
+pnpm publint           # package.json lint
+pnpm attw --pack       # ESM/CJS resolution check
+```
+
+Surface any errors/warnings; offer to fix obvious ones (missing `files`, wrong `main`).
+
+### Step 5/7: Pick versioning mode
+
+```
+A) Manual — bump package.json version yourself before each release
+B) release-please — GH Action opens version-bump PRs based on conventional commits (recommended)
+C) changesets — manual changeset entries; aggregator PR (recommended for monorepos)
+```
+
+If B, scaffold:
+
+```bash
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/workflow-release-please.yml .github/workflows/release-please.yml
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/release-please-config.json release-please-config.json
+echo '{".":"<current version>"}' > .release-please-manifest.json
+```
+
+If C:
+
+```bash
+cd "$REPO_ROOT"
+pnpm add -Dw @changesets/cli
+npx changeset init
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/workflow-changesets.yml .github/workflows/changesets.yml
+```
+
+### Step 6/7: Pick publish mode
+
+```
+A) Local publish (manual OTP per release) — works immediately
+B) OIDC trusted publishing from GH Actions — no token, no leak risk (recommended for prod)
+```
+
+If B:
+
+1. https://www.npmjs.com/settings/{account}/trusted-publishers
+2. Add: `<owner>/<repo>` → workflow `.github/workflows/npm-publish.yml`, environment `release`
+3. Skill scaffolds:
+
+```bash
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/workflow-npm-publish.yml .github/workflows/npm-publish.yml
+```
+
+The workflow uses `permissions: id-token: write` and runs `npm publish --provenance --access public`.
+
+### Step 7/7: Persist + verify
+
+```json
+{
+  "surfaces": {
+    "npm-package": {
+      "configured_at": "<now>",
+      "packages/codebyplan-package": {
+        "package_name": "codebyplan",
+        "versioning": "release-please",
+        "publish_mode": "oidc",
+        "access": "public"
+      }
+    }
+  }
+}
+```
+
+Verify (no actual publish — just dry-run the publish command):
+
+```bash
+cd "$PKG_PATH"
+npm publish --dry-run
+# Inspect output for warnings; no upload happens
+```
+
+## Done
+
+Surface is ready. `/cbp-ship` will offer publish when version bumps.
+
+## Common setup issues
+
+| Symptom                                | Fix                                                                         |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| `npm publish` 402 (paid plan required) | Scoped public package needs `--access public` (default is private for orgs) |
+| 403 on first publish                   | Scope not owned by you; create org or use unscoped name                     |
+| `attw` reports "FalseESM"              | `package.json` `type: "module"` but exports point to .cjs files             |
+| Tarball missing TypeScript types       | Add `"types"` to `exports` map AND add `dist/**/*.d.ts` to `files`          |