# Map AI Advisor Enhancement — M01–M10

Development work started 2026-10-13. Implementation worktree baseline: d788451728c7536c542eafb3d825b29e8df18a95. The previously audited local dev-chen is 5bba44e0b; only these task commits will be integrated there and checked against that target, without merging unrelated upstream history. Production G01/G02 remain partially verified. This branch does not authorize deployment, master imports or ordinary-member access.

## Materials and review

`materials.draft.json` contains 3 project documents, 2 area documents, 12 FAQ and 20 facts in English, Chinese and Bahasa Malaysia. Every item is a **draft** for mentor or Wai Kit. `source-manifest.json` records acquired originals and SHA-256; raw public HTML/PDF originals are retained outside Git in the audit artifact directory. Publication dates are unknown where the original does not identify one. Acquisition dates are not publication dates.

The official Eaton and MET 1 material contains old APDL periods; the Pavilion brochure's advertising permit period ends before this review date. Current asking prices, permit validity, completion assertions and operating facilities are excluded. Descriptions state what the cited website/brochure lists. Review licensing/use scope and all translations before setting `usageScope=site_answer` and actual `review.by/at/status=approved`. Do not bulk mark these drafts approved to pass an import.

Eaton source46621 and MET 1 source46464 already bridge to candidate Research schemes. They still require source-active/match metadata and quality review; Eaton has a coordinate conflict. Pavilion Mont Kiara mapping is not confirmed. None of these draft facts creates a Research marker or treats catalogue UUID as a scheme ID. Project knowledge can be reviewed independently; map/data bridging additionally requires `mappingReview` approval, named reviewer/date and verified coordinates, plus an active, unambiguous RealtyCheck source with LINK/confidence >=90/decided_by metadata. The three draft mapping reviews remain pending.

FAQ 10/11 are mathematical yield definitions, not rental observations. FAQ 12 explains the policy gap; it contains no foreign-buyer minimum or tax amount.

## Fixed scope and contract

See `contract.json` and `evals.json`: 20 retrieval cases, 30 end-to-end cases (6 supported + 4 boundary per language), and 12 original QA questions. R1-6 is the original report's cross-question map observation, not another question. The original Chinese input was not fully recorded; it is marked missing, not recreated as an exact original.

These are review candidates, frozen for implementation comparison. Any subsequent correction records the reason; do not relabel a refusal as a sourced answer or remove hard cases to raise a score. Automated HTTP/model fakes test the integration, not real embedding recall or model accuracy.

## Implementation and operational boundaries

- Site MySQL owns documents, immutable versions/facts and releases. The catalogue/master is read-only to this work.
- An offline import job generates embeddings and a per-release Qdrant collection. An incomplete import cannot replace the active release. Re-importing identical approved content reuses the ready release.
- Retrieval filters release, country, applicability, withdrawn documents and brief entity scope, then rechecks database authority. Index outage returns `partial` only for directly matched reviewed facts; absent evidence returns `unavailable`.
- `PROPERTYLAB_KNOWLEDGE_ENABLED` defaults false. Current pilot knowledge tools are server-gated to admins even if another Advisor tab lock is later opened.
- Embedding base URL/key are explicit separate configuration. No implicit use of production credentials or bypass of the chat gateway. An approved OpenAI-compatible embeddings endpoint is needed; the current PETA chat route alone is insufficient.
- The generation model stays on the existing AiClient/funding path. Claims are selected and validated before text is emitted; knowledge facts must bind to real versioned citations.
- Explicit budget, region and project names persist in the revision-locked brief. Accepted state survives a cancellation; cancelled/old turns cannot overwrite a newer result. Bare numerical follow-ups preserve the current language.
- Region map centers reuse `config/area_guide.php`; they represent guide focus positions, not administrative polygons, property coordinates or commute estimates.

## Pilot runbook (M10)

For the `dev-chen → master` release, use [DEPLOYMENT.md](DEPLOYMENT.md): missing inputs, rollout approval template, first-install bootstrap, one-command deployment and activation recovery. Its synchronous deployment import does not require an extra queue worker. The commands below remain available for a manual isolated pilot.

These are future commands for an **approved isolated staging/site environment**. They were not run on production.

1. Resolve G01/G02 and verify the deployment release, site/catalogue/master boundaries and three project mappings. Review the facts and intended use scope.
2. Confirm approved embedding endpoint, key, model/dimension, Qdrant endpoint/key and worker queue. Do not paste keys into chat or commit them. Keep knowledge disabled while preparing.
3. Apply the task migration through the normal staging migration process. No `migrate:fresh` against a business database.
4. Process the approved package offline: `php artisan propertylab:knowledge-import /approved/package.json --activate`. A worker must consume `knowledge-import`; default sync drivers run it inline, so configure a real queue before production use. `--sync` is for an intentional isolated staging run.
5. Inspect the ready release, version IDs, chunk count and embedding token usage. Test facts and citation support using the fixed cases before enabling.
6. Enable the knowledge flag only after review and staging acceptance; preserve the existing admin-only pilot restriction. Run the seven-step demo below with 3–5 authorized reviewers; do not invite them automatically.
7. Restore by disabling only the knowledge flag, or activating a previously verified ready release with `php artisan propertylab:knowledge-release <ready-release-uuid>`. Withdraw a document with `php artisan propertylab:knowledge-release <document-id> --withdraw`. Do not drop tables. A withdrawn document stays excluded even when returning to an older release.
8. Rebuild indexes using the approved original/package, with compatible model/dimension. Changing embedding configuration without a matching release yields an explicit degraded retrieval path rather than using incompatible vectors.

### Demo and feedback

- State Mont Kiara + RM800k, then condo; correct to RM700k; reload and check brief, map and query state.
- Ask each fully named project about facilities; select a mapped scheme and check that the same project's facts are retrieved.
- Request facts and price evidence together; verify charts/markers/claims/citations describe the same approved project.
- Ask an unsupported foreign-policy amount, rental observation or live listing; verify a supported partial answer or a precise missing-data explanation.
- Open sources and check title, page, excerpt, dates and immutable source version.
- Update one FAQ, withdraw one document, restore the previous release, then disable knowledge; original data exploration must still work.
- Use five concurrent pilot sessions; measure retrieval P95 <=2s and end-to-end P95 <=15s, retaining the original 45s mixed-request budget. Record actual provider/queue/index usage and costs; do not infer latency or cost from HTTP fakes.

Feedback columns: case ID, language, release, source version, conversation/turn/result IDs, failure category (material/retrieval/claim/state/map/UI/gateway), expected/actual outcome, reviewer, severity and retest. Never collect raw private prompts solely for diagnostics.

## Exit checklist

| Task | Engineering deliverable | Actual release gate |
|---|---|---|
| M01 | Draft package, originals and review checklist | Mentor/Wai Kit approval, use scope and G02 project identity |
| M02 | Fixed cases and additive contract | QA/business sign-off; unsupported cases kept separate |
| M03 | Versioned offline import, embedding/Qdrant adapters | Approved endpoint and real index import/rebuild validation |
| M04 | Scope/applicability/withdrawal filters and fallback | Real 16 positive retrieval cases >=15 Hit@5; four boundaries correct |
| M05 | Revision-safe explicit brief persistence and region focus | Five-turn staging journey and approved project crosswalk |
| M06 | Knowledge/data/mixed orchestration and persistence | Runtime feature remains off until ready; no snapshot dependency for facts |
| M07 | Reviewed three-language claims and citation validation | Actual source support/translation review and real model selection |
| M08 | Document drawer, map preservation, existing charts | Browser journey on mapped projects; no wrong markers |
| M09 | Targeted automated regression and build evidence | Real 30-case scores, all 12 QA results, concurrent latency, cost and rollback |
| M10 | Fixed pilot, feedback and restoration instructions | Approved staging deployment and human pilot; no production deployment here |
