@rubytech/create-maxy-code 0.1.114 → 0.1.115

package/payload/premium-plugins/real-agent/plugins/brochures/skills/property-brochure/references/structure.md

@@ -1,249 +0,0 @@
-# Brochure structure — orientation, 16-page layout, cover, floorplan, features, MI, QR, map
-
-## Orientation
-
-Brochures ship in either **landscape** (297×210mm A4, default — the editorial folio is designed for it) or portrait (210×297mm A4). The choice changes page geometry, render-slot dimensions, print snapshot pixel sizes, the PDF call, and which page layouts make visual sense — it is **not a cosmetic flag**. Every downstream measurement has a landscape value and a portrait value.
-
-### When to ask
-
-Default to landscape unless the user says otherwise. The folio's editorial layouts (split heros, wide caption strips, full-bleed feature spreads, three-column plan + particulars + EPC pages) are tuned for landscape proportions; portrait works but compresses the spreads. If the user explicitly asks for portrait, fine — re-test every page's `scrollHeight` against the new fit budget before generating snapshots. If a prior brochure for this property exists at `<property_dir>/output/brochure.html`, inherit its orientation by reading the CSS (`@page { size: A4 landscape | portrait }`) rather than asking again.
-
-### Dimensional contract
-
-| Quantity | Landscape (default) | Portrait |
-|---|---|---|
-| `.page` width × height | 297mm × 210mm | 210mm × 297mm |
-| Page fit budget (px @ 96dpi) | 1123 × **794** | 794 × **1123** |
-| Print snapshot pixel dimensions | 1123×794 | 794×1123 |
-| `@page` rule | `size: A4 landscape` | `size: A4 portrait` |
-| Playwright `page.pdf()` | `landscape: true` | (default; portrait) |
-| "Safe to read" snapshot ceiling | longest-edge 1123px | longest-edge 1123px |
-
-The 1600px image-source ceiling from `images.md` is unchanged — it provides 2× retina headroom for full-bleed images at either orientation.
-
-### Reference template orientation swap
-
-`references/template.html` ships **landscape** (`width: 297mm; min-height: 210mm` across `.page`, `.cover`, `.backpage`, plus `@page { size: A4 landscape }` in the print CSS). For portrait, swap every `297mm` ↔ `210mm` in those rules and change `@page { size: A4 landscape }` to `@page { size: A4 portrait }`. The page-internal flex/grid layouts then redistribute against the new aspect — re-test every page's `scrollHeight` against the new fit budget (1123 instead of 794) before generating snapshots, and expect the editorial feel to compress: the wide caption strips and side-by-side spread layouts will need to stack rather than sit alongside.
-
-## 16-page structure
-
-Each page is a `<section class="page">` (or `.cover` / `.backpage`) sized to the chosen orientation: `width: 297mm; min-height: 210mm` (landscape) or `width: 210mm; min-height: 297mm` (portrait). Every page must fit within the orientation's short-edge budget (794px landscape, 1123px portrait — both at 96dpi). Measure with `element.scrollHeight` during development against that budget and adjust image heights with inline styles if content overflows.
-
-The page count is **sixteen** so the brochure prints cleanly on duplex (16 is even) and binds cleanly as a saddle-stitched booklet (16 ÷ 4 = 4 folded sheets). See `a4-print-documents` → **Even-page count for duplex printing**.
-
-| Page | Class | Chapter | Key content |
-|------|-------|---------|-------------|
-| 1 | `.cover` | Cover | Split layout — paper title block on top with property name + address subtitle, full-bleed hero photo below |
-| 2 | `.page` | Contents (TOC) | Editorial image with caption, eight-chapter table of contents (Roman i–viii), credit line, folio strip |
-| 3 | `.page` | I · Of place & pedigree | Opener — property name with county sub-line, street + postcode + price spec, 5-stat row, two-paragraph editorial intro with dropcap, principal elevation image with caption |
-| 4 | `.page` | II · A house at ease | Hero open-plan image, text column, three-image caption strip |
-| 5 | `.page intermission` | (no chapter — visual breath) | Full-bleed image-only spread between chapters; no editorial copy |
-| 6 | `.page` | III · Hall, hearth & sun | Split header, large left image, two stacked right images |
-| 7 | `.page intermission` | (no chapter — visual breath) | Full-bleed image-only spread between chapters |
-| 8 | `.page` | IV · Bedrooms & baths | Text column with 3-stat row, 5-cell gallery (one tall feature) |
-| 9 | `.page gallery-page` | Image-led additional internal | Full-page asymmetric photo grid (no body copy), gallery head with eyebrow + title, captions per cell |
-| 10 | `.page` | V · Pool, outdoor kitchen & summerhouse | Full-bleed feature image, narrow text panel with attribute grid (repurpose if no leisure block — annexe / studio / outbuilding) |
-| 11 | `.page intermission` | (no chapter — visual breath) | Full-bleed outdoor image-only spread |
-| 12 | `.page folio-dark` | VI · Garden & ground | Full-bleed aerial with overlaid title, four short-text panels, dark-pill folio chrome |
-| 13 | `.page siteplan-page` | (extension of VI) | Dedicated site-plan page — large plot plan on one side, plot/grounds text panel on the other |
-| 14 | `.page` | VII · Plan & particulars | Wide chapter header, large floor plan + meta, 8-9 item particulars list, EPC bar chart |
-| 15 | `.page` | VIII · Material information | Three-section disclosure grid (Parts A/B/C), boilerplate footer |
-| 16 | `.backpage` | Back page | Atmospheric background, brand masthead, CTA headline, tagline, two-cell contact grid (agent + office), QR strip (video tour + listing), folio footer, disclaimer |
-
-**Page-type classes.** The default folio uses three structural extensions to the base `.page`:
-
-- `.intermission` — full-bleed photo spread with no editorial copy. Three intermissions sit between chapters (after II, IV/gallery, V) to give the eye a beat. If the property doesn't have enough strong landscape/atmospheric photos to fill all three, drop the weakest intermission rather than reusing an image.
-- `.gallery-page` — asymmetric grid of property photos (typically 4–5 cells with one tall feature) with a small head block and per-cell captions. Used for "rooms in passing" — supplementary internal shots that don't anchor a chapter.
-- `.siteplan-page` — dedicated plot-plan page with a large plan image and a text-side panel describing acreage, paddocks, drives, outlook. Pairs with the **Garden & ground** chapter — both pages share Roman numeral VI.
-- `.folio-dark` — applied to dark/photo-heavy pages so the folio chrome swaps to light-on-dark.
-
-## Cover layout — title block above, photo below
-
-The cover is the property's name plate, not its full pitch. The reference register (Knight Frank country houses, Strutt & Parker folios, Sotheby's International Realty) uses a **split layout**:
-
-1. Top ~85mm of paper, ivory background, with the property name in serif caps with heavy letter-spacing, flanked by hairline gold rules, with one tracked-caps subtitle below (full address)
-2. Bottom ~125mm full-bleed photographic image — the strongest single hero shot, no overlays
-
-**Do not** place price, edition number, folio number, masthead with brand logo, tagline paragraph, or location eyebrow over the cover photo. Each of those is a contrast-fight against the photo and a magnet for the panel-treatment work-around. The cover reads as confident only when the image is unblemished.
-
-Where do those data points go instead?
-
-| Data point | Lives on |
-|---|---|
-| Property name + full address | Cover title block (the only thing on the cover) |
-| Price | Page 3 opener, beneath the property name in italic, *and* in Material Information |
-| Folio / reference number | Back page, foot-left in tracked caps, *and* implicitly in the URL |
-| Edition / season | Optional, back page foot-right; usually omitted for evergreen brochures |
-| Brand masthead / agency name | Back page top, as a logo (light/white variant on the dark back-page hero) |
-| Tagline | Page 3 opener body or back-page tagline |
-
-The Knight Frank pattern: **the property speaks first**. The agency surfaces on the back where the buyer reads contact details. The price surfaces on the second spread, after the buyer has seen the photo.
-
-## Floorplan sizing (page 10)
-
-Floorplans are the most information-dense images in the brochure. The plan area on page 10 is the largest rectangle that does not push the particulars list, EPC bar, or chapter header off A4. Use `object-fit: contain; width: 100%; height: 100%` so the image fills the slot without distortion. Wide-aspect floorplans leave vertical headroom; tall ones leave horizontal headroom — that's expected and fine. After any change, measure both `scrollHeight` against the orientation's page-fit budget (794px landscape / 1123px portrait) **and** the spec-side column's `scrollHeight` against `clientHeight` — text overflow is the silent failure that a screenshot can hide.
-
-If a brochure has multiple floor plans (per-floor breakdowns), tune the layout to the images' aspect ratios rather than splitting evenly. A 2:1 wide-aspect plan needs less vertical room than a 1.16:1 nearly-square one.
-
-## Distinguishing features clearly — "outdoor kitchen" ≠ "summerhouse" ≠ "orangery"
-
-Property listings in this register often have several distinct outdoor or auxiliary buildings, each photographed separately. The brochure must keep them distinct in copy *and* match each photo to the right structure. The recurring failure mode is collapsing them into a single noun ("the cedar pavilion", "the garden complex") that means different things on different pages.
-
-For Henham/Sparrows-Farm-style country homes the typical glossary is:
-
-| Feature | Description | Photo cue |
-|---|---|---|
-| **Outdoor kitchen** | Cedar-clad cooking pavilion with sloped tile roof, sink, grill, often a wood-fired oven, bench or table seating | Wood/cedar walls dominate; no glass walls; cooking equipment visible |
-| **Summerhouse** | Detached glass-walled structure on a raised stone plinth, accessed by steps, often houses a gym or studio | Glass walls dominate; not for cooking; raised on plinth |
-| **Orangery** | Internal-to-the-home glass-roofed reception room, opens onto patio, used as a third living room | Inside the home's footprint; vaulted glass roof; furnished with sofas |
-| **Garden room** | A room within the home or a detached pavilion overlooking the garden, less glass-heavy than the orangery | Often has corner glazing but solid walls behind |
-
-Use the precise noun in copy and the precise photo per chapter. Do **not**:
-
-- Call the outdoor kitchen "the summerhouse" because both are outdoor structures
-- Call the summerhouse "the cedar pavilion" because cedar is the cladding material of the *outdoor kitchen*; the summerhouse is glass-walled
-- Use "garden complex" as a chapter title — it's vague; use the actual feature names
-- Conflate the orangery (interior reception) with the garden room (different room entirely)
-
-Verify each feature has its own photograph and its own paragraph. If the property has a feature that isn't photographed prominently (e.g. the summerhouse only appears in a wide drone shot), surface that as `DONE_WITH_CONCERNS` so the user can decide whether to commission a shot or downplay the feature in the copy.
-
-## Material Information (UK regulatory compliance)
-
-Three tiers per National Trading Standards and DMCCA 2024. Populate all known fields; mark unknowns as "TBC":
-
-- **Part A** (all transactions): price, tenure, council tax, property type, rooms, floor area, utilities (electricity, water, sewerage, heating), broadband, mobile, parking, EPC
-- **Part B** (where applicable): building safety, covenants, rights of way, easements, listed status, conservation area, TPOs, accessibility
-- **Part C** (additional facts): flood risk, coastal erosion, planning, construction type, structural issues, subsidence, damp, asbestos, knotweed, mining
-
-### Floor area — exclude detached outbuildings
-
-Total internal floor area is the sum of the principal home's floors. **Do not include detached outbuildings** (gymnasium-summerhouses, garages, plant rooms, garden offices) in the principal floor figure even when they sit at the same level on the floor plan or share a footprint reference. List them separately:
-
-> Floor 1 · 2,573 sq ft · Floor 2 · 1,948 sq ft · Gymnasium (summerhouse) · 495 sq ft · Garage · 338 sq ft
-
-A first-floor figure that secretly includes a detached gymnasium is a misrepresentation — even by a small amount it changes the £/sq ft and the comparable. Keep the principal home's floors honest, and disclose ancillary footprints alongside.
-
-### Pulling material data from a third-party report
-
-For UK listings, a Sprift, Propalt or PropertyData report can supply many Part A and Part B/C values that are not on the public listing page. When the user supplies a Sprift report URL or invokes one of the API endpoints below, navigate the page in a browser (not `WebFetch` — Sprift dynamically loads its sections) and extract:
-
-| Source | What it adds |
-|---|---|
-| [Sprift KFB report](https://reports.sprift.com/...) | Tenure, title number, council tax band + £, EPC current/potential, broadband (FTTP/FTTC/ADSL speeds), mobile signal coverage, flood risk, conservation area, restrictive covenants, UPRN, local authority, plot acreage |
-| [Sprift API](https://sprift.com/data-and-api) | Same fields programmatically |
-| [Propalt API](https://propalt.co.uk/product/api) | Material info bundled |
-| [PropertyData / Land Registry API](https://propertydata.co.uk/api/land-registry) | Title number, sold-history, deed restrictions |
-
-Sprift's KFB report is the most useful free-form source — it's a single URL the user pastes, contains nearly everything needed for Part A, and is current. Treat the listing page as authoritative for marketing copy (price, photos, key features) and the Sprift KFB report as authoritative for compliance data (tenure, broadband, flood risk).
-
-## Back-page QR codes — clickable, with visible URL
-
-The back page includes two QR codes, one for the video tour and one for the listing URL. The QR images alone are sufficient for a printed brochure (a viewer scans with their phone), but the brochure is *also* read as a digital PDF and as a hosted web page, where a QR code is unscannable from the same screen. Each QR must therefore have:
-
-1. The QR image itself (for print scanning).
-2. A short label above describing what it links to ("Watch the *video tour*", "View the *full listing*").
-3. **A visible, underlined URL beneath the label** — short and human-readable (e.g. `youtu.be/8V7jjS5ZyeI`, `muvin.co.uk · listing 949931`).
-4. **The whole stack wrapped in an `<a>` tag with `target="_blank" rel="noopener"`** so the QR image, label and URL are all clickable in the digital PDF and on the web.
-
-Markup:
-
-```html
-<div class="back-qr-strip">
-  <a class="qr" href="https://youtu.be/<videoId>" target="_blank" rel="noopener">
-    <img src="images/qr-video.png" alt="Scan or click to view the property video tour">
-    <div class="qr-label">Watch the <em>video tour</em></div>
-    <div class="qr-link">youtu.be/<videoId></div>
-  </a>
-  <a class="qr" href="https://<agent>.co.uk/property/<slug>/<id>/" target="_blank" rel="noopener">
-    <img src="images/qr-listing.png" alt="Scan or click to view the full property listing">
-    <div class="qr-label">View the <em>full listing</em></div>
-    <div class="qr-link"><agent>.co.uk &middot; listing <id></div>
-  </a>
-</div>
-```
-
-The `.qr-link` is **always present** — never empty. A printed brochure shows it as a typeset URL; a digital reader hovers and clicks it. Don't let the URL wrap awkwardly: keep it short (path stripped), use `&middot;` to separate domain and identifier, and apply `font-variant-numeric: tabular-nums` to the digits so they kern cleanly in the underlined treatment.
-
-Default styling:
-
-```css
-.back-qr-strip a.qr {
-  display: flex; flex-direction: column; align-items: center; gap: 6px;
-  text-decoration: none; color: inherit;
-  transition: opacity 200ms ease;
-}
-.back-qr-strip a.qr:hover { opacity: 0.85; }
-.back-qr-strip .qr-link {
-  font-family: var(--sans);
-  font-size: 9px; font-weight: 400;
-  text-decoration: underline;
-  text-decoration-color: rgba(201,176,122,0.45);
-  text-underline-offset: 3px;
-  color: var(--gold-300);
-  text-align: center;
-  font-variant-numeric: tabular-nums;
-  margin-top: 4px;
-}
-```
-
-A common mistake is to ship QR codes without the visible URL — it makes the digital experience worse than the print one. The visible URL is mandatory.
-
-## Location map — extract or omit
-
-The brochure includes a location map **only when the source listing supplies one**. When the listing has no map, the brochure ships without a map slot. The pipeline never synthesises a map from a postcode, an OSM static-tile call, or AI-generated artwork — postcode centroids can mislead about exact location, and the brochure should reflect what the agent actually publishes, not what the pipeline could imagine. **Extract or omit.**
-
-### How the conditional works
-
-`property-extract` screenshots whatever map element exists on the listing — provider-agnostic by design. Google Maps iframes (Loop CRM / Muvin), Mapbox or Leaflet div+canvas builds, static-map `<img>` tags from Rightmove-style backends, Apple/Bing embeds — they all land as `<property_dir>/images/map.webp` and `media.map: "map.webp"` in `property.json`. When no map element is detected on the listing, both `media.map` and (typically) `address.geo` are `null`. See **Map — extract or omit** in the property-extract SKILL for the heuristic detector and the screenshot contract.
-
-The template ships with a marker-bounded conditional block on page 10 (Plan & particulars), in the `.spec-side` column above the EPC bars:
-
-```html
-<!-- BROCHURE_MAP_SLOT_START
-     CONDITIONAL: render only when property.json -> media.map is non-null.
-     If media.map is null, DELETE everything between BROCHURE_MAP_SLOT_START
-     and BROCHURE_MAP_SLOT_END (inclusive of both marker comments). -->
-<figure class="location-map">
-  <img src="images/map.webp" alt="Location of Property Name — Town, Postcode">
-  <figcaption>Source: Google Maps &copy; YYYY Google</figcaption>
-</figure>
-<!-- BROCHURE_MAP_SLOT_END -->
-```
-
-The agent's job at brochure-assembly time:
-
-| `property.json -> media.map` | Action |
-|---|---|
-| Filename string (e.g. `"map.webp"`) | Leave the block in place. Copy `<property_dir>/images/map.webp` into `<output>/images/map.webp` (re-encode at 1500px / q86 if not already optimised). Substitute the filename, alt text (property name + town/postcode), and the year in the figcaption. |
-| `null` | **Delete** every line between `<!-- BROCHURE_MAP_SLOT_START` and `<!-- BROCHURE_MAP_SLOT_END -->` **inclusive of both marker comments**. The page-10 layout reflows; no placeholder, no broken image, no empty box. |
-
-The marker pattern is the same in both the template HTML and this SKILL — grep `BROCHURE_MAP_SLOT_START` across the plugin to see every place it's referenced.
-
-### Attribution
-
-When the slot is rendered, the figcaption must credit the provider whose tiles are visible in the screenshot. Read `property.json -> address.geo.source` and choose the right line:
-
-| `source` value | Figcaption text |
-|---|---|
-| `google_maps_iframe` | `Source: Google Maps © {year} Google` |
-| `mapbox_iframe` | `Source: © Mapbox © OpenStreetMap` |
-| `apple_maps_iframe` | `Source: Apple Maps` |
-| `static_map_image` | Use the attribution shown on the source listing if visible; otherwise the provider name as a generic noun (e.g. `Source: location map © OpenStreetMap contributors`) |
-| `unknown` (screenshot only) | `Source: location map as shown on the agent's listing` |
-
-Don't strip the attribution — it's a licence requirement on most providers' tiles, not a stylistic flourish. Google's brand guidelines additionally forbid recolouring the word "Google", so when that's the source keep "Google" in `var(--ink)`, not the gold accent. The italic figcaption styling lives in the template under `.location-map figcaption`.
-
-### Forbidden patterns
-
-The user has explicitly rejected synthesised maps. **None of these are allowed when `media.map` is `null`**:
-
-- Geocoding the postcode via postcodes.io (or any other geocoder) and rendering a centroid-pinned static map
-- OSM static-tile calls as a fallback ("just any map is better than no map")
-- AI-generated map artwork (DALL-E / Imagen / Midjourney prompts that produce map-like images)
-- Re-using a screenshot from a different listing or a stock map asset
-
-If `media.map` is `null` and the user asks for a map anyway, the correct answer is to send them back to the source listing — either the agent enables the map block on their CRM, or the brochure ships without one. **Extract or omit.**
-
-### Cross-reference
-
-The render-slot table in `images.md` lists "Map / screenshot" with a 1500 px digital floor and q86 WebP — those values apply **only** when a map has been captured. When `media.map` is `null`, there is no map asset to optimise and the row is moot.