Merge remote-tracking branch 'origin/main' into better-docker

# Conflicts:
#	.github/workflows/docker.yml
#	docker/DOCKER_README.md

Author: brunobuddy

.github/workflows/docker.yml

@@ -7,14 +7,18 @@ on:
         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
+  push:
+    branches: [main]
+    paths:
+      - "docker/DOCKER_README.md"
+      - ".github/workflows/docker.yml"
   pull_request:
     branches: [main]
     paths:
       - "docker/Dockerfile"
       - ".dockerignore"
       - "docker/docker-compose.yml"
       - "docker/.env.example"
-      - "docker/DOCKER_README.md"
       - "docker/install.sh"
       - "packages/backend/**"
       - "packages/frontend/**"
@@ -115,11 +119,31 @@ jobs:
             cosign sign --yes "${tag}@${DIGEST}"
           done
 
-      - name: Sync README to Docker Hub
-        uses: peter-evans/dockerhub-description@v4
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-          repository: manifestdotbuild/manifest
-          short-description: "Smart LLM router for personal AI agents. Self-host with Docker."
-          readme-filepath: ./docker/DOCKER_README.md
+  sync-description:
+    name: Sync Docker Hub description
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Push README to Docker Hub
+        env:
+          DOCKER_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+          DOCKER_PASS: ${{ secrets.DOCKERHUB_TOKEN }}
+        run: |
+          # Pinned to immutable digest for supply-chain safety.
+          # The underlying tool is chko/docker-pushrm:1. When bumping the tag,
+          # fetch the current digest with:
+          #   TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:chko/docker-pushrm:pull" | jq -r .token)
+          #   curl -sI -H "Authorization: Bearer $TOKEN" \
+          #     -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \
+          #     https://registry-1.docker.io/v2/chko/docker-pushrm/manifests/1 | grep -i docker-content-digest
+          docker run --rm \
+            -v "$GITHUB_WORKSPACE/docker/DOCKER_README.md:/data/README.md:ro" \
+            -e DOCKER_USER \
+            -e DOCKER_PASS \
+            chko/docker-pushrm@sha256:812a950e5be7dca26cef33b61eb2076bfcfb6c2a8ec96c126371fc049c3b6608 \
+            --file /data/README.md \
+            --short "Smart LLM router for personal AI agents. Cut costs up to 70%." \
+            --debug \
+            manifestdotbuild/manifest

CLAUDE.md

@@ -506,18 +506,24 @@ Changesets are **not** required on every PR — they're optional and only meanin
 
 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.
+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. The `sync-description` job also runs in the same workflow_dispatch and pushes the latest `docker/DOCKER_README.md` to the Docker Hub repo description.
 
 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.
 
+### Docker Hub description
+
+`docker/DOCKER_README.md` is the source of truth for the Docker Hub repo description at [`manifestdotbuild/manifest`](https://hub.docker.com/r/manifestdotbuild/manifest). The `sync-description` job in `docker.yml` pushes it to Docker Hub via the [`chko/docker-pushrm`](https://github.com/christian-korneck/docker-pushrm) container image (standalone `docker run`, no third-party GitHub Action). It uses the same `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN` secrets as the publish job — the Docker Hub PAT needs write access to the repo, which the existing token already has for image pushes. Edits to `docker/DOCKER_README.md` are treated as doc-only: they do **not** trigger the PR validate job (no point rebuilding multi-arch images for content changes), and they auto-sync to Docker Hub on merge to main via a dedicated `push:` trigger with a narrow paths filter. The `chko/docker-pushrm` image is pinned to an immutable digest in the workflow — when bumping, re-fetch the digest via `docker manifest inspect chko/docker-pushrm:1` or the registry API (see the inline comment in `docker.yml`).
+
 ### 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. |
+| PR opened/updated (runtime files) | `ci.yml` runs tests, lint, typecheck, coverage. `docker.yml` validates the Docker build (no push). `changeset-check` warns softly if no changeset is present. |
+| PR opened/updated (`docker/DOCKER_README.md` only) | No Docker CI runs — content-only change, nothing to validate. |
 | 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. |
+| 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 image publish. |
+| Merge of a PR that touched `docker/DOCKER_README.md` | `docker.yml` `sync-description` job runs, pushing the new README to Docker Hub via `chko/docker-pushrm`. No image rebuild. |
+| Manual `workflow_dispatch` on `Docker` workflow | `publish` job reads `packages/manifest/package.json` and pushes a new image tag to Docker Hub. `sync-description` also runs in parallel and re-syncs the Docker Hub description. This is the **only** path that publishes image artifacts. |
 
 ## Code Coverage (Codecov)
 

docker/DOCKER_README.md

@@ -6,9 +6,9 @@
   </picture>
 </p>
 <p align="center">
-  <a href="https://github.com/mnfst/manifest/stargazers"><img src="https://img.shields.io/github/stars/mnfst/manifest?style=flat" alt="GitHub stars" /></a>
+  <a href="https://hub.docker.com/r/manifestdotbuild/manifest"><img src="https://img.shields.io/docker/pulls/manifestdotbuild/manifest?color=2496ED&label=docker%20pulls" alt="Docker pulls" /></a>
   &nbsp;
-  <a href="https://www.npmjs.com/package/manifest"><img src="https://img.shields.io/npm/v/manifest?color=cb3837&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/mnfst/manifest/stargazers"><img src="https://img.shields.io/github/stars/mnfst/manifest?style=flat" alt="GitHub stars" /></a>
   &nbsp;
   <a href="https://github.com/mnfst/manifest/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mnfst/manifest?color=blue" alt="license" /></a>
   &nbsp;
@@ -17,13 +17,14 @@
 
 ## What is Manifest?
 
-Manifest is a smart model router for personal AI agents like OpenClaw, Hermes, or anything speaking the OpenAI-compatible HTTP API. It sits between your agent and your LLM providers, scores each request, and routes it to the cheapest model that can handle it. Simple questions go to fast, cheap models. Hard problems go to expensive ones. You save money without thinking about it.
+Manifest is a smart model router for **personal AI agents** like OpenClaw, Hermes, or anything speaking the OpenAI-compatible HTTP API. It sits between your agent and your LLM providers, scores each request, and routes it to the cheapest model that can handle it. Simple questions go to fast, cheap models. Hard problems go to expensive ones. You save money without thinking about it.
 
-- Route requests to the right model: Cut costs up to 70%
-- Automatic fallbacks: If a model fails, the next one picks up
-- Set limits: Don't exceed your budget
+- Route requests to the right model: cut costs up to 70%
+- Automatic fallbacks: if a model fails, the next one picks up
+- Set limits: don't exceed your budget
+- Self-hosted: your requests, your providers, your data
 
-![manifest-gh](https://github.com/user-attachments/assets/7dd74fc2-f7d6-4558-a95a-014ed754a125)
+![manifest-gh](https://raw.githubusercontent.com/mnfst/manifest/HEAD/.github/assets/manifest-screenshot.png)
 
 ## Table of contents
 
@@ -35,14 +36,15 @@ Manifest is a smart model router for personal AI agents like OpenClaw, Hermes, o
   - [Option 3: One-command install script](#option-3-one-command-install-script)
   - [Verifying the image signature](#verifying-the-image-signature)
   - [Custom port](#custom-port)
+- [Image tags](#image-tags)
 - [Upgrading](#upgrading)
 - [Backup & persistence](#backup--persistence)
 - [Environment variables](#environment-variables)
 - [Links](#links)
 
 ## Supported providers
 
-Works with 300+ models across OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, Mistral, Qwen, MiniMax, Kimi, Z.ai, GitHub Copilot, OpenRouter, Ollama, and any provider with an OpenAI-compatible API. Reuse an existing paid subscription where supported (ChatGPT Plus/Pro, Claude Max/Pro, Copilot, MiniMax Coding Plan, GLM Coding Plan, Ollama Cloud).
+Works with 300+ models across OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, Mistral, Qwen, MiniMax, Kimi, Amazon Nova, Z.ai, OpenRouter, Ollama, and any provider with an OpenAI-compatible API. Connect with an API key, or reuse an existing paid subscription (ChatGPT Plus/Pro, Claude Max/Pro, GLM Coding Plan, etc.) where supported.
 
 ## Manifest vs OpenRouter
 
@@ -51,7 +53,7 @@ Works with 300+ models across OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, M
 | Architecture | Your Manifest instance forwards to your providers    | Cloud proxy. All traffic goes through their servers |
 | Cost         | Free                                                 | 5% fee on every API call                            |
 | Source code  | MIT, fully open                                      | Proprietary                                         |
-| Data privacy | Metadata only (Cloud), no middleman (self-hosted)    | Prompts and responses pass through a third party    |
+| Data privacy | Self-hosted — no middleman                           | Prompts and responses pass through a third party    |
 | Transparency | Open scoring. You see why a model was chosen         | No visibility into routing decisions                |
 
 ---
@@ -197,6 +199,18 @@ environment:
 
 If you see "Invalid origin" on the login page, `BETTER_AUTH_URL` doesn't match the port you're using.
 
+## Image tags
+
+Every release is published with the following tags:
+
+- `{major}.{minor}.{patch}` — fully pinned (e.g. `5.46.0`)
+- `{major}.{minor}` — latest patch within a minor (e.g. `5.46`)
+- `{major}` — latest minor+patch within a major (e.g. `5`)
+- `latest` — latest stable release
+- `sha-<short>` — exact commit for rollback
+
+Images are built for both `linux/amd64` and `linux/arm64`.
+
 ## Upgrading
 
 Manifest ships a new image on every release. To upgrade an existing compose install: