Release v0.3.0

.github/workflows/ci.yml

@@ -21,10 +21,6 @@ env:
   # Turborepo remote cache (Vercel)
   TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
   TURBO_TEAM: ${{ vars.TURBO_TEAM }}
-
-
-
-env:
   TURBO_REMOTE_CACHE: ${{ vars.TURBO_REMOTE_CACHE || 'false' }}
 
 jobs:

.github/workflows/prerelease.yml

@@ -36,6 +36,7 @@ jobs:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'
           cache: 'pnpm'
+          provenance: true
 
       - run: pnpm install --frozen-lockfile
       - name: Ensure Changeset prerelease mode is entered
@@ -68,4 +69,13 @@ jobs:
           git push origin dev
 
       - name: Publish prereleases with tag 'alpha'
-        run: pnpm publish -r --provenance --access public --tag alpha --no-git-checks
+        run: |
+          for dir in packages/*/; do
+            if [ -d "$dir/dist" ]; then
+              cd "$dir"
+              PKG_NAME=$(node -p "require('./package.json').name")
+              echo "Publishing $PKG_NAME..."
+              npm publish --provenance --access public --tag alpha || echo "Skipped $PKG_NAME (may already exist)"
+              cd - > /dev/null
+            fi
+          done

.github/workflows/release.yml

@@ -44,6 +44,7 @@ jobs:
           node-version: 22
           registry-url: 'https://registry.npmjs.org'
           cache: 'pnpm'
+          provenance: true
 
       - run: pnpm install --frozen-lockfile
 
@@ -89,7 +90,16 @@ jobs:
 
       - name: Publish to npm
         if: steps.check.outputs.skip != 'true'
-        run: pnpm publish -r --provenance --access public --no-git-checks
+        run: |
+          for dir in packages/*/; do
+            if [ -d "$dir/dist" ]; then
+              cd "$dir"
+              PKG_NAME=$(node -p "require('./package.json').name")
+              echo "Publishing $PKG_NAME..."
+              npm publish --provenance --access public || echo "Skipped $PKG_NAME"
+              cd - > /dev/null
+            fi
+          done
 
       # -----------------------------------------------------------
       # Push version bumps back, then sync dev

.gitignore

@@ -3,6 +3,7 @@ node_modules
 packages/**/dist
 www/
 ISSUE-*-PLAN.md
+.turbo/
 
 # Coverage reports
 coverage/

CLAUDE.md

@@ -4,9 +4,48 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Branching & Commits
 
-- **`dev`** is the integration branch; **`main`** is the release branch. Feature branches branch from `dev`, PRs target `dev`.
-- `git fetch origin dev && git checkout -b feat/issue-XX-description origin/dev`
-- Use conventional commit prefixes (`feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`). Commit early and often at logical checkpoints.
+### ⚠️ IMPORTANT: Always Target `dev`
+
+
+**ALL pull requests must target `dev` branch.** This is non-negotiable.
+
+```
+main (release) ← ← ← ← ← ← ← dev (integration)
+                  \          ↗
+                   \        /
+                    PR #XX
+```
+
+- `dev` = integration branch where all work merges
+- `main` = release branch (only updated during releases)
+- Feature branches branch FROM `dev` and PRs target `dev`
+
+### Quick Start
+
+```bash
+# ALWAYS start from dev
+git fetch origin dev && git checkout -b feat/issue-XX-description origin/dev
+
+# Or for fixes:
+git fetch origin dev && git checkout -b fix/issue-XX-description origin/dev
+```
+
+
+### Commit Messages
+
+
+Use conventional commit prefixes:
+- `feat:` — new feature
+- `fix:` — bug fix
+- `refactor:` — code restructure (no behavior change)
+- `test:` — adding/updating tests
+- `docs:` — documentation only
+- `chore:` — tooling, dependencies, config
+
+
+Include issue numbers: `feat(cli): add --watch mode (fixes #42)`
+
+Commit early and often at logical checkpoints.
 
 ## Commands
 

CONTRIBUTING.md

@@ -72,15 +72,72 @@ Don't add tests or checks speculatively. Wait for a real failure, then automate
 
 ## Branching Workflow
 
-- **`dev`** is the integration branch. Feature branches are created from `dev` and PRs target `dev`.
-- **`main`** is the release branch. `dev` is merged to `main` only when cutting a release.
+### ⚠️ ALWAYS Target `dev` Branch
 
-Always pull the latest `dev` before creating a feature branch:
+**This is the single most important rule of this repo:**
+
+```
+Feature Branch → PR to dev → Merge to main (release only)
+```
+
+| Branch | Purpose | Who Pushes To It |
+|--------|---------|------------------|
+| `dev` | Integration branch for all work | PRs from feature branches |
+| `main` | Release/stable branch | Only during formal releases |
+
+### The Rule
+
+1. **Branch FROM `dev`**: `git checkout -b feat/issue-XX origin/dev`
+2. **Target `dev` in PRs**: All pull requests target `dev`
+3. **Only merge `dev` → `main`** during a formal release
+4. **Never commit directly to `dev` or `main`**
+
+### Standard Workflow
 
 ```bash
+# 1. Start fresh from dev
 git fetch origin dev && git checkout -b feat/issue-XX-description origin/dev
+
+# 2. Make changes, commit with conventional messages
+git commit -m "feat(cli): implement --watch mode (fixes #42)"
+
+# 3. Push and create PR targeting dev
+git push -u origin feat/issue-XX-description
+gh pr create --base dev --title "feat(cli): implement --watch mode"
+
+# 4. After review, merge to dev
+# CI automatically publishes alpha prereleases from dev
+
+
+# 5. During release, merge dev to main
+# CI exits prerelease mode and publishes stable versions
 ```
 
+### What Happens On Push To `dev`?
+
+CI automatically:
+1. Runs tests and builds
+2. Bumps alpha versions (e.g., `0.1.0` → `0.1.1-alpha.0`)
+3. Publishes to npm with `alpha` tag
+4. Backs up version changes
+
+### What Happens On Push To `main`?
+
+
+CI automatically:
+1. Exits prerelease mode
+2. Publishes stable versions (e.g., `0.1.0-alpha.5` → `0.1.0`)
+3. Back-merges version bumps to `dev`
+4. Re-enters prerelease mode for next cycle
+
+### Why This Structure?
+
+
+- `dev` is always releasable (continuous delivery of alphas)
+- `main` contains only stable, tested releases
+- Changesets accumulate in `dev` until a release is cut
+- No broken states ever reach `main`
+
 ## Commit Discipline
 
 **Commit early and often at logical checkpoints.** Don't accumulate a large diff across an entire feature branch — break the work into meaningful, reviewable commits. Each commit should leave the codebase in a buildable state.

examples/stackwright-docs/package.json

@@ -26,7 +26,6 @@
     "next": "^16.1.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "stackwright-docs": "link:",
     "tailwind-merge": "^2.6.0"
   },
   "devDependencies": {