The-Running-Dev
diff --git a/‎.github/workflows/docs-ci.yml‎
Lines changed: 29 additions & 4 deletions b/‎.github/workflows/docs-ci.yml‎
Lines changed: 29 additions & 4 deletions
diff --git a/‎.github/workflows/docs-deploy.yml‎
Lines changed: 21 additions & 0 deletions b/‎.github/workflows/docs-deploy.yml‎
Lines changed: 21 additions & 0 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 25 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎agent.md‎
Lines changed: 12 additions & 1 deletion b/‎agent.md‎
Lines changed: 12 additions & 1 deletion
diff --git a/‎build/Merge-LandingPage.ps1‎
Lines changed: 88 additions & 0 deletions b/‎build/Merge-LandingPage.ps1‎
Lines changed: 88 additions & 0 deletions
@@ -1,15 +1,17 @@
 name: Docs CI
 
 # Everything documentation needs except deploy: check the authored Markdown,
-# then build the site to prove it still builds. No path filters -- both jobs
-# are meant to be required status checks, and a required check that never runs
-# leaves a pull request permanently blocked.
+# then build the combined site (docs + landing page) to prove it still builds.
+# No path filters -- both jobs are meant to be required status checks, and a
+# required check that never runs leaves a pull request permanently blocked.
 #
 # The gate and the build are not the same check. Docusaurus fails on unresolved
 # routes inside the site; the gate covers what the site build never sees --
 # README.md, which is not part of the site at all, plus relative link targets,
 # heading anchors, product-name casing, and drift between a generated file and
-# its source.
+# its source. Neither one checks that the landing page (site/) still merges
+# cleanly onto the docs build -- that is what the verify job's extra steps are
+# for, so a PR proves the deploy path before it can run for real.
 
 "on":
     pull_request:
@@ -64,6 +66,29 @@ jobs:
             - name: Build documentation
               run: /template/scripts/docs-build.ps1 -SourceDocs ./docs -OutputPath artifacts/docs
 
+            # The landing page is a second, independent project (site/) sharing
+            # this one GitHub Pages deployment: it serves "/", the docs serve
+            # "/docs". The base image already has Node -- no setup-node needed.
+            #
+            # `check` runs format:check, lint, typecheck, vitest and the build
+            # (site/package.json), not just the build. A bare `build` would let
+            # a broken component test or a missing Open Graph tag merge and
+            # deploy as long as the bundle still compiled -- `check` is what a
+            # contributor runs locally before pushing, made a required step
+            # here too, not a weaker CI-only substitute for it.
+            - name: Build and verify landing page
+              run: |
+                  npm --prefix site ci
+                  npm --prefix site run check
+
+            # Overlays the landing page onto the docs build -- overwrites the
+            # docs build's generated-from-README root index.html, merges in
+            # the landing page's assets, and refuses to proceed if anything
+            # under artifacts/docs/docs/ changed. See build/Merge-LandingPage.ps1
+            # for why the two builds never collide.
+            - name: Merge landing page into documentation build
+              run: ./build/Merge-LandingPage.ps1 -LandingDist site/dist -DocsOutput artifacts/docs
+
             # Run the same archiving step docs-deploy.yml uses, so the deploy
             # path is covered before merge rather than after it. This action
             # tars the site with `tar --hard-dereference`, which fails outright
 
@@ -53,6 +53,27 @@ jobs:
             - name: Build Documentation
               run: /template/scripts/docs-build.ps1 -SourceDocs ./docs -OutputPath artifacts/docs
 
+            # The landing page is a second, independent project (site/) sharing
+            # this one GitHub Pages deployment: it serves "/", the docs serve
+            # "/docs". The base image already has Node -- no setup-node needed.
+            #
+            # `check`, not a bare build -- see docs-ci.yml's verify job, which
+            # runs the same command. This job is the one that actually runs on
+            # a push to main (verify skips push events), so it is also the
+            # last thing standing between a broken landing page and a real
+            # deploy if a check was ever bypassed getting there.
+            - name: Build and verify landing page
+              run: |
+                  npm --prefix site ci
+                  npm --prefix site run check
+
+            # Overlays the landing page onto the docs build -- see
+            # build/Merge-LandingPage.ps1, and the same step in docs-ci.yml's
+            # verify job, which proves this on every PR before it ever runs
+            # here on push to main.
+            - name: Merge landing page into documentation build
+              run: ./build/Merge-LandingPage.ps1 -LandingDist site/dist -DocsOutput artifacts/docs
+
             - name: Upload Pages Artifact
               uses: actions/upload-pages-artifact@v5
               with:
 
@@ -0,0 +1,25 @@
+# Agent Instructions
+
+This file exists for tools that look for `AGENTS.md` by convention. It is a pointer, not a
+copy — the instructions live in two files, and duplicating them here would give the
+repository two answers to every question.
+
+| Read | For |
+|---|---|
+| [`CLAUDE.md`](CLAUDE.md) | **Standing instructions.** What this project is, where the specs and source live, the docs-site tooling, working conventions, and the drift hazards this repo keeps hitting. Start here. |
+| [`agent.md`](agent.md) | **Lessons learned the hard way.** Retrospective notes — token economy, what worked, repo-specific drift hazards, open concerns. |
+
+Both apply regardless of which agent or tool is reading them. Nothing in either is specific
+to one assistant except the names of the tools it describes, and those are named accurately
+because getting them wrong sends the reader to paths that do not exist.
+
+## Why this is a pointer
+
+An earlier version of this file was a full copy of `CLAUDE.md` with every occurrence of one
+assistant's name mechanically replaced by another's. That rewrote nine real references into
+paths and packages that do not exist — `~/.Codex/skills/graphify/`, `npx Codex-mem doctor`,
+`/Codex-mem:learn-codebase` — while leaving 14 KB of otherwise identical prose free to drift
+from its source.
+
+A duplicate that can disagree with its original is the failure mode `CLAUDE.md` itself
+tracks, applied to the instructions. One file, one answer.
@@ -35,6 +35,13 @@ only when it would have changed a decision.
   A pattern built from the text you changed confirms your edits instead of finding your misses.
   **Removals are where this bites**: a bad edit contradicts something visibly, a missed removal
   is silent.
+- **Pull the real image before reasoning about it.** Merging the landing page (`site/`, a Vite
+  build) onto the docs build (`docs/`, Docusaurus) meant one real question: do their `assets/`
+  folders collide? Guessing wrong would have silently overwritten one build's JS with the
+  other's. `docker pull ghcr.io/the-running-dev/docs-template` and running the actual build
+  answered it in two commands: Docusaurus nests under `assets/css/` and `assets/js/`; Vite
+  writes flat hashed files straight into `assets/`. Never touch. `build/Merge-LandingPage.ps1`
+  ships on that verified fact, not an assumption about how either bundler works.
 - **Spec before code.** Building ahead of spec is where drift starts. Asked to "keep going"
   into code, we stopped and wrote the core spec (`04-core`) first — which immediately
   exposed that `03`'s kind-state duplicated envelope fields. That reconciliation would have
@@ -84,7 +91,11 @@ only when it would have changed a decision.
   Docusaurus 3, port 3000, and the local `sidebar.ts`. A production build passed with no
   leftover template docs in the sidebar. Re-verify when the base image tag changes. `/docs/`
   now serves the generated homepage (`docs/docs/index.md`); `/docs/engine/vision` is the
-  first spec page beneath it, and the bare domain forwards to `/docs/`.
+  first spec page beneath it. **Once `feature/landing-page` merges, the bare domain `/` stops
+  being `docs/src/pages/index.md` (generated from README) and becomes the standalone landing
+  page (`site/`) instead** — `build/Merge-LandingPage.ps1`, wired into both `docs-ci.yml` and
+  `docs-deploy.yml`, overlays it on every build. `/docs/` and everything beneath it is
+  unaffected; only the site root changes owner.
 - **Two link checks, and between them everything is now gated.** `build/Test-Documentation.ps1`
   hard-fails on relative links and heading anchors — that is the one that catches a doc
   rename. Both of Docusaurus's own passes are back to `'throw'`, which re-covers the
 
@@ -0,0 +1,88 @@
+<#
+.SYNOPSIS
+    Overlays the built landing page onto a built documentation site, so the
+    combined tree serves the landing page at "/" and the docs at "/docs".
+
+.DESCRIPTION
+    Two independent projects, one GitHub Pages deployment. The docs build
+    (docs-build.ps1) already puts the actual documentation under docs/docs/...
+    -- routeBasePath: 'docs' in docs/docusaurus.config.ts sees to that -- but
+    its own site root is docs/src/pages/index.md, generated from README.md.
+    That generated homepage is superseded once the landing page exists: this
+    script overwrites it with the landing page's own index.html and merges in
+    its assets, leaving everything under docs/ inside the output untouched.
+
+    The merge is safe because the two builds never write the same paths.
+    Docusaurus nests its bundle under assets/css/ and assets/js/; Vite writes
+    flat hashed files directly into assets/. Verified against a real build of
+    both projects, not assumed -- see the commit that added this script.
+
+.PARAMETER LandingDist
+    Path to the built landing page (a Vite `dist/` directory).
+
+.PARAMETER DocsOutput
+    Path to the built documentation site (docs-build.ps1's -OutputPath).
+
+.EXAMPLE
+    ./build/Merge-LandingPage.ps1 -LandingDist ./site/dist -DocsOutput ./artifacts/docs
+#>
+[CmdletBinding()]
+param(
+    [Parameter()]
+    [ValidateNotNullOrEmpty()]
+    [string]$LandingDist = 'site/dist',
+
+    [Parameter()]
+    [ValidateNotNullOrEmpty()]
+    [string]$DocsOutput = 'artifacts/docs'
+)
+
+Set-StrictMode -Version 3.0
+$ErrorActionPreference = 'Stop'
+
+if (-not (Test-Path -LiteralPath $LandingDist -PathType Container)) {
+    throw "Landing page build not found at '$LandingDist'. Run 'npm --prefix site run build' first."
+}
+
+if (-not (Test-Path -LiteralPath $DocsOutput -PathType Container)) {
+    throw "Documentation build not found at '$DocsOutput'. Run docs-build.ps1 first."
+}
+
+$docsSubtree = Join-Path $DocsOutput 'docs'
+if (-not (Test-Path -LiteralPath $docsSubtree -PathType Container)) {
+    throw "'$DocsOutput' does not look like a docs-build.ps1 output -- no 'docs' subdirectory found. Refusing to merge into a directory that isn't a real docs build, to avoid silently producing a broken site."
+}
+$docsPageCountBefore = (Get-ChildItem -LiteralPath $docsSubtree -Recurse -File).Count
+
+$landingIndex = Join-Path $LandingDist 'index.html'
+if (-not (Test-Path -LiteralPath $landingIndex -PathType Leaf)) {
+    throw "'$LandingDist' has no index.html -- is this really a Vite build output?"
+}
+
+# Overwrite the docs build's generated-from-README homepage with the landing
+# page. This is the one intentional collision: both projects produce a root
+# index.html, and the landing page wins.
+Copy-Item -LiteralPath $landingIndex -Destination (Join-Path $DocsOutput 'index.html') -Force
+
+$landingAssets = Join-Path $LandingDist 'assets'
+if (Test-Path -LiteralPath $landingAssets -PathType Container) {
+    $destAssets = Join-Path $DocsOutput 'assets'
+    New-Item -ItemType Directory -Path $destAssets -Force | Out-Null
+    Copy-Item -Path (Join-Path $landingAssets '*') -Destination $destAssets -Recurse -Force
+}
+
+# Anything else Vite emitted at the dist root (favicons, manifest files, etc.)
+# that is not index.html or assets/ -- copy it across too, without touching
+# docs/.
+Get-ChildItem -LiteralPath $LandingDist -Force |
+    Where-Object { $_.Name -notin @('index.html', 'assets') } |
+    ForEach-Object {
+        Copy-Item -LiteralPath $_.FullName -Destination $DocsOutput -Recurse -Force
+    }
+
+$docsPageCountAfter = (Get-ChildItem -LiteralPath $docsSubtree -Recurse -File).Count
+if ($docsPageCountAfter -ne $docsPageCountBefore) {
+    throw "The merge changed the file count under '$docsSubtree' ($docsPageCountBefore -> $docsPageCountAfter). The landing page must never write into docs/ -- aborting rather than shipping a possibly-corrupted docs tree."
+}
+
+Write-Host "[MERGE] Landing page overlaid onto '$DocsOutput'. docs/ untouched ($docsPageCountAfter files)." -ForegroundColor Green