Skip to main content

WiseAI Realtor — Operational Aria + In-App Help System (MVP) Expected Output Spec

STATUS: DRAFT — founder sign-off pending (Rule #17 gate).​

Reviewer applies the two migrations and validates product_knowledge. No push to main, no deploy, nothing auto-sent.

Sourced from (read-only): the Aria concierge code (prompt.ts, context-server.ts, screen-registry.ts, see-point.ts, route.ts), the RE guardrail module (ai-guardrails.ts), the onboarding model (onboarding-model.ts), the working-screen components under src/components/realtor/{crm,deals,listings,analytics,studio,reviews,qr-campaigns}/, and do-not-reinvent.md (feature ground-truth). Every operational answer is grounded in what the shipped code ACTUALLY does — no invented features.

§0 — Scope & non-goals​

In scope (this MVP):

  1. Operational Aria — Aria answers product "how do I use X" questions grounded in a NEW operational knowledge corpus, in addition to setup Q&A, when the owner is past setup or on a working screen. She still guides-not-does and still refuses regulated/out-of-lane topics.
  2. Operations corpus — a new product_knowledge category realtor_operations seeding concise, accurate how-to Q&A for the main features.
  3. See-point on working screens — the screen-element registry gains entries for the working screens (Inbox, Leads, Pipeline, Contacts, Analytics, Content Studio; Listings/Reviews/QR already present) so Aria can highlight there too.
  4. In-app help layer — one concise contextual help hint per main working-screen header + a persistent "Help" affordance in the top bar that opens Aria.
  5. Operator guide — a plain-language founder-facing doc (knowledge/products/wiseai-realtor/operator-guide.md).

Explicitly OUT of scope (deferred): a full /help route / help center; a searchable article library; video walkthroughs / screenshots; write actions by Aria (she stays read-only "see + point, not touch"); operational belt phrase-packs beyond EN/FR (unchanged from today); voice-side operational help changes.

§1 — Safety floor (NON-NEGOTIABLE — reviewer verifies byte-intact)​

The following must be unchanged by this work (diff must show no edits to their bodies):

  • buildReAiBridgeFrame() — the RE AI Bridge frame (ai-guardrails.ts).
  • buildRealEstateGuardrailBlock() + buildReFairHousingBlock() — the valuation / legal / financing / tax / offer / representation / steering / identity-disclosure / no-confidentiality / facts-only floor.
  • The post-LLM belt (scanRealEstateReply, BELT_RULES, safeRealEstateDeferral).
  • The onboarding honesty contract's HONEST METRICS, GUIDE, DON'T TOUCH, and OUT-OF-LANE COMPLIANCE sections.
  • The see-point read-only guarantee (only focus / navigate_and_highlight; no write path).

Acceptance:

  • S1 — src/lib/real-estate/__tests__/ai-guardrails.test.ts and ai-guardrails-belt.test.ts pass unchanged.
  • S2 — .../assistant/__tests__/aria-onboarding.test.ts passes: the assembled prompt still contains AI BRIDGE PRINCIPLE (first), NEVER give a home VALUATION, FAIR HOUSING, HONEST METRICS, SETUP-ONLY SCOPE, and GUIDE, DON'T TOUCH in the default (setup) context.
  • S3 — see-point.test.ts passes: no write action exists; every directive is structurally read-only.
  • S4 — The ONLY change to the honesty contract is the SCOPE section, and only in operational mode; setup mode is byte-identical to before.

§2 — Operational Aria (the core)​

Mode. The prompt builder chooses a scope mode from the turn context:

  • setup mode (default / setup hub / dashboard / unknown route / setup not launch-ready) → the existing SETUP-ONLY SCOPE block, byte-intact.
  • operational mode → widened PRODUCT-HELP scope, triggered when the owner is on a working feature screen (Inbox/Leads/Pipeline/Contacts/Listings/Analytics/ Studio/Reviews/QR/Website/Integrations/settings sub-screens) OR setup is launch-ready.

In operational mode Aria may: answer "how do I use X" from the realtor_operations corpus + the nine-step copy, and deep-link/see-point to the right screen.

In operational mode Aria must still: (a) say honestly she can't DO the action for the owner (read-only — GUIDE, DON'T TOUCH unchanged); (b) refuse genuinely out-of-lane/regulated topics per the guardrail block + OUT-OF-LANE COMPLIANCE; (c) never fabricate a status/route/feature; (d) only claim features that exist in the corpus/code.

Corpus loading. context-server.ts also fetches category realtor_operations (defensive: any error → empty) and passes it as operations rows. The prompt renders an OPERATIONS KNOWLEDGE block ONLY in operational mode.

Acceptance:

  • A1 — On a working screen (e.g. /realtor/app/inbox), the assembled prompt contains an OPERATIONS KNOWLEDGE block and a widened scope section that explicitly permits product how-tos; it does NOT contain SETUP-ONLY SCOPE.
  • A2 — With no currentRoute (or on /realtor/app/setup), the prompt is in setup mode: contains SETUP-ONLY SCOPE, does NOT contain OPERATIONS KNOWLEDGE.
  • A3 — The bridge frame + guardrail block appear in BOTH modes, unchanged.
  • A4 — Every realtor_operations answer is accurate to shipped code (no invented features), distinct, >=50 chars, deep-links to a real /realtor/app/* route, and stays in Aria's warm plain-language voice.
  • A5 — Asked to DO an action ("respond to this lead for me"), operational Aria declines (read-only) and offers to point/deep-link — never claims she did it.
  • A6 — Asked a regulated question ("what's this house worth?") on a working screen, the guardrail block still forces a defer; the belt still audits.

§3 — Operations corpus (product_knowledge category realtor_operations)​

Two migration files under churchwiseai-web/migrations/ (reviewer applies via the Supabase MCP, then runs validate_product_knowledge()):

  1. Widen the product_knowledge_category_check CHECK to add realtor_operations.
  2. Seed ~30 concise how-to Q&A rows covering: working a lead (lead -> Inbox -> respond -> Contact -> Pipeline), Inbox (AI summaries, co-pilot vs autopilot, take-over), Contacts & Pipeline, Listings (DDF vs exclusive/manual, featuring), QR campaigns (create -> print -> track), Reviews (import -> request -> approve), Content Studio (7 types, generate -> compliance -> publish), Website builder (templates, Compliance/identity, publish), Analytics (honest metrics), Notifications.

Isolation (mirrors the onboarding corpus): loaded ONLY by /api/realtor/onboarding/assistant (category filter); seeded at LOW priority (2-3) so it can never rank into the church chatbot's top-N-by-priority injection.

Acceptance:

  • K1 — After apply, SELECT severity, count(*) FROM validate_product_knowledge() shows no new CRITICAL vs the pre-apply baseline (no duplicate answers).
  • K2 — Every seeded answer >= 50 chars (no short-answer WARNING) and distinct.
  • K3 — Rows use per-row clock_timestamp() so the batch adds no new bulk-timestamp WARNING group.
  • K4 — Idempotent: re-running inserts nothing (guarded by NOT EXISTS).
  • K5 — category='realtor_operations' is accepted by the CHECK (migration 1 applied first).

§4 — See-point on working screens​

The screen-element registry (screen-registry.ts) gains header targets for the working screens; each registered id has a matching data-aria-target="<id>" attribute on the real screen header (anti-rot lint screen-registry.test.ts enforces parity). The registry route-validity test is widened to accept the nav-model working routes (not just step-ctas/hub/dashboard).

Acceptance:

  • P1 — screen-registry.test.ts passes: every registered id maps to a real data-aria-target attribute; no orphans; every route is a real realtor nav route.
  • P2 — targetsForRoute('/realtor/app/inbox') (and leads/pipeline/contacts/ analytics/studio) returns >= 1 target.
  • P3 — Directives remain read-only (unchanged see-point semantics).

§5 — In-app help layer​

  • Per-screen hint. A small ScreenHelpHint affordance on each main working-screen header: a one-line "what this screen is for / how to use it" line + an "Ask Aria" button that opens the concierge (operational). One concise hint per screen — no clutter. AODA: real button, keyboard-focusable, aria-* correct.
  • Top-bar Help. A persistent, honest "Help" / "?" affordance in RealtorTopBar that opens Aria. Minimal and on-brand (navy/teal). Honest label — it opens the AI guide, it does not promise human support it can't deliver.

Acceptance:

  • H1 — Inbox, Leads, Pipeline, Contacts, Listings, Analytics, Studio, Reviews, QR Campaigns each render exactly one contextual help hint in/near the header.
  • H2 — The top bar shows a Help affordance on every /realtor/app/* screen; a click opens the Aria panel.
  • H3 — Nothing added is a dead/"coming soon" control — every affordance does a real thing (opens Aria).
  • H4 — account_id stays in the query string on every authed Aria fetch (unchanged aria-client.ts contract).

§6 — Docs & regression​

  • D1 — knowledge/products/wiseai-realtor/operator-guide.md exists: plain-language, per-screen "what it does + day-to-day workflow", founder-trainable.
  • D2 — do-not-reinvent.md / relevant knowledge updated where this adds a module; pnpm derive --check noted for the reviewer.
  • D3 — tsc clean; build clean if runnable in the worktree (note the worktree Turbopack root gotcha if not).

§7 — Verification checklist (reviewer)​

  1. git diff shows the safety functions' bodies unchanged (§1).
  2. node --import tsx --test on ai-guardrails, ai-guardrails-belt, aria-onboarding, see-point, screen-registry — all pass.
  3. Apply migration 1 then 2; run validate_product_knowledge() — no new CRITICAL (§3 K1).
  4. pnpm tsc --noEmit clean.
  5. Deployed-URL Playwright (post-merge, per CLAUDE.md ladder): open a working screen, confirm the help hint + top-bar Help, open Aria, ask "how do I respond to a lead" (operational answer + deep-link), ask "what's this house worth" (defer), ask "turn on autopilot for me" (declines, read-only).