ci: relevance-gate workflows — skip deploys, release, and CI on non-relevant merges

.changeset/scaffold-docs-bos-app-ts.md

@@ -0,0 +1,5 @@
+---
+"everything-dev": patch
+---
+
+Scaffolded docs reference `bos.app.ts`, not `bos.config.json`. The init-scaffolded README/AGENTS/skill templates told users the runtime configuration lives in a root `bos.config.json` — but the scaffold generates (and tests assert) the authored `bos.app.ts` descriptor. Cosmetic doc sweep; legacy JSON configs in existing child repos still load.

.github/templates/workflows/ci.yml

@@ -12,6 +12,12 @@ on:
       - "docs/**"
       - ".changeset/**"
   pull_request:
+    # Docs-only PRs cannot affect lint/typecheck/tests; changeset-only PRs
+    # have nothing to validate here.
+    paths-ignore:
+      - "**.md"
+      - "docs/**"
+      - ".changeset/**"
   workflow_dispatch:
 
 permissions:

.github/workflows/check-skills.yml

@@ -28,6 +28,10 @@ on:
     types: [published]
   workflow_dispatch: {}
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   validate:
     name: Validate intent skills

.github/workflows/ci.yml

@@ -8,6 +8,13 @@ on:
       - "docs/**"
       - ".changeset/**"
   pull_request:
+    # Mirrors the push filter. Docs-only PRs run the dedicated Docs Check
+    # workflow (which also validates links against renamed/deleted targets);
+    # changeset-only PRs need no validation at all.
+    paths-ignore:
+      - "**.md"
+      - "docs/**"
+      - ".changeset/**"
   workflow_dispatch:
 
 concurrency:
@@ -90,7 +97,7 @@ jobs:
           else
             echo "workflows=false" >> "$GITHUB_OUTPUT"
           fi
-          if echo "$DIFF" | grep -qE '^Dockerfile$|^scripts/|^host/|^api/|^ui/|^plugins/|^packages/|^tests/|^bos\.config\.json$|^\.env\.test$|^(package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|tsconfig\.json|tsconfig\.base\.json|bos\.app\.ts)$|^\.github/workflows/ci\.yml$'; then
+          if echo "$DIFF" | grep -qE '^Dockerfile$|^scripts/|^host/|^api/|^ui/|^plugins/|^packages/|^tests/|^\.env\.test$|^(package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|tsconfig\.json|tsconfig\.base\.json|bos\.app\.ts)$|^\.github/workflows/ci\.yml$'; then
             echo "image-smoke=true" >> "$GITHUB_OUTPUT"
           else
             echo "image-smoke=false" >> "$GITHUB_OUTPUT"
@@ -105,12 +112,12 @@ jobs:
           else
             echo "every-plugin=false" >> "$GITHUB_OUTPUT"
           fi
-          if echo "$DIFF" | grep -qE '^host/|^ui/|^packages/|^bos\.config\.json$|^\.env\.test$|^(package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|tsconfig\.json|tsconfig\.base\.json|bos\.app\.ts|bos\.dev\.ts)$|^\.github/workflows/ci\.yml$'; then
+          if echo "$DIFF" | grep -qE '^host/|^ui/|^packages/|^\.env\.test$|^(package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|tsconfig\.json|tsconfig\.base\.json|bos\.app\.ts|bos\.dev\.ts)$|^\.github/workflows/ci\.yml$'; then
             echo "host=true" >> "$GITHUB_OUTPUT"
           else
             echo "host=false" >> "$GITHUB_OUTPUT"
           fi
-          if echo "$DIFF" | grep -qE '^tests/regression/(http|lib)/|^host/|^api/|^plugins/|^packages/|^scripts/|^Dockerfile$|^bos\.config\.json$|^\.env\.test$|^(package.json|pnpm-lock.yaml|pnpm-workspace.yaml|tsconfig.json|tsconfig.base.json|bos.app.ts|bos.dev.ts)$|^\.github/workflows/ci\.yml$'; then
+          if echo "$DIFF" | grep -qE '^tests/regression/(http|lib)/|^host/|^api/|^plugins/|^packages/|^scripts/|^Dockerfile$|^\.env\.test$|^(package.json|pnpm-lock.yaml|pnpm-workspace.yaml|tsconfig.json|tsconfig.base.json|bos.app.ts|bos.dev.ts)$|^\.github/workflows/ci\.yml$'; then
             echo "regression-http=true" >> "$GITHUB_OUTPUT"
           else
             echo "regression-http=false" >> "$GITHUB_OUTPUT"
@@ -120,7 +127,7 @@ jobs:
           else
             echo "regression-framework=false" >> "$GITHUB_OUTPUT"
           fi
-          if echo "$DIFF" | grep -qE '^tests/regression/(browser|lib)/|^host/|^ui/|^api/|^plugins/|^packages/|^scripts/|^Dockerfile$|^bos\.config\.json$|^\.env\.test$|^(package.json|pnpm-lock.yaml|pnpm-workspace.yaml|tsconfig.json|tsconfig.base.json|bos.app.ts|bos.dev.ts)$|^\.github/workflows/ci\.yml$'; then
+          if echo "$DIFF" | grep -qE '^tests/regression/(browser|lib)/|^host/|^ui/|^api/|^plugins/|^packages/|^scripts/|^Dockerfile$|^\.env\.test$|^(package.json|pnpm-lock.yaml|pnpm-workspace.yaml|tsconfig.json|tsconfig.base.json|bos.app.ts|bos.dev.ts)$|^\.github/workflows/ci\.yml$'; then
             echo "regression-browser=true" >> "$GITHUB_OUTPUT"
           else
             echo "regression-browser=false" >> "$GITHUB_OUTPUT"
@@ -189,9 +196,6 @@ jobs:
       - name: Check agent skills lock
         run: pnpm run skills:check
 
-      - name: Check docs links
-        run: pnpm run docs:check
-
       - name: Run typecheck
         run: pnpm run typecheck
 

.github/workflows/deploy.yml

@@ -33,12 +33,13 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     outputs:
-      deploy: ${{ steps.tip.outputs.current }}
+      deploy: ${{ steps.tip.outputs.current == 'true' && steps.relevance.outputs.relevant == 'true' }}
     steps:
       - name: Checkout code
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 (Node 24)
         with:
           ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+          fetch-depth: 2
 
       - name: Verify the CI-validated commit is still the main tip
         id: tip
@@ -53,6 +54,37 @@ jobs:
             echo "::notice::Skipping deploy — main advanced past the CI-validated commit ($SHA → $TIP). The queued run for the new tip deploys instead."
           fi
 
+      # Relevance gate: skip the full deploy train when the merged diff touches
+      # no runtime-affecting paths (docs/tests/workflows/changesets only).
+      # Merge commits (PR merges) diff exactly the PR's files; single-commit
+      # direct pushes too. Any uncertainty errs toward deploying, and manual
+      # dispatches always deploy.
+      - name: Check the diff for runtime-relevant paths
+        id: relevance
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "relevant=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if ! git rev-parse HEAD^ >/dev/null 2>&1; then
+            echo "::notice::No parent commit — assuming runtime-relevant"
+            echo "relevant=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          FILES="$(git diff --name-only HEAD^ HEAD)"
+          if [ -z "$FILES" ]; then
+            echo "::notice::Empty first-parent diff (merge-tangle history) — assuming runtime-relevant"
+            echo "relevant=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if echo "$FILES" | grep -qE '^Dockerfile$|^railway\.toml$|^scripts/|^host/|^api/|^ui/|^plugins/|^packages/|^bos\.app\.ts$|^bos\.dev\.ts$|^biome\.json$|^\.env\.test$|^(package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|tsconfig\.json|tsconfig\.base\.json)$|^\.github/workflows/(ci|deploy|release)\.yml$|^\.github/templates/'; then
+            echo "relevant=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "relevant=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::Skipping deploy — the merged diff touches no runtime-relevant paths:"
+            while IFS= read -r f; do echo "  $f"; done <<< "$FILES"
+          fi
+
   deploy:
     name: Deploy Production
     needs: [gate]

.github/workflows/docs-check.yml

@@ -0,0 +1,43 @@
+name: Docs Check
+
+# The docs link check lives here — outside CI's lint-and-typecheck — so CI can
+# path-ignore markdown entirely. The script is zero-dependency (node: builtins
+# plus git check-ignore), so the whole workflow is checkout + node, no install.
+#
+# Runs on every PR (not just docs paths): broken references are also caused by
+# renaming/deleting a file the markdown points at — docs-surface paths alone
+# miss those.
+on:
+  pull_request:
+  push:
+    branches: [main]
+    # Post-merge runs duplicate the PR check for code merges; docs paths still
+    # get validated on direct md pushes.
+    paths:
+      - "**.md"
+      - "docs/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  docs-link-check:
+    name: Docs link check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 (Node 24)
+
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "24"
+
+      - name: Check docs links
+        run: node scripts/docs-link-check.mjs

.github/workflows/release.yml

@@ -4,6 +4,12 @@ on:
   push:
     branches:
       - main
+    # Docs-only merges cannot change changesets — skip the changesets pass.
+    # Deliberately NOT ignoring .changeset/** — that is the input this
+    # workflow consumes.
+    paths-ignore:
+      - "**.md"
+      - "docs/**"
   workflow_dispatch:
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
@@ -30,12 +36,13 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
+      # No registry-url: it injects an empty `_authToken` into the job's
+      # .npmrc, which blocks npm's OIDC trusted-publishing exchange
+      # (publish fails with ENEEDAUTH instead of using the OIDC token).
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: "24"
-          npm-version: "11"
-          registry-url: "https://registry.npmjs.org"
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile --ignore-scripts
@@ -54,4 +61,3 @@ jobs:
           createGithubReleases: false
         env:
           GITHUB_TOKEN: ${{ github.token }}
-          NODE_AUTH_TOKEN: ""

packages/everything-dev/src/cli/init.ts

@@ -89,7 +89,7 @@
     changed = true;
   }
 
   const catalog: Record<string, string> = { ...(doc.catalog ?? {}) };
   for (const [name, version] of Object.entries(next.catalog)) {
     if (catalog[name] !== version) {
       catalog[name] = version;
@@ -121,7 +121,7 @@
     changed = true;
   }
 
   const overrides: Record<string, string> = { ...(doc.overrides ?? {}) };
   for (const key of CHILD_OVERRIDE_KEYS) {
     if (catalog[key] && overrides[key] !== catalog[key]) {
       overrides[key] = catalog[key];
@@ -384,7 +384,7 @@
   level: StarterLevel,
   parentConfig: { starter?: ParentStarterConfig } | null | undefined,
 ): string[] {
   const excluded = new Set<string>([...STARTER_PRODUCT_EXCLUSIONS]);
   if (level === "simple") {
     for (const entry of STARTER_SIMPLE_EXCLUSIONS) excluded.add(entry);
   }
@@ -1697,8 +1697,8 @@
    # Output: NEAR_PRIVATE_KEY=ed25519:...
    \`\`\`
    Add the key to your account via near-cli-rs, then set \`NEAR_PRIVATE_KEY\` in \`.env\` or CI secrets.
-4. **Update \`bos.config.json\`** — set \`account\` to your NEAR account, add \`extends\` to inherit the base platform, keep \`domain\` as the gateway:
-   \`\`\`json
+4. **Update \`bos.app.ts\`** — set \`account\` to your NEAR account, add \`extends\` to inherit the base platform, keep \`domain\` as the gateway:
+   \`\`\`ts
    { "extends": "bos://<parent-account>/<parent-gateway>", "account": "<your-account>.near", "domain": "<parent-gateway>" }
    \`\`\`
  5. **Publish and deploy:**
@@ -1795,9 +1795,9 @@
 
 ### Generated Types
 
-\`api/src/lib/plugins-types.gen.ts\`, \`api/src/lib/auth-types.gen.ts\`, \`ui/src/lib/api-types.gen.ts\`, and \`ui/src/lib/auth-types.gen.ts\` are generated by \`bos types gen\` from \`bos.config.json\`. These files are gitignored and auto-regenerated on \`pnpm install\`, \`typecheck\`, \`bos dev\`, \`bos build\`, and bos plugin management commands.
+\`api/src/lib/plugins-types.gen.ts\`, \`api/src/lib/auth-types.gen.ts\`, \`ui/src/lib/api-types.gen.ts\`, and \`ui/src/lib/auth-types.gen.ts\` are generated by \`bos types gen\` from \`bos.app.ts\`. These files are gitignored and auto-regenerated on \`pnpm install\`, \`typecheck\`, \`bos dev\`, \`bos build\`, and bos plugin management commands.
 
-If you hand-edit \`bos.config.json\`, run \`bos types gen\` or restart \`bos dev\` to regenerate.`);
+If you hand-edit \`bos.app.ts\`, run \`bos types gen\` or restart \`bos dev\` to regenerate.`);
   }
 
   const testCommands: string[] = [];
@@ -1876,7 +1876,7 @@
 
 ### Architecture note: remotes are code bundles
 
-Remotes in \`bos.config.json\` are **not hosted APIs** — they are code bundles loaded via Module Federation at runtime. The UI, API, auth, and plugins all run in the same host process. There is no remote server to call; everything is loaded in-process through Module Federation and \`every-plugin\`.`);
+Remotes in \`bos.app.ts\` are **not hosted APIs** — they are code bundles loaded via Module Federation at runtime. The UI, API, auth, and plugins all run in the same host process. There is no remote server to call; everything is loaded in-process through Module Federation and \`every-plugin\`.`);
 
   parts.push(`## Troubleshooting
 
@@ -1888,7 +1888,7 @@
 \`\`\`
 
 **Module Federation errors:**
-- Check \`bos.config.json\` URLs are accessible
+- Check \`bos.app.ts\` URLs are accessible
 - Verify shared dependency versions match in package.json
 - Clear browser cache
 
@@ -1902,7 +1902,7 @@
 
 **Required files:**
 - \`.env\` — Secrets (see \`.env.example\`)
-- \`bos.config.json\` — Runtime configuration (committed)`);
+- \`bos.app.ts\` — Runtime configuration (committed)`);
 
   return `${parts.join("\n\n")}\n`;
 }
@@ -2000,7 +2000,7 @@
 
   return `# ${title} skill
 
-Use this when you want an agent to run, edit, and publish **${title}** — an everything.dev app composed at runtime from \`bos.config.json\`.
+Use this when you want an agent to run, edit, and publish **${title}** — an everything.dev app composed at runtime from \`bos.app.ts\`.
 
 There are two ways to work with this app:
 
@@ -2050,7 +2050,7 @@
 
 ### Architecture note
 
-Remotes in \`bos.config.json\` are **not hosted APIs** — they are code bundles loaded via Module Federation at runtime. Everything runs in the same host process.
+Remotes in \`bos.app.ts\` are **not hosted APIs** — they are code bundles loaded via Module Federation at runtime. Everything runs in the same host process.
 
 ### Run locally