chore(audit): execute 2026-06-04 (2055) audit — docs CI config triggers, env-var docs (#125)

* ci(docs): trigger linkcheck on wrangler/bunfig/osv-scanner config changes

These files affect the docs build, install behavior, and vuln scan but were absent from the linkcheck push paths, so a config-only push could land on main without the build/linkcheck running.

Audit: F002

* docs(docs): document BORINGSTACK_UI_DIR/API_DIR build-time path overrides

These env vars override the sibling-app roots used for catalog generation (for shallow clones / worktrees / non-monorepo layouts) but were undocumented. Documented at the resolveTemplateRoot resolution point and the pre-push pass-through site, where a debugger lands. They are internal contributor knobs, not product config, so they stay out of the published docs site.

Audit: F004

* docs(api): document optional dev-only PREVIEW_PORT in .env.example

preview.ts reads process.env.PREVIEW_PORT directly (outside the validated schema) because it only runs under bun run preview:templates. Documented as a commented stub matching the EMAIL_TEMPLATES_DIR convention — an uncommented key would trip the env-cascade-drift guardrail.

Audit: F003

Author: agjs

.github/workflows/apps-docs-linkcheck.yml

@@ -14,6 +14,13 @@ on:
       - "apps/docs/astro.config.mjs"
       - "apps/docs/package.json"
       - "apps/docs/bun.lock"
+      # Build/install/scan config: wrangler (Cloudflare asset + build settings),
+      # bunfig (install behavior), osv-scanner (vuln allowlist). A config-only
+      # push must still rebuild + linkcheck so a broken config can't land
+      # unverified.
+      - "apps/docs/wrangler.jsonc"
+      - "apps/docs/bunfig.toml"
+      - "apps/docs/osv-scanner.toml"
       - ".github/workflows/apps-docs-linkcheck.yml"
       # Catalog inputs: the generated docs data is derived from sibling-app
       # scripts/README.md, package.json scripts, and lint-meta export-catalog.

apps/api/.env.example

@@ -210,3 +210,11 @@ VALKEY_DB=0
 # Optional. Override only if you copy the precompiled email templates
 # (src/templates/email/dist) to a non-default location in your image.
 # EMAIL_TEMPLATES_DIR=/app/src/templates/email/dist
+
+# Optional, dev-only. Port for the email-template preview server
+# (`bun run preview:templates`); defaults to 3002. Read directly from the
+# environment rather than the validated env schema because it never runs in
+# the deployed app — so it stays commented here (an uncommented key would trip
+# the env-cascade-drift guardrail, which requires every .env.example key to
+# exist in src/config/env/schema.ts).
+# PREVIEW_PORT=3002

apps/docs/scripts/docs-catalog-lib.mjs

@@ -5,6 +5,18 @@ import { fileURLToPath } from "node:url";
 
 const DOCS_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
+/*
+ * Build-time only. Resolves a sibling template app's root for catalog
+ * generation. By default it assumes the monorepo layout (apps/<siblingName>
+ * next to apps/docs). Two optional env overrides exist for setups where that
+ * assumption breaks — shallow CI clones, isolated worktrees, or docs built
+ * outside the monorepo:
+ *   - BORINGSTACK_UI_DIR  — absolute path to the ui app (sibling default: ../ui)
+ *   - BORINGSTACK_API_DIR — absolute path to the api app (sibling default: ../api)
+ * Empty/unset falls back to the sibling path. These are internal contributor
+ * knobs, not product config, so they are documented here at the resolution
+ * point rather than in the published docs site.
+ */
 export function resolveTemplateRoot(envKey, siblingName) {
   const fromEnv = process.env[envKey];
 

apps/docs/scripts/pre-push.sh

@@ -28,6 +28,10 @@ fail()    { c_red   "✗ $*"; exit 1; }
 ok()      { c_green "✓ $*"; }
 
 step "1/4 Docs data (monorepo apps)"
+# BORINGSTACK_UI_DIR / BORINGSTACK_API_DIR: optional absolute-path overrides
+# for the sibling app roots (defaults: ../ui, ../api). See resolveTemplateRoot
+# in scripts/docs-catalog-lib.mjs. Pass-through here so a non-monorepo layout
+# (shallow clone / worktree) can still locate the catalog source apps.
 BORINGSTACK_UI_DIR="$BORINGSTACK_UI_DIR" \
 BORINGSTACK_API_DIR="$BORINGSTACK_API_DIR" \
   bun run check:docs-data || fail "docs data drift: run bun run generate:docs-data from apps/docs"