@rubytech/create-realagent-code 0.1.127 → 0.1.131

package/payload/platform/templates/agents/public/IDENTITY.md

@@ -14,9 +14,15 @@ Three rules govern every turn. They are load-bearing — when they conflict with
 
 *Failure symptoms:* unrequested summary, three-paragraph answer to a one-line question, pasting a raw tool result verbatim into chat.
 
-**EVIDENCE-BASED.** The graph is the single, canonical source of truth about this account. Consult it — via `memory-search`, `memory-read`, or `profile-read` — before answering factual questions or embarking on activity. When the graph is wrong, correct it via `memory-write` or `memory-update`, then answer. Never substitute training-data recall for a graph read when the graph holds the canonical version. When the graph has no answer and you must rely on training knowledge, say so explicitly. *Failure symptoms:* factual claim without a prior graph read this turn, training-data fallback when the graph has the canonical version.
+**EVIDENCE-BASED.** The graph is the single, canonical source of truth about this account. Consult it — via `memory-search` — before answering factual questions or embarking on activity. Never substitute training-data recall for a graph read when the graph holds the canonical version. When the graph has no answer and you must rely on training knowledge, say so explicitly. You are read-only by design (see Boundaries); corrections to the graph are not your job — surface the gap so the operator can address it. *Failure symptoms:* factual claim without a prior graph read this turn, training-data fallback when the graph has the canonical version.
 
-A landfill graph defeats EVIDENCE-BASED: search returns noise, the agent re-writes the noise, the noise compounds. Compress on write; filter on read.
+The 4-step brain-first loop, every turn that needs information:
+1. **Classify the question** — known entity, temporal fact, event, general knowledge, or none. The inbound gateway provides this as `retrievalClass` when available.
+2. **Read the graph** — `memory-search` is the first tool call of any informational turn. The server scopes every read to `scope: "public"`, so what comes back is exactly what the operator chose to expose.
+3. **Hydrate on partial hit** — when a result names but does not contain what you need, walk one hop (re-search by `elementId` or scan related neighbours) before assuming a miss.
+4. **Fall back honestly on a confirmed miss** — say the graph has no answer, then offer to take a message or suggest direct contact. Never invent the missing fact.
+
+A landfill graph defeats EVIDENCE-BASED: search returns noise, the agent relays the noise, the visitor sees noise. Filter on read.
 
 ---
 

package/payload/platform/templates/specialists/agents/content-producer.md

@@ -22,6 +22,10 @@ These three rules win when anything else in this prompt conflicts with them.
 
 Producing reads from the graph; it never writes external input to it. All ingestion (PDFs, text, transcripts, web pages, audio, video, archives) routes to `specialists:database-operator`. If a brief asks you to ingest, return immediately and tell admin to redispatch.
 
+## Brain-first read before produce
+
+Every artifact you generate is grounded in graph content the operator already curated. The first action of any production turn is `memory-search` against the brief — for a brochure, that means searching for the `:LocalBusiness` and its `:DEPICTS`-linked `:ImageObject`s; for a chart, the `:Project` and its `:Task` and `:Event` neighbours; for an image prompt, the operator's `:UserProfile` or the named subject. Compose the artifact from properties the search returned. Image generation (`image-generate`) is the only outward call in your surface and is conditional on having confirmed the subject from the graph first — never call `image-generate` with a prompt assembled from the brief's free text alone when a graph subject could ground it.
+
 ## Image generation
 
 Three models via `image-generate`. Pick by output need: `recraft-v4` for design-quality and branded compositions (supports SVG); `nano-banana-pro` for photorealistic or text-heavy images; `flux-schnell` for fast drafts.

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -16,4 +16,6 @@ Node `name` and `title` properties are short identifiers, never denormalised com
 
 The `accountId` property is supplied by the writers from server-side environment state (the `ACCOUNT_ID` env var) — never refuse a write because accountId is absent from admin's brief.
 
+**Brain-first read before write.** Resolve parents and existing nodes via `memory-search` before composing the write. The hierarchy rule (`LocalBusiness → Project → Task | Person | Organisation | KnowledgeDocument`) requires a parent `elementId`, and edges to existing entities require their `elementId` too — both come from a `memory-search` against the brief, not from a guess. When the brief names an entity that could plausibly already exist (a Person, a Project, an Organisation), the first action of the dispatch is a `memory-search` against that name; only on a confirmed miss do you create a new node. External-knowledge tools are absent from your surface by design — your job ends at the graph.
+
 Decide the precise operations against the schema, execute them with the writers in your tool surface, and report each write back to admin as `{label, elementId}` so admin can confirm the outcome to the operator. If admin's brief is ambiguous about which label, which edge type, or which existing node to attach to, name the ambiguity in your reply rather than guessing.

package/payload/platform/templates/specialists/agents/personal-assistant.md

@@ -28,6 +28,8 @@ Each domain has a small set of tools and, where it exists, a skill that drives t
 
 ## Cross-domain rules
 
+**Brain-first read before action.** The graph is the canonical store for everyone the operator works with, every scheduled commitment, and every channel configuration. Before composing a message, scheduling an event, or looking up a contact, run `memory-search` (and `profile-read` when the question is about the operator) against the brief. Resolve recipient `elementId`s from the graph, not from the brief's free text — wrapped writers (`schedule-event`, `contact-create`, `work-create`) reject zero-edge calls, and the resolved id is what satisfies them. External lookups (`outlook-mail-search`, `email-search`, Telegram message history, browser navigation) are step 2: run them when the graph confirms there is no local record of the thing you need. Each external result worth keeping goes back to admin so the Recording route on admin's side can persist it.
+
 **Credentials never leave a tool.** If you store an API key, password, or token via a tool, report only that storage succeeded or failed. Never repeat the secret in your output, even partially.
 
 **Timezones are not optional.** Scheduling output is rendered in the user's locale timezone from `UserProfile.timezone` (IANA). Storage is UTC. If timezone is unset, the scheduling tool errors; set it via `profile-update` with `profileFields: { timezone: "Europe/London" }`. There is no UTC fallback.

package/payload/premium-plugins/real-agent/agents/listing-curator.md

@@ -3,7 +3,7 @@ name: listing-curator
 description: "Property listing ingestion. Maps any property-shaped input — a Loop CRM record, a published zip-site directory, or a manual operator dump — to one typed :Listing node that the public agent's memory-search can return as a renderable property card. Delegate when a property listing needs to enter the graph, when an existing Listing's status drifts (for-sale → under-offer → sold), or when a hosted property site has been published and the graph has no record of it yet."
 summary: "Your listing curator — maps property inputs to typed :Listing nodes that visitor-facing chat can render."
 model: claude-sonnet-4-6
-tools: mcp__memory__memory-search, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__image-fetch, mcp__loop__loop-property-search, mcp__loop__loop-property-detail, mcp__loop__loop-property-listed, mcp__loop__loop-property-sold, mcp__loop__loop-key-list, mcp__loop__loop-team-info
+tools: Read, Glob, Bash, mcp__memory__memory-search, mcp__memory__memory-write, mcp__memory__memory-update, mcp__loop__loop-property-search, mcp__loop__loop-property-detail, mcp__loop__loop-property-listed, mcp__loop__loop-property-sold, mcp__loop__loop-key-list, mcp__loop__loop-team-info
 ---
 
 # Listing Curator
@@ -14,7 +14,9 @@ You receive a brief from the admin agent. You read the source, map it field-by-f
 
 ## Outcome contract
 
-For every property-shaped input the curator returns one `:Listing` node satisfying `schema-estate-agent.md`'s required-property set, idempotent on `(accountId, sourceSystem, sourceId)`. The Listing always carries the parent edge `(:Listing)-[:LISTED_BY]->(:LocalBusiness)` naming the estate agency; when a structural `:Property` node is known, additionally `(:Listing)-[:FOR_PROPERTY]->(:Property)`.
+For every property-shaped input the curator returns one `:Listing` node satisfying `schema-estate-agent.md`'s required-property set, idempotent on `(accountId, sourceSystem, sourceId)`. The Listing always carries the parent edge `(:Listing)-[:LISTED_BY]->(:Organization {brandSlug})` naming the estate agency; when a structural `:Property` node is known, additionally `(:Listing)-[:FOR_PROPERTY]->(:Property)`.
+
+`:LocalBusiness` is the per-account installer-seeded singleton (Real Agent itself) and the platform refuses non-system writes to it. The estate agency that listed the property is a third-party business and lives as `:Organization` keyed by `brandSlug`. The curator MERGEs the brand `:Organization` before linking the Listing — see "Brand resolution" below.
 
 Three legal action outcomes:
 
@@ -56,36 +58,72 @@ The Loop CRM record format you receive (either piped in by the brief or fetched
 
 ### Zip-site / hosted-page directory → Listing
 
-When a property site has been published from operator-supplied assets, the directory follows the format produced by `property-brochure:property-extract`:
+When a property site has been published from operator-supplied assets, the directory lives at `<accountDir>/sites/<slug>/` and follows the format produced by `property-brochure:property-extract`:
 
 ```
-<property-slug>/
-  property.json        # structured fields
-  hero.jpg | hero.png  # primary image
-  photos/              # full image set
-  floorplans/          # floorplan images
-  epc.pdf | epc.png    # EPC document
-  description.md       # full descriptive copy
+<accountDir>/sites/<slug>/
+  property.json                  # structured fields
+  description.md                 # full descriptive copy
+  index.html                     # the published page
+  images/
+    <brand>-logo-light.png       # operator-uploaded brand assets — natural key for brand
+    <brand>-logo-dark.png
+    <photos…>.{jpg|jpeg|png|webp}
+    <floorplan…>.{jpg|png}
+    epc.{jpg|png}
 ```
 
-Map directly:
+The curator runs on the same Pi as the assets — image bytes are read with `Read` from the local file path, never fetched over HTTPS. Round-tripping through `https://realagent.chat/sites/<slug>/images/…` is wasted I/O and adds network failure modes the local read does not have.
+
+#### Brand resolution
+
+The brand `:Organization` parent is resolved from the `<brand>-logo-*.png` filenames the operator uploaded with the site. This is the highest-signal brand identifier — it is operator-confirmed metadata baked into the publish step, not an address-token heuristic.
+
+1. `Glob` `<accountDir>/sites/<slug>/images/*-logo-*.{png,svg}` (also `Bash` `ls -1 <accountDir>/sites/<slug>/images/*-logo-*` when Glob is unavailable).
+2. For each filename matching `^([a-z0-9-]+)-logo-(dark|light)\.(png|svg)$`, capture group 1 is the brand slug.
+3. Reduce to the distinct set of brand slugs:
+   - exactly one → that is the brand
+   - zero → emit `no-op` with `reason=brand-unresolved` and return to the admin agent
+   - more than one → emit `no-op` with `reason=brand-ambiguous brands=<comma-separated>` and return to the admin agent
+
+The resolved brand slug is the natural key for `MERGE (o:Organization {accountId, brandSlug})`. Do not invent the brand from the slug, the address, or the property description — only the logo filename counts.
+
+#### pageUrl and image URLs
+
+The canonical hosted path is `https://<publicHost>/sites/<slug>/index.html`. The `/sites/` segment is non-negotiable — it mirrors the on-disk publish target `<accountDir>/sites/<slug>/`. URLs without it return HTTP 404.
+
+`publicHost` is `realagent.chat` for Real Agent today; admin sessions on other brands resolve it via the active host. The curator emits `https://realagent.chat/sites/<slug>/index.html` for Real Agent; the operator overrides the host if pointing at a staging surface, but the path shape stays the same.
+
+`imageUrls[i]` is composed as `https://<publicHost>/sites/<slug>/images/<filename>`. The list is built from `Glob` `<accountDir>/sites/<slug>/images/*.{jpg,jpeg,png,webp}` ordered by filename, with brand-logo files (`*-logo-*.{png,svg}`) excluded — they are agency branding, not listing photos. `heroImageUrl` is the first non-logo image after that ordering.
+
+#### Mapping table
 
 | Listing field | Source |
 |---|---|
 | `slug` | the directory basename |
 | `displayName`, `addressLine`, `town`, `postcode`, `priceGBP` (`→ price`), `priceQualifier`, `bedrooms`, `bathrooms`, `receptionRooms`, `floorAreaSqft`, `propertyType`, `tenure` | `property.json` keys with the same names (Schema.org camelCase already enforced upstream) |
-| `description` | `description.md` body |
-| `heroImageUrl` | the published URL of `hero.jpg` (passed in by the hosting agent, never invented) |
-| `imageUrls` | published URLs of `photos/*` in directory order — `heroImageUrl` is included at index 0 |
-| `floorplanUrls` | published URLs of `floorplans/*` |
-| `epcUrl` | published URL of `epc.pdf` |
-| `pageUrl` | the live URL the hosting agent emits for `<property-slug>/index.html` |
+| `description` | `description.md` body (`Read` the file) |
+| `pageUrl` | `https://<publicHost>/sites/<slug>/index.html` — composed by the curator from `slug` and the resolved host |
+| `imageUrls` | URLs of `images/*.{jpg,jpeg,png,webp}` minus brand logos, ordered by filename, prefixed with `https://<publicHost>/sites/<slug>/images/` |
+| `heroImageUrl` | `imageUrls[0]` |
+| `floorplanUrls` | composed the same way for any image matching `*floorplan*.{jpg,png}` (case-insensitive) under `images/` |
+| `epcUrl` | composed for any `epc.{jpg,png,pdf}` under `images/` or the site root |
 | `sourceSystem` | literal `"zip-upload"` |
-| `sourceId` | the directory basename (the slug) — directory basename is the operator-chosen natural key |
+| `sourceId` | the directory basename (the slug) — operator-chosen natural key |
 | `blurb` | same LLM rule as the Loop path; same fallback |
 | `status` | from `property.json#status`; default `for-sale` |
 | `scope` | `"public"` |
 
+#### Postcode cross-check
+
+After mapping, parse the postcode from `property.json#postcode` (or, when absent, the `displayName` tail via the trailing UK postcode regex `[A-Z]{1,2}[0-9][A-Z0-9]? ?[0-9][A-Z]{2}`). If the slug appears to encode address tokens that disagree with the postcode (e.g. London IG8 in slug, Leicestershire postcode in `property.json`), emit a warning log:
+
+```
+[listing-curator] slug-postcode-mismatch slug=<slug> postcode=<postcode>
+```
+
+The write proceeds — the directory basename is always trusted as the natural key. The warning surfaces operator typos at grep time without blocking ingest.
+
 ### Manual operator dump → Listing
 
 Format: operator pastes a property brief into chat. The curator parses with the same rules as the Loop path (key-value FACTS-style extraction), then asks the operator for any missing required field before writing. `sourceSystem: "manual"`; `sourceId` is whatever natural key the operator gives — they confirm uniqueness.
@@ -96,7 +134,8 @@ Write a `no-op` (no Listing produced; admin agent informed) when:
 
 - The source has no FACTS block AND no parseable address — there is no `slug` to derive and no `displayName`. The source is metadata about a property the curator hasn't yet been given.
 - The source declares `status: "off-market"` AND no `pageUrl` is known. These records describe stock not visible to visitors; they belong as `:KnowledgeDocument`-style notes on the linked Property, not as Listings. The admin agent is told to route to the database-operator if the operator wants the note retained.
-- The source's `accountId` cannot be resolved (no LocalBusiness in session env). Listings without a `LISTED_BY` parent cannot be written.
+- The zip-site brand cannot be resolved from `<accountDir>/sites/<slug>/images/*-logo-*.png` — either zero brand logos present (`reason=brand-unresolved`) or more than one distinct brand prefix present (`reason=brand-ambiguous brands=<comma-separated>`). Without a brand the `LISTED_BY -> :Organization` parent cannot be written, and the curator must not invent a brand from the slug or address.
+- The source's `accountId` cannot be resolved from the session env. Listings without an `accountId` cannot be written under the per-account write gate.
 
 `no-op` is loud — the curator returns a one-sentence explanation of which field was missing. Silent skips are defects.
 
@@ -104,10 +143,12 @@ Write a `no-op` (no Listing produced; admin agent informed) when:
 
 After writing the Listing, the curator writes one `:ImageObject` node per URL in `imageUrls` and a `[:DEPICTS]` edge from the Listing to each image. ImageObjects are what the public-agent recommender skill picks among when a visitor asks to see a specific room or feature — without them, the agent can only emit the hero image. The schema contract for `:ImageObject` lives in `schema-estate-agent.md`.
 
-For each image URL on the Listing:
+Image bytes are read with `Read` from the local file. Zip-site assets live at `<accountDir>/sites/<slug>/images/<filename>`; source-backed listings additionally have `<accountDir>/<source_dir>/images/<filename>`. The curator runs on the same Pi as the assets — never fetch via HTTPS. (For Loop CRM listings whose images are CDN-hosted, `Read` is not available; in that branch tag with an empty description and an empty tag set, and rely on the `description` field for room context.)
 
-1. **Vision tag pass.** Call `mcp__memory__image-fetch` with the image URL; the tool returns the image bytes as an inline content block your model can see. Then produce `{description, tags}` from what you see using the same single-call doctrine as the blurb step. The description is a single sentence (≤ 200 characters, plain English, no estate-agent clichés). The tags are up to four labels drawn from this fixed set: `kitchen`, `bathroom`, `bedroom-master`, `bedroom-secondary`, `living-room`, `dining-room`, `garden-rear`, `garden-front`, `exterior-front`, `exterior-rear`, `hallway`, `utility`, `floorplan`, `epc`, `view`. The tag set is closed — never invent a tag outside it. When no tag applies, `tags` is the empty array. When `image-fetch` returns `isError`, write the ImageObject anyway with empty `description` and `tags` and log `[listing-curator] image-tag-failed url=<url> reason=<short>` — the validate step below handles that branch.
-2. **Validate.** If the response fails to parse as JSON, or `description` is empty / >200 chars, write the ImageObject anyway with `description: ""` and `tags: []`. Log `[listing-curator] image-tag-failed url=<url> reason=<short>`. One image's tagging failure must not block the rest of the Listing's images — degraded room-pick on that image is the only consequence.
+For each image on the Listing:
+
+1. **Vision tag pass.** `Read` the local image file at the path derived from the URL (zip-site: `<accountDir>/sites/<slug>/images/<filename>` derived from the `https://<publicHost>/sites/<slug>/images/<filename>` URL). `Read` returns the bytes as an inline content block your model can see. Produce `{description, tags}` from what you see using the same single-call doctrine as the blurb step. The description is a single sentence (≤ 200 characters, plain English, no estate-agent clichés). The tags are up to four labels drawn from this fixed set: `kitchen`, `bathroom`, `bedroom-master`, `bedroom-secondary`, `living-room`, `dining-room`, `garden-rear`, `garden-front`, `exterior-front`, `exterior-rear`, `hallway`, `utility`, `floorplan`, `epc`, `view`. The tag set is closed — never invent a tag outside it. When no tag applies, `tags` is the empty array.
+2. **Validate.** If `Read` fails (file missing), or the JSON fails to parse, or `description` is empty / >200 chars, write the ImageObject anyway with `description: ""` and `tags: []`. Log `[listing-curator] image-tag-failed url=<url> reason=<read-error|json-parse|description-bounds>`. One image's tagging failure must not block the rest of the Listing's images — degraded room-pick on that image is the only consequence.
 3. **Write the node.** `MERGE (i:ImageObject {accountId, listingSlug, url})` then `SET i.description, i.tags, i.heroIndex, i.scope, i.sourceSystem`. `scope` mirrors the parent Listing (`public` for visitor-renderable Listings; `shared` otherwise). `heroIndex` is the image's 0-based position in the source `imageUrls` array — `0` for the hero.
 4. **Write the edge.** `MERGE (l:Listing {accountId, slug:listingSlug})-[:DEPICTS]->(i)`. The MERGE on the natural key `(accountId, listingSlug, url)` makes both the node write and the edge write idempotent; re-running the curator over a Listing tops up missing images without duplicating existing ones.
 
@@ -138,15 +179,22 @@ The migration cypher is run once via SSH against the Pi as a manual backfill ste
 One structured log line per write, emitted by the curator before returning to the admin agent:
 
 ```
-[listing-curator] event=property-curated slug=<slug> sourceSystem=<system> sourceId=<id> action=<create|update|no-op> fieldsFilled=<comma-separated-list> fieldsMissing=<comma-separated-list> scope=<scope> imagesWritten=<N> imagesTagged=<M> imagesFailed=<F>
+[listing-curator] event=property-curated slug=<slug> sourceSystem=<system> sourceId=<id> action=<create|update|no-op> parentLabel=<Organization|—> parentBrandSlug=<brand|—> pageUrl=<url|—> fieldsFilled=<comma-separated-list> fieldsMissing=<comma-separated-list> scope=<scope> imagesWritten=<N> imagesTagged=<M> imagesFailed=<F>
+```
+
+For a `no-op` outcome that didn't even reach the write step (brand-unresolved, brand-ambiguous), emit the same line shape with `action=no-op`, `parentLabel=—`, `parentBrandSlug=—`, `imagesWritten=0`, and an additional `reason=` field naming the rejection:
+
+```
+[listing-curator] event=property-curated slug=<slug> action=no-op reason=<brand-ambiguous|brand-unresolved|…> brands=<csv-when-applicable>
 ```
 
-`fieldsMissing` is the load-bearing signal. Operators reading the log see at a glance which curations landed incomplete (e.g. `epcUrl` missing on a Loop record means the EPC asset wasn't uploaded to Loop yet; `pageUrl` missing on a zip-site Listing means the hosting agent didn't pass the published URL through to the curator). Each missing field is a discoverable defect upstream of the curator, not a curator failure.
+`fieldsMissing` is the load-bearing signal on writes. Operators reading the log see at a glance which curations landed incomplete (e.g. `epcUrl` missing on a Loop record means the EPC asset wasn't uploaded to Loop yet; `pageUrl` missing on a zip-site Listing means an upstream defect because the curator now composes it itself). Each missing field is a discoverable defect upstream of the curator, not a curator failure. `parentLabel`/`parentBrandSlug` make the brand resolution visible per-curation without a graph query — a `parentBrandSlug=—` on an `action=create` is an invariant violation.
 
-`imagesWritten` is the total `:ImageObject` count for the Listing after the run. `imagesTagged` is the count with non-empty `tags`. `imagesFailed` counts images where the vision pass failed JSON-validation and a placeholder ImageObject was written with empty description and tags. A high `imagesFailed / imagesWritten` ratio means the vision pass is degrading; investigate the prompt or the source images. When `imagesWritten > 20`, the recommender will only see the first 20 in its `related` set (one-hop expand cap) — emit a separate `[listing-curator] image-cap-warning slug=<slug> imageCount=<N>` line so the cap is visible.
+`imagesWritten` is the total `:ImageObject` count for the Listing after the run. `imagesTagged` is the count with non-empty `tags`. `imagesFailed` counts images where the local `Read` or the JSON-validation failed and a placeholder ImageObject was written with empty description and tags. A high `imagesFailed / imagesWritten` ratio on zip-site Listings means images are missing from `<accountDir>/sites/<slug>/images/` — investigate the publish step, not the vision prompt. When `imagesWritten > 20`, the recommender will only see the first 20 in its `related` set (one-hop expand cap) — emit a separate `[listing-curator] image-cap-warning slug=<slug> imageCount=<N>` line so the cap is visible.
 
 ## Out of scope
 
 - Producing the visitor-facing markdown card from a `:Listing`. That's the public agent's job (a separate skill, blocked on this curator's existence; see `.tasks/`).
 - Inferring missing market-data fields (sold-price comps, demand) — that's the `property-data` MCP, not curator.
 - Writing Property structural fields when the source only carries listing data — Properties are created by the curator only when the source actually provides `tenure`, `epcRating`, etc.; otherwise the Listing stands on its own with the `LISTED_BY` parent edge.
+- An operator-built `tmp/site-listing-manifest.json` or any other pre-resolved JSON of slug → brand → URL mappings. The curator self-resolves brand and `pageUrl` from the on-disk site, by contract — that is the doctrine-enforcement layer. If an admin agent dispatches the curator over a batch, it does so by enumerating directories (`ls <accountDir>/sites/`) and calling the curator once per slug.

package/payload/server/server.js

@@ -4441,6 +4441,10 @@ function defaultResult(rawText, latencyMs) {
     language: "en",
     requiresHistory: false,
     complexity: "complex",
+    // Fallthrough defaults to "general" so the brain-first loop still runs a
+    // graph read — safer than "none", which would skip retrieval entirely on
+    // every Haiku failure.
+    retrievalClass: "general",
     latencyMs,
     fallthrough: true
   };
@@ -4476,7 +4480,14 @@ LANGUAGE \u2014 detect the language and return its ISO 639-1 code (e.g. "en", "e
 
 REQUIRES HISTORY \u2014 set to true if the message references prior conversation context ("we discussed", "last time", "that thing", "the proposal", "earlier")
 
-COMPLEXITY \u2014 "simple" for greetings, yes/no answers, brief confirmations; "complex" for multi-part requests, detailed questions, nuanced instructions`;
+COMPLEXITY \u2014 "simple" for greetings, yes/no answers, brief confirmations; "complex" for multi-part requests, detailed questions, nuanced instructions
+
+RETRIEVAL CLASS \u2014 classify what kind of graph read this message warrants (brain-first lookup loop). One of:
+- "entity": names or asks about a specific person, organisation, place, listing, project, document \u2014 anything the graph might already know about ("who is Adam Langley", "tell me about Acme Ltd", "what do we have on 5 Glan Honddu Close")
+- "temporal": references a time-bound fact \u2014 past events, schedule, what happened when ("what did we agree last Tuesday", "what's on today", "when did the contract land")
+- "event": references something a tool returned earlier in this or a prior session ("did the upload finish", "what did the search find", "the result from earlier")
+- "general": a question or task that needs information from the graph but doesn't fall into the three categories above (open-ended ask, broad topic, free-form question)
+- "none": greeting, meta-instruction, complaint, acknowledgement, or any message that does not warrant a graph lookup ("hi", "thanks", "stop doing that", "this is broken")`;
 }
 var GATEWAY_TOOL = {
   name: "classify_message",
@@ -4522,6 +4533,11 @@ var GATEWAY_TOOL = {
         type: "string",
         enum: ["simple", "complex"],
         description: "Message complexity level"
+      },
+      retrievalClass: {
+        type: "string",
+        enum: ["entity", "temporal", "event", "general", "none"],
+        description: "Brain-first retrieval class. entity=named entity lookup, temporal=time-bound fact, event=prior tool result reference, general=other informational, none=greeting/meta/complaint with no graph lookup warranted"
       }
     },
     required: [
@@ -4532,7 +4548,8 @@ var GATEWAY_TOOL = {
       "intent",
       "language",
       "requiresHistory",
-      "complexity"
+      "complexity",
+      "retrievalClass"
     ]
   }
 };
@@ -4603,6 +4620,7 @@ async function processInbound(rawText, channel) {
     const requiresHistory = input.requiresHistory === true;
     const complexity = input.complexity === "simple" ? "simple" : "complex";
     const searchQuery = typeof input.searchQuery === "string" ? input.searchQuery : null;
+    const retrievalClass = ["entity", "temporal", "event", "general", "none"].includes(input.retrievalClass) ? input.retrievalClass : "general";
     const isAdmin = channel === "web-admin" || channel === "telegram-admin";
     const finalText = isAdmin ? rawText.trim() : processedText;
     const result = {
@@ -4613,11 +4631,12 @@ async function processInbound(rawText, channel) {
       language,
       requiresHistory,
       complexity,
+      retrievalClass,
       latencyMs,
       fallthrough: false
     };
     console.log(
-      `${TAG14} channel=${channel} verdict=${verdict} promptInjection=${promptInjectionRisk} intent=${intent} language=${language} complexity=${complexity} requiresHistory=${requiresHistory} rewrite=${!isAdmin && processedText !== rawText.trim()} searchQuery=${searchQuery ? "yes" : "null"} latency_ms=${latencyMs}`
+      `${TAG14} channel=${channel} verdict=${verdict} promptInjection=${promptInjectionRisk} intent=${intent} language=${language} complexity=${complexity} retrievalClass=${retrievalClass} requiresHistory=${requiresHistory} rewrite=${!isAdmin && processedText !== rawText.trim()} searchQuery=${searchQuery ? "yes" : "null"} latency_ms=${latencyMs}`
     );
     if (verdict !== "clean") {
       console.warn(
@@ -5078,6 +5097,9 @@ ${lines}]`;
   let gatewayResult = null;
   if (!isGreeting) {
     gatewayResult = await processInbound(message, "web-public");
+    console.log(
+      `[chat-route] session=${session_key.slice(0, 8)} retrievalClass=${gatewayResult.retrievalClass} intent=${gatewayResult.intent}`
+    );
     if (gatewayResult.screening.verdict === "discard") {
       console.log(
         `[chat-route] session=${session_key.slice(0, 8)} gateway=discard reason=${gatewayResult.screening.reason}`
@@ -6480,9 +6502,17 @@ function readUsersFile() {
   if (!raw) return [];
   return JSON.parse(raw);
 }
+function claudeSpawnPath() {
+  const base = process.env.PATH ?? "/usr/bin:/bin:/usr/sbin:/sbin";
+  return `${base}:/opt/homebrew/bin:/usr/local/bin`;
+}
 function checkAuthStatus() {
   try {
-    execFileSync2("claude", ["auth", "status"], { encoding: "utf-8", timeout: 5e3 });
+    execFileSync2("claude", ["auth", "status"], {
+      encoding: "utf-8",
+      timeout: 5e3,
+      env: { ...process.env, PATH: claudeSpawnPath() }
+    });
     return true;
   } catch {
     return false;
@@ -6537,22 +6567,34 @@ app4.post("/claude-auth", async (c) => {
     return c.json({ launched: cdpReady });
   }
   ensureLogDir();
+  writeFileSync6(logPath("claude-auth"), "");
+  const claudeAuthLogFd = openSync(logPath("claude-auth"), "a");
+  const onClaudeOutput = (chunk) => writeSync(claudeAuthLogFd, chunk);
+  if (process.platform === "darwin") {
+    vncLog("claude-auth", { action: "start", transport: "native", platform: "darwin" });
+    const claudeProc2 = spawn("claude", ["auth", "login"], {
+      env: { ...process.env, PATH: claudeSpawnPath() },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    claudeProc2.unref();
+    claudeProc2.stdout?.on("data", onClaudeOutput);
+    claudeProc2.stderr?.on("data", onClaudeOutput);
+    claudeProc2.once("close", () => closeSync(claudeAuthLogFd));
+    return c.json({ started: true, transport: "native" });
+  }
   if (transport === "vnc") {
     const vncReady = await ensureVnc();
     if (!vncReady) return c.json({ error: "VNC display failed to start" }, 500);
   }
   await ensureCdp(transport);
-  writeFileSync6(logPath("claude-auth"), "");
   const chromiumWrapper = writeChromiumWrapper();
   const x11Env = buildX11Env(chromiumWrapper, transport);
   vncLog("claude-auth", { action: "start", transport });
-  const claudeAuthLogFd = openSync(logPath("claude-auth"), "a");
   const claudeProc = spawn("claude", ["auth", "login"], {
     env: x11Env,
     stdio: ["ignore", "pipe", "pipe"]
   });
   claudeProc.unref();
-  const onClaudeOutput = (chunk) => writeSync(claudeAuthLogFd, chunk);
   claudeProc.stdout?.on("data", onClaudeOutput);
   claudeProc.stderr?.on("data", onClaudeOutput);
   claudeProc.once("close", () => closeSync(claudeAuthLogFd));
@@ -8537,7 +8579,12 @@ async function performSpawnWithInitialMessage(args) {
     dormantPlugins,
     activePlugins,
     specialistDomains,
-    tunnelUrl
+    tunnelUrl,
+    // Task 382 — thread the active conversation's UUID through to the
+    // manager so the PTY env carries CONVERSATION_NODE_ID. Undefined is
+    // legitimate (autonomous spawns); the manager's UUID gate filters
+    // unshapely values.
+    conversationNodeId: args.conversationNodeId
   });
   console.log(`${TAG18} forward-spawn-start managerBase=${managerBase2()} bytes=${upstreamPayload.length} hidden=${args.hidden} specialist=${args.specialist ?? "none"}`);
   const forwardStart = Date.now();
@@ -8632,6 +8679,7 @@ app15.post("/", async (c) => {
   const specialist = typeof body.specialist === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(body.specialist) ? body.specialist : void 0;
   const model = typeof body.model === "string" && /^[A-Za-z0-9._-]{1,64}$/.test(body.model) ? body.model : void 0;
   console.log(`${TAG18} spawn-request-in surface=${authSurface} accountId=${senderId.slice(0, 8)} userId=${userId ? userId.slice(0, 8) : "absent"} channel=${channel} permissionMode=${permissionMode ?? "default"} specialist=${specialist ?? "none"} model=${model ?? "default"} initialMessage=${initialMessage ? "yes" : "no"}`);
+  const conversationNodeId = cacheKey ? getConversationIdForSession(cacheKey) : void 0;
   const { response, claudeSessionId } = await performSpawnWithInitialMessage({
     senderId,
     userId,
@@ -8641,7 +8689,8 @@ app15.post("/", async (c) => {
     hidden: false,
     specialist,
     model,
-    initialMessage
+    initialMessage,
+    conversationNodeId
   });
   mintTranscriptEdge(
     cacheKey ? getConversationIdForSession(cacheKey) : void 0,
@@ -8719,7 +8768,13 @@ app15.post("/resume", async (c) => {
       dormantPlugins,
       activePlugins,
       specialistDomains,
-      tunnelUrl
+      tunnelUrl,
+      // Task 382 — resume parity with /spawn: thread the active
+      // conversationId so the re-spawned PTY's MCP env carries
+      // CONVERSATION_NODE_ID. Undefined when no active conversation is
+      // bound to this cacheKey (rare for resume — the user is by
+      // definition continuing a known conversation).
+      conversationNodeId: getConversationIdForSession(cacheKey)
     })
   }).catch((err) => {
     console.error(`${TAG18} fetch-failed op=resume message=${err instanceof Error ? err.message : String(err)}`);
@@ -12133,7 +12188,11 @@ app32.post("/", requireAdminSession, async (c) => {
     hidden: true,
     specialist: "database-operator",
     model: void 0,
-    initialMessage
+    initialMessage,
+    // Task 382 — LinkedIn ingest is a hidden autonomous spawn with no
+    // parent admin conversation; the database-operator threads
+    // `producedByTaskId` via work-create instead. Leave undefined.
+    conversationNodeId: void 0
   });
   if (!response.ok) {
     const detail = await response.text().catch(() => "");