Promote v1.0.0 to production

.agents/skills/changeset-release-pr/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: changeset-release-pr
-description: 'Prepare the next Roomote release PR: review what merged to develop, fill missing release notes, ensure meaningful user-facing features are documented, confirm patch/minor/major when unspecified, run the product version script, and open the final release PR. Use when asked to prep, cut, or write notes for a release.'
+description: 'Prepare Roomote releases: cut the normal release PR from develop, or ship an urgent patch directly from latest main and synchronize its version back to develop. Use when asked to prep, cut, hotfix, or write notes for a release.'
 ---
 
 # Changeset Release PR
 
-Use this skill to prepare the single release PR that cuts the next Roomote
-version. The deliverable is a normal PR against `develop` containing the root
-version bump, final `CHANGELOG.md` entry, any public documentation updates needed
-for the release's meaningful user-facing features, and deletion of every
+By default, use this skill to prepare the single release PR that cuts the next
+Roomote version. The deliverable is a normal PR against `develop` containing the
+root version bump, final `CHANGELOG.md` entry, any public documentation updates
+needed for the release's meaningful user-facing features, and deletion of every
 consumed pending changeset. Merging it makes CI open the frozen Promote PR to
-`main`.
+`main`. For an urgent patch that cannot wait for that path, use the clearly
+separated direct-to-main hotfix workflow below.
 
 ## How releases work here
 
@@ -271,6 +272,178 @@ Commit the generated release artifacts on a feature branch and open a PR against
 - a note that squash-merging the PR cuts the release and automatically opens
   the frozen **Promote vX.Y.Z to production** PR against `main`
 
+## Emergency direct-to-main hotfix path
+
+Use this path only for an urgent production patch that cannot wait for the
+normal `develop` release flow above. The normal workflow remains the default.
+This exception produces two PRs:
+
+1. a complete patch and generated release artifacts targeting `main`
+2. a companion PR targeting `develop` that changes only root `package.json` and
+   `CHANGELOG.md`
+
+The production PR must merge first. Do not merge the companion until the tag,
+images, and GitHub Release have all shipped successfully.
+
+### A. Establish the release state
+
+Fetch both branches and tags, then branch from the exact latest `main` tip:
+
+```bash
+git fetch --tags origin \
+  refs/heads/main:refs/remotes/origin/main \
+  refs/heads/develop:refs/remotes/origin/develop
+git switch --create hotfix/<concise-name> origin/main
+git tag --sort=-version:refname | head -5
+node -p "require('./package.json').version"
+head -20 CHANGELOG.md
+```
+
+Before continuing, verify:
+
+- `HEAD` is exactly `origin/main`.
+- The newest shipped `vX.Y.Z` tag, root version, and top changelog section agree.
+- `main` has no pending non-README changeset that `pnpm run version` would
+  accidentally consume with the hotfix.
+- No newer unshipped Promote PR or release candidate conflicts with the patch
+  version. Resolve release ordering rather than guessing.
+- The fix is a patch and every required prerequisite is already on `main` or is
+  explicitly included because it is safe to ship with the fix.
+- The patch preserves the schema N-1 rollback guarantee and does not require an
+  incompatible migration, destructive schema change, or coordinated rollout
+  that makes direct release unsafe.
+
+### B. Apply the complete fix
+
+Identify the exact merged fix on `develop`, including tests, docs, and required
+supporting changes. Read its source PR and compare its merge commit to `main`;
+do not copy only the most obvious runtime file. Cherry-pick the smallest complete
+commit set, usually the squash commit:
+
+```bash
+git cherry-pick <develop-fix-sha>
+git diff --stat origin/main...HEAD
+git diff --name-status origin/main...HEAD
+git diff <develop-fix-sha>^..<develop-fix-sha> -- <expected-fix-paths>
+git diff origin/main...HEAD -- <expected-fix-paths>
+```
+
+Account for every intentional difference caused by prerequisites or conflict
+resolution. Exclude unrelated features, pending `develop` changesets, and
+release artifacts from another version.
+
+When the fix depends on an external service or production-like integration,
+repeat the smallest safe live check that proves the original symptom is fixed.
+Record the environment and observable result without exposing secrets or private
+data. If a live check is irrelevant or unavailable, say why and rely on focused
+deterministic tests.
+
+### C. Generate and validate the patch release
+
+Add one hotfix-specific patch changeset using the same format as step 8. Commit
+the complete fix and changeset separately when useful for auditability, then
+consume the changeset through the repository-owned command:
+
+```bash
+pnpm run version
+```
+
+Never run `changeset version`, and never hand-edit the generated version or
+changelog heading. Polish the generated top changelog summary and highlights as
+described in step 9, then commit root `package.json` and `CHANGELOG.md` as the
+version commit.
+
+Verify that:
+
+- the root version is exactly one patch above the shipped `main` version
+- the top `CHANGELOG.md` section contains the complete hotfix note
+- the hotfix changeset was consumed and no non-README `.changeset/*.md` remains
+- no workspace package version changed
+- `origin/main...HEAD` contains only the complete fix plus root `package.json`
+  and `CHANGELOG.md`
+
+Preserve the changeset commit in branch history even though the version commit
+deletes its file. Run the release scripts, focused product tests and typechecks,
+formatting check, and full pre-push gate:
+
+```bash
+pnpm test:release-scripts
+pnpm exec oxfmt --check .
+node scripts/pre-push-checks.mjs
+```
+
+Repeat any relevant live check after final conflict resolution or release edits.
+Failed or unavailable checks are release blockers unless a maintainer explicitly
+accepts and records the risk.
+
+### D. Open the production hotfix PR
+
+Open the hotfix PR against `main`. Include the source fix PR/commit and
+prerequisites, previous and next versions, exact patch scope and intentional
+differences, all validation and live-check results, rollback instructions, and a
+link to the companion PR once available. Require a **merge commit**; never squash
+or rebase this PR.
+
+Rollback guidance must distinguish two states:
+
+- Before the tag is consumed externally, revert the hotfix merge commit if that
+  is still operationally safe.
+- After publication, redeploy the previous immutable `vX.Y.Z`; never move,
+  delete, or reuse a published tag. Describe data or schema cleanup separately
+  and preserve the N-1 rollback contract.
+
+### E. Prepare the companion develop sync
+
+After the production branch is final, create a branch from latest
+`origin/develop` and bring over only the generated product version and changelog:
+
+```bash
+git switch --create chore/sync-<version>-on-develop origin/develop
+git restore --source <hotfix-tip> -- package.json CHANGELOG.md
+git diff --name-only origin/develop
+git diff --exit-code <hotfix-tip> -- package.json CHANGELOG.md
+git diff --exit-code origin/develop -- .changeset
+```
+
+Do not cherry-pick the runtime fix; it should already be on `develop`. Do not run
+`pnpm run version` on this branch because that would consume unrelated pending
+`develop` changesets. The first diff must list exactly `package.json` and
+`CHANGELOG.md`; the other two must be empty. If `develop` independently changed
+either release artifact, reconcile deliberately without touching pending
+changesets and stop if the companion cannot remain a truthful two-file sync.
+
+Open the companion PR against `develop`. It must be squash-merged only after all
+production gates below succeed. Merging it early can make
+`.github/workflows/release.yml` freeze the moving `develop` tip as
+`release/vX.Y.Z` and open an incorrect Promote PR.
+
+### F. Enforce merge and release order
+
+Do not collapse or reorder these gates:
+
+1. Merge the production hotfix PR into `main` with a merge commit.
+2. Wait for **Tag Product Release** to succeed for that `main` merge.
+3. Verify the remote annotated tag exists and resolves to the released tree with
+   `git ls-remote --tags origin refs/tags/vX.Y.Z` and, after fetching,
+   `git rev-parse 'vX.Y.Z^{}'`.
+4. Wait for the tag-triggered **Publish GHCR Images** workflow to succeed,
+   including image publication and GitHub Release creation. Verify the GitHub
+   Release and immutable image tags; tag creation alone is not completion.
+5. Only then squash-merge the companion PR into `develop`.
+
+After the tag exists, the `develop` Release workflow sees an already shipped
+version and exits without creating a candidate. If a production gate fails,
+leave the companion open while the release is repaired or rolled back.
+
+PRs [#1840](https://github.com/RooCodeInc/Roomote/pull/1840) and
+[#1841](https://github.com/RooCodeInc/Roomote/pull/1841) demonstrate this
+two-branch workflow. Their Notion-specific live checks are an optional example,
+not a requirement for unrelated hotfixes.
+
+End the hotfix path by reporting both PR URLs, released version, source fix and
+prerequisite commits, exact file scope, live-check result or reason omitted,
+validation results, current merge-order gate, and rollback risks.
+
 ## Guardrails
 
 - Never edit `CHANGELOG.md` or the root version by hand; generate both with

.docker/app/Dockerfile

@@ -113,16 +113,16 @@
 ENV S3_ENDPOINT=http://minio:9000
 ENV S3_PRESIGN_ENDPOINT=http://minio:9000
 ENV S3_REGION=us-east-1
 ENV S3_ACCESS_KEY_ID=roomote
 ENV S3_SECRET_ACCESS_KEY=roomote-local-artifacts-password
 ENV S3_BUCKET_ARTIFACTS=roomote-artifacts
 ENV JOB_AUTH_PRIVATE_KEY=local-self-host-build-job-auth-private-key
 ENV JOB_AUTH_PUBLIC_KEY=local-self-host-build-job-auth-public-key
 ENV PREVIEW_AUTH_PRIVATE_KEY=local-self-host-build-preview-auth-private-key
 ENV PREVIEW_AUTH_PUBLIC_KEY=local-self-host-build-preview-auth-public-key
 ENV DASHBOARD_PASSWORD=roomote-local-admin
 ENV ENCRYPTION_KEY=local-roomote-encryption-key-0001
 ENV ARTIFACT_SIGNING_KEY=local-roomote-artifact-signing-key-1
 ENV PREVIEW_PROXY_BASE_URL=http://localhost:18081
 ENV PREVIEW_DOMAINS=localhost,127.0.0.1,roomotepreview.localhost
 
@@ -378,6 +378,7 @@
 COPY --chown=roomote-app:roomote-app --from=build-web /roomote/apps/web/.next/standalone ./
 COPY --chown=roomote-app:roomote-app --from=build-web /roomote/apps/web/.next/static ./apps/web/.next/static/
 COPY --chown=roomote-app:roomote-app --from=build-web /roomote/apps/web/public ./apps/web/public/
+COPY --chown=roomote-app:roomote-app CHANGELOG.md ./CHANGELOG.md
 # The web server (cwd /roomote/apps/web) reads setup-flow docs from
 # ../docs at request time, so the MDX sources must ship in the image.
 COPY --chown=roomote-app:roomote-app --from=build-web /roomote/apps/docs ./apps/docs/

.docker/gbrain/entrypoint.sh

@@ -175,13 +175,26 @@ elif [ -n "${OPENAI_API_KEY:-}" ]; then
   DEFAULT_CHAT_MODEL="openai:gpt-5.6-luna"
 else
   # No credential: the server still boots and serves, it just cannot embed or
-  # synthesize. Roomote gates every Brain code path on the same keys, so it
+  # synthesize. Roomote gates every Brain code path on the same signal, so it
   # will not talk to this container either.
   BRAIN_PROVIDER="none"
   DEFAULT_EMBEDDING_MODEL=""
   DEFAULT_CHAT_MODEL=""
 fi
 
+# Gateway mode holds no real provider key, so chat defaults to the
+# `roomote/helper` sentinel: the Roomote gateway answers it with the
+# deployment's helper model instead of forwarding to a provider, which is what
+# frees synthesis from needing a Brain provider key. Convergence rule: the
+# chat model is a plain env export re-derived on every boot (env wins over
+# anything the brain stored at init), so a brain that previously defaulted to
+# gpt-5.6-luna picks this up on its next boot — while an operator's explicit
+# GBRAIN_MODEL (below) or R_BRAIN_MODEL (applied by the gateway per request)
+# still wins over the default.
+if [ -n "${OPENAI_BASE_URL:-}" ] && [ "$BRAIN_PROVIDER" != "none" ]; then
+  DEFAULT_CHAT_MODEL="${BRAIN_PROVIDER}:roomote/helper"
+fi
+
 # An operator-chosen embedding model arrives as a bare id (text-embedding-3-large)
 # because it is written once and must survive a provider switch; gbrain wants
 # it provider-qualified. Qualify it with whichever provider this container
@@ -280,35 +293,14 @@ gbrain config set dream.synthesize.link_manifest true >/dev/null
 gbrain config set agent.use_gateway_loop true >/dev/null
 echo "[gbrain-entrypoint] corpus checkout: $BRAIN_DIR (filesystem + Postgres index)"
 
-# Route gbrain's OpenRouter reranker through the same Roomote credential
-# gateway as embeddings and chat. Do this after initialization so exposing an
-# OpenRouter-compatible endpoint does not change which provider gbrain chooses
-# when it creates the Brain. An empty forwarded setting restores the default,
-# including after a deployment previously selected another reranker.
-GBRAIN_RERANKER_MODEL="${GBRAIN_RERANKER_MODEL:-openrouter:voyageai/rerank-2.5-lite}"
-case "$GBRAIN_RERANKER_MODEL" in
-  openrouter:*)
-    if [ -z "${OPENROUTER_BASE_URL:-}" ] && [ -n "${OPENAI_BASE_URL:-}" ]; then
-      OPENROUTER_BASE_URL="${OPENAI_BASE_URL%/}"
-      case "$OPENROUTER_BASE_URL" in
-        */v1) ;;
-        *) OPENROUTER_BASE_URL="$OPENROUTER_BASE_URL/v1" ;;
-      esac
-      export OPENROUTER_BASE_URL
-    fi
-    if [ -z "${OPENROUTER_API_KEY:-}" ] && [ -n "${OPENAI_API_KEY:-}" ]; then
-      OPENROUTER_API_KEY="$OPENAI_API_KEY"
-      export OPENROUTER_API_KEY
-    fi
-    if [ -z "${OPENROUTER_BASE_URL:-}" ] || [ -z "${OPENROUTER_API_KEY:-}" ]; then
-      echo "[gbrain-entrypoint] WARNING: $GBRAIN_RERANKER_MODEL needs OPENROUTER_BASE_URL and OPENROUTER_API_KEY."
-      echo "[gbrain-entrypoint] WARNING: reranking will remain fail-open until the gateway is configured."
-    fi
-    ;;
-esac
-
-gbrain config set search.reranker.model "$GBRAIN_RERANKER_MODEL" >/dev/null
-echo "[gbrain-entrypoint] reranker: $GBRAIN_RERANKER_MODEL"
+# The Brain does not use a reranker. gbrain's own init already writes
+# `search.reranker.enabled false` for installs keyed the way ours are, but
+# make the choice explicit so every brain — including ones created before
+# this line and ones hit by upstream mode-bundle default flips — converges
+# on the same shipped behavior. Retrieval is hybrid RRF; autocut no-ops
+# without rerank scores by design.
+gbrain config set search.reranker.enabled false >/dev/null
+echo "[gbrain-entrypoint] reranker: disabled"
 
 # Adding a key to a brain created without one is a first-class flow rather
 # than an edge case: on hosts whose compose parser ignores `profiles` the

.env.production.example

@@ -142,21 +142,19 @@ DEFAULT_COMPUTE_PROVIDER=docker
 # R_GITHUB_APP_SLUG=
 # Optional comma-separated GitHub App slugs that are also trusted as Roomote-managed.
 # R_GITHUB_ADDITIONAL_APP_SLUGS=
-# Self-run Brain inference (embeddings/rerank stay on your hardware; chat
+# Self-run Brain embeddings (embeddings stay on your hardware; chat
 # synthesis keeps using the configured provider). With the bundled service,
 # set COMPOSE_PROFILES=brain,local-inference and ALL of the settings below —
-# the model names and dimensions must match what the inference server
+# the model name and dimensions must match what the inference server
 # serves, and the embedding pair is create-time: set everything BEFORE the
 # Brain's first boot. gbrain's defaults (text-embedding-3-small, 1536) name
-# models the bundled server does not serve, so the URLs alone are not a
+# models the bundled server does not serve, so the URL alone is not a
 # working configuration. Self-run model names pass through unchanged and
 # must exactly match the ids served by the upstream.
 # R_BRAIN_EMBEDDINGS_UPSTREAM_URL=http://infinity:7997
-# R_BRAIN_RERANK_UPSTREAM_URL=http://infinity:7997
 # R_BRAIN_INFERENCE_UPSTREAM_API_KEY=
 # R_BRAIN_EMBEDDING_MODEL=BAAI/bge-m3
 # R_BRAIN_EMBEDDING_DIMENSIONS=1024
-# R_BRAIN_RERANKER_MODEL=BAAI/bge-reranker-v2-m3
 # R_GITHUB_APP_ID=
 # Raw GitHub App private-key PEM with newlines escaped as \n; do not base64 it.
 # R_GITHUB_APP_PRIVATE_KEY=

.github/workflows/release.yml

@@ -116,6 +116,7 @@ jobs:
             fi
 
             release_sha="$(git rev-parse HEAD)"
+            shipping_guard_sha="$candidate_sha"
             git push origin "${release_sha}:refs/heads/${release_branch}"
             candidate_status="Candidate refreshed to \`${release_sha}\` from \`develop\`."
             echo "Refreshed ${release_branch} to ${release_sha}"
@@ -129,15 +130,40 @@ jobs:
             fi
 
             release_sha="$bump_sha"
+            shipping_guard_sha="$release_sha"
             candidate_status="Frozen at \`${release_sha}\` — the commit where \`${version}\` was versioned. Commits merged to \`develop\` afterward require an explicit candidate refresh or ship in the next release."
             if git ls-remote --exit-code --heads origin "$release_branch" >/dev/null 2>&1; then
-              echo "Release branch ${release_branch} already exists; leaving it frozen."
+              remote_release_sha="$(git ls-remote --exit-code --heads origin "refs/heads/${release_branch}" | cut -f1)"
+              if [ "$remote_release_sha" != "$release_sha" ]; then
+                echo "Release branch ${release_branch} points to ${remote_release_sha}, expected ${release_sha}; refusing to write Promote PR metadata for a different candidate."
+                exit 1
+              fi
+              echo "Release branch ${release_branch} already exists at ${release_sha}; leaving it frozen."
             else
               git push origin "${release_sha}:refs/heads/${release_branch}"
               echo "Cut ${release_branch} at ${release_sha}"
             fi
           fi
 
+          remote_release_sha="$(git ls-remote --exit-code --heads origin "refs/heads/${release_branch}" | cut -f1)"
+          if [ "$remote_release_sha" != "$release_sha" ]; then
+            echo "Release branch ${release_branch} moved to ${remote_release_sha}, expected ${release_sha}; refusing to update Promote PR metadata."
+            exit 1
+          fi
+
+          git fetch origin "refs/heads/main:refs/remotes/origin/main" --tags --quiet
+          if git rev-parse "$tag" >/dev/null 2>&1 || git merge-base --is-ancestor "$shipping_guard_sha" origin/main; then
+            echo "Cannot update Promote PR metadata for ${tag}: the candidate reached main while the branch was being prepared."
+            exit 1
+          fi
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            existing="$(gh pr list --base main --head "$release_branch" --state open --json url --jq '.[0].url // empty')"
+            if [ -z "$existing" ]; then
+              echo "Cannot refresh ${tag}: the Promote PR closed while the branch was being updated."
+              exit 1
+            fi
+          fi
+
           notes="$(node scripts/release/extract-changelog-section.mjs "$version" || true)"
           body_file="$(mktemp)"
           {