# GOAL — Complete PlusROI mode & soft-launch `with` for parallel double-entry

**Status:** active. **Owner spec:** ADR #020 + `docs/features/tenant-modes.md`.
This file is the durable definition of done. On every run, read it +
`BUILD-STATE.md`, then continue at the first unfinished phase/gate.

## Definition of done (all must be true)

1. **PlusROI mode is a complete workspace** — host-matched look, books-centric
   nav, and every write form Danielle, Rob, and Rian need for their real
   monthly work in the browser.
2. **Bowden Works is preserved and unbroken** — data, nightly parity
   rehearsal, and its own look all keep working exactly as today.
3. **PlusROI is app-owned** — seeded fresh from
   `/home/rian/PlusROI + Bowden Works Bookkeeping _ Revenue _ Expenses _ Invoices.xlsx`,
   the nightly sheet-rebuild OFF for it, in-app writes ON. The app is the
   system of record for PlusROI.
4. **Every persona scenario (below) passes a real browser test** — via view-as
   for Danielle and Rob; directly as Rian.
5. Suites green, deployed, `srv-gw security-audit` clean, docs updated per the
   project definition of done, and a one-page **parallel-run playbook** for
   Danielle/Rob/Rian delivered.
6. **Soft launch, not cutover:** Rian runs this in parallel with the sheet via
   manual double-entry for a month. Cutover later changes NOTHING in the app —
   it only means the double-entry stops.

## Guardrails

Single-writer on migrations / `services/money` / transforms · the diff harness
stays GREEN · **the stable-identity core + all money-path work run on the Fable
model** · never break Bowden Works · no secrets in chat · Supabase is
export-only · **no `if(tenant)` in any component** (all via the WorkspaceProfile)
· docs-first (ADR + feature doc before code) for substantive features · every
phase ends deployed + tests green + BUILD-STATE updated.

## Phases (in order — each ends with its gate)

### Phase 1 — Presentation (in flight)
WorkspaceProfile scaffold + PlusROI theme/shell/nav (`docs/features/tenant-modes.md`).
**Gate:** flipping the Books switcher re-skins the whole app to the hosting look
with a books-centric nav; Bowden Works looks unchanged; rian eyeballs it.

### Phase 2 — Stable identity + app-owned flip (FABLE; harness-gated core)
- Legacy transform preserves **party identities across rebuilds** (upsert-by-slug,
  stable uuids); tenant-scope the row-clears so an app-owned tenant survives the
  nightly BW rebuild.
- `books_owner` (`sheet`|`app`): sheet importer skips `app` tenants; the
  invoice/expense write-block keys on `sheet`.
- One **fresh final import** from the provided file → flip PlusROI to `app`.
- **Gate:** harness GREEN; a simulated BW nightly rebuild leaves PlusROI's
  invoices/expenses/projects/parties fully intact; settlement gate GREEN (32/32);
  shared entities (Adi, Heather, Bowden Works) keep one identity across tenants.

### Phase 3 — Write forms (each to existing tables; owner/role-gated; audited)
- **Clients + Contacts** — client form (org address/phone + defaults: friendly/
  official name, credit limit, currency, commission owner+%, invoice timing,
  terms); **contacts = person records linked to the client via a `cc_recipient`
  affiliation** (email on the contact, not the org), created inline.
- **Vendors** — thin create/manage.
- **Projects** with the corrected **recurrence model** (recurring y/n + cycle +
  billing timing Month-End/Mid-Month — not the sheet's conflated "type") **and
  milestone schedules** for non-recurring (deposit / milestone / final with
  amounts); inherits the client's defaults.
- **Invoice generation from a project** — single + batch; recurring → one
  Pending-Approval invoice per cycle (amount defaults from the project, editable
  per-invoice WITHOUT changing the project default); non-recurring milestones →
  generate all at once; status lifecycle **Pending Approval → Ready to Invoice →
  Invoiced (log external QuickBooks #) → Paid**; **USD payment → record the
  realized CAD collected amount** at Paid.
- **Expenses** — manual entry (vendor, project, amount, category, paid-by);
  **multi-line / per-project entry** (Yulia's split invoice); the **CC extractor
  extended to PlusROI** with **per-user batch privacy** (Rob sees only his
  batches) + "move into PlusROI shared expenses."
- **Settlement "apply to month"** write action (tag paid invoices + unapplied
  expenses to a settlement month); the settlement panel already computes split +
  copy-lines.
- **Gate:** every form round-trips real data; nothing leaks across tenants, or
  (for CC batches) across users.

### Phase 4 — Persona acceptance in the browser (the real gate)

**Danielle (view-as):**
1. **Month-end recurring batch:** Projects → filter to active **recurring** +
   **Month-End** → per project "create invoice" → each lands **Pending Approval**.
2. **Ready → Invoiced:** take the **Ready to Invoice** batch, record each
   QuickBooks #, set **Invoiced**.
3. **USD payment:** a USD invoice paid → record the **CAD collected** → **Paid**.
4. **Transcribe Yulia:** split-by-project invoice → **multiple expense rows**,
   one per project, vendor = Yulia.

**Rob (view-as):**
1. **New client via a commission owner** (Customer First Design): full info incl.
   address **+ 2 new CC contacts** (name + email).
2. **New project "Monthly PPC":** monthly recurring, Mid-Month, default **$1,500**;
   generate the **first** invoice and correct it to **$2,000** — next month still
   defaults to $1,500.
3. **CC expenses:** CC extractor (TD) → filter his PlusROI charges, categorize,
   move some into **PlusROI shared expenses**; sees **only his own** batches.

**Rian (direct):**
1. **New website project** for an existing client, **$5,000 CAD** as **$1,000
   deposit + $2,000 milestone + remainder on completion**; non-recurring;
   **generate all 3 invoices at once** (Pending Approval); set the deposit to
   **Ready to Invoice**.
2. **Month-end settlement:** CC-tool his expenses into PlusROI, port **Bowden
   Works Team** expenses in, filter to **paid** invoices and **apply** to the
   month, apply the **unapplied** expenses, then read the computed **split +
   team/PPC/other** lines and copy into Wave.

## Model policy
Presentation + forms on the standard model; **Phase 2 (stable-id core) + any
`services/money` change on Fable** (delegate to Fable-model agents; keep
orchestrating on the current model — never block on a model switch).

## New scope surfaced by the personas (all additive to existing tables)
milestone invoice schedules · USD-payment realized-FX (collected CAD) · per-user-
private CC batches · invoice generation from projects · recurrence model
(recurring/cycle/timing) · contacts with a `cc_recipient` affiliation.

## On completion
Deploy · `srv-gw security-audit` · update CHANGELOG / BUILD-STATE / feature docs /
ADRs · deliver the parallel-run playbook · report the soft-launch state.