@webpresso/agent-kit 0.21.0

package/catalog/agent/rules/agent-guide.md

@@ -0,0 +1,464 @@
+---
+type: rule
+slug: agent-guide
+title: Agent Rules
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+paths: 
+  - 'schema/**/*.yaml'
+  - '**/*.ts'
+  - '**/*.tsx'
+  - 'legacy task-runner file'
+---
+
+# Agent Rules
+
+> Generic agent rules for a monorepo using webpresso. Cross-platform rules live
+> in `AGENTS.md` (auto-loaded).
+
+## Entity / Schema System (YAML SSOT)
+
+If your project uses a YAML-declared entity / schema system:
+
+- **Source of truth**: `schema/*.yaml` (or `entities/*.yaml`)
+- **Entity name = filename** (e.g., `agent_tasks.yaml` → `entity: agent_tasks`)
+- **DB table preserved** via an explicit `database.table` field
+- **Leading `_` = external** (skipped in compilation)
+- **Never edit compiled metadata** directly
+
+## Before Modifying Entities
+
+- Validate with your repo's schema-check recipe (runs static + runtime checks)
+- Dry-run compile before apply
+
+## Field Types (Typical)
+
+`text`, `text[]`, `integer`, `bigint`, `boolean`, `timestamp`, `date`, `jsonb`,
+`numeric`, `uuid`
+
+## Reference Format
+
+```yaml
+references:
+  table: projects
+  column: id
+  onDelete: cascade
+```
+
+## Naming Convention
+
+Entity / table prefixes carve out domains. Typical examples:
+
+| Prefix           | Domain                                          |
+| ---------------- | ----------------------------------------------- |
+| `agent_*`        | AI Agent personas, scheduling, suggestions      |
+| `ai_*`           | AI Agent sessions and usage tracking            |
+| `billing_*`      | Billing, invoices, and ledger                   |
+| `blueprint_*`    | Blueprint definitions and execution             |
+| `deployment_*`   | Deployment management                           |
+| `meta_*`         | Platform metadata (entities, fields, roles)     |
+| `notification_*` | Notification system and preferences             |
+| `project_*`      | Project-level resources and configuration       |
+| `task_*`         | Task tracking, labels, and analysis             |
+| `user_*`         | User profiles, activity, and preferences        |
+| `workflow_*`     | Workflow definitions, execution, and scheduling |
+
+Adapt the prefix list to your domain; the rule that matters is that the
+prefix → domain mapping is stable and checked in.
+
+## Import Aliases (`#`)
+
+**Universal `#` import aliases are configured across the monorepo.**
+
+### Rules
+
+- **Use `#` for all cross-directory imports** within a package.
+- **`#` maps to `src/`** for packages, `app/` for pages apps.
+- **Keep `./` for same-directory imports** (e.g., `from './types'`).
+- **Never use `../` for imports** within `src/` — always use `#`.
+- **Never use `../src/` in imports** — this is always wrong; use `#` instead.
+- **`vi.mock()` paths must use `#`** — never use relative `../` paths in
+  `vi.mock()` calls. Relative mock paths break when vitest projects use
+  `extends: false` or when test files are at different directory depths.
+  Always match the source code's import style.
+
+### Why `#` Instead of `~/`?
+
+**The Problem**: TypeScript `paths` (`~/`) resolve relative to the tsconfig
+doing the typechecking. In monorepos with source exports, when package A
+typechecks package B's source, `~/` resolves against package A's tsconfig,
+causing `Cannot find module '~/...'` errors.
+
+**The Solution**: Node.js **subpath imports** (`#`) are package-scoped. They
+resolve via the **declaring package's** `package.json` `imports` field,
+regardless of which package is typechecking.
+
+### Configuration Required
+
+**Every package** using `#` imports MUST have BOTH:
+
+1. **`package.json`** `imports` field (for Node.js runtime + cross-package
+   typechecking):
+
+```json
+{
+  "imports": {
+    "#*": "./src/*.ts"
+  }
+}
+```
+
+2. **`tsconfig.json`** `paths` field (for TypeScript within the package):
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "#*": ["./src/*"]
+    }
+  }
+}
+```
+
+**Both are required.** The `package.json` field enables cross-package
+resolution; the `tsconfig.json` paths enable within-package typechecking.
+
+### Examples
+
+```typescript
+// ✅ Cross-directory imports with #
+import { foo } from '#lib/utils'
+import { bar } from '#services/auth'
+import { baz } from '#database/schema'
+
+// ✅ Same-directory imports with ./
+import { helpers } from './helpers'
+import type { User } from './types'
+
+// ❌ Wrong - relative parent imports
+import { bar } from '../../services/auth'
+
+// ✅ vi.mock with # alias (matches source imports)
+vi.mock('#services/auth', () => ({ /* ... */ }))
+vi.mock('#database', () => ({ /* ... */ }))
+
+// ❌ Wrong - relative vi.mock paths (may not match resolved module ID)
+vi.mock('../../services/auth', () => ({ /* ... */ }))
+vi.mock('../src/database', () => ({ /* ... */ }))
+```
+
+### Infrastructure
+
+- `vite-tsconfig-paths` plugin configured in vitest and vite for runtime `#`
+  resolution.
+- All packages use `paths` with relative values in `tsconfig.json` (no
+  `baseUrl` — removed for TS7 / tsgo compatibility).
+- All packages export source directly (`exports` pointing to `./src/*.ts`),
+  making `#` the only viable solution for cross-package typechecking.
+
+## Isolated Validation for Structural Changes
+
+**Before modifying infrastructure, bundler config, or cross-package resolution
+in production packages**, validate the change in the smallest affected
+package first.
+
+- **Use a narrow scope**: prefer the smallest package that exercises the
+  target behavior.
+- **Use it to**: test build-tool upgrades, plugin compatibility, module
+  resolution changes, new export conditions, and `#` alias behavior in
+  isolation.
+- **Why**: production packages have large module graphs and long startup
+  times, so isolating the change first keeps debugging cost bounded.
+
+## Repo Restrictions
+
+See [repo-restrictions.md](repo-restrictions.md) for the complete enforcement
+guide — how to add new restrictions via linter plugins, hooks, and agent
+instructions.
+
+## Deterministic External Boundaries
+
+When code talks to an external boundary — subprocesses, sockets, workers, HTTP
+services, WebSocket handshakes, file-system locks, or polling-based readiness
+checks — the behavior must be deterministic.
+
+### Rules
+
+- **Every external async boundary must have an explicit deadline or bounded
+  polling policy.**
+- **Timeout ownership belongs to the caller or config layer**, not hidden
+  transport internals.
+- **Prefer shared helpers** such as `withDeadline` and `pollUntil` from your
+  shared utilities package over ad hoc `Promise.race(...)`,
+  `Date.now() + timeoutMs`, or local timeout wrappers.
+- **Use fake timers for timeout unit tests** and attach rejection handlers
+  before advancing timers.
+- **Use real timers only for runtime integration tests** where the goal is to
+  prove actual subprocess, socket, or network behavior.
+
+### Anti-patterns
+
+- Inline `Promise.race([work, timeoutPromise])` helpers duplicated per package
+- Unbounded `while (...)` polling loops driven by `Date.now()` arithmetic
+- Environment-variable-only timeout policy for library code
+- Timeout tests that rely on wall-clock sleeps when fake timers would prove
+  the same behavior faster and more reliably
+
+### Hook and discovery-specific requirements
+
+- **Generated hook runtimes must be path-stable.** If setup or scaffolding
+  writes executable hook commands, prefer absolute binary paths or a
+  repo-controlled absolute anchor. Do not depend on the host PATH inside Codex,
+  Claude, CI, or other sanitized hook environments.
+- **Repair generated runtime state at the source.** If a generated hook surface
+  is broken or duplicated, fix the owning scaffolder/setup path and add a
+  regression test. Do not treat hand-editing generated `.codex/`, `.claude/`,
+  or user-home runtime files as the durable solution.
+- **Discovery paths must degrade, not hang.** MCP roots fetches, git probes,
+  and project/worktree discovery must have explicit budgets and return partial
+  structured results with warnings when a dependency is slow or unavailable.
+- **Contract requirement:** discovery tool lanes (`wp_blueprint_projects`,
+  `wp_blueprint_list`, `wp_blueprint_get` aggregate scope) must return partial
+  results and warning signals instead of blocking on any single slow external
+  dependency. No workflow is allowed to “fix” this by raising global MCP/tool
+  deadlines alone.
+
+## Network Resilience
+
+Retry logic belongs in the **HTTP / data-access layer**, not in React hooks
+or components.
+
+- Put retries in the function that makes the network call, not in
+  `useCallback` or `useEffect`.
+- Stacking retries at multiple layers creates cascading delay budgets and
+  uncoordinated retry storms.
+- Use `sleep` and `isRetryableError` (or equivalent) from your shared
+  utilities — never roll a raw
+  `new Promise(resolve => setTimeout(resolve, ms))`.
+- Retry only idempotent, retryable error codes (ECONNREFUSED, ETIMEDOUT,
+  ECONNRESET). Non-retryable errors (4xx, auth) must break immediately.
+
+## Environment Variables & Secret Injection
+
+Runtime environment variables and secrets are **never** stored in `.dev.vars`,
+`.env` files, or any file on disk. They are resolved at runtime by the
+repo's secret manager wrapper (e.g. Doppler, 1Password, AWS Secrets Manager).
+
+### Rules
+
+- **Never suggest creating `.dev.vars`** — it is not part of this workflow.
+- **Never suggest creating `.env` files** for secrets.
+- **Always use the repo's secret-bearing command wrapper** when a command
+  needs repo-managed environment injection.
+- **Prefer a dedicated recipe over an escape-hatch wrapper** when the workflow
+  is repo-owned and repeatable.
+- **Do not ask the user to manually export** `DATABASE_URL` or other secret
+  env vars for normal repo commands.
+- If required env vars are missing at runtime, the fix is: ensure the command
+  runs through the secret-bearing wrapper, **not** to create config files.
+- Secret manager setup is manager-driven and should go through the repo
+  workflow first. Treat the active secret manager as one implementation under
+  an abstraction, not a hardcoded repo-wide assumption.
+- Do not tell the user to paste secrets onto disk or create local
+  `.env` / `.dev.vars` fallbacks.
+- **Never cache credentials to disk for performance.** Source-of-truth tools
+  (`gh auth token`, `op read`, `doppler secrets get`, `aws sts ...`) are fast
+  enough; if a per-shell fork is too slow, the fix is upstream (lazy resolve,
+  daemon), not a plaintext cache file. User-level paths (`~/.cache/`,
+  `~/.config/<tool>/`, `/tmp/`) are still disk — same rule applies.
+
+## File & Path Rules
+
+### Scripts Location
+
+- **Never** create a root-level `/scripts/` folder if the repo has a
+  dedicated command/runtime surface (e.g. `src/ci/`, `src/audit/`, or a
+  repo-owned scripts package).
+- All scripts go in the dedicated scripts package.
+- Run with the repo's script-runner recipe.
+
+### Executable Path Anchors
+
+- **Never** use `resolve(import.meta.dirname, '../..')`, `join(__dirname, './x')`,
+  `new URL('../x', import.meta.url)`, or any other hardcoded relative
+  filesystem path in executable code or config.
+- **Always** use a repo-provided helper or runtime-provided absolute base path
+  as the anchor.
+- When available, enforce this through the shared `wp audit absolute-path-policy`
+  surface rather than a repo-local duplicate scanner.
+- Packages live at varying depths — hardcoded relative paths break when files
+  move.
+
+## Commit messages
+
+Prefer subjects that name area and intent (see `AGENTS.md`); avoid opaque
+one-word subjects for platform-wide changes.
+
+## E2E Coverage Contract
+
+When changing or adding a user-facing feature, agents must classify browser
+coverage explicitly instead of treating all Playwright tests as
+interchangeable.
+
+### Suites
+
+- a real critical-path journey suite (or equivalent): persisted user
+  workflows.
+- a smoke/canary suite: route health, accessibility canaries, quarantined
+  flows, and non-persistent checks.
+- Sibling feature suites (e.g. `admin/`, `notifications/`): domain-specific
+  browser coverage that still must follow the same realism rules.
+
+### When a new feature needs a journey test
+
+Add or extend a journey-grade E2E test when the change affects any of these:
+
+- creation, update, delete, or role/permission changes
+- multi-step wizards or workflows
+- persistence after reload or re-entry
+- list-to-detail-to-save flows
+- auth, session, consent, analytics, or redirect behavior
+- user-visible error recovery on a critical path
+
+### When smoke coverage is enough
+
+Smoke-only coverage is acceptable for:
+
+- route availability
+- access control canaries
+- accessibility checks without mutation
+- temporary quarantine coverage for product paths that are not yet viable as
+  real journeys
+
+Smoke coverage must not be counted as equivalent to journey coverage.
+
+### Journey rules
+
+- use real browser login and Playwright `storageState`; do not use cookie or
+  session injection
+- reach pages through visible UI navigation when that is part of the real path
+- mutate state through the UI or real browser-origin requests only
+- verify persistence after reload, revisit, or downstream navigation
+- fail on visible backend errors instead of treating them as alternate success
+- do not use in-test `skip` for required seed data
+- do not claim an E2E feature is complete until focused checks and the full
+  `journeys` plus `smoke` suites are green through the repo's task runner
+
+### Forbidden shortcuts for browser tests
+
+- synthetic analytics or DB inserts for the behavior under test
+- direct-detail URL bypass when a visible list or CTA is the real path
+- API or database cleanup standing in for the action being tested
+- assertions that only prove a modal opened, a request fired, or a placeholder
+  rendered
+
+### Manual verification is not a deliverable
+
+A blueprint task whose acceptance criteria says "manually verify in the
+browser", "open the page and confirm", or equivalent is **incomplete**. Human
+click-through verification degrades immediately: it is not repeatable, not
+regression-safe, and cannot be run in CI.
+
+**Rule**: if the only way to verify a task is to open a browser and look at
+the page, write a Playwright E2E test instead. The test becomes the
+acceptance evidence.
+
+When you encounter this during blueprint execution:
+
+1. Identify the page, route, or user interaction the manual step describes.
+2. Write a `journeys/` or `smoke/` spec that automates that check.
+3. Replace the manual acceptance item with a reference to the new spec file.
+4. Mark the task done only after the spec is committed.
+
+This also applies retroactively: if a blueprint task already marked `done`
+has only manual evidence, raise it as a gap and add the missing spec.
+
+### Coverage audit checklist
+
+Before adding or reviewing browser coverage for a feature, verify these in
+order:
+
+- identify the real browser entrypoint from visible shell navigation, header
+  CTAs, or in-product links
+- confirm whether the surface uses real backend state or only local/mock data
+- classify the surface as `journey`, `smoke`, or `not-yet-journeyable`
+- if the route is backed by mock data or local-only state, do not fake a
+  persisted journey; prefer integration tests and document the product gap
+- if the route is read-only and already covered by adjacent journeys, prefer
+  smoke or route-health coverage over shallow duplicated journeys
+
+### Verification for shared E2E changes
+
+If you touch shared E2E auth, setup, runtime-state wiring, or other
+cross-suite infra, do not stop at a focused spec.
+
+- run the focused spec you changed
+- run the full `journeys` suite
+- run the full `smoke` suite
+- run the relevant typecheck or targeted test command for touched app
+  packages
+
+## Test Organization (Colocated Pattern)
+
+**Policy**: All test files use the **colocated pattern** — tests live next to
+the source files they test.
+
+### Rules
+
+- **Test files next to source**: `src/auth.ts` + `src/auth.test.ts`
+- **No `__tests__/` directories** — prohibited by policy
+- **Fixtures allowed**: `src/__fixtures__/` for test data
+- **Helpers allowed**: `src/test-helpers/` for test utilities
+
+### Naming Conventions
+
+| Test Type         | Pattern                 | Example                  |
+| ----------------- | ----------------------- | ------------------------ |
+| Unit tests        | `*.test.ts`             | `auth.test.ts`           |
+| Integration tests | `*.integration.test.ts` | `db.integration.test.ts` |
+| E2E tests         | `*.e2e.ts`              | `graphql-auth.e2e.ts`    |
+| Playwright specs  | `*.spec.ts`             | `login.spec.ts`          |
+
+### Enforcement
+
+- Pre-commit hook prevents new `__tests__/` directories.
+- Policy documented alongside this file.
+- Vitest automatically discovers colocated tests via `**/*.test.{ts,tsx}`.
+
+## Stryker mutation dry-run exclusions
+
+Integration tests that spawn heavyweight subprocesses (cold-start bun + TypeScript
+transpilation, long-lived MCP server processes, etc.) must be excluded from
+`vitest.stryker.config.ts`. They are covered by the regular `test` job; running
+them inside Stryker's forks pool pushes them past the 10 s unit-test timeout.
+
+**When to add an exclusion:**
+
+- The test calls `spawnSync('bun', [someSourceFile.ts, ...])` — bun cold-start
+  is ~5–11 s depending on the module graph.
+- The test spawns a long-lived child process (e.g. MCP server over JSON-RPC).
+- The test file is `*.integration.test.ts` or `*.e2e.test.ts` **and** it
+  spawns any external process that loads a significant module tree.
+
+**How to add one** (in `vitest.stryker.config.ts`):
+
+```ts
+exclude: [
+  ...,
+  // <one-line reason>
+  'src/path/to/heavy.integration.test.ts',
+]
+```
+
+**Current exclusions:** `init.e2e.test.ts`, `runner.test.ts`,
+`rtk/integration.test.ts`, `mcp/server.integration.test.ts`.
+
+After adding an exclusion, verify the Stryker suite still passes:
+
+```bash
+vp exec vitest run --config vitest.stryker.config.ts
+```

package/catalog/agent/rules/blueprint-scoping.md

@@ -0,0 +1,69 @@
+---
+type: rule
+slug: blueprint-scoping
+title: Blueprint scoping — product-wedge anchor required
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+---
+
+# Blueprint scoping — product-wedge anchor required
+
+New blueprints that extend or replace enabling-layer infrastructure (runtime,
+schema engine, agent fabric, session storage, policy engine, workflow runner)
+MUST name a product-wedge in the current roadmap stage that directly consumes
+the new capability. Blueprints without that anchor stay in `draft/` or move to
+`archived/`.
+
+## Why
+
+Infra-only blueprints that lack a product-wedge anchor tend to hit the same
+failure mode — substantial infra scope, no direct consumer pull, and a large
+share of the actual value lands via other paths. The findings are worth
+preserving; the blueprints themselves over-scoped.
+
+The fix is simple: before investing in infra, name the product surface that
+will use it in the same cycle.
+
+## How to apply
+
+During `wp blueprint new` / refinement, the blueprint `_overview.md` must
+include a **Product wedge anchor** subsection at the top of the summary. The
+anchor must name:
+
+1. The concrete roadmap outcome this work unblocks (cite the vision or
+   roadmap document and the specific outcome).
+2. The user-facing surface (route, UI component, CLI verb) that consumes the
+   new capability **in the same blueprint or an already-in-progress one**.
+3. What the product user can do after this lands that they cannot do today.
+
+### Template
+
+```markdown
+## Product wedge anchor
+
+- **Stage outcome:** <cite roadmap section + specific outcome>
+- **Consuming surface:** <route / component / verb + path>
+- **New user-visible capability:** <one sentence>
+```
+
+If you cannot fill all three, the blueprint is premature. Convert it to a
+fact-check document under `blueprints/draft/` with a note that it blocks on a
+product-wedge anchor, or mine its findings into a narrower blueprint that has
+one.
+
+## What counts as a product wedge
+
+A wedge is something a roadmap-stage user can see or touch:
+
+- An app they launched
+- A live deployment flow they triggered
+- A user they acquired via an acquisition loop
+- A KPI signal they read off a dashboard
+- A review decision they approved in the UI
+
+Pure-infra wedges ("cleaner runtime", "simpler fabric") do not qualify on
+their own. They qualify only when paired with one of the above.

package/catalog/agent/rules/changeset-release.md

@@ -0,0 +1,161 @@
+---
+type: rule
+slug: changeset-release
+title: Changesets Release Workflow
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-28'
+paths: 
+  - '.changeset/**'
+  - '.github/workflows/*.yml'
+  - 'package.json'
+  - 'CHANGELOG.md'
+  - 'src/**'
+---
+
+# Changesets Release Workflow
+
+This repository uses **Changesets** for version management and publishing.
+The active package identity here is `@webpresso/agent-kit` and the publish
+target is the public npm registry (`https://registry.npmjs.org/`).
+
+## Never do these
+
+- **Never** push `v*` tags manually for release purposes.
+- **Never** bump `package.json#version` by hand.
+- **Never** run `git tag v<X.Y.Z>` to trigger a publish.
+- **Never** run `vp run changeset publish` (or `changeset version`) without
+  committing the results first. `changeset version` modifies `package.json`,
+  `CHANGELOG.md`, and `.changeset/` — all three must be committed before
+  publishing. Unpublished version bumps in the working tree produce a valid
+  tarball but leave git history incoherent.
+- **Never** publish from a dirty working tree. Run `git status` first; commit
+  or stash everything before `changeset publish`.
+- **Never** treat `webpresso` (unscoped) as this repo's canonical release
+  package. This repo ships `@webpresso/agent-kit`.
+
+## Commit sequence — mandatory every release
+
+```
+1. Implement changes + commit code
+2. vp run changeset          # creates .changeset/<slug>.md
+3. git add .changeset/<slug>.md && git commit -m "chore: add changeset"
+4. Merge to main           # CI runs version bump + public npm publish automatically
+```
+
+Steps 2-3 happen on the feature branch alongside the code change. There is
+no manual `vp run changeset version` or `vp run changeset publish` step in the
+normal path — CI owns those for this repository.
+
+## How releases work (CI-driven, direct-publish on push to `main`)
+
+**This repo uses a direct-publish flow — there is no \"Version Packages\" PR.**
+
+When a feature branch with a `.changeset/<slug>.md` file merges to `main`,
+`release.yml` runs the following sequence automatically:
+
+1. `vp run version` — runs `changeset version &&
+   vp run sync-marketplace-version`. This bumps `package.json`, updates
+   `CHANGELOG.md`, removes the consumed `.changeset/<slug>.md` files, and
+   syncs `.claude-plugin/marketplace.json` to match the new version.
+2. `git push` — commits the version bump directly to `main`.
+3. `pnpm publish --no-git-checks` — publishes `@webpresso/agent-kit` to the
+   public npm registry using the workflow-owned publish path.
+4. CI creates a `release/v<version>` branch with compiled `dist/` committed
+   for Claude Code marketplace consumers.
+
+The workflow supports a manual dry-run trigger:
+```bash
+gh workflow run release.yml -f dry-run=true
+```
+
+## First-time setup — new extracted repos
+
+For a freshly bootstrapped repo that has never been published:
+
+```bash
+# 1. Ensure @changesets/cli is in devDependencies
+grep -q '@changesets/cli' package.json || vp install -D @changesets/cli
+
+# 2. Initialise changeset
+vp run changeset init                  # creates .changeset/config.json + README
+
+# 3. Enter prerelease mode (for alpha/beta dist-tags)
+vp run changeset pre enter alpha       # creates .changeset/pre.json
+
+# 4. Create the initial changeset and commit it
+cat > .changeset/initial-release.md << 'EOF'
+---
+"@webpresso/agent-kit": minor
+---
+
+Initial release for @webpresso/agent-kit.
+EOF
+git add .changeset/ && git commit -m "chore: add initial changeset"
+
+# 5. Merge to main — CI runs version bump + publish automatically
+```
+
+**Do NOT run `vp run changeset version` or `vp run changeset publish` manually**
+for established repos — CI owns both steps. Manual execution bypasses the
+`sync-marketplace-version` script and the release branch flow.
+
+## Release workflow (self-contained Changesets)
+
+The active pattern is a self-contained `release.yml` in this repository that
+handles versioning and publish end-to-end. Do not reintroduce legacy
+reusable-release workflow templates here.
+
+## Required repo files
+
+This repository must have:
+```
+.npmrc               # public npm registry defaults only; no GitHub Packages remap
+.changeset/config.json   # baseBranch: "main"
+@changesets/cli      # in devDependencies
+```
+
+Without `@changesets/cli` in `devDependencies`, `vp run changeset` is
+unavailable in CI.
+
+## Changeset config
+
+`.changeset/config.json` in each repo:
+- `baseBranch: "main"`.
+- `updateInternalDependencies: "patch"`.
+
+For the first scoped public npm release, the effective publish path must set
+public visibility (for example via `package.json#publishConfig.access` or an
+explicit workflow flag). Do not leave the release contract depending on a
+restricted/private default.
+
+## Marketplace specifics
+
+After publishing, CI creates a `release/v<version>` branch with `dist/`
+committed. Claude Code marketplace consumers **must** pin to
+`release/v<version>` — never to `main`, which has no `dist/`.
+
+```jsonc
+// marketplace.json consumer reference
+{ "source": { "repo": "OWNER/REPO", "ref": "release/v0.2.0" } }
+```
+
+### marketplace.json version sync (automated)
+
+`.claude-plugin/marketplace.json` must always mirror `package.json#version`.
+This is automated: the `version` npm script runs `changeset version &&
+vp run sync-marketplace-version`, so the version bump that CI commits to
+`main` already includes the updated manifest.
+
+**Never manually edit `marketplace.json#version`** — let the release script
+do it. If you see a drift (e.g. after a hotfix that bypasses the script), run:
+
+```bash
+bun scripts/sync-marketplace-version.ts
+```
+
+The drift gate in `src/build/validate-marketplace.test.ts` catches any
+desync during the regular test run.