@rubytech/create-maxy-code 0.1.17 → 0.1.19

package/dist/__tests__/cdp-port-no-silent-fallback.test.js

@@ -2,7 +2,7 @@
 // silent-fallback-masks-root-cause violation. The four runtime sites that
 // previously substituted `9222 + offset` for a missing brand.json.cdpPort
 // (paths.ts, admin/mcp/index.ts, vnc.sh, test-laptop-vnc-boot.sh) plus the
-// installer-side brand stamp at packages/create-maxy/src/index.ts have all
+// installer-side brand stamp at packages/create-maxy-code/src/index.ts have all
 // been swept to loud-fail. This test asserts the three greps from criterion
 // 2 of the task brief return zero matches; reintroducing any silent fallback
 // fails CI immediately.
@@ -19,7 +19,7 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const SELF_DIR = fileURLToPath(new URL(".", import.meta.url));
 // dist/__tests__/ → repo root is four levels up
-// (packages/create-maxy/dist/__tests__ → packages/create-maxy → packages → repo).
+// (packages/create-maxy-code/dist/__tests__ → packages/create-maxy-code → packages → repo).
 const REPO_ROOT = resolve(SELF_DIR, "..", "..", "..", "..");
 function grepReturns(pattern, includes) {
     const args = ["-RnE", pattern];

package/dist/__tests__/onboarding-state-readback.test.js

@@ -0,0 +1,61 @@
+// Task 033 — install-invariant for OnboardingState seed.
+//
+// The installer re-reads Neo4j after seed-neo4j.sh to verify the
+// OnboardingState node landed. The parser turns cypher-shell's plain-
+// format output into a tri-state outcome consumed by the loud-fail
+// branch in src/index.ts. These tests fence the three outcomes the
+// installer logs name: present / missing / unreachable.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { classifyOnboardingReadBack } from "../onboarding-readback.js";
+test("non-zero exit → unreachable, with stderr tail captured", () => {
+    const outcome = classifyOnboardingReadBack({
+        status: 1,
+        stdout: "",
+        stderr: "Connection refused: bolt://localhost:7687",
+    });
+    assert.equal(outcome.kind, "unreachable");
+    if (outcome.kind === "unreachable") {
+        assert.match(outcome.stderrTail, /Connection refused/);
+    }
+});
+test("header row only (no match) → missing", () => {
+    // cypher-shell --format plain emits the column header even when zero rows
+    // matched. The seed-or-fail contract treats header-only as the loud-fail.
+    const outcome = classifyOnboardingReadBack({
+        status: 0,
+        stdout: "currentStep\n",
+        stderr: "",
+    });
+    assert.equal(outcome.kind, "missing");
+});
+test("data row present → present, currentStep relayed verbatim", () => {
+    const outcome = classifyOnboardingReadBack({
+        status: 0,
+        stdout: "currentStep\n0\n",
+        stderr: "",
+    });
+    assert.equal(outcome.kind, "present");
+    if (outcome.kind === "present") {
+        assert.equal(outcome.currentStep, "0");
+    }
+});
+test("empty stdout + zero exit → missing (defensive: cypher-shell flushed nothing)", () => {
+    const outcome = classifyOnboardingReadBack({
+        status: 0,
+        stdout: "",
+        stderr: "",
+    });
+    assert.equal(outcome.kind, "missing");
+});
+test("trailing whitespace tolerated on present row", () => {
+    const outcome = classifyOnboardingReadBack({
+        status: 0,
+        stdout: "currentStep\n0  \n\n",
+        stderr: "",
+    });
+    assert.equal(outcome.kind, "present");
+    if (outcome.kind === "present") {
+        assert.equal(outcome.currentStep, "0");
+    }
+});

package/dist/index.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, rea
 import { resolve, join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerUnitFile } from "./port-resolution.js";
+import { classifyOnboardingReadBack } from "./onboarding-readback.js";
 import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
 import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
 import { requireSupportedPlatform } from "./platform-detect.js";
@@ -2289,6 +2290,47 @@ function setupAccount() {
         logFile(`  [neo4j] passing NEO4J_URI=${neo4jUri} to seed`);
         shell("bash", [seedScript], { cwd: INSTALL_DIR, env: neo4jEnv });
     }
+    // Task 033 — install-invariant: OnboardingState must exist post-seed.
+    // Loud-fails (exit 1) on miss because the first admin session has nothing
+    // to read otherwise: loadOnboardingStep returns -1 (no node), the chat
+    // tries to drive the 9-step flow against missing state, and step
+    // advancements have nowhere to land. Symmetric to Task 904's
+    // [install-invariant] line — log-and-continue isn't enough here because
+    // the gap silently breaks every fresh install. Idempotent on re-runs:
+    // the seed's MERGE leaves the node untouched.
+    const accountId = resolveInstallAccountId();
+    if (accountId) {
+        assertOnboardingStateSeeded(accountId, neo4jUri, password);
+    }
+    else {
+        console.log("  [install-invariant] onboarding-state-check SKIPPED reason=no-account-discovered");
+    }
+}
+// Task 033 — Neo4j read-back assertion. Runs cypher-shell against the
+// brand's Neo4j and confirms an OnboardingState{accountId} node exists.
+// Loud-fail exit on miss / Neo4j unreachable so the installer logs name
+// the exact symptom the next run has to fix.
+function assertOnboardingStateSeeded(accountId, neo4jUri, password) {
+    const TAG = "[install-invariant]";
+    const cypher = `MATCH (o:OnboardingState {accountId: '${accountId}'}) RETURN o.currentStep AS currentStep;`;
+    const result = spawnSync("cypher-shell", ["-u", "neo4j", "-p", password, "-a", neo4jUri, "--format", "plain", cypher], { stdio: "pipe", encoding: "utf-8", timeout: 10_000 });
+    const outcome = classifyOnboardingReadBack({
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    });
+    if (outcome.kind === "unreachable") {
+        console.error(`  ${TAG} onboarding-state-UNREACHABLE accountId=${accountId} exit=${result.status} stderr=${JSON.stringify(outcome.stderrTail)}`);
+        logFile(`  ${TAG} onboarding-state-UNREACHABLE accountId=${accountId} stderr=${outcome.stderrTail}`);
+        throw new Error(`OnboardingState read-back failed: cypher-shell exit=${result.status}`);
+    }
+    if (outcome.kind === "missing") {
+        console.error(`  ${TAG} onboarding-state-MISSING accountId=${accountId}`);
+        logFile(`  ${TAG} onboarding-state-MISSING accountId=${accountId}`);
+        throw new Error(`OnboardingState missing for accountId=${accountId} after seed-neo4j.sh`);
+    }
+    console.log(`  ${TAG} onboarding-state-present accountId=${accountId} currentStep=${outcome.currentStep}`);
+    logFile(`  ${TAG} onboarding-state-present accountId=${accountId} currentStep=${outcome.currentStep}`);
 }
 // ---------------------------------------------------------------------------
 // Tunnel script shortcuts

package/dist/onboarding-readback.js

@@ -0,0 +1,27 @@
+// Task 033 — pure parser for the OnboardingState read-back assertion.
+//
+// Extracted into a dedicated module (not src/index.ts) so the test
+// suite can import it without triggering index's brand.json-at-load
+// side effect. The installer's loud-fail branches at
+// `assertOnboardingStateSeeded` consume the tri-state outcome.
+/**
+ * Classify cypher-shell --format plain output into one of three states:
+ *
+ * - `unreachable` — non-zero exit (auth, network, syntax). Stderr tail
+ *   (last 200 chars) is preserved so the install log carries the
+ *   symptom verbatim.
+ * - `missing` — exit 0 but no data row beyond the header. cypher-shell
+ *   prints the column name even on a zero-match query.
+ * - `present` — exit 0 with at least one data row. `currentStep` is the
+ *   first field on row 2.
+ */
+export function classifyOnboardingReadBack(input) {
+    if (input.status !== 0) {
+        return { kind: "unreachable", stderrTail: input.stderr.trim().slice(-200) };
+    }
+    const lines = input.stdout.trim().split("\n").filter((l) => l.length > 0);
+    if (lines.length < 2) {
+        return { kind: "missing" };
+    }
+    return { kind: "present", currentStep: lines[1].trim() };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"
@@ -17,7 +17,7 @@
     "payload"
   ],
   "keywords": [
-    "maxy",
+    "maxy-code",
     "ai",
     "assistant",
     "raspberry-pi",

package/payload/platform/config/brand-registry.json

@@ -1,16 +1,16 @@
 {
   "brands": [
     {
-      "hostname": "maxy",
-      "configDir": ".maxy",
+      "hostname": "maxy-code",
+      "configDir": ".maxy-code",
       "vncDisplay": 99,
       "rfbPort": 5900,
       "websockifyPort": 6080,
       "cdpPort": 9222
     },
     {
-      "hostname": "realagent",
-      "configDir": ".realagent",
+      "hostname": "realagent-code",
+      "configDir": ".realagent-code",
       "vncDisplay": 100,
       "rfbPort": 5901,
       "websockifyPort": 6081,

package/payload/platform/config/brand.json

@@ -1,9 +1,9 @@
 {
   "productName": "Maxy",
-  "hostname": "maxy",
-  "serviceName": "maxy.service",
-  "installDir": "maxy",
-  "configDir": ".maxy",
+  "hostname": "maxy-code",
+  "serviceName": "maxy-code.service",
+  "installDir": "maxy-code",
+  "configDir": ".maxy-code",
   "tagline": "AI for Productive People",
   "strapline": "Convenience as standard.",
   "domain": "getmaxy.com",

package/payload/platform/plugins/cloudflare/scripts/reset-tunnel.sh

@@ -28,7 +28,7 @@ set -euo pipefail
 
 # shellcheck source=_stream-log.sh
 # Resolve symlinks before dirname — ~/reset-tunnel.sh is installed as a symlink
-# (see packages/create-maxy/src/index.ts:installTunnelScripts), so the raw
+# (see packages/create-maxy-code/src/index.ts:installTunnelScripts), so the raw
 # BASH_SOURCE[0] points at $HOME, not the scripts directory where _stream-log.sh lives.
 source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
 require_stream_log_path reset-tunnel

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -33,7 +33,7 @@ set -euo pipefail
 
 # shellcheck source=_stream-log.sh
 # Resolve symlinks before dirname — ~/setup-tunnel.sh is installed as a symlink
-# (see packages/create-maxy/src/index.ts:installTunnelScripts), so the raw
+# (see packages/create-maxy-code/src/index.ts:installTunnelScripts), so the raw
 # BASH_SOURCE[0] points at $HOME, not the scripts directory where _stream-log.sh lives.
 source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
 require_stream_log_path setup-tunnel

package/payload/platform/plugins/docs/references/deployment.md

@@ -39,6 +39,29 @@ This installs all dependencies (Node.js, Neo4j, Cloudflare tunnel, Claude Code),
 6. Starts the {{productName}} web server on port 19200
 7. Configures systemd so everything restarts automatically if the Pi reboots
 
+## First admin session — onboarding handover
+
+After install, the first time you open the admin URL, {{productName}} walks you through a 9-step onboarding flow: plugin selection, output style, thinking-view, timezone, persona, Cloudflare, Anthropic API key, and the business-profile capture. The flow is gated on a single piece of Neo4j state, an `OnboardingState{accountId, currentStep}` node:
+
+- `seed-neo4j.sh` writes the node at install time with `currentStep=0`. The installer re-reads it before exiting; a missing node or an unreachable Neo4j fails the install loudly (`[install-invariant] onboarding-state-MISSING` or `onboarding-state-UNREACHABLE`).
+- Every admin session-create reads `currentStep`. Anything below 9 keeps `onboarding_complete=false` on `/api/health` and `/api/admin/session`, and the chat opens on the next step's component (multi-select, dropdown, etc.).
+- The first input on a freshly-spawned admin claude session is prepended with an `<onboarding-state currentStep="N">` directive that tells the agent to call `skill-load skillName=onboarding`. Resumed sessions skip this prepend so the agent doesn't re-ask the same step.
+- If Neo4j is unreachable at session-create, the prepend becomes a loud-fail block (`graphUnreachable="true"`) and `onboarding_complete` is reported false — never silently skipped.
+
+Diagnostic command on the Pi (substitute the brand's Neo4j port from `~/.maxy/.env` or `~/.realagent/.env`):
+
+```bash
+cypher-shell -a bolt://localhost:<brand-neo4j-port> \
+  "MATCH (o:OnboardingState) RETURN o.accountId, o.currentStep"
+```
+
+Failure signals to grep in `~/.maxy/logs/server.log` (or `~/.realagent/logs/server.log`):
+
+- missing `[onboarding-seed]` line in install output
+- `[install-invariant] onboarding-state-MISSING`
+- `[onboarding-gate] step=null complete=true` (the pre-Task-033 bug)
+- missing `[skill-load] name=onboarding` while `[onboarding-gate]` reports `complete=false`
+
 ## Service Management
 
 {{productName}} runs via systemd and starts automatically on boot. You don't need to start it manually. To check if it's running, ask {{productName}} "Check system status."
@@ -121,7 +144,7 @@ A separate operator-side harness at `platform/scripts/installer-device-verify.sh
 
 The installer registers Claude Code plugins on the device as the last step before the brand service starts. After registration, `claude plugin list` on the Pi shows every Maxy platform plugin shipped by the brand, every premium sub-plugin shipped by the brand, and any external plugins the brand declares (e.g. Telegram, Discord, iMessage from `claude-plugins-official`). Spawned `claude` sessions inherit those plugins from `~/.claude/` — the session manager passes no `--mcp-config` argv.
 
-**Where the manifests come from.** The Maxy plugin source tree uses `PLUGIN.md` (YAML frontmatter) for plugin metadata, not Claude Code's native `.claude-plugin/plugin.json`. At bundle time, `scripts/generate-plugin-manifests.mjs` walks the payload and synthesises a Claude-Code-native `plugin.json` per plugin plus a `marketplace.json` at each tree root. The generator runs in `packages/create-maxy/scripts/bundle.js` after platform + premium plugins are copied into the payload, so the deployed install directory carries:
+**Where the manifests come from.** The Maxy plugin source tree uses `PLUGIN.md` (YAML frontmatter) for plugin metadata, not Claude Code's native `.claude-plugin/plugin.json`. At bundle time, `scripts/generate-plugin-manifests.mjs` walks the payload and synthesises a Claude-Code-native `plugin.json` per plugin plus a `marketplace.json` at each tree root. The generator runs in `packages/create-maxy-code/scripts/bundle.js` after platform + premium plugins are copied into the payload, so the deployed install directory carries:
 
 - `<INSTALL_DIR>/platform/plugins/<name>/.claude-plugin/plugin.json` per platform plugin
 - `<INSTALL_DIR>/platform/plugins/.claude-plugin/marketplace.json` (marketplace `maxy-platform`)
@@ -142,7 +165,7 @@ Generator schema:
 
 Skills, agents, hooks, and commands directories at the plugin root are auto-discovered by Claude Code — no explicit field needed.
 
-**Install flow** (`registerLocalAndExternalPlugins()` in `packages/create-maxy/src/index.ts`):
+**Install flow** (`registerLocalAndExternalPlugins()` in `packages/create-maxy-code/src/index.ts`):
 
 1. Discover every `.claude-plugin/marketplace.json` under the install directory.
 2. For each one not already in `claude plugin marketplace list`, run `claude plugin marketplace add <dir>`. Pre-existing entries log `[plugin-marketplace] added <name> idempotent=true`.

package/payload/platform/scripts/installer-device-verify.sh

@@ -12,7 +12,7 @@
 # banner — is a non-zero exit with the failing device named on stderr.
 #
 # CONTRACT
-#   Archival of any task that touches packages/create-maxy/** is contingent
+#   Archival of any task that touches packages/create-maxy-code/** is contingent
 #   on this script exiting zero against the published version. The exit code
 #   and the per-device summary are quoted in the close commit body.
 #
@@ -191,7 +191,7 @@ for i in $(seq 0 $((DEVICE_COUNT - 1))); do
   # Step 2 — confirm a terminal-success banner in the latest install log.
   # Pick the newest install-*.log by mtime (`ls -t`) and grep for either of
   # the installer's two terminal-success markers emitted by
-  # packages/create-maxy/src/index.ts:
+  # packages/create-maxy-code/src/index.ts:
   #   • DISPLAY_MODE=virtual (Pi, headless VNC) →
   #     "Browser automation ready (CDP connected)"  (index.ts:3012)
   #   • DISPLAY_MODE=native  (laptop, on-demand Chromium) →

package/payload/platform/scripts/redact-install-logs.sh

@@ -2,7 +2,7 @@
 # Existing-pi install-log redaction (Task 744).
 #
 # Idempotent one-shot remediation for Pis that completed installation BEFORE
-# the install-log redaction landed at packages/create-maxy/src/index.ts:152.
+# the install-log redaction landed at packages/create-maxy-code/src/index.ts:152.
 # Scans every `install-*.log` in the configured logs directory and replaces
 # every literal `set-initial-password ...<secret>` payload with
 # `set-initial-password [REDACTED]`. Re-running the script is safe —
@@ -10,7 +10,7 @@
 # edits occur.
 #
 # Source patterns covered:
-#   1. TS installer (packages/create-maxy/src/index.ts:152) — "[ISO] > sudo
+#   1. TS installer (packages/create-maxy-code/src/index.ts:152) — "[ISO] > sudo
 #      neo4j-admin dbms set-initial-password -- <secret>" or any args after
 #      "set-initial-password" (positional or "--" delimited).
 #   2. Legacy bash installer (removed) — "+ sudo neo4j-admin dbms

package/payload/platform/scripts/seed-neo4j.sh

@@ -541,4 +541,39 @@ BACKFILL_EOF
   echo "  [backfill] $BACKFILL_RESULT"
 fi
 
+# ------------------------------------------------------------------
+# 4. Seed OnboardingState (Task 033 — maxy-code)
+# ------------------------------------------------------------------
+# The first admin session reads OnboardingState.currentStep to decide whether
+# the chat opens on step 1 of the 9-step onboarding flow or on a free-form
+# greeting. Pre-Task-033 the node was never written at seed, so the post-PIN
+# session-create's loadOnboardingStep returned -1 (no node) which used to
+# conflate with null (Neo4j unreachable) and silently report
+# onboardingComplete:true — the operator was dropped into the admin agent
+# with no plugin selection, output-style, timezone, SOUL, Cloudflare,
+# Anthropic-key, or business-profile setup.
+#
+# Keyed on accountId, not userId — fresh installs reach the seed before
+# users.json exists (PIN is set later by the onboarding flow itself).
+# MERGE is idempotent: re-runs leave currentStep untouched, refreshing only
+# updatedAt.
+SEED_NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+echo "==> Seeding OnboardingState for accountId=$ACCOUNT_ID"
+ONBOARDING_SEED_RESULT=$("$CYPHER_SHELL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" --format plain << CYPHER_EOF
+MERGE (o:OnboardingState {accountId: '$ACCOUNT_ID'})
+ON CREATE SET o.currentStep = 0,
+              o.createdAt = '$SEED_NOW',
+              o.updatedAt = '$SEED_NOW'
+ON MATCH SET o.updatedAt = '$SEED_NOW'
+RETURN o.currentStep AS currentStep, o.createdAt = '$SEED_NOW' AS created;
+CYPHER_EOF
+)
+ONBOARDING_STEP=$(echo "$ONBOARDING_SEED_RESULT" | awk 'NR==2 {print $1}')
+ONBOARDING_CREATED=$(echo "$ONBOARDING_SEED_RESULT" | awk 'NR==2 {print $2}')
+if [ "$ONBOARDING_CREATED" = "true" ]; then
+  echo "  [onboarding-seed] accountId=$ACCOUNT_ID currentStep=$ONBOARDING_STEP idempotent=false"
+else
+  echo "  [onboarding-seed] accountId=$ACCOUNT_ID currentStep=$ONBOARDING_STEP idempotent=true"
+fi
+
 echo "  Done."

package/payload/platform/scripts/verify-skill-tool-surface.sh

@@ -8,7 +8,7 @@
 # and where a skill prescribes a forbidden direct-execution path
 # (`cypher-shell`, `neo4j-admin` invocations, raw-Cypher DML in prose).
 #
-# Wired into the root `packages/create-maxy/package.json` `prepublishOnly`
+# Wired into the root `packages/create-maxy-code/package.json` `prepublishOnly`
 # script so a regression cannot reach npm publish without firing.
 #
 # One stdout line per (skill, specialist) pair:

package/payload/platform/scripts/vnc.sh

@@ -45,7 +45,7 @@ BRAND_JSON="${PLATFORM_ROOT}/config/brand.json"
 # Task 959 — brand.json is the single source of truth at runtime; missing
 # fields loud-fail rather than silently substituting a vncDisplay-derived
 # offset (silent-fallback-masks-root-cause recurrence). The install-time
-# offset rule in packages/create-maxy/src/index.ts stamps every brand at
+# offset rule in packages/create-maxy-code/src/index.ts stamps every brand at
 # build time, so a correctly-installed device always has all five fields.
 if [ ! -f "$BRAND_JSON" ]; then
   echo "[vnc.sh] error reason=brand-config-missing path=$BRAND_JSON" >&2
@@ -89,7 +89,7 @@ mkdir -p "$LOG_DIR"
 log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"; }
 
 # Task 929 — resolve the absolute Chromium binary path from the install-time
-# config file. The installer (packages/create-maxy/src/index.ts
+# config file. The installer (packages/create-maxy-code/src/index.ts
 # ensureNonSnapChromium + writeChromiumBinaryPathFile) writes this file with
 # the non-snap binary chosen for this device — `/usr/bin/chromium` on Pi
 # Bookworm (real .deb) or `/usr/bin/google-chrome-stable` on Ubuntu Noble

package/payload/premium-plugins/real-agency/plugins/brochures/skills/brand-design/SKILL.md

@@ -80,7 +80,7 @@ Two PNGs of the wordmark/lockup as the brand uses it. **The filename describes t
 | Filename | Art colour | Place it on |
 |---|---|---|
 | `<slug>-logo-light.png` | light/white/cream/pale pixels | dark surfaces (back-page hero, dark masthead) |
-| `<slug>-logo-dark.png` | dark/black/navy/charcoal pixels | light surfaces (TOC, page.html nav, paper backgrounds) |
+| `<slug>-logo-dark.png` | dark/black/navy/charcoal pixels | light surfaces (TOC, index.html nav, paper backgrounds) |
 
 So if you open `donnavincent-logo-light.png` and see white text, that is correct — it's the light-coloured variant. If you open `donnavincent-logo-dark.png` and see white text, the file was misnamed by an earlier run; rename it.
 

package/payload/premium-plugins/real-agency/plugins/brochures/skills/make-brochure/SKILL.md

@@ -23,7 +23,7 @@ The deliverable is identical to `property-brochure`'s outcome — written into `
 
 - `brochure.html` plus per-page 300 dpi PNG print snapshots (canonical, archival)
 - Two image-only PDFs: `<slug>-brochure-print.pdf` (300 dpi print master) and `<slug>-brochure-web.pdf` (192 dpi web/digital). Both built from per-page Playwright snapshots via img2pdf and linearized via qpdf — no Ghostscript anywhere in the chain. See `property-brochure → PDF deliverable` and `a4-print-documents → PDF deliverables`.
-- A self-contained **web bundle** at `output/web/` plus `output/<slug>-web.zip` — the smaller, ready-to-host version for property micro-sites; includes both the brochure and a companion **landing page** at `page.html` that presents the property as a continuous scrollable web page. See `property-brochure → Web bundle` and `property-brochure → Page`
+- A self-contained **web bundle** at `output/web/` plus `output/<slug>-web.zip` — the smaller, ready-to-host version for property micro-sites; includes both the brochure and a companion **landing page** at `index.html` that presents the property as a continuous scrollable web page. See `property-brochure → Web bundle` and `property-brochure → Page`
 
 The orchestrator's value is in what it does **not** redo:
 
@@ -271,19 +271,19 @@ After a complete run, the on-disk layout is **exactly** this — no deeper nesti
             qr-video.png, qr-listing.png
           web/                            # self-contained web bundle, generated alongside print archive
             brochure.html                 # same HTML; print-img refs point at .jpg snapshots; QR codes are clickable <a>
-            page.html                     # companion property landing page (Modern House-style scroll)
+            index.html                     # companion property landing page (Modern House-style scroll)
             <property_slug>-brochure.pdf  # digital PDF, copied for the in-page Download button
             cover-print.jpg
             page2-print.jpg … page15-print.jpg
             backpage-print.jpg
             images/                       # web-tier per-slot encodings: hero 1300/q82, story 1100/q80, thumb 800/q76
               <property_slug>-NN.webp
-              <property_slug>-hero-1-main.webp     # page.html hero rotator — source-res @ q88
-              <property_slug>-hero-2-<role>.webp   # page.html hero rotator — interior moment
-              <property_slug>-hero-3-<role>.webp   # page.html hero rotator — garden / outdoor
+              <property_slug>-hero-1-main.webp     # index.html hero rotator — source-res @ q88
+              <property_slug>-hero-2-<role>.webp   # index.html hero rotator — interior moment
+              <property_slug>-hero-3-<role>.webp   # index.html hero rotator — garden / outdoor
               <property_slug>-floorplan.png        # line-art PNG, copied unchanged from canonical
-              <brand_slug>-logo-light.png # light-coloured logo art — for dark surfaces (e.g. dark page.html sections)
-              <brand_slug>-logo-dark.png  # dark-coloured logo art — for light surfaces (e.g. page.html nav, brochure cover when paper)
+              <brand_slug>-logo-light.png # light-coloured logo art — for dark surfaces (e.g. dark index.html sections)
+              <brand_slug>-logo-dark.png  # dark-coloured logo art — for light surfaces (e.g. index.html nav, brochure cover when paper)
               qr-video.png, qr-listing.png
           <property_slug>-web.zip         # zipped form of web/, ready to upload to a static-site host
 ```
@@ -325,7 +325,7 @@ Determinism rules — a run that violates any of these is wrong, even if the bro
 | "House" instead of "home" at super-premium register | Wrong word for the buyer. "Home" is warmer, more aspirational, and matches the register. Replace globally. |
 | Text overlaid on photographs relying on a gradient + text-shadow for legibility | Insufficient against busy backgrounds (stone tile, golden-hour skies). Use a translucent dark panel directly behind the text. See `property-brochure → Text on images`. |
 | Including a detached gymnasium-summerhouse footprint in the principal home's first-floor sq ft | Misrepresents £/sq ft. List ancillary footprints separately. See `property-brochure → Floor area`. |
-| Shipping a web bundle without `page.html` | The web bundle is the property's hosted experience. The brochure is a downloadable folio; the landing page is the scrollable "for sale" page that links to it. Both are mandatory in the zip. See `property-brochure → Page`. |
+| Shipping a web bundle without `index.html` | The web bundle is the property's hosted experience. The brochure is a downloadable folio; the landing page is the scrollable "for sale" page that links to it. Both are mandatory in the zip. See `property-brochure → Page`. |
 | Putting QR codes on the back page without a visible URL or a clickable wrapper | A QR is unscannable from the digital screen showing the brochure. The clickable URL beneath each QR is mandatory; it makes the digital reader experience equivalent to the print reader experience. See `property-brochure → Back-page QR codes`. |
 | Using the same logo variant for the back-page masthead (dark surface) and the landing-page nav (light surface) | The two surfaces need opposite logo variants — white-on-transparent for the back page, dark/coloured for the landing nav. Both must be present in `output/web/images/`. |
 
@@ -339,7 +339,7 @@ Report `DONE` only after:
 - Both PDF deliverables exist alongside `brochure.html`: the print master (`<property_slug>-brochure-print.pdf`, ~50–80 MB at 300 dpi) and the web/digital (`<property_slug>-brochure-web.pdf`, ~20–35 MB at 192 dpi). Both are image-only, built from per-page Playwright snapshots via img2pdf and linearized via qpdf; both pass `qpdf --check`, both report `Optimized: yes`, and both have zero embedded fonts (`pdffonts | wc -l` returns 2). See `a4-print-documents → Verification`.
 - All per-page print snapshots referenced by the HTML's print CSS exist at expected names — `cover-print.png`, `page2-print.png` through `page15-print.png`, and `backpage-print.png` (16 files for the 16-page folio) — at the orientation-correct 300 dpi pixel dimensions (3509×2481 landscape / 2481×3509 portrait).
 - The brochure has an **even page count** (canonical 16; multiples of 2 required, ideally multiples of 4 for booklet binding) — see `a4-print-documents` → Even-page count for duplex printing.
-- The **web bundle** exists at `output/web/` and as a zipped `output/<slug>-web.zip` — see `property-brochure → Web bundle` for what it contains. The bundle includes both `brochure.html` and the companion `page.html` (see `property-brochure → Page`), plus a copy of the web PDF named simply `<property_slug>-brochure.pdf` to match the in-page Download links. Smoke-test was performed: an isolated HTTP server returned 200 for every referenced asset (HTML, web-tier images, jpg snapshots, the bundled PDF), and **both** `brochure.html` and `page.html` rendered correctly. Typical zip is 30–50 MB for a 16-page folio.
+- The **web bundle** exists at `output/web/` and as a zipped `output/<slug>-web.zip` — see `property-brochure → Web bundle` for what it contains. The bundle includes both `brochure.html` and the companion `index.html` (see `property-brochure → Page`), plus a copy of the web PDF named simply `<property_slug>-brochure.pdf` to match the in-page Download links. Smoke-test was performed: an isolated HTTP server returned 200 for every referenced asset (HTML, web-tier images, jpg snapshots, the bundled PDF), and **both** `brochure.html` and `index.html` rendered correctly. Typical zip is 30–50 MB for a 16-page folio.
 - **Back-page QR codes are clickable.** Each QR is wrapped in an `<a target="_blank">` tag and accompanied by a visible underlined URL beneath the label, so a digital reader can click instead of scan. See `property-brochure → Back-page QR codes`.
 - The user-facing report names which steps ran and which were reused, **and the chosen orientation**, **and the path to both the canonical print archive and the web zip**.
 - No image was read in violation of the 2000px rule (verifiable: every image read should have been preceded by a `sips`/`identify` measurement, and any over-threshold image was previewed via `/tmp/`).

package/payload/premium-plugins/real-agency/plugins/brochures/skills/property-brochure/SKILL.md

@@ -9,7 +9,7 @@ Produce an A4 property brochure from raw assets. The default deliverable is a 16
 
 ## Output location
 
-By default the brochure is written to the **caller's current working directory**. The skill creates `./output/brochure.html`, `./output/web/page.html`, the print PNGs, and the two PDFs underneath `pwd` — no inference, no nesting under a brand workspace.
+By default the brochure is written to the **caller's current working directory**. The skill creates `./output/brochure.html`, `./output/web/index.html`, the print PNGs, and the two PDFs underneath `pwd` — no inference, no nesting under a brand workspace.
 
 If you want the output elsewhere, pass `output_dir` explicitly (an absolute path or a relative path resolved against CWD). Common overrides:
 
@@ -23,12 +23,12 @@ Do not silently nest the output under a brand workspace just because one is pres
 
 ## Step 1 — copy the canonical templates (do this first)
 
-`references/template.html` and `references/page.html` are the **only** acceptable starting points. They are placeholder-only — every property value is a `{{ token }}`. Copy them before doing anything else. **Do not write brochure HTML or page HTML from scratch. Do not start from a sibling property's output. Do not improvise structure from prose.**
+`references/template.html` and `references/index.html` are the **only** acceptable starting points. They are placeholder-only — every property value is a `{{ token }}`. Copy them before doing anything else. **Do not write brochure HTML or page HTML from scratch. Do not start from a sibling property's output. Do not improvise structure from prose.**
 
 ```bash
 mkdir -p <output_dir>/web
 cp ~/.claude/plugins/real-estate-brochure/skills/property-brochure/references/template.html <output_dir>/brochure.html
-cp ~/.claude/plugins/real-estate-brochure/skills/property-brochure/references/page.html      <output_dir>/web/page.html
+cp ~/.claude/plugins/real-estate-brochure/skills/property-brochure/references/index.html      <output_dir>/web/index.html
 ```
 
 `<output_dir>` is whatever the **Output location** section above resolves to — typically `./output/` in the caller's CWD.
@@ -43,7 +43,7 @@ Both files must contain canonical sentinels (proves they came from `references/`
 
 ```bash
 grep -q '{{ property_name }}'  <output_dir>/brochure.html  || echo "FAIL: brochure not from template"
-grep -q 'hero-stage'           <output_dir>/web/page.html  || echo "FAIL: page.html not from references"
+grep -q 'hero-stage'           <output_dir>/web/index.html  || echo "FAIL: index.html not from references"
 ```
 
 Both greps must succeed before populating content. If either fails, recopy.
@@ -74,14 +74,14 @@ Read the seller brief once before writing any copy. Then walk the `{{ placeholde
 | Editorial copy register, em-dash policy, "home" vs "house", text-on-images, typography, stats rows, AI hero prompt, **per-section composition guide** | [references/copy.md](references/copy.md) |
 | Orientation, 16-page layout, cover, floorplan, distinguishing features, Material Information, QR codes, location map | [references/structure.md](references/structure.md) |
 | Live editing, snapshot capture, PDF deliverable, web bundle | [references/build.md](references/build.md) |
-| `page.html` landing page — sections, hero rotator, mobile/drawer | [references/page-landing.md](references/page-landing.md) |
+| `index.html` landing page — sections, hero rotator, mobile/drawer | [references/index-landing.md](references/index-landing.md) |
 
 ### Substitution completion gate
 
 A brochure with any `{{ x }}` still in the rendered HTML is **shipped broken**. Before any snapshot capture or PDF build, run:
 
 ```bash
-unsubstituted=$(grep -c '{{' "$output_dir/brochure.html" "$output_dir/web/page.html" 2>/dev/null | awk -F: '{s+=$2} END {print s}')
+unsubstituted=$(grep -c '{{' "$output_dir/brochure.html" "$output_dir/web/index.html" 2>/dev/null | awk -F: '{s+=$2} END {print s}')
 [ "$unsubstituted" -eq 0 ] || { echo "DEFECT: $unsubstituted unsubstituted {{ tokens }} remain"; exit 1; }
 ```
 
@@ -106,7 +106,7 @@ unsubstituted=$(grep -c '{{' "$output_dir/brochure.html" "$output_dir/web/page.h
 - **Page count must be even** (16 default; 12 if the property is too small). 14 is forbidden.
 - **Image-only PDFs** — no fonts embedded, no Ghostscript anywhere in the chain.
 - **Self-contained `output/`** — never reference `../` paths. Every asset the HTML uses must live under `output/images/`.
-- **Web bundle must include `page.html`** — a bundle without it is incomplete.
+- **Web bundle must include `index.html`** — a bundle without it is incomplete.
 - **Suppress screen-only chrome before snapshotting** — the template's `.download-bar` is hidden under `@media print` but Playwright's `element.screenshot()` captures the screen render, where the bar IS visible. The render script in `build.md` injects a style tag (`.download-bar { display: none !important; }`) before capture. Any custom render script must do the same.
 - **No `{{ token }}` may remain in rendered output** — `grep '{{' output/brochure.html` must return zero matches before PDFs are built.
 

package/payload/premium-plugins/real-agency/plugins/brochures/skills/property-brochure/references/build.md

@@ -164,7 +164,7 @@ The web bundle is a parallel directory with the same on-disk shape as `output/`
 ```
 output/web/
   brochure.html                      # identical content; only print-img references switched .png → .jpg
-  page.html                          # companion landing page (mandatory in bundle)
+  index.html                          # companion landing page (mandatory in bundle)
   cover-print.jpg, page2-print.jpg … backpage-print.jpg   # 96 dpi JPEG snapshots (q=88)
   <slug>-brochure.pdf                # identical bytes to <slug>-brochure-web.pdf at the property level — simpler name inside the bundle since there's only one PDF here
   images/
@@ -220,7 +220,7 @@ A 16-page folio's web-bundle snapshots total ~3 MB (vs ~85 MB for the canonical
 
 ### Copy the web PDF into the bundle
 
-The web PDF (`<slug>-brochure-web.pdf` at the property level) is also placed inside the bundle, named simply `<slug>-brochure.pdf` to match `page.html` and `brochure.html` link conventions (where there's only one PDF in scope, no `-web` suffix is needed):
+The web PDF (`<slug>-brochure-web.pdf` at the property level) is also placed inside the bundle, named simply `<slug>-brochure.pdf` to match `index.html` and `brochure.html` link conventions (where there's only one PDF in scope, no `-web` suffix is needed):
 
 ```bash
 cp output/<slug>-brochure-web.pdf output/web/<slug>-brochure.pdf
@@ -245,7 +245,7 @@ Serve the unzipped bundle from an isolated temp directory and verify every refer
 TMP=/tmp/web-test && rm -rf $TMP && mkdir -p $TMP
 cd $TMP && unzip -q /path/to/<slug>-web.zip
 python3 -m http.server 8765 &
-for f in brochure.html page.html cover-print.jpg images/<slug>-01.webp images/<brand>-logo-light.png <slug>-brochure.pdf; do
+for f in brochure.html index.html cover-print.jpg images/<slug>-01.webp images/<brand>-logo-light.png <slug>-brochure.pdf; do
   echo "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8765/$f) $f"
 done
 ```
@@ -257,10 +257,10 @@ The brochure should render the same as the canonical preview, just lighter on th
 | File | `output/` (canonical archive) | `output/web/` (web bundle) |
 |---|---|---|
 | `brochure.html` | full-resolution images, `.png` snapshot refs | identical structure, `.jpg` snapshot refs, smaller image refs |
-| `page.html` | — | ✓ companion landing page; see `page-landing.md` |
+| `index.html` | — | ✓ companion landing page; see `index-landing.md` |
 | `<slug>-brochure-print.pdf` | ✓ canonical print master (50–80 MB, 300 dpi) | — (too large to bundle) |
 | `<slug>-brochure-web.pdf` | ✓ web/digital deliverable (20–35 MB, 192 dpi) | — copied into bundle as `<slug>-brochure.pdf` |
-| `<slug>-brochure.pdf` | — | ✓ identical bytes to `-web.pdf`; matches page.html / brochure.html link |
+| `<slug>-brochure.pdf` | — | ✓ identical bytes to `-web.pdf`; matches index.html / brochure.html link |
 | `cover-print.png … backpage-print.png` | ✓ 300 dpi PNG (~4–7 MB each) — canonical snapshots | — replaced by 96 dpi `.jpg` versions |
 | `cover-print.jpg … backpage-print.jpg` | — | ✓ 96 dpi JPEG (~150 KB each, derived from the 300 dpi PNGs) |
 | `images/<slug>-NN.webp` | full-quality per Render-slot table | web-tier per the web table above |

package/payload/premium-plugins/real-agency/plugins/brochures/skills/property-brochure/references/copy.md

@@ -109,7 +109,7 @@ If five cells at the chosen font size do not fit the available row width, **shri
 
 ## Per-section composition guide
 
-This section is the writing brief for each placeholder block in `template.html` and `page.html`. The token names map 1:1 to entries in `placeholders.md`; this file says **how the copy should read** for each one.
+This section is the writing brief for each placeholder block in `template.html` and `index.html`. The token names map 1:1 to entries in `placeholders.md`; this file says **how the copy should read** for each one.
 
 ### Cover & subtitle (page 1)
 
@@ -195,9 +195,9 @@ This section is the writing brief for each placeholder block in `template.html`
 - `{{ backpage_headline }}` — canonical phrasing "Arrange a viewing of <em>{{ property_name }}</em>". Do not paraphrase.
 - `{{ backpage_tagline }}` — single sentence, 25-45 words. Mirrors the cover/opener without duplicating phrases. Close with "Best understood in person." or an equivalent property-specific clincher.
 
-### Landing page (page.html)
+### Landing page (index.html)
 
-The landing-page tokens (`{{ landing_* }}`) source the same brief but render in continuous-scroll form rather than a 16-page folio. Each `{{ landing_*_para_N }}` follows the same length/voice rules as the equivalent brochure paragraph — see placeholders.md → "Category 9 — page.html editorial copy" for the per-section breakdown.
+The landing-page tokens (`{{ landing_* }}`) source the same brief but render in continuous-scroll form rather than a 16-page folio. Each `{{ landing_*_para_N }}` follows the same length/voice rules as the equivalent brochure paragraph — see placeholders.md → "Category 9 — index.html editorial copy" for the per-section breakdown.
 
 ## AI hero image prompt
 

package/payload/premium-plugins/real-agency/plugins/brochures/skills/property-brochure/references/images.md

@@ -120,7 +120,7 @@ The brochure is a **print-first deliverable**. Source images target the print-ma
 | **Map / screenshot** | screenshot with text labels | **2000 px** | source size, no resize | 88 |
 | **EPC chart** | small, already <100KB — copy through unchanged | n/a | as-is | as-is |
 
-**Floor plan exception — keep the source file as-is.** When the seller (or the agency's floor-plan provider) supplies a high-resolution PNG, **use it directly** — do not convert to WebP, do not downscale, do not re-encode. Floor plans are line art with thin strokes and crisp text where any quality loss is visibly worse than the same quality loss on photographic content. The same file (`<slug>-floorplan.png`) is referenced in the canonical brochure HTML, in the page.html landing page, and copied verbatim into `output/web/images/`. Because the new PDF pipeline rasterises whole pages from the rendered HTML (rather than passing the floor plan through a separate compression stage), the floor plan's quality at the PDF stage is determined by the snapshot DPI — 300 dpi for the print master, 192 dpi for the web PDF. A typical 2000 px floor plan slotted into a ~150 mm-wide brochure cell renders crisply at 300 dpi without any per-image processing. The **web bundle** also references the same `.png` (not a `.webp` substitute) — line art doesn't compress well as WebP and the file size is already modest.
+**Floor plan exception — keep the source file as-is.** When the seller (or the agency's floor-plan provider) supplies a high-resolution PNG, **use it directly** — do not convert to WebP, do not downscale, do not re-encode. Floor plans are line art with thin strokes and crisp text where any quality loss is visibly worse than the same quality loss on photographic content. The same file (`<slug>-floorplan.png`) is referenced in the canonical brochure HTML, in the index.html landing page, and copied verbatim into `output/web/images/`. Because the new PDF pipeline rasterises whole pages from the rendered HTML (rather than passing the floor plan through a separate compression stage), the floor plan's quality at the PDF stage is determined by the snapshot DPI — 300 dpi for the print master, 192 dpi for the web PDF. A typical 2000 px floor plan slotted into a ~150 mm-wide brochure cell renders crisply at 300 dpi without any per-image processing. The **web bundle** also references the same `.png` (not a `.webp` substitute) — line art doesn't compress well as WebP and the file size is already modest.
 
 The **source-px floor** is the floor on the input photo's longest edge **before optimisation** — see the `Image resolution floor` section in the **a4-print-documents** SKILL for the rationale and full thresholds.