# Firm Launch — Operations Build-Out Roadmap

> Goal: build a fully demonstrable asset-management operating platform — internal tooling, client-facing materials, and compliance stack — so that when we approach RMs, we can show a firm that looks and runs like it's live.
>
> Companion doc: `dual-licensed-asset-manager-launch-plan.md` (regulatory/structural plan — this roadmap covers the operational build).
>
> Status key: `[ ]` open · `[~]` in progress · `[x]` done · `[!]` blocked (needs user input / external party) · `[?]` needs decision
>
> Session state is updated at the bottom (Worklog) each working session.

---

## 0. Guiding principles

1. **Single source of truth for everything that repeats.** Brand (colors, fonts, logos, tone), fee schedules, legal entity facts, disclaimers — defined once in a central config, rendered into every artifact (website, proposals, letters, presentations). Change the theme once → everything updates.
2. **Content flows up the hierarchy.** Daily market commentary → weekly journal → monthly/quarterly/annual investment letters, with AI-assisted synthesis between layers. Never write the same narrative twice.
3. **Compliance-first on every client-facing artifact.** Every marketing piece, proposal, and letter must be producible *with* its compliance annotations (FINMA/FinSA + SEC) from day one — retrofitting compliance onto "fake ops" wastes the demo.
4. **Demo-grade ≠ production-grade, but demo-grade must be honest.** Everything shown to an RM must be real functionality or clearly labeled as illustrative. Marketing materials shown to prospects before licensing have FinSA implications (see A1) — treat pre-license RM outreach content carefully.
5. **Working documents live in the vault; rendered outputs live in the build system.** Obsidian for planning/notes/knowledge; git-versioned template/pipeline repo for anything rendered.

---

## 1. Workstreams

### WS-A · Strategy, positioning & constraints (spine — decides everything else)

- [ ] A1. Pre-license marketing compliance mapping. Question list PREPARED (§6). Trigger-based, not a now-item: becomes urgent at first external circulation of materials (RM pitch) or at incorporation, whichever first. Until then, WS-C materials carry a draft "illustrative / not an offer" disclaimer treatment and internal-only status.
- [~] A2. Firm identity decisions.
  - Name: PLACEHOLDER (`[FIRM]`) — naming discussion deferred; all templates/tokens must read name from config so rename is one-line.
  - Branding direction (user, 2026-10-08): neither "ancient Swiss asset manager" nor "AI-startup modern". Target: conservative reliability + modern systems/investment approach. Investment identity to express: fundamentals analysis across a wide universe of high-quality securities, price action as entry/exit overlay ("the market is always right"), strong risk management — avoid huge loss positions, reduce market exposure in times of stress. Detailed visual identity later (B2).
- [~] A3. Product shelf definition: mandate types, model portfolios, fee schedule per mandate type, minimums. Needed by WS-B, C, D, E.
  - RESOLVED (2026-10-08): risk-profile ladder = Fixed-income-only → Conservative → Balanced → Offensive → Equity-only, plus many further model strategy variations.
  - Design principle confirmed: model strategies are centralized in the AM database with mandate-level variation handled by client constraints on top — NOT copies per mandate. (Already how asset-mgmt-db works: two-pass construction, model + client constraints, SCD2 versioned.)
  - OPEN: currency variants (USD/CHF/EUR books?) — treated as same % rates, different reference currency, until decided otherwise.
  - Fee schedule DRAFTED (2026-10-08): see `fee-schedule-draft.md` — YAML-config (single source of truth), 5 tiers + custom-variant uplift, AUM bands, min fee CHF 6k, min mandate CHF 500k (FinSA qualified-investor), RM share 60% (band 50–70%), retro-free. 6 open decisions in that file §4.
- [x] A4. Investment process narrative: DRAFT v1 written (2026-10-13): `03-research/business/investment-process-narrative.md` — from user's verbatim answers. Core: fundamentals-first + technical overlay (relative-strength rotation ranking; CMT-credentialed) + mechanical risk discipline. Quality gate: two categories (Quality majority + Growth satellite, factor-diversification rationale); dimensions: FCF conversion, revenue growth, margin trajectory, balance-sheet strength, moat. RISK RULES (mechanical): position −20% from purchase → cut to half (no debate, + review warning); −25% → discretionary review warning; −30% → full exit mechanical; single-name 6% (default, configurable) → trim to 5%; 50%-above-target-weight → warning+review; <0.5% → warning+review (top-up or sell). MARKET-RISK FRAMEWORK: sector-rotation drawdown-precedence monitoring → de-risk + raise cash equivalents. INTERNAL NOTES (NOT for marketing/RM): the overlay + market-risk framework both run on Relative Rotation Graphs (RRG) — the secret sauce, widely used by TAs/fund managers but NOT in separately managed accounts; public framing = "relative-strength rotation ranking", RRG never named; framing/marketing development = follow-up item (CMT anchors credibility). Technical scores managed OUTSIDE the engine, delivered to DB on frequency. Follow-up build items: position-risk rule engine (D-workstream), RRG data pipelines (internal), overlay marketing framing, D7 tax-optimization tool.
- [x] A5-research. Research briefs delivered (2026-10-09): `research-rm-psychology.md` (~30KB), `research-client-pitch-mistakes.md` (~27KB), `research-storytelling-science.md` (~29KB), synthesized into `marketing-synthesis.md` (10 non-negotiable design rules + two-track differentiation table + five-beat narrative arcs for both tracks). Key quantified anchors: RM stated-vs-moved AUM ~40% at 18 months (Chalem/finews); Swiss EAM identity avg 1.57/5 (SEAMIx); bank RM comp CHF 270–420k total vs EAM rev-share 25–40%; all-in Swiss bank client costs ~2× stated (moneyland/FinGuide); BGer 4A_116/2018 non-compete precedent for RMs.
- [~] A5. RM value proposition + two-track design.
  - TARGET DECIDED (2026-10-09, user): **primary archetype = "Restless EAM RM"** — currently at another (small) Swiss EAM, pain points: persistent underperformance at current EAM, no equity partnership path, ~50% revenue share, no voice in process, founder distracted by other ventures. Secondary archetype = "Constrained Bank RM" (traditional bank→EAM source) — separate pitch variant needed.
  - Pitch implication: against archetype B we sell "a better RUN firm" (not independence) — demo/machinery central. Bank-RM variant sells independence + platform readiness.
  - Open: whether our "underperformance" teaching angle is safe to use against their current firm (taste/legal care needed); what equity/partnership structure we can credibly offer (user decision, affects C2 + fee schedule).
  - In flight → DONE: `research-rm-move-economics.md` delivered (2026-10-09). Key findings: 60/65% share = top-of-band but defensible (AlphaSwiss advertises 60% for junior staff; vapa band 40–60%; 2–3x bank grid ceiling); against incumbent 50% the wedge is retro-free base + succession answerability + written exit rights, not the 10 points; EAM-to-EAM is the highest-conversion lowest-risk move (no non-compete overhang, KYC static, Magistra's "few administrative signatures"); ~80% of EAM consolidation is silent RM-book transfers = active pipeline of exactly our archetype; what candidates fail to check (succession risk 58% unarranged, identity, cost-base economics) we should volunteer unprompted.
  - NEW ARTIFACT: `rm-first-year-income-table.md` — the RM-track's one-table economics artifact (income at 25/40/60% follow × 3 book sizes, incumbent-50% vs us-60/65%, pessimistic-first candor structure). Open user decisions in that file: transition guarantee (6–12m floor?), equity track design, share-basis wording ("60% of the client fee, not 70% of something smaller").
  - EQUITY DECISION (2026-10-09, user): real equity (B-shares) for founding RMs, first buyback right; dual share class to protect founder control; partners' council for voice. Design stress-tested → `rm-participation-structure.md` v2: original 49%-of-net-income pool produced 148–234% comp outcomes at scale (double-keying flaw: cash + dividend both keyed to book size); corrected architecture = ownership (fixed B-share %, exit-valued) SEPARATED from income (30% of RM-channel retained revenue, current-contribution weighted). Verified outcomes: founding RM ~65% of own-book rev at all scales; later-joiner 55% cash; founders keep 100% direct rev + 35% of RM rev. Open items §5 (exit formula, sustainability test, pool cap 20/25%, FINMA shareholder notifications, articles-at-incorporation).
  - WALKTHROUGH delivered: `rm-participation-walkthrough.md` — step-by-step plain-language explanation with 10-year simulations on 3 paths (target 4B / modest 600m / RM-heavy 1B). Structural invariants verified: every equity RM earns exactly 60–65% of own-book revenue at ANY firm size; founders keep 35% of RM-book fees + 100% of direct; ownership fixed at entry, income current; founders always hold 100% of votes. New open knob: exit multiple cap (100× cost ≈ CHF 1.4M ceiling for a 150m-book founder) — user to decide with lawyer.
  - CORRECTED MODEL (2026-10-09, user clarification): founders bring NO direct books — 100% of revenue is RM-sourced. Founders' residual = retained RM half − pool − opex. With realistic opex (`opex-buildup.md`): residual 26–31% of gross revenue at every stage (700k→11.7M); pool insulated from expenses by design; expense discipline coupled to RMs via exit formula (retained earnings). Opex build-up staged in `opex-buildup.md`: Stage 1 ~116k (5bp, no salaries) → Stage 2 ~488k (8bp, founder salaries 270k + 1 hire) → Stage 3 ~840k (7bp, 3.5 FTE) → Stage 4 ~1.36M (3bp, 5-6 FTE). Staffing leaner than median Swiss EAM per AUM (systems-driven). What's excluded: custodian pass-throughs, VAT, one-time launch costs, founders' taxes. Trigger for founder salaries: ~500-600M RM books / residual >1M.

### WS-B · Central style & content system (the "single source of truth" engine)

- [x] B1. Choose build architecture. DECIDED (2026-10-08): one local-only git repo — `brand/` (colors, fonts, tokens), `templates/` (docx/md/latex/html), `content/` (journals, letters), `scripts/` (render pipeline). Never published online (user requirement — repo stays on machines, no remote hosting of firm material pre-launch). Obsidian remains the authoring layer.
- [~] B2. Brand token file: `brand.yaml` — colors, typography, logo usage, tone-of-voice rules, boilerplate disclaimers (FINMA/FinSA + SEC variants), entity facts (address, UIDs — placeholders pre-launch). Every template reads from this. → Now part of the CONTENT-COMPILER framework (Item 5C): brand.yaml + layout-rules.yaml are the waterfall source (LAYER 3); user wants centrally-managed fonts/structure with waterfall effect on all artifacts. Spec: `asset-mgmt-db/specs/item-5c-content-compiler-framework-spec.md`.
- [ ] B3. Writing style guide: house voice, banned phrases, language per audience (institutional vs. private), German/English conventions, disclaimers placement rules.
- [~] B4. Daily commentary template + capture workflow: EXISTS IN PART — vault templates already present (`_templates/daily-journal.md` with overnight-moves/flows/calendar/stop-check structure; monthly-letter.md with numbers-first + "What was wrong" credibility section — user's own design, predates the research). → Becomes LAYER 2 (content) of the content-compiler: Obsidian = authoring surface, vault ingested by compiler.
- [~] B5. Content roll-up pipeline: daily → weekly → monthly → quarterly → annual. Now = content-compiler's event-engine: scheduled mover-monitor sweeps (daily/weekly/monthly/quarterly) generate event-report drafts (AI + FactTable grounding, layout per specs) into `content-assets/events/`; quarterly artifacts query the events library. AI output validation: numeric claims validated against DB data-pack (researchFlow pattern — compiler refuses ungrounded numbers).
- [~] B6. Rendering pipeline: markdown/docx/pdf/HTML output from templates + tokens. → Item 5C content-compiler: Jinja2 HTML → Chromium headless PDF recommended (Option B; Quarto/Typst = Option A documented, swappable later); pure-SVG chart generator (brand-token styled, no matplotlib); artifact classes: client_report, security_note, monthly_letter, portfolio_review deck, quarterly deck, fact_sheet, daily/weekly note. Manual-edit gate: drafts editable as markdown, git-tracked draft→final transitions. Verify a theme change propagates to all outputs (acceptance test).
- [x] B2. Brand token file: DONE v1 (2026-10-13) — **Zurich Anthracite Hybrid design system imported** from user-provided skill (`zurich-anthracite-skill.zip` in vault Files/): full token set (DTCG tokens.json, CSS, matplotlib style, LaTeX sty), house rules (oxblood ≤10% accent, serif-headings-only, Inter tnum data, no red/green semantics, print vs screen variants, WCAG-verified contrast pairs). Implementation: brand fonts installed system-wide (Source Serif 4 + Inter + Lexend variable — SIL OFL, free; Lexend variable from google/fonts = Deca cut, family name "Lexend"); `brand/brand.yaml` rewritten to ZA palette/typography/Swiss number format; ZA chart-series discipline added (oxblood = highlight/negative, benchmark = anthracite-400 dashed, series order 1-6). Waterfall VERIFIED: brand.yaml edit → regenerated artifacts, no template changes. Client report AND portfolio-review deck both render in ZA.
- [ ] B7. Website: structure (home, philosophy, team, strategies, contact), built from same tokens; decide host + domain `[?]`. Pre-license content must respect A1 findings. → Website gets its own HTML templates off the same brand tokens (Option C decision: dual render).

### WS-C · Marketing & client-facing materials (built from WS-B system)

- [~] C0. Two-track marketing structure (established 2026-10-09, user decision): Track 1 = potential clients (standard), Track 2 = potential RMs joining the firm. Distinct value propositions and messaging per Challenger Sale — same look and feel (brand tokens), completely different targeting of each group's needs and concerns. All WS-C materials are now built per-track: client-track and RM-track variants of deck, proposals, letters. Development approach: interactive back-and-forth discussion with user per topic, NOT one-shot drafting.
- [~] C0c. Track 3 — anchor client/investor pitch (user idea 2026-10-09): one unique CHF 50–100M+ individual, below family-office feasibility (SFO break-even CHF 200–250M Swiss / $250–500M global; MFO entry CHF 10–30M — the target sits squarely in the gap), ideally inherited wealth without operating business. Delivered: `anchor-client-track.md` — FO value-driver deliverability map (consolidated reporting ✅ built, oversight ✅, coordination ◐ via partners, deal access ❌ don't claim); pitch thesis "family-office functions without the office cost — co-own the platform instead of funding its salaries"; offer structured per research (fee economics first — lawful discount; profit-participation right second; equity <10% Swiss qualified-participation line / <25% US control, passive, pre-cleared, PAAMCO v. Sussman lesson); anchor allocation comes from the SAME pool as founding RMs (cap-table decision together, at incorporation, both in articles); RM pitch BENEFITS (anchor AUM = institutional proof) but scarcity recalibrated (anchor = separate client-investor category). Same 8-beat spine, new dials: SFO-arithmetic riddle opener, fragmentation/governance-vacuum discovery, cost-curve exhibits, consolidated-picture as the small step. Tone: arithmetic + governance, not storytelling adrenaline. Sourcing: liquidity-event press, wealth lawyers/notaries, tax advisers, CHF 100M+ private bankers, MFO declines. RESTRUCTURED (user, 2026-10-09): anchor pays NORMAL published fees — no discount, no founding-pricing expiry for the anchor; economics offset via PURCHASED participation at fair value (B-shares or profit-participation right, <10% Swiss line, <25% US control, passive, pre-cleared). Distributions are investment returns, not fee rebates — substance-over-form clean (risk-bearing = no hidden transfer); equal treatment trivially satisfied at client layer; owner-conflict named + mitigated (information barriers, ownership-blind allocation, standard owner-PM precedent); promoter conflict (anchor as referrer) default-resolved: no referrals, fallback papered like RM introduction. Anchor participation at FIRM level, NOT in RM-channel pool. Founders RECEIVE the purchase price (launch balance sheet improves). Two legs decouple for timing: client relationship can start pre-license at normal fees; participation purchase at incorporation or post-license. Open: instrument choice, sizing, promoter-conflict decision. Source pack: `research-family-office-thresholds.md`.
- [ ] C1. Firm presentation deck (Track 1 master deck; RM-track variant derived separately per C0).
- [ ] C2. RM pitch deck + RM FAQ (fee share, service model, transition story). Depends A5, A1.
- [ ] C3. Investment proposal template (client): mandate-type sections, portfolio construction, fee table from tokens, risk disclosure — with per-client variable slots for the demo.
- [ ] C4. Client onboarding presentation (what new clients see in first meeting).
- [ ] C5. Investment letter templates: monthly, quarterly, annual — generated by B5 pipeline, with real vs. demo data switch.
- [ ] C6. Security analysis template (one-pager: thesis, valuation, risk, position sizing) and macro analysis template (theme brief: view, drivers, positioning implications, invalidation).
- [ ] C7. Fact sheets / portfolio report pack (what clients receive monthly: performance, positioning, commentary) — ideally auto-generated from the PMS database (see WS-D).
- [ ] C8. Website content (from B7 skeleton).
- [ ] C9. Business cards, letterhead, email signature, NDA/cooperation-announcement basics for RM conversations.

### WS-D · Internal operations tooling (the AM database layer)

- [~] D1. AM database inventory + gap spec. (Repo: `/home/rpi/asset-mgmt-db`.)
  - INVENTORY (2026-10-08): SCD2 bitemporal architecture DONE — 22 tables, 126+ tests. Done: Slices 01–04 + 06–07 (universe, client data, portfolios, reconstruction engine, fee reconciliation); FMP+ECB data pipelines (102 US securities, prices, fundamentals, FX); Strategy Sandbox notebook; criteria expansion (liquidity/quality filters, industry exclusion); compliance monitoring/enforcement split. Sample strategies seeded: USD Balanced/Conservative/Offensive (+ test strategies from Item 4A).
  - In flight: Item 4B portfolio comparison tool — spec passed, awaiting user demo sign-off; then Item 3 (four-eye workflow-state delta on migration 021).
  - Deferred: Slices 08–09 (CRM + compliance) — pending WealthArc API access.
  - Open per its own ROADMAP: Item 1 strategy library/versioning (HIGH), Item 2 momentum overlay (MEDIUM), Item 3 rebalance workflow + snapshots (HIGH — quarterly recalibration, interim severe-shift rule).
  - STILL MISSING vs firm-launch needs: trade planning/order workflow with approval trail (feeds E compliance evidence), client reporting generator (D4), RM/fee-share tracking, prospect pipeline (D6), demo mandate seeding at scale for F2, non-USD (CHF/EUR) book support.
  - NEXT: define "demo-ready" cut — which of the above must exist before F1/F2 demo, vs. post-launch. Tie-in: asset-mgmt-db's Item 1/3 map to our D2/D3.
  - LIVE STATE VERIFIED (2026-10-09, topic 5 prep): DB up (PostgreSQL 17, port 5433 socket /tmp, 27 tables). Data: 102 securities; metric history 2024-09-02 → 2026-08-27 (48.7k rows, prices via security_metric_history.extra metrics); 3 clients / 3 test portfolios (P-00005/06/07, TEST-stamped, USD_CONSERVATIVE/OFFENSIVE/BALANCED) with 702 transactions spanning 2025-07-01 → 2026-08-25 (~14 months simulated history); FX history present; strategy schema live. Python engine (reconstruct/fees/ranking/exposure/constraints/pit) lives in worktree `.worktrees/t_945c3468` (branch t_945c3468-slice-1-validate-point-in-time-query-for) with 4B comparison notebook + CSV outputs — NOT yet in master tree. FMP feed cancelled (user) — data covers the demo period; no new ingest needed for demo.
  - USER DECISIONS (2026-10-09, topic 5): (a) demo built on the historical window we already have — simulate performance/reports through 2025-07→2026-08 rather than waiting for fresh feed; (b) WE run the demo initially; RMs get direct tool usage only once processes are automated and robust; (c) build the missing demo pieces interactively with the user (ask many questions, get it right).
- 2026-10-13 (session 6, continued): Content-compiler live. Item 5B spec Q&A'd and D4 built: performance engine (Item 5A: TWR/benchmarks/fee layers, 12 tests, committed) → firm-content repo created (B1 realized: brand/templates/compiler/configs/drafts/output) → first client report compiled (Jinja2→Typst→PDF, 3pp, watermark, verified visually) → portfolio_review deck compiled (16:9, ZA dark title slide). B2 DONE: Zurich Anthracite design system imported from user's skill zip — fonts installed (Source Serif 4/Inter/Lexend), brand.yaml rewritten to ZA tokens, waterfall verified (re-render with zero template edits), ZA chart discipline (oxblood highlight, dashed benchmark). Typst binary relocated to repo bin/. Samples delivered to vault: Files/firm-content-samples/ (client report PDF + deck PDF + 3 preview PNGs). Note: Lexend variable font family name "Lexend" (Deca cut). Engine caveats standing: provenance note in 5A spec + demo methodology. Mover monitor BUILT (compiler/movers.py, thresholds config, 5,277-event library backfilled 2025-07→2026-08; FMP data artifacts flagged for AI narrative cross-check). Monthly-letter template BUILT (user's vault structure, ZA print style, placeholder commentary pending approval). Samples: report + deck + letter PDFs + 3 preview PNGs in vault Files/firm-content-samples/. PRACTICE RUN DELIVERED (2026-10-13): quarterly review deck in BOTH variants (print default — white title/disclaimer slides per ZA §7 handout rule, resolving user's dark-page concern; screen variant kept for on-screen), client report with REAL contribution table (Key Contributors: weight × return × contribution-as-%-of-start-value, INTC/SPY/JNJ/GE/META/JPM/AVGO/DIS rows), 5,277-event library live. CONTRIBUTION ENGINE committed (contribution.py): three-factor selection verified — INTC +283% selected via contribution+abs-move, JNJ +75% at 98th percentile unusualness, META -21% at 97th; JPM +23% contribution-only correctly NOT selected. NARRATIVE LAYER v1 committed (narratives.py): five-beat story skeletons (SITUATION/TENSION/TURN/RESOLUTION/WHAT-NEXT) with house-commentary slots + plausibility gate (period return vs peer distribution, threshold max(3×median, median+40)) → INTC/JNJ routed to review queue as test-data artifacts (gate working as designed). Practice deliverables in vault Files/firm-content-samples/ (PRINT + SCREEN decks, client report quarterly). CENTRAL SOURCING REFACTOR (user principle, after user caught period≠since mismatch in practice report — root cause: hand-copied config numbers): built `firm-content/compiler/datapack.py` — ALL numbers (returns, benchmark, fees, cost bp, value, contributors, three-factor selection) now derived from the ENGINE at render time; configs stripped to presentation choices only (portfolio, period, variant, labels, commentary); numeric overrides in configs are WARNED and IGNORED (fail-safe toward central truth); render.py merges datapack over config.data; letter datapack derives per-strategy MTD from the three test portfolios (window prev-month-end→end so mid-month cuts yield one period). All four artifacts re-verified consistent (14.8/10.0/+4.8 everywhere; letter MTD now engine-derived: Conservative +1.5%/+1.6% etc.). Deck contributors table fixed to meaningful columns (Security/Name/Return/Contribution — old Best/Worst columns were a hand-set hack). Chart SVGs remain engine-sourced via monthly yaml. Remaining hand-set inputs: commentary blocks (by design — human-approved), labels, chart file references. NEXT: AI drafting pass on skeletons (house-input-first, reference-tagged), demo mandate expansion (D5), demo script F1. Migration plan skeleton added (§8: Pi → production machine when build completes; Obsidian vault = FRESH START, private material stays behind; Hermes bootstrap instruction pack to be written at migration time). A4 DRAFT v1 written from user's verbatim answers (loss ladder −20/−25/−30, 6%→trim-to-5%, 50%/0.5% warnings, sector-rotation market-risk framework, Quality+Growth two-category gate; RRG = internal secret sauce, never named publicly; D7 tax tool + D8 rule-engine added to queue). A4 ANSWERS APPLIED (2026-10-13): (1) "market is always right" = INTERNAL credo; client-facing rephrase (c) adopted: "our views propose, the market disposes — we let prices confirm or refute them"; (2) loss ladder applies to ALL positions; SELL-RESTRICTION MODEL built (migration 030: `position_restriction` — LOCKUP/CLIENT_RESTRICTION/REGULATORY/LIQUIDITY, end date or permanent, `reconsiderable` attribute so engine may list restricted securities as potential opportunities, never forced actions; blocked securities excluded from ALL sell/trim/rebalance sims; staggered ANNUAL PM review even for permanent restrictions, review_owner per PM); (3) commentary folders confirmed (easy-to-change for machine move — paths env-configurable); (4) synthetic seed notes planted (3 notes: monthly 2026-08, weekly W36, NEM data-artifact event note — TEST-stamped, removed at launch); (5) drafts/ separated PER ARTIFACT CLASS (client_report/, portfolio_review/, monthly_letter/…) — chart assets follow the class dir; all artifacts re-rendered OK; engine paths env-configurable (AMDB_ENGINE_SRC) for §8 machine move. `asset-mgmt-db/specs/item-5a-performance-engine-spec-proposal.md` (Q1–Q12 all resolved). Migration 028 applied (benchmark_definition SCD2 baskets, index_history base-100 series, custodian_fee_history with synthetic 0.20/0.15/0.25% rates). Index backfill from Yahoo (2,490 rows: ^SP500TR + AGG/GLD/DBC/SHY adjusted proxies, 2024-09→2026-08). Engine `performance.py` in worktree (ledger-derived holdings — position_history holds only final snapshot, discovered during build; cash from pre-signed ledger amounts — second sign-convention bug caught and fixed by testing). **12 tests passing.** Worked example Jul-2025→Aug-2026: P-00005 Conservative +16.2% gross / +14.8% net vs bench +9.97%; P-00006 Offensive +37.3%/+35.9% vs +20.95%; P-00007 Balanced +28.6%/+26.7% vs +21.42%. Q11 resolved: OFFENSIVE 70/20/10 (alts folded into equities until data exists). Q12: Yahoo = demo-period source only; consolidate to premium FMP tier at launch (provenance per row survives). Committed to worktree branch + main tree.
  - DEMO DATA PROVENANCE (verified, user asked 2026-10-09): the test portfolios are NOT random walks — `generate_transaction_history.py` ran the REAL reconstruction engine at each quarter-end (Jul-2025 open + 5 rebalances: Sep/Dec/Mar/Jun/Aug) and executed its target diffs at REAL market prices from the DB (sells before buys, cash-constrained fills, partial fills allowed). The portfolios ARE "what our engine would have done" — real strategy rules, real prices, quarterly recalibration + interim drift actions (80 BUYs / 43 SELLs for P-00005). Performance numbers are therefore genuine engine-vs-benchmark comparisons, WITH idealized-execution caveats: (a) trades fill at same-day last_price (no slippage/spread), (b) dividend/interest are estimates (0.5%/0.25% of position value per quarter), (c) the engine's reconstruction is deterministic (no look-ahead in principle — targets as-of date use data as-of that date). CRITICAL PROVENANCE DETAIL (verified 2026-10-09, user memory confirmed): the technical rating system was NOT part of the seeded rebalances — at every rebalance date (Jul-2025 through Aug-2026), essentially the whole universe had NO technical score in the DB (scores exist only for ~54 securities dated 2026-08-25/26: 48 DEMO_SCORES + 56 FMP rows). The ranking engine's documented fallback assigned a deterministic ticker-hash score (md5(ticker)%11−5) to unscored securities — so the seeded portfolio selection = FUNDAMENTAL GATE (quality-tier ranges from real FMP fundamentals) + HASH-ORDERED placeholder ranking, with real technical scores entering only the very latest data. The fundamental gate carried the real signal; the technical overlay was placeholder. Demo framing must reflect this honestly: 'the machinery is live; the technical score pipeline connects from the TA software (manual update initially, per design)' — and the seeded performance numbers demonstrate the GOVERNANCE/fee/reporting machinery, not a validated momentum alpha. These caveats MUST appear in the demo methodology note (our own candor rule). GROSS performance definition implemented: add-back of our fee (industry-standard gross-of-fee reporting; fee deducted from account in ledger). NEXT: report-pack generator (D4) rendering from this engine + demo mandate expansion + demo script F1.
- [~] D2. Portfolio alignment / drift engine: BUILT v1 (2026-10-13) — `assetmgmt/alignment.py` (worktree): reconstruct(model, as_of) → target weights vs ledger actual; per-asset-class drift vs ALLOCATION_BANDs (WITHIN_BAND/SOFT_BREACH/HARD_BREACH); per-position A4 risk actions (−20/−25/−30 loss ladder via avg cost, single-name 6% cap for STOCKS only, ETF/commodity strategy position-size limits, ≥150%-of-target review, <0.5% floor review); position restrictions (migration 030) excluded from all actions, listed separately with reconsiderable flag. Verified on all 3 portfolios: P-00005 FI 65.8%/60% + equity 34.2%/30% within ±10% bands, actions: LQD + SPY drift reviews; P-00006 clean; P-00007 IGSB+HD reviews. NOTE: 22 pre-existing test failures in reconstruct/constraints tests (fixture-vs-data drift, confirmed pre-existing via stash test — NOT from D2; test-debt cleanup queued). Demo centerpiece ready: the alignment engine is the live-demo feature marketing-synthesis rule 9 calls for.
- [ ] D3. Trade planning & order workflow: idea → trade ticket → approval trail (this doubles as compliance evidence, feeds WS-E controls).
- [x] B2. Brand token file: DONE v1 (2026-10-13) — **Zurich Anthracite Hybrid design system imported** from user-provided skill (`zurich-anthracite-skill.zip` in vault Files/): full token set (DTCG tokens.json, CSS, matplotlib style, LaTeX sty), house rules (oxblood ≤10% accent, serif-headings-only, Inter tnum data, no red/green semantics, print vs screen variants, WCAG-verified contrast pairs). Implementation: brand fonts installed system-wide (Source Serif 4 + Inter + Lexend — SIL OFL, free); `brand/brand.yaml` rewritten to ZA palette/typography/Swiss number format (1'000'000 separators, true minus); client report re-rendered through the waterfall — ZA typography/tables/chart colors live in the PDF, fonts embedded. Waterfall VERIFIED: brand.yaml edit → regenerated artifact, no template changes.
- [~] D4. Client reporting generator: BUILT v0.1 (2026-10-13) — first client report compiled end-to-end through the content-compiler framework: performance engine → data YAML assets → pure-SVG brand-styled chart → Jinja2 → Typst → 3-page A4 PDF, verified visually. Repo: `~/firm-content` (the B1 build repo, created) — brand/brand.yaml + layout-rules.yaml (waterfall source), compiler/render.py + charts.py, templates/client_report/, configs/, drafts/ (manual-edit gate), output/. Typst v0.15.1 installed at /tmp (needs stable relocation). Known template fixes applied during pilot (tsc escape filter for $/#/brackets, watermark via page background, show-rule headings). Visual quality good: tables/chart/watermark clean; TODO improvements: watermark legibility tuning, section page-break control, number formatting of fee line ("—" placeholders), allocation table from 4B views (v1 uses strategy-band approximations). 5B spec Q3–Q7 answered by user: modular metric toggles (simple/institutional), privacy modes (full_name/mandate_number/anonymous/percentages-only), arbitrary period support, EN v1 with i18n string tables, generator in DB repo → migrating to firm-content repo (DONE for compiler+templates).
- [~] B5. Content roll-up pipeline: events library LIVE (2026-10-13) — mover monitor built (`firm-content/compiler/movers.py`): deterministic event detection from DB (per-cadence × per-asset-class thresholds in `content-assets/mover_thresholds.yaml`, config-driven), idempotent event YAML files into `content-assets/events/{YYYY}/`, library backfilled Jul-2025→Aug-2026 (**5,277 event records**, e.g. ORCL +36% 2025-09-10, IBM −25%, silver crash −31%). Verified against known volatile days. Known issues flagged: FMP price artifacts (NEM +44% single-day = restatement, not market) will register as events — AI narrative layer must cross-check volume/context; daily equity threshold 3% yields ~12 events/day across 102 securities (tune later).
- [~] B5c. COMMENTARY SOURCING + DRAFT-REVIEW LOOP (Item 5E spec, 2026-10-13, user-directed architecture): human commentary lives in `~/Obsidian-Macro/03-research/commentary/{daily,weekly,monthly,quarterly,events,letters/sent}` — mostly internal, never sent; extends existing daily-journal/weekly-review habits (new `_templates/commentary-monthly.md` created). Frontmatter = machine interface (type/date/status/tickers/sectors/themes/event_ids/usable). AI ASSEMBLES complete drafts (narrative + storyline) from sourced notes for human review — human views enter through sourcing; human reviews by feedback (regenerate) or direct edit; edits are the audit trail and recurring patterns feed the voice block. Citation map (hidden src tags) visible to reviewer, stripped from client render. Gates: internal notes inform, only approved blocks ship. Cadence roll-up: monthlies summarize dailies/weeklies, quarterlies summarize monthlies — each link human-gated. Letters/sent archive = precedent + consistency check. Q1–Q5 ALL ANSWERED + ASSEMBLER BUILT (2026-10-13): `firm-content/compiler/assemble.py` — commentary notes (frontmatter-matched: date window + heading keywords, substring-tolerant) + 5D story skeletons + datapack → complete assembled draft md with hidden citation tags (`<!-- src: ... -->`), explicit [REVIEW: ...] slots for gaps (never invented content), body word-cap check (500), citation map section, and a Feedback (human) companion section for the review loop. Renderer consumes assembled commentary automatically (content-assets/commentary/<period>.yaml overrides config-inline; [usable: false] lines and reviewer tags stripped at render). FIRST END-TO-END RUN PASSED: synthetic monthly note 2026-08 → assembled draft (268 words, 5 citations) → compiled letter PDF carries the human's words (placeholders gone). Review loop as user specified: feedback → regenerate, or direct edit (draft becomes truth). Remaining build: deck/report assembly variants + regenerate-with-feedback parsing.
- [~] B5b. Event NARRATIVE LAYER spec written (2026-10-13): `asset-mgmt-db/specs/item-5d-event-narrative-layer-spec.md`. Design per user requirements: (1) GROUPING before drafting — same-day events grouped by sector → industry → region (domicile, activates when non-US books come on) into story_groups with portfolio-exposure overlay; (2) PLAUSIBILITY GATE before any narrative (single-name >3× sector median → data-artifact suspect → review queue, never auto-draft — the NEM +44% case); (3) SOURCING priority: house input (approved Obsidian commentary) → online research with [R-n] reference tags VISIBLE TO REVIEWER ONLY (never in client artifacts — user rule) → else "driver not established" (excuses banned); (4) GROUNDING: FactTable with stable fact IDs, compiler refuses ungrounded numbers, fallback = data-blocks-only version; (5) CONTRIBUTION FOCUS: reports/decks lead with top contributors + detractors (weight × return, engine extension planned) + materiality screen (≥10% of gross gains/losses enters narrative regardless of rank); (6) VOICE BLOCK added to brand.yaml (LAYER 3): register/person/sentence caps/banned phrases ("the market was volatile" etc.)/required postures (decisions named before markets, unexplained moves stated as unexplained) — same rules bind AI and human. ANTI-REGURGITATION RULE (user core requirement): market recap ≤1 sentence per narrative; story = what it means for the portfolio → what we did → what changes our mind; performance never excused by markets (decisions, not markets, explain outcomes). Story components per research-storytelling-science.md mapped compliance-safely (protagonist = client portfolio, stakes translated human-scale, fear always followed by mechanism, one retellable sentence per artifact). Q3–Q5 ANSWERED (2026-10-13): Q3 sources NEVER in client artifacts for now (display-layer toggle if compliance later requires); Q4 voice list grows iteratively from real drafts + THREE-FACTOR contribution model (absolute move / contribution weight×return / unusualness = percentile of the move within the asset's OWN rolling history — verified: NEM +30% 30d move = 98th percentile of its own history, AAPL +4.4% = 38th → genuinely normal; the user's ATR intuition implemented with close prices as percentile-of-own-history; narrative-selection rule = high on ANY TWO of three factors, or materiality screen ≥10% of gross P&L; unusualness mentioned explicitly when it's the story — SUCCESs "Unexpected" beat); Q5 length caps TIGHTENED (event-story ≤100w, sector ≤150, letter body ≤500, slide ≤30, report section ≤250 — hard compiler enforcement, positioning point: shorter than industry bias). Q1/Q2/Q6/Q7 defaults adopted (sector→industry→region grouping; simple contribution v1; narratives in content-assets/narratives/; plausibility gate 3× sector median). Remaining open: Q7 review-queue surface (Obsidian query vs HTML page). COUNT CLARIFIED (user asked): 5,277 = event FILES (one YAML per detected mover, ~3,600 daily-cadence + ~500 each weekly/monthly/quarterly; ~12 events/day at 3% equity threshold — correlated sector moves produce multiple same-day events; narrative layer should group by sector/theme, and thresholds are tunable). SCOPE GAP (user flagged): monitor scans the tracked universe only — client-book LEGACY holdings outside the universe (inherited positions from PMS transfers) are not yet scanned; planned --include-client-book mode once the PMS import provides their prices (production; onboarding must check portfolios for out-of-universe holdings). Demo data is fully in-universe. Documented in movers.py docstring + content-assets/README.md.
- [~] C5. Investment letter templates: monthly_letter template BUILT (2026-10-13) — faithful to the user's own vault structure (`_templates/monthly-letter.md`: numbers first, "What was wrong" credibility section, one thematic section, outlook) in ZA print styling; first letter compiled with honest PLACEHOLDER commentary (marked as pending B5 approval). Sample in vault Files/firm-content-samples/.
- [~] D5. Demo data set: DEFERRED seeding (user decision 2026-10-13: no FMP feed now, no bond data feed — skip additional model generation; the 3 existing portfolios already prove the machinery). Spec retained for when data arrives: `asset-mgmt-db/specs/item-d5-demo-mandate-expansion-spec.md` (2 new strategies FI_ONLY/EQUITY_ONLY trivial via engine once securities exist; 5 portfolios; client variety; EUR/CHF books deferred — universe 100% USD, no native CHF/EUR securities or feeds). PEOPLE MODEL SHIPPED (migration 029 applied + registered, user addition): `person` (internal staff + external individuals), `client_person_history` (SCD2: BENEFICIAL_OWNER with share_pct sum≤1 per KYC/AML, AUTHORIZED_SIGNATORY, CONTACT, TRUSTEE), `client_rm_history` (SCD2: PRIMARY|DEPUTY RM per client), `portfolio_pm_history` (PM attribution). Demo people seeded (RM-01/02/03, PM-01, COO-01) + assigned to existing clients/portfolios. Future-data dependency noted: CHF/EUR native books also need native-currency index series in index_history for honest benchmarks.
- [ ] D6. CRM-lite: prospect/RM pipeline (who, status, next step, AUM potential) — this is also the RM-conviction tracker.
- [~] D9a. RESTRICTION ENGINE BUILT (user requirement, 2026-10-13): migration 031 applied — `trade_restriction` (BUY-blocks: WASH_TRADE chains from sells, CLIENT_RULE, REGULATORY; jurisdiction-scoped), `wash_trade_window` config (US 61d, CH/DE none documented), `tax_lot` per-lot cost basis (the unit for tax work; FIFO default, method per portfolio). `assetmgmt/restrictions.py` RestrictionEngine: (a) `plant_wash_block` — every SELL in a wash-rule jurisdiction plants a BUY-block for sale_date+window (verified: SPY sale 2026-08-01 → BUY blocked until 2026-10-01); (b) `overview(as_of, portfolio|rm|pm)` — UNIFIED SELL+BUY restriction overview per mandate, per RM book, per PM book with expirations (user spec: checked before any trade, considered in rebalancing/tax-optimization/liquidity sims); (c) `check_trade` pre-trade gate (verified: GLD SELL blocked by CLIENT_RESTRICTION with reconsiderable flag). Wired into D2 alignment (restrictions excluded from actions).
- [ ] D9. Liquidity generation + tax-aware simulation: spec written (`specs/item-d9-liquidity-and-tax-sim-spec.md`) — client needs X → Stage 0 cash sweep, Stage 1 alignment-only plan (ignore gains), Stage 2 tax-aversion toggles (0 ignore / 1 prefer low-gain lots / 2 minimize realized gain s.t. deviation budget) always showing resulting portfolio + deviation-from-model cost statement + wash-sale chain effects (planned repurchases inside blocked windows = unavailable options, never silently executed); never breaches mandate/position/allocation limits or restrictions. v1 = scored greedy (no solver dependency), MILP later. Dependencies: proposal-document artifact class only (tax_lot seeding DEFERRED, tax_parameter DROPPED per user 2026-10-13).
- [ ] D7. Tax-optimization tool (user idea 2026-10-13, RM-retention feature): assess realized + unrealized capital gains per client jurisdiction (likely Nov–Dec run), propose rebalancings/position trims to optimize tax outcome. jurisdiction-aware tax lots; output = proposal document for RM + client. Feeds from position cost basis (portfolio_cost_basis_override exists) + realized/unrealized ledger. RM-facing highlight.
- [ ] D8. Position-risk rule engine: mechanical monitors from A4 §4 — −20%→half, −25%→review warning, −30%→exit, 6%→trim-to-5%, 50%-over-target warning, <0.5% warning; emits warning/review events into B5 events pipeline; config-driven thresholds per mandate.

### WS-E · Compliance & legal documentation stack

- [ ] E1. Lawyer selection: Swiss regulatory lawyer + US securities counsel. REPOSITIONED (2026-10-08, user): trigger-based, NOT a current blocker. Triggers: (a) incorporation date set → engagement for statutes + application dossier; (b) first external material circulation → A1 question list §6; (c) resignation letter planned → E2 contract audit. Until then: build proceeds on documented assumptions.
- [ ] E2. Contract audit: confirm no non-compete hiding in side letters/bonus/pension docs. Trigger: before resignation / before RM outreach. (User checked main contract: no post-termination non-compete.)
- [ ] E3. Integrated compliance manual skeleton (FINMA/FinSA + SEC): section map, then AI-draft per section per the launch plan's 5C list.
- [ ] E4. Client lifecycle documents: client agreement (discretionary mandate), PoA, risk disclosure/appropriateness forms, FinSA key information documents for qualified clients.
- [ ] E5. Custodian/broker workstream: target custodian shortlist, fee comparison, onboarding requirements, agreement review checklist.
- [ ] E6. KYC/onboarding process map: step-by-step flow (prospect → proposal → agreement → PoA → custodian account → funded), with document checklist and responsible party per step. This is the "demo the full process" script.
- [ ] E7. Marketing compliance sign-off process (internal): who reviews materials, versioning, filing — needed because everything in WS-C must pass this.
- [ ] E8. AML framework first draft (risk analysis, KYC standards) — can be drafted now, finalized with external compliance firm.
- [ ] E9. SO pre-engagement: pick 1–2 SOs, initial informal contact on expectations.

### WS-F · The demo ("fake full operations" as a product)

- [~] F1-pre. DEMO FRAMING (user, 2026-10-13): RMs should NOT see the automation/AI machinery — they observe the RESULT: unparalleled coverage and service each mandate and position gets. Demo shows the artifacts as if a large staff produced them; pipeline stays backstage. F1 script written to this framing.
- [~] B5d. SECTOR-MOVE ANALYSIS module BUILT (user requirement, 2026-10-13): when a whole sector moves significantly (monitored beyond our universe), produce dispersion analysis WITHIN our universe — who led, who lagged, vs-sector spreads, our-positions overlay (our_led/our_lagged) — investment-letter material. `firm-content/compiler/sector_analysis.py`: equal-weight sector stats + member ranking + portfolio overlay, any lookback; YAML to content-assets/sector_analysis/. Verified: Technology 2026-06-05 — 13 members, mean −6.44%, dispersion 3.59%, AAPL led (−1.2%) / INTC lagged (−11.3%), both ours (genuine letter story).
- [~] F1. Define the demo script: 45–60 min walkthrough weaving all three tracks (RM / client / anchor) — firm intro → live AM database (portfolio, drift, trade plan) → sample client report → sample investment letter → onboarding flow walkthrough → timeline & economics. NOW TOPIC 5 of the interactive marketing series (2026-10-09).
- [~] F2. Build the demo environment: demo mandates (D5), demo letters (C5 pipeline), demo report pack (D4) all populated and consistent with each other. Now also doubles as the Track-1 shadow-portfolio engine and the Track-3 consolidated-picture demo (per small-step menu).
- [ ] F3. RM target list: names, custodian, client base profile, AUM estimate, relationship history, approach angle. Private file. Now also includes the Track-3 anchor-candidate sourcing (liquidity-event press, wealth lawyers, tax advisers, MFO declines).
- [ ] F4. Outreach sequencing: who first (closest relationships), what to say given E1/A1 constraints (post-resignation timing per contract audit E2).
- [ ] F5. Convert 1–2 RM verbal commitments into a light "letter of intent" / cooperation outline (non-binding but concrete: indicative AUM, fee share expectations). This is the assurance that justifies the launch risk.

### WS-G · Corporate setup (parallel track, mostly user actions)

- [ ] G1. Incorporate AG (notary, statutes, capital) — per launch plan Phase 0.
- [ ] G2. Bank account for the AG, accounting setup, audit firm.
- [ ] G3. Office/infrastructure: address, IT stack, email domain, phone.
- [ ] G4. Coordinate with launch plan timeline; update launch plan doc when decisions land here.

### WS-H · Pooled vehicles & later-stage (parked)

- [ ] H1. AMC/fund structure sketch — parked until core business is real (per launch plan).

---

## 2. Dependency map (what unlocks what)

- A1 (pre-license marketing rules) → gates C2, F4 outreach content
- A3 (product shelf) → B2 fees, C1, C3, D1 mandate registry, F1 demo
- B2 (brand tokens) → all of WS-C, B7, D4
- B5 (content pipeline) → C5 letters
- D1/D2/D3 (DB core) → D4 reporting → C7 → F2 demo
- E1 (lawyers) → E4 final docs, A1 definitive answer, E2 contract audit
- E6 (onboarding map) → F1 demo script section
- F2 → F3/F4/F5 (RM campaign)

**Critical path to the RM pitch:** A1 → A3 → B2 → B4/B6 → C1/C2 + D1/D4/D5 → E6 → F1/F2.

## 3. Work order (suggested first sprints)

1. Sprint 1: A1 question-list draft, A2, A3, E2, B1 architecture decision, D1 inventory.
2. Sprint 2: B2, B3, B4 (first daily commentary produced for real), A4, A5.
3. Sprint 3: B6 rendering, C1, C3, E6 map, D2.
4. Sprint 4: C2 RM deck, C5 letters pipeline, E3/E4 first drafts, demo seeding (D5).
5. Then: iterate toward F1/F2 demo-ready, run E1 lawyer calls, G1 incorporation.

## 4. Open questions for user `[?]`

- Fee schedule: 6 open decisions in `fee-schedule-draft.md` §4 (tier rates, minimums, performance-fee module, founding-RM step-up)
- Firm name: placeholder `[FIRM]` until naming discussion (A2)
- Branding details (palette, fonts, tone calibration) — later, B2
- Who are the 1–3 first-target RMs (F3) — only when we're close to demo-ready
- Website domain/hosting preference (B7) — pre-launch item

## 4b. Parked user action items (non-blocking)

- Item 4B sign-off in asset-mgmt-db: run the suggested demo path (what-if P-00005 Conservative vs USD_OFFENSIVE — 15 actions, 47.7% turnover, ~30,257 CHF indicative G/L on TEST data — then a floor/tolerance variation) and confirm numbers look sane. Unblocks Item 3 (rebalance workflow) — which we need for D2/D3 anyway, so worth doing before Sprint 4.

## 6. A1 — Lawyer question list (pre-license marketing & RM outreach)

> Purpose: single batch of questions for the Swiss regulatory lawyer (first call, before building WS-C demo materials). Answers gate C2 (RM deck), F1 (demo script), F4 (outreach sequencing).

1. **Pre-license status of materials.** Once the AG is incorporated but before FINMA license: may we (a) show our internal AM database, sample model portfolios, and sample client reports to prospective RMs in a private meeting? (b) circulate a firm presentation deck? (c) circulate sample investment letters? What must be labeled/disclaimed?
2. **FinSA "financial service" boundary.** At what point does showing portfolio models / commentary to a prospective client constitute providing a financial service (personal recommendation / advertisement under FinSA Art. 3, 68)? Does discussing a model portfolio's positioning with an RM cross that line pre-license?
3. **RM intermediation.** RMs introducing clients: are they "client advisers" needing registration in the client adviser register (FinSA Art. 24–28) when acting for our unlicensed-yet firm? Does their current employer status create issues for pre-commitment talks?
4. **Client agreements pre-license.** Can we sign binding mandate agreements with clients that become effective upon license grant, or must everything be conditional?
5. **Track record.** We have no firm track record; my personal record is at the current employer. What can lawfully/prudently be shown (GIPS-style, employer-attributed, disclaimed) in decks and reports?
6. **SEC side.** Same questions pre-SEC-registration (can be batched with US counsel later — lower priority since FINMA license gates operations anyway).
7. **Contract audit** (E2): review of employment contract + side letters to confirm absence of post-termination non-compete and of any garden-leave/notice-period restrictions on preparing to compete.

## 7. Worklog

- 2026-10-08: Roadmap created. Inputs: user decision to pursue RM pre-commitments; contract check found no post-termination non-compete (verify via E2); AM database build already started (D1).
- 2026-10-08 (session 2): B1 decided (local-only git repo, no remote). A3: risk-profile ladder fixed (FI-only→Conservative→Balanced→Offensive→Equity-only + variants; centralized models + client constraints — matches asset-mgmt-db design). D1 inventory done — asset-mgmt-db is mature (SCD2, reconstruction, fees, 3 sample strategies); gaps identified (trade workflow, reporting generator, RM tracking, demo seeding, CHF/EUR books). A1 lawyer question list drafted (§6).
- 2026-10-08 (session 3): A3 fee schedule drafted (`fee-schedule-draft.md`, v0.1, 6 open user decisions). A2: name = `[FIRM]` placeholder via config-token (rename = one line); branding direction captured (conservative + modern systems; fundamentals + price-action overlay + risk mgmt). A1 + E1/E2 repositioned trigger-based (user: no lawyer needed at this stage; 4B sign-off is internal QA, parked as user action in §4b).
- 2026-10-09 (session 4): Book-import tooling modernized per user decision — new generic `/home/rpi/book_import.py` (model permanently `google/gemini-3.6-flash`, replacing minimax-m3; old one-off scripts deprecated). *The Challenger Sale* imported as skill `business/challenger-sale` (14/15 sections; Appendix C has no text layer in the PDF, noted in skill). Purpose: marketing-approach input for WS-C/A5 (RM pitch, insight-led client conversations). Extraction includes per-chapter B2B→asset-management adaptation lens.
- 2026-10-09 (session 5): Research + RM economics complete (topics 1–3). Fee schedule, participation structure v2 (corrected after stress-test found 148–234% comp outcomes), walkthrough with 10-year paths, opex build-up staged, founder-fare verified (26–31% of gross at every stage; opex never >8bp). RM model: no-direct-books founders, 100% RM-sourced revenue. Economics workstream PARKED per user ("look closer later") — all state in skill `business/firm-launch-rm-economics`. NEXT: topic 4 client-track messaging.

## 8. Production migration — Pi → production machine (PLANNED, not yet actioned)

> User directive 2026-10-13: once everything is built, nothing stays on this Raspberry Pi. Migration to a
> new, more powerful machine is required. NOT actioned now — this section is the plan skeleton to be
> detailed at migration time. At that point: write the full migration plan + a **Hermes bootstrap
> instruction pack** so the Hermes instance on the new machine can install and configure everything and be
> fully operational quickly.

### 8.1 What moves (project scope only)

| Component | Source on Pi | Target | Notes |
|---|---|---|---|
| asset-mgmt-db repo + engine worktree | `~/asset-mgmt-db` (incl. `.worktrees/t_945c3468` merged or re-created) | same path layout | git bundle export; merge worktree engine into master first (migration prep task) |
| PostgreSQL 17 + full DB dump | native, `/tmp` socket, port 5433, db `asset_mgmt`, user `rpi`; cluster under `/home/rpi/pg17` | same version, new socket paths | `pg_dump`/`pg_restore` or basebackup; re-register `_migrations` checksums; **fresh DB credentials** |
| firm-content repo (local-only git) | `~/firm-content` | same layout | NEVER hosted online pre-launch (B1 rule) — transfer via encrypted medium, not a remote |
| Migrations, specs, scripts | inside both repos | — | includes `sql/`, `specs/`, `scripts/` |
| Hermes skills (project) | `~/.hermes/skills/` (firm-*, asset-mgmt-db, book-import, challenger-sale, rss-feeds…) | new machine's profile | skills carry the procedural memory |
| Commentary library (FRESH START) | — | new vault, curated | see 8.2 — old vault is NOT copied wholesale |

### 8.2 Obsidian vault: FRESH START (user directive)

- New vault contains **only**: needed directory skeleton (`00-methodology`, `03-research/business`, `03-research/commentary/*`, `04-performance`, `_templates/*`, `Files/`), the firm-relevant templates, and a few example drafts.
- The current vault contains **private material that must NOT move to the firm machine** — full-vault sync is forbidden. Curated export list to be written at migration time (templates + selected business docs + commentary library seeded fresh).
- Business docs worth carrying: this roadmap, launch plan, RM/participation/opex/fee docs, specs. Methodology docs only if firm-relevant (risk-framework, templates).

### 8.3 Hermes bootstrap instruction pack (the "get operational fast" deliverable)

A single instruction document (plus scripts) the new machine's Hermes executes top-to-bottom:
1. **System**: install/verify Python 3.14+, PostgreSQL 17 (native), Typst binary, fonts (Source Serif 4, Inter, Lexend), venv with engine deps.
2. **Repos**: restore `asset-mgmt-db` + `firm-content` from encrypted bundles; verify git integrity + no remote configured.
3. **DB**: start cluster (`start_pg.sh` equivalent), restore dump, re-register migrations, run test suite (126+ tests) as the acceptance gate.
4. **Engines**: verify performance/contribution/datapack/narratives import and smoke-test on P-00005 (known expected numbers: 14.8%/10.0%/+4.8%, value 2'311'616).
5. **Compiler**: regenerate the four practice artifacts; compare against known-good checksums/layout.
6. **Movers + events**: run a sweep; confirm event library intact.
7. **Hermes config**: profile, skills, cron (sweeps), memory notes relevant to the project; connection details updated (new host paths/ports).
8. **Vault**: create fresh Obsidian vault from curated skeleton (8.2).
9. **Acceptance checklist**: one page — every component green = migration done; failure = rollback and fix.

### 8.4 Open items for migration time `[?]`
- Target hardware/OS choice (user decides; "more powerful device").
- Whether engine worktree merges to master before or during migration (recommend: before — one codebase to move).
- Fresh credentials/keys policy (DB password, API keys — re-issued, never copied from Pi configs).
- Demo-data policy: re-seed on new machine from scripts (deterministic) vs copy the DB dump (faster) — recommend dump for continuity, scripts as fallback.
- Cron/schedule re-registration on the new host.