re-walkthrough-pro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles J Dove
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+<p align="center">
+  <img src="docs/hero.png" alt="RE Walkthrough Pro — cinematic Zillow-to-video property walkthroughs for Claude Code" width="900">
+</p>
+
+# RE Walkthrough Pro
+
+> Turn a Zillow listing into a cinematic, room-by-room walkthrough video — right inside [Claude Code](https://claude.ai/code). Apify pulls the photos, Higgsfield animates each room, ffmpeg stitches the final cut. Built to sell to real estate agents.
+
+<p>
+  <a href="https://www.charlieautomates.com/charlie-os-vs/"><img src="https://img.shields.io/badge/Work_with_Charlie-Charlie_OS-7c3aed?style=for-the-badge&logo=anthropic&logoColor=white" alt="Work with Charlie"></a>
+  <a href="https://www.npmjs.com/package/re-walkthrough-pro"><img src="https://img.shields.io/npm/v/re-walkthrough-pro?color=blue&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/re-walkthrough-pro"><img src="https://img.shields.io/npm/dt/re-walkthrough-pro?color=blue&label=downloads" alt="npm downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/re-walkthrough-pro?color=green" alt="MIT license"></a>
+  <a href="https://github.com/charlesdove977/re-walkthrough-pro/stargazers"><img src="https://img.shields.io/github/stars/charlesdove977/re-walkthrough-pro?style=flat" alt="stars"></a>
+</p>
+
+RE Walkthrough Pro ships the **`re-walkthrough-pro`** skill: a single command that takes a Zillow listing (or finds you some), pulls every photo, animates each room into a short cinematic camera-move clip, and stitches them into one finished walkthrough video you can hand an agent.
+
+A finished tour that looks like a $1,000–3,000 production, made from listing photos in minutes, for sub-cents of scraping plus a handful of Higgsfield credits.
+
+> **Honest framing:** This produces a *cinematic walkthrough* (per-room camera-move clips stitched together), **not** a true 3D / Matterport reconstruction. It looks premium, and it's impossible without an AI video engine — but don't promise a walkable dollhouse.
+
+---
+
+## Why
+
+Agents pay for media. The bottleneck is production time. RE Walkthrough Pro removes it: one command, listing in → sellable walkthrough out. Drop it into a real estate marketing service as a video line item, or batch tours across a whole farm area and pitch the listing agents.
+
+The architecture is the unlock. Higgsfield video models work clip-by-clip (~5s image-to-video), so a whole-house walkthrough **must** be per-room clips stitched on your side. This skill does exactly that, with a camera move matched to each room type so the stitched result reads like walking through the home.
+
+---
+
+## Install
+
+### Option 1 — `npx` (recommended)
+
+```bash
+npx re-walkthrough-pro install
+```
+
+Installs the skill to `~/.claude/skills/re-walkthrough-pro/`. Refresh after a package upgrade:
+
+```bash
+npm view re-walkthrough-pro version       # check latest
+npx re-walkthrough-pro@latest update      # refresh in place
+```
+
+### Option 2 — Global install
+
+```bash
+npm install -g re-walkthrough-pro
+re-walkthrough-pro install
+```
+
+### Option 3 — Directly from GitHub
+
+```bash
+npx github:charlesdove977/re-walkthrough-pro install
+```
+
+### Project-scoped install (per repo)
+
+```bash
+cd ~/path/to/project
+npx re-walkthrough-pro install --project
+```
+
+### Uninstall / where
+
+```bash
+npx re-walkthrough-pro uninstall
+npx re-walkthrough-pro where            # ~/.claude/skills/re-walkthrough-pro
+```
+
+Restart Claude Code after installing, then run `/re-walkthrough-pro`.
+
+---
+
+## What you need
+
+Two MCP servers connected in Claude Code, plus ffmpeg:
+
+- **[Higgsfield MCP](https://higgsfield.ai/mcp?utm_source=ig&utm_medium=social&utm_category=gr&utm_campaign=Higgsfield_MCP_-_IG&utm_creator=charlieautomates&utm_content_type=rl&utm_post=dBaWAw&invite_code=higgsfield-mcp-ig-charlieautomates-dBaWAw)** — required. Animates each room (Seedance 2.0 / Kling 3.0 image-to-video) and reframes for social. Every image + video model in one credit pool. *(My affiliate link.)*
+- **[Apify account](https://www.apify.com?fpr=charles)** — required for the listing scrape. The Zillow detail scraper pulls photos + address + specs in one call. *(My referral link.)* Grab the [Apify MCP server](https://github.com/apify/actors-mcp-server) (`@apify/actors-mcp-server`) and your token at [console.apify.com](https://console.apify.com/settings/integrations).
+- **ffmpeg** — required for stitching (`brew install ffmpeg`).
+
+---
+
+## How it works
+
+```
+1. RESOLVE   Zillow link → Apify detail scraper (photos + address + specs)
+             "find 5 in NJ" → search actor → detail scraper (chained dataset)
+2. PERSIST   write PROPERTY.md, download all photos to source-images/
+3. CURATE    vision pass: best photo per room, drop floorplans/dupes, tag room type
+4. ANIMATE   per room → Higgsfield image-to-video with a room-matched camera move
+5. STITCH    ffmpeg concat in walkthrough order → 16:9 master (+ optional 9:16)
+6. DELIVER   final video + per-room scenes + PROPERTY.md, in one folder
+```
+
+### Two ways in
+
+- **Single property:** paste a Zillow listing URL (or an address).
+- **Discovery:** "find 5 single-family homes in Montclair NJ" → it searches, shows you the listings, you pick.
+
+### Room → camera move
+
+Each room type gets a cinematic move (drone approach for the exterior, steadicam walkthrough for halls, orbit for great rooms, window-approach reveals for views, rising reveal for the backyard). The moves are model-agnostic — they apply to whatever Higgsfield video model you pick.
+
+---
+
+## Output
+
+```
+listing-walkthroughs/<property-slug>/
+├── PROPERTY.md          address · Zillow link · price · beds/baths/sqft · agent · shot list
+├── source-images/       every photo pulled from Zillow
+├── scenes/              per-room cinematic clips (room-01-exterior.mp4, room-02-living.mp4 …)
+└── final/               walkthrough-16x9.mp4 (+ walkthrough-9x16.mp4 if requested)
+```
+
+---
+
+## What gets installed
+
+```
+~/.claude/skills/re-walkthrough-pro/
+├── SKILL.md
+├── tasks/
+│   └── build-walkthrough.md          ← interview + 7-step pipeline
+├── frameworks/
+│   ├── apify-zillow-actors.md         ← the Zillow actor stack + how to call it
+│   ├── higgsfield-camera-moves.md     ← room→camera-move mapping (self-sufficient)
+│   └── stitch-pipeline.md             ← ffmpeg normalize/concat + 9:16 reframe
+├── templates/
+│   └── property-md.md
+└── checklists/
+    └── walkthrough-quality.md
+```
+
+Walkthroughs are written to your *project* (`listing-walkthroughs/`), never into the skill folder.
+
+---
+
+## Optional: richer prompt craft
+
+The built-in camera-move mapping is self-sufficient. If you also have the **`seedance-real-estate`** and **`seedance-cinematic`** skills installed (both ship inside [UGC Factory](https://www.npmjs.com/package/ugc-factory)), the skill invokes them for richer per-room motion prompts and a film-look color grade. Purely additive — nothing breaks without them.
+
+---
+
+## FAQ
+
+**Is this true 3D?**
+No. It's per-room cinematic camera-move clips stitched into a tour. Premium-looking, honest to describe as a "cinematic walkthrough," not a Matterport dollhouse.
+
+**Does it touch my repo when I install?**
+No. Default install writes to `~/.claude/skills/re-walkthrough-pro/`. Only `--project` writes into the current directory.
+
+**Does Zillow block scraping?**
+Zillow blocks naive `fetch`/headless, which is exactly why the skill routes images through the Apify actor — the reliable source for both the link and discovery paths.
+
+**What does a run cost?**
+The Apify scrape is sub-cent per property. The real cost is Higgsfield credits, scaled by room count — which is why the skill auto-curates to ~6–10 hero rooms by default.
+
+---
+
+## Related projects
+
+- **[Charlie OS](https://www.charlieautomates.com/charlie-os/)** — one-click Claude Code setup bundling BASE, CARL, PAUL, SEED, Skillsmith, and dozens of curated skills.
+- **[UGC Factory](https://www.npmjs.com/package/ugc-factory)** — AI UGC ad studio; bundles the 15 Seedance genre skills (including the two this skill optionally uses).
+- **[Advertising Ops](https://github.com/charlesdove977/advertising-ops)** — CMO-in-a-box media buyer for Claude Code.
+- **[Work with Charlie](https://www.charlieautomates.com/charlie-os-vs/)** — done-for-you installs, custom skill builds, 1:1 Claude Code engineering.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Built by [Charles J Dove](https://www.charlieautomates.com).

package/bin/re-walkthrough-pro.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * re-walkthrough-pro CLI
+ *
+ * Installs the re-walkthrough-pro Claude Code skill into either the
+ * user-global directory (~/.claude/skills/re-walkthrough-pro/) or the
+ * current project's .claude/skills/re-walkthrough-pro/ directory.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 're-walkthrough-pro';
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILL_SRC = path.join(PACKAGE_ROOT, 'skill');
+const PKG = require(path.join(PACKAGE_ROOT, 'package.json'));
+
+function userClaudeDir() {
+  return path.join(os.homedir(), '.claude');
+}
+
+function projectClaudeDir() {
+  return path.join(process.cwd(), '.claude');
+}
+
+function resolveSkillTarget(opts) {
+  const base = opts.project ? projectClaudeDir() : userClaudeDir();
+  return path.join(base, 'skills', SKILL_NAME);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(s, d);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function rmrf(target) {
+  if (!fs.existsSync(target)) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+function install(opts) {
+  const target = resolveSkillTarget(opts);
+  const exists = fs.existsSync(target);
+
+  if (exists && !opts.force) {
+    console.error(
+      `[re-walkthrough-pro] Skill already installed at:\n  ${target}\n\n` +
+        `Run with --update to overwrite, or --uninstall to remove first.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (exists && opts.force) {
+    rmrf(target);
+  }
+
+  copyDir(SKILL_SRC, target);
+
+  console.log(`[re-walkthrough-pro] Skill installed:`);
+  console.log(`  ${target}`);
+  console.log('');
+  console.log(`Invoke from Claude Code with:  /${SKILL_NAME}`);
+  console.log(`Then paste a Zillow listing link, or say "find 5 listings in <place>".`);
+  console.log('');
+  console.log(`Requires: Higgsfield MCP + Apify MCP connected in Claude Code, and ffmpeg installed.`);
+}
+
+function uninstall(opts) {
+  const target = resolveSkillTarget(opts);
+  if (fs.existsSync(target)) {
+    rmrf(target);
+    console.log(`[re-walkthrough-pro] Removed skill: ${target}`);
+  } else {
+    console.log(`[re-walkthrough-pro] Nothing to uninstall at ${target}`);
+  }
+}
+
+function where(opts) {
+  console.log(resolveSkillTarget(opts));
+}
+
+function help() {
+  console.log(`re-walkthrough-pro v${PKG.version}
+
+Install the re-walkthrough-pro Claude Code skill.
+
+Usage:
+  npx re-walkthrough-pro <command> [flags]
+
+Commands:
+  install         Install skill to ~/.claude/skills/${SKILL_NAME}/
+  update          Same as install, but overwrite if already present
+  uninstall       Remove skill from the target directory
+  where           Print the target install path and exit
+  --help, -h      Show this message
+  --version, -v   Show version
+
+Flags:
+  --project       Install into the current project's ./.claude/ instead of ~/.claude/
+
+Examples:
+  npx re-walkthrough-pro install
+  npx re-walkthrough-pro install --project
+  npx re-walkthrough-pro update
+  npx re-walkthrough-pro uninstall
+
+Skill name once installed: /${SKILL_NAME}
+Repo:                       https://github.com/charlesdove977/re-walkthrough-pro
+`);
+}
+
+function parseArgs(argv) {
+  const opts = { project: false, force: false };
+  let cmd = null;
+  for (const arg of argv) {
+    if (arg === '--project') opts.project = true;
+    else if (arg === '--update' || arg === '--force' || arg === '-f') opts.force = true;
+    else if (arg === '--help' || arg === '-h') cmd = '__help';
+    else if (arg === '--version' || arg === '-v') cmd = '__version';
+    else if (!arg.startsWith('-') && cmd === null) cmd = arg;
+  }
+  return { cmd, opts };
+}
+
+function main() {
+  const { cmd, opts } = parseArgs(process.argv.slice(2));
+
+  switch (cmd) {
+    case 'install':
+      install(opts);
+      return;
+    case 'update':
+      opts.force = true;
+      install(opts);
+      return;
+    case 'uninstall':
+      uninstall(opts);
+      return;
+    case 'where':
+      where(opts);
+      return;
+    case '__version':
+      console.log(PKG.version);
+      return;
+    case '__help':
+    case null:
+    default:
+      help();
+      return;
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "re-walkthrough-pro",
+  "version": "0.1.0",
+  "description": "Claude Code skill that turns a Zillow listing into a cinematic, room-by-room property walkthrough video — Apify scrapes the photos, Higgsfield animates each room, ffmpeg stitches the final cut. Built to sell to real estate agents.",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skill",
+    "real-estate",
+    "zillow",
+    "property-video",
+    "listing-video",
+    "walkthrough",
+    "higgsfield",
+    "seedance",
+    "apify",
+    "ffmpeg",
+    "ai-video",
+    "real-estate-marketing"
+  ],
+  "homepage": "https://github.com/charlesdove977/re-walkthrough-pro#readme",
+  "bugs": {
+    "url": "https://github.com/charlesdove977/re-walkthrough-pro/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/charlesdove977/re-walkthrough-pro.git"
+  },
+  "license": "MIT",
+  "author": "Charles J Dove",
+  "type": "commonjs",
+  "bin": {
+    "re-walkthrough-pro": "bin/re-walkthrough-pro.js"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "scripts": {
+    "test": "node bin/re-walkthrough-pro.js --version && echo 'OK'"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: re-walkthrough-pro
+type: standalone
+version: 0.1.0
+category: content
+description: Turn a Zillow listing into a cinematic room-by-room walkthrough video (Apify scrape → Higgsfield image-to-video → ffmpeg stitch) to sell to real estate agents
+allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
+---
+
+<activation>
+## What
+Turns a Zillow listing into a cinematic, room-by-room property walkthrough video. Pulls the listing and its photos via an Apify Zillow actor, animates each room into a short cinematic clip with the Higgsfield MCP (image-to-video), then stitches the clips into one finished walkthrough you can sell to listing agents.
+
+## When to Use
+- You have a Zillow listing link (or want to discover listings) and want a sellable cinematic walkthrough
+- Producing a batch of property tours to pitch to local agents
+- Adding a video-walkthrough line item to a real estate marketing service
+
+## Not For
+- True 3D / Matterport reconstruction — Higgsfield does cinematic camera moves on photos, not spatial reconstruction
+- Other portals (Realtor.com, Redfin) — Zillow only in v1
+- Agent outreach / sending the video — this skill produces the asset, not the pitch
+- Music or voiceover — v1 ships a silent master; add sound in your editor
+</activation>
+
+<persona>
+## Role
+Real estate content producer — turns raw listing photos into premium cinematic tours, fast and repeatably.
+
+## Style
+- Interview-first: asks the input + creative questions up front, then runs the pipeline without hand-holding
+- Honest about the tech: calls it a "cinematic walkthrough," never promises true 3D
+- Cost-aware: curates rooms to control Higgsfield credit spend, says what it's skipping
+- Reports concrete paths — every property lands in a predictable folder
+
+## Expertise
+- Apify Zillow actor stack (detail scraper + search chaining)
+- Higgsfield image-to-video camera-move direction per room type
+- ffmpeg stitching and aspect-ratio reframing
+</persona>
+
+<commands>
+| Command | Description | Routes To |
+|---------|-------------|-----------|
+| `/re-walkthrough-pro` | Full guided build (link or discovery → walkthrough) | tasks/build-walkthrough.md |
+</commands>
+
+<routing>
+## Load on Command
+@tasks/build-walkthrough.md (when the skill runs — the full interview + pipeline)
+
+## Load on Demand
+@frameworks/apify-zillow-actors.md (when resolving a listing or discovering listings)
+@frameworks/higgsfield-camera-moves.md (when animating rooms)
+@frameworks/stitch-pipeline.md (when stitching scenes + reframing)
+@templates/property-md.md (when writing each property's PROPERTY.md)
+@checklists/walkthrough-quality.md (before declaring a walkthrough done)
+
+## Optional Sibling Skills (prompt-craft enrichment, model-agnostic)
+- `seedance-real-estate` — Camera Movement Library + Room-by-Room Strategy + Lighting Guide; richer per-room motion prompts
+- `seedance-cinematic` — film-look layer (color grade, atmosphere) when style = cinematic
+- OPTIONAL: if installed, the skill invokes them for richer prompt wording. If not, the built-in camera-move mapping in `frameworks/higgsfield-camera-moves.md` is self-sufficient. Both ship inside UGC Factory (npm: `ugc-factory`). These supply prompt craft for ANY Higgsfield video model (Seedance 2.0, Kling 3.0, future).
+</routing>
+
+<greeting>
+RE Walkthrough Pro loaded.
+
+Give me a property and I'll produce a cinematic room-by-room walkthrough you can sell to an agent.
+
+- **Have a link?** Paste the Zillow listing URL.
+- **Want options?** Tell me a place + count (e.g. "5 good listings in New Jersey") and I'll find some.
+
+What are we working with?
+</greeting>

package/skill/checklists/walkthrough-quality.md

@@ -0,0 +1,34 @@
+# Walkthrough Quality Checklist
+
+Validates a finished property walkthrough before delivering it to an agent.
+
+## Assets & Structure
+- [ ] `listing-walkthroughs/{property-slug}/` contains PROPERTY.md, source-images/, scenes/, final/
+- [ ] PROPERTY.md has address, Zillow link, specs, and all four build choices recorded
+- [ ] source-images/ has at least one photo per animated room
+- [ ] scenes/ clip count equals the PROPERTY.md shot-list row count
+
+## Video Output
+- [ ] final/ contains a non-zero master file (walkthrough-16x9.mp4 or chosen ratio)
+- [ ] Master duration ≈ sum of scene durations (no clip silently dropped)
+- [ ] Scenes play in walkthrough order: exterior → entry → living → kitchen → beds → baths → outdoor
+- [ ] If 9:16 was requested, final/walkthrough-9x16.mp4 exists and is correctly reframed (subject not cropped out)
+
+## Visual Quality
+- [ ] No clip has obvious melting/warping of furniture, doorways, or windows
+- [ ] Each clip uses one slow camera move (no fast or compound moves)
+- [ ] Exterior opens the tour; an outdoor/backyard shot closes it when available
+- [ ] No floorplans, maps, or watermark-heavy photos animated as rooms
+
+## Truth-in-Claims
+- [ ] Asset is described as a "cinematic walkthrough," not "3D" or "Matterport"
+- [ ] Master is silent (v1) — no accidental audio baked in
+
+## Scoring
+
+| Score | Rating | Action |
+|-------|--------|--------|
+| 100% | Ship it | Deliverable to the agent |
+| 80-99% | Fix and ship | Regenerate the offending room(s), then go |
+| 50-79% | Rework | Several bad clips or wrong order — rebuild scenes |
+| Below 50% | Restart | Bad source set or wrong listing — re-scrape |

package/skill/frameworks/apify-zillow-actors.md

@@ -0,0 +1,80 @@
+<apify_zillow_actors>
+
+## Purpose
+
+The Apify actor stack for pulling Zillow listings + photos, and how to call it via the Apify MCP. Researched and validated 2026-06-27. Zillow hard-blocks naive `fetch`/headless scraping, so an actor is the reliable source of both the listing metadata and the photos — Claude cannot "just grab" the images from a URL.
+
+## The Stack
+
+| Role | Actor (`username/name`) | Use it for |
+|------|-------------------------|------------|
+| **Primary — detail + photos** | `maxcopell/zillow-detail-scraper` | One property → photos + address + price + beds/baths/sqft + year + room types + agent, in ONE call. This is the default for both input paths. |
+| **Discovery — search** | `maxcopell/zillow-scraper` | "Find listings" from a Zillow search URL. Returns listing URLs + a dataset. |
+| **Discovery — by ZIP** | `maxcopell/zillow-zip-search` | "Find listings in 07042" — search by ZIP code with filters. |
+| **Fallback — images only** | `burbn/zillow-property-images-scraper` | If the detail scraper's photo set is thin; hi-res images to 1536px from `propertyUrls`. |
+
+**Why this stack:** the maxcopell suite is built to chain — a search actor writes a dataset, and the detail scraper reads it via its `searchResultsDatasetId` input. So discovery and single-property paths share one downstream actor (the detail scraper), which is the one that returns photos.
+
+## How to Call (Apify MCP)
+
+Use the Apify MCP tools (load via ToolSearch if deferred: `mcp__apify__fetch-actor-details`, `mcp__apify__call-actor`, `mcp__apify__get-dataset-items`).
+
+1. **Inspect input** (only if unsure of fields): `fetch-actor-details` with `{ inputSchema: true }`.
+2. **Run** the actor: `call-actor` with the actor `fullName` + input JSON. For a single property, prefer `waitSecs > 0` so the run completes and returns results inline.
+3. **Read output**: results land in the run's dataset — read them (the call result includes the dataset, or use `get-dataset-items` with the returned dataset id).
+
+### Detail scraper input — by URL (most common)
+
+```json
+{
+  "startUrls": [
+    { "url": "https://www.zillow.com/homedetails/17-Zelma-Dr-Greenville-SC-29617/11026031_zpid/" }
+  ],
+  "propertyStatus": "FOR_SALE"
+}
+```
+
+### Detail scraper input — by address
+
+```json
+{
+  "addresses": ["18 Zelma Dr, Greenville, SC 29617"],
+  "propertyStatus": "FOR_SALE"
+}
+```
+
+### Chaining discovery → detail
+
+```json
+// after running maxcopell/zillow-zip-search and getting its dataset id:
+{ "searchResultsDatasetId": "<dataset-id-from-search-run>" }
+```
+
+## What the Detail Scraper Returns (validated)
+
+Per its README, each result includes: price + listing status, full address + coordinates, home type, year built, lot size, living area, room counts and **room types**, parking/garage, HOA/fees, interior/exterior features, **image URLs and rich media links**, agent/broker contact + license, tour availability, MLS/attribution, parcel/tax ids, tax + price history, nearby/comparable listings, schools.
+
+The fields this skill needs: `address`, `price`, `beds`/`baths`/`sqft` (living area), `yearBuilt`, agent name/contact, and the **image URL list** (feeds `source-images/` and the per-room animation).
+
+## propertyStatus matters
+
+Zillow serves for-sale, for-rent, and sold via different methods, so the detail scraper needs `propertyStatus` to match the listing. If it's wrong, the actor self-corrects but spends extra requests. Defaults: active listing → `FOR_SALE`; sold comps → `RECENTLY_SOLD`; rentals → `FOR_RENT`.
+
+## Cost
+
+All PAY_PER_EVENT, sub-cent per property on the free tier (detail scraper ~$0.0036/result, search ~$0.0023/result; cheaper at higher Apify tiers). Scraping cost is negligible next to Higgsfield credits — the room count (curation) is the real cost lever, not the scrape.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Trying to fetch Zillow photos with curl/headless directly | Zillow blocks it; you get nothing or a CAPTCHA | Always route images through the actor |
+| Running the images-only actor AND the detail scraper for one property | Detail scraper already returns photos — double spend | Use detail scraper alone; images actor only as a fallback |
+| Omitting `propertyStatus` on a sold/rental listing | Extra requests, slower, possible wrong record | Pass the correct status |
+| Re-scraping on every run | Wastes events; photos already in source-images/ | Reuse the saved source-images/ when regenerating clips |
+
+## Source
+
+Apify Store, Real Estate category. Actor IDs current as of 2026-06-27; re-verify with `search-actors "Zillow"` if a run 404s or an actor is deprecated.
+
+</apify_zillow_actors>

package/skill/frameworks/higgsfield-camera-moves.md

@@ -0,0 +1,91 @@
+<higgsfield_camera_moves>
+
+## Purpose
+
+How to drive the Higgsfield MCP to turn a single still room photo into a cinematic clip that reads as "walking through" the house — using the proven Seedance prompt craft from the sibling skills `seedance-real-estate` (15-real-estate) and `seedance-cinematic` (01-cinematic) instead of hand-rolled prompts. A walkthrough is NOT one generation; it is one short image-to-video clip per room, each with a room-appropriate camera move, stitched later.
+
+## The Hard Constraint (read first)
+
+Higgsfield `generate_video` is **image-to-video**: it animates a camera/scene move on one still for a short clip (~5s). It does NOT reconstruct 3D space or walk a continuous path through a house. Therefore:
+
+- Whole-house walkthrough = N per-room clips, stitched on our side (see `stitch-pipeline.md`).
+- Never promise true 3D / Matterport. Sell it as a "cinematic walkthrough."
+
+## Image-to-Video Adaptation (important)
+
+`seedance-real-estate` and `seedance-cinematic` mostly author **text-to-video** prompts — they describe the entire scene. We feed a **real listing photo**, so the photo already carries the scene. Borrow only these layers from those skills, applied as a motion prompt ON the photo:
+
+1. The **camera move** (from the RE Camera Movement Library).
+2. The **lighting / time-of-day mood** (RE Lighting Guide) — only as a light grade, do not re-describe furniture/layout.
+3. For cinematic style, the **film-look layer** from `seedance-cinematic` (color grade, atmosphere, depth).
+
+Do NOT re-describe the room's contents in the prompt — that fights the input image and drifts content. Prompt the camera + light, trust the photo.
+
+## How to Author Each Room's Prompt
+
+For each room photo, build the motion prompt by consulting the sibling skills:
+
+1. Pick the room's camera move from the mapping below (named moves from `seedance-real-estate` → Camera Movement Library).
+2. Invoke the **`seedance-real-estate`** skill for that move's wording + the room's entry in Room-by-Room Showcase Strategy + a lighting cue from the Lighting & Time-of-Day Guide.
+3. If build style = **cinematic**, also invoke **`seedance-cinematic`** and layer its color-grade / atmosphere language.
+4. Compress the move to the ~5s clip length; keep ONE move per clip.
+
+## Room → Camera Move Mapping (RE Camera Movement Library)
+
+| Room / shot | Named move (seedance-real-estate) | Note for image-to-video |
+|-------------|-----------------------------------|--------------------------|
+| Exterior / establishing | DRONE AERIAL APPROACH (or GIMBAL GLIDE along facade) | slow approach toward entry; compress to ~5s |
+| Entry / foyer | DOORWAY THRESHOLD REVEAL → STEADICAM WALKTHROUGH | "walking in" feel |
+| Hallway | STEADICAM WALKTHROUGH | human walking pace, smooth |
+| Living / great room | ROTATING/ORBIT or GIMBAL SMOOTH GLIDE | reveal space + depth |
+| Kitchen | GIMBAL SMOOTH GLIDE (counter flow) or ORBIT (island) | highlight finishes |
+| Dining | GIMBAL SMOOTH GLIDE (table approach) | warm, steady |
+| Primary bedroom | STEADICAM / gentle GIMBAL GLIDE | calm, spacious |
+| Primary bath / spa | DOORWAY THRESHOLD REVEAL → short push-in | bright, clean |
+| Secondary bedroom | GIMBAL SMOOTH GLIDE | brief beat |
+| Guest bathroom | REVEAL AROUND CORNER / short push-in | quick, don't linger |
+| Home office / library | PULLBACK OR PUSH-IN REVEAL | detail → context |
+| Specialty (gym, cinema, wine) | PULLBACK/PUSH-IN or ORBIT | feature the wow |
+| Window / view feature | WINDOW APPROACH & VIEW REVEAL | the emotional beat |
+| Soaring ceiling / 2-story foyer | CEILING-TO-FLOOR VERTICAL TILT | reveal height |
+| Outdoor / backyard / pool | DRONE AERIAL APPROACH or LATERAL CRANE | rising reveal closer |
+| Detail (marble, fixtures, joinery) | PULLBACK/PUSH-IN REVEAL + SUBTLE FOCUS SHIFT | craftsmanship |
+
+## Prompting Rules
+
+- **One move per clip.** Compound moves warp geometry. Single and slow.
+- **Slow beats fast.** Real estate reads premium when calm; fast moves expose AI artifacts (melting furniture, bent doorways).
+- **Prompt the camera + light, not the scene.** The photo carries content.
+- **Engine is independent of the prompt craft.** The camera-move + lighting + cinematic-grade layers are model-agnostic — they apply to whatever Higgsfield video model you pick (Seedance 2.0 default, Kling 3.0, or a future model). Optionally `models_explore(action:'recommend')` per shot.
+- **Aspect ratio = master ratio.** Generate at 16:9 for the agent master (or 9:16 if that's the only output). Reframe later; never generate twice.
+
+## Generation + Polling
+
+1. `generate_video` (image-to-video) per room photo with its authored motion prompt → job id.
+2. Dispatch all rooms, then poll `job_status` per id (don't block room N on N-1).
+3. Download each clip to `scenes/room-NN-{type}.mp4`, NN = walkthrough position.
+
+## Handling Bad Outputs
+
+| Symptom | Fix |
+|---------|-----|
+| Furniture melts / warps | Regenerate with a gentler, shorter move (orbit → short push-in) |
+| Doorway / window bends | Reduce move distance; prefer lateral glide over push-in for that room |
+| Clip too short to feel cinematic | Accept it — stitched short clips still read as a tour; never force one long generation |
+| One room keeps failing | Note it, skip after one retry; never block the property on one room |
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Re-describing the room in the prompt | Fights the input photo, drifts content | Prompt only the camera move + light |
+| Copying the seedance skills' full text-to-video scene prompts | They assume no input image; bloats + drifts | Borrow camera-move + lighting layers only |
+| Generating the whole house in one call | Higgsfield can't; incoherent output | One clip per room, stitch later |
+| Fast / compound camera moves | Exposes AI artifacts, looks cheap | Single slow move per clip |
+| Duplicating the RE Camera Library into this skill | Two sources drift on every Seedance update | Invoke `seedance-real-estate` by name |
+
+## Source
+
+Camera-move grammar: `seedance-real-estate` (15-real-estate) Camera Movement Library + Room-by-Room Showcase Strategy + Lighting & Time-of-Day Guide. Film-look layer: `seedance-cinematic` (01-cinematic). Higgsfield MCP: `generate_video`, `models_explore`, `job_status`, `reframe`.
+
+</higgsfield_camera_moves>

package/skill/frameworks/stitch-pipeline.md

@@ -0,0 +1,78 @@
+<stitch_pipeline>
+
+## Purpose
+
+How to assemble the per-room Higgsfield clips into one finished walkthrough, and how to produce the optional 9:16 social cut. Stitching happens on our side with ffmpeg — the skill owns the edit, not Claude eyeballing it and not Higgsfield.
+
+## Walkthrough Order
+
+Concatenate in natural tour order, NOT the order Zillow returned photos:
+
+```
+exterior → entry/foyer → living → dining → kitchen → bedrooms → bathrooms → outdoor/backyard
+```
+
+The `scenes/` files are already named `room-NN-{type}.mp4` with NN encoding this order, so a sorted concat is correct.
+
+## Normalize Before Concat
+
+Higgsfield clips can differ in fps, resolution, or codec. Concatenating mismatched clips causes stutter or failure. Normalize each clip to the same fps + resolution + codec first, then concat.
+
+```bash
+# 1. Normalize every scene to 1080p, 30fps, h264 (master = 16:9)
+for f in scenes/room-*.mp4; do
+  ffmpeg -y -i "$f" -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,fps=30" \
+    -c:v libx264 -pix_fmt yuv420p -an "norm-$(basename "$f")"
+done
+
+# 2. Concat in sorted (walkthrough) order
+ls norm-room-*.mp4 | sort | sed "s/^/file '/;s/$/'/" > concat.txt
+ffmpeg -y -f concat -safe 0 -i concat.txt -c:v libx264 -pix_fmt yuv420p -an final/walkthrough-16x9.mp4
+```
+
+Silent master by design (v1): `-an` drops audio. Add music/VO in your editor later.
+
+## Optional Transitions
+
+Hard cuts on the beat are clean and safe (default). If you want crossfades between rooms, use `xfade` — but keep them short (0.3–0.5s) so the tour stays brisk. Hard cuts are the recommended default; only add crossfades if the user asks.
+
+## 9:16 Social Cut
+
+If the user requested a 9:16 cut, produce it FROM the finished clips, not by regenerating:
+
+- **Preferred:** Higgsfield `reframe` on the master (content-aware — keeps the subject framed).
+- **Fallback (ffmpeg center-crop + scale):**
+
+```bash
+ffmpeg -y -i final/walkthrough-16x9.mp4 \
+  -vf "scale=-1:1920,crop=1080:1920" -c:v libx264 -pix_fmt yuv420p -an final/walkthrough-9x16.mp4
+```
+
+Center-crop loses edges; `reframe` is better for rooms where the focal point isn't centered.
+
+## Verify Output
+
+After producing each final file:
+- File exists and is non-zero.
+- Duration ≈ sum of scene durations (catches a silently dropped clip).
+- Plays start-to-finish (a quick `ffprobe` for duration + stream count is enough; no need to watch).
+
+```bash
+ffprobe -v error -show_entries format=duration -of default=nk=1:nw=1 final/walkthrough-16x9.mp4
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Concat without normalizing | Stutter, A/V desync, or ffmpeg errors on mismatched clips | Normalize fps/res/codec first |
+| Regenerating rooms at 9:16 for the social cut | Double Higgsfield spend | Reframe the finished master |
+| Long fancy transitions | Drags the tour, looks like a screensaver | Hard cuts (or ≤0.5s crossfade) |
+| Trusting the concat blindly | A dropped clip yields a short video nobody notices | Check duration ≈ sum of scenes |
+| Baking in music in v1 | Locks the edit, licensing headaches | Ship silent master; sound added downstream |
+
+## Source
+
+ffmpeg (concat demuxer, scale/pad/crop, xfade) + Higgsfield `reframe`. Commands are reference patterns — adjust resolution/fps to the chosen master ratio.
+
+</stitch_pipeline>

package/skill/tasks/build-walkthrough.md

@@ -0,0 +1,168 @@
+<purpose>
+Take a Zillow listing (a pasted link, an address, or one discovered via search) and produce a finished cinematic room-by-room walkthrough video. Scrapes the listing + photos via Apify, animates curated rooms with the Higgsfield MCP, stitches the clips with ffmpeg, and writes everything into a predictable per-property folder.
+</purpose>
+
+<user-story>
+As a creator selling media to real estate agents, I want one command that turns a listing into a cinematic walkthrough, so that I can produce a sellable tour in minutes instead of manually scraping, prompting, and editing.
+</user-story>
+
+<when-to-use>
+- User pastes a Zillow listing URL or address and wants a walkthrough
+- User wants to discover listings ("find 5 in NJ") then build from one
+- Entry point routes here via /listing-walkthrough
+</when-to-use>
+
+<references>
+@frameworks/apify-zillow-actors.md (during resolve_listing — actor IDs, inputs, chaining)
+@frameworks/higgsfield-camera-moves.md (during animate_rooms — room→camera-move mapping + prompts)
+@frameworks/stitch-pipeline.md (during stitch_and_reframe — ffmpeg concat + reframe)
+@templates/property-md.md (during persist_property — PROPERTY.md shape)
+@checklists/walkthrough-quality.md (during review_and_deliver — pre-delivery QA)
+</references>
+
+<steps>
+
+<step name="choose_input_mode" priority="first">
+Determine what we're building from. Ask the user (if not already clear from how they invoked the skill):
+
+1. **Do you have a specific listing, or want me to find some?**
+   - A Zillow listing URL → single-property path
+   - An address → single-property path (use the actor's `addresses` input)
+   - "Find me listings" → discovery path (ask: location + how many, e.g. "5 single-family homes in Montclair NJ")
+
+**Wait for response.**
+
+<if condition="discovery path">
+Load @frameworks/apify-zillow-actors.md. Run the search/zip actor for the requested location + count. Present the found listings as a table (address · price · beds/baths · sqft · photo count). Ask the user to pick one (or more, processed one at a time).
+
+**Wait for selection.**
+</if>
+
+Confirm the final property/properties and the listing status (FOR_SALE / RECENTLY_SOLD / FOR_RENT — needed by the detail scraper; default FOR_SALE for active listings).
+</step>
+
+<step name="collect_creative_choices">
+Ask the creative questions (offer the recommended default for each — let the user accept all defaults with one "go"):
+
+1. **Style** — Cinematic (camera-move per room) [default] or Basic (simple slow pan / Ken-Burns).
+2. **Rooms** — Auto-curate ~6–10 hero shots [default] or animate all photos.
+3. **Output ratio** — 16:9 master for agent delivery [default], 9:16 social cut, or both.
+4. **Engine** — Seedance 2.0 [default] or Kling 3.0.
+
+**Wait for response (or a blanket "use defaults").**
+
+State the rough cost before running: detail scrape (~$0.004) + N Higgsfield clips. Confirm to proceed.
+
+**Wait for go.**
+</step>
+
+<step name="resolve_listing">
+Load @frameworks/apify-zillow-actors.md.
+
+Resolve the property to structured data + photo URLs via the Apify MCP:
+- URL path → call `maxcopell/zillow-detail-scraper` with `startUrls`.
+- Address path → same actor with `addresses`.
+- Discovery path → chain the search actor's dataset into the detail scraper via `searchResultsDatasetId`.
+
+Use the Apify MCP `call-actor` tool (fetch the actor's input schema first if unsure). Retrieve the run's dataset items.
+
+Verify you got: full address, price, beds/baths/sqft, year built, agent info, and a non-empty list of image URLs. If image URLs are missing or sparse, fall back to `burbn/zillow-property-images-scraper` with `propertyUrls` for the photos.
+
+Derive a `{property-slug}` from the address (kebab-case, e.g. `17-zelma-dr-greenville-sc-29617`).
+</step>
+
+<step name="persist_property">
+Load @templates/property-md.md.
+
+Create the property folder tree under the output root `listing-walkthroughs/{property-slug}/`:
+- `source-images/` — download every photo URL here (use Bash `curl`/`wget`; name `NN-original.jpg` in returned order).
+- `scenes/` — created now, filled in animate_rooms.
+- `final/` — created now, filled in stitch_and_reframe.
+
+Write `listing-walkthroughs/{property-slug}/PROPERTY.md` from the template: address, Zillow link, price, beds/baths/sqft, year, agent, full room/photo list, and the run's creative choices.
+</step>
+
+<step name="curate_rooms">
+<if condition="rooms = auto-curate">
+Do a vision pass over `source-images/`: Read the images, pick the single best photo per distinct room, drop floorplans, maps, aerial-only, watermark-heavy, and near-duplicate shots. Target the hero set: exterior, entry/foyer, living, kitchen, primary bed, primary bath, one secondary bed, and a backyard/outdoor shot when present (~6–10 total). Tag each kept photo with its room type.
+</if>
+
+<if condition="rooms = all">
+Use every non-floorplan photo, tagging each with its best-guess room type for camera-move selection.
+</if>
+
+Produce an ordered shot list: [photo file, room type, walkthrough position]. Walkthrough order = exterior → entry → living → kitchen → bedrooms → bathrooms → outdoor, regardless of Zillow's photo order.
+</step>
+
+<step name="animate_rooms">
+Load @frameworks/higgsfield-camera-moves.md.
+
+The prompt craft is **model-agnostic** (applies to whichever Higgsfield video model you chose: Seedance 2.0, Kling 3.0, or any future model). Two OPTIONAL sibling skills enrich the wording when present:
+- **`seedance-real-estate`** — Camera Movement Library, Room-by-Room Showcase Strategy, Lighting & Time-of-Day Guide.
+- **`seedance-cinematic`** — film-look layer (color grade, atmosphere, depth), used when style = cinematic.
+
+For each shot in the list, generate one clip via the Higgsfield MCP:
+1. Pick the room's camera move from the framework mapping in `higgsfield-camera-moves.md` (this mapping is self-sufficient on its own).
+2. **Author the motion prompt.** If `seedance-real-estate` is installed, invoke it for the move wording + room cue + lighting; if style = cinematic and `seedance-cinematic` is installed, layer its grade/atmosphere. If neither is installed, build the prompt directly from the framework mapping + prompting rules — it is enough. Either way: apply only the camera-move + lighting layers ON the photo — do NOT re-describe the room (image-to-video carries the scene). Compress the move to the ~5s clip length; one move per clip.
+3. (Optional) Call `models_explore` to confirm the best model for the shot; otherwise use the chosen engine.
+4. Call `generate_video` as image-to-video, passing the room photo + the authored motion prompt, at the master ratio (16:9 unless 9:16-only was selected).
+5. Capture the returned job id.
+
+After dispatching all rooms, poll `job_status` for each until rendered. Download each finished clip to `scenes/room-NN-{type}.mp4` (NN = walkthrough position, zero-padded).
+
+If a clip fails or warps badly (furniture melting, doorway distortion), regenerate that single room with a gentler move (shorter push-in) before continuing. Do not block the whole property on one bad room — note it and move on if a retry also fails.
+</step>
+
+<step name="stitch_and_reframe">
+Load @frameworks/stitch-pipeline.md.
+
+1. Concatenate `scenes/*.mp4` in walkthrough order via ffmpeg → `final/walkthrough-16x9.mp4` (or the chosen master ratio). Normalize fps/resolution per the framework before concat so clips join cleanly.
+2. <if condition="ratio includes 9:16 and master is 16:9">Produce `final/walkthrough-9x16.mp4` — prefer Higgsfield `reframe` for content-aware reframing; fall back to ffmpeg center-crop + scale per the framework.</if>
+3. Master is silent by design (v1). Do not add audio.
+
+Verify each final file exists, is non-zero, and plays start-to-finish with the expected duration (~sum of scene durations).
+</step>
+
+<step name="review_and_deliver">
+Load @checklists/walkthrough-quality.md and validate the output against it.
+
+Report to the user:
+- Final video path(s) under `listing-walkthroughs/{property-slug}/final/`
+- Scene count + any rooms that were skipped/failed
+- `PROPERTY.md` path
+- Rough Higgsfield credit + Apify cost spent
+
+Ask: "Walkthrough ready — want any room regenerated, a different ratio, or this batched across more listings?"
+
+**Wait for approval or revision requests.**
+</step>
+
+</steps>
+
+<output>
+## Artifact
+A finished cinematic walkthrough video plus a complete per-property asset folder.
+
+## Structure
+```
+listing-walkthroughs/{property-slug}/
+├── PROPERTY.md                 address · link · price · specs · agent · room list · run notes
+├── source-images/              every photo pulled from Zillow (NN-original.jpg)
+├── scenes/                     per-room Higgsfield clips (room-NN-{type}.mp4)
+└── final/                      walkthrough-16x9.mp4 (+ walkthrough-9x16.mp4 if requested)
+```
+
+## Location
+Output root: `listing-walkthroughs/` at repo root.
+</output>
+
+<acceptance-criteria>
+- [ ] Listing resolved to structured data + non-empty photo set via Apify
+- [ ] PROPERTY.md written with address, link, specs, agent, and creative choices
+- [ ] All source photos downloaded to source-images/
+- [ ] Each curated room produced one clip in scenes/, ordered by walkthrough position
+- [ ] final/ contains a playable master that runs start-to-finish in correct room order
+- [ ] If 9:16 requested, the social cut exists and is correctly reframed
+- [ ] Output passes checklists/walkthrough-quality.md
+- [ ] User confirmed the walkthrough matches intent
+</acceptance-criteria>

package/skill/templates/property-md.md

@@ -0,0 +1,92 @@
+# Property Template
+
+Template for `listing-walkthroughs/{property-slug}/PROPERTY.md` — the per-property brief that travels with the walkthrough assets.
+
+**Purpose:** Capture everything about the property (so the folder is self-describing for re-runs and for the agent pitch) plus the creative choices used for this build.
+
+---
+
+## File Template
+
+```markdown
+# {property-address}
+
+**Zillow:** {zillow-url}
+**Status:** {listing-status}
+**Slug:** {property-slug}
+**Built:** {build-date}
+
+## Property
+| Field | Value |
+|-------|-------|
+| Price | {price} |
+| Beds | {beds} |
+| Baths | {baths} |
+| Living area | {sqft} sqft |
+| Year built | {year-built} |
+| Home type | {home-type} |
+
+## Agent
+- **Name:** [Listing agent name]
+- **Contact:** [Phone / email if returned]
+- **Brokerage:** [Brokerage]
+
+## Photos
+- Source count: {source-photo-count} (in `source-images/`)
+- Curated for animation: {curated-count}
+
+## Shot List (walkthrough order)
+| # | Room | Photo | Camera move |
+|---|------|-------|-------------|
+| 01 | [exterior] | [NN-original.jpg] | [push-in] |
+| 02 | [entry] | [NN-original.jpg] | [forward dolly] |
+| ... | ... | ... | ... |
+
+## Build Choices
+- **Style:** {style}            (cinematic / basic)
+- **Rooms:** {room-mode}        (auto-curate / all)
+- **Output ratio:** {ratio}     (16:9 / 9:16 / both)
+- **Engine:** {engine}          (Seedance 2.0 / Kling 3.0)
+
+## Outputs
+- Master: `final/walkthrough-16x9.mp4`
+- Social: [final/walkthrough-9x16.mp4 if produced]
+- Scenes: {scene-count} clips in `scenes/`
+
+## Run Notes
+[Any rooms skipped/failed, regenerations, or cost notes]
+```
+
+---
+
+## Field Documentation
+
+| Field | Type | Required | Purpose | Example |
+|-------|------|----------|---------|---------|
+| `{property-address}` | variable | Yes | Full street address | `17 Zelma Dr, Greenville, SC 29617` |
+| `{zillow-url}` | variable | Yes | Source listing link | `https://www.zillow.com/homedetails/.../11026031_zpid/` |
+| `{listing-status}` | variable | Yes | FOR_SALE / RECENTLY_SOLD / FOR_RENT | `FOR_SALE` |
+| `{property-slug}` | variable | Yes | kebab-case folder name | `17-zelma-dr-greenville-sc-29617` |
+| `{build-date}` | variable | Yes | Date built (YYYY-MM-DD) | `2026-06-27` |
+| `{price}` `{beds}` `{baths}` `{sqft}` `{year-built}` `{home-type}` | variable | Yes | Core specs from the actor | `$415,000` / `3` / `2` / `1840` / `1998` / `Single Family` |
+| `{source-photo-count}` `{curated-count}` `{scene-count}` | variable | Yes | Counts from the run | `34` / `8` / `8` |
+| `{style}` `{room-mode}` `{ratio}` `{engine}` | variable | Yes | The build choices | `cinematic` / `auto-curate` / `16:9` / `Seedance 2.0` |
+| `[Listing agent name]` / `[Contact]` / `[Brokerage]` | prose | No | Agent details if the actor returned them | `Jane Doe, Keller Williams` |
+| `[Shot list rows]` | prose | Yes | One row per animated room | `01 / exterior / 03-original.jpg / push-in` |
+| `[Run Notes]` | prose | No | Skips, retries, cost | `Bath 2 skipped — only floorplan photo` |
+
+## Section Specifications
+
+### Property
+**Purpose:** The spec table the agent cares about.
+**Contains:** Price, beds, baths, sqft, year, home type — pulled straight from the detail scraper.
+**Quality check:** Every cell filled from actor data, not guessed.
+
+### Shot List
+**Purpose:** Audit trail mapping each scene clip back to its source photo + camera move.
+**Contains:** One row per animated room in walkthrough order.
+**Quality check:** Row count equals `scenes/` clip count.
+
+### Build Choices
+**Purpose:** Reproducibility — re-run the same property the same way.
+**Quality check:** All four choices recorded (style, rooms, ratio, engine).