JLaborda · Oct 14, 2026 · Oct 14, 2026
diff --git a/.cursor/rules/domain.md b/.cursor/rules/domain.md
@@ -14,30 +14,35 @@ How the engineering skills should consume this repo's domain documentation when
 ## Before exploring, read these
 
 - **`CONTEXT-MAP.md`** — domains, relationships, delivery sequencing, Sources.
-- **Domain glossary** — investing: `CONTEXT.md`; credit: `credit/CONTEXT.md`.
+- **Domain glossary** — investing: `investing/CONTEXT.md`; credit: `credit/CONTEXT.md`.
 - **`docs/adr/`** — architectural decision records for cross-cutting choices (including ADR-0003 Phase 2 QV cancelled).
-- **Investing:** `docs/mvp/architecture/architecture.md` (frozen historical vision) and `docs/mvp/features/<feature>.md` when changing investing.
+- **Investing:** `investing/docs/architecture/architecture.md` (frozen historical vision) and `investing/docs/features/<feature>.md` when changing investing.
 - **Credit:** `credit/docs/` feature specs when present; `credit/README.md` for domain entry.
 
 If a CONTEXT file or `docs/adr/` does not exist yet, **proceed silently**. Do not flag their absence or suggest creating them upfront.
 
-Do not treat `src/` or `notebooks/` as canonical architecture for new domains; see `AGENTS.md`.
+Do not treat root `notebooks/` as canonical architecture for new domains; see `AGENTS.md`.
 
 ## File structure
 
 ```
 /
 ├── CONTEXT-MAP.md             ← portfolio domains + relationships
-├── CONTEXT.md                 ← investing ubiquitous language
-├── investing/README.md
+├── investing/
+│   ├── CONTEXT.md             ← investing ubiquitous language
+│   ├── README.md
+│   ├── docs/                  ← investing demo specs
+│   ├── src/investing/         ← investing package
+│   ├── apps/dashboard/
+│   └── tests/
 ├── credit/
 │   ├── CONTEXT.md             ← credit / CSS ubiquitous language
 │   ├── README.md
-│   └── docs/                  ← credit feature specs
-├── docs/
-│   ├── adr/                   ← system-wide ADRs
-│   └── mvp/                   ← investing demo specs (delivered / frozen vision)
-└── src/                       ← investing demo implementation (migrate later)
+│   ├── docs/                  ← credit feature specs
+│   ├── src/credit/
+│   └── tests/
+└── docs/
+    └── adr/                   ← system-wide ADRs
 ```
 
 ## Use CONTEXT vocabulary

diff --git a/.cursor/rules/issue-tracker.md b/.cursor/rules/issue-tracker.md
@@ -22,12 +22,12 @@ Infer the repo from `git remote -v` — `gh` does this automatically when run in
 
 | Layer | Where | Role |
 | --- | --- | --- |
-| **Investing specs (canonical)** | `docs/mvp/features/*.md`, `docs/mvp/architecture/architecture.md` | Investing product/engineering truth; update before closing investing work |
+| **Investing specs (canonical)** | `investing/docs/features/*.md`, `investing/docs/architecture/architecture.md` | Investing product/engineering truth; update before closing investing work |
 | **Credit specs (canonical)** | `credit/docs/` (see `CONTEXT-MAP.md`) | Credit / CSS product/engineering truth; update before closing credit work |
 | **GitHub issues** | This repo's GitHub Issues | PRDs, vertical slices, and triage for Matt Pocock engineering skills (`to-issues`, `to-prd`, `triage`) |
-| **Notion tasks** | Board `Cursor Agent Tasks` | Optional execution tracking via Notion MCP; see `AGENTS.md` and `docs/mvp/NOTION_SETUP.md` |
+| **Notion tasks** | Board `Cursor Agent Tasks` | Optional execution tracking via Notion MCP; see `AGENTS.md` and `investing/docs/NOTION_SETUP.md` |
 
-When a skill publishes to the issue tracker, create or update a **GitHub issue**. Link the relevant spec path (`docs/mvp/features/...` or `credit/docs/...`) in the issue body. Do not treat Notion as the issue tracker for those skills unless the user explicitly asks to sync there.
+When a skill publishes to the issue tracker, create or update a **GitHub issue**. Link the relevant spec path (`investing/docs/features/...` or `credit/docs/...`) in the issue body. Do not treat Notion as the issue tracker for those skills unless the user explicitly asks to sync there.
 
 ## When a skill says "publish to the issue tracker"
 

diff --git a/.cursor/rules/mvp-docs.mdc b/.cursor/rules/mvp-docs.mdc
@@ -1,16 +1,16 @@
 ---
-description: MVP Markdown spec structure and editing conventions
-globs: docs/**
+description: Investing Markdown spec structure and editing conventions
+globs: investing/docs/**
 alwaysApply: false
 ---
 
-# MVP documentation conventions
+# Investing documentation conventions
 
-When creating or editing specs under `docs/mvp/`:
+When creating or editing specs under `investing/docs/`:
 
 ## Feature specs
 
-Follow the structure used in existing features (e.g. `docs/mvp/features/cheap-stocks.md`):
+Follow the structure used in existing features (e.g. `investing/docs/features/cheap-stocks.md`):
 
 - Objective
 - MVP scope / Out of MVP scope
@@ -23,7 +23,7 @@ Add **Implementation status** when coding starts: `planned` | `in_progress` | `d
 
 ## Architecture spec
 
-- Record closed decisions in tables (see "Decisions made so far" in `docs/mvp/architecture/architecture.md`).
+- Record closed decisions in tables (see "Decisions made so far" in `investing/docs/architecture/architecture.md`).
 - Cross-link feature files from the module table.
 - Do not contradict a closed architecture decision without updating the architecture doc first.
 

diff --git a/.cursor/rules/notion-tasks.mdc b/.cursor/rules/notion-tasks.mdc
@@ -5,14 +5,14 @@ alwaysApply: true
 
 # Notion task tracking
 
-**Git specs are canonical** (`docs/mvp/` for investing; `credit/docs/` for credit). Notion is for tasks and status only. Portfolio map: [`CONTEXT-MAP.md`](../../CONTEXT-MAP.md).
+**Git specs are canonical** (`investing/docs/` for investing; `credit/docs/` for credit). Notion is for tasks and status only. Portfolio map: [`CONTEXT-MAP.md`](../../CONTEXT-MAP.md).
 
 ## Task fields
 
 Each Notion task should include:
 
 - **Title:** e.g. `Feature: Cheap Stocks — implement EY rank` or `Credit: Application mart — EY-style WOE shortlist`
-- **Spec path:** investing → `docs/mvp/features/<feature>.md`; credit → `credit/docs/…` (e.g. `credit/docs/features/css-chapter5-mart-and-scoring.md`)
+- **Spec path:** investing → `investing/docs/features/<feature>.md`; credit → `credit/docs/…` (e.g. `credit/docs/features/css-chapter5-mart-and-scoring.md`)
 - **Notes:** copy acceptance criteria from the spec
 
 ## Sync discipline

diff --git a/.cursor/rules/project-context.mdc b/.cursor/rules/project-context.mdc
@@ -9,28 +9,28 @@ SmartWealthAI is a **portfolio monorepo** for finance engineering: **investing**
 
 ## Current phase
 
-- **Investing:** June 30 demo slice **delivered** ([`demo-slice.md`](../../docs/mvp/demo-slice.md)). Specs remain under `docs/mvp/`; code under `src/smartwealthai` until a migrate-only PR.
-- **Credit:** **Active next** — specs and new code under `credit/` ([`credit/CONTEXT.md`](../../credit/CONTEXT.md), `credit/docs/`).
+- **Investing:** June 30 demo slice **delivered** ([`demo-slice.md`](../../investing/docs/demo-slice.md)). Code and specs under `investing/` (`investing/src/investing/`, `investing/docs/`, `investing/CONTEXT.md`).
+- **Credit:** **Active** — specs and new code under `credit/` ([`credit/CONTEXT.md`](../../credit/CONTEXT.md), `credit/docs/`).
 - **Phase 2 Quantitative Value:** **cancelled** for active execution ([ADR-0003](../../docs/adr/0003-phase2-qv-cancelled.md)). Prefer updating specs over writing investing QV code.
 
 ## Canonical documentation
 
 - Portfolio map: `CONTEXT-MAP.md`
-- Investing glossary: `CONTEXT.md`
+- Investing glossary: `investing/CONTEXT.md`
 - Credit glossary: `credit/CONTEXT.md`
 - Domain READMEs: `investing/README.md`, `credit/README.md`
 - ADRs: `docs/adr/`
-- Investing demo slice: `docs/mvp/demo-slice.md`
-- Investing architecture (frozen vision): `docs/mvp/architecture/architecture.md`
-- Investing features: `docs/mvp/features/*.md`
-- Credit features (when present): `credit/docs/`
-- Requirements (historical): `docs/mvp/requirements/requirements.md`
-- Backlog: `docs/mvp/backlog/backlog.md`
+- Investing demo slice: `investing/docs/demo-slice.md`
+- Investing architecture (frozen vision): `investing/docs/architecture/architecture.md`
+- Investing features: `investing/docs/features/*.md`
+- Credit features: `credit/docs/`
+- Requirements (historical): `investing/docs/requirements/requirements.md`
+- Backlog: `investing/docs/backlog/backlog.md`
 
 ## Not canonical
 
-Do not use `notebooks/` as reference architecture. Do not treat investing `src/` layout as the template for credit — new credit code lands under `credit/`.
+Do not use root `notebooks/` as reference architecture. Domain packages live under `investing/src/investing/` and `credit/src/credit/`.
 
 ## Code changes
 
-Investing implementation changes must trace to a feature spec under `docs/mvp/features/` or the demo slice. Credit changes must trace to specs under `credit/docs/` (create the spec first). Read `CONTEXT-MAP.md` and the matching domain CONTEXT before proposing design or code.
+Investing implementation changes must trace to a feature spec under `investing/docs/features/` or the demo slice. Credit changes must trace to specs under `credit/docs/` (create the spec first). Read `CONTEXT-MAP.md` and the matching domain CONTEXT before proposing design or code.
diff --git a/.cursor/rules/spec-driven-workflow.mdc b/.cursor/rules/spec-driven-workflow.mdc
@@ -8,10 +8,10 @@ alwaysApply: true
 ## Before coding
 
 1. Name the feature spec file:
-   - Investing: `docs/mvp/features/<feature>.md` (e.g. `cheap-stocks.md`)
+   - Investing: `investing/docs/features/<feature>.md` (e.g. `cheap-stocks.md`)
    - Credit: under `credit/docs/` (e.g. `credit/docs/features/css-chapter5-mart-and-scoring.md`)
 2. Read domain constraints:
-   - Investing: `docs/mvp/architecture/architecture.md` (frozen historical vision; point-in-time data, exclusions, MLflow, paper trading, universe rules)
+   - Investing: `investing/docs/architecture/architecture.md` (frozen historical vision; point-in-time data, exclusions, MLflow, paper trading, universe rules)
    - Credit: `credit/CONTEXT.md` + `CONTEXT-MAP.md` (+ the feature spec)
 3. If scope is unclear, ask the user and record the answer in the spec (open questions or decisions tables).
 

diff --git a/.github/workflows/pr-ci.yml b/.github/workflows/pr-ci.yml
@@ -40,7 +40,7 @@ jobs:
       - name: Test with coverage
         # Match [tool.coverage.run]: both packages + branch=true (mixing CLI
         # statement-only --cov with pyproject branch data fails combine).
-        run: poetry run pytest --cov=smartwealthai --cov=credit --cov-branch --cov-report=term-missing --cov-report=xml
+        run: poetry run pytest --cov=investing --cov=credit --cov-branch --cov-report=term-missing --cov-report=xml
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5

diff --git a/AGENTS.md b/AGENTS.md
@@ -8,31 +8,31 @@ SmartWealthAI is a **portfolio monorepo** (investing + credit; fraud later). See
 
 | Domain | Status |
 | --- | --- |
-| **Investing** (Magic Formula demo) | **Delivered** (v0.1.0). Specs under `docs/mvp/`; code still under `src/smartwealthai` until a migrate-only PR. |
+| **Investing** (Magic Formula demo) | **Delivered** (v0.1.0). Code and specs under `investing/` (`investing/src/investing/`, `investing/docs/`, `investing/CONTEXT.md`). |
 | **Credit** (CSS) | **Active next.** Specs and new code under `credit/` (`credit/docs/`, `credit/CONTEXT.md`). |
 | **Phase 2 Quantitative Value** | **Cancelled** for active execution ([ADR-0003](docs/adr/0003-phase2-qv-cancelled.md); branch `archive/phase2-qv`). |
 
-Investing changes must align with a feature spec in `docs/mvp/features/` and [`docs/mvp/architecture/architecture.md`](docs/mvp/architecture/architecture.md) (frozen historical vision — not a live QV north star). Credit changes align with specs under `credit/docs/`.
+Investing changes must align with a feature spec in `investing/docs/features/` and [`investing/docs/architecture/architecture.md`](investing/docs/architecture/architecture.md) (frozen historical vision — not a live QV north star). Credit changes align with specs under `credit/docs/`.
 
-Do not treat `src/` or `notebooks/` as canonical architecture for new domains; investing code there is the demo delivery, not a template to copy for credit.
+Do not treat root `notebooks/` as canonical architecture. Domain code lives under `investing/src/investing/` and `credit/src/credit/`.
 
 ## Documentation map (source of truth)
 
 | Path | Purpose |
 | --- | --- |
 | `CONTEXT-MAP.md` | Portfolio domain map, relationships, delivery sequencing |
-| `CONTEXT.md` | Investing ubiquitous language (until moved to `investing/CONTEXT.md`) |
+| `investing/CONTEXT.md` | Investing ubiquitous language |
 | `credit/CONTEXT.md` | Credit / CSS ubiquitous language |
 | `investing/README.md` | Investing domain entry (manager-facing) |
 | `credit/README.md` | Credit domain entry (manager-facing) |
 | `credit/docs/` | Credit feature specs (when present) |
 | `docs/adr/*.md` | Architecture Decision Records (hard-to-reverse choices) |
-| `docs/mvp/demo-slice.md` | Investing June 30 demo slice (delivered) |
-| `docs/mvp/architecture/architecture.md` | Investing MVP vision (frozen; see ADR-0003) |
-| `docs/mvp/features/*.md` | Investing per-module specs |
-| `docs/mvp/requirements/requirements.md` | Sprint 0 spike (historical) |
-| `docs/mvp/backlog/backlog.md` | Informal ideas mapped to investing features |
-| `docs/README.md` | Index of the `docs/` tree |
+| `investing/docs/demo-slice.md` | Investing June 30 demo slice (delivered) |
+| `investing/docs/architecture/architecture.md` | Investing MVP vision (frozen; see ADR-0003) |
+| `investing/docs/features/*.md` | Investing per-module specs |
+| `investing/docs/requirements/requirements.md` | Sprint 0 spike (historical) |
+| `investing/docs/backlog/backlog.md` | Informal ideas mapped to investing features |
+| `docs/README.md` | Index of root `docs/` (ADRs) and pointers to domain docs |
 
 See also `.cursor/rules/*.mdc` for persistent agent guidance.
 
@@ -42,8 +42,8 @@ Write all code, comments, docstrings, documentation, commits, and PR text in **E
 
 ## Spec-driven workflow
 
-1. Identify the feature spec: investing → `docs/mvp/features/<feature>.md`; credit → `credit/docs/` (when present).
-2. Read the matching architecture/context: investing → `docs/mvp/architecture/architecture.md` + `CONTEXT.md`; credit → `credit/CONTEXT.md` + `CONTEXT-MAP.md`.
+1. Identify the feature spec: investing → `investing/docs/features/<feature>.md`; credit → `credit/docs/` (when present).
+2. Read the matching architecture/context: investing → `investing/docs/architecture/architecture.md` + `investing/CONTEXT.md`; credit → `credit/CONTEXT.md` + `CONTEXT-MAP.md`.
 3. Resolve open questions in the spec; record decisions in the spec or ADR.
 4. Implement only what the spec allows for the current phase.
 5. After implementation, update the feature spec (implementation status, acceptance criteria, links to code when it exists).
@@ -86,7 +86,7 @@ export SIMFIN_API_KEY="<from user secrets>"
 poetry run download-simfin
 ```
 
-Spec: [`docs/mvp/features/etl-data-lake.md`](docs/mvp/features/etl-data-lake.md). Operator guide: [`docs/mvp/guides/download-simfin.md`](docs/mvp/guides/download-simfin.md). Delivery target: [`docs/mvp/demo-slice.md`](docs/mvp/demo-slice.md).
+Spec: [`investing/docs/features/etl-data-lake.md`](investing/docs/features/etl-data-lake.md). Operator guide: [`investing/docs/guides/download-simfin.md`](investing/docs/guides/download-simfin.md). Delivery target: [`investing/docs/demo-slice.md`](investing/docs/demo-slice.md).
 
 ### Fundamentals — SEC spike (frozen)
 
@@ -95,7 +95,7 @@ export SEC_IDENTITY="Your Name your@email.com"
 poetry run download-fundamentals --universe dow30
 ```
 
-Guide: [`docs/mvp/guides/download-fundamentals.md`](docs/mvp/guides/download-fundamentals.md).
+Guide: [`investing/docs/guides/download-fundamentals.md`](investing/docs/guides/download-fundamentals.md).
 
 ## Gotchas
 
@@ -107,7 +107,7 @@ Guide: [`docs/mvp/guides/download-fundamentals.md`](docs/mvp/guides/download-fun
 
 ## Notion (task tracking)
 
-Git specs are canonical (`docs/mvp/` for investing; `credit/docs/` for credit). Notion tracks execution tasks only. Setup: [`docs/mvp/NOTION_SETUP.md`](docs/mvp/NOTION_SETUP.md).
+Git specs are canonical (`investing/docs/` for investing; `credit/docs/` for credit). Notion tracks execution tasks only. Setup: [`investing/docs/NOTION_SETUP.md`](investing/docs/NOTION_SETUP.md).
 
 ### Default task board
 
@@ -119,7 +119,7 @@ Git specs are canonical (`docs/mvp/` for investing; `credit/docs/` for credit).
 
 Agents must use the Notion MCP server (authenticated in **Cursor → Settings → MCP**) to find and update this board. Search the workspace for `Cursor Agent Tasks` before creating or editing tasks. Do not ask the user to commit a Notion URL to the repository.
 
-Each task should reference a spec path (e.g. `docs/mvp/features/universe-construction.md` or `credit/docs/…`) and copy acceptance criteria from that spec. When a task completes, update the Git spec first, then mark the Notion task done.
+Each task should reference a spec path (e.g. `investing/docs/features/universe-construction.md` or `credit/docs/…`) and copy acceptance criteria from that spec. When a task completes, update the Git spec first, then mark the Notion task done.
 
 **Skills (after MCP auth):** `spec-to-implementation`, `create-task`, `tasks-build`, `tasks-explain-diff`. For `tasks-build`, the user supplies a single task URL in chat (not in this file).
 
@@ -139,4 +139,4 @@ Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-
 
 ### Domain docs
 
-Portfolio map: `CONTEXT-MAP.md`. Investing glossary: `CONTEXT.md`. Credit glossary: `credit/CONTEXT.md`. ADRs in `docs/adr/`. See [`.cursor/rules/domain.md`](.cursor/rules/domain.md).
+Portfolio map: `CONTEXT-MAP.md`. Investing glossary: `investing/CONTEXT.md`. Credit glossary: `credit/CONTEXT.md`. ADRs in `docs/adr/`. See [`.cursor/rules/domain.md`](.cursor/rules/domain.md).