@rubytech/create-sitedesk-code 0.1.340

package/payload/platform/plugins/memory/references/schema-estate-agent.md

@@ -0,0 +1,154 @@
+# Schema Reference — Estate Agent
+
+Vertical schema for `businessType: "estate-agent"` — estate agents, letting agents, property managers.
+
+This reference extends the base schema. All base node types remain valid. Load `schema-base.md` first.
+
+When loading this reference, confirm: "Using schema-base + schema-estate-agent".
+
+---
+
+## Additional Node Types
+
+| Entity | Neo4j Label | Schema.org Type | Required Properties |
+|--------|-------------|-----------------|---------------------|
+| Property | `Property` | `schema:Accommodation` | `accountId`, `slug` (id, address-derived), `address` |
+| Listing | `Listing` | `schema:RealEstateListing` | `accountId`, `slug`, `displayName`, `listingType` (sale/let), `status`, `sourceSystem`, `sourceId`, `scope`, `heroImageUrl`*, `pageUrl`*, `blurb` |
+| ImageObject | `ImageObject` | `schema:ImageObject` | `accountId`, `listingSlug`, `url`, `description`, `tags`, `scope` |
+| Viewing | `Viewing` | `schema:Event` (subtype) | `accountId`, `listing` (id), `applicant` (id), `date`, `feedback`, `outcome` |
+| Applicant | `Applicant` | `schema:Person` (extended) | Base Person properties + `budget`, `tenure`, `moveDate`, `requirements` |
+| Offer | `Offer` | `schema:Offer` | `accountId`, `listing` (id), `applicant` (id), `price`, `conditions`, `status`, `date` |
+
+\* `heroImageUrl` and `pageUrl` are required for any Listing whose `status` is `for-sale`, `under-offer`, or `sold` (anything publicly listable). Listings with `status: "off-market"` or `status: "withdrawn"` are exempt — they describe stock not currently visible to visitors and have no public listing page to point at. The curator writes `status: "off-market"` and skips the two URLs when the source has no public marketing.
+
+### Property — obligatory hub
+
+`:Property` is the obligatory top-level node of the estate-agent vertical: the physical property, with its listing events hanging beneath it. Every curated listing produces a `:Property` — there is no `:Listing` without a parent `:Property`. The physical property is the operator-facing object; a listing is a marketing event on it (a property can be listed for sale, withdrawn, then re-listed to let — three `:Listing` nodes, one `:Property`).
+
+`:Property` is keyed `(accountId, slug)`, where `slug` is the address-normalised slug (lowercase, ASCII, dash-separated; the same derivation the curator applies to a listing's address). One canonical address resolves to one `:Property` per account. (A UPRN is the stronger identity when one is resolvable; the curator carries no UPRN-resolution tool today, so the address slug is the operative key and UPRN is a future enrichment.)
+
+`:Property` carries the mandatory parent edge `(:Property)-[:LISTED_BY]->(:Organization {brandSlug})` naming the estate agency — this is the ≥1-adjacency write-gate parent that `:Listing` carried in the pre-inversion model. Its children attach via `(:Property)-[:HAS_LISTING]->(:Listing)`.
+
+`:Property` is created address-only. Structural fields — `propertyType`, `tenure`, `epcRating`, `features` — are optional enrichment a later curation top-up fills in; their absence never blocks the hub from being written (a listing routinely lands before structural data is collected). Only `accountId`, `slug`, and `address` are required on write.
+
+### Listing — full property set
+
+The required-properties column above is the minimum a Listing must carry. The complete property set the `listing-curator` specialist writes:
+
+**Visitor-renderable (the public agent reads these to assemble property cards):**
+- `slug` — URL-safe identifier derived from address (`griffin-house-upper-church-street-chepstow`)
+- `displayName` — human-readable title (`Griffin House, Upper Church Street, Chepstow NP16 5EX`)
+- `heroImageUrl` — primary image URL that will render inline in the chat
+- `blurb` — single marketing-grade sentence, ≤ 280 characters, suitable as alt-text and short caption
+- `pageUrl` — the live listing URL the visitor follows to view full details
+
+**Marketing entity:**
+- `listingType` — `sale` or `let`
+- `status` — `for-sale` / `under-offer` / `sold` / `withdrawn` / `off-market`
+- `price` — integer in pence (no currency symbol, no commas)
+- `priceQualifier` — `guide` / `offers-over` / `offers-in-excess` / `poa` / `fixed-price` / `auction` (null when not stated)
+- `bedrooms`, `bathrooms`, `receptionRooms` — integers (null when unknown)
+- `floorAreaSqft` — integer square feet (null when unknown)
+
+**Address (carried directly on the Listing rather than via a separate PostalAddress when only the formatted address is known — addresses upgrade to a linked `:PostalAddress` once structured):**
+- `postcode` — UK postcode, upper-case, single-space-separated outward/inward (`NP16 5EX`)
+- `addressLine` — first line of the address
+- `town`
+
+**Structured detail (optional):**
+- `propertyType` — `cottage` / `detached` / `semi-detached` / `terraced` / `flat` / `bungalow` / etc.
+- `tenure` — `freehold` / `leasehold` / `share-of-freehold` / `commonhold`
+- `description` — the full descriptive copy from the source (the `body` of any legacy KnowledgeDocument; the description block of the source listing)
+- `imageUrls` — string array of all image URLs (`heroImageUrl` is always also present in this array, at index 0)
+- `floorplanUrls` — string array
+- `epcUrl` — the EPC document URL
+
+**Published served-tree references (harvested by the curator after a site is published — see Filesystem ↔ graph below):**
+- `brochureUrl` — the hosted HTML brochure (`https://<publicHost>/sites/<slug>/brochure.html`) when a brochure was published with the site; null when the served tree carries no `brochure.html`. Unconstrained string — no `schema.cypher` constraint or index.
+- `socialTileUrls` — string array of the published Open Graph / social-share tile URLs (`https://<publicHost>/sites/<slug>/socials/og-*.jpg`); empty array when the site was published without a `socials/` subtree. Unconstrained string array — no `schema.cypher` constraint or index.
+
+**Provenance + search:**
+- `sourceSystem` — `loop-crm` / `zip-upload` / `manual`
+- `sourceId` — natural key in the source system (for Loop, the `loopPropertyId`)
+- `ingestedAt`, `lastVerifiedAt` — ISO timestamps
+- `scope` — `public` for listings that should be returned to anonymous visitors via the public memory-search; `shared` for staff-only listings (e.g. pre-marketing pipeline)
+- `embedding` — 768-dim vector (written automatically by `memory-write`)
+
+### ImageObject — per-photo node
+
+Every visitor-renderable image on a Listing is its own `:ImageObject` node, linked by `(:Listing)-[:DEPICTS]->(:ImageObject)`. Modelling images as graph entities lets the public agent pick contextually ("show me the kitchen") rather than always emitting the hero — memory-search returns the Listing plus its child ImageObjects in the `related` set, and the recommender chooses by reading each image's `description` and `tags`.
+
+Properties:
+
+- `accountId` — tenancy, mirrored from the parent Listing
+- `listingSlug` — the parent Listing's slug; carried directly so memory-search results on ImageObject alone can resolve back without a graph join
+- `url` — the live image URL (b-cdn.net for Loop, hosted-site path for zip-upload). Visitor-renderable as `![desc](url)` per the public agent IDENTITY image-allowlist clause
+- `description` — single sentence describing what the image shows. Vision-LLM-generated (Haiku) at curation time. ≤ 200 chars, plain English, no estate-agent clichés
+- `tags` — string array of normalised room/feature labels: `kitchen`, `bathroom`, `bedroom-master`, `bedroom-secondary`, `living-room`, `dining-room`, `garden-rear`, `garden-front`, `exterior-front`, `exterior-rear`, `hallway`, `utility`, `floorplan`, `epc`, `view`. Empty array when the image is unclassifiable. Tags drive room-specific picks; `description` drives general semantic search
+- `heroIndex` — integer position in the parent Listing's `imageUrls` array. `0` = the hero image. Used to fall back to hero when room-specific tags don't match
+- `scope` — mirrored from parent Listing (`public` for visitor-renderable; `shared` for staff-only)
+- `sourceSystem` — mirrored from parent Listing
+
+Natural key: **`(accountId, listingSlug, url)`**. The curator MERGEs on this triple. Re-running the curator over a Listing tops up missing ImageObjects without duplicating existing ones; description and tags refresh on each run (so a later vision-LLM upgrade improves quality without manual cleanup).
+
+No `embedding` on v1. The agent picks by reading the parent Listing's child ImageObjects from the `related` set returned by hybrid search; vector search over images is a follow-up only if pick quality is poor.
+
+Known limit: hybrid search's 1-hop expand caps `related` at 20 neighbours per Listing. Listings with more than 20 images lose the surplus to the cap. Acceptable for v1 (most listings ≤ 20); file a follow-up if it bites.
+
+### Listing — natural-key contract
+
+Idempotency key: **`(accountId, sourceSystem, sourceId)`**. The curator MERGEs on this triple. Re-running the curator over the same source record updates the existing Listing in place — fields refresh (status drift over the listing's lifecycle is expected and desired: `for-sale` → `under-offer` → `sold`); no duplicate Listing is ever created.
+
+If the source emits multiple distinct listing events tied to a single underlying property (e.g. relisted after withdrawal, then again let separately), each listing event carries its own `sourceId` in the source system and becomes its own `:Listing` node. The listings share one `:Property` parent, which holds a separate `(:Property)-[:HAS_LISTING]->(:Listing)` edge to each. Property idempotency on `(accountId, slug)` is additive to Listing idempotency: re-running the curator over the same source record creates no duplicate `:Property` and no duplicate `:Listing`. The curator never collapses distinct listing events into one node.
+
+### Applicant vs base Person
+
+`Applicant` extends the base `Person` type with property-search-specific properties. Use `Applicant` as an additional label on the `Person` node — the applicant is still a `Person` for base queries, but the extra label carries estate-agent-specific fields like `budget` and `requirements`.
+
+---
+
+## Relationship Patterns
+
+```
+(:Property)-[:LISTED_BY]->(:Organization {brandSlug})
+(:Property)-[:HAS_LISTING]->(:Listing)
+(:Listing)-[:DEPICTS]->(:ImageObject)
+(:Viewing)-[:FOR_LISTING]->(:Listing)
+(:Viewing)-[:BY_APPLICANT]->(:Person)
+(:Offer)-[:ON_LISTING]->(:Listing)
+(:Offer)-[:FROM_APPLICANT]->(:Person)
+```
+
+`(:Property)-[:LISTED_BY]->(:Organization {brandSlug})` is the mandatory parent edge that every `:Property` carries — it satisfies the ≥1-adjacency write-gate doctrine ([[feedback_graph_hierarchy_doctrine]]) and names the estate agency that listed the property. The target is `:Organization` keyed by `brandSlug`, not `:LocalBusiness`. `:LocalBusiness` is the per-account installer-seeded singleton (the account's own business — Real Agent itself); the write gate refuses any non-system attempt to create a second one. The agencies whose listings ingest through the curator are third-party businesses and live as `:Organization`.
+
+`(:Property)-[:HAS_LISTING]->(:Listing)` is the parent edge of every `:Listing` — the `:Listing` satisfies the ≥1-adjacency gate via this incoming edge from its `:Property` (the gate is direction-agnostic; an incoming edge from a parent counts). The pre-inversion `(:Listing)-[:FOR_PROPERTY]->(:Property)` edge is retired: the property is now the obligatory parent above the listing, not optional structural enrichment below it. Because the agency edge lives on `:Property`, the agency `:Organization` is two hops from a `:Listing` (Listing → Property → Organization); hybrid search's one-hop expansion returns the `:Property` for a Listing hit, not the agency.
+
+`(:Listing)-[:DEPICTS]->(:ImageObject)` is written by the curator once per image present on the Listing. ImageObjects satisfy the ≥1-adjacency rule via this edge (Listing is the parent); they do not carry their own `LISTED_BY` edge because the Listing already does. Hybrid search expands one hop by default, so a memory-search returning a Listing also returns its DEPICTS-linked ImageObjects in the result's `related` array — no separate search call needed to assemble a property card with the right image.
+
+---
+
+## Filesystem ↔ graph (base template)
+
+Unlike a construction job folder (operator-authored source files), the estate-agent projection is over a **published served tree** — hosting output the platform writes, not files the operator edits by hand. Each served listing lives at `<accountDir>/sites/<slug>/`, the on-disk target of `publish-site`, and is served at `https://<publicHost>/sites/<slug>/`. The graph references this tree by **hosted URL**, never by local path: a `:Listing`/`:ImageObject` URL property is the canonical reference, and the served file is the thing it points at. This mapping is the **base template** — the standard a brochure-pipeline publish projects into; it is shipped-generic, not any operator's data.
+
+**URL ↔ path rule (deterministic).** Every served artefact resolves both ways by a single substitution: `https://<publicHost>/sites/<slug>/X` ↔ `<accountDir>/sites/<slug>/X`. The `/sites/<slug>/` segment is invariant — it is the publish target's on-disk shape mirrored into the hosted path. To resolve a graph URL to a local file, strip the `https://<publicHost>/sites/<slug>/` prefix and join the remainder onto `<accountDir>/sites/<slug>/`; to project a served file, do the reverse.
+
+**Artefact → graph reference.** Every visitor-renderable or publicly-meaningful artefact class under `sites/<slug>/` resolves to a `:Listing` or `:ImageObject` reference:
+
+| Served artefact | Graph reference |
+|---|---|
+| `index.html` — the published landing page | `:Listing.pageUrl` |
+| `images/<photo>.{jpg,jpeg,png,webp}` (non-logo) | `:Listing.imageUrls[]`, `:Listing.heroImageUrl` (index 0), and one `:ImageObject.url` per photo |
+| `images/*floorplan*.{jpg,png}` | `:Listing.floorplanUrls[]` (and its `:ImageObject.url`) |
+| `images/epc.{jpg,png,pdf}` or `epc.*` at the root | `:Listing.epcUrl` (and its `:ImageObject.url`) |
+| `brochure.html` — the hosted HTML brochure | `:Listing.brochureUrl` |
+| `socials/og-*.jpg` — Open Graph / social-share tiles | `:Listing.socialTileUrls[]` |
+
+**Served but intentionally unreferenced (tool / collateral).** These classes are part of the published bundle but carry no graph reference by design — the reconcile audit excludes them exactly as it excludes the `url-get/` cache, and their presence is never an orphan:
+
+- `<slug>-brochure.pdf` — the downloadable form of the brochure; `brochureUrl` references the canonical `brochure.html`, so the PDF is the same artefact class, not a separate node reference.
+- `socials.html`, `social-posts.md`, `og.html` — operator-only social collateral and the re-run template; not visitor-renderable, not indexable.
+- `images.json` — the curator's brochure sidecar (consumed at curation time, not a renderable artefact).
+- `llms.txt`, `llms-full.txt` — AEO surfaces written by `publish-site`.
+
+A served file outside the referenced classes and outside this exclusion set is an orphan — the reconcile audit counts it in `unreachable`. `broken-refs` is scoped to **served-tree URLs only**: a `:Listing`/`:ImageObject` URL that matches the `https://<publicHost>/sites/<slug>/` prefix but resolves to no served file (slug rename, un-republished listing) is counted in `broken-refs`. Externally-hosted URLs are outside the served tree and outside this audit — a Loop listing's `b-cdn.net` `:ImageObject.url` or its Rightmove/Zoopla/agent-site `pageUrl` carries no `sites/<slug>/` prefix, the URL↔path rule cannot resolve it, and it is never counted as broken. Map a served file to its nearest canonical reference; invent no node or edge type absent from this schema.

package/payload/platform/plugins/memory/references/schema-food-beverage.md

@@ -0,0 +1,32 @@
+# Schema Reference — Food & Beverage
+
+Vertical schema for `businessType: "food-beverage"` — restaurants, cafes, bars, food trucks, catering.
+
+This reference extends the base schema. All base node types remain valid. Load `schema-base.md` first.
+
+When loading this reference, confirm: "Using schema-base + schema-food-beverage".
+
+---
+
+## Additional Node Types
+
+| Entity | Neo4j Label | Schema.org Type | Required Properties |
+|--------|-------------|-----------------|---------------------|
+| TableReservation | `TableReservation` | `schema:FoodEstablishmentReservation` | `accountId`, `guest` (id), `partySize`, `date`, `time`, `tableNumber`, `reservationStatus` |
+| MenuItem | `MenuItem` | `schema:MenuItem` | `accountId`, `name`, `description`, `price`, `category`, `allergens`, `available` |
+| Menu | `Menu` | `schema:Menu` | `accountId`, `name`, `validFrom`, `validThrough`, `items` |
+| DiningOrder | `DiningOrder` | `schema:Order` (F&B subtype) | `accountId`, `table` (id), `items`, `orderStatus`, `totalPrice`, `servedBy` (id) |
+
+### DiningOrder vs base Order
+
+`DiningOrder` is the food-and-beverage-specific label for table orders. Use `DiningOrder` (not `Order`) for orders placed at a table or counter. The base `Order` is used for general jobs — `DiningOrder` carries F&B-specific properties like `table` and `servedBy`.
+
+---
+
+## Relationship Patterns
+
+```
+(:Menu)-[:CONTAINS]->(:MenuItem)
+(:DiningOrder)-[:FROM_TABLE]->(:TableReservation)
+(:DiningOrder)-[:INCLUDES]->(:MenuItem)
+```

package/payload/platform/plugins/memory/references/schema-hospitality.md

@@ -0,0 +1,31 @@
+# Schema Reference — Hospitality
+
+Vertical schema for `businessType: "hospitality"` — hotels, B&Bs, guesthouses, serviced apartments.
+
+This reference extends the base schema. All base node types remain valid. Load `schema-base.md` first.
+
+When loading this reference, confirm: "Using schema-base + schema-hospitality".
+
+---
+
+## Additional Node Types
+
+| Entity | Neo4j Label | Schema.org Type | Required Properties |
+|--------|-------------|-----------------|---------------------|
+| Reservation | `Reservation` | `schema:LodgingReservation` | `accountId`, `guest` (id), `checkInDate`, `checkOutDate`, `roomType`, `totalPrice`, `reservationStatus` |
+| Room | `Room` | `schema:Accommodation` | `accountId`, `name`, `roomType`, `capacity`, `pricePerNight`, `amenities` |
+| GuestProfile | `GuestProfile` | `schema:Person` (extended) | Base Person properties + `dietaryRequirements`, `preferences`, `loyaltyPoints` |
+
+### GuestProfile vs base Person
+
+`GuestProfile` extends the base `Person` type with hospitality-specific properties. When creating a guest record, use `GuestProfile` as an additional label on the `Person` node — the guest is still a `Person` for base queries, but the extra label allows hospitality-specific property queries.
+
+---
+
+## Relationship Patterns
+
+```
+(:Reservation)-[:FOR_ROOM]->(:Room)
+(:Reservation)-[:BOOKED_BY]->(:Person)
+(:Invoice)-[:FOR_RESERVATION]->(:Reservation)
+```

package/payload/platform/plugins/memory/references/schema-knowledge-work.md

@@ -0,0 +1,80 @@
+# Schema Reference — Knowledge Work
+
+Vertical schema for `businessType: "knowledge-work"` — the SiteDesk brand's knowledge workers: strategists, founders, operators, researchers, analysts.
+
+This reference extends the base schema. All base node types remain valid. Load `schema-base.md` first.
+
+When loading this reference, confirm: "Using schema-base + schema-knowledge-work".
+
+---
+
+## Reuse the base — this vertical adds only the gaps
+
+Most of knowledge work is already in the base schema. Use the base labels, do not duplicate them:
+
+- People and orgs: `Person`, `Organization`, `Position`, `Credential`. Reporting lines are the `REPORTS_TO` edge below, not a node.
+- Work: `Task` (a `schema:Action`), `Project`, `Meeting`, `Event`, `Workflow`.
+- Concepts and content: `DefinedTerm` (concepts, skills, glossary, learnings), `Concept`, `Idea`, `CreativeWork`, `KnowledgeDocument` and `Section`.
+
+The gaps this vertical fills are: goals and OKRs, decision records, risk, and the research / citation / evidence layer. It adds those seven labels and nothing else.
+
+---
+
+## Additional Node Types
+
+| Entity | Neo4j Label | Schema.org Type | Required Properties |
+|--------|-------------|-----------------|---------------------|
+| Objective | `Objective` | platform-native | `accountId`, `title`, `framework` (OKR/OGSM/V2MOM/Hoshin), `timeframe`, `status` (draft/active/achieved/missed/abandoned) |
+| KeyResult | `KeyResult` | platform-native | `accountId`, `title`, `target`, `current`, `unit`, `status` (on-track/at-risk/missed/achieved) |
+| Decision | `Decision` | `schema:CreativeWork` | `accountId`, `title`, `status` (proposed/accepted/superseded/rejected), `decision` |
+| Risk | `Risk` | platform-native | `accountId`, `statement`, `probability` (low/medium/high), `impact` (low/medium/high), `status` (open/mitigated/accepted/closed) |
+| Source | `Source` | `schema:CreativeWork` | `accountId`, `title`, `sourceType` (article/book/web/dataset/report) |
+| Finding | `Finding` | platform-native | `accountId`, `statement`, `status` (draft/validated/retracted) |
+| Hypothesis | `Hypothesis` | platform-native | `accountId`, `statement`, `status` (open/supported/refuted/assumed) |
+
+`Objective` carries the strategy framework on a `framework` discriminator rather than proliferating one label per framework: OGSM and V2MOM strategy/method tiers are `Objective` nodes distinguished by `framework`. A North-Star metric is an `Objective`-level `KeyResult`, not a separate label. A `Source` is a referenced work (a citation target), distinct from an ingested `KnowledgeDocument` whose full text lives on disk. An open research question is a `Hypothesis {status:'open'}`; an assumption is a `Hypothesis {status:'assumed'}` — the base `Question` label stays reserved for `schema:Question` FAQ content.
+
+Optional properties seen in practice: `Decision` — `context`, `consequences`, `decidedAt`; `Source` — `url`, `doi`, `datePublished`; `Finding` — `confidence`.
+
+---
+
+## Idempotency contracts
+
+MERGE keys per label:
+
+- `:Objective` — `(accountId, title)`
+- `:KeyResult` — `(accountId, objectiveTitle, title)` — child of the `:Objective` it measures
+- `:Decision` — `(accountId, title)`
+- `:Risk` — `(accountId, statement)`
+- `:Source` — `(accountId, title)`
+- `:Finding` — `(accountId, statement)`
+- `:Hypothesis` — `(accountId, statement)`
+
+---
+
+## Relationship Patterns
+
+```
+(:Objective)-[:MEASURED_BY]->(:KeyResult)
+(:Project)-[:ADVANCES]->(:Objective)
+(:Project)-[:ADVANCES]->(:KeyResult)
+(:Task)-[:ADVANCES]->(:Objective)
+(:Task)-[:ADVANCES]->(:KeyResult)
+(:Decision)-[:SUPERSEDES]->(:Decision)
+(:Risk)-[:THREATENS]->(:Objective)
+(:Risk)-[:THREATENS]->(:Project)
+(:Source)-[:AUTHORED_BY]->(:Person)
+(:Source)-[:CITES]->(:Source)
+(:Source)-[:SUPPORTS]->(:Source)
+(:Source)-[:REFUTES]->(:Source)
+(:Finding)-[:DERIVED_FROM]->(:Source)
+(:Finding)-[:DERIVED_FROM]->(:KnowledgeDocument)
+(:Finding)-[:SUPPORTS]->(:Hypothesis)
+(:Finding)-[:REFUTES]->(:Hypothesis)
+(:Task)-[:DEPENDS_ON]->(:Task)
+(:Person)-[:REPORTS_TO]->(:Person)
+(:Person)-[:RESPONSIBLE_FOR]->(:Task)
+(:Person)-[:ACCOUNTABLE_FOR]->(:Decision)
+```
+
+A `Decision` records what it decided through a `DECIDES` edge to the entity it governs (an `Objective`, a `Project`, a `Task`, or any base entity), and supersedes the decision it replaces. `Source`-to-`Source` citation uses CiTO verbs (`CITES`, `SUPPORTS`, `REFUTES`); a `Finding` is derived from its evidence (`DERIVED_FROM`, the PROV `wasDerivedFrom` relation) and bears on a `Hypothesis` (`SUPPORTS`/`REFUTES`). Task precedence uses `DEPENDS_ON` with an optional `type` property in `{FS, SS, FF, SF}` (the project-management precedence kinds). Responsibility is an edge, never a node: reporting lines are `REPORTS_TO`, and RACI assignment is `RESPONSIBLE_FOR` / `ACCOUNTABLE_FOR` / `CONSULTED_ON` / `INFORMED_OF` from a `Person` to a `Task` or `Decision` — consistent with the base doctrine that responsibility is a property of an edge, not its own node.

package/payload/platform/plugins/memory/references/schema-logistics.md

@@ -0,0 +1,30 @@
+# Schema Reference — Logistics
+
+Vertical schema for `businessType: "logistics"` — couriers, freight, delivery services, fleet operators.
+
+This reference extends the base schema. All base node types remain valid. Load `schema-base.md` first.
+
+When loading this reference, confirm: "Using schema-base + schema-logistics".
+
+---
+
+## Additional Node Types
+
+| Entity | Neo4j Label | Schema.org Type | Required Properties |
+|--------|-------------|-----------------|---------------------|
+| Shipment | `Shipment` | `schema:ParcelDelivery` | `accountId`, `sender` (id), `recipient` (id), `origin` (id), `destination` (id), `status`, `trackingNumber`, `estimatedDelivery` |
+| Vehicle | `Vehicle` | `schema:Vehicle` | `accountId`, `registration`, `type`, `driver` (id), `capacity`, `nextService` |
+| Route | `Route` | `cdm:Activity` | `accountId`, `vehicle` (id), `driver` (id), `date`, `stops`, `startTime`, `endTime` |
+| Stop | `Stop` | `schema:DeliveryEvent` | `accountId`, `route` (id), `address` (id), `shipments`, `arrivalTime`, `signature` |
+
+---
+
+## Relationship Patterns
+
+```
+(:Shipment)-[:CARRIED_ON]->(:Route)
+(:Route)-[:USES_VEHICLE]->(:Vehicle)
+(:Stop)-[:PART_OF_ROUTE]->(:Route)
+(:Stop)-[:AT_ADDRESS]->(:PostalAddress)
+(:Shipment)-[:DELIVERED_TO]->(:Person|Organization)
+```

package/payload/platform/plugins/memory/references/schema-professional-services.md

@@ -0,0 +1,33 @@
+# Schema Reference — Professional Services
+
+Vertical schema for `businessType: "professional-services"` — consultants, agencies, accountants, solicitors, advisors.
+
+This reference extends the base schema. All base node types remain valid. Load `schema-base.md` first.
+
+When loading this reference, confirm: "Using schema-base + schema-professional-services".
+
+---
+
+## Additional Node Types
+
+| Entity | Neo4j Label | Schema.org Type | Required Properties |
+|--------|-------------|-----------------|---------------------|
+| Engagement | `Engagement` | `cdm:Opportunity` | `accountId`, `client` (id), `scope`, `startDate`, `endDate`, `value`, `status` |
+| Retainer | `Retainer` | `schema:Order` (subtype) | `accountId`, `client` (id), `monthlyValue`, `hoursIncluded`, `renewalDate` |
+| Deliverable | `Deliverable` | `schema:DigitalDocument` | `accountId`, `engagement` (id), `name`, `dueDate`, `status`, `version` |
+| TimeEntry | `TimeEntry` | `cdm:Activity` | `accountId`, `engagement` (id), `date`, `hours`, `description`, `billable` |
+
+### Retainer vs base Order
+
+`Retainer` is the professional-services-specific label for recurring service agreements. Use `Retainer` (not `Order`) for ongoing client contracts with monthly billing. One-off project work uses a base `Order` linked to an `Engagement`.
+
+---
+
+## Relationship Patterns
+
+```
+(:Engagement)-[:FOR_CLIENT]->(:Person|Organization)
+(:Deliverable)-[:PART_OF]->(:Engagement)
+(:TimeEntry)-[:LOGGED_AGAINST]->(:Engagement)
+(:Invoice)-[:FOR_ENGAGEMENT]->(:Engagement)
+```

package/payload/platform/plugins/memory/references/schema-retail.md

@@ -0,0 +1,33 @@
+# Schema Reference — Retail
+
+Vertical schema for `businessType: "retail"` — shops, boutiques, online stores, product sellers.
+
+This reference extends the base schema. All base node types remain valid. Load `schema-base.md` first.
+
+When loading this reference, confirm: "Using schema-base + schema-retail".
+
+---
+
+## Additional Node Types
+
+| Entity | Neo4j Label | Schema.org Type | Required Properties |
+|--------|-------------|-----------------|---------------------|
+| Product | `Product` | `schema:Product` | `accountId`, `name`, `sku`, `description`, `price`, `category`, `stockLevel` |
+| StockMovement | `StockMovement` | `cdm:Activity` | `accountId`, `product` (id), `quantity`, `direction` (in/out), `reason`, `date` |
+| PurchaseOrder | `PurchaseOrder` | `schema:Order` (subtype) | `accountId`, `supplier` (id), `lineItems`, `orderDate`, `expectedDelivery`, `orderStatus` |
+| StoreLocation | `StoreLocation` | `schema:Store` | `accountId`, `name`, `address` (id), `openingHours` |
+
+### PurchaseOrder vs base Order
+
+`PurchaseOrder` is the retail-specific label for supplier-facing orders (restocking, procurement). Use `PurchaseOrder` (not `Order`) when ordering from a supplier. Customer-facing orders use the base `Order` label.
+
+---
+
+## Relationship Patterns
+
+```
+(:Order)-[:CONTAINS_PRODUCT]->(:Product)
+(:Product)-[:SUPPLIED_BY]->(:Organization)
+(:StockMovement)-[:AFFECTS]->(:Product)
+(:PurchaseOrder)-[:FROM_SUPPLIER]->(:Organization)
+```

package/payload/platform/plugins/memory/references/schema-trades.md

@@ -0,0 +1,36 @@
+# Schema Reference — Trades
+
+Vertical schema for `businessType: "trades"` — home services, construction, and tradespeople (plumber, electrician, builder, decorator).
+
+This reference extends the base schema. All base node types (Person, Organization, Order, Event, Invoice, Service, etc.) remain valid. Load `schema-base.md` first.
+
+When loading this reference, confirm: "Using schema-base + schema-trades".
+
+---
+
+## Additional Node Types
+
+| Entity | Neo4j Label | Schema.org Type | Required Properties |
+|--------|-------------|-----------------|---------------------|
+| Quote | `Quote` | `schema:Order` + `cdm:Opportunity` | `accountId`, `quoteNumber`, `customer` (id), `lineItems`, `validUntil`, `totalPrice` |
+| SiteVisit | `SiteVisit` | `schema:Event` (subtype) | `accountId`, `address` (id), `engineer` (id), `startDate`, `purpose` |
+| Inspection | `Inspection` | `cdm:Case` (subtype) | `accountId`, `address` (id), `findings`, `recommendations`, `photos` |
+| Certification | `Certification` | `schema:DigitalDocument` | `accountId`, `type` (gas safe, NICEIC, etc.), `issuedDate`, `expiryDate` |
+| Material | `Material` | `schema:Product` | `accountId`, `name`, `sku`, `unitCost`, `supplier` (id) |
+
+### Quote vs base Order
+
+`Quote` is the trades-specific label for estimates and quotes before acceptance. Use `Quote` (not `Order`) when the work is proposed but not yet confirmed. Once a quote is accepted, create a base `Order` node linked to it, or update the Quote's `orderStatus` to reflect acceptance.
+
+---
+
+## Relationship Patterns
+
+```
+(:Order)-[:REQUIRES_VISIT]->(:SiteVisit)
+(:Order)-[:USES_MATERIAL]->(:Material)
+(:SiteVisit)-[:AT_ADDRESS]->(:PostalAddress)
+(:Certification)-[:HELD_BY]->(:Person)
+```
+
+The `(:Certification)-[:HELD_BY]->(:Person)` relationship tracks which staff member holds a trade certification (e.g., Gas Safe, NICEIC, Part P).

package/payload/platform/plugins/memory/references/transcript-formats/circleback.md

@@ -0,0 +1,49 @@
+# Circleback — MCP transcript ingest reference
+
+Companion to [`conversation-archive-mcp`](../../skills/conversation-archive-mcp/SKILL.md). Names the install command, the expected MCP tool surface, the returned shape, and how to map that shape into `memory-ingest` parameters for the conversation-archive writer.
+
+## Install (operator)
+
+Circleback ships a remote streamable-HTTP MCP server at `https://circleback.ai/api/mcp`. Install once per Claude Code host:
+
+```bash
+claude mcp add --transport http circleback https://circleback.ai/api/mcp
+```
+
+Circleback also ships a CLI, but the MCP path is the canonical surface for this skill — the CLI is operator-side only. First invocation opens an OAuth flow in the operator's browser; the operator authorises which meetings Circleback exposes to this Claude Code session. Tokens live in the host, not in maxy.
+
+**Operator-facing verification.** After install, run `/mcp` in admin chat. The expected entry is `circleback — connected` with a tool count > 0. If the entry is missing or shows an error, re-run the install one-liner before invoking the ingest skill.
+
+## Expected tool surface
+
+The skill discovers tools by name pattern at run time. Expected tools (names may drift):
+
+- **List meetings.** Pattern: `mcp__circleback__list_meetings`, `mcp__circleback__search_meetings`, or similar. Accepts a date window and/or text filter; returns an array of meeting objects with at minimum `id`, `title`, `startedAt`, `attendees`.
+- **Fetch a meeting's transcript.** Pattern: `mcp__circleback__get_meeting`, `mcp__circleback__read_meeting`, or similar. Accepts a meeting ID; returns the full meeting including the transcript turns.
+
+If discovered tools diverge, match by description. Run `/mcp` to enumerate the live set.
+
+## Returned shape (typical)
+
+A Circleback meeting object carries the following fields relevant to ingest:
+
+| Circleback field | Maps to memory-ingest |
+|---|---|
+| `id` / `meetingId` | `circlebackMeetingId` (cross-reference property on `:ConversationArchive`) |
+| `title` | `archiveTitle` (prefixed with `"circleback · "` and suffixed with the ISO date) |
+| `startedAt` / `start_time` | `lastIngestedMessageAt` fallback when transcript turns lack per-turn timestamps |
+| `attendees[]` — each with `name`, `email` | Per-attendee resolution against `:AdminUser` / `:Person` (Step 4 of the skill) |
+| `transcript[]` — each with `speaker`, `timestamp`, `text` | Rendered into turn-attributed `[<ISO>] <speaker>: <text>` lines for the typed-section JSON |
+| `calendarEventId` / `event_id` | `calendarEventId` cross-reference property on `:ConversationArchive` when present |
+| `actionItems[]` / `summary` | NOT used for `:Section` rows — provider-authored layers; downstream Phase 2 derivation produces uniform typed claims from the transcript |
+
+## Edge cases
+
+- **Meeting with multiple recording segments** — Circleback occasionally splits a single meeting across two recording sessions (e.g. operator paused recording mid-meeting). The MCP `list_meetings` tool returns them as two distinct meeting IDs. Each ingests as its own `:ConversationArchive`. Cross-segment dedup is not in scope.
+- **Attendee with no email** (Circleback often resolves names from calendar invites but may carry free-text additions): falls through to the per-attendee prompt loop.
+- **Redacted transcripts** — Circleback supports operator-side redaction. Redacted spans render as `[REDACTED]` in the turn text; the skill writes them as-is. The downstream classifier treats them as ordinary tokens.
+
+## What this reference is not
+
+- Not a Circleback API or CLI reference. The MCP surface is the contract for this skill.
+- Not a token manager. OAuth is in the host.

package/payload/platform/plugins/memory/references/transcript-formats/granola.md

@@ -0,0 +1,50 @@
+# Granola — MCP transcript ingest reference
+
+Companion to [`conversation-archive-mcp`](../../skills/conversation-archive-mcp/SKILL.md). Names the install command, the expected MCP tool surface, the returned shape, and how to map that shape into `memory-ingest` parameters for the conversation-archive writer.
+
+## Install (operator)
+
+Granola ships a remote streamable-HTTP MCP server. Install once per Claude Code host:
+
+```bash
+claude mcp add --transport http granola <granola-mcp-url>
+```
+
+Granola's docs live at https://docs.granola.ai/help-center/sharing/integrations/mcp — read the linked page for the current MCP URL and any auth pre-step. First invocation opens an OAuth flow in the operator's browser; the operator authorises which notebooks / meetings Granola exposes to this Claude Code session. Tokens live in the host, not in maxy.
+
+**Operator-facing verification.** After install, run `/mcp` in admin chat. The expected entry is `granola — connected` with a tool count > 0. If the entry is missing or shows an error, re-run the install one-liner before invoking the ingest skill.
+
+## Expected tool surface
+
+The skill discovers tools by name pattern at run time. Expected tools (names may drift across vendor doc revisions — run `/mcp` to confirm the live set):
+
+- **List meetings / notes.** Pattern: `mcp__granola__list_notes`, `mcp__granola__search_notes`, or similar. Accepts a date window and/or text filter; returns an array of note objects with at minimum `id`, `title`, `createdAt`, `attendees`.
+- **Fetch a single note's transcript.** Pattern: `mcp__granola__get_note`, `mcp__granola__read_note`, or similar. Accepts a note ID; returns the full note object including the transcript turns.
+
+If the discovered tools diverge from these patterns, prefer matching by description over matching by name (the host exposes each tool's description). If two tools could plausibly serve "list meetings", surface the disambiguation to the operator rather than guessing.
+
+## Returned shape (typical)
+
+A Granola note object carries the following fields relevant to ingest:
+
+| Granola field | Maps to memory-ingest |
+|---|---|
+| `id` | `granolaNoteId` (cross-reference property on `:ConversationArchive`) |
+| `title` | `archiveTitle` (prefixed with `"granola · "` and suffixed with the ISO date) |
+| `createdAt` / `meetingStartTime` | `lastIngestedMessageAt` fallback when transcript turns lack per-turn timestamps |
+| `attendees[]` — each with `displayName`, `email` | Per-attendee resolution against `:AdminUser` / `:Person` (Step 4 of the skill) |
+| `transcript[]` — each with `speaker`, `startTime`, `text` | Rendered into turn-attributed `[<ISO>] <speaker>: <text>` lines for the typed-section JSON |
+| `calendarEventId` / `googleCalendarEventId` / `outlookEventId` | `calendarEventId` cross-reference property on `:ConversationArchive` (whichever provider field is populated; normalise to one property) |
+| `summary` / `aiSummary` | NOT used for `:Section` summaries — the in-turn classifier produces section summaries from the transcript itself; Granola's AI summary is provider-authored and would bias the chunking |
+
+## Edge cases
+
+- **Note exists but transcript is empty** (the operator joined the meeting but Granola did not record): FAIL for that meeting with `phase=fetch reason="granola note <id> has empty transcript"`. The empty parent is not written.
+- **Attendee with no email** (operator added a free-text name to a Granola attendee list): falls through to the per-attendee prompt loop. The operator picks an existing `:Person` or blocks.
+- **Continuation lines** (Granola occasionally emits multi-line transcript entries with embedded newlines): collapse internal newlines to spaces; one transcript entry = one rendered line.
+- **Retention** — Granola retains notes per the operator's plan. If a note returned by `list_notes` cannot be fetched via `get_note` (404), surface the provider error verbatim and continue with the next note.
+
+## What this reference is not
+
+- Not a Granola API reference. The MCP surface is the contract — this doc only covers the fields the ingest skill consumes. If Granola adds new tools or fields the skill should use, edit this doc and the skill in the same commit.
+- Not a token manager. The OAuth dance is entirely in Claude Code's MCP host; maxy never sees a Granola token.

package/payload/platform/plugins/memory/references/transcript-formats/otter.md

@@ -0,0 +1,50 @@
+# Otter — MCP transcript ingest reference
+
+Companion to [`conversation-archive-mcp`](../../skills/conversation-archive-mcp/SKILL.md). Names the install command, the expected MCP tool surface, the returned shape, and how to map that shape into `memory-ingest` parameters for the conversation-archive writer.
+
+## Install (operator)
+
+Otter ships a remote streamable-HTTP MCP server at `https://mcp.otter.ai/mcp`. Install once per Claude Code host:
+
+```bash
+claude mcp add --transport http otter https://mcp.otter.ai/mcp
+```
+
+Confirm the current URL against Otter's documentation before relying on this one-liner. First invocation opens an OAuth flow in the operator's browser; the operator authorises which conversations Otter exposes to this Claude Code session. Tokens live in the host, not in maxy.
+
+**Operator-facing verification.** After install, run `/mcp` in admin chat. The expected entry is `otter — connected` with a tool count > 0. If the entry is missing or shows an error, re-run the install one-liner before invoking the ingest skill.
+
+## Expected tool surface
+
+The skill discovers tools by name pattern at run time. Expected tools (names may drift):
+
+- **List conversations.** Pattern: `mcp__otter__list_conversations`, `mcp__otter__search_conversations`, or similar. Accepts a date window and/or text/keyword filter; returns an array of conversation objects with at minimum `id`, `title`, `startTime`, `participants`.
+- **Fetch a conversation's transcript.** Pattern: `mcp__otter__get_conversation`, `mcp__otter__read_transcript`, or similar. Accepts a conversation ID; returns the full conversation including the transcript turns.
+
+If the discovered tools diverge, match by description over name. Run `/mcp` to enumerate the live set when in doubt.
+
+## Returned shape (typical)
+
+An Otter conversation object carries the following fields relevant to ingest:
+
+| Otter field | Maps to memory-ingest |
+|---|---|
+| `id` / `speech_id` | `otterConversationId` (cross-reference property on `:ConversationArchive`) |
+| `title` | `archiveTitle` (prefixed with `"otter · "` and suffixed with the ISO date) |
+| `startTime` / `start_time` | `lastIngestedMessageAt` fallback when transcript turns lack per-turn timestamps |
+| `participants[]` — each with `name`, `email` | Per-attendee resolution against `:AdminUser` / `:Person` (Step 4 of the skill) |
+| `transcript[]` / `utterances[]` — each with `speaker`, `start`, `text` | Rendered into turn-attributed `[<ISO>] <speaker>: <text>` lines for the typed-section JSON |
+| `calendarEventId` / `meeting_event_id` | `calendarEventId` cross-reference property on `:ConversationArchive` when present (Otter does not always populate it — only for meetings imported from a connected calendar) |
+| `summary` / `outline` | NOT used for `:Section` summaries — the in-turn classifier produces them from the transcript |
+
+## Edge cases
+
+- **Speaker labels are pseudonymous** ("Speaker 1", "Speaker 2") when Otter could not identify a participant. Surface them to the operator at attendee-resolution time — the operator either matches "Speaker 1" to a known `:Person` (because they recognise the meeting) or blocks the attendee.
+- **Live in-progress conversations** — Otter may expose a conversation that is still being transcribed. Skip these: the skill only ingests finished recordings. Detect by checking the provider's `status` / `is_live` field when present and FAIL with `phase=fetch reason="otter conversation <id> still in progress"`.
+- **Attendee with no email** (free-text participant added in Otter): falls through to the per-attendee prompt loop.
+- **Highlights / action items** in Otter's UI are provider-authored layers; do not ingest them as separate `:Section` rows. The transcript text is the source of truth; downstream Phase 2 derivation produces typed claims uniformly across sources.
+
+## What this reference is not
+
+- Not an Otter API reference. The MCP surface is the contract.
+- Not a token manager. OAuth is in the host.