Sort Browse Plugins by install count, and default to it

.github/ISSUE_TEMPLATE/bug.yml

@@ -68,4 +68,4 @@ body:
           required: true
         - label: I searched open and closed issues for the same problem.
           required: true
-        - label: If an agent wrote this, the body ends with `> AGENT GENERATED: by <model>` and links the thread or report.
+        - label: If an agent wrote this, the body ends with `> AGENT GENERATED` and links the thread or report.

.github/ISSUE_TEMPLATE/feature.yml

@@ -39,4 +39,4 @@ body:
       options:
         - label: I searched open and closed issues for the same request.
           required: true
-        - label: If an agent wrote this, the body ends with `> AGENT GENERATED: by <model>`.
+        - label: If an agent wrote this, the body ends with `> AGENT GENERATED`.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,8 @@
-<!-- Keep the four sections. Delete this comment. See docs/filing-issues.md for the issue side. -->
+<!-- Keep the below sections. Delete this comment. See docs/filing-issues.md for the issue side. -->
+
+## Human comments
+
+<!-- Agents: Do not fill in this section. This is for human users to fill in. -->
 
 ## What was wrong
 
@@ -15,4 +19,4 @@
 Fixes #
 
 <!-- Agents: end with the line below. -->
-<!-- > AGENT GENERATED: by <model> -->
+<!-- > AGENT GENERATED -->

.github/workflows/check-plugin-sdk-version.mjs

@@ -0,0 +1,81 @@
+import { execFileSync } from "node:child_process";
+
+/**
+ * A change to the published plugin SDK surface must bump PLUGIN_SDK_VERSION.
+ *
+ * Pre-1.0 the major is the compatibility number and never moves for additive
+ * work, so the patch is the only thing a plugin author can point
+ * `engines.bbPluginSdk` at to say "I need a host new enough to have this" —
+ * `isPluginSdkRangeSatisfied` reads that range as a floor within the major.
+ * Ship a new export without a bump and a plugin using it has no version to
+ * require, so installing it on an older bb fails at runtime instead of
+ * legibly at load.
+ *
+ * Nothing else catches this: `version.test.ts` only checks that package.json
+ * and the constant agree with each other, and `app-contract.ts` has no
+ * enumerated export list the way the backend, rpc, and host contracts do.
+ */
+const SURFACE_PATHS = [
+  "packages/plugin-sdk/src/app-contract.ts",
+  "packages/plugin-sdk/src/app.ts",
+  "packages/plugin-sdk/src/backend-contract.ts",
+  "packages/plugin-sdk/src/host-contract.ts",
+  "packages/plugin-sdk/src/host.ts",
+  "packages/plugin-sdk/src/index.ts",
+  "packages/plugin-sdk/src/provider-bridge.ts",
+  "packages/plugin-sdk/src/rpc-contract.ts",
+];
+
+const VERSION_PATH = "packages/domain/src/plugin-sdk-version.ts";
+
+function git(...args) {
+  return execFileSync("git", args, { encoding: "utf8" }).trim();
+}
+
+/**
+ * The commit this branch left the base at. Returns null when it cannot be
+ * resolved — an unattended push to a fork with no base, say — and the check
+ * then passes rather than failing on something the author cannot act on.
+ */
+function resolveMergeBase() {
+  const baseRef = process.env.GITHUB_BASE_REF || "main";
+  for (const candidate of [`origin/${baseRef}`, baseRef]) {
+    try {
+      return git("merge-base", candidate, "HEAD");
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+const mergeBase = resolveMergeBase();
+if (mergeBase === null) {
+  console.log("No base commit to compare against; skipping.");
+  process.exit(0);
+}
+
+const changed = new Set(
+  git("diff", "--name-only", `${mergeBase}...HEAD`).split("\n").filter(Boolean),
+);
+const changedSurface = SURFACE_PATHS.filter((path) => changed.has(path));
+
+if (changedSurface.length === 0) {
+  console.log("Plugin SDK surface unchanged.");
+  process.exit(0);
+}
+
+if (!changed.has(VERSION_PATH)) {
+  console.error(
+    `The plugin SDK surface changed without a version bump:\n` +
+      changedSurface.map((path) => `  ${path}`).join("\n") +
+      `\n\nBump PLUGIN_SDK_VERSION in ${VERSION_PATH} (patch, pre-1.0) and` +
+      ` keep packages/plugin-sdk/package.json in step, so a plugin using the` +
+      ` new surface can require a host that has it.`,
+  );
+  process.exit(1);
+}
+
+console.log(
+  `Plugin SDK surface changed in ${changedSurface.length} file(s) with a version bump.`,
+);

.github/workflows/ci.yml

@@ -43,8 +43,12 @@ jobs:
           pnpm-version: ${{ env.PNPM_VERSION }}
           cache-prefix: checks
 
+      # Four tasks for four vCPUs: TypeScript 7 and esbuild are multi-threaded,
+      # so turbo's default of ten concurrent tasks only adds contention here.
+      # Measured pinned to 4 CPUs, two rounds each: 96 s / 110 s at the
+      # default vs 90 s / 58 s at four.
       - name: Build, typecheck, and lint
-        run: pnpm exec turbo run build typecheck lint --cache-dir=.turbo/cache --output-logs=new-only
+        run: pnpm exec turbo run build typecheck lint --cache-dir=.turbo/cache --output-logs=new-only --concurrency=4
 
       # Runs after build and typecheck, so the guard's own turbo build is a
       # cache hit and the package it packs is the one this commit really ships.
@@ -72,6 +76,14 @@ jobs:
       - name: Check app bundle budgets
         run: node apps/app/scripts/check-bundle-budget.mjs
 
+      # Provider-literal ratchet (G1 of the provider-plugin migration):
+      # core must never gain a new provider-id carve-out; the per-file
+      # baseline may only shrink. See docs/provider-plugin-api.md.
+      - name: Check provider-literal ratchet
+        run: |
+          git fetch --depth=1 origin "${{ github.base_ref || github.event.repository.default_branch }}" || true
+          node scripts/check-provider-literal-ratchet.mjs --base "origin/${{ github.base_ref || github.event.repository.default_branch }}"
+
       # Exceeding the Actions cache quota is silent: GitHub evicts entries
       # without failing or warning anything, so the only symptom is caches
       # quietly ceasing to hit. Warn while there is still headroom.

.github/workflows/deploy-demo-server.yml

@@ -0,0 +1,84 @@
+name: Deploy Demo Server
+
+# The bb demo server is the mock bb server an App Store reviewer connects to
+# (apps/demo-server). It has no database, no secrets, and no route of its
+# own, so this is the short form of deploy-connect.yml: install, typecheck
+# and test, deploy. It serves from workers.dev; see the wrangler config for
+# why it is not on demo.getbb.app.
+#
+# Paths: the worker bundles @bb/server-contract from source, and the
+# contract is what its tests check the fixtures against, so a contract change
+# redeploys the demo too. That is the point: a demo that has drifted from the
+# contract is a demo that crashes in front of a reviewer.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "apps/demo-server/**"
+      - "packages/server-contract/**"
+      - ".github/workflows/deploy-demo-server.yml"
+  workflow_dispatch:
+
+env:
+  NODE_VERSION: "22.x"
+  PNPM_VERSION: "9.15.0"
+
+permissions:
+  contents: read
+
+# One deploy at a time, and a queued one waits rather than being dropped, so
+# the worker never ends up on a build older than main.
+concurrency:
+  group: demo-server-deploy-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy demo server to Cloudflare Workers
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        with:
+          version: ${{ env.PNPM_VERSION }}
+          run_install: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --prefer-offline
+
+      # The tests parse every fixture with the contract's own schemas. Run
+      # them here too, not only in ci.yml: this job also fires on a contract
+      # change, and that is exactly when a fixture can go stale.
+      - name: Typecheck and test
+        run: pnpm exec turbo run typecheck test --filter=@bb/demo-server
+
+      # No build step: wrangler's esbuild bundles the worker and its workspace
+      # dependency straight from source. The account is pinned in
+      # wrangler.jsonc, so the token never has to pick one.
+      - name: Deploy demo server
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: pnpm --filter @bb/demo-server exec wrangler deploy | tee deploy.log
+
+      # The workers.dev URL is what goes in the App Store review notes. Surface
+      # it on the run so nobody has to open the Cloudflare dashboard for it.
+      - name: Report the URL
+        run: |
+          {
+            echo "## Demo server"
+            echo
+            grep -Eo 'https://[^ ]+\.workers\.dev' deploy.log | sort -u | sed 's/^/- /' || echo "- URL not found in the wrangler output; check the deploy step log."
+          } >> "$GITHUB_STEP_SUMMARY"