Merge pull request #1541 from mnfst/chore/manifest-synthetic-package

chore: introduce packages/manifest as canonical release version

Author: brunobuddy

.changeset/config.json

@@ -7,5 +7,5 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": []
+  "ignore": ["manifest-backend", "manifest-frontend", "manifest-shared"]
 }

.github/workflows/docker.yml

@@ -4,8 +4,8 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Version to publish (e.g. 5.38.1)"
-        required: true
+        description: "Optional version override (e.g. 5.38.1). Leave blank to use the current version from packages/manifest/package.json."
+        required: false
         type: string
   pull_request:
     branches: [main]
@@ -55,6 +55,18 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Resolve version
+        id: version
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            VERSION="${{ inputs.version }}"
+            echo "Using version from workflow input: $VERSION"
+          else
+            VERSION=$(jq -r .version packages/manifest/package.json)
+            echo "Using version from packages/manifest/package.json: $VERSION"
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
       - uses: docker/setup-qemu-action@v3
 
       - uses: docker/setup-buildx-action@v3
@@ -69,9 +81,9 @@ jobs:
         with:
           images: manifestdotbuild/manifest
           tags: |
-            type=semver,pattern={{version}},value=${{ inputs.version }}
-            type=semver,pattern={{major}}.{{minor}},value=${{ inputs.version }}
-            type=semver,pattern={{major}},value=${{ inputs.version }}
+            type=semver,pattern={{version}},value=${{ steps.version.outputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ steps.version.outputs.version }}
+            type=semver,pattern={{major}},value=${{ steps.version.outputs.version }}
             type=sha
 
       - uses: docker/build-push-action@v6

CLAUDE.md

@@ -481,13 +481,43 @@ All pricing comes from a single source:
 
 ## Releases
 
-There are **no publishable npm packages** in this repo anymore. `packages/backend`, `packages/frontend`, and `packages/shared` are all `private: true`. Manifest ships exclusively as the Docker image at `manifestdotbuild/manifest` (built from `docker/Dockerfile`).
+There are **no publishable npm packages** in this repo. `packages/backend`, `packages/frontend`, `packages/shared`, and `packages/manifest` are all `private: true`. Manifest ships exclusively as the Docker image at `manifestdotbuild/manifest` (built from `docker/Dockerfile`).
 
-Changesets are still installed and wired into the release workflow for internal `CHANGELOG.md` bookkeeping on private packages — they are **not** required on every PR. Use `npx changeset add --empty` if you want to record a changelog entry for a private-package change, otherwise skip it.
+### `packages/manifest/` is the canonical version
 
-The Docker image is built and published via `.github/workflows/docker.yml`:
-- **PR**: validates the Docker build on changes to `docker/`, `.dockerignore`, `packages/backend/`, `packages/frontend/`, `packages/shared/`, or root `package.json`/`turbo.json`.
-- **Manual publish**: `workflow_dispatch` with a `version` input, run by a maintainer when a new image tag should be pushed.
+`packages/manifest/` is a **code-free shell package** that exists only to hold the canonical "Manifest version". It has no `src/`, no tests, no dependencies — just `package.json`, `README.md`, and (after the first release) a `CHANGELOG.md`. The real backend and frontend live under `packages/backend/` and `packages/frontend/` as before.
+
+`.changeset/config.json` has `"ignore": ["manifest-backend", "manifest-frontend", "manifest-shared"]`, so when a contributor runs `npx changeset`, **only `manifest` is a selectable target**. Bumps to `manifest-backend` / `manifest-frontend` / `manifest-shared` are silently discarded. Always target `manifest` regardless of which files you actually changed.
+
+### Adding a changeset
+
+```bash
+npx changeset
+# → select "manifest"
+# → choose patch / minor / major
+# → write a one-line summary (this becomes the CHANGELOG entry)
+```
+
+Commit the generated `.changeset/*.md` file alongside your code. On merge to `main`, `release.yml` runs `changesets/action`, which opens (or updates) a `chore: version packages` PR bumping `packages/manifest/package.json` and appending to `packages/manifest/CHANGELOG.md`.
+
+Changesets are **not** required on every PR — they're optional and only meaningful for changes you want in the changelog. Use `npx changeset add --empty` for purely internal work if you want an explicit "no release" marker.
+
+### Cutting a Docker release
+
+1. Merge the pending `chore: version packages` PR to land the version bump in `packages/manifest/package.json`.
+2. Go to **GitHub Actions → Docker → Run workflow**, leave the `version` input blank, click Run.
+3. The `publish` job reads `packages/manifest/package.json`, resolves the version automatically, and pushes `manifestdotbuild/manifest:{version}` + `{major}.{minor}` + `{major}` + `sha-<short>` to Docker Hub. The image is multi-arch (amd64 + arm64) and cosign-signed.
+
+To retag an older commit or publish a hotfix version that doesn't match the current `package.json`, pass a semver string in the `version` input and it overrides the package.json lookup.
+
+### Summary of what CI does on each trigger
+
+| Trigger | What happens |
+|---------|--------------|
+| PR opened/updated | `ci.yml` runs tests, lint, typecheck, coverage. `docker.yml` validates the Docker build (no push) if the PR touches runtime files. `changeset-check` warns softly if no changeset is present. |
+| Merge to `main` | `release.yml` runs `changesets/action` to open or update the `chore: version packages` PR. **No auto-publish** — neither npm nor Docker. |
+| Merge of `chore: version packages` PR | `release.yml` runs again. Version bump in `packages/manifest/package.json` and the CHANGELOG update land on `main`. Still no publish. |
+| Manual `workflow_dispatch` on `Docker` workflow | Reads `packages/manifest/package.json` and pushes a new image tag to Docker Hub. This is the **only** path that publishes anything. |
 
 ## Code Coverage (Codecov)
 

CONTRIBUTING.md

@@ -150,7 +150,20 @@ The backend runs standalone and OpenClaw talks to it as a regular OpenAI-compati
 1. Create a branch from `main` for your change
 2. Make your changes in the relevant package(s)
 3. Write or update tests as needed
-4. Run the test suite to make sure everything passes:
+4. Add a changeset if your change should appear in the release notes:
+
+```bash
+npx changeset
+# → select "manifest"
+# → choose patch / minor / major
+# → write a one-line summary
+```
+
+Always target `manifest` — it's the canonical release version for the whole project, and it's the only package changesets will accept. `manifest-backend`, `manifest-frontend`, and `manifest-shared` are ignored regardless of what you pick. Commit the generated `.changeset/*.md` alongside your code. Changesets are optional for internal/tooling changes; skip this step if the change doesn't need a CHANGELOG entry.
+
+See [`packages/manifest/README.md`](packages/manifest/README.md) for why this package exists.
+
+5. Run the test suite to make sure everything passes:
 
 ```bash
 npm test --workspace=packages/shared
@@ -159,13 +172,23 @@ npm run test:e2e --workspace=packages/backend
 npm test --workspace=packages/frontend
 ```
 
-5. Verify the production build works:
+6. Verify the production build works:
 
 ```bash
 npm run build
 ```
 
-6. Open a pull request against `main`
+7. Open a pull request against `main`
+
+### Cutting a Docker release
+
+Manifest ships as the Docker image at [`manifestdotbuild/manifest`](https://hub.docker.com/r/manifestdotbuild/manifest). Releases are manual:
+
+1. After merging PRs with changesets, a `chore: version packages` PR will be open on `main` — merge it to land the version bump in `packages/manifest/package.json` and update `packages/manifest/CHANGELOG.md`.
+2. Go to **GitHub Actions → Docker → Run workflow**, leave the `version` input blank, click Run.
+3. The workflow reads the version from `packages/manifest/package.json` and pushes `manifestdotbuild/manifest:{version}` (plus `{major}.{minor}`, `{major}`, and a `sha-<short>` rollback tag).
+
+If you need to retag an older commit or publish a version that doesn't match the current `package.json`, pass a semver string in the `version` input and it overrides the auto-detected value.
 
 ### Commit Messages
 

package-lock.json

@@ -29,7 +29,8 @@
   "workspaces": [
     "packages/shared",
     "packages/frontend",
-    "packages/backend"
+    "packages/backend",
+    "packages/manifest"
   ],
   "scripts": {
     "dev": "turbo dev",

package.json

@@ -0,0 +1,22 @@
+# manifest
+
+This package exists to hold the canonical **Manifest release version**.
+
+It contains no code. The real backend and frontend live in [`../backend`](../backend) and [`../frontend`](../frontend), and shared types in [`../shared`](../shared). The Docker image at [`manifestdotbuild/manifest`](https://hub.docker.com/r/manifestdotbuild/manifest) bundles the built backend + frontend.
+
+## What it's for
+
+- **Changesets target**: `.changeset/config.json` ignores `manifest-backend`, `manifest-frontend`, and `manifest-shared`, so when contributors run `npx changeset` the only selectable package is this one. Always target `manifest` regardless of which files you actually changed — this is the single source of truth for "the version of Manifest as a whole".
+- **Docker release version**: `.github/workflows/docker.yml` reads the `version` field from this package's `package.json` via `jq` and uses it to tag the image (`manifestdotbuild/manifest:{version}` + derived `{major}.{minor}` / `{major}` / `sha-<short>` tags).
+- **Changelog**: `CHANGELOG.md` here (auto-generated by changesets) is the unified Manifest release history.
+
+## Adding a changeset
+
+```bash
+npx changeset
+# → select "manifest"
+# → choose patch / minor / major
+# → write a one-line summary
+```
+
+Commit the generated file. On merge to `main`, the release workflow opens a `chore: version packages` PR bumping `version` and appending to `CHANGELOG.md`. Merge that PR to land the version bump, then manually run the Docker workflow (`Actions → Docker → Run workflow` with a blank input) to publish.

packages/manifest/README.md

@@ -0,0 +1,6 @@
+{
+  "name": "manifest",
+  "version": "5.46.0",
+  "private": true,
+  "description": "Canonical release version for the Manifest Docker image. This package holds no code — the real backend and frontend live in ../backend and ../frontend. See README.md for details."
+}