joelklemmer-com

Nx monorepo for JoelKlemmer.com: a multilingual authority-verification site and Briefing Room (governed retrieval + reasoning) on Next.js 16 (App Router), with shared libraries, MDX content, and a verify chain that gates changes.

What this is

• Public site: Executive Brief, Work, Operating System, Writing, Contact, Public Record, Case Studies, Books, Media, Q&A, policies, and supporting routes — all behind locale-prefixed URLs ([locale]/...).
• Governance: Presentation Governance Framework (PGF) and Content OS constrain tone, proof linkage, and page intent (enforced by Nx validators).
• Intelligence: Optional vector (e.g. Pinecone) and graph (e.g. Neo4j) backends for retrieval; active dataset version via env and artifacts/intelligence/active-version.json; promotion/rollback are documented under docs/briefing-room/.
• i18n: 50 active locales (English + 49); registry in libs/i18n/src/locales.ts (ACTIVE_LOCALES). Primary pinned order: en, he, uk, es.

Stack

• Runtime: Node ≥20.19.0, <21 (package.json engines)
• Package manager: pnpm (see packageManager in package.json)
• Build: Nx 22 with @nx/next, @nx/playwright, @nx/eslint
• App: apps/web — Next.js 16, next-intl, MDX (next-mdx-remote)
• Content: content/ (MDX), libs/i18n/src/messages/<locale>/ (JSON namespaces)
• Validation: tools/validate-*.ts exposed as Nx targets on project web (apps/web/project.json)

Repository layout

Path	Role
apps/web	Next.js app; thin route files under src/app/[locale]/
apps/web-e2e	Playwright: e2e, a11y, visual
libs/*	Shared libraries (screens, sections, ui, i18n, seo, content, intelligence, …); apps import libs only
content/	MDX: brief, case studies, proof, public record, books, writing, …
knowledge/	Institutional / vault-style knowledge (parallel to content/; not the Next public/ tree)
tools/	Validators and scripts (nx run web:<target>)
docs/	Architecture, subsystems, ops, intelligence, i18n, quality gates
artifacts/	Intelligence outputs (e.g. artifacts/intelligence/active-version.json); operational, not MDX source
apps/web/public/	Canonical static assets for the Next app (images, manifests, media)
public/ (repo root)	Minimal exception tree (e.g. ai-discovery/ copied into the app at build); not a second full public/

AI discovery (public): /ai-discovery/ai-discovery.json; APIs /api/ai/knowledge, /api/ai/questions (locale-aware). See docs/intelligence/ai-knowledge-publication-audit.md.

Local development

Action	Command
Install	pnpm install
Dev server	pnpm dev or pnpm serve (sets NX_CLOUD=false via workspace scripts)
Production build	pnpm build → nx build web (via tools/run-build.cjs)
Start (after build)	pnpm start → nx run web:start
Full verify gate	pnpm run ci:verify or pnpm nx run web:verify --verbose

Do not run raw nx dev web without NX_CLOUD=false (or the pnpm scripts), or you may see Nx Cloud errors in local-only workflows.

Briefing Room / intelligence dev: web:dev and web:serve copy active-version metadata and set intelligence env (see apps/web/project.json → dev / serve).

Verify and CI

• Authoritative order: apps/web/project.json → targets.verify.options.commands.
• Human-readable list: VERIFY.md (must stay in sync with project.json).
• Per-gate detail: docs/platform/quality-gates.md.
• CI vs release gate (exact diff): docs/operations/verification-policy.md.

Two tiers (do not confuse them):

Tier	What	Meaning
PR CI	verify-fast in .github/workflows/ci.yml	Fast subset + web:test. Not the full release chain.
Release gate	.github/workflows/release-verify.yml on push to main	Runs pnpm nx run web:verify — same as pnpm run ci:verify (after install). Required for “green = release-ready.”

A green PR does not imply a green full web:verify. main must pass Release verify (full web:verify) (or you must run pnpm run ci:verify locally before deploy). Optionally add that job as a required status check on main in GitHub branch protection.

Documentation integrity

pnpm nx run web:docs-integrity-validate

Environment (essentials)

• Local: Copy from .env.example where present; never commit secrets.
• Node heap (build / verify / dev): pnpm dev, pnpm build, pnpm nx run web:verify, and pnpm run ci:verify align with NODE_OPTIONS=--max-old-space-size=24576 (24 GiB; tools/merge-node-options-heap.cjs, apps/web/project.json targets, package.json scripts) so large Next.js builds do not OOM. Nx defaults to parallel: 4 in nx.json to limit concurrent tasks. To merge with other flags, use tools/merge-node-options-heap.cjs or set NODE_OPTIONS in .env.local (see .env.example). Details: docs/audits/local-memory-and-execution-hardening-report.md.
• Contact / email: CONTACT_TO_EMAIL, CONTACT_FROM_EMAIL, EMAIL_PROVIDER_API_KEY (or RESEND_API_KEY); optional Upstash for rate limiting — see .env.example.
• Production Briefing Room / intelligence: Explicit flags and providers (Pinecone, Neo4j, OpenAI, etc.) are documented in docs/briefing-room/production-intelligence-config.md. Do not rely on implicit defaults for customer traffic.

Operations and launch documentation

Need	Document
Ops hub (runbooks, links)	docs/operations/README.md
Governance audit (this pass)	docs/operations/documentation-governance-audit.md
CI, local dev, incidents	docs/ops/README.md, docs/ops/ci.md
Dataset promotion / rollback	docs/briefing-room/intelligence-promotion.md
Deployment gate (GitHub)	docs/briefing-room/deployment-gate-ci.md
Vercel	docs/devops/vercel-deployment.md
Locale / translation	docs/i18n/locale-integrity.md, docs/i18n/autonomous-translation-system.md
Doc index	docs/index.md

Guardrails (short)

• Route page.tsx files stay thin (~120 lines); composition in libs/screens and libs/sections.
• User-facing strings: next-intl or MDX; no hardcoded copy in app/ui.
• Layering: apps → libs only; libs do not import apps.
• Locked routes/locales per .cursorrules and product policy — do not change slugs without explicit instruction.

Root documentation

Document	Purpose
ARCHITECTURE.md	Nx layering, libraries, subsystems
VERIFY.md	Full web:verify sequence
AGENTS.md	Agents, verify chain, file scope
CONTRIBUTING.md	Workflow and PR expectations

---

Local development note: the canonical dev command is pnpm dev. On Windows, see scripts/dev-web-local.ps1 if needed.