chore(release): promote dev to main

.changeset/collections-types-cleanup.md

@@ -0,0 +1,13 @@
+---
+"@stackwright/collections": patch
+---
+
+chore(collections): remove duplicate CollectionProvider definitions
+
+`file-collection-provider.ts` now imports `CollectionProvider`, `CollectionEntry`,
+`CollectionListOptions`, and `CollectionListResult` directly from `@stackwright/types`
+rather than from the local `./types` file.
+
+`types.ts` is converted to a re-export shim so any unexpected downstream imports
+remain backward-compatible. This completes the Phase 1 cleanup from the
+types-hierarchy-refactor.

.changeset/generate-agent-docs-interfaces.md

@@ -0,0 +1,15 @@
+---
+"@stackwright/cli": patch
+---
+
+feat(cli): generate-agent-docs now emits an interface contracts table
+
+A new auto-generated section in AGENTS.md documents the TypeScript interface
+contracts defined in `@stackwright/types`:
+
+- CollectionProvider, CollectionEntry, CollectionListOptions, CollectionListResult
+- ScaffoldHookContext, ScaffoldHook, HookHandler, ScaffoldHookType
+
+The section is delimited by `<!-- stackwright:interface-table:start/end -->` markers
+and updated by `pnpm stackwright -- generate-agent-docs` alongside the existing
+content-type-table. This completes Phase 1 step 8 of the types-hierarchy-refactor.

.changeset/hookhandler-reexport.md

@@ -0,0 +1,15 @@
+---
+"@stackwright/hooks-registry": patch
+"@stackwright/scaffold-core": patch
+---
+
+fix(scaffold-core): export HookHandler type from hooks-registry and scaffold-core
+
+`HookHandler` is the canonical type alias for scaffold hook handler functions,
+defined in `@stackwright/types`. It was re-exported by `hooks-registry/src/hooks.ts`
+but not forwarded through `index.ts`, making it unavailable via the public package
+import paths.
+
+Both `@stackwright/hooks-registry` and `@stackwright/scaffold-core` now re-export
+`HookHandler` alongside the other scaffold hook types. This completes Phase 1 step 4
+of the types-hierarchy-refactor.

.github/workflows/prerelease.yml

@@ -48,7 +48,7 @@ jobs:
             git config user.name "github-actions"
             git config user.email "github-actions@github.com"
             git add .changeset/pre.json
-            git commit -m "chore: enter prerelease mode [skip ci]"
+            git commit -m "chore: enter prerelease mode"
             git push origin dev
             fi
 
@@ -66,7 +66,7 @@ jobs:
       - name: Push changes back to dev
         run: |
           git add .
-          git commit -m "chore: bump prerelease versions [skip ci]" || echo "No changes to commit"
+          git commit -m "chore: bump prerelease versions" || echo "No changes to commit"
           git push origin dev
 
       - name: Publish prereleases with tag 'alpha'

.github/workflows/release.yml

@@ -18,14 +18,12 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
-    # Use startsWith (not contains) to check ONLY the commit title for [skip ci].
-    # Squash merges embed individual commit messages in the body, and automated
-    # commits (prerelease bumps, etc.) include [skip ci] — which would incorrectly
-    # suppress the release workflow if we used contains() on the full body.
+    # startsWith guards against the release workflow re-triggering on its own
+    # version bump commit. Must stay in sync with the commit message below.
     if: >-
       ${{ github.event_name == 'workflow_dispatch' ||
         (github.event_name == 'push' &&
-         !startsWith(github.event.head_commit.message, 'chore: version packages for release [skip ci]')) }}
+         !startsWith(github.event.head_commit.message, 'chore: version packages for release')) }}
     steps:
       - name: Generate PerAsperaCI token
         id: app-token
@@ -120,7 +118,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add .
-          git commit -m "chore: version packages for release [skip ci]" || echo "No changes to commit"
+          git commit -m "chore: version packages for release" || echo "No changes to commit"
           git push origin main
 
       - name: Back-merge into dev
@@ -141,7 +139,7 @@ jobs:
           if [ ! -f ".changeset/pre.json" ]; then
             pnpm changeset pre enter alpha
             git add .changeset/pre.json
-            git commit -m "chore: re-enter prerelease mode after back-merge [skip ci]"
+            git commit -m "chore: re-enter prerelease mode after back-merge"
           fi
           # Force push is required after a rebase to rewrite dev's remote history.
           git push origin dev --force-with-lease

AGENTS.md

@@ -116,6 +116,29 @@ The YAML key is the key used inside `content_items` entries. All types inherit `
 **TypographyVariant values:** `h1` `h2` `h3` `h4` `h5` `h6` `subtitle1` `subtitle2` `body1` `body2` `caption` `button` `overline`
 <!-- stackwright:content-type-table:end -->
 
+### Interface Contracts
+
+**AGENTS: This table is auto-generated from `@stackwright/types`. Run `pnpm stackwright -- generate-agent-docs` to regenerate. Do NOT edit the content between the markers manually.**
+
+<!-- stackwright:interface-table:start -->
+All interface contracts are defined in `@stackwright/types` and re-exported from `@stackwright/collections`, `@stackwright/hooks-registry`, and `@stackwright/scaffold-core` for backward compatibility.
+
+| Interface / Type | Kind | Fields / Signature |
+|---|---|---|
+| `CollectionProvider` | interface | `list(collection, opts?)` (Promise<CollectionListResult>), `get(collection, slug)` (Promise<CollectionEntry | null>), `collections()` (Promise<string[]>) |
+| `CollectionEntry` | interface | `slug` (string), `[key: string]` (unknown) |
+| `CollectionListOptions` | interface | `limit`? (number), `offset`? (number), `sort`? (string), `filter`? (Record<string, unknown>) |
+| `CollectionListResult` | interface | `entries` (CollectionEntry[]), `total` (number) |
+| `ScaffoldHookContext` | interface | `targetDir` (string), `projectName` (string), `siteTitle` (string), `themeId` (string), `packageJson` (Record<string, unknown>), `dependencyMode` ('workspace' | 'standalone'), `codePuppyConfig`? (Record<string, unknown>), `pages`? (string[]), `install`? (boolean), `[key: string]`? (unknown) |
+| `ScaffoldHook` | interface | `type` (ScaffoldHookType), `name` (string), `handler` (HookHandler), `priority`? (number), `critical`? (boolean) |
+| `HookHandler` | type | `(context: ScaffoldHookContext)` (Promise<void> | void) |
+| `ScaffoldHookType` | type | `values` ('preScaffold' | 'preInstall' | 'postInstall' | 'postScaffold') |
+
+**Import paths (all equivalent):**
+- `CollectionProvider` — `@stackwright/types` · `@stackwright/collections`
+- `ScaffoldHookContext`, `ScaffoldHook`, `HookHandler`, `ScaffoldHookType` — `@stackwright/types` · `@stackwright/hooks-registry` · `@stackwright/scaffold-core`
+<!-- stackwright:interface-table:end -->
+
 ### Dark Mode & Color Preferences
 
 Stackwright has first-class dark mode and cookie-based preference persistence:

examples/stackwright-docs/AGENTS.md

@@ -52,6 +52,29 @@ The YAML key is the key used inside `content_items` entries. All types inherit `
 **TypographyVariant values:** `h1` `h2` `h3` `h4` `h5` `h6` `subtitle1` `subtitle2` `body1` `body2` `caption` `button` `overline`
 <!-- stackwright:content-type-table:end -->
 
+### Interface Contracts
+
+**AGENTS: This table is auto-generated from `@stackwright/types`. Run `pnpm stackwright -- generate-agent-docs` to regenerate. Do NOT edit the content between the markers manually.**
+
+<!-- stackwright:interface-table:start -->
+All interface contracts are defined in `@stackwright/types` and re-exported from `@stackwright/collections`, `@stackwright/hooks-registry`, and `@stackwright/scaffold-core` for backward compatibility.
+
+| Interface / Type | Kind | Fields / Signature |
+|---|---|---|
+| `CollectionProvider` | interface | `list(collection, opts?)` (Promise<CollectionListResult>), `get(collection, slug)` (Promise<CollectionEntry | null>), `collections()` (Promise<string[]>) |
+| `CollectionEntry` | interface | `slug` (string), `[key: string]` (unknown) |
+| `CollectionListOptions` | interface | `limit`? (number), `offset`? (number), `sort`? (string), `filter`? (Record<string, unknown>) |
+| `CollectionListResult` | interface | `entries` (CollectionEntry[]), `total` (number) |
+| `ScaffoldHookContext` | interface | `targetDir` (string), `projectName` (string), `siteTitle` (string), `themeId` (string), `packageJson` (Record<string, unknown>), `dependencyMode` ('workspace' | 'standalone'), `codePuppyConfig`? (Record<string, unknown>), `pages`? (string[]), `install`? (boolean), `[key: string]`? (unknown) |
+| `ScaffoldHook` | interface | `type` (ScaffoldHookType), `name` (string), `handler` (HookHandler), `priority`? (number), `critical`? (boolean) |
+| `HookHandler` | type | `(context: ScaffoldHookContext)` (Promise<void> | void) |
+| `ScaffoldHookType` | type | `values` ('preScaffold' | 'preInstall' | 'postInstall' | 'postScaffold') |
+
+**Import paths (all equivalent):**
+- `CollectionProvider` — `@stackwright/types` · `@stackwright/collections`
+- `ScaffoldHookContext`, `ScaffoldHook`, `HookHandler`, `ScaffoldHookType` — `@stackwright/types` · `@stackwright/hooks-registry` · `@stackwright/scaffold-core`
+<!-- stackwright:interface-table:end -->
+
 ## Development Commands
 
 ```bash

package.json

@@ -96,6 +96,7 @@
 	    "uuid": ">=14.0.0",
 	    "fast-uri": ">=3.1.2",
 	    "js-yaml": ">=4.1.1",
+	    "read-yaml-file>js-yaml": "^3",
 	    "postcss": ">=8.5.10"
         },
         "onlyBuiltDependencies": [