@rubytech/create-maxy 1.0.879 → 1.0.881

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

@@ -0,0 +1,228 @@
+---
+name: property-extract
+description: Use when a live property listing URL on an estate-agent website (Muvin, or any site using the Loop CRM CDN at b-cdn.net) needs to be turned into a local property assets directory containing photos, floorplans, EPC documents, and structured metadata that the property-brochure skill can consume. Trigger phrases include "extract property from <url>", "get property details from <url>", "scrape this listing", "pull all the photos from <listing>", "stage assets for the brochure", or any request that names a live property URL and asks for the photos, floorplans, and details to be saved locally.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - WebFetch
+---
+
+# property-extract
+
+Turn one publicly-accessible property listing URL into a self-contained property assets directory that `property-brochure` can consume without re-visiting the source site.
+
+The reference output this skill targets is `/Users/neo/estate-agents/muvin/properties/henham-road-debden-green-hamperden-end-cb11-3lz-949931/` — read that directory once before generating to anchor the standard.
+
+## Outcome contract
+
+The skill is **complete** when the target directory contains exactly this structure:
+
+```
+<output-dir>/<property-slug>-<listing-id>/
+  property.json          # structured metadata
+  description.md         # human-readable description + agent + EPC + council tax
+  brochure/              # empty — reserved for property-brochure output
+  epc/                   # EPC certificate PDF/image, OR empty if rating is "TBC"
+  floorplans/            # all floorplan images, original filenames
+  images/                # all property photographs and renders, original filenames
+```
+
+Every photograph and floorplan referenced by the listing must be downloaded. The folders `brochure/` and `epc/` may legitimately be empty (the first by design, the second if no EPC has been issued); `images/` and `floorplans/` must not be empty if the listing exposes any.
+
+`<property-slug>` comes from the URL path segment (e.g. `henham-road-debden-green-hamperden-end-cb11-3lz`). `<listing-id>` is the numeric ID, also from the URL. Concatenating them keeps the folder both human-readable and unique even when the same street has multiple listings.
+
+Anything else (raw HTML dumps, `/tmp` files, intermediate URL lists) must be cleaned up before reporting completion.
+
+## Inputs
+
+Required: a property listing URL, fully-formed and publicly accessible. If only a postcode or property name is given, decline and ask for the URL — listings are uniquely identified by their numeric IDs, and there is no reliable way to infer one from a description.
+
+Optional: an output directory. The default is `<brand_dir>/properties/`, where `<brand_dir>` is the brand workspace for the agent that owns the listing. For a Muvin URL with the existing brand pack at `/Users/neo/estate-agents/muvin/`, that resolves to `/Users/neo/estate-agents/muvin/properties/`. If the brand workspace cannot be located, fall back to `./properties/` in the caller's current working directory.
+
+The property directory **must** sit inside its brand workspace at `<brand_dir>/properties/<property_slug>-<listing_id>/` — never as a sibling of the brand workspace, never inside another property's folder. This is the contract `make-brochure` and `property-brochure` read against.
+
+## Scope boundaries
+
+| In scope | Out of scope |
+|---|---|
+| Muvin listings (`muvin.co.uk/property/...`) and any other agent fronting the Loop CRM CDN (`*.b-cdn.net/propertyimages/...`, `*.b-cdn.net/floorplans/...`) | Listings on agency-specific platforms (Rightmove, Zoopla, OnTheMarket, OpenRent) — those have separate page structures and image hosts |
+| All photos, floorplans, drone shots, AI-staged renders | Stripping AI-generated images from the photo set — keep them all and flag in metadata |
+| Property description, key features, price, specs, agent contact | Walkthrough video transcription (the property-brochure skill handles that separately if the user supplies one) |
+| EPC rating as a value, EPC certificate PDF if linked from the page | EPC certificate retrieval from the EPC Register — that's a separate lookup; if the listing does not link the certificate, leave `epc/` empty and record `"epc_rating": "TBC"` (or the band shown) in `property.json` |
+| Council tax band as shown on the page | Council tax band verification against VOA — out of scope |
+| Material Information visible on the listing page (tenure, council tax, EPC) | Full Part A/B/C compliance gathering — that's the brochure assembly step's job |
+
+If the page is JS-rendered and `curl` returns no asset URLs, fall back to a headless-browser fetch (Chrome DevTools MCP or Playwright). If even that fails, stop and report `STATUS: BLOCKED` — do not synthesise an asset list.
+
+## Artifact contracts
+
+### Folder layout
+
+The four subfolders are **mandatory and named exactly** as specified — they are part of the contract that `property-brochure` reads against. Do not pluralise differently, do not collapse `epc/` into `floorplans/`, do not add a sibling `videos/` folder. If a future asset class needs accommodating, propose a contract change to the plugin first.
+
+### `images/`
+
+Every URL on the page matching `b-cdn.net/propertyimages/<tenant-uuid>/<listing-id>/` is an image asset. Two CDN buckets are in active use as of April 2026:
+
+- `loop-app.b-cdn.net` — older photos (2024-vintage uploads)
+- `loopcrm.b-cdn.net` — newer 2026 additions (drone shots, AI-staged renders, screenshots)
+
+Download all of them. Preserve the original filenames — they encode upload timestamps as Unix epochs (e.g. `DSC01495_1727361503898.jpg` → 26 Sept 2024) which are useful for ordering and de-duplication later.
+
+Image categories observable from filename prefixes:
+
+| Prefix | Origin |
+|---|---|
+| `DSC*`, `IMG*` | Photographer's DSLR/mirrorless |
+| `DJI_*` | Drone imagery |
+| `ChatGPT-Image-*` | AI-staged render |
+| `Screenshot-*` | Map/aerial screenshot from a desktop tool |
+| `iPhone*`, `WhatsApp*` | Quick mobile snaps (lower resolution) |
+
+Record the count per prefix in `property.json` under `media.image_breakdown` — `property-brochure` uses this to pick the right photo for each slot.
+
+### `floorplans/`
+
+URLs matching `b-cdn.net/floorplans/<tenant-uuid>/<listing-id>/`. Listings typically ship one floorplan per floor (so 1–3 files for a UK home). Preserve original filenames.
+
+### `epc/`
+
+If the page links a PDF whose URL contains `epc` or whose link text mentions "EPC" / "Energy Performance Certificate", download it here. If the page only states a rating ("EPC rating: D") without linking a certificate, leave the folder empty and reflect the rating in `property.json`. If the rating is "TBC", record that exact string — do not guess.
+
+### `brochure/`
+
+Always empty on output. This is the slot `property-brochure` writes its `output/brochure.html` and per-page print PNGs into. Creating it pre-empts a "where does the brochure go" question downstream.
+
+### `property.json`
+
+Machine-readable metadata. Required keys:
+
+```json
+{
+  "source": {
+    "url": "<full listing URL>",
+    "listing_id": "<numeric id>",
+    "tenant_id": "<uuid from CDN paths>",
+    "scraped_on": "<YYYY-MM-DD>"
+  },
+  "address": {
+    "line_1": "...",
+    "locality": "...",
+    "postcode": "..."
+  },
+  "price": {
+    "amount": <integer GBP>,
+    "currency": "GBP",
+    "qualifier": "Offers Over | Guide Price | Asking Price | POA"
+  },
+  "specifications": {
+    "property_type": "Detached House | ...",
+    "bedrooms": <int>,
+    "bathrooms": <int>,
+    "reception_rooms": <int>,
+    "tenure": "Freehold | Leasehold | null",
+    "epc_rating": "A | B | ... | TBC",
+    "council_tax_band": "A | B | ... | H",
+    "age": "<string, optional>"
+  },
+  "key_features": ["...", "..."],
+  "agent": {
+    "name": "...",
+    "agency": "...",
+    "phone": "...",
+    "email": "..."
+  },
+  "media": {
+    "video_tours": ["<url>", "..."],
+    "image_count": <int>,
+    "floorplan_count": <int>,
+    "epc_document": "<filename in epc/ or null>",
+    "brochure": null
+  }
+}
+```
+
+Unknown values are `null`, not `""` and not omitted. The downstream brochure skill relies on `null` to recognise "we know we don't have this" vs. a missing key (= "this wasn't extracted, look again").
+
+### `description.md`
+
+Plain Markdown, no frontmatter. Structure:
+
+1. H1: full address.
+2. One-line summary: price, beds, baths, reception rooms, type, council tax, EPC.
+3. Source line: linked listing URL.
+4. Agent line: name, agency, phone, email.
+5. H2 "Property Description" — verbatim paragraphs from the listing's description section. Preserve paragraph breaks. Do not paraphrase. Strip HTML entities (`&rsquo;` → `'`, `&amp;` → `&`).
+6. H2 "Video tours" — bulleted list of every video URL on the page (YouTube, Vimeo, Giraffe360, Matterport, etc.).
+7. H2 "EPC and council tax" — both values exactly as shown.
+8. H2 "Folder layout" — one-line description of what's in each subfolder, with the actual counts.
+
+Capture rules:
+
+- **Verbatim** for the description body. The agent's wording is the source of truth for the brochure copy.
+- If the listing has no description text (rare), record `_No description provided on the listing._` and continue. Do not invent.
+- If the listing's marketing footer ("WOULD YOU LIKE TO VIEW", "CAN WE HELP YOU TOO") is intermingled with the property description, **keep the property paragraphs and drop the agency boilerplate** — the brochure has its own back-page CTA.
+
+## Image preview safety
+
+**Do not `Read` any downloaded image whose longest edge exceeds 2000px** — it breaks the session by overrunning the multimodal encoding budget. Most DSLR (`DSC*`) and drone (`DJI_*`) photos from a Muvin listing are 6000–8000px and will trigger this. Measure with `sips -g pixelWidth -g pixelHeight <file>` before any `Read`, or skip the visual check entirely (filename, byte-size, and `sips` dimensions cover most "did the download work?" questions). See `make-brochure` for the full safety workflow including the `sips -Z 2000` downscale recipe.
+
+## Process — high level
+
+The skill orchestrates four capabilities, each a **what** not a **how**:
+
+1. **Probe.** Fetch the URL once with `WebFetch` to get a summarised view (price, address, agent, image count). This is a cheap sanity check — if the summary disagrees with what you extract from raw HTML, the page is likely JS-rendered and you need a headless browser.
+2. **Extract.** Pull the raw HTML and grep all `b-cdn.net/propertyimages/...` and `b-cdn.net/floorplans/...` URLs. Deduplicate. Also grep PDF URLs containing `epc`. Extract the `<div class="section__description">` block for the description text.
+3. **Stage.** Create the four-folder structure under `<output-dir>/<slug>-<listing-id>/`. Download images and floorplans in parallel (`xargs -n1 -P8 curl -O -L`) — there are routinely 40–60 images per listing and serial downloads are slow.
+4. **Assemble.** Write `property.json` and `description.md`. Run a final consistency pass: image count in JSON matches files on disk, EPC rating in JSON matches the description.md line, agent contact in JSON matches the description.md header.
+
+The skill does not prescribe which HTTP tool to use. `curl` is fine for the static HTML pages Muvin serves. If a future agent ships a JS-rendered listing page, switch to Chrome DevTools MCP or Playwright — the contract on the output is unchanged.
+
+## Reference standard
+
+Before producing output, read these files to anchor the format:
+
+- `/Users/neo/estate-agents/muvin/properties/henham-road-debden-green-hamperden-end-cb11-3lz-949931/property.json` — the JSON schema in practice.
+- `/Users/neo/estate-agents/muvin/properties/henham-road-debden-green-hamperden-end-cb11-3lz-949931/description.md` — the prose voice and structure.
+
+A delivered package that diverges substantially in shape from the reference is wrong, even if the content is accurate.
+
+## Common mistakes
+
+| Mistake | Why it's wrong |
+|---|---|
+| Using only the `WebFetch` summary | The summary lists "49 images" but does not return individual URLs. You must grep the raw HTML for filenames. |
+| Stripping AI-generated renders from `images/` | They are part of the listing's marketing set. The brochure skill chooses which to use; the extractor's job is fidelity. |
+| Renaming files to a `<slug>-NN.jpg` scheme on extraction | That's `property-brochure`'s job at the brochure-assembly step. Keep originals so the brochure skill can match by prefix and timestamp. |
+| Inventing values for unknown specifications | `null` means "not on the listing". A guess at tenure or EPC introduces silent error into downstream Material Information compliance. |
+| Including the agency's marketing boilerplate ("WOULD YOU LIKE TO VIEW", "CAN WE HELP YOU TOO") in `description.md` | The brochure has its own back page. Including it would duplicate text the brand designer is already authoring. |
+| Skipping `floorplans/` because the listing only has one | One floorplan still goes in `floorplans/`, not `images/`. The folder layout is a contract — `property-brochure` looks for floorplans in exactly one place. |
+| Saving `/tmp/muvin_property.html` or other working files inside the output directory | The directory is the deliverable. Working files get cleaned up. |
+| Hardcoding the tenant UUID | The UUID identifies the agency on Loop CRM. Different Muvin offices can have different tenant IDs. Extract it from the actual URLs on the page. |
+| Treating "EPC: TBC" as a missing field | "TBC" is information — the agent is telling you the assessment hasn't been done. Record it verbatim. |
+
+## Completion criteria
+
+Report `DONE` only after:
+
+- The directory `<slug>-<listing-id>/` exists with all four subfolders.
+- `property.json` and `description.md` are at the directory root.
+- `images/` count matches `media.image_count` in `property.json`.
+- `floorplans/` count matches `media.floorplan_count` in `property.json`.
+- `epc/` is either empty (with rating "TBC" or only-rating-shown) or contains a downloaded certificate referenced by `media.epc_document`.
+- `brochure/` exists and is empty.
+- No `/tmp` files, no `.html` dumps, no `urls.txt` left behind.
+- The source URL appears in `property.json.source.url` and on the source line of `description.md`.
+
+If any of those are not true, report `DONE_WITH_CONCERNS` and list each gap.
+
+## When NOT to use this skill
+
+- The user wants a brochure produced from photos they already have on disk → skip extraction, go straight to `property-brochure`.
+- The listing is on Rightmove, Zoopla, OnTheMarket, or another non-Loop-CRM platform → the URL parsing and CDN paths differ. Either extend this skill with a new branch or route to a platform-specific extractor.
+- The user wants a quick price/specs lookup, not the full asset bundle → use `WebFetch` directly. The folder structure is overkill.
+- The user wants market data, comparables, or transaction history → that's a different research task; this skill is asset staging, not analysis.