ridgeline 0.7.5 → 0.7.12

package/README.md

@@ -5,35 +5,39 @@
 Build harness for long-horizon software execution using AI agents.
 
 Ridgeline decomposes large software ideas into phased builds using a
-multi-agent pipeline (shaper, specifier, researcher, refiner, planner, builder,
-reviewer) driven by the Claude CLI. It manages state through git checkpoints,
+multi-agent pipeline (shaper, designer, specifier, researcher, refiner, planner,
+builder, reviewer) driven by the Claude CLI. It manages state through git checkpoints,
 tracks costs, and supports resumable execution when things go wrong.
 
 ## How it works
 
 1. **Shape** -- describe what you want built. The shaper agent analyzes your
    codebase and asks clarifying questions to produce a structured shape document.
-2. **Specify** -- an ensemble of three specialist agents (completeness, clarity,
+2. **Design** (optional) -- the designer agent establishes a visual design system
+   (`design.md`) through interactive Q&A. Auto-runs the asset catalog if assets
+   exist, and injects catalog context (detected style, palette, resolution) into
+   the design conversation. Works at build level or project level.
+3. **Specify** -- an ensemble of three specialist agents (completeness, clarity,
    pragmatism) drafts spec proposals, then a synthesizer merges them into
    `spec.md`, `constraints.md`, and optionally `taste.md`.
-3. **Research** (optional) -- an ensemble of research specialists (academic,
+4. **Research** (optional) -- an ensemble of research specialists (academic,
    ecosystem, competitive) investigates the spec using web sources, then a
    synthesizer merges findings into `research.md`. A gap analysis agenda step
    runs before specialist dispatch to focus research on spec gaps. Findings
    accumulate across iterations rather than being overwritten. A quick
    single-agent mode is also available. See [Research and Refine](docs/research.md).
-4. **Refine** (optional) -- the refiner agent rewrites `spec.md` incorporating
+5. **Refine** (optional) -- the refiner agent rewrites `spec.md` incorporating
    research findings and writes `spec.changelog.md` documenting what changed.
    Additive by default -- adds insights without removing user-authored content.
-5. **Plan** -- an ensemble of three specialist planners (simplicity,
+6. **Plan** -- an ensemble of three specialist planners (simplicity,
    thoroughness, velocity) proposes phase decompositions, then a synthesizer
    merges them into numbered phase files with acceptance criteria.
-6. **Build** -- for each phase the builder agent implements the spec inside your
+7. **Build** -- for each phase the builder agent implements the spec inside your
    repo, then creates a git checkpoint.
-7. **Review** -- the reviewer agent (read-only) checks the output against the
+8. **Review** -- the reviewer agent (read-only) checks the output against the
    acceptance criteria and returns a structured verdict. On failure, the harness
    generates a feedback file from the verdict for the builder's next attempt.
-8. **Retry or advance** -- failed phases are retried up to a configurable limit;
+9. **Retry or advance** -- failed phases are retried up to a configurable limit;
    passing phases hand off context to the next one.
 
 ## Install
@@ -42,6 +46,8 @@ tracks costs, and supports resumable execution when things go wrong.
 npm install -g ridgeline
 ```
 
+**Platform:** macOS and Linux. Windows is not supported.
+
 Ridgeline requires the [Claude CLI](https://docs.anthropic.com/en/docs/claude-code)
 to be installed and authenticated.
 
@@ -63,13 +69,17 @@ ridgeline my-feature "Build a REST API for task management"
 
 # Or run each stage individually
 ridgeline shape my-feature "Build a REST API for task management"
+ridgeline design my-feature            # optional: establish visual design system
 ridgeline spec my-feature
-ridgeline research my-feature --deep  # optional: enrich spec with web research
-ridgeline refine my-feature           # optional: merge research into spec
+ridgeline research my-feature --deep   # optional: enrich spec with web research
+ridgeline refine my-feature            # optional: merge research into spec
 ridgeline plan my-feature
 ridgeline dry-run my-feature   # preview before committing
 ridgeline build my-feature
 
+# Catalog media assets (images, audio, video, text)
+ridgeline catalog my-feature --classify --describe
+
 # Resume after a failure (re-run build)
 ridgeline build my-feature
 
@@ -85,8 +95,8 @@ ridgeline clean
 ### `ridgeline [build-name] [input]` (default)
 
 Auto-advances the build through the next incomplete pipeline stage
-(shape → spec → plan → build; research and refine are opt-in). Accepts all
-flags from the individual commands.
+(shape → spec → plan → build; design, research, and refine are opt-in).
+Accepts all flags from the individual commands.
 
 ### `ridgeline shape [build-name] [input]`
 
@@ -100,6 +110,20 @@ path to an existing document or a natural language description.
 | `--timeout <minutes>` | `10` | Max duration per turn |
 | `--flavour <name-or-path>` | none | Agent flavour: built-in name or path to custom agents |
 
+### `ridgeline design [build-name]`
+
+Establishes or updates a visual design system through interactive Q&A. Produces
+`design.md` in the build directory (or project-level if no build name is given).
+If an asset directory exists but no catalog has been built, the catalog is
+auto-run and its summary (detected style, palette, resolution, category
+breakdown) is injected into the designer's context.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model <name>` | `opus` | Model for designer agent |
+| `--timeout <minutes>` | `10` | Max duration per turn |
+| `--flavour <name-or-path>` | none | Agent flavour: built-in name or path to custom agents |
+
 ### `ridgeline spec [build-name]`
 
 Runs the specifier ensemble: three specialist agents (completeness, clarity,
@@ -189,7 +213,70 @@ Resets pipeline state to a given stage and deletes downstream artifacts.
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--to <stage>` | (required) | Stage to rewind to: `shape`, `spec`, `research`, `refine`, or `plan` |
+| `--to <stage>` | (required) | Stage to rewind to: `shape`, `design`, `spec`, `research`, `refine`, or `plan` |
+
+### `ridgeline catalog [build-name]`
+
+Indexes media assets into `asset-catalog.json` — a structured metadata file that
+feeds into the design and build phases. Supports images, audio, video, and text
+files. The catalog pipeline runs in three tiers:
+
+1. **Deterministic metadata** (always runs) — scans the asset directory, extracts
+   file metadata (size, hash, dimensions for images), detects spritesheets and
+   tileable textures, infers category from directory structure and filename
+   conventions (e.g., `characters/knight-walk.png` → category "characters",
+   subject "knight", state "walk"). Computes project-wide visual identity
+   aggregates (detected style, palette, resolution).
+2. **Classification** (with `--classify`) — assigns categories to uncategorized
+   files. Filename heuristics run first (e.g., `bg_*` → backgrounds, `sfx_*` →
+   sfx). Files that don't match any pattern fall through to AI classification
+   using Claude vision for images or text prompts for other media types.
+3. **Vision enrichment** (with `--describe`) — uses Claude vision to add semantic
+   descriptions, facing direction, pose, style tags, and animation type for image
+   assets. Layout and UI assets are auto-described regardless of the flag.
+4. **Sprite packing** (with `--pack`) — groups image assets by category and packs
+   them into 2048×2048 sprite atlases with PixiJS-compatible JSON metadata.
+   Backgrounds and layout references are excluded.
+
+The catalog is incremental — unchanged files (by content hash) are skipped on
+subsequent runs unless `--force` is set.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--asset-dir <path>` | auto | Path to asset directory |
+| `--classify` | off | AI-classify uncategorized files into categories |
+| `--describe` | off | Add vision-based descriptions for all image assets |
+| `--pack` | off | Generate sprite atlases after cataloging |
+| `--batch` | off | Batch multiple images per vision call |
+| `--force` | off | Re-process all assets ignoring content hash |
+| `--model <name>` | `opus` | Model for vision and classification |
+| `--timeout <minutes>` | `5` | Max duration per AI call |
+
+Asset directory is resolved in order: `--asset-dir` flag,
+`.ridgeline/builds/<build-name>/assets/`, `.ridgeline/assets/`, or the
+`assetDir` field in `settings.json`.
+
+### `ridgeline retrospective [build-name]`
+
+Analyzes a completed build and extracts learnings for future builds. Reads the
+trajectory log, budget, state, and any feedback files, then appends structured
+insights to `.ridgeline/learnings.md`. Future builds automatically pick up these
+learnings if the file exists.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model <name>` | `opus` | Model for retrospective agent |
+| `--timeout <minutes>` | `10` | Max duration |
+| `--flavour <name-or-path>` | none | Agent flavour: built-in name or path to custom agents |
+
+### `ridgeline check`
+
+Checks recommended tools and prerequisites for a flavour. Reports which
+external tools are available and which are missing.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--flavour <name-or-path>` | from settings | Agent flavour to check |
 
 ### `ridgeline clean`
 
@@ -201,15 +288,19 @@ WIP branches. Use this after inspecting a failed build.
 ```text
 .ridgeline/
 ├── settings.json      # Optional project-level config (network allowlist, etc.)
+├── design.md          # Optional project-level visual design system
+├── learnings.md       # Optional accumulated build learnings (from retrospective)
 ├── worktrees/         # Git worktrees for active builds
 │   └── <build-name>/  # Isolated working directory per build
 └── builds/<build-name>/
     ├── shape.md           # Structured project context (from shaper)
+    ├── design.md          # Optional visual design system (from designer)
     ├── spec.md            # What to build
     ├── constraints.md     # Technical constraints and check commands
     ├── taste.md           # Optional coding style preferences
     ├── research.md        # Optional research findings (from researcher)
     ├── spec.changelog.md  # Optional changelog of spec refinements
+    ├── asset-catalog.json # Optional indexed media assets (from catalog)
     ├── phases/
     │   ├── 01-scaffold.md
     │   ├── 01-scaffold.feedback.md  # Generated by harness on review failure

package/dist/agents/core/designer.md

@@ -53,12 +53,22 @@ Round 1 — Art Direction:
 - Art style: pixel art, vector, 3D, hand-drawn, realistic
 - Color palette: mood, saturation level, palette constraints
 - Asset dimensions: sprite sizes, texture resolutions, canvas size
+- Shape language: proportions (chunky/slim), corners (rounded/sharp), detail level
+- Rendering: pixel scale, scaling mode (nearest/bilinear), canvas size
 
 Round 2 — UI & HUD:
 
 - HUD/overlay style: transparency, position, font choices
 - Menu design: navigation patterns, transition styles
 - In-game text: dialogue boxes, tooltips, damage numbers
+- Layout regions: where health, score, inventory, and action buttons go
+- Mood: overall atmosphere and tone in a brief phrase
+
+Round 3 — Asset Integration (when asset catalog data is in context):
+
+- Asset manifest review: confirm discovered assets match creative intent
+- Background treatment: mood, parallax, scroll behavior for each background
+- Asset loading strategy: preload vs lazy, atlas format, base path
 
 **For print-layout projects:**
 
@@ -129,3 +139,11 @@ The format is flexible — brand guidelines, informal notes, formal style guides
 **Respect existing design.md.** If one exists, read it as starting context. Offer to refine or extend, don't start from scratch unless asked.
 
 **Stay in design territory.** Don't ask about code architecture, error handling, or implementation details. Those belong to the shaper and specifier.
+
+**When asset catalog data is present in context:**
+
+- Propose palette, style, resolution, and scaling defaults derived from the catalog's visual identity analysis. Include these as `suggestedAnswer` values.
+- Present the asset manifest summary for user confirmation.
+- Use layout region data (if available) to propose HUD/menu arrangements.
+- Flag any catalog warnings about palette mismatches for user review.
+- Cover asset loading strategy (preload/lazy, format, base path) in your questions.

package/dist/agents/core/planner.md

@@ -65,6 +65,38 @@ Every phase file must follow this structure exactly:
 <Relevant sections of spec.md for this phase, quoted or summarized.>
 ```
 
+## Phase Dependencies (Parallel Execution)
+
+Phases can declare dependencies to enable parallel execution. When a phase depends only on a subset of prior phases (not the immediately preceding one), add YAML frontmatter:
+
+```markdown
+---
+depends_on: [01-scaffold]
+---
+# Phase 3: API Endpoints
+...
+```
+
+**Rules for dependencies:**
+
+- Phases without frontmatter automatically depend on the immediately preceding phase (sequential execution).
+- A phase can only depend on phases with a lower index number.
+- If a phase reads or modifies files created by another phase, it must depend on that phase.
+- Phase 01 never has dependencies (it is the root).
+- Use dependencies to enable parallelism when phases work on independent parts of the codebase.
+- When in doubt, omit the frontmatter. False parallelism is worse than false sequentiality.
+
+**Example: fan-out pattern**
+
+```text
+01-scaffold       (no deps — root)
+02-api            depends_on: [01-scaffold]
+03-ui             depends_on: [01-scaffold]
+04-integration    depends_on: [02-api, 03-ui]
+```
+
+Phases 02 and 03 run in parallel after 01 completes. Phase 04 waits for both.
+
 ## Rules
 
 **No implementation details.** Do not specify creation order, internal structure, sub-agent assignments, implementation patterns, or approach. The builder decides all of this. You describe the destination, not the route.

package/dist/agents/core/retrospective.md

@@ -0,0 +1,64 @@
+---
+name: retrospective
+description: Analyzes a completed build to extract learnings, patterns, and recommendations for future builds
+model: opus
+---
+
+You are a build retrospective analyst. After a build completes, you analyze the trajectory, budget, feedback files, and final state to extract actionable learnings.
+
+## Your inputs
+
+These are injected into your context:
+
+1. **trajectory.jsonl** — chronological event log of the entire build (plan, build, review, retry events with durations and costs)
+2. **budget.json** — per-phase, per-role cost breakdown
+3. **Feedback files** — reviewer verdicts and feedback from any retried phases
+4. **state.json** — final build state with phase statuses, durations, and retry counts
+
+## Your process
+
+### 1. Analyze the build trajectory
+
+- Which phases completed cleanly on the first attempt?
+- Which phases required retries? What were the reviewer's objections?
+- Where was the most time and money spent?
+- Were there any patterns in failures (e.g., the same type of issue recurring)?
+
+### 2. Extract learnings
+
+Produce a structured retrospective in the following format. Be specific — name files, patterns, and concrete observations. Avoid generic advice.
+
+```markdown
+## Build: {build-name} ({date})
+
+### What Worked
+- Specific things that went well (clean passes, efficient phases)
+
+### What Didn't
+- Specific failures, retries, and their root causes
+
+### Patterns to Repeat
+- Concrete patterns worth carrying forward (spec structures, constraint phrasings, phase granularity choices)
+
+### Patterns to Avoid
+- Anti-patterns observed (overly broad phases, missing constraints, spec ambiguities)
+
+### Cost Analysis
+- Total cost and duration
+- Most expensive phases and why
+- Efficiency observations
+
+### Recommendations for Next Build
+- Specific, actionable suggestions for improving spec, constraints, or phase structure
+```
+
+### 3. Write the output
+
+Append your retrospective to the learnings file. Do NOT overwrite previous entries — each build's learnings accumulate.
+
+## Rules
+
+- Be concrete and specific, not generic. "Phase 03 failed because the spec didn't mention auth middleware" is useful. "Consider being more specific in specs" is not.
+- Focus on what the build artifacts reveal, not hypotheticals.
+- Keep each section to 3-5 bullet points. Quality over quantity.
+- If the build completed cleanly with no retries, say so — a clean build is still worth noting.

package/dist/catalog/build-catalog.d.ts

@@ -0,0 +1,21 @@
+import { AssetCatalog, CatalogOptions } from "./types";
+export type CatalogResult = {
+    catalog: AssetCatalog;
+    stats: {
+        total: number;
+        added: number;
+        updated: number;
+        unchanged: number;
+        pruned: number;
+        classified: number;
+    };
+    /** Files in auto-describe categories that need vision enrichment. */
+    needsVisionDescribe: string[];
+};
+type BuildCatalogOpts = Pick<CatalogOptions, "isForce" | "isClassify" | "model" | "timeout">;
+/**
+ * Build or update the asset catalog.
+ * Handles all media types. Vision enrichment and sprite packing are handled separately.
+ */
+export declare const buildCatalog: (assetDir: string, buildDir: string, opts: BuildCatalogOpts) => Promise<CatalogResult>;
+export {};

package/dist/catalog/build-catalog.js

@@ -0,0 +1,305 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCatalog = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const parse_conventions_1 = require("./parse-conventions");
+const extract_metadata_1 = require("./extract-metadata");
+const classify_1 = require("./classify");
+/** Map file extensions to media types. */
+const MEDIA_EXTENSIONS = {
+    // images
+    ".png": "image", ".jpg": "image", ".jpeg": "image",
+    ".gif": "image", ".webp": "image", ".svg": "image", ".avif": "image",
+    // audio
+    ".mp3": "audio", ".wav": "audio", ".ogg": "audio",
+    ".flac": "audio", ".aac": "audio", ".m4a": "audio",
+    // video
+    ".mp4": "video", ".webm": "video", ".mov": "video", ".avi": "video",
+    // text
+    ".txt": "text", ".json": "text", ".csv": "text",
+    ".md": "text", ".yaml": "text", ".yml": "text",
+};
+/** Detect media type from file extension. */
+const detectMediaType = (filePath) => MEDIA_EXTENSIONS[path.extname(filePath).toLowerCase()] ?? null;
+/** Recursively walk a directory tree and return all asset file paths (relative to root). */
+const walkAssets = (dir, root) => {
+    const base = root ?? dir;
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkAssets(fullPath, base));
+        }
+        else if (detectMediaType(entry.name) !== null) {
+            results.push(path.relative(base, fullPath));
+        }
+    }
+    return results;
+};
+/** Load existing catalog from disk, if present. */
+const loadExistingCatalog = (catalogPath) => {
+    if (!fs.existsSync(catalogPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+};
+/** Build a lookup map from an existing catalog for incremental updates. */
+const buildHashIndex = (catalog) => {
+    const index = new Map();
+    if (!catalog)
+        return index;
+    for (const entry of catalog.assets) {
+        index.set(entry.file, entry);
+    }
+    return index;
+};
+/** Detect the most common resolution among square or nearly-square image assets. */
+const detectResolution = (assets) => {
+    const sizes = new Map();
+    for (const a of assets) {
+        if (a.mediaType !== "image")
+            continue;
+        if (a.isSpritesheet && a.frameSize) {
+            const key = `${a.frameSize.w}x${a.frameSize.h}`;
+            sizes.set(key, (sizes.get(key) ?? 0) + 1);
+        }
+        else if (a.width && a.height && a.width === a.height && a.width <= 256) {
+            const key = `${a.width}x${a.height}`;
+            sizes.set(key, (sizes.get(key) ?? 0) + 1);
+        }
+    }
+    if (sizes.size === 0)
+        return null;
+    return [...sizes.entries()].sort((a, b) => b[1] - a[1])[0][0];
+};
+/** Build aggregate palette from all image assets (top 8 most frequent colours). */
+const detectPalette = (assets) => {
+    const freq = new Map();
+    for (const a of assets) {
+        if (!a.palette)
+            continue;
+        for (const c of a.palette) {
+            freq.set(c, (freq.get(c) ?? 0) + 1);
+        }
+    }
+    return [...freq.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 8)
+        .map(([colour]) => colour);
+};
+/** Detect visual style from image asset properties. */
+const detectStyle = (assets) => {
+    const imageAssets = assets.filter((a) => a.mediaType === "image");
+    if (imageAssets.length === 0)
+        return null;
+    const smallAssets = imageAssets.filter((a) => {
+        const size = a.isSpritesheet && a.frameSize
+            ? Math.max(a.frameSize.w, a.frameSize.h)
+            : Math.max(a.width ?? 0, a.height ?? 0);
+        return size <= 128;
+    });
+    if (smallAssets.length > imageAssets.length * 0.6)
+        return "pixel-art";
+    const svgCount = imageAssets.filter((a) => a.format === "svg").length;
+    if (svgCount > imageAssets.length * 0.5)
+        return "vector";
+    return null;
+};
+/** Derive aggregate visual identity from all cataloged assets. */
+const deriveVisualIdentity = (assets) => {
+    const style = detectStyle(assets);
+    return {
+        detectedStyle: style,
+        detectedPalette: detectPalette(assets),
+        detectedResolution: detectResolution(assets),
+        detectedScaling: style === "pixel-art" ? "nearest" : null,
+    };
+};
+/** Compare detected palette against design.md palette and produce warnings. */
+const checkPaletteMismatches = (assets, buildDir, ridgelineDir) => {
+    const warnings = [];
+    const designPaths = [
+        path.join(buildDir, "design.md"),
+        path.join(ridgelineDir, "design.md"),
+    ];
+    let designContent = null;
+    for (const p of designPaths) {
+        if (fs.existsSync(p)) {
+            designContent = fs.readFileSync(p, "utf-8");
+            break;
+        }
+    }
+    if (!designContent)
+        return warnings;
+    const hexPattern = /#[0-9a-fA-F]{6}/g;
+    const designColours = new Set([...designContent.matchAll(hexPattern)].map((m) => m[0].toLowerCase()));
+    if (designColours.size === 0)
+        return warnings;
+    for (const asset of assets) {
+        if (!asset.palette)
+            continue;
+        const offPalette = asset.palette.filter((c) => !designColours.has(c.toLowerCase()));
+        if (offPalette.length > 0) {
+            warnings.push(`${asset.file} uses colours (${offPalette.join(", ")}) not found in design.md palette. This may be intentional.`);
+        }
+    }
+    return warnings;
+};
+/**
+ * Build or update the asset catalog.
+ * Handles all media types. Vision enrichment and sprite packing are handled separately.
+ */
+const buildCatalog = async (assetDir, buildDir, opts) => {
+    const ridgelineDir = path.join(process.cwd(), ".ridgeline");
+    const catalogPath = path.join(buildDir, "asset-catalog.json");
+    const existing = loadExistingCatalog(catalogPath);
+    const hashIndex = buildHashIndex(existing);
+    const assetFiles = walkAssets(assetDir);
+    const existingFiles = new Set(hashIndex.keys());
+    const assets = [];
+    const needsVisionDescribe = [];
+    let added = 0;
+    let updated = 0;
+    let unchanged = 0;
+    let classified = 0;
+    const timeoutMs = opts.timeout * 60 * 1000;
+    const totalFiles = assetFiles.length;
+    let processedCount = 0;
+    for (const relPath of assetFiles) {
+        const absPath = path.join(assetDir, relPath);
+        const hash = (0, extract_metadata_1.computeContentHash)(absPath);
+        const prev = hashIndex.get(relPath);
+        existingFiles.delete(relPath);
+        // Skip unchanged files (unless --force)
+        if (!opts.isForce && prev && prev.hash === hash) {
+            assets.push(prev);
+            unchanged++;
+            // Still track if auto-describe category needs vision
+            if (prev.mediaType === "image") {
+                const conv = (0, parse_conventions_1.parseConventions)(relPath);
+                if (parse_conventions_1.AUTO_DESCRIBE_CATEGORIES.has(conv.category) && !prev.description) {
+                    needsVisionDescribe.push(relPath);
+                }
+            }
+            continue;
+        }
+        processedCount++;
+        const mediaType = detectMediaType(relPath);
+        const conventions = (0, parse_conventions_1.parseConventions)(relPath);
+        const basic = (0, extract_metadata_1.extractBasicMetadata)(absPath);
+        // Build the entry — image-specific metadata only for images
+        const entry = {
+            file: relPath,
+            hash,
+            mediaType,
+            category: conventions.category,
+            name: conventions.name,
+            subject: conventions.subject,
+            state: conventions.state,
+            fileSizeBytes: basic.fileSizeBytes,
+            extension: basic.extension,
+        };
+        if (mediaType === "image") {
+            const meta = await (0, extract_metadata_1.extractImageMetadata)(absPath);
+            const palette = await (0, extract_metadata_1.extractPalette)(absPath);
+            const spritesheet = (0, extract_metadata_1.detectSpritesheet)(meta.width, meta.height);
+            const isTileable = await (0, extract_metadata_1.detectTileable)(absPath, meta.width, meta.height);
+            const defaults = (0, parse_conventions_1.inferDefaults)(conventions.category);
+            entry.width = meta.width;
+            entry.height = meta.height;
+            entry.format = meta.format;
+            entry.hasAlpha = meta.hasAlpha;
+            entry.channels = meta.channels;
+            entry.dominantColour = palette.dominantColour;
+            entry.palette = palette.palette;
+            entry.isSpritesheet = spritesheet.isSpritesheet;
+            entry.frameCount = spritesheet.frameCount;
+            entry.frameSize = spritesheet.frameSize;
+            entry.frameDirection = spritesheet.frameDirection;
+            entry.suggestedAnchor = defaults.anchor;
+            entry.suggestedZLayer = defaults.zLayer;
+            entry.isTileable = isTileable;
+        }
+        // Classify uncategorized files when --classify is set
+        if (conventions.category === "uncategorized" && opts.isClassify) {
+            process.stderr.write(`\x1b[90m  Classifying ${relPath} (${processedCount}/${totalFiles})...\x1b[0m\n`);
+            const result = (0, classify_1.classifyByHeuristics)(relPath, basic.extension, mediaType)
+                ?? (0, classify_1.classifyWithAI)(absPath, relPath, basic.extension, mediaType, opts.model, timeoutMs);
+            entry.category = result.category;
+            entry.isClassified = true;
+            entry.classificationConfidence = result.confidence;
+            classified++;
+            // Update anchor/zLayer defaults based on new category
+            if (mediaType === "image") {
+                const defaults = (0, parse_conventions_1.inferDefaults)(entry.category);
+                entry.suggestedAnchor = defaults.anchor;
+                entry.suggestedZLayer = defaults.zLayer;
+            }
+        }
+        assets.push(entry);
+        if (mediaType === "image" && parse_conventions_1.AUTO_DESCRIBE_CATEGORIES.has(entry.category)) {
+            needsVisionDescribe.push(relPath);
+        }
+        if (prev) {
+            updated++;
+        }
+        else {
+            added++;
+        }
+    }
+    // Remaining entries in existingFiles are pruned (files removed from disk)
+    const pruned = existingFiles.size;
+    const catalog = {
+        generatedAt: new Date().toISOString(),
+        assetDir,
+        isDescribed: existing?.isDescribed ?? false,
+        visualIdentity: deriveVisualIdentity(assets),
+        warnings: checkPaletteMismatches(assets, buildDir, ridgelineDir),
+        assets,
+    };
+    return {
+        catalog,
+        stats: { total: assets.length, added, updated, unchanged, pruned, classified },
+        needsVisionDescribe,
+    };
+};
+exports.buildCatalog = buildCatalog;
+//# sourceMappingURL=build-catalog.js.map