bsmnt 0.7.1 → 0.10.0

package/src/templates/next-default/.env.example

@@ -1,6 +1,7 @@
 # ============================================
 # Basement Next Starter - Environment Variables
 # ============================================
+# bsmnt:if dotenvx
 # This project uses dotenvx (https://dotenvx.com): the committed `.env` holds
 # shared values, with secrets encrypted there. The private keys live in
 # `.env.keys` (gitignored) — restore them with `bun run env:setup`.
@@ -15,6 +16,13 @@
 #
 # This file just documents the available variables; real values live in `.env`.
 # ============================================
+# bsmnt:endif
+# bsmnt:if !dotenvx
+# Copy this file to `.env.local` and fill in the values you need.
+# `.env.local` is gitignored, so real values stay off version control.
+# Only NEXT_PUBLIC_* variables are exposed to the browser.
+# ============================================
+# bsmnt:endif
 
 
 # ============================================
@@ -24,6 +32,8 @@
 # Base URL for your site (used for SEO, canonical URLs, etc.)
 # Development: http://localhost:3000
 # Production: https://your-domain.com
+# Inlined at build time — scope this to the Production environment only in
+# Vercel so Preview deployments fall through to VERCEL_PROJECT_PRODUCTION_URL.
 NEXT_PUBLIC_BASE_URL=""
 
 # Draft mode secret for preview functionality

package/src/templates/next-default/.github/workflows/ci.yml

@@ -46,6 +46,7 @@ jobs:
       - name: Lint
         run: bun run lint
 
+      # bsmnt:if dotenvx
       # dotenvx needs the private key to decrypt secrets at build time. It's
       # pulled from 1Password via an org-wide service-account token + the op-ref
       # committed in .env. Optional: builds pass without it (only plaintext /
@@ -70,6 +71,12 @@ jobs:
           fi
           bun run build
 
+      # bsmnt:endif
+      # bsmnt:if !dotenvx
+      - name: Build
+        run: bun run build
+
+      # bsmnt:endif
       # Runs your tests if any exist; a fresh project with none passes cleanly.
       - name: Test
         run: |

package/src/templates/next-default/README.md

@@ -22,6 +22,7 @@ bun dev
 | `bun format` | Format the codebase |
 | `bun typecheck` | Run TypeScript |
 | `bun analyze` | Analyze the Next.js bundle |
+<!-- bsmnt:if dotenvx -->
 | `bun env:set KEY value` | Encrypt one value into `.env` (`--plain`, `--preview`/`--prod`) |
 | `bun env:encrypt-all` | Bulk-encrypt every plaintext value in a file (`--preview`/`--prod`) |
 | `bun env:setup` | Restore `.env.keys` from 1Password |
@@ -29,7 +30,9 @@ bun dev
 | `bun env:setup-remote` | Push private keys to GitHub / Vercel (`github`/`vercel`, or pick) |
 | `bun setup-remote` | Create the GitHub repo, link a Vercel project, and push the key to Vercel env |
 | `bun env:save` | Save the private key to 1Password (Development vault) |
+<!-- bsmnt:endif -->
 
+<!-- bsmnt:if dotenvx -->
 ## Environment variables
 
 Secrets are encrypted at rest with [dotenvx](https://dotenvx.com): the committed `.env` holds encrypted values, the private keys live in `.env.keys` (gitignored), and dev/build run through `dotenvx run` so values decrypt automatically.
@@ -53,6 +56,15 @@ Secrets are encrypted at rest with [dotenvx](https://dotenvx.com): the committed
 
 A gitleaks pre-commit hook + CI scan block committed plaintext secrets (install: `brew install gitleaks`).
 
+<!-- bsmnt:endif -->
+<!-- bsmnt:if !dotenvx -->
+## Environment variables
+
+Copy `.env.example` to `.env.local` and fill in the values you need. `.env.local` is gitignored, so it stays off version control. Only `NEXT_PUBLIC_*` variables are exposed to the browser — everything else is server-only.
+
+For deploys, set the same variables in your host's dashboard (e.g. Vercel → Settings → Environment Variables).
+
+<!-- bsmnt:endif -->
 ## Project Structure
 
 ```txt
@@ -90,8 +102,10 @@ The workflow takes its runtime versions from your manifests, so there's a single
 
 It also caches Bun's install cache between runs, and the test step is a no-op until you add real test files.
 
+<!-- bsmnt:if dotenvx -->
 The build decrypts the committed `.env` with the dotenvx private key, pulled from 1Password: set an **org-level** `OP_SERVICE_ACCOUNT_TOKEN` (a read-only [service account](https://developer.1password.com/docs/service-accounts/) scoped to the `Development` vault) — one secret for every repo — and CI reads the key via the op-ref committed in `.env`. A per-repo `DOTENV_PRIVATE_KEY` secret (`bun run env:setup-remote github`) works as a fallback; builds pass without either (only plaintext / `NEXT_PUBLIC_*` is read).
 
+<!-- bsmnt:endif -->
 ### Branch protection
 
 To block merges when CI fails, enable branch protection on `main`:

package/src/templates/next-default/app/robots.ts

@@ -1,6 +1,5 @@
 import type { MetadataRoute } from "next"
-
-const APP_BASE_URL = process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000"
+import { getBaseUrl } from "@/lib/utils/url"
 
 export default function robots(): MetadataRoute.Robots {
   return {
@@ -9,6 +8,6 @@ export default function robots(): MetadataRoute.Robots {
       allow: "/",
       disallow: [],
     },
-    sitemap: `${APP_BASE_URL}/sitemap.xml`,
+    sitemap: `${getBaseUrl()}/sitemap.xml`,
   }
 }

package/src/templates/next-default/knip.json

@@ -12,11 +12,13 @@
     "@svgr/webpack",
     "gsap",
     "@gsap/react",
-    "motion"
+    "motion",
+    "detect-gpu",
+    "lodash-es",
+    "@types/lodash-es",
+    "react-device-detect",
+    "zustand"
   ],
-  "ignoreBinaries": [
-    "op",
-    "gh",
-    "vercel"
-  ]
+  "ignoreBinaries": ["op", "gh", "vercel"],
+  "ignoreFiles": [".agents/**", ".claude/**", "hooks/**"]
 }

package/src/templates/next-default/lefthook.yml

@@ -14,11 +14,6 @@ pre-commit:
       run: bunx tsgo --noEmit --incremental false
       stage_fixed: false
 
-pre-push:
-  commands:
-    knip:
-      run: bun run knip
-
 post-merge:
   commands:
     install-deps:

package/src/templates/next-default/next.config.ts

@@ -64,8 +64,10 @@ const nextConfig: NextConfig = {
       },
     },
   },
+  logging: {
+    browserToTerminal: true,
+  },
   experimental: {
-    browserDebugInfoInTerminal: true,
     optimizePackageImports: [
       "@react-three/drei",
       "@react-three/fiber",
@@ -86,7 +88,8 @@ const nextConfig: NextConfig = {
   },
   headers: async () => [
     {
-      source: "/(.*)",
+      // Excludes /studio* — must stay mutually exclusive with the rule below.
+      source: "/((?!studio(?:/|$)).*)",
       headers: [
         {
           key: "X-Content-Type-Options",
@@ -118,6 +121,37 @@ const nextConfig: NextConfig = {
         },
       ],
     },
+    {
+      // X-Frame-Options can't allow a third-party origin, and Next can't unset
+      // it from another rule — the iframe needs it absent, not overridden.
+      source: "/studio/:path*",
+      headers: [
+        {
+          key: "X-Content-Type-Options",
+          value: "nosniff",
+        },
+        {
+          key: "Content-Security-Policy",
+          value: "frame-ancestors 'self' https://*.sanity.io;",
+        },
+        {
+          key: "X-XSS-Protection",
+          value: "1; mode=block",
+        },
+        {
+          key: "X-DNS-Prefetch-Control",
+          value: "on",
+        },
+        {
+          key: "Strict-Transport-Security",
+          value: "max-age=63072000; includeSubDomains; preload",
+        },
+        {
+          key: "Permissions-Policy",
+          value: "camera=(), microphone=(), geolocation=()",
+        },
+      ],
+    },
   ],
   redirects: async () => [
     {

package/src/templates/next-default/package.json

@@ -30,30 +30,30 @@
   "dependencies": {
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "next": "^16",
-    "react": "^19",
-    "react-dom": "^19",
+    "next": "^16.3.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tailwind-merge": "^3.4.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@next/bundle-analyzer": "^16",
+    "@next/bundle-analyzer": "^16.3.0",
     "@svgr/webpack": "^8.1.0",
-    "@tailwindcss/postcss": "^4",
+    "@tailwindcss/postcss": "^4.2.2",
     "@types/bun": "^1.3.6",
     "@types/node": "^24.13.1",
-    "@types/react": "^19.2.9",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@typescript/native-preview": "^7.0.0-dev.20260122.3",
+    "@typescript/native-preview": "^7.0.0-dev.20260323.1",
     "babel-plugin-react-compiler": "^1.0.0",
     "cross-env": "^10.1.0",
     "knip": "^6.16.1",
     "lefthook": "^1.13.0",
     "postcss-preset-env": "^10.6.1",
     "schema-dts": "^2.0.0",
-    "tailwindcss": "^4",
-    "typescript": "^5"
+    "tailwindcss": "^4.2.2",
+    "typescript": "^5.9.3"
   },
   "trustedDependencies": [
     "@biomejs/biome",

package/src/templates/next-experiments/.env.example

@@ -1,6 +1,7 @@
 # ============================================
 # Basement Next Starter - Environment Variables
 # ============================================
+# bsmnt:if dotenvx
 # This project uses dotenvx (https://dotenvx.com): the committed `.env` holds
 # shared values, with secrets encrypted there. The private keys live in
 # `.env.keys` (gitignored) — restore them with `bun run env:setup`.
@@ -15,6 +16,13 @@
 #
 # This file just documents the available variables; real values live in `.env`.
 # ============================================
+# bsmnt:endif
+# bsmnt:if !dotenvx
+# Copy this file to `.env.local` and fill in the values you need.
+# `.env.local` is gitignored, so real values stay off version control.
+# Only NEXT_PUBLIC_* variables are exposed to the browser.
+# ============================================
+# bsmnt:endif
 
 
 # ============================================
@@ -24,6 +32,8 @@
 # Base URL for your site (used for SEO, canonical URLs, etc.)
 # Development: http://localhost:3000
 # Production: https://your-domain.com
+# Inlined at build time — scope this to the Production environment only in
+# Vercel so Preview deployments fall through to VERCEL_PROJECT_PRODUCTION_URL.
 NEXT_PUBLIC_BASE_URL=""
 
 # Draft mode secret for preview functionality

package/src/templates/next-experiments/.github/workflows/ci.yml

@@ -46,6 +46,7 @@ jobs:
       - name: Lint
         run: bun run lint
 
+      # bsmnt:if dotenvx
       # dotenvx needs the private key to decrypt secrets at build time. It's
       # pulled from 1Password via an org-wide service-account token + the op-ref
       # committed in .env. Optional: builds pass without it (only plaintext /
@@ -70,6 +71,12 @@ jobs:
           fi
           bun run build
 
+      # bsmnt:endif
+      # bsmnt:if !dotenvx
+      - name: Build
+        run: bun run build
+
+      # bsmnt:endif
       # Runs your tests if any exist; a fresh project with none passes cleanly.
       - name: Test
         run: |

package/src/templates/next-experiments/README.md

@@ -22,6 +22,7 @@ bun dev
 | `bun format` | Format the codebase |
 | `bun typecheck` | Run TypeScript |
 | `bun analyze` | Analyze the Next.js bundle |
+<!-- bsmnt:if dotenvx -->
 | `bun env:set KEY value` | Encrypt one value into `.env` (`--plain`, `--preview`/`--prod`) |
 | `bun env:encrypt-all` | Bulk-encrypt every plaintext value in a file (`--preview`/`--prod`) |
 | `bun env:setup` | Restore `.env.keys` from 1Password |
@@ -29,7 +30,9 @@ bun dev
 | `bun env:setup-remote` | Push private keys to GitHub / Vercel (`github`/`vercel`, or pick) |
 | `bun setup-remote` | Create the GitHub repo, link a Vercel project, and push the key to Vercel env |
 | `bun env:save` | Save the private key to 1Password (Development vault) |
+<!-- bsmnt:endif -->
 
+<!-- bsmnt:if dotenvx -->
 ## Environment variables
 
 Secrets are encrypted at rest with [dotenvx](https://dotenvx.com): the committed `.env` holds encrypted values, the private keys live in `.env.keys` (gitignored), and dev/build run through `dotenvx run` so values decrypt automatically.
@@ -53,6 +56,15 @@ Secrets are encrypted at rest with [dotenvx](https://dotenvx.com): the committed
 
 A gitleaks pre-commit hook + CI scan block committed plaintext secrets (install: `brew install gitleaks`).
 
+<!-- bsmnt:endif -->
+<!-- bsmnt:if !dotenvx -->
+## Environment variables
+
+Copy `.env.example` to `.env.local` and fill in the values you need. `.env.local` is gitignored, so it stays off version control. Only `NEXT_PUBLIC_*` variables are exposed to the browser — everything else is server-only.
+
+For deploys, set the same variables in your host's dashboard (e.g. Vercel → Settings → Environment Variables).
+
+<!-- bsmnt:endif -->
 ## Project Structure
 
 ```txt
@@ -90,8 +102,10 @@ The workflow takes its runtime versions from your manifests, so there's a single
 
 It also caches Bun's install cache between runs, and the test step is a no-op until you add real test files.
 
+<!-- bsmnt:if dotenvx -->
 The build decrypts the committed `.env` with the dotenvx private key, pulled from 1Password: set an **org-level** `OP_SERVICE_ACCOUNT_TOKEN` (a read-only [service account](https://developer.1password.com/docs/service-accounts/) scoped to the `Development` vault) — one secret for every repo — and CI reads the key via the op-ref committed in `.env`. A per-repo `DOTENV_PRIVATE_KEY` secret (`bun run env:setup-remote github`) works as a fallback; builds pass without either (only plaintext / `NEXT_PUBLIC_*` is read).
 
+<!-- bsmnt:endif -->
 ### Branch protection
 
 To block merges when CI fails, enable branch protection on `main`:

package/src/templates/next-experiments/app/robots.ts

@@ -1,6 +1,5 @@
 import type { MetadataRoute } from "next"
-
-const APP_BASE_URL = process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000"
+import { getBaseUrl } from "@/lib/utils/url"
 
 export default function robots(): MetadataRoute.Robots {
   return {
@@ -9,6 +8,6 @@ export default function robots(): MetadataRoute.Robots {
       allow: "/",
       disallow: [],
     },
-    sitemap: `${APP_BASE_URL}/sitemap.xml`,
+    sitemap: `${getBaseUrl()}/sitemap.xml`,
   }
 }

package/src/templates/next-experiments/knip.json

@@ -12,11 +12,13 @@
     "@svgr/webpack",
     "gsap",
     "@gsap/react",
-    "motion"
+    "motion",
+    "detect-gpu",
+    "lodash-es",
+    "@types/lodash-es",
+    "react-device-detect",
+    "zustand"
   ],
-  "ignoreBinaries": [
-    "op",
-    "gh",
-    "vercel"
-  ]
+  "ignoreBinaries": ["op", "gh", "vercel"],
+  "ignoreFiles": [".agents/**", ".claude/**", "hooks/**"]
 }

package/src/templates/next-experiments/lefthook.yml

@@ -14,11 +14,6 @@ pre-commit:
       run: bunx tsgo --noEmit --incremental false
       stage_fixed: false
 
-pre-push:
-  commands:
-    knip:
-      run: bun run knip
-
 post-merge:
   commands:
     install-deps:

package/src/templates/next-experiments/next.config.ts

@@ -64,8 +64,10 @@ const nextConfig: NextConfig = {
       },
     },
   },
+  logging: {
+    browserToTerminal: true,
+  },
   experimental: {
-    browserDebugInfoInTerminal: true,
     optimizePackageImports: [
       "@react-three/drei",
       "@react-three/fiber",
@@ -86,7 +88,8 @@ const nextConfig: NextConfig = {
   },
   headers: async () => [
     {
-      source: "/(.*)",
+      // Excludes /studio* — must stay mutually exclusive with the rule below.
+      source: "/((?!studio(?:/|$)).*)",
       headers: [
         {
           key: "X-Content-Type-Options",
@@ -118,6 +121,37 @@ const nextConfig: NextConfig = {
         },
       ],
     },
+    {
+      // X-Frame-Options can't allow a third-party origin, and Next can't unset
+      // it from another rule — the iframe needs it absent, not overridden.
+      source: "/studio/:path*",
+      headers: [
+        {
+          key: "X-Content-Type-Options",
+          value: "nosniff",
+        },
+        {
+          key: "Content-Security-Policy",
+          value: "frame-ancestors 'self' https://*.sanity.io;",
+        },
+        {
+          key: "X-XSS-Protection",
+          value: "1; mode=block",
+        },
+        {
+          key: "X-DNS-Prefetch-Control",
+          value: "on",
+        },
+        {
+          key: "Strict-Transport-Security",
+          value: "max-age=63072000; includeSubDomains; preload",
+        },
+        {
+          key: "Permissions-Policy",
+          value: "camera=(), microphone=(), geolocation=()",
+        },
+      ],
+    },
   ],
   redirects: async () => [
     {

package/src/templates/next-experiments/package.json

@@ -31,31 +31,31 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.474.0",
-    "next": "^16",
-    "react": "^19",
-    "react-dom": "^19",
+    "next": "^16.3.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tailwind-merge": "^3.4.0",
     "three": "^0.182.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@next/bundle-analyzer": "^16",
+    "@next/bundle-analyzer": "^16.3.0",
     "@svgr/webpack": "^8.1.0",
-    "@tailwindcss/postcss": "^4",
+    "@tailwindcss/postcss": "^4.2.2",
     "@types/bun": "^1.3.6",
     "@types/node": "^24.13.1",
-    "@types/react": "^19.2.9",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@typescript/native-preview": "^7.0.0-dev.20260122.3",
+    "@typescript/native-preview": "^7.0.0-dev.20260323.1",
     "babel-plugin-react-compiler": "^1.0.0",
     "cross-env": "^10.1.0",
     "knip": "^6.16.1",
     "lefthook": "^1.13.0",
     "postcss-preset-env": "^10.6.1",
     "schema-dts": "^2.0.0",
-    "tailwindcss": "^4",
-    "typescript": "^5"
+    "tailwindcss": "^4.2.2",
+    "typescript": "^5.9.3"
   },
   "trustedDependencies": [
     "@biomejs/biome",

package/src/templates/next-pagebuilder/.env.example

@@ -1,6 +1,7 @@
 # ============================================
 # Basement Next Starter - Environment Variables
 # ============================================
+# bsmnt:if dotenvx
 # This project uses dotenvx (https://dotenvx.com): the committed `.env` holds
 # shared values, with secrets encrypted there. The private keys live in
 # `.env.keys` (gitignored) — restore them with `bun run env:setup`.
@@ -15,8 +16,17 @@
 #
 # This file just documents the available variables; real values live in `.env`.
 # ============================================
+# bsmnt:endif
+# bsmnt:if !dotenvx
+# Copy this file to `.env.local` and fill in the values you need.
+# `.env.local` is gitignored, so real values stay off version control.
+# Only NEXT_PUBLIC_* variables are exposed to the browser.
+# ============================================
+# bsmnt:endif
 
 # Base URL
+# Inlined at build time — scope this to the Production environment only in
+# Vercel so Preview deployments fall through to VERCEL_PROJECT_PRODUCTION_URL.
 NEXT_PUBLIC_BASE_URL=
 
 # Draft Mode

package/src/templates/next-pagebuilder/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Changes
+
+- 
+
+## Checklist
+
+- [ ] `bun lint` passes
+- [ ] Tested locally in dev mode
+- [ ] No breaking changes (or documented in summary)

package/src/templates/next-pagebuilder/.github/workflows/ci.yml

@@ -46,6 +46,7 @@ jobs:
       - name: Lint
         run: bun run lint
 
+      # bsmnt:if dotenvx
       # dotenvx needs the private key to decrypt secrets at build time. It's
       # pulled from 1Password via an org-wide service-account token + the op-ref
       # committed in .env. Optional: builds pass without it (only plaintext /
@@ -77,6 +78,20 @@ jobs:
           fi
           bun run build
 
+      # bsmnt:endif
+      # bsmnt:if !dotenvx
+      - name: Build
+        env:
+          # Sanity project ID and dataset are public (they ship in the client
+          # bundle), so they are stored as repository variables. The Sanity read
+          # token is secret — add it under Settings → Secrets and variables →
+          # Actions. All three are empty (and harmless) until Sanity is set up.
+          NEXT_PUBLIC_SANITY_PROJECT_ID: ${{ vars.NEXT_PUBLIC_SANITY_PROJECT_ID }}
+          NEXT_PUBLIC_SANITY_DATASET: ${{ vars.NEXT_PUBLIC_SANITY_DATASET }}
+          SANITY_API_READ_TOKEN: ${{ secrets.SANITY_API_READ_TOKEN }}
+        run: bun run build
+
+      # bsmnt:endif
       # Runs your tests if any exist; a fresh project with none passes cleanly.
       - name: Test
         run: |

package/src/templates/next-pagebuilder/README.md

@@ -21,6 +21,7 @@ bun dev
 - `bun build` - Production build
 - `bun lint` - Run linter
 - `bun sanity:typegen` - Generate Sanity types
+<!-- bsmnt:if dotenvx -->
 - `bun env:set KEY value` - Encrypt one value into `.env` (`--plain`, `--preview`/`--prod`)
 - `bun env:encrypt-all` - Bulk-encrypt every plaintext value in a file (`--preview`/`--prod`)
 - `bun env:setup` - Restore `.env.keys` from 1Password
@@ -28,7 +29,9 @@ bun dev
 - `bun env:setup-remote` - Push private keys to GitHub / Vercel (`github`/`vercel`, or pick)
 - `bun setup-remote` - Create the GitHub repo, link a Vercel project, and push the key to Vercel env
 - `bun env:save` - Save the private key to 1Password (Development vault)
+<!-- bsmnt:endif -->
 
+<!-- bsmnt:if dotenvx -->
 ## Environment variables
 
 Secrets are encrypted at rest with [dotenvx](https://dotenvx.com): the committed `.env` holds encrypted values, the private keys live in `.env.keys` (gitignored), and dev/build run through `dotenvx run` so values decrypt automatically.
@@ -52,6 +55,46 @@ Secrets are encrypted at rest with [dotenvx](https://dotenvx.com): the committed
 
 A gitleaks pre-commit hook + CI scan block committed plaintext secrets (install: `brew install gitleaks`).
 
+<!-- bsmnt:endif -->
+<!-- bsmnt:if !dotenvx -->
+## Environment variables
+
+Copy `.env.example` to `.env.local` and fill in the values you need. `.env.local` is gitignored, so it stays off version control. Only `NEXT_PUBLIC_*` variables are exposed to the browser — everything else is server-only.
+
+For deploys, set the same variables in your host's dashboard (e.g. Vercel → Settings → Environment Variables).
+
+<!-- bsmnt:endif -->
+## Sanity Dashboard (Studio in an iframe)
+
+The Studio at `/studio` can be embedded in the Sanity Dashboard
+(`https://www.sanity.io/@<org>/studio/<appId>/<workspace>`), which loads it in an
+iframe from `www.sanity.io`. Three things have to be true for that to work:
+
+1. **Headers.** `next.config.ts` already exempts `/studio/:path*` from the
+   site-wide `X-Frame-Options` / `frame-ancestors 'self'` headers, sending
+   `frame-ancestors 'self' https://*.sanity.io` there instead and dropping
+   `X-Frame-Options` entirely for that path (it has no "allow this origin"
+   form — it must be absent, not overridden). Nothing to do here unless
+   you've hand-edited `headers()`.
+2. **Bridge script.** Already wired in: `next-sanity/studio`'s `NextStudio`
+   re-exports `NextStudioWithBridge`, which renders the
+   `core.sanity-cdn.com/bridge.js` tag the Dashboard needs. Don't hand-roll
+   that script tag, and don't switch the Studio route to
+   `next-sanity/studio/client-component` (the bridge-less variant).
+3. **Registered URL.** In [Sanity Manage](https://sanity.io/manage), the
+   Studio application's URL must be the **full path**
+   (`https://example.com/studio`), not just the domain. This can't be set
+   from code — either click through Manage, or run
+   `sanity deploy --external --url https://example.com/studio --yes` from
+   `lib/integrations/sanity`. Writing it via the API needs the
+   `sanity.project.deployStudio` grant, which read/write tokens don't have.
+
+Verify against a production build (`bun build && bun start`), not dev. One trap:
+the Dashboard reports `Failed to load iframe due to X-Frame-Options: SAMEORIGIN`
+for *any* framing failure, including a wrong registered URL with already-correct
+headers. Trust the browser console's `Framing '<url>' violates …` line instead —
+it names the URL actually being framed.
+
 ## Continuous Integration
 
 A GitHub Actions workflow (`.github/workflows/ci.yml`) runs on every pull request to `main` and on pushes to `main`. It runs type checking, linting, the production build, tests, and `knip`.
@@ -63,8 +106,10 @@ The workflow takes its runtime versions from your manifests, so there's a single
 
 It also caches Bun's install cache between runs, and the test step is a no-op until you add real test files.
 
+<!-- bsmnt:if dotenvx -->
 The build decrypts the committed `.env` with the dotenvx private key, pulled from 1Password: set an **org-level** `OP_SERVICE_ACCOUNT_TOKEN` (a read-only [service account](https://developer.1password.com/docs/service-accounts/) scoped to the `Development` vault) — one secret for every repo — and CI reads the key via the op-ref committed in `.env`. A per-repo `DOTENV_PRIVATE_KEY` secret (`bun run env:setup-remote github`) works as a fallback; builds pass without either (only plaintext / `NEXT_PUBLIC_*` is read).
 
+<!-- bsmnt:endif -->
 ### Sanity environment
 
 The build reads Sanity config from GitHub Actions variables/secrets (empty and harmless until you configure Sanity). Once your repo is on GitHub, the quickest way to set them is: