viepilot 1.3.1 → 1.6.1

package/docs/user/features/ui-direction.md

@@ -5,25 +5,76 @@
 ## Mục tiêu
 - Chốt hướng UI/UX sớm bằng prototype định hướng
 - Ghi quyết định thiết kế cùng ngữ cảnh nghiệp vụ
-- Tạo đầu vào rõ ràng cho `/vp-crystallize`
+- Tạo đầu vào rõ ràng cho `/vp-crystallize`, kể cả khi sản phẩm có **nhiều page** (FEAT-007)
 
-## Artifacts
-Mỗi session UI tạo/cập nhật:
+## Hai layout được hỗ trợ
+
+### A) Legacy — một file chính (FEAT-002)
+Dùng khi chỉ có một màn hình / một luồng prototype đơn.
 
 ```text
 .viepilot/ui-direction/{session-id}/
-  index.html
+  index.html    # toàn bộ direction
   style.css
-  notes.md
+  notes.md      # rationale, assumptions, references
+```
+
+### B) Multi-page — mỗi page một HTML (khuyến nghị khi ≥2 màn)
+Dễ diff, dễ review, dễ map sang routing thật sau này.
+
+```text
+.viepilot/ui-direction/{session-id}/
+  index.html           # hub: liên kết tới mọi page (nav / danh sách)
+  style.css            # shared styles (tránh copy lớn giữa các file)
+  pages/
+    landing.html
+    dashboard.html
+    ...
+  notes.md             # rationale + bảng inventory (bắt buộc khi có pages/)
 ```
 
-`notes.md` là nguồn sự thật cho:
-- rationale
-- assumptions
-- references (bao gồm 21st.dev links/prompts)
+- **`index.html`**: không bắt buộc trùng nội dung với một page cụ thể; nên là **mục lục + link** tới `pages/*.html` để mở nhanh từng màn.
+- **`pages/{slug}.html`**: một file cho một page/screen; đặt `slug` ổn định (trùng tên route dự kiến nếu đã biết).
+
+## `notes.md` — nguồn sự thật
+
+Luôn ghi:
+- rationale, assumptions, references (21st.dev, v.v.)
+
+### Hook bắt buộc khi thư mục `pages/` tồn tại
+
+Sau **mỗi** lần thêm / đổi tên / xóa file trong `pages/`, assistant **phải** cập nhật:
+
+1. Liên kết trong `index.html` (hub).
+2. Section **`## Pages inventory`** trong `notes.md` (bảng đầy đủ mọi page hiện có).
+
+Mẫu bảng (copy-paste và điền):
+
+```markdown
+## Pages inventory
+
+| Slug | File | Title | Purpose | Key sections | Nav to |
+|------|------|-------|---------|--------------|--------|
+| landing | pages/landing.html | Marketing home | Acquire signups | hero, features, CTA | signup, login |
+| dashboard | pages/dashboard.html | App shell | Overview metrics | sidebar, charts, alerts | settings |
+```
+
+- **Slug**: định danh ngắn, ổn định.
+- **File**: đường dẫn tương đối từ thư mục session.
+- **Nav to**: slug hoặc tên page đích (comma-separated).
+
+Nếu **không** có thư mục `pages/`, không cần section `## Pages inventory` (layout legacy).
 
 ## Flow khuyến nghị
 1. `/vp-brainstorm --ui`
-2. Cập nhật yêu cầu/điều chỉnh layout trong chat
-3. Assistant cập nhật artifacts theo từng quyết định
-4. `/vp-crystallize` đọc artifacts để map sang tech stack thật
+2. Chọn legacy hoặc multi-page theo số màn hình.
+3. Mỗi thay đổi page → cập nhật HTML + **hub + `## Pages inventory`** trong cùng một lượt.
+4. `/vp-crystallize` đọc `notes.md` trước, sau đó `index.html`, `style.css`, và **từng** `pages/*.html` (nếu có) để lên kiến trúc UI đủ page.
+
+## Kiểm tra nhanh (optional)
+
+```bash
+node scripts/verify-ui-direction-pages.cjs
+```
+
+Script báo lỗi nếu có session có `pages/*.html` nhưng thiếu `## Pages inventory` hoặc thiếu tên file page trong `notes.md`.

package/docs/user/quick-start.md

@@ -54,6 +54,25 @@ npm run readme:sync
 # refresh README Total LOC metrics via cloc
 ```
 
+### Version check & update
+
+Sau khi có `vp-tools` trên PATH (ví dụ `npm i -g viepilot` hoặc cài qua `npx viepilot install` copy bundle):
+
+```bash
+vp-tools info
+vp-tools info --json
+```
+
+Cập nhật ViePilot qua npm — nên xem trước bằng dry-run; trong script/CI thêm `--yes` khi apply:
+
+```bash
+vp-tools update --dry-run
+vp-tools update --yes
+vp-tools update --global --yes
+```
+
+Trong project có dependency `viepilot`, có thể chạy: `node node_modules/viepilot/bin/vp-tools.cjs info`.
+
 ---
 
 ## Step 2: Create a New Project
@@ -103,6 +122,9 @@ ViePilot tạo `.viepilot/` directory với:
 - `TRACKER.md` — Progress tracking
 - `ARCHITECTURE.md` — System design
 - `SYSTEM-RULES.md` — Coding standards
+- `AI-GUIDE.md` — Thứ tự đọc context (kể cả **vision / horizon** trước khi khóa kiến trúc sâu)
+
+**Post-MVP không chỉ nằm trong brainstorm:** sau crystallize, horizon phải vào `ROADMAP.md` + vision theo pha trong `PROJECT-CONTEXT.md`. Tóm tắt cho user: [Product horizon end-to-end](features/product-horizon.md).
 
 ---
 

package/install.sh

@@ -2,6 +2,8 @@
 
 # ViePilot Installation Script
 # Installs ViePilot skills and tools to Cursor/Claude environment
+#
+# Optional: VIEPILOT_SYMLINK_SKILLS=1 — symlink skills/* into ~/.cursor/skills/ (absolute paths)
 
 set -e
 
@@ -109,13 +111,23 @@ mkdir -p "$VIEPILOT_DIR/bin"
 mkdir -p "$VIEPILOT_DIR/lib"
 mkdir -p "$VIEPILOT_DIR/ui-components"
 
-# Install skills
+# Install skills (copy default; VIEPILOT_SYMLINK_SKILLS=1 for dev-style live links)
 echo "  Installing skills..."
 for skill_dir in "$SCRIPT_DIR/skills"/*; do
     if [ -d "$skill_dir" ]; then
         skill_name=$(basename "$skill_dir")
-        cp -r "$skill_dir" "$CURSOR_SKILLS_DIR/"
-        echo "    ✓ $skill_name"
+        if [ "${VIEPILOT_SYMLINK_SKILLS:-0}" = "1" ]; then
+            if command -v realpath >/dev/null 2>&1; then
+                skill_abs=$(realpath "$skill_dir")
+            else
+                skill_abs=$(cd "$skill_dir" && pwd)
+            fi
+            ln -sfn "$skill_abs" "$CURSOR_SKILLS_DIR/$skill_name"
+            echo "    ✓ $skill_name (symlink)"
+        else
+            cp -r "$skill_dir" "$CURSOR_SKILLS_DIR/"
+            echo "    ✓ $skill_name"
+        fi
     fi
 done
 

package/lib/viepilot-info.cjs

@@ -0,0 +1,196 @@
+/**
+ * ViePilot bundle metadata for `vp-tools info` (FEAT-008).
+ * Resolves the viepilot package root from the CLI location — no `.viepilot/` project required.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Walk upward from startDir (and optionally cwd) for package.json with name "viepilot".
+ * @param {string} startDir - e.g. path.join(__dirname, '..') from bin/vp-tools.cjs
+ * @returns {string|null} absolute package root or null
+ */
+function resolveViepilotPackageRoot(startDir) {
+  const tryRoots = [path.resolve(startDir), path.resolve(process.cwd())];
+  const seen = new Set();
+  for (const base of tryRoots) {
+    if (seen.has(base)) continue;
+    seen.add(base);
+    let dir = base;
+    while (dir && dir !== path.dirname(dir)) {
+      const pkgPath = path.join(dir, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+          if (pkg && pkg.name === 'viepilot') {
+            return dir;
+          }
+        } catch (_e) {
+          /* ignore */
+        }
+      }
+      dir = path.dirname(dir);
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} root - viepilot package root
+ * @returns {string|null}
+ */
+function readInstalledVersion(root) {
+  const pkgPath = path.join(root, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.version || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Query npm registry for latest published version (requires network + npm on PATH).
+ * @returns {{ ok: true, version: string } | { ok: false, error: string }}
+ */
+function fetchLatestNpmVersion() {
+  try {
+    const out = execFileSync('npm', ['view', 'viepilot', 'version', '--json'], {
+      encoding: 'utf8',
+      timeout: 15000,
+      windowsHide: true,
+    }).trim();
+    const parsed = JSON.parse(out);
+    const version = typeof parsed === 'string' ? parsed : String(parsed);
+    return { ok: true, version };
+  } catch (e) {
+    return { ok: false, error: e.message || String(e) };
+  }
+}
+
+/**
+ * Parse `version:` from YAML-like frontmatter (first --- block).
+ * @param {string} content
+ * @returns {string}
+ */
+function parseSkillFileVersion(content) {
+  if (typeof content !== 'string' || !content.startsWith('---')) {
+    return 'unspecified';
+  }
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) {
+    return 'unspecified';
+  }
+  const block = content.slice(3, end);
+  const m = block.match(/^version:\s*["']?([^"'\r\n]+)["']?/m);
+  return m ? m[1].trim() : 'unspecified';
+}
+
+/**
+ * @param {string} root - viepilot package root
+ * @returns {Array<{ id: string, version: string, relativePath: string }>}
+ */
+function listSkillsWithVersions(root) {
+  const skillsDir = path.join(root, 'skills');
+  if (!fs.existsSync(skillsDir)) {
+    return [];
+  }
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const skillFile = path.join(skillsDir, ent.name, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+    const content = fs.readFileSync(skillFile, 'utf8');
+    out.push({
+      id: ent.name,
+      version: parseSkillFileVersion(content),
+      relativePath: path.join('skills', ent.name, 'SKILL.md').replace(/\\/g, '/'),
+    });
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+
+const WORKFLOW_SEMVER_NOTE = 'no semver in workflow markdown';
+
+/**
+ * @param {string} root
+ * @returns {Array<{ id: string, relativePath: string, semverInFile: null, note: string }>}
+ */
+function listWorkflows(root) {
+  const wfDir = path.join(root, 'workflows');
+  if (!fs.existsSync(wfDir)) {
+    return [];
+  }
+  const files = fs
+    .readdirSync(wfDir)
+    .filter((f) => f.endsWith('.md'))
+    .sort((a, b) => a.localeCompare(b));
+  return files.map((f) => ({
+    id: f.replace(/\.md$/i, ''),
+    relativePath: path.join('workflows', f).replace(/\\/g, '/'),
+    semverInFile: null,
+    note: WORKFLOW_SEMVER_NOTE,
+  }));
+}
+
+/**
+ * @param {string} root
+ * @returns {string|null}
+ */
+function tryGitHead(root) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: root,
+      encoding: 'utf8',
+      timeout: 8000,
+      windowsHide: true,
+    }).trim();
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {{ includeLatestNpm?: boolean }} [options]
+ */
+function buildInfoReport(root, options = {}) {
+  const includeLatestNpm = options.includeLatestNpm !== false;
+  const installedVersion = readInstalledVersion(root);
+  let pkgName = 'viepilot';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name) pkgName = pkg.name;
+  } catch (_e) {
+    /* keep default */
+  }
+
+  const report = {
+    packageRoot: root,
+    packageName: pkgName,
+    installedVersion: installedVersion || 'unknown',
+    latestNpm: includeLatestNpm ? fetchLatestNpmVersion() : { ok: false, error: 'skipped' },
+    gitHead: tryGitHead(root),
+    skills: listSkillsWithVersions(root),
+    workflows: listWorkflows(root),
+  };
+
+  return report;
+}
+
+module.exports = {
+  resolveViepilotPackageRoot,
+  readInstalledVersion,
+  fetchLatestNpmVersion,
+  parseSkillFileVersion,
+  listSkillsWithVersions,
+  listWorkflows,
+  tryGitHead,
+  buildInfoReport,
+  WORKFLOW_SEMVER_NOTE,
+};

package/lib/viepilot-update.cjs

@@ -0,0 +1,156 @@
+/**
+ * Plan and run `npm` upgrade for the viepilot package (FEAT-008 / vp-tools update).
+ */
+
+const path = require('path');
+const { spawnSync, execFileSync } = require('child_process');
+const viepilotInfo = require('./viepilot-info.cjs');
+
+/**
+ * @returns {string|null} absolute path to global .../node_modules/viepilot
+ */
+function tryGetNpmGlobalViepilotPath() {
+  try {
+    const root = execFileSync('npm', ['root', '-g'], {
+      encoding: 'utf8',
+      timeout: 10000,
+      windowsHide: true,
+    }).trim();
+    if (!root) return null;
+    return path.resolve(root, 'viepilot');
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * @param {string} viepilotPackageRoot
+ * @param {boolean} forceGlobal
+ * @param {string|null} globalViepilotPath
+ */
+function classifyInstall(viepilotPackageRoot, forceGlobal, globalViepilotPath) {
+  if (forceGlobal) {
+    return {
+      mode: 'global',
+      cwd: undefined,
+      npmArgs: ['install', '-g', 'viepilot@latest'],
+      ambiguous: false,
+    };
+  }
+  const r = path.resolve(viepilotPackageRoot);
+  if (globalViepilotPath) {
+    const g = path.resolve(globalViepilotPath);
+    if (r === g) {
+      return {
+        mode: 'global',
+        cwd: undefined,
+        npmArgs: ['install', '-g', 'viepilot@latest'],
+        ambiguous: false,
+      };
+    }
+  }
+  const localSuffix = path.join('node_modules', 'viepilot');
+  if (r.endsWith(localSuffix)) {
+    const projectRoot = path.resolve(viepilotPackageRoot, '..', '..');
+    return {
+      mode: 'local',
+      cwd: projectRoot,
+      npmArgs: ['install', 'viepilot@latest'],
+      ambiguous: false,
+    };
+  }
+  return {
+    mode: 'global',
+    cwd: undefined,
+    npmArgs: ['install', '-g', 'viepilot@latest'],
+    ambiguous: true,
+  };
+}
+
+/**
+ * Rough semver compare for x.y.z (numeric segments only).
+ * @returns {-1|0|1|null} null if either side empty
+ */
+function compareSemver(a, b) {
+  if (a == null || b == null || a === '' || b === '') return null;
+  const pa = String(a).split(/[.+]/).map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split(/[.+]/).map((x) => parseInt(x, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da < db) return -1;
+    if (da > db) return 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {{ startDir: string, forceGlobal?: boolean }} opts
+ */
+function buildUpdatePlan(opts) {
+  const startDir = opts.startDir;
+  const forceGlobal = Boolean(opts.forceGlobal);
+  const root = viepilotInfo.resolveViepilotPackageRoot(startDir);
+  if (!root) {
+    return { ok: false, error: 'Could not locate viepilot package root' };
+  }
+
+  const installed = viepilotInfo.readInstalledVersion(root);
+  const latestResult = viepilotInfo.fetchLatestNpmVersion();
+
+  if (latestResult.ok && installed && compareSemver(installed, latestResult.version) >= 0) {
+    return {
+      ok: true,
+      alreadyLatest: true,
+      installedVersion: installed,
+      latestVersion: latestResult.version,
+      viepilotRoot: root,
+    };
+  }
+
+  const globalViepilotPath = tryGetNpmGlobalViepilotPath();
+  const layout = classifyInstall(root, forceGlobal, globalViepilotPath);
+  const displayCommand = layout.cwd
+    ? `(cwd ${layout.cwd}) npm ${layout.npmArgs.join(' ')}`
+    : `npm ${layout.npmArgs.join(' ')}`;
+
+  return {
+    ok: true,
+    alreadyLatest: false,
+    installedVersion: installed,
+    latestVersion: latestResult.ok ? latestResult.version : null,
+    latestNpmError: latestResult.ok ? null : latestResult.error,
+    viepilotRoot: root,
+    mode: layout.mode,
+    cwd: layout.cwd,
+    npmArgs: layout.npmArgs,
+    ambiguous: layout.ambiguous,
+    displayCommand,
+  };
+}
+
+/**
+ * @param {object} plan - from buildUpdatePlan (not alreadyLatest)
+ * @returns {{ ok: boolean, code?: number }}
+ */
+function runNpmUpdate(plan) {
+  const r = spawnSync('npm', plan.npmArgs, {
+    cwd: plan.cwd,
+    stdio: 'inherit',
+    shell: false,
+    windowsHide: true,
+  });
+  if (r.status === 0) {
+    return { ok: true };
+  }
+  return { ok: false, code: r.status == null ? 1 : r.status };
+}
+
+module.exports = {
+  tryGetNpmGlobalViepilotPath,
+  classifyInstall,
+  compareSemver,
+  buildUpdatePlan,
+  runNpmUpdate,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.3.1",
+  "version": "1.6.1",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {
@@ -16,6 +16,7 @@
     "test:watch": "jest --watch",
     "readme:sync": "node scripts/sync-readme-metrics.cjs",
     "lint:cli": "node --check bin/vp-tools.cjs && node --check bin/viepilot.cjs",
+    "verify:ui-direction": "node scripts/verify-ui-direction-pages.cjs",
     "verify:release": "npm run lint:cli && npm test && npm pack --dry-run",
     "prepublishOnly": "npm run verify:release",
     "smoke:published": "node scripts/smoke-published.cjs",

package/skills/vp-brainstorm/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-brainstorm
 description: "Brainstorm session để thu thập ý tưởng, quyết định cho dự án"
-version: 0.3.0
+version: 0.4.0
 ---
 
 <cursor_skill_adapter>
@@ -25,7 +25,8 @@ Hỗ trợ:
 - Xem lại session trước đó
 - Landing page layout discovery (hỏi thêm để chốt bố cục)
 - In-session research (research ngay trong phiên brainstorm theo yêu cầu)
-- UI Direction mode: tạo/cập nhật HTML prototype + notes trong `.viepilot/ui-direction/{session-id}/`
+- UI Direction mode: tạo/cập nhật HTML prototype + notes trong `.viepilot/ui-direction/{session-id}/` — hỗ trợ **multi-page** (`pages/{slug}.html` + hub `index.html`) và hook **`## Pages inventory`** trong `notes.md` khi có `pages/` (FEAT-007)
+- **Product horizon (ENH-014):** mọi session phải duy trì **`## Product horizon`** khi thảo luận capability/milestone — tier tags `(MVP)` / `(Post-MVP)` / `(Future)`, non-goals, deferred capabilities; hoặc ghi rõ **single-release / no deferred epics** (contract: `workflows/brainstorm.md`)
 
 **Creates/Updates:**
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
@@ -56,10 +57,11 @@ Key steps:
 3. Load context if continuing
 4. Run interactive Q&A với topic-based structure
 5. Nếu topic là landing page: hỏi thêm bố cục + tham khảo `21st.dev` để đề xuất section/components
-6. Nếu topic cần UI/UX: tạo/cập nhật UI Direction artifacts (`index.html`, `style.css`, `notes.md`) trong `.viepilot/ui-direction/{session-id}/`
+6. Nếu topic cần UI/UX: tạo/cập nhật UI Direction artifacts trong `.viepilot/ui-direction/{session-id}/` — legacy: `index.html` + `style.css` + `notes.md`; multi-page: thêm `pages/*.html`, `index.html` làm hub, và sau mỗi thay đổi page cập nhật **`## Pages inventory`** trong `notes.md` (xem `docs/user/features/ui-direction.md`)
 7. Nếu user yêu cầu research hoặc cần làm rõ quyết định: research ngay trong session và quay lại topic
-8. Save session with structured format (bao gồm research notes + UI direction references khi có)
-9. Suggest next action: `/vp-crystallize`
+8. Khi topic thêm/sửa capability hoặc release scope: cập nhật **`## Product horizon`** trong session (merge, không xóa tier tags im lặng) theo `workflows/brainstorm.md`
+9. Save session with structured format (bao gồm research notes + UI direction references + **Product horizon** khi có)
+10. Suggest next action: `/vp-crystallize`
 </process>
 
 <success_criteria>
@@ -71,5 +73,7 @@ Key steps:
 - [ ] 21st.dev references included when relevant
 - [ ] Research can be executed inside the same brainstorm session
 - [ ] UI Direction artifacts created/updated when UI mode is active
+- [ ] Multi-page sessions: hub links + `## Pages inventory` stay in sync with `pages/*.html`
+- [ ] `## Product horizon` present với MVP / Post-MVP / Future (hoặc explicit single-release statement) khi scope được thảo luận
 - [ ] Next steps suggested
 </success_criteria>

package/skills/vp-crystallize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-crystallize
 description: "Chuyển đổi brainstorm thành executable artifacts"
-version: 0.3.0
+version: 0.4.0
 ---
 
 <cursor_skill_adapter>
@@ -25,9 +25,9 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 ├── AI-GUIDE.md          # Navigation cho AI
 ├── PROJECT-META.md      # Metadata dự án
 ├── ARCHITECTURE.md      # System design
-├── PROJECT-CONTEXT.md   # Domain knowledge
+├── PROJECT-CONTEXT.md   # Domain knowledge + `<product_vision>` (phased scope)
 ├── SYSTEM-RULES.md      # Coding rules & standards
-├── ROADMAP.md           # Phases & tasks
+├── ROADMAP.md           # MVP phases & tasks + **Post-MVP / Product horizon** block (mandatory)
 ├── TRACKER.md           # Progress tracking
 ├── HANDOFF.json         # Machine-readable state
 └── schemas/             # Database, API, Kafka schemas
@@ -75,12 +75,15 @@ Ask user for:
 - Load all brainstorm sessions
 - Extract: decisions, architecture, schemas, features
 - Extract selected tech stacks
-- Validate completeness
+- **Product horizon (ENH-014):** parse each session **`## Product horizon`**; build consolidated **horizon inventory**; record **single-release** mode when stated; run **validation gate** (missing section vs multi-release discussion → stop and ask; tier conflicts → stop) — full contract: `workflows/crystallize.md` Step 1
+- Validate completeness (tech stack, features, schema/API clarity, **horizon gate**)
 
 ### Step 1A: Consume UI direction (if present)
-- Read `.viepilot/ui-direction/{session-id}/notes.md`, `index.html`, `style.css`
-- Carry approved layout/component decisions into architecture + roadmap artifacts
-- Mark assumptions explicitly if direction artifacts are missing
+- Read `.viepilot/ui-direction/{session-id}/notes.md` first, then `style.css`, then HTML:
+  - **Multi-page:** if `pages/*.html` exists → require `## Pages inventory` in `notes.md`, validate it lists every page file, read each `pages/*.html` plus hub `index.html` for navigation.
+  - **Legacy:** no `pages/` → read `index.html` + `style.css` as before.
+- Carry approved layout/component decisions into architecture + roadmap artifacts; **architecture must reference all pages** from inventory when multi-page.
+- Mark assumptions explicitly if direction artifacts are missing or inventory/files mismatch.
 
 ### Step 1B: Official stack research (mandatory)
 - For every selected stack, research official docs and authoritative sources
@@ -119,6 +122,7 @@ Ask user for:
 - Business rules
 - Conventions
 - Constraints
+- Fill **`<product_vision>`** from template (`templates/project/PROJECT-CONTEXT.md`): MVP boundary, Post-MVP / Future themes, anti-goals — aligned with brainstorm horizon + Step 1 inventory
 
 ### Step 6: Generate SYSTEM-RULES.md
 - Architecture rules
@@ -131,10 +135,9 @@ Ask user for:
 - Stack-specific rules from cache
 
 ### Step 7: Generate ROADMAP.md
-- Break into phases
-- Define tasks per phase
-- Set acceptance criteria
-- Add verification checkpoints
+- Use `templates/project/ROADMAP.md` — **executable MVP phases** first (tasks, criteria, verification)
+- **Mandatory `## Post-MVP / Product horizon`:** epic-level deferred work from horizon inventory **or** explicit single-release statement (no silent omission)
+- **Self-check before finalize:** non-empty horizon inventory must appear in ROADMAP; if mismatch → stop and ask user — see `workflows/crystallize.md` Step 7
 
 ### Step 8: Generate schemas/
 - database-schema.sql
@@ -168,7 +171,9 @@ Ask user for:
 - [ ] All artifacts created in .viepilot/
 - [ ] PROJECT-META.md has complete metadata
 - [ ] SYSTEM-RULES.md has all standards
-- [ ] ROADMAP.md has phases with tasks
+- [ ] Step 1 horizon extracted or explicit single-release recorded; validation gate satisfied
+- [ ] PROJECT-CONTEXT.md includes populated **`<product_vision>`** (template placeholders filled from brainstorm)
+- [ ] ROADMAP.md has MVP phases with tasks **and** mandatory Post-MVP / horizon block (or explicit single-release statement)
 - [ ] TRACKER.md initialized
 - [ ] Project files created
 - [ ] Git committed