Repository Public
1<!-- Author: Simon-Pierre Boucher — contact@spboucher.ai · File: README.md -->2<div align="center">34<img src="docs/brand/logo.svg" alt="VQuant for macOS logo" width="560">56<br><br>78<img src="docs/brand/icon.png" alt="VQuant for macOS icon" width="112" height="112">910# VQuant for macOS1112**The native macOS workstation of the VQuant research desk — markets, charting, the research agent, the Quant13Engine, data explorer, portfolio and risk, with the same account and the same passkeys as the web app.14Swift 6, SwiftUI and AppKit. No web view, no third-party dependency.**1516**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1718[](https://vquant.spboucher.ai)19-7c3aed?style=for-the-badge)2021222324252627282930313233343536[](https://git.spboucher.ai/vquant-macos/commits)37[](https://git.spboucher.ai/vquant-macos/commits)38[](https://git.spboucher.ai/vquant-macos/insights)39[](https://git.spboucher.ai/vquant-macos)40[](https://git.spboucher.ai/vquant-macos/insights)41[](https://git.spboucher.ai/vquant-macos)42[](https://git.spboucher.ai/vquant-macos/branches)43[](https://git.spboucher.ai/vquant-macos/tags)44[](https://git.spboucher.ai/vquant-macos)454647484950515253545556575859606162636465</div>6667---6869## Table of contents7071- [Overview](#-overview)72- [Features](#-features)73- [Architecture](#-architecture)74- [Stack](#-stack)75- [Repository layout](#-repository-layout)76- [Build and run](#-build-and-run)77- [Configuration](#-configuration)78- [Sections and windows](#-sections-and-windows)79- [Backend API used](#-backend-api-used)80- [Local data](#-local-data)81- [Security and privacy](#-security-and-privacy)82- [Testing](#-testing)83- [Release](#-release)84- [First sign-in on a Mac](#-first-sign-in-on-a-mac)85- [Troubleshooting and gotchas](#-troubleshooting-and-gotchas)86- [Known limitations and next steps](#-known-limitations-and-next-steps)87- [Documentation](#-documentation)88- [Author](#-author)89- [License](#-license)9091---9293## 🎯 Overview9495VQuant for macOS is the native client (Swift 6, SwiftUI, AppKit where it earns its place) of the VQuant server at96`vquant.spboucher.ai`. VQuant is, at its core, the **autonomous quantitative research agent**; the terminal, the97Quant Lab, the portfolios and the Research Studio are surfaces around it — with the same account and passkeys as the98web app, and one synced state across web, Mac and iPhone. **No web view.** Computation, data and model inference stay on99the server; the Mac computes only display aids from data it was sent (chart indicators, descriptive portfolio100statistics) and labels them as such.101102- Version **2.0.0 (3) "VQuant Next"** · macOS 14+ · universal (arm64 + x86_64) · Developer ID signed. 2.0.0 was103 notarized by Apple on 2026-11-20 (submissions 7204cfbb… app, 60682e96… disk image, both Accepted), stapled, installed in /Applications and published as `VQuant-2.0.0.dmg` (sha256 044d90ed…) under spbgit releases `vquant-macos/v2.0.0`. The previous 1.0.1 app is kept in `~/Library/Developer/VQuant/backup/`.104- Backend: 2.0.0 needs **backend 6 "VQuant Next"** (`/api/v2/*`, contract `vquant-next/docs/next/CONTRACT.md`); the 1.x105 routes it still uses are those of v5.8.0. Shared package: [`VQuantKit`](../VQuantKit) (local dependency `../VQuantKit`).106- The application follows what the backend really offers: there is no WebSocket feed and no trading, so nothing is107 called "live" and no order can be placed (see108 [`docs/MACOS_ARCHITECTURE.md`](docs/MACOS_ARCHITECTURE.md)).109110### What is new in 2.0.0 "VQuant Next"111112An upgrade of 1.0.1, not a rewrite — everything 1.0.1 did is still there. Evidence for every line is in113[`docs/FEATURE_PARITY.md`](docs/FEATURE_PARITY.md) and [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md).114115| Area | 2.0.0 |116|---|---|117| **One account, synced** | Watchlists, portfolios, chart layouts and drawings, projects, notes, preferences and mappable window layouts are synced objects (`VQSyncEngine`, replica sealed with the cache key). 1.x local watchlists and layouts are migrated once, without loss. Sync status and conflict notices in the toolbar |118| **Research (the centre)** | Research mode with dataset attachment and inspection, budgets, a model picker reading the server registry with "Auto" and its routing reason, usage and cost; the **research cockpit** (report + inspector: Activity · Code · Experiments · Figures · Files · Environment); approvals; studies list; resume by REST; provenance and trace of any analysis |119| **Terminal** | Market overview with yield curve and calendar and a freshness chip per section; synced watchlists with multi-select and drag-reorder; ⌘K command palette; statements with period compare, common size and a formula inspector |120| **Charting** | Bars from the v2 data layer with provenance; drawing tools anchored to time and price, stored in the synced chart object; "Ask the agent about the visible range"; a renderer 3–100× faster on long series (Core Graphics kept after measuring: [`docs/CHART_PERFORMANCE.md`](docs/CHART_PERFORMANCE.md)) |121| **Quant Lab** | 19 engines by category, forms generated from the tool specification, progress and cancel, one result renderer, compare, dedicated options and backtest layouts with integrity statements always visible, automated review (always labelled as such) |122| **Portfolios** | Several portfolios (`main` is the agent's), in-place editor, CSV import with preview, valuation by currency, analysis with `portfolio_lab` / `risk_lab`, rebalancing as a proposal — never an order |123| **Research Studio** | Projects with question, hypotheses and items; notes with a markdown editor and versions; reviews; exports PDF / MD / LaTeX / ZIP; project memory |124| **Mac** | 14 destinations with shortcuts, Research and Lab menus, 20 Settings panes (routing with live preview, budgets, memory, usage and cost, audit log, data providers, sync), notifications routed to their window, a menu-bar extra, windows restored where they were |125126Fixed on the way (defects present since 1.0): a detached chart window opened while signed in was blank; a window127re-opened by a saved layout was blank; restored windows came back on the default section.128129### Family130131| App | Platform | Repository | Role |132|---|---|---|---|133| **VQuant** | Web — `vquant.spboucher.ai` | [git.spboucher.ai/vquant](https://git.spboucher.ai/vquant) | Backend and web app: agent, data, Python quant engines, reports, passkey gate, native bridge |134| **VQuant for macOS** (this repository) | macOS 14+ native | [git.spboucher.ai/vquant-macos](https://git.spboucher.ai/vquant-macos) | Native workstation on the same accounts and passkeys |135| **VQuant for iOS / iPadOS** | iOS · iPadOS native | [git.spboucher.ai/vquant-ios](https://git.spboucher.ai/vquant-ios) | Native iPhone and iPad client of the same backend |136137---138139## ✨ Features140141The tables of this section describe what 1.0.1 already had (all of it is still there); what 2.0.0 adds is in142[What is new in 2.0.0](#what-is-new-in-200-vquant-next) above. Classes follow143[`docs/FEATURE_PARITY.md`](docs/FEATURE_PARITY.md): **native** (done on the Mac), **server-backed** (native interface,144the server does the work), **kit** (shared package).145146### Markets147148| Feature | Details |149|---|---|150| **Overview** | Index ticker and analyses in progress |151| **Markets** | Indices, movers (gainers, losers, most active), exchange hours |152| **Watchlists** | Synced with the account since 2.0 (1.0.1: local to the Mac); symbols can be dragged into a list |153| **Symbol search** | `⌘K`, backed by `/api/fmp/search` |154| **Data freshness** | Five stated states: **Recent** (provider timestamp under 2 min), **Delayed**, **Historical**, **Cached** (server unreachable; last value this Mac received), **Unavailable**. The provider's timestamp is shown; quotes are polled over HTTPS and nothing is called "live" |155156### Charting157158| Feature | Details |159|---|---|160| **Chart types** | Candles, OHLC, line, area; volume; logarithmic scale |161| **Indicators** | SMA, EMA, Bollinger bands, RSI, MACD — computed on the Mac from server bars and unit-tested |162| **Intervals** | 1 min, 5 min, 15 min, 30 min, 1 hour, 4 hours, 1 day |163| **Interaction** | Crosshair, pan and zoom (pointer, scroll, pinch, keyboard), symbol comparison |164| **Chart windows** | `⇧⌘N` opens a chart window, `⇧⌘D` detaches the current chart; crosshairs of linked charts follow each other |165| **Rendering** | Core Graphics through SwiftUI `Canvas`; when more bars are visible than fit, neighbours are merged for drawing only and the chart states "1 mark = n bars" |166| **Export** | PNG, PDF, CSV (CSV writes the source bars, not the merged marks) |167168### Research169170| Feature | Details |171|---|---|172| **Research agent** | Chat with the server's agent: four modes, model choice, image attachment by drag and drop |173| **Live run view** | Status, plan, tools, sub-analysts, figures, follow-ups — 20 stream event types decoded; an unknown type is counted and reported, never dropped silently |174| **Resilient runs** | An analysis is a server job: the runner reconnects and replays from the last event; Stop cancels it |175| **Conversations** | List, search, rename, pin, delete |176| **Reports** | Native Markdown renderer: tables, text, figures, report markers, sources |177| **Export** | PDF, Word and slides rendered by the server |178| **Quant Engine** | GARCH, VaR, Monte Carlo, options, portfolio optimiser and risk metrics as server jobs **with provenance** (parameters, the Python code that ran, the result); result figures with Swift Charts (frontier, distributions, volatility forecast, allocation, drawdown) |179| **Data Explorer** | 15 datasets (income statement, balance sheet, cash flow, key metrics, ratios, analyst estimates, price targets, grades, earnings surprises, dividends, institutional holders, insider trading, news, ESG, daily prices): sort, filter, date range, columns, CSV, plot |180181### Portfolio and workspace182183| Feature | Details |184|---|---|185| **Portfolio** | Valuation, allocation and CSV, computed on the Mac from server positions and quotes. A record of holdings: no order can be placed |186| **Risk Analytics** | Descriptive statistics from daily closes (labelled as native) and launch of the server engines |187| **Agent** | The agent's long-term memory, portfolio and scheduled watches |188| **Jobs** | Analyses and computations, running and finished |189| **Documents** | Shared reports |190191### Mac-native192193| Feature | Details |194|---|---|195| **Windows** | Any number of workstation windows, each with its own section, symbol and conversation; tabs, full screen |196| **Saved layouts** | `⌃⌘S` saves the open windows, what each shows and its frame |197| **Menus and shortcuts** | Native toolbar, menus, context menus; `⌘1`…`⌘9` switch sections |198| **Device sessions** | List and revoke device sessions, list passkeys, sign out (Settings) |199| **Touch ID app lock** | `⌃⌘L` locks; the session token is released by the Keychain only after Touch ID |200| **Offline reading** | Network-first encrypted cache: only a network failure falls back to the last stored value, marked as cached |201| **Notifications** | When a job ends in the background |202| **Network diagnostics** | In Settings |203204---205206## 🏗 Architecture207208```mermaid209flowchart LR210 subgraph MAC["VQuant.app — sandboxed, hardened runtime"]211 subgraph UI["App target — SwiftUI/AppKit · MainActor"]212 V["VQuantApp<br/>scenes · commands"]213 E["AppEnvironment<br/>dependency container"]214 ST["Stores<br/>Session · Market · Workspace · Research · Quant"]215 F["Features<br/>14 sections · Settings · Sign-in"]216 end217 subgraph CORE["VQuantCore — SwiftPM · Sendable · no UI"]218 N["Networking<br/>HTTPTransport · APIClient · SSEParser"]219 AU["Auth<br/>AuthService · TokenStore"]220 SV["Services<br/>VQuantAPI · GenerationRunner"]221 C["Cache<br/>DiskCache AES-GCM · Freshness"]222 AN["Analytics<br/>Indicators · Downsampler · CSV"]223 end224 KC[("Keychain<br/>device token · cache key")]225 PK["System passkeys<br/>Touch ID · iCloud Keychain"]226 end227 S["VQuant server<br/>vquant.spboucher.ai"]228 V --> E --> ST --> F229 ST --> SV --> N230 ST --> AN231 SV --> C232 AU --> KC233 AU --> PK234 AU --> N235 N -->|"HTTPS · JSON · SSE<br/>Bearer device token"| S236```237238### Native passkey sign-in239240```mermaid241sequenceDiagram242 participant A as VQuant.app243 participant OS as macOS authenticator244 participant S as VQuant server245 participant K as Keychain246 A->>S: POST /api/native/login/options247 S-->>A: challenge248 A->>OS: passkey assertion (Touch ID)249 OS-->>A: signed assertion250 A->>S: POST /api/native/login/verify251 S-->>A: device token (shown once, stored hashed on the server)252 A->>K: store token (this device only, not synced)253 A->>S: every request carries the Bearer token254 Note over A,S: a 401 signs the Mac out and erases the cache, a network failure never does255```256257### An analysis from the Mac258259```mermaid260sequenceDiagram261 participant A as GenerationRunner262 participant S as VQuant server263 A->>S: POST /api/chat264 S-->>A: SSE events (job, status, plan, tools, text, figures)265 Note over A,S: stream cut266 A->>S: GET /api/generations/:id/stream?from=n267 S-->>A: replay from event n, then live268 A->>S: POST /api/generations/:id/cancel (Stop)269```270271- **Dependency injection.** `AppEnvironment` is built once and passed explicitly to every view.272 `@Environment(Model.self)` is deliberately avoided: on macOS 27 it traps inside table cells, menus, sheets and273 toolbars. Core types take protocols (`HTTPTransport`, `TokenStore`, `PasskeyAuthenticator`) so tests substitute them.274- **Concurrency.** Core is `Sendable` and compiled in Swift 6 mode with complete checking; the app target defaults275 to `MainActor`. Long work is `async`; the main thread never waits on the network.276- **Server responsibilities stay on the server**: model inference, web research, the Python notebook, every277 quantitative engine, PDF/DOCX/slide rendering, persistence, per-person authorisation.278- **Charting.** Metal was evaluated and not used: the heaviest series is reduced to at most one mark per279 2.5 points before drawing, so the cost of a frame is bounded by the window width, not by the series length.280281---282283## 🧱 Stack284285| Layer | Technology | Version / setting | Role |286|---|---|---|---|287| Language | Swift | 6.0, `SWIFT_STRICT_CONCURRENCY: complete` | Everything |288| UI | SwiftUI + AppKit | `@Observable`, typed `WindowGroup` restoration | Windows, sections, menus |289| Charts | Core Graphics (`Canvas`) · Swift Charts | — | Price charts · result figures |290| Auth | AuthenticationServices · LocalAuthentication | — | Platform passkeys · Touch ID lock |291| Storage | Keychain · AES-GCM disk cache | — | Device token · offline reading |292| Core | SwiftPM package `VQuantCore` | swift-tools 6.0 | Networking, auth, streaming, models, cache, analytics |293| Project | XcodeGen (`project.yml`) | — | Generates `VQuant.xcodeproj` |294| Minimum system | macOS | 14.0 | `@Observable`, `SectorMark`, `onChange(of:initial:)`, `SettingsLink` |295| Dependencies | none | 0 packages | Checked on the signed bundle by `Scripts/verify-release.sh` |296297---298299## 🗂 Repository layout300301```302vquant-macos/303├── Package.swift # SwiftPM: VQuantCore (Core/), VQuantAppLogic (kit-dependent logic of App/Next), tests304├── project.yml # XcodeGen: app target VQuant (+ VQuantKit, VQuantUI from ../VQuantKit) + VQuantUITests305├── App/ # 16 files · 3 186 lines306│ ├── VQuantApp.swift # scenes (main, chart, Settings, menu-bar extra), commands, layouts, launch guard307│ ├── AppEnvironment.swift # dependency container: api (1.x), vq (kit), sync, feature-store registry308│ ├── Navigation.swift # AppSection (14), MainSpec, ChartSpec, WindowModel, AskDraft309│ ├── SessionStore.swift # sign-in, lock, expiry310│ ├── Stores.swift, ResearchStore.swift, QuantStore.swift, LabStore.swift, SettingsStore.swift, Notifier.swift311│ └── Next/ # KitBridge (transport adapter, cipher), SyncStore, StudyStore, Commands,312│ # WorkspaceMapping, MacLogic (shortcut table, notification routes)313├── Features/ # 51 files · 15 534 lines — one folder per area314│ ├── Shell/ # MainWindow, SyncStatusView315│ ├── Auth/ # SignInView, SystemPasskeyAuthenticator316│ ├── Research/ # composer, cockpit (inspector), insight (route, usage, provenance, trace, approvals)317│ ├── Studio/ # projects, note editor, reviews, memory, export318│ ├── Terminal/ # overview, yield curve, watchlists, command palette, statements319│ ├── Markets/, Data/ # 1.x Markets and Data Explorer320│ ├── Charting/ # canvas, interaction, drawings, sync, provenance, ask, benchmark harness321│ ├── Quant/ # lab catalogue, generated forms, jobs, results, compare, review, options / backtest322│ ├── Portfolio/ # portfolios, holdings, CSV import, analysis and proposal, risk analytics323│ ├── MenuBar/, Agent/324│ └── Settings/ # 20 panes325├── Components/ # 4 files · 706 lines — DesignSystem, InlineEditing, GridTable, MarkdownView326├── Core/ # 25 files · 4 166 lines — VQuantCore (no UI, no kit)327│ ├── Networking/, Auth/, Services/, Models/, Cache/, Support/328│ ├── Analytics/ # Indicators, Downsampler, ChartDrawings, PortfolioImport, CSV329│ ├── Markdown/ # blocks, editing330│ ├── Terminal/, Lab/ # selection, statement maths, palette ranking, lab support331│ └── Stores/LocalStores.swift # 1.x local stores (now only the migration source and local-only layouts)332├── Resources/ # Info.plist, entitlements (Release / Debug), Assets.xcassets (AppIcon, AccentColor)333├── Scripts/ # build, tests, dev session (5058), restore check, provisioning, release, verification334├── Tests/335│ ├── CoreTests/ # 16 files + Fixtures/ (40 recorded responses) + Support/ (mocks)336│ ├── SyncTests/ # migration rule against the kit's fake server337│ └── UITests/ # 9 files · 30 tests338└── docs/ # reference documents + brand/339```340341---342343## 🛠 Build and run344345```bash346Scripts/build.sh debug # Debug build (products in ~/Library/Developer/VQuant)347swift test # core tests348Scripts/integration-test.sh [--analysis] # against the VQuant Next TEST backend (M2U64:~/dev/vquant-next-api, :5058)349Scripts/ui-test.sh # XCUITest, signed in on the test copy350Scripts/run-dev.sh [--shot f.png] [-- -VQSection charting -VQSymbol MSFT]351python3 Scripts/provision.py && Scripts/release.sh && Scripts/verify-release.sh && Scripts/notarize.sh352```353354| Script | Purpose |355|---|---|356| `Scripts/build.sh generate\|debug\|core-test\|ui-test` | Development entry point: generate the Xcode project, build Debug, run the core and UI tests. Products go to `~/Library/Developer/VQuant` (outside `~/Desktop`: TCC and Launch Services treat Desktop specially) |357| `Scripts/dev-session.sh` | Opens the SSH tunnel to the backend test copy and a device session on it (software passkey). `eval "$(Scripts/dev-session.sh)"` sets `VQ_SERVER` and `VQ_DEV_TOKEN`; the token is never printed to the terminal |358| `Scripts/run-dev.sh` | Launches the Debug build against the test copy with a development session (in-memory stores: no Keychain, no real cache), optionally capturing its window |359| `Scripts/integration-test.sh` | Core suite against the real backend test copy (never production); `--analysis` also runs one fast and one cancelled analysis (calls the model provider: a few cents) |360| `Scripts/ui-test.sh` | XCUITest: the signed-out screen, and navigation of every section while signed in on the test copy |361| `Scripts/check-headers.sh` | Fails when a first-party source file lacks its author header |362| `Scripts/provision.py`, `Scripts/asc.py` | Register the bundle id, its Associated Domains capability and the Developer ID profile with the existing App Store Connect API key (idempotent) |363| `Scripts/release.sh` · `verify-release.sh` · `notarize.sh` | Release archive, bundle checks, notarization (see [Release](#-release)) |364| `Scripts/make-icon.swift` · `window-shot.swift` | Icon generator · window capture helper |365366The test backend is the frozen VQuant Next API on its node (`M2U64:~/dev/vquant-next-api`, `PORT=5058`,367`PASSKEY_ORIGIN=http://localhost:5058`, a copy of production data; test objects are prefixed `mac-test-`). Debug builds368cannot use system passkeys; they receive a development session minted on the node by the copy's own helper369(`Scripts/dev-session.sh`; the token is kept in a private file and never printed). `Scripts/run-dev.sh` documents the370launch arguments that open any destination (`-VQSection`, `-VQTheme`, `-VQTab`, `-VQSettings`, `-VQX…`), and371`Scripts/restore-check.sh` checks window restoration with real key presses and a real quit.372373---374375## ⚙️ Configuration376377| Setting | Where | Meaning |378|---|---|---|379| Server | `App/AppEnvironment.swift` | `https://vquant.spboucher.ai`; a local override (`-VQServer` argument or `VQ_SERVER`) is accepted for `localhost` / `127.0.0.1` only |380| `VQ_DEV_TOKEN` | environment, Debug | Development session issued by `Scripts/dev-session.sh` |381| `-VQSection`, `-VQSymbol` | launch arguments | Open a given section and symbol (`Scripts/run-dev.sh`) |382| `VQ_DERIVED` | environment | DerivedData location for the UI tests (default `~/Library/Developer/VQuant/DerivedData`) |383| `NOTARY_PROFILE` | environment | Existing `notarytool` keychain profile used by `Scripts/notarize.sh` |384| Bundle identifiers | `project.yml` | Release `ai.spboucher.vquant` · Debug `ai.spboucher.vquant.debug` · UI tests `ai.spboucher.vquant.uitests` |385| Entitlements (Release) | `Resources/VQuant.entitlements` | App Sandbox, network client, user-selected read-write files, Associated Domains `webcredentials:vquant.spboucher.ai`, Keychain access group |386| Entitlements (Debug) | `Resources/VQuant-Debug.entitlements` | App Sandbox, network client, user-selected read-write files (no restricted entitlement) |387388---389390## 🖥 Sections and windows391392| Group | Section | Shortcut |393|---|---|---|394| Research | Research | `⌘1` |395| Research | Research Studio | `⌘2` |396| Terminal | Overview | `⌘3` |397| Terminal | Markets | `⌘4` |398| Terminal | Watchlists | `⌘5` |399| Terminal | Charting | `⌘6` |400| Terminal | Statements | `⌘7` |401| Quant | Quant Lab | `⌘8` |402| Portfolio | Portfolios | `⌘9` |403| Terminal | Data Explorer | View menu |404| Portfolio | Risk Analytics | View menu |405| Quant | Jobs | View menu |406| Workspace | Agent | View menu |407| Workspace | Documents | View menu |408409| Scene | Description |410|---|---|411| `WindowGroup(id: "main", for: MainSpec.self)` | Any number of workstation windows; each has its own `WindowModel` (section, symbol, conversation, selected computation), restored by macOS where it was |412| `WindowGroup(id: "chart", for: ChartSpec.self)` | Detached chart windows (symbol, interval, range, comparisons restored) |413| `Settings` | Panes include Account, Security (Touch ID and passkeys), Devices, Cache, Notifications and Network (diagnostics) |414415Other commands (one table in code, `AppShortcuts`, with a unit-tested collision check): `⌘K` command palette ·416`⌥⌘F` find symbol · `⌘R` refresh now · `⌥⌘S` sync now · `⌥⌘N` new conversation · `⇧⌘R` new research study ·417`⇧⌘A` attach dataset · `⌘.` stop analysis · `⌥⌘I` research inspector · `⇧⌘L` lab catalogue · `⌥⌘R` run again ·418`⇧⌘N` new chart window · `⇧⌘D` detach chart · `⇧⌘S` save window layout (was `⌃⌘S` in 1.0.1, which is the system's419Show/Hide Sidebar) · `⌃⌘L` lock VQuant. A menu-bar extra (Settings › Appearance) shows the market session, a few420indices, running work and a quick ask.421422---423424## 🔌 Backend API used425426Every route the client calls was read in the backend source and is listed, with its verification status, in427[`docs/API_INVENTORY.md`](docs/API_INVENTORY.md). The client calls no route outside that inventory428(`Core/Services/VQuantAPI.swift`, `Core/Auth/AuthService.swift`). Transport: HTTPS, JSON, server-sent events;429native clients send `X-VQ-Client: vquant-macos/<version>` and a Bearer device token. There is no WebSocket endpoint.4302.0.0 adds the backend 6 surface (`/api/v2/*`: sync, models and routing, usage, data layer, search, projects, reviews,431memory, audit, autonomous research) through the shared package VQuantKit — part 2 of the inventory.432433| Area | Routes |434|---|---|435| Authentication | `GET /api/health` · `POST /api/native/login/options\|verify` · `POST /api/native/register/options\|verify` · `GET /api/native/session` · `POST /api/native/logout` · `POST /api/native/reauth/options\|verify` · `GET /api/native/devices` · `DELETE /api/native/devices/:id` · `DELETE /api/native/passkeys/:ref` |436| Market data | `GET /api/fmp/indices` · `/gainers` · `/losers` · `/actives` · `/market-hours` · `/search` · `/quote/:symbol` · `/company-profile/:symbol` · `/chart/full/:symbol` · `/chart/intraday/:symbol` · the 15 dataset routes |437| Research agent | `POST /api/chat` · `GET /api/generations` · `GET /api/generations/:id/stream` · `POST /api/generations/:id/cancel` · `GET/PATCH/DELETE /api/sessions[/:id]` |438| Exports and reports | `POST /api/generate-pdf` · `/generate-docx` · `/convert-to-slides` · `GET /api/shared-reports` · `GET /api/share/:id` · `POST /api/share` · `GET /figures/*`, `/plots/*`, `/api/download/:file` |439| Workspace | `GET /api/workspace` · memories, portfolio and watches routes |440| Quant Engine | `GET /api/quant/tools` · `POST /api/quant/jobs` · `GET /api/quant/jobs` · `GET/DELETE /api/quant/jobs/:id` |441| Diagnostics | `GET /api/analytics/real-time-stats` |442443Not exposed on purpose: the admin routes (`/api/admin/*`), which act on every person's data with no per-person444check. Not used: `/api/speech-to-text` (dictation is not ported).445446Server limits the client reports as they are: 4 running analyses per person, one per conversation; analysis jobs447live in the server's memory (a restart ends them); replay for 20 minutes after the end; no cancel route for quant448jobs.449450---451452## 🗄 Local data453454The Mac holds no database: the server is the source of truth.455456| Item | Where | Protection |457|---|---|---|458| Device token (`vqn_…`) | Keychain generic password | `WhenUnlockedThisDeviceOnly`, not synced; behind `SecAccessControl(.userPresence)` when the Touch ID lock is on |459| Offline cache | Disk, per cache key | AES-GCM sealed under a Keychain key, excluded from backups, erased at sign-out or when another person signs in |460| Watchlists | Local store (`Core/Stores/LocalStores.swift`) | Local to the Mac |461| Saved window layouts | Local store | Windows, what each shows, frames and displays |462| Per-window navigation | Scene storage | Restored by macOS |463464---465466## 🔐 Security and privacy467468- **Same people, same passkeys, same relying party** as the web app: nothing new to create for a person who469 already uses it. A passkey created in Safari and synced by iCloud Keychain signs in here, and the reverse.470- **Why the web cookie is not reused**: a native app has no page origin, and the cookie is identical on every471 device and cannot be revoked individually. The bridge issues one opaque **device token** (256 random bits), stored472 on the server as a SHA-256 hash; unused for 90 days it expires; revocation is immediate.473- **Sensitive operations** (revoking another device, deleting a passkey) need a fresh passkey check, valid 5 minutes;474 the last passkey of an account cannot be deleted.475- **The token is the only credential stored on the Mac.** Passkey private keys stay in the system authenticator;476 biometric data never reaches the app or the server.477- **Touch ID app lock**: Touch ID unlocks the credential; the server still authenticates every request.478- **Sign-out** revokes the session on the server, then clears the Keychain and the cache. A 401 (revoked elsewhere,479 expired) signs the Mac out and erases the cache. A network failure never signs out.480- **App Sandbox and hardened runtime**; no web engine, no JavaScript engine, no third-party code, no secret in the481 bundle — all checked on the signed bundle by `Scripts/verify-release.sh` (13 checks).482- **Offline**: nothing is queued while offline; analyses, computations and edits are refused with an explanation.483 A server refusal is always an error, never served from the cache.484485Details: [`docs/AUTHENTICATION.md`](docs/AUTHENTICATION.md).486487---488489## 🧪 Testing490491| Suite | Command | Result for 2.0.0 (details and evidence classes in [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md)) |492|---|---|---|493| Core unit tests | `swift test` | 130 tests in 21 suites + 5 in the sync-migration suite — passed |494| Integration against the VQuant Next test backend (5058, never production): passkey ceremonies with a software authenticator, market data, quant jobs, Quant Lab, Studio, research workspace | `Scripts/integration-test.sh` | 130 tests in 21 suites passed; the real-analysis test skipped (model calls) |495| UI tests (8 classes, run serially) | `VQ_UI_ONLY=<Class> Scripts/ui-test.sh` | 28 tests: 23 passed, 2 failed, 3 skipped — the failures are XCUITest clicks not delivered on two custom controls; the same paths work with real pointer events |496| Real pointer and key events | `cliclick` + System Events, `Scripts/restore-check.sh` | drag-reorder, chart drawing, ticker drop, routing clicks, review sheet, window restoration after a real quit |497| Signed bundle | `Scripts/verify-release.sh` | 13 checks passed |498| Headers | `Scripts/check-headers.sh` | ok |499500Fixtures in `Tests/CoreTests/Fixtures` are responses recorded from the test copies; mocks (`MockTransport`,501`SoftwareAuthenticator`) exist only in the test target. Model calls made for 2.0.0: one fast analysis ($0.0034) and502one research study ($0.318), both on the test backend.503504Measured: the chart renderer (10 000 bars with all indicators: 39.4 ms → 5.0 ms per frame; 100 000 bars: 444 ms →5054.4 ms; Metal not adopted — [`docs/CHART_PERFORMANCE.md`](docs/CHART_PERFORMANCE.md)); 162 MB resident for the signed506build signed in and idle for a few seconds; bundle 24 MB, universal.507508---509510## 📦 Release511512```bash513python3 Scripts/provision.py # bundle id, Associated Domains capability, Developer ID profile (idempotent)514Scripts/release.sh # Release archive signed with the existing Developer ID Application identity → dist/VQuant.app515Scripts/verify-release.sh # 13 checks on the signed bundle516Scripts/notarize.sh # notarize + staple the app, then build, sign, notarize and staple the DMG517```518519| Item | Value |520|---|---|521| Version | **2.0.0 (3)**, tag `v2.0.0` — notarized and published 2026-11-20. Previous: 1.0.1 (2), tag `v1.0.1` |522| Bundle identifier | `ai.spboucher.vquant` (App ID shared with the iOS app of the same name) |523| Signing | Developer ID Application, manual, provisioning profile "VQuant Developer ID" (Associated Domains), `--timestamp` |524| Notarization | 1.0.1: application and disk image **Accepted**, stapled and validated. 2.0.0: not submitted (owner's decision) |525| Gatekeeper | `spctl -a -vv /Applications/VQuant.app` → accepted, source=Notarized Developer ID |526| Artifact | `dist/VQuant-2.0.0.dmg` (published 2.0.0, notarized) · `dist/VQuant-1.0.1.dmg` (previous) — not tracked in git |527| Architecture | Universal (`ONLY_ACTIVE_ARCH: NO` in Release) |528529The scripts never create, print or modify credentials: they fail if no Developer ID Application identity exists,530and "notarized" is printed only when Apple answered Accepted.531532---533534## 🔑 First sign-in on a Mac535536Install `VQuant.app` in `/Applications`, open it, **Sign In with a Passkey**. A passkey created for the web app and537synced by iCloud Keychain works as is. For a Mac without one: on the server node,538`cd ~/vquant && npm run -s access:invite invite <person>`, then paste the link under *Enrol this Mac with a setup link*.539540---541542## 🩺 Troubleshooting and gotchas543544| Topic | Explanation |545|---|---|546| **Debug builds and passkeys** | The Associated Domains entitlement needs the Developer ID provisioning profile, and macOS resolves the association per application identifier: Debug builds use another bundle id (`.debug`) and cannot use system passkeys. Development and tests use a software authenticator against the backend test copy |547| **A development copy must never shadow the installed app** | Hence the distinct Debug identifier: a copy registered with Launch Services under the release id would break the passkey domain association |548| **Lists on macOS 27** | The outline-backed `List(selection:)` received the click but never selected a row (defect of 1.0.0: sidebar and inner lists did not respond). Every single-selection list uses rows that select by their own action (`SelectableRow`) |549| **Never write navigation back into a `WindowGroup(for:)` value** | It re-creates the window content. Per-window state lives in scene storage |550| **`@Environment(Model.self)`** | Traps on macOS 27 inside table cells, menus, sheets and toolbars: the environment is passed explicitly |551| **No window after a forced quit** | A launch guard reopens the main window |552| **Efficient frontier** | Drawn as points: a line through x-sorted points was wrong |553| **UI tests bundle** | Ad hoc signed with the hardened runtime off: library validation would refuse to load it |554| **Build products** | Kept in `~/Library/Developer/VQuant`, outside `~/Desktop` (TCC and Launch Services treat Desktop specially) |555| **Passkey refused on a new Mac** | Apple's CDN must serve the server's `apple-app-site-association` file listing the app id |556| **Signed out unexpectedly** | The server answered 401: the session was revoked elsewhere or unused for 90 days |557558---559560## 🧭 Known limitations and next steps561562Known gaps of 2.0.0 ([`docs/FEATURE_PARITY.md`](docs/FEATURE_PARITY.md)):563564- Keyboard arrow navigation exists in the watchlist table and the palette; other lists select on click.565- LaTeX formulas are not typeset. No dictation. No admin console (by design).566- Numbers follow the account's synced number format (fr-CA on the owner's account) in the 2.0 screens, while the567 1.x screens (Markets, the chart axis, the quote panel) keep the system format; labels are English everywhere.568- Chart rendering uses Core Graphics, not Metal — by measurement ([`docs/CHART_PERFORMANCE.md`](docs/CHART_PERFORMANCE.md)).569- Instruments profiling was not run.570571Not verified — the complete list is in [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md). The main ones: every Touch ID572ceremony (sign-in on the signed build, enrolment, app lock, reauth-gated revocation from the Settings pane — the API573is tested with a software authenticator); a research approval answered from the Mac; a review started from the Mac;574the migration on a Mac that really holds 1.x watchlists; the real menu-bar item; a delivered system notification;575offline with the network physically off; deep and ultra modes, Stop and mid-stream join on backend 6; Intel Macs and576macOS 14–26; VoiceOver.577578What would come next:5795801. Notarize and publish 2.0.0 once the owner has tried the signed build against production backend 6.5812. Keyboard navigation in every list; one number format across 1.x and 2.0 screens.5823. LaTeX rendering; dictation once the server has a speech key.5834. Instruments passes (Time Profiler on chart interaction, Allocations on long research sessions) and an automatic584 update channel.585586---587588## 📚 Documentation589590| Document | Content |591|---|---|592| [`docs/MACOS_ARCHITECTURE.md`](docs/MACOS_ARCHITECTURE.md) | 2.0 in one page, layers (core, kit, app), sync, research, windows, charting, freshness, offline |593| [`docs/CHART_PERFORMANCE.md`](docs/CHART_PERFORMANCE.md) | Frame-time measurements of the chart renderer and the Metal decision |594| [`docs/FEATURE_PARITY.md`](docs/FEATURE_PARITY.md) | Every web feature and native addition, with its evidence; what the brief asked for that does not exist |595| [`docs/API_INVENTORY.md`](docs/API_INVENTORY.md) | Every route the client calls, verified in the backend source |596| [`docs/AUTHENTICATION.md`](docs/AUTHENTICATION.md) | Passkeys, device sessions, Touch ID lock |597| [`docs/MIGRATION_PLAN.md`](docs/MIGRATION_PLAN.md) | Phases, backend changes, next steps |598| [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md) | What was tested, measured, fixed, and what was not verified |599600---601602## 👤 Author603604<div align="center">605<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>606607**Simon-Pierre Boucher** — design, development, operations<br>608[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai609610</div>611612---613614## 📄 License615616All rights reserved © 2026 Simon-Pierre Boucher. Private software.617