bsmnt 0.4.3 → 0.6.0

package/dist/modules/features/forms/hubspot/config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HubSpot integration configuration manifest.
+ * Single source of truth for dependencies, scripts, paths, and merge rules.
+ *
+ * The core is dependency-free: it loads HubSpot's official forms script at
+ * runtime and styles the injected DOM with self-contained CSS.
+ */
+import type { IntegrationId } from "../../../../domain/integration.js";
+/**
+ * A path copied only when another integration is already present in the target
+ * project. Used to ship the optional Sanity Studio form picker.
+ */
+export interface ConditionalPath {
+    /** Source path relative to this integration's `files/` directory. */
+    src: string;
+    /** Destination path relative to the project root (before `src/` prefixing). */
+    dest: string;
+    /** Integration that must already exist for the copy to run. */
+    requires: IntegrationId;
+}
+export interface HubSpotIntegrationConfig {
+    name: string;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    scripts: Record<string, string>;
+    additivePaths: string[];
+    mergeFiles: string[];
+    conditionalPaths: ConditionalPath[];
+}
+export declare const hubspotConfig: HubSpotIntegrationConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/modules/features/forms/hubspot/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../../src/modules/features/forms/hubspot/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACpC;AAED,eAAO,MAAM,aAAa,EAAE,wBAoB3B,CAAC"}

package/dist/modules/features/forms/hubspot/config.js

@@ -0,0 +1,25 @@
+/**
+ * HubSpot integration configuration manifest.
+ * Single source of truth for dependencies, scripts, paths, and merge rules.
+ *
+ * The core is dependency-free: it loads HubSpot's official forms script at
+ * runtime and styles the injected DOM with self-contained CSS.
+ */
+export const hubspotConfig = {
+    name: "hubspot",
+    // The core embed loads HubSpot's script at runtime — no extra packages.
+    dependencies: {},
+    devDependencies: {},
+    scripts: {},
+    additivePaths: ["lib/integrations/hubspot"],
+    mergeFiles: [],
+    // The Sanity Studio picker is only useful with Sanity installed.
+    conditionalPaths: [
+        {
+            src: "_sanity-adapter",
+            dest: "lib/integrations/hubspot/sanity",
+            requires: "sanity",
+        },
+    ],
+};
+//# sourceMappingURL=config.js.map

package/dist/modules/features/forms/hubspot/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../src/modules/features/forms/hubspot/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2BH,MAAM,CAAC,MAAM,aAAa,GAA6B;IACtD,IAAI,EAAE,SAAS;IAEf,wEAAwE;IACxE,YAAY,EAAE,EAAE;IAChB,eAAe,EAAE,EAAE;IACnB,OAAO,EAAE,EAAE;IAEX,aAAa,EAAE,CAAC,0BAA0B,CAAC;IAE3C,UAAU,EAAE,EAAE;IAEd,iEAAiE;IACjE,gBAAgB,EAAE;QACjB;YACC,GAAG,EAAE,iBAAiB;YACtB,IAAI,EAAE,iCAAiC;YACvC,QAAQ,EAAE,QAAQ;SAClB;KACD;CACD,CAAC"}

package/dist/paths.d.ts

@@ -4,6 +4,10 @@ export declare const TEMPLATES_DIR: string;
 export declare const TEMPLATE_HOOKS_DIR: string;
 /** Directory containing the Biome linting plugin rules. */
 export declare const PLUGINS_DIR: string;
+/** Directory containing bundled agent skills copied into generated projects. */
+export declare const AGENT_SKILLS_DIR: string;
+/** Node-version guard injected into each scaffolded project; under `src/` so it ships verbatim. */
+export declare const CHECK_NODE_VERSION_FILE: string;
 /**
  * Directory containing the Sanity integration source files.
  * Always resolves to `src/modules/features/cms/sanity/files/` relative to the
@@ -17,4 +21,16 @@ export declare const SANITY_FILES_DIR: string;
  * relative to the project root.
  */
 export declare const SANITY_PAGEBUILDER_FILES_DIR: string;
+/**
+ * Directory containing the HubSpot integration source files.
+ * Always resolves to `src/modules/features/forms/hubspot/files/` relative to the
+ * project root.
+ */
+export declare const HUBSPOT_FILES_DIR: string;
+/**
+ * Directory containing the dotenvx integration source files (the CI guard
+ * workflow and the 1Password key-restore script). Always resolves to
+ * `src/modules/features/env/dotenvx/files/` relative to the project root.
+ */
+export declare const DOTENVX_FILES_DIR: string;
 //# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAaA,6DAA6D;AAC7D,eAAO,MAAM,aAAa,EAAE,MAI3B,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,EAAE,MAIhC,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,WAAW,EAAE,MAA2C,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAQ9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAQ1C,CAAC"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAaA,6DAA6D;AAC7D,eAAO,MAAM,aAAa,EAAE,MAI3B,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,EAAE,MAIhC,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,WAAW,EAAE,MAA2C,CAAC;AAEtE,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,EAAE,MAI9B,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,EAAE,MAKrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAQ9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAQ1C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAQ/B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAQ/B,CAAC"}

package/dist/paths.js

@@ -14,6 +14,10 @@ export const TEMPLATES_DIR = path.join(PROJECT_ROOT, "src", "templates");
 export const TEMPLATE_HOOKS_DIR = path.join(PROJECT_ROOT, "src", "template-hooks");
 /** Directory containing the Biome linting plugin rules. */
 export const PLUGINS_DIR = path.join(PROJECT_ROOT, "plugins");
+/** Directory containing bundled agent skills copied into generated projects. */
+export const AGENT_SKILLS_DIR = path.join(PROJECT_ROOT, "src", "agent-skills");
+/** Node-version guard injected into each scaffolded project; under `src/` so it ships verbatim. */
+export const CHECK_NODE_VERSION_FILE = path.join(PROJECT_ROOT, "src", "assets", "check-node-version.mjs");
 /**
  * Directory containing the Sanity integration source files.
  * Always resolves to `src/modules/features/cms/sanity/files/` relative to the
@@ -27,4 +31,16 @@ export const SANITY_FILES_DIR = path.join(PROJECT_ROOT, "src", "modules", "featu
  * relative to the project root.
  */
 export const SANITY_PAGEBUILDER_FILES_DIR = path.join(PROJECT_ROOT, "src", "modules", "features", "cms", "sanity-pagebuilder", "files");
+/**
+ * Directory containing the HubSpot integration source files.
+ * Always resolves to `src/modules/features/forms/hubspot/files/` relative to the
+ * project root.
+ */
+export const HUBSPOT_FILES_DIR = path.join(PROJECT_ROOT, "src", "modules", "features", "forms", "hubspot", "files");
+/**
+ * Directory containing the dotenvx integration source files (the CI guard
+ * workflow and the 1Password key-restore script). Always resolves to
+ * `src/modules/features/env/dotenvx/files/` relative to the project root.
+ */
+export const DOTENVX_FILES_DIR = path.join(PROJECT_ROOT, "src", "modules", "features", "env", "dotenvx", "files");
 //# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAW,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1D,MAAM,SAAS,GAAW,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAEnD;;;;GAIG;AACH,MAAM,YAAY,GAAW,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAE3D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAW,IAAI,CAAC,IAAI,CAC7C,YAAY,EACZ,KAAK,EACL,WAAW,CACX,CAAC;AAEF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,kBAAkB,GAAW,IAAI,CAAC,IAAI,CAClD,YAAY,EACZ,KAAK,EACL,gBAAgB,CAChB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAW,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAW,IAAI,CAAC,IAAI,CAChD,YAAY,EACZ,KAAK,EACL,SAAS,EACT,UAAU,EACV,KAAK,EACL,QAAQ,EACR,OAAO,CACP,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAW,IAAI,CAAC,IAAI,CAC5D,YAAY,EACZ,KAAK,EACL,SAAS,EACT,UAAU,EACV,KAAK,EACL,oBAAoB,EACpB,OAAO,CACP,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAW,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1D,MAAM,SAAS,GAAW,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAEnD;;;;GAIG;AACH,MAAM,YAAY,GAAW,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAE3D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAW,IAAI,CAAC,IAAI,CAC7C,YAAY,EACZ,KAAK,EACL,WAAW,CACX,CAAC;AAEF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,kBAAkB,GAAW,IAAI,CAAC,IAAI,CAClD,YAAY,EACZ,KAAK,EACL,gBAAgB,CAChB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAW,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AAEtE,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAW,IAAI,CAAC,IAAI,CAChD,YAAY,EACZ,KAAK,EACL,cAAc,CACd,CAAC;AAEF,mGAAmG;AACnG,MAAM,CAAC,MAAM,uBAAuB,GAAW,IAAI,CAAC,IAAI,CACvD,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,wBAAwB,CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAW,IAAI,CAAC,IAAI,CAChD,YAAY,EACZ,KAAK,EACL,SAAS,EACT,UAAU,EACV,KAAK,EACL,QAAQ,EACR,OAAO,CACP,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAW,IAAI,CAAC,IAAI,CAC5D,YAAY,EACZ,KAAK,EACL,SAAS,EACT,UAAU,EACV,KAAK,EACL,oBAAoB,EACpB,OAAO,CACP,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAW,IAAI,CAAC,IAAI,CACjD,YAAY,EACZ,KAAK,EACL,SAAS,EACT,UAAU,EACV,OAAO,EACP,SAAS,EACT,OAAO,CACP,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAW,IAAI,CAAC,IAAI,CACjD,YAAY,EACZ,KAAK,EACL,SAAS,EACT,UAAU,EACV,KAAK,EACL,SAAS,EACT,OAAO,CACP,CAAC"}

package/package.json

@@ -1,9 +1,12 @@
 {
 	"name": "bsmnt",
-	"version": "0.4.3",
-	"packageManager": "bun@1.2.20",
+	"version": "0.6.0",
+	"packageManager": "bun@1.3.14",
 	"description": "CLI to scaffold basement projects and add integrations",
 	"type": "module",
+	"engines": {
+		"node": ">=24"
+	},
 	"workspaces": [
 		".",
 		"src/templates/*"
@@ -20,12 +23,18 @@
 		"!src/templates/*/.next",
 		"!src/templates/*/bun.lock",
 		"src/template-hooks",
+		"src/agent-skills",
 		"src/modules/features/cms/sanity/files",
+		"src/modules/features/cms/sanity-pagebuilder/files",
+		"src/modules/features/env/dotenvx/files",
+		"src/assets",
 		"plugins"
 	],
 	"scripts": {
+		"preinstall": "node src/assets/check-node-version.mjs",
 		"build": "tsc",
 		"check": "tsc --noEmit",
+		"test": "bun test src",
 		"dev": "tsx src/index.ts",
 		"lint": "biome check .",
 		"lint:fix": "biome check --write --unsafe .",
@@ -51,7 +60,9 @@
 		"lint:all": "turbo run lint --filter=bsmnt-next-starter --filter=bsmnt-webgpu-starter --filter=bsmnt-experiments-starter",
 		"version-canary": "changeset version --snapshot canary",
 		"release-canary": "changeset publish --tag canary --no-git-tag",
-		"test:templates": "bash scripts/test-templates.sh"
+		"test:templates": "bash scripts/test-templates.sh",
+		"link:local": "bash scripts/build-and-link.sh",
+		"unlink:local": "bash scripts/build-and-link.sh --unlink"
 	},
 	"keywords": [
 		"webgpu",
@@ -63,23 +74,24 @@
 	"author": "",
 	"license": "ISC",
 	"dependencies": {
-		"@sanity/client": "^7.15.0",
-		"@sanity/image-url": "^2.0.3",
-		"@sanity/vision": "^5.11.0",
+		"@sanity/client": "^7.22.1",
+		"@sanity/image-url": "^2.1.1",
+		"@sanity/vision": "^5.30.0",
 		"commander": "^13.1.0",
+		"dotenv": "^17.4.2",
 		"fs-extra": "^11.3.3",
-		"next-sanity": "^12.1.0",
+		"next-sanity": "^13.0.10",
 		"ora": "^9.1.0",
 		"picocolors": "^1.1.1",
 		"prompts": "^2.4.2",
-		"sanity": "^5.11.0"
+		"sanity": "^5.30.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.14",
 		"@changesets/changelog-github": "^0.5.2",
 		"@changesets/cli": "^2.29.8",
 		"@types/fs-extra": "^11.0.4",
-		"@types/node": "^25.2.3",
+		"@types/node": "^24.13.1",
 		"@types/prompts": "^2.4.9",
 		"cross-env": "^10.1.0",
 		"lefthook": "^1.13.0",

package/src/agent-skills/json-ld/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: json-ld
+description: >-
+  Add schema.org JSON-LD structured data when building components or pages
+  that render structured content (job listings, FAQs, events, videos,
+  work/product lists, articles, breadcrumbs). Use BEFORE hand-writing any
+  <script type="application/ld+json"> tag — this project ships typed
+  generators for all common schemas.
+---
+
+# JSON-LD Structured Data
+
+This project ships typed JSON-LD generators and a `<JsonLd />` component in
+`lib/utils/json-ld.tsx`. Never hand-roll a `<script type="application/ld+json">`
+tag — import a generator and render it through `<JsonLd />` (it serializes and
+escapes `<` for safe embedding).
+
+```tsx
+import { JsonLd, generateJobPostingJsonLd } from "@/lib/utils/json-ld"
+
+// inside a server component
+{jobs.map((job) => (
+  <JsonLd
+    key={job.id}
+    data={generateJobPostingJsonLd({
+      title: job.title,
+      description: job.description,
+      datePosted: job.publishedAt,
+      employmentType: job.type,
+      organizationName: job.company,
+    })}
+  />
+))}
+```
+
+## Which tier owns the data?
+
+1. **Site-wide identity** (`Organization`, `WebSite`) — already emitted by the
+   site layout. Never re-emit these from components or pages. With Sanity,
+   editors manage it in Studio → Layout → Structured Data; Company Data social
+   links merge into `sameAs` via their "Include in Structured Data" toggle.
+2. **Page-level** (Sanity projects only) — editors attach predefined JSON-LD
+   blocks (FAQ, Event, Video, Job Posting, Software Application, Item List,
+   Custom) to a page under SEO & Metadata → Structured Data (JSON-LD). The
+   page document component already renders them. If the content is page-owned
+   and editor-managed, point editors to that field instead of coding it.
+3. **Component-level** — when a component itself renders structured content
+   (from props or CMS data), emit JSON-LD next to the markup using the
+   generators below.
+
+## Component → schema mapping
+
+| Component renders                          | Generator                            |
+| ------------------------------------------ | ------------------------------------ |
+| Job / career listings                      | `generateJobPostingJsonLd` (per job) |
+| FAQ / accordion Q&A                        | `generateFaqJsonLd`                  |
+| Events / agenda                            | `generateEventJsonLd` (per event)    |
+| Video player or embed                      | `generateVideoJsonLd`                |
+| Curated lists (work, products, post index) | `generateItemListJsonLd`             |
+| Article / blog post body                   | `generateArticleJsonLd`              |
+| Breadcrumb navigation                      | `generateBreadcrumbJsonLd`           |
+| App / tool promo section                   | `generateSoftwareApplicationJsonLd`  |
+| Plain marketing pages                      | `generateWebPageJsonLd`              |
+| Logo walls, testimonials, generic heroes   | none — don't force structured data   |
+
+## Rules
+
+- Emit from **server components** so the script tags are in the initial HTML.
+- One `<JsonLd />` per entity — map each job/event to its own tag instead of
+  merging unrelated entities into one block.
+- Only emit when the schema's required fields exist (e.g. `JobPosting` needs
+  title, description, datePosted). Skip the tag entirely rather than emitting
+  partial data.
+- Sanity data: run values through `stegaClean` from `next-sanity` before they
+  reach JSON-LD (see `components/layout/json-ld` for the pattern), otherwise
+  invisible stega characters leak into the emitted markup.
+- Don't duplicate: if a page-level Sanity block already covers the content,
+  don't also emit it from the component.
+- Generators absolutize app-relative URLs (`/jobs/123`) automatically; pass
+  absolute URLs (including Sanity CDN assets) as-is.
+
+## Verify
+
+Check `view-source:` for each `application/ld+json` script and validate with
+https://validator.schema.org or https://search.google.com/test/rich-results.

package/src/agent-skills/manage-env/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: manage-env
+description: >-
+  Use when adding or changing an environment variable in a project that uses our
+  dotenvx setup. Decides secret vs trivial config: trivial/`NEXT_PUBLIC_*` the
+  agent handles fully, but for a secret the agent only wires the key in code
+  (process.env, validation schema, types) and hands the value-setting to the
+  human — it never types a secret value into a command. Triggers on "add an env
+  var", "new environment variable", "set an API key/token/secret", "put X in
+  .env", "encrypt env", or editing any `.env*` file.
+---
+
+# Add or change an environment variable
+
+This project uses **dotenvx**. Env files:
+
+- `.env` — shared / development, committed **encrypted**
+- `.env.preview`, `.env.production` — per-environment overrides, committed encrypted (created on demand)
+- `.env.local` — plaintext, gitignored (personal local overrides)
+- `.env.keys` — private keys, gitignored (backed up in the team password manager)
+
+Scripts run `dotenvx run -f .env.$VERCEL_ENV -f .env -- …`, so the env-specific
+file overrides `.env`. A **gitleaks** pre-commit hook + CI scan are the real
+enforcement — this skill just makes the right choice the default.
+
+## 1. Secret or trivial config?
+
+- **Secret** — API keys, tokens, DB URLs, anything you'd rotate if it leaked.
+- **Trivial** — public base URLs, feature flags, anything `NEXT_PUBLIC_*` (it
+  ships to the browser anyway). Plaintext is fine; encrypting buys nothing.
+
+## 2a. Secret → never put the value in a command
+
+A raw secret in a command (`env:set KEY <value>`) leaks the plaintext into the
+tool call and the conversation context. So split the work:
+
+- **Agent — code wiring only, never the value.** Read it via `process.env.KEY`,
+  add it to the env validation schema / types if the project has one, and add a
+  placeholder line to `.env.example`. Document the key name and where it's used.
+- **Human — owns the value.** Either run `bun run env:set KEY <value>` yourself
+  (`--preview` / `--prod` for per-environment), or set it directly in the Vercel
+  environment. `env:set` encrypts in place and adds the matching
+  `DOTENV_PRIVATE_KEY*` to `.env.keys`.
+- **Verify (agent):** only via `git diff` showing `KEY=encrypted:…`. Never run
+  `env:view` on a secret — it prints the decrypted value into context.
+- Each `DOTENV_PRIVATE_KEY*` must exist on the matching Vercel environment and as a
+  CI secret, or it won't decrypt there.
+- **Edge runtime caveat.** dotenvx only decrypts in the Node runtime (via
+  `instrumentation.ts`). A secret read in `middleware.ts` or a `runtime = "edge"`
+  route is **not** decrypted from `.env` — it must be set directly as a Vercel env
+  var. The encrypted `.env` covers Node functions + build, not the edge.
+
+## 2b. Trivial config → plaintext
+
+Add it plaintext — no encryption — with `bun run env:set KEY value --plain`, or
+just append a line to the file:
+
+```bash
+NEXT_PUBLIC_FOO=bar
+```
+
+gitleaks ignores non-secret plaintext, so it won't fail the scan.
+
+## Rule
+
+Never commit a real secret in plaintext. If one lands there, bulk-encrypt it in
+place with `bun run env:encrypt-all` (no value typed).

package/src/assets/check-node-version.mjs

@@ -0,0 +1,22 @@
+// Reads engines.node from cwd's package.json so one file works in this repo and
+// every project it's injected into.
+import { readFileSync } from "node:fs";
+
+let required = Number.NaN;
+try {
+	const { engines } = JSON.parse(readFileSync("package.json", "utf8"));
+	required = Number(engines?.node?.match(/\d+/)?.[0]);
+} catch {
+	// Can't read or parse package.json — nothing to enforce, let install proceed.
+	process.exit(0);
+}
+
+if (
+	!Number.isNaN(required) &&
+	Number(process.versions.node.split(".")[0]) < required
+) {
+	console.error(
+		`\nNode ${required}+ required. You have ${process.versions.node}.\n`,
+	);
+	process.exit(1);
+}

package/src/modules/features/cms/sanity/files/app/blog/[slug]/page.tsx

@@ -6,6 +6,9 @@ import {
 	ALL_ARTICLES_QUERY,
 	ARTICLE_QUERY,
 } from "@/lib/integrations/sanity/queries";
+import { urlForImage } from "@/lib/integrations/sanity/utils/image";
+import { buildPageJsonLd } from "@/lib/integrations/sanity/utils/page-json-ld";
+import { generateArticleJsonLd, JsonLd } from "@/lib/utils/json-ld";
 
 export async function generateStaticParams() {
 	if (!client) return [];
@@ -30,28 +33,52 @@ export default async function BlogArticlePage({ params }: Props) {
 
 	if (!article) return notFound();
 
+	const articleUrl = `/blog/${slug}`;
+	const articleImage = article.featuredImage
+		? urlForImage(article.featuredImage).url()
+		: article.metadata?.image
+			? urlForImage(article.metadata.image).url()
+			: undefined;
+	const pageJsonLd = buildPageJsonLd(article.metadata?.jsonLd);
+
 	return (
-		<article className="container mx-auto px-4 py-8 max-w-4xl">
-			<header className="mb-8">
-				<h1 className="text-4xl font-bold mb-4">{article.title}</h1>
-				{article.excerpt && (
-					<p className="text-lg text-gray-600">{article.excerpt}</p>
-				)}
-				<div className="flex gap-4 mt-4 text-sm text-gray-500">
-					{article.author && <span>By {article.author}</span>}
-					{article.publishedAt && (
-						<time dateTime={article.publishedAt}>
-							{new Date(article.publishedAt).toLocaleDateString()}
-						</time>
+		<>
+			<JsonLd
+				data={generateArticleJsonLd({
+					title: article.metadata?.title || article.title || "",
+					url: articleUrl,
+					description: article.metadata?.description || article.excerpt,
+					image: articleImage,
+					datePublished: article.publishedAt,
+					dateModified: article._updatedAt,
+					authorName: article.author,
+				})}
+			/>
+			{pageJsonLd.map(({ key, data }) => (
+				<JsonLd key={key} data={data} />
+			))}
+			<article className="container mx-auto px-4 py-8 max-w-4xl">
+				<header className="mb-8">
+					<h1 className="text-4xl font-bold mb-4">{article.title}</h1>
+					{article.excerpt && (
+						<p className="text-lg text-gray-600">{article.excerpt}</p>
 					)}
-				</div>
-			</header>
-
-			{article.content && (
-				<div className="prose max-w-none">
-					<RichText content={article.content} />
-				</div>
-			)}
-		</article>
+					<div className="flex gap-4 mt-4 text-sm text-gray-500">
+						{article.author && <span>By {article.author}</span>}
+						{article.publishedAt && (
+							<time dateTime={article.publishedAt}>
+								{new Date(article.publishedAt).toLocaleDateString()}
+							</time>
+						)}
+					</div>
+				</header>
+
+				{article.content && (
+					<div className="prose max-w-none">
+						<RichText content={article.content} />
+					</div>
+				)}
+			</article>
+		</>
 	);
 }

package/src/modules/features/cms/sanity/files/app/blog/page.tsx

@@ -0,0 +1,54 @@
+import Link from "next/link";
+import { sanityFetch } from "@/lib/integrations/sanity/live";
+import { ALL_ARTICLES_QUERY } from "@/lib/integrations/sanity/queries";
+
+export const metadata = {
+	title: "Blog",
+	alternates: {
+		types: { "application/rss+xml": "/feed.xml" },
+	},
+};
+
+export default async function BlogIndexPage() {
+	const { data: articles } = await sanityFetch({ query: ALL_ARTICLES_QUERY });
+
+	return (
+		<main className="container mx-auto px-4 py-8 max-w-4xl">
+			<h1 className="text-4xl font-bold mb-8">Blog</h1>
+
+			{articles && articles.length > 0 ? (
+				<ul className="flex flex-col gap-8">
+					{articles.map((article) => {
+						const slug = article.slug?.current;
+						if (!slug) return null;
+
+						return (
+							<li key={article._id}>
+								<article>
+									<h2 className="text-2xl font-semibold mb-2">
+										<Link href={`/blog/${slug}`} className="hover:underline">
+											{article.title}
+										</Link>
+									</h2>
+									{article.excerpt && (
+										<p className="text-gray-600 mb-2">{article.excerpt}</p>
+									)}
+									<div className="flex gap-4 text-sm text-gray-500">
+										{article.author && <span>By {article.author}</span>}
+										{article.publishedAt && (
+											<time dateTime={article.publishedAt}>
+												{new Date(article.publishedAt).toLocaleDateString()}
+											</time>
+										)}
+									</div>
+								</article>
+							</li>
+						);
+					})}
+				</ul>
+			) : (
+				<p className="text-gray-600">No articles published yet.</p>
+			)}
+		</main>
+	);
+}

package/src/modules/features/cms/sanity/files/app/feed.xml/route.ts

@@ -0,0 +1,36 @@
+import { client } from "@/lib/integrations/sanity/client";
+import { ALL_ARTICLES_QUERY } from "@/lib/integrations/sanity/queries";
+import { generateRssFeed, rssErrorResponse } from "@/lib/utils/rss";
+import { getBaseUrl } from "@/lib/utils/url";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+	const baseUrl = getBaseUrl();
+	if (!client) return rssErrorResponse();
+
+	try {
+		const articles = await client.fetch(ALL_ARTICLES_QUERY);
+
+		const items = (articles ?? [])
+			.filter((article) => article.slug?.current && !article.metadata?.noIndex)
+			.map((article) => ({
+				title: article.title ?? "Untitled",
+				link: `${baseUrl}/blog/${article.slug?.current}`,
+				description: article.excerpt ?? undefined,
+				pubDate: article.publishedAt ?? undefined,
+				authors: article.author ? [article.author] : undefined,
+			}));
+
+		return generateRssFeed({
+			title: `${new URL(baseUrl).hostname} Blog`,
+			link: `${baseUrl}/blog`,
+			description: "Latest articles",
+			feedUrl: `${baseUrl}/feed.xml`,
+			items,
+		});
+	} catch (error) {
+		console.error("Error generating RSS feed:", error);
+		return rssErrorResponse();
+	}
+}

package/src/modules/features/cms/sanity/files/components/sanity/structured-data.tsx

@@ -0,0 +1,83 @@
+import { stegaClean } from "next-sanity";
+import { sanityFetch } from "@/lib/integrations/sanity/live";
+import { STRUCTURED_DATA_QUERY } from "@/lib/integrations/sanity/queries";
+import {
+	generateOrganizationJsonLd,
+	generateWebSiteJsonLd,
+	JsonLd,
+} from "@/lib/utils/json-ld";
+
+type StructuredDataResult = {
+	name?: string | null;
+	legalName?: string | null;
+	description?: string | null;
+	url?: string | null;
+	logo?: string | null;
+	sameAs?: (string | null)[] | null;
+	contactPoint?: {
+		email?: string | null;
+		telephone?: string | null;
+		contactType?: string | null;
+	} | null;
+	address?: {
+		streetAddress?: string | null;
+		locality?: string | null;
+		region?: string | null;
+		postalCode?: string | null;
+		country?: string | null;
+	} | null;
+} | null;
+
+const nonEmpty = (value: unknown): string | undefined => {
+	const cleaned = stegaClean(value);
+	return typeof cleaned === "string" && cleaned.trim() !== ""
+		? cleaned
+		: undefined;
+};
+
+/**
+ * Site-wide Organization + WebSite JSON-LD from the Structured Data
+ * singleton, with the static app values as fallback.
+ */
+export async function SanityStructuredData({
+	fallbackName,
+	fallbackDescription,
+	fallbackLogo,
+}: {
+	fallbackName: string;
+	fallbackDescription?: string;
+	fallbackLogo?: string;
+}) {
+	const { data } = await sanityFetch({ query: STRUCTURED_DATA_QUERY });
+	// Deep-clean stega artifacts up front so nested objects (contactPoint,
+	// address) never leak visual-editing markers into the emitted JSON-LD.
+	const structuredData = stegaClean(data as unknown as StructuredDataResult);
+
+	const name = nonEmpty(structuredData?.name) ?? fallbackName;
+	const description =
+		nonEmpty(structuredData?.description) ?? fallbackDescription;
+	const url = nonEmpty(structuredData?.url);
+	const logo = nonEmpty(structuredData?.logo) ?? fallbackLogo;
+
+	const sameAs = (structuredData?.sameAs ?? [])
+		.map(nonEmpty)
+		.filter((value): value is string => Boolean(value));
+
+	return (
+		<>
+			<JsonLd data={generateWebSiteJsonLd({ name, url, description })} />
+			<JsonLd
+				data={generateOrganizationJsonLd({
+					name,
+					url,
+					logo,
+					description,
+					legalName: nonEmpty(structuredData?.legalName),
+					sameAs: sameAs.length ? sameAs : undefined,
+					contactPoint: structuredData?.contactPoint,
+					address: structuredData?.address,
+				})}
+			/>
+		</>
+	);
+}