Findability prototype (Alex): nav + hub + landing

.cursor/rules/docs-builder.md

@@ -0,0 +1,45 @@
+# Docs builder project context
+
+## Project
+
+- This repo contains the docs builder tooling and local doc rendering workflows.
+- Main local preview command (after a successful build):
+
+  ```bash
+  dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- serve
+  ```
+
+- Default local URL: `http://localhost:3000/`
+- `serve` uses the docset at **`docs/`** relative to the current working directory when run from the repo root. Use `-p|--path` to point at another folder.
+
+## Important paths
+
+- Tooling project: `src/tooling/docs-builder/docs-builder.csproj`
+- Local docset used for quick validation (default for `serve`): `docs/`
+- Layout file commonly touched for sidebar + main structure: `src/Elastic.Markdown/_Layout.cshtml`
+
+## Workflow guidance
+
+- Prefer `serve` with the local `docs/` folder when validating layout or CSS changes quickly.
+- `serve` runs in **isolated** mode: isolated header, not the assembler elastic-nav. Sidebar may still use **Nav V2 markup** for styling; that is not the same as the **global** `navigation-v2.yml` tree produced by an assembler build.
+- If the task explicitly requires elastic-nav or fully assembled site behavior, use the **assembler** flow (`assembler build` / `assemble`, then `assembler serve`), not `serve` alone.
+
+## Validation expectations
+
+1. Build the CLI (required after C#, Razor, or embedded view changes):
+
+   ```bash
+   dotnet build src/tooling/docs-builder/docs-builder.csproj
+   ```
+
+2. Run `serve` without rebuilding the project in the same invocation:
+
+   ```bash
+   dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- serve
+   ```
+
+## Notes
+
+- Warnings about navigation children or cross-links may appear in logs and do not necessarily block startup.
+- Confirm the server is running by checking for: `Now listening on: http://localhost:3000`
+- Static CSS/JS under `src/Elastic.Documentation.Site/_static/` is generated (e.g. when building `Elastic.Documentation.Site`); do not assume it is the only source of truth without rebuilding when changing `Assets/`.

.cursor/settings.json

@@ -0,0 +1,7 @@
+{
+  "plugins": {
+    "figma": {
+      "enabled": true
+    }
+  }
+}

.cursor/skills/docs-assembler-nav-v2-preview/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: docs-assembler-nav-v2-preview
+description: >-
+  Rebuilds the assembled documentation snapshot and serves static HTML with the full global sidebar
+  from navigation-v2.yml (Nav V2 IA), elastic-nav shell, and dev feature flags. Use when the user needs
+  the complete assembler navigation tree—not isolated TOC—localhost:4000, NAV_V2, assembler build/serve,
+  stale layout/CSS on port 4000, blank page or connection refused on 4000, missing .artifacts/assembly,
+  or "Can not serve empty directory" when starting assembler serve.
+---
+
+# docs-assembler-nav-v2-preview
+
+## Purpose
+
+Use when the user wants:
+
+- The **full Nav V2 tree** driven by `config/navigation-v2.yml` (labels, `toc:` sections, placeholders, assembler wiring)
+- Preview on **`assembler serve`** (default **port 4000**), not isolated `serve` on 3000
+- To refresh `.artifacts/assembly` after layout, Razor, or `Assets/` CSS/JS changes (static HTML lags until rebuild)
+- To recover from an empty or failed assembly output before serving
+
+## Context
+
+- **Isolated `serve` (3000)** reuses Nav V2 **components** but feeds them the **local docset TOC** only. It does **not** load `navigation-v2.yml` as the global IA.
+- **Assembler build** produces `.artifacts/assembly` with **BuildType.Assembler**, **elastic-nav**, and—when the environment enables it—**`NAV_V2: true`** (see `config/assembler.yml` under `dev` and `preview`).
+- Default assembler environment is **`dev`** unless overridden; `dev` includes `NAV_V2: true`.
+- **`assembler serve`** only reads **pre-generated** files from `.artifacts/assembly` (plus Debug behavior for `_static`—see `StaticWebHost`). It does not re-run Razor per request.
+
+## Prerequisites
+
+- Commands from the **docs-builder repository root**.
+- **Git checkouts** for assembler repos must be valid (e.g. `git rev-parse HEAD` works). If clones are missing or corrupt, run **`assembler clone`** before **`assembler build`**.
+- **Network** may be required for cross-link indices during build.
+- **GitHub access:** `assembler clone` pulls private `elastic/*` repositories. The machine needs **SSH keys or HTTPS + PAT** authorized for the org (including **SAML SSO** approval for Elastic org). Without that, clone/build will fail with `git fetch` exit **128** or SAML messages—**the agent cannot fix auth**; the user must sign in / authorize keys.
+
+### Without access to private repos (local Nav V2 smoke test)
+
+Use the **global** CLI flag **`--skip-private-repositories`** (stripped by `GlobalCli` before subcommands) on **clone** and **build** so private entries (`cloud`, `integration-docs`, etc.) are omitted. The local `docs/` tree is injected as **docs-builder** content per `AssemblyConfiguration`.
+
+```bash
+dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- --skip-private-repositories assembler clone
+dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- --skip-private-repositories assembler build --environment dev
+dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assembler serve --port 4000
+```
+
+**Caveat:** the assembled site is **incomplete** vs production (missing private docsets). **Nav V2** and **navigation-v2.yml** still render for what remains—enough for UI/IA checks. Documented similarly in `CONTRIBUTING.md` (Aspire / integration tests).
+
+## When the user asks to "run the build" or fix an empty 4000
+
+Execute in order (from repo root), and **report each outcome**:
+
+1. `dotnet build src/tooling/docs-builder/docs-builder.csproj`
+2. `dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assembler clone`  
+   — or with **`-- --skip-private-repositories`** before `assembler clone` if private repos fail (see above).
+3. `dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assembler build --environment dev`  
+   — same optional **`--skip-private-repositories`** prefix if step 2 used it.
+4. Verify output exists, e.g. `test -f .artifacts/assembly/docs/index.html` (or `ls .artifacts/assembly/docs/`)
+5. Only then: `dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assembler serve --port 4000`
+
+If step 2 or 3 fails, **do not** expect step 5 to work; see **Troubleshooting**.
+
+## Steps
+
+1. **Build the CLI** (pick up Razor, C#, and embedded site changes):
+
+   ```bash
+   dotnet build src/tooling/docs-builder/docs-builder.csproj
+   ```
+
+2. **Ensure sources exist** (if the previous build failed with git errors):
+
+   ```bash
+   dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assembler clone
+   ```
+
+3. **Regenerate assembly output** (this cleans and repopulates `.artifacts/assembly` on success):
+
+   ```bash
+   dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assembler build
+   ```
+
+   Optional: set environment explicitly to match `assembler.yml` (defaults to `dev`):
+
+   ```bash
+   dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assembler build --environment dev
+   ```
+
+4. **Serve the snapshot**:
+
+   ```bash
+   dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assembler serve --port 4000
+   ```
+
+5. **Open the site** — root often redirects to `docs`; dev URI in config is `http://localhost:4000` with `path_prefix: docs`, so start from:
+
+   - `http://localhost:4000/` (redirect), or  
+   - `http://localhost:4000/docs/` as needed.
+
+6. **Verify Nav V2** — in the sidebar HTML, look for `data-nav-v2` / `docs-sidebar-nav-v2` on a normal doc page inside the assembled site.
+
+7. **Confirm the server is listening** — logs must include `Now listening on: http://localhost:4000`. Optionally check `lsof -i :4000 -sTCP:LISTEN` or `curl -sI http://localhost:4000/`.
+
+## Troubleshooting: nothing on port 4000 / blank / connection refused
+
+| Symptom | Likely cause | What to do |
+|--------|----------------|------------|
+| Browser cannot connect; **nothing listening** on 4000 | `assembler serve` never started or crashed on startup | Run serve after a **successful** build; read the console error. |
+| **`Can not serve empty directory: …/.artifacts/assembly`** | `.artifacts/assembly` **does not exist** (or tooling treats it as missing) | Run **`assembler build`** successfully first. `StaticWebHost` throws if the directory is absent (`StaticWebHost.cs` checks `dir.Exists`). |
+| **`assembler build`** fails with **`git rev-parse HEAD`** / exit **128** | Checkout dir exists but is **not a valid git repo** or has no commits | Re-clone or fix that checkout under the assembler checkouts path (see clone logs). |
+| **`assembler clone`** / **`git fetch`** fails with **SAML SSO** / access rights | Host is **not authenticated** to Elastic org repos | User must use PAT + SSO or SSH key **authorized for the org**; retry `assembler clone`. |
+| Build succeeded earlier but UI looks old | Serving **stale** snapshot | Re-run **`assembler build`** after code/CSS changes, then serve again. |
+
+**Pre-flight before claiming 4000 works:**
+
+```bash
+test -d .artifacts/assembly && test -f .artifacts/assembly/docs/index.html && echo "assembly OK" || echo "assembly missing or incomplete"
+```
+
+## One-shot alternative
+
+Equivalent to clone + build + serve in one flow (long-running):
+
+```bash
+dotnet build src/tooling/docs-builder/docs-builder.csproj
+dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- assemble --serve
+```
+
+(`assemble` may clone and build; `--serve` uses port **4000** by default per product docs.)
+
+## Response template
+
+- **CLI build:** success / failure
+- **Assembler build:** success / failure (note if `assembly` was cleaned mid-failure)
+- **Serve:** URL and port
+- **Nav:** confirm full tree requires successful **assembler** build with **`NAV_V2`** for the chosen environment
+- **If stale UI:** remind that **`assembler build`** must complete after code changes before **`assembler serve`**
+- **If 4000 is empty:** state whether **port is listening**, whether **`.artifacts/assembly`** exists, and the **last error** from clone/build/serve (auth vs git vs missing directory)
+
+## Guardrails
+
+- Do **not** tell the user that isolated **`serve` on 3000** shows the **`navigation-v2.yml`** global tree.
+- Do **not** assume **`assembler serve`** reflects the latest Razor/CSS without a successful **`assembler build`** after those changes.
+- If **`assembler build`** fails after cleaning output, **`assembler serve`** may serve nothing or old content—fix clones/build first.
+- **`--assume-build`** skips regeneration when output exists; avoid it when the user explicitly needs **fresh** HTML/CSS.
+
+## Related
+
+- Project rule: `.cursor/rules/docs-builder.md`
+- Isolated preview skill: `.cursor/skills/docs-builder-serve/SKILL.md`
+- Layout validation skill: `.cursor/skills/docs-layout-validation/SKILL.md`
+- IA reference: `nav-v2-status.md`, `config/navigation-v2.yml`, `config/assembler.yml` (`feature_flags.NAV_V2`)

.cursor/skills/docs-builder-serve/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: docs-builder-serve
+description: >-
+  Builds and runs the docs-builder isolated preview server (Kestrel on localhost, default port 3000).
+  Use when the user wants local preview, localhost docs, serve mode, layout/CSS validation in isolated
+  mode, or to check if the dev server is up and whether log warnings block startup.
+---
+
+# docs-builder-serve
+
+## Purpose
+
+Apply this skill when the user wants to:
+
+- Run docs-builder locally for preview
+- Open or verify `http://localhost:3000/` (or another `--port`)
+- Know if a log line is blocking startup or safe to ignore
+- Validate layout or static asset behavior in **isolated** mode (not assembler)
+
+## Context
+
+- **Mode:** `serve` = isolated preview (isolated header, **not** elastic-nav from assembler).
+- **Tooling project:** `src/tooling/docs-builder/docs-builder.csproj`
+- **Default docset:** `docs/` relative to the **repository root** (current working directory should be the repo root when running commands). Override with `-p|--path` if needed.
+- **Default URL:** `http://localhost:3000/` (use `--port <n>` to change)
+
+## Steps
+
+1. **Build the CLI** (required after C#, Razor, or embedded view changes):
+
+   ```bash
+   dotnet build src/tooling/docs-builder/docs-builder.csproj
+   ```
+
+2. **Start the server** without compiling again in the same invocation:
+
+   ```bash
+   dotnet run --project src/tooling/docs-builder/docs-builder.csproj --no-build -- serve
+   ```
+
+   Optional: `serve --port 3001` (or another port) if 3000 is busy.
+
+3. **Inspect terminal output**
+
+   - Success: look for `Now listening on: http://localhost:3000` (or the chosen port).
+   - **Non-blocking (typical):** cross-link / navigation children warnings during docset load often still allow startup.
+   - **Blocking:** process exits, or no “Now listening” line after a clear fatal error.
+
+4. **Report clearly**
+
+   Use the response template below unless the user only asked a narrow question.
+
+5. **How to stop**
+
+   - `Ctrl+C` in the terminal running the server.
+   - If the user must free the port without that terminal: `lsof -ti :3000 | xargs kill` (adjust port); only suggest killing PIDs the user owns.
+
+## Response template
+
+- **Build:** success / failure (short reason if failure)
+- **Server:** running / not running
+- **URL:** `http://localhost:3000/` (or actual port)
+- **Mode:** isolated `serve` (not assembler static output)
+- **Logs:** brief note on any warnings and whether they block preview
+- **Stop:** `Ctrl+C` (and port-kill only if relevant)
+
+## Guardrails
+
+- Do **not** describe elastic-nav as available in isolated `serve`; assembler is a separate flow (`assembler build` / `assemble` + `assembler serve`).
+- Do **not** equate isolated sidebar Nav V2 **markup** with the **global** `navigation-v2.yml` tree from an assembler build.
+- Treat cross-link / navigation-structure warnings as **non-blocking** unless startup fails or logs show an unhandled exception before listening.
+- Run commands from the **docs-builder repository root** so `docs/` and project paths resolve correctly.

.cursor/skills/docs-layout-validation/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: docs-layout-validation
+description: >-
+  Guides validation of documentation page layout: sidebar, main column width, TOC column, and
+  `_Layout.cshtml` changes via isolated `serve`. Use when the user works on sidebar/main spacing,
+  full-bleed nav, `doc-page-main`, Nav V2 chrome, or asks if a layout tweak shows in local preview
+  versus assembler-only behavior.
+---
+
+# docs-layout-validation
+
+## Purpose
+
+Use when the task involves:
+
+- Sidebar / pages nav layout or width
+- Main content width, max-width, centering, or horizontal spacing
+- Changes to `src/Elastic.Markdown/_Layout.cshtml` or related layout CSS
+- Judging whether a layout tweak is visible in **local isolated preview** or needs **assembler**
+
+## Relevant files
+
+- **Primary Razor layout:** `src/Elastic.Markdown/_Layout.cshtml`
+- **Sidebar partial:** `src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml`
+- **Nav tree / V2 markup:** `src/Elastic.Documentation.Site/Navigation/_TocTree.cshtml`, `_TocTreeNavV2.cshtml`
+- **Shared layout CSS (tokens, sidebar chrome, `doc-page-main`):** `src/Elastic.Documentation.Site/Assets/styles.css`
+- **CLI for preview:** `src/tooling/docs-builder/docs-builder.csproj`
+
+After changing `Assets/*.css`, ensure `Elastic.Documentation.Site` (or full docs-builder build) has run so `_static/styles.css` is regenerated; it is not committed and isolated `serve` uses the built static bundle.
+
+## What isolated `serve` validates
+
+Good source of truth for:
+
+- Grid/flex structure of sidebar + main + TOC column (as rendered by `Elastic.Markdown` default layout)
+- Spacing, padding, max-width rules applied in that layout path
+- Responsive behavior at **md+** vs stacked mobile layout where applicable
+- Whether Razor/CSS changes compile and render in **BuildType.Isolated**
+
+## What isolated `serve` does not replace
+
+Requires **assembler build** + **`assembler serve`** (or deployed assembly) to validate:
+
+- **elastic-nav** and header chrome from assembler
+- **Global** navigation from `navigation-v2.yml` / assembler navigation pipeline
+- Final HTML snapshot behavior under `.artifacts/assembly`
+
+## Validation checklist
+
+1. **Identify touched files** (Razor vs CSS vs both) and whether behavior is layout-only or navigation-data-driven.
+2. **Rebuild** what embeds views or generates CSS:
+   - `dotnet build src/tooling/docs-builder/docs-builder.csproj` (and Site project if only CSS in `Assets/` changed without going through full build).
+3. **Run isolated preview** (see project skill `docs-builder-serve` or rule `docs-builder`): `serve` on `http://localhost:3000/`.
+4. **Open a normal Markdown doc page** (not only landing / full-search / special layouts) if the change targets the default doc layout.
+5. **Check in the browser**
+   - Sidebar position and width (including full-bleed vs centered shell)
+   - Main + “On this page” column alignment
+   - Regressions at **md** and **lg** if the change targets breakpoints
+6. **Report**
+   - What files drive the visible change
+   - Confirmed or not in isolated `serve`
+   - Whether **assembler** validation is still recommended (elastic-nav / global nav / static output freshness)
+
+## Response style
+
+Be explicit about:
+
+- What **can** be validated with isolated `serve`
+- What **still** needs assembler (or a fresh `assembler build` before `assembler serve`)
+- Whether symptoms point to **layout/CSS** vs **navigation YAML / cross-links / toc data**
+
+## Guardrails
+
+- Never claim isolated `serve` **fully** validates elastic-nav or the assembled site.
+- If symptoms match **assembled** navigation or stale **port 4000** static output, recommend `dotnet build` + `assembler build` (or `assemble`) then `assembler serve`, and a hard refresh.
+- Separate **visual/layout** issues from **navigation content** issues (toc, docset, cross-links).
+- Do not assume changes under `src/Elastic.Documentation.Site/Assets/` are live without a build that regenerates `_static/`.