# Map AI Advisor — "show me the location" acceptance — 2026-10-16

Follow-up to [GENERALIZATION_ACCEPTANCE.md](GENERALIZATION_ACCEPTANCE.md) (PR #210, dev-chen 59c1c9c9). The request: after a buyer states home, work, budget and preferences in their own words, the chat answers from evidence and the map shows the matching places; follow-ups and corrections update both together. Entry: Analyze Property → AI Advisor (`/property/research?mode=advisor`). Nothing here touches the AI Coach (`/property/ai-advisor`), credits, the Super Admin exemption, permissions or other modules' rate limits. No migration, dependency or environment variable is added.

## What already worked (baseline, reused)

Verified on the baseline build in a real browser against local Herd with real OpenAI GPT-4.1 before any change:

- "I stay at Sunway Velocity, work in TRX." saves `routine.home` / `routine.work`, answers both sourced access-station connections (Cochrane 1 stop, Maluri 2 stops), shows the three station reference points, fits the map to them and asks for the budget once.
- "Find condos near Cochrane under RM500k." saves the RM500,000 purchase budget, runs `search_properties_near_station` with the disclosed 2 km straight-line radius, highlights the matched schemes on the map and fits them.
- "Actually, I work at Pasar Seni." changes only `routine.work` (home and budget retained) and answers the new connection.
- Station evidence cards already had `View on map`; the budget cannot be relaxed by the model; zero matches and rental-price gaps are disclosed (G7/G3 of the earlier suite).

## Gaps found in that baseline (browser evidence, `evidence-map-advisor-show-location-20261016/baseline/`)

| # | Gap | Fixed in |
| --- | --- | --- |
| G1 | A station search answer had no project cards: only model-selected claim text (3 of the 4 matched projects were named) and "No supported numerical chart is attached". Nothing to hover or click; no card ↔ marker correspondence; distance and price basis only in prose. | `EvidencePanel.vue` (cards), `GroundedAnswer.php` (count claim) |
| G2 | "condos" (plural) was not parsed, so the saved property types stayed "all seven" and a Serviced Apartment appeared in a condo search. | `BriefExtractor.php` |
| G3 | Every station point read "Station: X". After the work correction the old work station (TRX, now a pass-through station on Cochrane → Pasar Seni) was indistinguishable from the new destination, in the cards and on the map. | `RailConnections.php`, `ResultComposer.php`, `stationRoles.js`, `EvidencePanel.vue`, `PropertyMap.vue` |
| G4 | After the correction the previous search's focus survived: the floating "Viewing property" card for Demo Cochrane A stayed on the map and the scene kept the old focus ids. | `useResearchScene.js` |
| G5 | On the work-only correction the model called `get_transit_connections` with origin "Cochrane" (a station from history) instead of the saved home "Sunway Velocity", so only one of the two access stations was answered. | `AdvisorOrchestrator.php` |
| G6 | The scope line still said "no named area yet" after a station search. | `Advisor.vue` |
| G7 | Phone layout: the only map entry under an answer was "Show selection on map" (selected properties only); station and project results offered no way to the map tab. | `EvidencePanel.vue`, `Advisor.vue` |

## What this change adds

- **Station roles.** Every station point of a rail or station-search result carries `role` (`origin`, `destination`, `via`, `anchor` = search centre) and `endpoint` (the label the buyer typed, e.g. "Sunway Velocity"). The page labels them against the saved routine — Home / Work when the endpoint or station name resolves the brief (same normalisation as `RailConnections::normalize`), otherwise From / To / Via / Search centre — in the cards ("Home · Cochrane · Sunway Velocity access") and on the map ("Work: Pasar Seni", "Via: Tun Razak Exchange (TRX)", smaller marker). Pass-through stations are one compact "Passes through" row. A composed result keeps one point per station, the strongest role winning.
- **Project cards.** A search-type answer lists its projects as numbered cards: type, "Historical median RM x · RM y/sq ft" (or "No source price"), "≈ d km from <station> station reference · straight line", a precision note when the scheme is not a plain `scheme` (the local demo rows read "synthetic demo"). Hovering highlights the marker; clicking focuses it and opens the existing "Viewing property" card without replacing the current result, the saved scope or the brief — so a card in an older message is safe to click. "Show all on map" re-fits every matched project. The deterministic match-count claim is always the first sentence of the answer, so the text and the cards agree on the number even when the model names fewer projects. A zero match says "No recorded projects matched these filters within 2 km of <station>." instead of the chart message.
- **Map focus.** A station search fits the station plus its projects; a rail answer fits its stations and clears the previous search's focused property; the scope line reads "near Cochrane · 2 km straight-line".
- **Corrections.** "condos" / "condominiums" set the Condo/Apartment type. A work-only correction keeps the saved home as the rail origin, so a multi-access home (Sunway Velocity) is still answered through both stations.
- **Phones.** Every answer with stations or projects has a "View on map" button; a card tap switches to the Map tab and focuses that project; nothing switches tabs on its own while the buyer is typing.

## Verification

### Automated

- Isolated PHP suite (`tests/Unit/PropertyLab` + `PropertyLabAdvisorTest`): **366 tests / 2,976 assertions passed** (baseline 347 / 2,862). New: `RailConnectionRolesTest` (4), `ResultComposerTest` (+3), `RoutineMemoryTest` (+8 cases), `AdvisorGroundingTest` (+1), `PropertyLabAdvisorTest` (+3 — the origin guard and two controls with an explicit "From Cochrane").
- Frontend PropertyLab scope: **20 files / 116 tests passed** (baseline 18 / 96). New: `EvidencePanel.test.js`, `stationRoles.test.js`; extended `Advisor.test.js` (station search focus, card click makes no `/tools` call and leaves the brief untouched, phone "View on map"), `PropertyMap.test.js` (role label, via radius), `useResearchScene.test.js`, `destinationModel.test.js`. The whole `npx vitest run` keeps the same 30 pre-existing failures in five unrelated files (Prompts preview, PropertyMatch admin, Zoom evaluation, sales coach chat, portal guide) that fail on untouched dev-chen.
- Changed-file Pint, `check-migration-constants`, `check-suite-links` (baseline 67) and `check-test-doubles` pass; `check-learning-content.mjs` still reports the pre-existing stale `how-to.en.json` (reproduced on untouched master 9808c526 in PR #210). Client and SSR builds pass.
- GitHub Actions still cannot start jobs ("recent account payments have failed or your spending limit needs to be increased" on every job of the last three dev-chen runs and on master pushes); the remote CI is an environment block, not a code failure, and is not claimed green.

### Real-model replays (service level, local Herd, OpenAI GPT-4.1)

A replay harness drives the same HTTP + SSE endpoints the page uses (dev quick login, conversation create, `PUT state` with the page's default brief, `POST /turns`) and records the brief, result and answer of every turn. 36 turns in the first pass (the boss sequence plus the eight fixed groups of the earlier acceptance, with "Same budget, but show me recorded projects near Cochrane by location only." appended to G8), then 16 reruns after the deduplication fix. Every turn completed; 0.9–7.8 s each.

| Case | Outcome |
| --- | --- |
| Boss: Sunway Velocity → TRX; condos near Cochrane ≤ RM500k; work → Pasar Seni | T1 both access stations (`origin`, endpoint "Sunway Velocity") + TRX (`destination`). T2 3 Condo/Apartment matches (A 0.22 km, B 0.65 km, TRX A 1.35 km; Serviced Apartment D excluded by type, C by price, E missing price), count claim first. T3 home kept, work Pasar Seni, **both** Cochrane → Pasar Seni (4 stops) and Maluri → Pasar Seni (5 stops), TRX `via`. |
| G1 Taman Connaught → TRX, rent RM2,200, no car | 6 stops no transfer; Maluri/Cochrane `via`; rent basis + no-car saved; rental-price gap disclosed with the location-only offer. |
| G2 Cochrane → Pasar Seni, then only work → TRX, recall | Home "Cochrane MRT" kept; 1 stop; recall lists home/work/transport/budget/types/area. |
| G3 Kajang search, TRX work, RM650k → rent RM2,800 | Search area "MRT Kajang" kept apart from work; purchase search 0 matches within 2 km (11 outside radius); rent switch keeps RM2,800 rent only; compound turn answers 14 stops + rental gap, Kajang once as `origin`. |
| G4 Hypothetical Kajang vs actual Maluri | Both connections (14 vs 2 stops); brief unchanged; recall correct; search area → Cochrane only. Maluri appears once as `origin` after the dedupe. |
| G5 Unknown development, explicit station | Unknown project not invented; Taman Connaught used as origin only when stated; no walking time. |
| G6 Arrival guarantee | Connectivity answered, guarantee explicitly declined, one missing detail asked. |
| G7 Zero matches then Cochrane | Taman Connaught: 0 condos ≤ RM500k (10 outside radius, 1 wrong type), no relaxation; Cochrane: A, B, TRX A with the count claim first. |
| G8 Two origins, latter/there, work → Pasar Seni, same budget | Both origins compared; "latter" → Taman Connaught; Chinese answer; work → Pasar Seni (9 stops, TRX `via`); location-only search keeps the RM2,500 rent budget and lists 5 of 6 nearby projects with the location-only limitation. |

Replay records (brief, result summary, answer per turn) are kept in the local evidence folder `evidence-map-advisor-show-location-20261016/replays/`.

### Browser (chrome-devtools, local Herd, real model)

Desktop 1440×900 and phone 390×844 emulation, each a fresh conversation with the boss sequence; recordings `after/boss-desktop-walkthrough-final.mp4` and `after/boss-mobile-walkthrough.mp4` plus screenshots `after/01–04`, `m1–m3`. Checked per turn: the brief line, the station tags, the cards, the map labels, the "Viewing property" card, the scope line, and on the phone which tab is active.

- Turn 1: cards "Home · Cochrane · Sunway Velocity access", "Work · Tun Razak Exchange (TRX)", "Home · Maluri"; map fits the three stations, labelled Home/Work. Phone: Chat tab stays; "View on map" opens the Map tab fitted to the stations.
- Turn 2: three numbered cards with distance and historical median, "Search centre · Cochrane", scope "near Cochrane · 2 km straight-line"; map fits station + projects. Clicking card 2 focuses Demo Cochrane B (the floating card switches to it) with no `/tools` request and no brief change; "Show all on map" re-fits. Phone: a card tap switches to the Map tab on that project.
- Turn 3: brief "Home: Sunway Velocity · Work: Pasar Seni · RM 500,000"; cards Home/Work/Home plus "Passes through: TRX, Pavilion Bukit Bintang"; map "Work: Pasar Seni", "Home: Cochrane", "Home: Maluri", "Via: …" with smaller via markers; the previous "Viewing property" card is gone; the turn-1 TRX card now reads "To", not "Work".
- One iteration was needed: the first build showed "TRX access" under the Work card because the endpoint "TRX" is an alias of the station itself; `stationRoles.js` now drops the detail when the endpoint names the station (`stationRoles.test.js`), and the final desktop recording was made on that build.

## Local data used for this acceptance

The local research snapshot is synthetic (`LOCAL_TEST_SYNTHETIC`, precision `synthetic_demo`). It originally held three "LOCAL TEST — Demo Mont Kiara" schemes, none within 2 km of any Kajang Line station. Eight more clearly labelled demo schemes were added to the LOCAL database only ("LOCAL TEST — Demo Cochrane A–E", "Demo TRX A", "Demo Pasar Seni A–B", six synthetic monthly observations each) so that a station search has something to show. They are not committed, not market data, and the cards show their precision as "synthetic demo".

## Limits and data gaps

- Production inventory: the real research snapshot, the three project mappings and the knowledge package remain the prerequisites in [DEPLOYMENT.md](DEPLOYMENT.md); this acceptance proves behaviour on the local synthetic snapshot, not coverage.
- Station coordinates exist for 28 of the 29 Kajang Line stations, each from the map embed on that station's MRT Corp page. They are station-area references that can sit several hundred metres from the station, not entrances. Taman Midah is the exception: its embed is centred about 1.2 km from the station, so it stays unplaced and a search centred on it says so.
- Still unavailable, and still not invented: live listings, rental prices and availability, live train service, waiting times, walking or door-to-door times. Distances are straight-line from a station-area reference, never a route.
- A budget with no stated basis is treated as the page's default purchase basis once the workspace is saved; typed over the API without that default, the advisor asks "buying or monthly rent?" rather than assuming.
- Delivery stays `dev-chen → master` through PR #210; no merge or production deployment was performed.
