# AMS — Commercial Vision & Strategic Roadmap

**Date:** 2026-05-17
**Status:** Living document — update as the vision sharpens
**Owner:** James (vision) · Claude (drafting) · Team (execution)
**Sibling docs:** [AMS-INTEGRATION-PLAN-v1.md](AMS-INTEGRATION-PLAN-v1.md) · [AMS-ARCHITECTURE-DIAGRAMS.md](AMS-ARCHITECTURE-DIAGRAMS.md) · [UNIFIED-FRAMEWORK-v1.md](UNIFIED-FRAMEWORK-v1.md)

---

## Executive summary

AMS is being built as an **internal POC today**, with a clear evolution path to a **commercial SaaS product** sold per-service on a free-trial → paid-subscription model, eventually supporting **multi-broker connectivity** for independent traders.

**The good news:** ~80% of the architecture we've already shipped supports this vision without rewrites. Plug-and-play sources, the service entitlement registry, the three-namespace isolation, the identity helper, and the audit log were all chosen with this future in mind.

**This document captures:** (1) where we are, (2) the vision, (3) the five evolution stages, (4) the architectural pillars that carry us there, (5) the cohesive-shell + two-zone launcher + service-detail + team-view UX vision, (6) the org/billing model for commercial, and (7) what to decide NOW vs LATER.

---

## § 1 — Where we are today

| Layer | Status |
|---|---|
| Auth (login/logout/session/2FA-ready) | ✅ Live, working |
| Invite-only signup | ✅ Live (admin issues invite via email + URL fallback) |
| Service registry (`ams.services`) | ✅ 11 services seeded, 1 live (Accountability HUD) |
| Per-user entitlements (`ams.user_service_access`) | ✅ Live, with `expires_at` nullable for ∞ access |
| License keys table (`ams.license_keys`) | ✅ Schema exists, no UI yet |
| Admin UI (users, teams, invites) | ✅ Live |
| Service launcher (`/ams/app/`) | ✅ Single-zone grid; cards = entitled services + locked planned services |
| Public landing (`/ams/index.html`) | ✅ Live, no auth, marketing copy |
| Plug-and-play trade sources | ✅ TradeSource ABC + AccountabilitySource concrete; 4 placeholder source rows |
| Audit log | ✅ Every auth/admin event logged |
| Email send | ✅ Works (PHP `mail()`); DKIM not yet repaired; works in spam-tolerant flows |

What's NOT yet wired (the gap to vision):
- Cohesive shell wrapping legacy surfaces (HUD, MGP, Scorecards still open in new tab)
- Two-zone launcher (active services up top, catalog below)
- Per-service detail/marketing pages
- Team view per service (who else uses this)
- Trial / paid grant lifecycle (the `trial_days` + self-signup flow we just discussed)
- License management UI (currently splash)
- Org / tenancy model (single firm today; no orgs yet)
- Payment integration (Stripe)
- Public registration (currently invite-only)

---

## § 2 — The vision in one paragraph

AMS becomes a **unified trading-operations platform** where every service (HUD, Scorecards, MGP, Playbooks, Param Surface, MTF VP, Daily Stop, Strategy Library, Monthly Reports, etc.) is wrapped in a consistent AMS shell, presented as a catalog where each card describes the service in detail. Users sign up per-service (free trial → paid subscription), with admins able to grant complimentary or unlimited access. Multi-broker connectivity (E*TRADE, IB, TOS, MZQ Proxy, …) means each trader can wire their own accounts in and use AMS as their unified accountability layer, independent of which broker they execute through. For B2B sales, AMS supports orgs (trading firms) that subscribe and add users; for B2C, individual traders subscribe per-service.

---

## § 3 — Five evolution stages

| Stage | What ships | Customers | Pricing |
|---|---|---|---|
| **1. POC** (today) | Internal team uses AMS w/ Accountability HUD via legacy cockpit + admin UI | Domino Trading (6 users, internal) | Free |
| **2. Internal hardened** (next 4-8 weeks) | Cohesive shell wraps all surfaces · two-zone launcher · service detail pages · trial/admin-grant flow · DKIM fix | Domino Trading internal | Free |
| **3. Closed beta** (1-2 months out) | Public landing + invite-only beta sign-up · free trials per service · feedback loop | Trusted friends / external traders (10-50 invites) | Free with admin-issued trials |
| **4. Public launch — free tier + paid** | Public registration · Stripe integration · free / Pro / Team / Enterprise plans · subscription lifecycle | Anyone | Free tier limited + paid SKUs |
| **5. Multi-broker self-service** | Brokers as plug-in adapters (E*TRADE/IB/TOS/MZQ Proxy) · OAuth per broker · per-broker license · enterprise SSO | Individual traders + firms across brokers | Per-service, per-broker, per-org |

Each stage uses the same data model and code — adds tables / endpoints rather than rewriting existing.

---

## § 4 — Architectural pillars that already carry us there

These design choices were deliberately made for vision-readiness:

| Pillar | Decision | Vision-readiness |
|---|---|---|
| **Plug-and-play trade sources** | ADR-0002 — `TradeSource` ABC + DB-driven registry | Multi-broker = drop one .py file + INSERT one row. E*TRADE / IB / TOS / MZQ all already mocked. |
| **Service entitlement registry** | `ams.services` + `ams.user_service_access` | Per-user, per-service, per-time-window grants. Already supports free / paid / trial / unlimited via existing fields. |
| **Three isolation namespaces** | `/gt_dev/ams/` · `/z/logs/ams/` · `ams.*` schema | Easy to fork for white-label / multi-region / commercial-tier separation later. |
| **Identity function** | `main.resolve_identity(account_id)` | Works the same regardless of source — bridges any broker's account_id to a user. |
| **Team/group model** | `main.teams` + `main.groups` + `main.user_groups` | Same model fits internal team OR external customer org with sub-teams (desks/cohorts). Just add `org_id` later. |
| **Audit log** | Every auth/admin/sensitive event → `main.audit_logs` | Compliance / GDPR / SOC2 foundation already laid. |
| **Invite-only flow** | `ams.team_invitations` w/ token_hash + expiry + status | Works for both internal AND closed-beta rollout. Public registration is an additional flow, not a replacement. |
| **AMS shell** | `_shell/header.php` server-rendered | Adding cohesive wrap to legacy surfaces is "include header.php at the top + iframe/embed below" — no SPA needed. |

---

## § 5 — Service catalog + entitlement model (concrete schema)

### Migration 006 (proposed, additive)

```sql
-- Make ams.services aware of trial / free / pricing
ALTER TABLE ams.services
  ADD COLUMN IF NOT EXISTS is_free          BOOLEAN NOT NULL DEFAULT FALSE,
  ADD COLUMN IF NOT EXISTS trial_days       INTEGER,            -- null = no trial offered
  ADD COLUMN IF NOT EXISTS allow_self_trial BOOLEAN NOT NULL DEFAULT TRUE,
  ADD COLUMN IF NOT EXISTS price_cents      INTEGER,            -- monthly retail; null = inquire / not for sale
  ADD COLUMN IF NOT EXISTS hero_image       TEXT,               -- detail page banner
  ADD COLUMN IF NOT EXISTS long_description TEXT,               -- markdown for detail page
  ADD COLUMN IF NOT EXISTS use_cases        TEXT,               -- markdown bullets
  ADD COLUMN IF NOT EXISTS how_to_use       TEXT;               -- markdown quickstart

-- Distinguish grant types
ALTER TABLE ams.user_service_access
  ADD COLUMN IF NOT EXISTS grant_type VARCHAR(20) NOT NULL DEFAULT 'admin_granted',
  -- 'trial' | 'paid' | 'admin_granted' | 'admin_unlimited' | 'bundle' | 'free_tier'
  ADD COLUMN IF NOT EXISTS source     VARCHAR(120);
  -- 'self_signup_trial' | 'admin:james' | 'subscription:stripe_XYZ' | 'license:KEY_HASH' | 'bundle:plan_pro'
```

### Decision rule for "can this user access this service?"

```
1. service.is_free = TRUE                                              → 'free'
2. user.role IN ('admin','enterprise_admin')                           → 'admin_bypass'
3. user_service_access row exists AND active=TRUE
     AND (expires_at IS NULL OR expires_at > NOW())
     AND row.grant_type ∈ ('trial','paid','admin_granted',
                            'admin_unlimited','bundle','free_tier')   → 'granted' (with reason from grant_type)
4. (future) user.org subscribes to a plan that includes this service   → 'org_bundle'
5. otherwise                                                            → 'locked'
```

Already-implemented in `entitlements.php` — just needs the grant_type column reads added when migration 006 lands.

### Six grant scenarios (all served by the same schema)

| Scenario | `grant_type` | `expires_at` | `source` |
|---|---|---|---|
| Always-free service (e.g., MGP free tier) | — (no row needed; `services.is_free=TRUE`) | — | — |
| User self-starts free trial | `trial` | NOW() + service.trial_days | `self_signup_trial` |
| Admin gives 30-day comp access | `admin_granted` | NOW() + 30d | `admin:james` |
| Admin gives unlimited access | `admin_unlimited` | NULL (=∞) | `admin:james` |
| Paid subscription | `paid` | period_end from Stripe | `subscription:stripe_sub_XXX` |
| Plan-bundle (Pro tier includes 3 services) | `bundle` | subscription period_end | `bundle:plan_pro` |

---

## § 6 — The cohesive AMS shell vision

**Today:** AMS wraps only `/ams/*` pages. Legacy services (HUD, MGP, Scorecards, Playbooks) open in new tabs with their own (or no) chrome. Users feel they're using "AMS + some other tools" rather than "one platform."

**Vision:** Every service the user can click is wrapped in the AMS shell. Same topnav, same user chip, same session, same look. Switching between services is one click; the shell persists.

### Four ways to wrap a legacy service (rank-ordered)

| Approach | What it is | Pros | Cons | When to use |
|---|---|---|---|---|
| **A. Iframe wrapper** | New PHP page at `/ams/services/<slug>.php` includes `header.php` + iframe of legacy URL + footer | Quickest (1 hr per service); preserves legacy code; auth on the AMS shell | Iframe quirks (mobile scroll, deep-link), no shared events between shell and content | Static/read-only legacy pages (MGP, Scorecards reports, Playbooks) |
| **B. Server-side proxy + injection** | Apache or PHP fetches legacy HTML, injects AMS shell HTML before `</body>`, returns wrapped result | No iframe issues, looks native | Apache config complexity; per-surface XSS risk if legacy outputs untrusted HTML | Surfaces with rich content but no SPA framework |
| **C. Reverse proxy with auth pass-through** | Apache `mod_proxy_html` rewrites links + injects shell | Most invisible to user; legacy code untouched | Most config; needs careful Apache work | Final-state for legacy surfaces that won't be ported |
| **D. Direct port into AMS** | Rewrite the surface as PHP under `/ams/app/<service>/` using AMS shell + DB directly | Full cohesion, no legacy dependencies | High effort per surface (days to weeks) | Cockpits where deep integration matters (HUD, Daily Stop) — and eventually for everything |

### Recommended phasing

| Service | Recommended wrap | Phase |
|---|---|---|
| Accountability HUD | **D (direct port)** with Jimbo coordination per HUD-off-limits | Phase 4 of integration plan |
| Daily Stop | **D** (small, already AMS-integration-friendly) | Phase 4 |
| MGP | **A (iframe)** for now → **D** later when MGP is auth-aware | Phase 4 (iframe) → Phase 5 (direct) |
| Scorecards | **A (iframe)** | Phase 4 |
| Playbooks | **A (iframe)** | Phase 4 |
| Param Surface | **A (iframe)** | Phase 4 |
| Strategy Library | **A (iframe)** | Phase 4 |
| Monthly Reports | **A (iframe)** | Phase 4 |
| MTF VP | **A (iframe)** | Phase 4 |
| Live Classifier | **D (direct)** since needs identity context | Phase 4 |

Iframe wrap (A) shipped per-service is ~1 hour each. Eight services in roughly one work day. The user gets the cohesive AMS experience immediately; deeper ports happen later without breaking the surface UX.

---

## § 7 — Two-zone launcher design

**Today (single zone):** All 11 service cards in one grid, sorted by `sort_order`. Locked / live mixed.

**Vision (two zones):**

```
┌─ Your services ────────────────────────────────────┐
│  (active + accessible — quick launch)              │
│                                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │ 🎯 HUD       │  │ 📋 MGP       │  │ + more   │ │
│  │ Active      │  │ Trial 3d    │  │          │ │
│  │ → Open      │  │ → Open      │  │          │ │
│  └──────────────┘  └──────────────┘  └──────────┘ │
└────────────────────────────────────────────────────┘

┌─ Browse all services ──────────────────────────────┐
│  (catalog — sign up for what you need)             │
│                                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │ 📊 Scorecards│  │ 📖 Playbooks │  │ 📐 Param │ │
│  │ Available   │  │ 14d free trial│  │ Surface  │ │
│  │ $15/mo or   │  │ → Start     │  │ Locked   │ │
│  │  → Free trial│  │  trial      │  │ → Details│ │
│  └──────────────┘  └──────────────┘  └──────────┘ │
│  ┌──────────────┐  ┌──────────────┐  ...           │
│  │ 🛡 Daily Stop│  │ 📚 Strategy  │                │
│  │ Free for all│  │ Library      │                │
│  │ → Open      │  │ Coming soon  │                │
│  └──────────────┘  └──────────────┘                │
└────────────────────────────────────────────────────┘
```

**Top zone — "Your services":**
- Filter: only services where access != `locked`
- Card shows: icon · name · status (Active / Active until X / Trial Nd left / Admin unlimited) · `Open →` button
- Sort: most-recently-used first (when we have usage data)

**Bottom zone — "Browse all services":**
- Filter: every service the user does NOT have active (or hide "Coming soon" if cluttered)
- Card shows: icon · name · 1-line tagline · price/trial badge · `Details →` button (NOT direct open)
- Click → service detail page

### Click behavior
- Top-zone card click → opens the service (in AMS shell wrap)
- Bottom-zone card click → opens **service detail page**

---

## § 8 — Service detail page

A dedicated marketing/info page per service, accessible from the launcher and (publicly) from the marketing site.

URL: `/ams/services/<slug>` (or `/services/<slug>` for public when no session)

```
┌─────────────────────────────────────────────────────────┐
│  [AMS topnav]                                            │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   🎯  Accountability HUD                          [LIVE] │
│                                                          │
│   Your live trading cockpit — daily P&L, open positions │
│   fills, daily-stop tracking across all your accounts.  │
│                                                          │
│   ┌─────────────────────────────────────────────────┐   │
│   │           [hero screenshot / GIF]                │   │
│   └─────────────────────────────────────────────────┘   │
│                                                          │
│   What it does                                           │
│   • Real-time P&L per trader account, refresh every 2.5s │
│   • Daily stop tracking with breach alerts               │
│   • Zone-coded cards (green/yellow/red) for at-a-glance  │
│   • Live position blotter + per-trade fills              │
│                                                          │
│   How traders use it                                     │
│   • Morning: declare daily stop                          │
│   • Throughout the day: glance during breaks             │
│   • End of day: review the swing                         │
│                                                          │
│   Who uses it on your team                               │
│   ┌──── ┌──── ┌──── ┌──── ┌────                          │
│   │NL │ │PR │ │BF │ │TH │ │JD │  ← team members         │
│   │act│ │act│ │act│ │act│ │adm│    with their status     │
│   └──── └──── └──── └──── └────                          │
│                                                          │
│   Pricing                                                │
│   ● Free for internal traders (your status: Active)     │
│   ● 14-day free trial · $15/mo after                     │
│                                                          │
│   [    Open the HUD →   ]   [  Watch demo (2:30)  ]     │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

### What populates the page

Mostly from `ams.services` (after migration 006 adds the description columns):
- `label`, `description` (already exists)
- `long_description` (NEW — markdown body)
- `use_cases` (NEW — markdown bullets)
- `how_to_use` (NEW — markdown quickstart)
- `hero_image` (NEW — URL or path)
- `price_cents`, `trial_days`, `is_free` (NEW — pricing block)

Plus computed:
- **Team view block:** SELECT users in same team + their access status for this service
- **User's current access:** what `entitlements.php` returns for current user + service

### CTAs on the detail page

| User's access state | CTAs shown |
|---|---|
| Granted (active, not expiring soon) | `Open →` (primary) · `View pricing` (secondary) |
| Trial — 3 days left | `Open →` (primary) · `Subscribe to keep access — $X/mo` (secondary highlight) |
| Locked, trial available | `Start free 14-day trial` (primary) · `Subscribe — $X/mo` (secondary) |
| Locked, trial used, paid available | `Subscribe — $X/mo` (primary) · `Contact admin` (secondary) |
| Locked, admin-grant only (`allow_self_trial=FALSE`) | `Request access — message admin` (primary, opens DM template) |
| Coming soon | `Notify me when available` (primary) — captures email/userid interest |

---

## § 9 — Team view per service

Every service detail page shows the user's team-mates' access status. Builds social proof + reveals who can help.

Data: `main.users` JOIN `main.user_groups` JOIN `main.groups` JOIN `main.teams` (current user's teams), then LEFT JOIN `ams.user_service_access` for each member to determine their status.

UI: small avatar chips or initials with color-coded border:
- Green = active
- Yellow = trial
- Grey = no access
- Purple = admin

Hover → tooltip with "Nolan Lennon · Active · since May 12"

---

## § 10 — Tenancy model for commercial

Current model: one firm (Domino Trading), all users are internal. No `org_id` exists.

Vision: multi-tenant SaaS where each customer firm is an `org` with N users. Internal POC = "Internal" org (a single seeded row).

### Migration 007 (proposed for Stage 3-4)

```sql
CREATE TABLE IF NOT EXISTS main.orgs (
    id              SERIAL PRIMARY KEY,
    name            VARCHAR(150) NOT NULL,
    slug            VARCHAR(64)  UNIQUE NOT NULL,
    billing_email   VARCHAR(150),
    status          VARCHAR(20)  NOT NULL DEFAULT 'active',  -- active|trial|paused|cancelled
    plan_slug       VARCHAR(50)  REFERENCES main.plans(slug),
    trial_ends_at   TIMESTAMPTZ,
    created_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS main.plans (
    slug             VARCHAR(50) PRIMARY KEY,
    name             VARCHAR(100) NOT NULL,
    description      TEXT,
    price_cents_mo   INTEGER,
    price_cents_yr   INTEGER,
    max_users        INTEGER,                 -- null = unlimited
    included_services TEXT[]  NOT NULL DEFAULT '{}',  -- service.name values
    is_visible       BOOLEAN NOT NULL DEFAULT TRUE,
    sort_order       INTEGER NOT NULL DEFAULT 100
);

-- Add org_id to users (nullable — internal/legacy users have NULL)
ALTER TABLE main.users
  ADD COLUMN IF NOT EXISTS org_id INTEGER REFERENCES main.orgs(id);

-- Seed internal org for current team
INSERT INTO main.orgs (name, slug, status) VALUES ('Internal', 'internal', 'active')
ON CONFLICT (slug) DO NOTHING;

-- Backfill all current users to internal org
UPDATE main.users SET org_id = (SELECT id FROM main.orgs WHERE slug = 'internal')
WHERE org_id IS NULL;
```

### Entitlement decision rule with orgs

Adds one branch to the existing rule:
```
4. user's org has an active subscription whose plan.included_services contains this service.name → 'org_bundle'
```

### Team vs Org

| Concept | Existed since | Purpose |
|---|---|---|
| **Org** (NEW for commercial) | Migration 007 | The billable entity. Customer firm. Subscribes to plans. |
| **Team** (existing) | Migration 001 | A working group within an org. E.g., "Lennon Desk" within "Domino Trading". |
| **Group** (existing) | Migration 001 | Sub-team within a team. Used for finer access scoping. |

For internal POC: one org ("Internal") with one team ("Domino Trading") and one group ("Members"). For a 5-user enterprise customer: one org ("Acme Trading") with N teams ("Equities Desk", "Options Desk", etc.).

---

## § 11 — Payment / billing model

Stage 4 introduces Stripe.

### Recommended Stripe approach

- **Stripe Checkout** for new subscriptions (hosted page, low compliance overhead)
- **Stripe Customer Portal** for plan changes / cancellations (Stripe-hosted UI)
- **Stripe Webhooks** to sync subscription state into `ams.user_service_access` / future `ams.org_subscriptions`
- **Subscription = org-level** (B2B simplicity). Per-user usage tracked separately if needed.

### Schema additions (Migration 008, conceptual)

```sql
CREATE TABLE IF NOT EXISTS ams.subscriptions (
    id                      SERIAL PRIMARY KEY,
    org_id                  INTEGER NOT NULL REFERENCES main.orgs(id) ON DELETE CASCADE,
    plan_slug               VARCHAR(50) NOT NULL REFERENCES main.plans(slug),
    status                  VARCHAR(30) NOT NULL,           -- 'trialing'|'active'|'past_due'|'cancelled'
    stripe_customer_id      VARCHAR(64),
    stripe_subscription_id  VARCHAR(64) UNIQUE,
    current_period_start    TIMESTAMPTZ,
    current_period_end      TIMESTAMPTZ,
    cancel_at_period_end    BOOLEAN     NOT NULL DEFAULT FALSE,
    started_at              TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    cancelled_at            TIMESTAMPTZ
);

CREATE TABLE IF NOT EXISTS ams.invoices (
    id                  SERIAL PRIMARY KEY,
    org_id              INTEGER NOT NULL,
    subscription_id     INTEGER REFERENCES ams.subscriptions(id),
    stripe_invoice_id   VARCHAR(64) UNIQUE,
    amount_cents        INTEGER NOT NULL,
    currency            VARCHAR(3) NOT NULL DEFAULT 'USD',
    status              VARCHAR(30) NOT NULL,        -- 'open'|'paid'|'void'|'uncollectible'
    period_start        TIMESTAMPTZ,
    period_end          TIMESTAMPTZ,
    issued_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    paid_at             TIMESTAMPTZ,
    hosted_invoice_url  TEXT
);
```

Stripe webhook handler (Phase 4 work) writes/updates these tables; entitlement check reads from them.

### Pricing model recommendation

For maximum flexibility AND simple SKUs:
- **Per-service price** (à la carte) — e.g., HUD = $15/mo, Scorecards = $10/mo, etc.
- **Bundle tiers** (discount via plan) — e.g., "Pro" = HUD + Scorecards + MGP at $30/mo (vs $35 à la carte)
- **Per-seat for team orgs** — each additional user beyond first is +$X/mo
- **Annual discount** — 12 months for the price of 10 (typical)

Service detail page shows both options — "Add this service alone for $15/mo, or unlock 3 services with Pro for $30/mo."

---

## § 12 — Decisions to make NOW vs LATER

### Decide NOW (architectural — bake into Migration 006/007)

| # | Decision | Recommendation |
|---|---|---|
| D1 | Add trial/free/pricing columns to `ams.services` now? | **YES** — Migration 006. Foundation for everything else. |
| D2 | Add `grant_type` + `source` to `user_service_access` now? | **YES** — Migration 006. Audit + reporting clarity. |
| D3 | Add `org_id` to `main.users` now (nullable, defaulting to "internal")? | **YES** — Migration 007 (or 006 if combined). Avoids future backfill pain. |
| D4 | Two-zone launcher design? | **YES** — UX direction is clear. Implement in next slice. |
| D5 | Per-service detail page? | **YES** — Marketing + signup CTA hub. |
| D6 | Team view block on detail page? | **YES** — Social proof + collaboration nudge. |
| D7 | Cohesive shell strategy — iframe-first then port? | **YES** (recommend iframe-first for ALL non-cockpit surfaces, direct port for cockpits) |

### Decide LATER (operational — defer until needed)

| # | Decision | When to decide |
|---|---|---|
| D8 | Stripe checkout vs Paddle vs custom? | Stage 3-4 (closed beta → public launch) |
| D9 | Specific plan tiers + prices | Stage 4 (when actually launching) |
| D10 | Per-user vs per-org seat pricing | Stage 4-5 |
| D11 | Trial length per service | Stage 3+ (collect data first) |
| D12 | Customer support tooling (Helpscout / Intercom / custom) | Stage 4 |
| D13 | Marketing site CMS (separate or in-AMS) | Stage 3-4 |
| D14 | Multi-broker onboarding UX (OAuth per broker) | Stage 5 |

---

## § 13 — Phase-by-phase implementation plan

### Phase A — Migration 006 + two-zone launcher + service detail (next 2-3 days)
- Migration 006: trial/free/pricing on services + grant_type/source on access
- Backfill `services.long_description` / `use_cases` / `how_to_use` for the 11 services (admin-curated copy)
- New `/ams/app/index.php` two-zone layout
- New `/ams/services/<slug>.php` detail page template (with team-view block)
- "Start free trial" + "Subscribe" CTAs (Subscribe = stub for now — shows "Pricing coming soon" modal)
- Promote `/ams/admin/licenses/` from splash to real grant-issue + revoke UI

### Phase B — Cohesive shell wrap (1 week)
- For each non-cockpit service: `/ams/services/<slug>.php` wraps legacy URL in iframe inside AMS shell
- Direct ports for HUD + Daily Stop coordinated with Jimbo
- Launcher cards open in-shell (not new tab)

### Phase C — Migration 007 (orgs + plans) + Stripe (when ready for closed beta)
- Add `main.orgs`, `main.plans`, `ams.subscriptions`, `ams.invoices`
- Backfill current users to "Internal" org
- Stripe integration via Checkout + Customer Portal
- Webhook handler updates subscription state
- Public registration flow (replaces invite-only as primary)

### Phase D — Multi-broker onboarding (when needed)
- E*TRADE / IB / TOS / MZQ Proxy adapter modules
- OAuth flow per broker
- Per-user broker credential storage (encrypted)
- Trade source registry already exists; just enable + populate per user

### Phase E — Enterprise tier (when first customer signs)
- SSO (SAML / OAuth)
- Per-org admin delegation
- White-label / custom branding
- Audit log export
- SLA + dedicated support

---

## § 14 — What this means for the immediate next slice

If approved, the **next implementation slice (Phase A)** ships:

1. **Migration 006** — additive: `services` gets trial_days/is_free/price_cents/description columns; `user_service_access` gets grant_type/source
2. **`ams/app/index.php` v2** — two-zone layout (Your services / Browse all services)
3. **`ams/services/<slug>.php`** — detail page template + Team-view block
4. **`ams/admin/licenses/index.php`** — promoted from splash to real grant management
5. **Trial self-signup** — "Start free trial" button creates the grant row with expires_at
6. **Admin "unlimited" grant** — toggle in admin grant form, sets expires_at = NULL

That's ~6-8 hours of work, no schema risk, fully backward-compatible.

**To approve and start: say "go Phase A" and I execute the migration + ship the new launcher + detail pages.**

---

## Living document — keep this current

When a new architectural decision is made or a stage is reached, edit this file in place. Update the "Status" line at the top with the date. Don't fork into v2 — git history preserves prior versions.

The doc's purpose is to give every team member (and future Claude session) the same shared mental model of what AMS is becoming, so day-to-day decisions don't drift from the vision.
