Broker's playbook —
running your state on the Rebato platform.

Broker verification is the gate that unlocks every supervisory action you will take on the platform. We verify your real estate license against the issuing state regulator before granting any role — there is no "trust us" path. The flow is built so that approval can be either fully manual (a Rebato compliance reviewer cross-checks the state regulator website by hand) or fully automated (the platform calls a state API adapter and the result is recorded), with the same audit guarantees in both modes.

• 1.1 Apply at /auth/signup-broker. The form collects your work email, password, full legal name, the state where you hold an active license, your license number, your license type (designated or managing), and the brokerage name — either an existing brokerage you are joining or a new one you are registering. The form is intentionally small; deeper KYC happens in the review step.
• 1.2 License goes into pending_verification. Submission writes a license row with status pending_verification, an empty role_assignment (so you cannot transact yet), and a BROKER_SIGNUP_SUBMITTED event in the hash-chained compliance_event_log. From the moment you submit, the regulator's audit trail starts.
• 1.3 Platform admin reviews at /admin/licenses. A Rebato compliance reviewer opens your record and chooses one of two paths:Manual: Open the state regulator website (e.g., dol.wa.gov for WA, dre.ca.gov for CA, dos.ny.gov for NY) and search by your license number. Confirms that the holder name matches the application and the status is active.Auto-verify (when an adapter exists for your state): Reviewer clicks "Auto-verify". Behind the scenes the platform calls LicenseAutoVerificationService.verifyLicenseAgainstState({state, licenseNumber, holderName}) which returns one of active / expired / suspended / revoked. The raw response is hashed and stored next to your license record.
• 1.4 Approval grants your role. When the reviewer clicks "Approve", three things happen in a single transaction: your license row flips to verified, your role_assignment gets a designated_broker (or managing_broker) row, and the audit log gets two events — BROKER_VERIFIED and ROLE_GRANTED — both chained to your earlier signup event.
• 1.5 Sign in to the /brokers portal. You receive an email with the activation link. From this point on, every login, every page visit inside /brokers, and every supervisory action you take is scoped to the states where you hold an active license — checked at request-time, not at signup-time.
• 1.6 Rejection: explained, recoverable. If something is off — name mismatch, license suspended, wrong state — the reviewer rejects with a written reason. Your license row goes to revoked status and the reason is stored. You can re-apply at /auth/signup-broker with corrected information; the new application is a separate event in the audit chain.

Once verified, the rest of your supervisory powers come online. Everything below assumes you are signed in to /brokers with an active broker role.

The dashboard is the home base for your daily work. Layout is a left-hand sidebar (Dashboard / Agents / Sponsorships / Listings / Member firm site / Back to public site) with your active state(s) shown as a badge in the header so you always know which scope you are operating in. The center is a 4-card KPI grid plus a list of common quick actions.

The four KPI cards

Below the KPIs is a quick-actions strip — "Approve next pending sponsorship", "Open today's listings", "Edit member firm site". Each one deep-links into the right page so you don't hunt through the sidebar.

This is the work you do most. /brokers/sponsorships lists every pending agent application that wants you as their sponsoring broker. The page is intentionally a single table with no clever filtering — pending stays in front of you until you approve or reject.

What you see for each row

Agent name, work email, the state they applied in (which must match a state where you hold an active license — applications outside your scope never reach you), license number, license type, and the date they submitted. If Platform admin has already auto-verified the license, you also see an "auto-verified" badge so you can skip the manual cross-check.

Verify their license

If the auto-verify badge is missing, you do a quick manual cross-check: open the state regulator's lookup, search by license number, confirm the name matches and the status is active. This usually takes under 60 seconds. If your state has an adapter and you'd rather wait, the daily pnpm worker:license-verification worker will run overnight and the badge will appear next morning.

Approve — what happens

• Sponsorship activates. The sponsorship row flips to status='active' with started_at = now().
• Role granted. A role_assignment row of type agent_internal is created — this is what unlocks the agent's portal access.
• Audit log written. Two chained events: AGENT_SPONSORED and ROLE_GRANTED, both with actor_user_id = your user id so the regulator can see who approved.
• Welcome email sent. The agent gets a transactional email confirming approval and pointing them to the agent portal sign-in.

Reject — what happens

Click "Reject", enter a reason in the dialog (required, free-form text). The sponsorship row flips to status='rejected' with rejection_reason stored and rejected_at = now(). An AGENT_SPONSORSHIP_REJECTED event is appended to the audit chain. The agent receives an email with the reason and can re-apply to a different broker — your rejection does not blacklist them platform-wide.

/brokers/agents is the roster of agents currently active under your sponsorship. Think of it as the hiring manager view, with a row per agent and a few essential signals at a glance.

• Per-agent row. Name, work email, license number, sponsorship start date, and current status (active or inactive — inactive means the sponsorship is paused but not ended).
• Drill-down (v2). Click an agent to see their detail page. Today this is read-only — listings they own, offers they have written, BBAs they have signed. Editing capabilities (rename, reassign, set targets) arrive in v2.
• License expiry alerts (v2). The daily pnpm worker:license-verification run flags agents whose license expires within 60 days. In v2 these surface on your dashboard with a "Remind agent" action; today the worker just records the flag.
• Revoke sponsorship. When an agent leaves (or you need to end the relationship), click "End sponsorship". The sponsorship row goes to status='ended' with ended_at set, the agent's agent_internal role_assignment is revoked, and they can no longer transact. They keep the historical record of their past work; nothing is hard-deleted.

/brokers/listings shows every listing whose subject property is in a state where you hold an active license. The list mixes two origin types — listings created by your own agents and listings flowing in from MLS feeds — with a clear badge so you can tell which is which.

• Origin types. Listings tagged OWN_BROKERAGE are created by agents you sponsor. Listings tagged MLS_SYNDICATED come from an external feed (Bridge / Trestle / MLSGrid). You supervise the former; the latter you mostly watch for compliance flags.
• Approve-publish (v2). Today, listings created by your agents auto-publish after passing the steering language and state policy gates. In v2 you can flip your firm into "broker review required" mode — drafts wait for your approval before going public.
• Compliance flags queue. Any listing that our re-scanner finds suspect (a steering phrase that slipped through the first scan, a price drop pattern that hits state anti-flipping flags, an iBuyer resale on day 89) lands in your review queue. You either dismiss with a comment or send back to the agent for rewording.
• Cross-state listings are invisible. If you hold WA + OR but a listing is in CA, you don't see it here — the query is filtered at the database layer. There is no toggle to "show all"; cross-state visibility requires cross-state licenses.

Each member firm has its own public site under your state subdomain (wahomerebate.com if you're WA, cahomerebate.com if you're CA, and so on). The site is yours to brand and customize — but it sits on the same shared backbone, so compliance gates and the audit trail apply identically.

Publish flow

Hitting publish runs the change through three checks: state policy resolver (does the text comply with your state's mandatory disclosures?), steering language NLP scanner (Fair Housing — Gate 6), and the hash-chain audit append (the event is TENANT_SITE_PUBLISHED with a snapshot hash of your draft). On success the cache is invalidated via revalidateTag; the public site updates within ~60 seconds globally.

The single most important defensive property of the broker portal is that you cannot accidentally — or even deliberately — operate outside your licensed states. We enforce this at three layers; you would have to compromise all three to violate it.

• Code-level guard. Every supervisory handler calls assertBrokerStateScope_I_VERIFIED_STATE_OWNS({brokerStates, resourceState}) before reading or writing. The deliberately awkward function name is per our naming-as-audit rule — anyone reviewing the code sees instantly that this call is the gate.
• DB-level filtering. Queries on listing, offer, sponsorship, and agent tables auto-append WHERE state_or_province IN (your_active_license_states). There is no "admin override" parameter on these handlers — to bypass the filter you would need a code change, code review, and an audit event explaining why.
• UI-level visibility. The sidebar of /brokers shows only the states where you have active licenses. State badges in the header tell you exactly which scope is active in the current view. Unlicensed-state listings are not "hidden"; they are not loaded.
• Audit fingerprint. Every approve, reject, and edit writes actor_user_id = you into the event. State regulators reading the audit chain can reconstruct every decision you made, in order, with the exact policy version that was active when you made it.

Eleven gates govern every transactional action on the platform. You don't write them — Rebato does. But they are what makes your supervisory job tractable: instead of policing each agent in real time, you let the gates auto-enforce and only intervene on exceptions.

• Gate 1 (BBA hard gate). Your agent cannot tour a buyer who has not signed a Buyer Broker Agreement. The system blocks the scheduling API; you don't need to chase it.
• Gate 6 (steering language). If your agent's listing description contains discriminatory phrases ("perfect for families", "exclusive Christian community"), publish fails before the listing goes live. The queue surfaces it for your review.
• Gate 7 (state policy). Rebate calculations consult the per-state policy table. In states where buyer rebates are banned, the calculator returns zero with an explanation. Restricted-disclosure states require an extra signed disclosure form, which the system enforces.
• Gate 8 (transaction-time license recheck). Every offer submission, every BBA signature, every closing re-checks your agent's license against the live licensing record. If the license expired mid-transaction, the system pauses the workflow and notifies you instead of letting an unlicensed transaction proceed.
• Gate 9 (audit log). Every action you and your agents take — approvals, rejections, sponsorship changes, listing edits — is appended to the hash-chained audit log. UPDATE and DELETE on this table are blocked by a database trigger; nightly export to S3 with Object Lock makes it WORM.

When a state regulator audits you, you don't scramble. You query compliance_event_log filtered to your brokerage_state_registration_id, export the result, and hand it over. Every BBA, every offer, every rebate, every supervisory action — dated, hashed, signed by the actor.

• License auto-verification times out. If the state regulator's API is down or returns an indeterminate response, you can still manually verify and approve from /brokers/sponsorships. Platform admin sees both the failed auto-verify attempt and your manual override in the audit chain.
• Steering language listing in queue. Open it from the compliance flags queue, read the flagged passage, and either dismiss (with a comment if you disagree with the flag) or send back to the agent with a requested rewording. The agent gets the comment in their portal.
• Cross-state attempt. If a deep link or stale tab tries to load a resource outside your scope, the API returns AccessDeniedError 403. The attempt is logged with your user id so it shows up in audits, but the data doesn't leak.
• Mass revocation by Platform admin. If a firm-level compliance issue is found, Platform admin can revoke all sponsorships under your brokerage in one action. Every affected agent loses agent_internal instantly. You receive notification, but the action is theirs to take and yours to answer for in the regulator hearing.

• Daily routine. 9am — open /brokers/sponsorships and clear pending approvals. 11am — open /brokers/listings and skim new drafts. End of day — read the audit summary on the dashboard.
• Delegate to managing brokers. Managing brokers have the same day-to-day permissions as you, but their scope can be narrower (a sub-team or region within your state). Use them as your team leads.
• Templated rejection reasons. Most sponsorship rejections fall into a small handful of buckets: name mismatch, license inactive, wrong state, inadequate experience for the role applied. Save 4–5 templates; paste, edit, send.
• Subscribe to the compliance digest (v2). A weekly summary of flags, rejections, near-expiry licenses, and policy changes affecting your state. Saves you from polling the dashboard.