@@ -18,7 +18,7 @@ permissions: {}
 jobs:
   test:
     name: test (${{ matrix.os }}, ${{ matrix.shard }})
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ matrix.os == 'ubuntu-latest' && github.repository == 'voidzero-dev/void' && 'blacksmith-4vcpu-ubuntu-2404' || matrix.os }}
     permissions:
       contents: read
     # No Cloudflare creds in this job. The credentialed live deploy e2e runs in the separate
@@ -29,7 +29,7 @@ jobs:
       matrix:
         # Windows runs on main pushes and on PRs labeled "test: windows",
         # unless a reusable workflow caller explicitly disables it.
-        os: '${{ (((github.event_name == ''push'' && startsWith(github.ref, ''refs/heads/'')) || contains(github.event.pull_request.labels.*.name, ''test: windows'')) && !(github.event_name == ''workflow_call'' && inputs.skip_windows)) && fromJSON(''["blacksmith-4vcpu-ubuntu-2404","windows-latest"]'') || fromJSON(''["blacksmith-4vcpu-ubuntu-2404"]'') }}'
+        os: '${{ (((github.event_name == ''push'' && startsWith(github.ref, ''refs/heads/'')) || contains(github.event.pull_request.labels.*.name, ''test: windows'')) && !(github.event_name == ''workflow_call'' && inputs.skip_windows)) && fromJSON(''["ubuntu-latest","windows-latest"]'') || fromJSON(''["ubuntu-latest"]'') }}'
         # Unit tests and two integration shards run on separate runners. Each integration
         # shard builds its own checkout first, so generated playground state is never shared.
         shard: [unit, '1/2', '2/2']
@@ -70,11 +70,12 @@ jobs:
           node-version-file: .node-version
           cache: true
 
-      # Both runner images already provide Chromium's shared-library dependencies. Avoid
-      # `--with-deps` here: it runs apt on Linux and makes test startup depend on the external
-      # Ubuntu mirrors even though no OS packages are needed by these runners.
+      # The upstream Linux image and Windows already provide browser libraries.
+      # Forks use GitHub's Ubuntu image and install Chromium's system dependencies.
       - run: vp exec playwright install chromium
-        if: ${{ matrix.shard != 'unit' }}
+        if: ${{ matrix.shard != 'unit' && (runner.os != 'Linux' || github.repository == 'voidzero-dev/void') }}
+      - run: vp exec playwright install --with-deps chromium
+        if: ${{ matrix.shard != 'unit' && runner.os == 'Linux' && github.repository != 'voidzero-dev/void' }}
 
       - run: vp check
         if: ${{ matrix.shard == 'unit' }}
 
@@ -23,7 +23,7 @@ permissions: {}
 jobs:
   build-api-container:
     if: github.event_name == 'pull_request'
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: ${{ github.repository == 'voidzero-dev/void' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 10
     permissions:
       contents: read
@@ -35,7 +35,7 @@ jobs:
         run: docker build --pull --tag void-api-build-container:ci platform/packages/api/container
 
   lint-build-check:
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: ${{ github.repository == 'voidzero-dev/void' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     permissions:
       contents: read
     steps:
@@ -61,7 +61,7 @@ jobs:
       - run: vp run check:sdk
 
   test:
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: ${{ github.repository == 'voidzero-dev/void' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     permissions:
       contents: read
     strategy:
@@ -82,23 +82,27 @@ jobs:
 
   # The production guard. `platform-deploy.yml` migrates before it deploys the api worker, so a
   # push to `prod` applies a new schema while the previous release is still serving traffic. This
-  # migrates a real Postgres with the migrations under test, then runs the `prod` branch's
+  # migrates a real Postgres with the migrations under test, then runs the selected released ref's
   # integration tests against that schema: if the code that is live cannot run on the new schema,
-  # the push must not ship. Accepted limits: the baseline is the `prod` branch head rather than the
-  # deployed revision, and released migrations are assumed append-only (drizzle never re-applies an
-  # applied entry and skips entries not newer than the last applied).
+  # the push must not ship. Void Cloud defaults to `prod`; forks opt in by setting the repository
+  # variable VOID_PLATFORM_PRODUCTION_REF to their released branch, tag, or commit. The selected
+  # ref must represent the deployed version, and released migrations are assumed append-only
+  # (drizzle never re-applies an entry and skips entries not newer than the last applied).
   #
   # It has teeth on PRs, where the code under test is a different commit from the one that is
-  # live. The production deploy sets `require-schema-compat` for every trigger — including a
-  # manual dispatch, which can be started from any ref and would otherwise skip the job. Staging
-  # deploys skip it: they cannot break production, and they run on nearly every push to `main`.
+  # live. The production deploy explicitly requests `require-schema-compat`, including on
+  # manual dispatch. Fork reusable-workflow callers can request it with their own baseline.
+  # Staging deploys run source checks without the production compatibility comparison.
   schema-compat:
-    if: github.event_name == 'pull_request' || inputs.require-schema-compat
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    if: >-
+      ${{ inputs.require-schema-compat || (github.event_name == 'pull_request'
+      && (github.repository == 'voidzero-dev/void' || vars.VOID_PLATFORM_PRODUCTION_REF != '')) }}
+    runs-on: ${{ github.repository == 'voidzero-dev/void' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 20
     permissions:
       contents: read
     env:
+      PRODUCTION_REF: ${{ vars.VOID_PLATFORM_PRODUCTION_REF || 'prod' }}
       POSTGRES_USER: void_ci
       POSTGRES_PASSWORD: void_ci_pass
       POSTGRES_DB: void_schema_compat
@@ -121,6 +125,11 @@ jobs:
           --health-timeout=5s
           --health-retries=5
     steps:
+      - name: Require a production baseline for fork deployment checks
+        if: ${{ github.repository != 'voidzero-dev/void' && vars.VOID_PLATFORM_PRODUCTION_REF == '' }}
+        run: |
+          echo '::error::Set the repository variable VOID_PLATFORM_PRODUCTION_REF to the released platform ref before requesting schema compatibility checks.'
+          exit 1
       # Phase 1 — apply the migrations under test to a real Postgres.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -134,32 +143,23 @@ jobs:
         env:
           DATABASE_URL: ${{ env.COMPAT_DATABASE_URL }}
 
-      # Phase 2 — the release that is live must still run on that schema. `prod` is that release.
-      # PRs are checked against it; a push to `prod` checks itself, as in the old repository; a
-      # manual dispatch from another ref is checked against `prod`.
+      # Phase 2 — the selected released ref must still run on the migrated schema.
+      # Forks opt in with VOID_PLATFORM_PRODUCTION_REF; Void Cloud defaults to prod.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          ref: prod
+          ref: ${{ env.PRODUCTION_REF }}
           persist-credentials: false
-      - name: Does the baseline carry the platform?
-        id: production
+      - name: Require platform code in the baseline
         run: |
-          if [ -d platform/packages/api ]; then
-            echo 'usable=true' >> "$GITHUB_OUTPUT"
-          else
-            # Production still runs a pre-monorepo revision, so there is no platform code to test
-            # against: the schema is checked, the code is not. That gap closes with the first
-            # release from this repository, after which this branch stops being taken.
-            echo 'usable=false' >> "$GITHUB_OUTPUT"
-            echo '::warning::The compatibility baseline predates the platform, so the production code was not exercised against the migrated schema. This stops once prod carries the platform.'
+          if [ ! -d platform/packages/api ]; then
+            echo '::error::The selected production baseline does not contain the platform. Choose a released platform ref with VOID_PLATFORM_PRODUCTION_REF.'
+            exit 1
           fi
-      - if: steps.production.outputs.usable == 'true'
-        uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0
+      - uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0
         with:
           cache: true
           node-version-file: .node-version
       - name: Run the production ref's integration tests on the migrated schema
-        if: steps.production.outputs.usable == 'true'
         run: |
           vp run build
           vp run --filter './platform/packages/**' build
 
@@ -24,14 +24,23 @@ concurrency:
 permissions: {}
 
 jobs:
+  check-ref:
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    steps:
+      # Actions string comparisons ignore case. Check before entering Staging.
+      - name: Verify the exact staging branch
+        run: test "$GITHUB_REF" = 'refs/heads/main'
+
   ci:
-    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }}
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/main' }}
+    needs: check-ref
     uses: ./.github/workflows/platform-ci.yml
     permissions:
       contents: read
 
   deploy:
-    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }}
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/main' }}
     needs: ci
     runs-on: blacksmith-4vcpu-ubuntu-2404
     environment: Staging
@@ -55,11 +64,13 @@ jobs:
           STAGING_DATABASE_URL: ${{ secrets.STAGING_DATABASE_URL }}
 
   smoke-test:
-    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }}
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/main' }}
     needs: deploy
     uses: ./.github/workflows/platform-smoke-test.yml
     permissions:
       contents: read
+    # Pass only the smoke-test credentials. The called job resolves their values
+    # from Staging; omitting this mapping leaves them empty on reusable runs.
     secrets:
       CF_ACCESS_CLIENT_ID_STAGING: ${{ secrets.CF_ACCESS_CLIENT_ID_STAGING }}
       CF_ACCESS_CLIENT_SECRET_STAGING: ${{ secrets.CF_ACCESS_CLIENT_SECRET_STAGING }}
 
@@ -16,18 +16,27 @@ concurrency:
 permissions: {}
 
 jobs:
+  check-ref:
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/prod' }}
+    runs-on: ubuntu-latest
+    steps:
+      # Actions string comparisons ignore case. Check before entering Prod.
+      - name: Verify the exact production branch
+        run: test "$GITHUB_REF" = 'refs/heads/prod'
+
   ci:
-    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }}
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/prod' }}
+    needs: check-ref
     uses: ./.github/workflows/platform-ci.yml
     with:
-      # Every production trigger runs the schema-compatibility guard, whichever ref the
-      # dispatch came from.
+      # Automatic and manual production runs use the prod ref and must pass
+      # the schema-compatibility guard.
       require-schema-compat: true
     permissions:
       contents: read
 
   deploy:
-    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }}
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/prod' }}
     needs: ci
     runs-on: blacksmith-4vcpu-ubuntu-2404
     environment: Prod
 
@@ -16,14 +16,37 @@ on:
 permissions: {}
 
 jobs:
+  check-ref:
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    steps:
+      # Reusable runs use the caller's ref. Reject case variants before secrets.
+      - name: Verify the exact smoke-test branch
+        run: test "$GITHUB_REF" = 'refs/heads/main'
+
   smoke-test:
-    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }}
+    if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' && github.ref == 'refs/heads/main' }}
+    needs: check-ref
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    # Configure all three credentials in Staging. Reusable callers must declare
+    # these secret names explicitly for GitHub to resolve the environment values.
     environment: Staging
     timeout-minutes: 15
     permissions:
       contents: read
     steps:
+      - name: Verify staging smoke-test credentials
+        env:
+          CF_ACCESS_CLIENT_ID_STAGING: ${{ secrets.CF_ACCESS_CLIENT_ID_STAGING }}
+          CF_ACCESS_CLIENT_SECRET_STAGING: ${{ secrets.CF_ACCESS_CLIENT_SECRET_STAGING }}
+          VOID_TOKEN_STAGING: ${{ secrets.VOID_TOKEN_STAGING }}
+        run: |
+          for name in CF_ACCESS_CLIENT_ID_STAGING CF_ACCESS_CLIENT_SECRET_STAGING VOID_TOKEN_STAGING; do
+            if [[ -z "${!name}" ]]; then
+              echo "::error::Missing $name. Configure it in the Staging environment."
+              exit 1
+            fi
+          done
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -24,7 +24,7 @@ The `void` package on npm has these previous versions: '0.0.1', '0.1.0', '0.1.2'
     - Run `vp test run` on tests relevant to the current feature only during feature development. Only run the full test suite when everything is done for final verification.
     - If there are tests hanging or running particularly slow, investigate right there and attempt to fix. Testing velocity is something that should be maintained or improved at every opportunity.
   - Documentation: after verification, update all docs if relevant and applicable:
-    - `README.md` (this file)
+    - `README.md`
     - affected packages's `README.md` or `AGENTS.md`
     - relevant docs md files in `docs`
     - `packages/void/skills/void` (if change affects skill/CLI guidance)
@@ -40,7 +40,7 @@ The `void` package on npm has these previous versions: '0.0.1', '0.1.0', '0.1.2'
 ```
 vp run build                        # Build all packages
 vp run build:all                    # Build packages and playgrounds
-vp run build:core                   # Build only the core plugin
+vp run build:core                   # Build shared packages, CLI, and platform runtime
 vp test run                         # Run tests (unit + integration tests)
 vpr test:all                        # Format, lint, build, typecheck, and run all SDK/platform tests
 vp test run packages/void           # Only test the core plugin
@@ -60,15 +60,18 @@ pnpm workspaces managed through Vite+. Shared dependency versions use the **pnpm
 | [`packages/deploy-cloudflare`](./packages/deploy-cloudflare) | `@void/deploy-cloudflare` | Direct Cloudflare config and verified upload primitives           |
 | [`packages/edge`](./packages/edge)                           | `@void/edge`              | Shared routing, headers, and static edge runtime                  |
 | [`packages/isr`](./packages/isr)                             | `@void/isr`               | Shared ISR protocol, core logic, and direct runtime               |
+| [`packages/platform`](./packages/platform/README.md)         | `@void/platform`          | Self-hosted installation contracts and packaged platform runtime  |
 | [`packages/void`](./packages/void/AGENTS.md)                 | `void`                    | Core Vite plugin — routing, inference, migrations, CLI            |
 | [`packages/react`](./packages/react/README.md)               | `@void/react`             | React framework adapter for Pages mode (SSR, Link, useForm)       |
 | [`packages/vue`](./packages/vue/README.md)                   | `@void/vue`               | Vue framework adapter for Pages mode (SSR, Link, useForm)         |
 | [`packages/svelte`](./packages/svelte/README.md)             | `@void/svelte`            | Svelte 5 framework adapter for Pages mode (SSR, Link, useForm)    |
 | [`packages/solid`](./packages/solid/README.md)               | `@void/solid`             | SolidJS framework adapter for Pages mode (SSR, Link, useForm)     |
 | [`docs`](./docs)                                             | (private)                 | Documentation site (VitePress)                                    |
-| [`platform`](./platform/README.md)                           | (private)                 | Hosted control plane, routing, proxy, logs, and dashboard         |
+| [`platform`](./platform/README.md)                           | (private)                 | Self-hosted platform source, routing, proxy, logs, and dashboard  |
 | `playground/*`                                               | (private)                 | local apps for testing                                            |
 
+The platform source is part of this repository. Its workspace-only packages keep `private: true` to prevent accidental npm publication; this does not mean the platform source is private. Use `docs/guide/platform-development.md` for contributor/fork setup and `docs/guide/self-hosted-platform.md` for installation.
+
 Platform packages live under `platform/packages/*` and may depend on public/shared root packages. Public SDK packages under `packages/*` must not import from `platform/`.
 
 ## `void` Overview
@@ -92,14 +95,15 @@ The `void` package contains two parts:
 
 **CLI (`void`)** — commands for local development DX and deployment:
 
-- **`deploy`** — builds, validates migrations, packages, and uploads to Void
+- **`deploy`** — builds, validates migrations, and deploys to the configured Cloudflare or Void target
+- **`platform`** — installs, maintains, and administers a self-hosted Void platform
 - **`gen`** — scaffolds models, routes, middleware, SSR entries, cron jobs, and queue consumers
 - **`init`** — sets up agent instructions, skills, and reference prompts for coding agents
 - **`db`** — manages migrations and inspects the local D1 database
 - **`auth`** — login, logout, and token management
-- **`projects`** — link, create, and manage Void projects
-- **`domains`** — configure custom domains for deployed projects
-- **`secrets`** — manage production environment variables
+- **`project`** — link, create, and manage Void projects
+- **`domain`** — configure custom domains for deployed projects
+- **`secret`** — manage production environment variables
 
 See [`packages/void/AGENTS.md`](./packages/void/AGENTS.md) for architecture, source layout, design decisions, package exports, route parsing rules, code generation, and agent integration.
 
 
@@ -8,6 +8,10 @@ If you run a team platform, `void platform` also lets you give people access,
 manage their projects, and investigate deployments from the terminal. Start with
 [Platform Administration](./docs/guide/platform-administration.md).
 
+The platform implementation is included in this repository. To change it or
+deploy a runtime from your own fork, follow
+[Platform Development](./docs/guide/platform-development.md).
+
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite';
@@ -40,6 +44,8 @@ pnpm void deploy     # deploy to the saved Cloudflare or Void target
 
 ## Adding Void to an Existing Project
 
+Already deploy the same Void app directly to Cloudflare? Run `void deploy`. If your project has a `wrangler.jsonc` or `wrangler.json` and no deployment destination, Void offers to link and deploy using the existing Worker and resources. Accept once, then use `void deploy` for future deployments. See [Deploy an existing Worker](./docs/integrations/cloudflare.md#deploy-an-existing-worker).
+
 1. Install Void:
 
 ```sh
 
@@ -240,6 +240,7 @@ export default extendConfig(
               { text: 'Deployment', link: '/guide/deployment' },
               { text: 'Self-hosted Platform', link: '/guide/self-hosted-platform' },
               { text: 'Platform Administration', link: '/guide/platform-administration' },
+              { text: 'Platform Development', link: '/guide/platform-development' },
             ],
           },
         ],