Appearance
Real Estate — discovery brief
THIS IS NOT A COMPLETED DISCOVERY. IT IS THE AGENDA FOR ONE.
CLAUDE.md's G-D gate requires an approved discovery.md before any vertical goes live, and check:release fails a release whose scope carries a domain_scoped item without one. This page is Part 0: the questions to put to real agents and builders, plus what the architecture can already answer so the session is not spent re-deriving it. Nothing here is a decision.
Status: brief written 2026-08-09 · session not held · QRS-454
Why this vertical got its own brief
The owner spoke to real estate agents and surfaced a workflow that no other QRSETU vertical has:
Agent A has a client looking for a 3BHK in a particular area. Agent B holds a matching listing. A asks B to share it, B accepts and names a commission split, and the listing then appears on A's Setu Card — still owned by B, so B's edits show up on A's card.
Plus a second, adjacent one: builders launch projects with special schemes, and channel-partner agents promote that inventory through their own cards.
Real estate is not "another catalogue vertical". It is network-driven — supply, demand and the right to market are held by different parties. That is a different shape from every industry currently modelled, all of which assume the merchant owns what they sell.
⚠ Proportionality note: real_estate is expertise, and no expertise industry has a discovery doc yet. Per the plan's own rule (full discovery for the first domain in an archetype, a short delta doc for each sibling), this is the FULL one, and car_sales, photographer, electrician_plumber and direct_seller become delta docs against it. That makes the session worth more than one vertical.
What the architecture already answers — do not spend session time here
Verified against the v2 migrations, so the session can start from these rather than rediscover them.
| The requirement | Already answered | Where |
|---|---|---|
| B's edits propagate to A's card, live | Free, by construction. A manifest block may REFERENCE a field, never CONTAIN vendor content (invariant T12, gated). A shared listing on A's card is a reference to B's catalog_items row, so propagation is the default and copying is the thing that is hard to do | ADR-0019 · check:setu-card-templates T12 |
| One listing visible on many cards, without duplication | The mechanism exists. my_shared_org_ids('catalogue') resolves a UNION up the workspace tree gated by organizations.share_catalogue (default off). Its own comment describes "the dealership case, where one row per car is visible to twenty agents so exclusivity holds by construction" — which is structurally the co-broking requirement | ADR-0022 · 20260808190000_v2_rls_policies.sql |
| Builder launch offers rendered across partner cards | Already designed, five of six pieces exist (sharing · tree targeting · manifest block · analytics · time-bounding) | ADR-0025 |
| Shared inventory + campaigns for an agent network | Already the named flagship: car_sales is "structurally identical to real estate, plus shared inventory and campaigns" | industries seed |
| Co-broking as a relationship type | Already anticipated, not built. The plan records: "co-broking (peer), dealership seats (hierarchical, org-owned), MLM upline (hierarchical, member-owned) — model it once as a typed relationship with a role" | 26.0.1 plan, enterprise section |
The gap is topology, not mechanism. Every relationship in v2 is either hierarchical inside one organization (workspaces.parent_id + materialized path) or membership (workspace_members). Both co-broking and builder↔channel-partner are an edge between two workspaces with no common ancestor.
What genuinely does not exist — and only two of the four are expensive later
| # | Missing | Expensive later? |
|---|---|---|
| 1 | A peer collaboration edge (cross-workspace, no shared ancestor, with a role and a state machine: requested → accepted → withdrawn) | No. Additive: a new table plus a third RLS helper alongmy_workspace_ids / my_oversight_workspace_ids / my_shared_org_ids. Same class as ADR-0022's sharing flags |
| 2 | Commission split | No structurally (v2 has no money model at all yet), but see the risk below — the danger is product/regulatory, not schema |
| 3 | A demand-side record ("my client wants 3BHK in Kothrud under ₹1.2cr") | ⚠ YES. Everything in catalogue is supply-side. party models a customer, but not what they want. And this is the marketplace on-ramp: if consumers (category 3) ever post requirements themselves, the table needs a nullable consumer identity from the first migration — CLAUDE.md's own rule is that an append-only or high-volume table cannot gain an identity column cheaply |
| 4 | The real-estate typed field set (bedrooms, carpet area, locality, price band) | ⚠ YES, and it escalates QRS-452. Matching supply to demand requires filtering, and the attributes column's own rule is explicit: "anything filtered, sorted, grouped, charted, priced or gated is a typed column" — not the JSON bag. So co-broking makes the attributes granularity question load-bearing rather than theoretical |
Two risks to settle BEFORE designing anything
Raised unprompted because both change what the product is, not how it looks.
R1 · Recording a commission split moves QRSETU toward broker/escrow
Facilitating, recording or displaying a money arrangement between two agents is a different business from hosting a card. The plan already flags the adjacent hazard: "the RBI PA constraint is the one most easily broken by a future 'let's hold the money until delivery' idea." Even displaying an agreed split creates an expectation that the platform will enforce it, and therefore a dispute surface with no adjudication mechanism behind it.
Suggested v1 posture, to be confirmed in the session: the platform records the agreement as text between two parties, moves no money, adjudicates nothing, and says so in the UI. Anything stronger needs its own ADR and a legal read.
R2 · Authority to market is a legal precondition, and we have nowhere to record it
An agent must be RERA-registered, and advertising a property one is not authorised to market carries real exposure. So "B's listing appears on A's card" needs a recorded authorisation — and that is the same shape as ADR-0004's compliance_profile / ad_restricted, which does not exist (verified: no such column). The compliance-restricted-vertical problem therefore arrives here with first-party content rather than with a third-party ad, which is the case ADR-0004 deferred.
Part 1 — questions for real agents (the session)
Supply and demand
- Walk through the last three deals. Where did the listing come from, and where did the buyer?
- What fraction of deals involve another agent at all? Is co-broking the exception or the norm?
- How do you currently discover that another agent has what your client wants? WhatsApp groups?
- What does a "requirement" look like when you write it down today, if you write it down?
- Which attributes do you actually filter on, in the order you use them?
Collaboration 6. Who introduces whom? Is the relationship standing (a trusted circle) or per-deal? 7. What stops you sharing a listing with an agent you don't know? 8. Has a co-broke gone wrong? What happened, and what would have prevented it? 9. Is the split agreed before or after the buyer is shown the property? 10. Who talks to the buyer, the seller? Does the other agent ever meet either?
Builders and channel partners 11. How does builder inventory reach you today, and how do you learn about a scheme change? 12. Are you authorised in writing? By whom, and how would you prove it? 13. Can you edit anything the builder published, or only re-share it? 14. Does the builder want to see which of your leads came from their project?
The card 15. What would you want a buyer to see on your card that no portal shows them? 16. Would you put a co-broked listing on your own card, or send a link to the other agent's? 17. What must never appear on your card?
Part 1b — the builder as an ENTERPRISE customer (QRS-455)
The owner raised whether builders are a separate enterprise segment, with channel partners as an organic acquisition network. The opportunity is real and the flywheel as first drawn runs backwards. Full argument in QRS-455; the parts that change the session agenda:
What a builder will actually pay for, and what they will not
They will not pay to host listings. Portals already do that, and a builder's partners already have WhatsApp. The willingness-to-pay sits on three things they cannot buy today:
- Per-partner attribution. Which partner produced which lead, site visit and booking. In QRSETU this is not a feature to build — a lead arriving through partner X's card is attributed by construction, because the card IS the origin. A WhatsApp forward has no attribution at all. This is the single strongest builder-side argument we have.
- Brand and compliance control. One authored source, rendered by N partners who cannot edit it — ADR-0022's "a child may USE an ancestor's resources" plus T12's reference-not-contain. Partners inventing their own creatives and quoting dead prices is a RERA exposure that lands on the builder, so this is cost avoidance, not a nice-to-have.
- Same-day scheme propagation, with proof of delivery. ADR-0025's central publication and purge-at-campaign-boundary.
A fourth, lower down but real: partner performance ranking. Builders currently guess.
What makes a partner adopt — and it must be independent of the builder
⚠ This is the weak link in the whole model. Enterprise-anchor-drives-adoption works when the anchor can compel usage. A dealership rep is an employee (org_owned). A channel partner is an independent business, and by our own "paying ≠ owning" rule they own their card (member_owned). The builder pays for a network it cannot force to log in, which is textbook seat shelfware and a renewal churn.
So partner-side value must stand up with the builder removed: their own card and their own leads, permanently theirs even if they leave the builder · always-current builder inventory with zero effort · the co-broking network, which is builder-independent and is what they actually want · a verifiable "authorised channel partner" signal, which is a trust asset in a low-trust market.
The strategic consequence: the individual plan is not the small plan. It is the retention mechanism for the enterprise plan.
Questions to add to the session — builder side
- How do you attribute a booking to a partner today, and how often is it disputed?
- What does a partner dispute cost you, in money and in time?
- Who makes the creatives your partners circulate? Have you ever had to retract one?
- When a price or scheme changes, how do you know all partners received it? Do you?
- How many partners are active versus enrolled? How do you tell?
- Would you pay per project, per partner seat, or per booking?
- Would you require partners to use a platform, or only encourage it?
- Whose brand does the buyer see first, yours or the partner's? Who decides?
Two modelling questions this raises
- Is a builder's project a workspace? The existing test settles it: "if a place needs its own card and its own P&L it is a WORKSPACE; if it is only an address it is a LOCATION." A project has its own card, price list, schemes and partner set, so project = workspace inside the builder's tree, units are its
catalog_items, schemes are campaigns. No new entity needed — confirm in the session rather than assume. - Pricing shape. Seats license users (QRS-397), so 200 partners = 200 seats, and a builder will refuse to pay for partners who may never log in. Per-project pricing fits the builder's own unit economics (a launch has an allocated marketing budget) and the entitlement model can already express it via the
workspace_groupscope. Test question 23 before assuming.
Part 2 — capability mapping (fill in AFTER the session)
Per the plan's rule, every workflow maps to an existing capability, or to a new one with a written justification that it generalises to ≥3 industries (ADR-0020's governing gate).
| Workflow | Existing capability, or new + its ≥3-industry justification |
|---|---|
| to be completed from the session |
A first read on the peer edge, to be tested not assumed: it looks like it clears the bar — real_estate (co-broking), car_sales (dealer-to-dealer inventory), electrician_plumber (subcontracting a job), photographer (referring work, second-shooter). That is an argument for taking the session seriously, not for building the primitive now.
Sequencing — CORRECTED BY THE OWNER 2026-08-09
⚠ An earlier version of this page said real_estate was a 26.0.2 vertical and recommended shipping listings-only there. That was wrong and is corrected: SOLO REAL ESTATE AGENTS ARE IN R1. The builder / channel-partner use case is what defers to R2 (QRS-455), not the agent.
The mistake came from reading the 26.0.1 plan's launch-vertical table, which lists Real Estate Agent under 26.0.2, as current rather than as superseded. Owner decision is authoritative. QRS-460 tracks the consequences, and they are not cosmetic:
| Consequence | Effect |
|---|---|
| QRS-459 (property field set) becomes an R1 BLOCKER | It was filed as "decide now, populate with the vertical in 26.0.2". The vertical is now R1, so the item_attribute_schema decision (QRS-452) and its real-estate population both land in R1 |
| Launch offers must be AGENT-authorable in R1 | See below — not a builder-only capability |
| Co-broking stays out of R1 | It is the network layer, and it needs this discovery session first. An agent's own listings on their own card is a complete, useful product without it |
| The discovery session moves onto the critical path | It is no longer background research for a later release |
Launch offers are the AGENT's, not only the builder's — and R1 needs them
Owner requirement: "a solo real estate agent should be able to independently create and publish launch offers/properties on their Setu Card", with special visual treatment rather than appearing as just another listing.
✅ The architecture already distinguishes exactly this, and it is live rather than inert. ADR-0025 D1 separates the two things that look alike:
promo_slot (ADR-0004) | offer (ADR-0025) | |
|---|---|---|
| Whose content | Third party | The vendor's own |
| Compliance risk | Real — a restricted vertical may not carry it | None — advertising your own service is ordinary commerce |
| Status | Inert, fails closed forever | Live |
An agent's launch offer is a first-party offer, so it carries no compliance gate. And because it renders on one card, the agent's own, it needs no targeting, no tree and therefore no campaign primitive — which matters, since real_estate's composition is ['catalogue','party','schedule','location'] and does not include campaign. resolveOffers(card, now) is card-scoped by design.
⚠ The one real cost of pulling this into R1, stated before it is discovered: a TIME-BOUNDED offer is a render-time temporal gate, which ADR-0025 D2 calls "the hard part" because it collides with the edge cache. Its answer is a scheduled purge at offer boundaries via the outbox table (which exists), never a short TTL and never client-side rendering.
Recommendation, which avoids D2 entirely for R1: ship the launch/featured treatment as a manual flag the agent turns on and off, with no expiry date. No expiry means no render-time temporal gate, no scheduled purge, and no cache problem — and a solo agent managing a handful of listings is perfectly served by a toggle. Scheduled, self-expiring offers arrive with campaigns in R2, where D2's outbox machinery is already the plan.
⚠ This does not block the Store/Catalogue design. The Real estate · Sahyadri Properties demo profile exercises kind:'listing', absent stock and indicative pricing — all schema facts independent of co-broking. See design-system/store-catalogue-spec.md §10.1.