feat: prepare Quant Companion for private beta

README.md

@@ -1,14 +1,14 @@
 # Quant Companion
 
-The unified **Quant Alchemy** workbench — strategy performance analytics, a
+The unified **Quant Alchemy** workbench: strategy performance analytics, a
 trading journal, and position sizing with liquidation analysis, in one app.
 
 This app merges three previously separate projects:
 
-| Tool | Route | Formerly |
-| --- | --- | --- |
-| Performance Analytics | `/analytics` | quant-companion (SolidJS) |
-| Trading Journal | `/journal` | trading-journal (React + Convex) |
+| Tool                     | Route         | Formerly                               |
+| ------------------------ | ------------- | -------------------------------------- |
+| Performance Analytics    | `/analytics`  | quant-companion (SolidJS)              |
+| Trading Journal          | `/journal`    | trading-journal (React + Convex)       |
 | Position Size Calculator | `/calculator` | position-size-calculator (static HTML) |
 
 Plus a gamification layer (`/achievements`): XP, alchemy-themed ranks
@@ -23,14 +23,19 @@ disciplined trading habits.
 - Tailwind CSS v4 + shadcn/ui components
 - Plotly for charts, Papa Parse + SheetJS for CSV/XLSX import
 
+SheetJS CE is pinned to the vendor's official 0.20.3 tarball because the npm
+registry package stops at the vulnerable 0.18.5 release. See the
+[SheetJS installation guide](https://docs.sheetjs.com/docs/getting-started/installation/frameworks/).
+
 ## Development
 
 ```bash
 pnpm install
-pnpm dev              # frontend — http://localhost:3000
+pnpm dev              # frontend at http://localhost:3000
 pnpm dev:convex       # Convex backend (first run configures the deployment)
-pnpm build            # deploys Convex, then the production build (what Vercel runs)
+pnpm build            # deploys Convex only in Vercel production; UI-only elsewhere
 pnpm build:ui         # production build only, no Convex deploy
+pnpm brand:assets     # regenerate favicons, app icons, and the social card
 pnpm lint             # eslint
 pnpm test             # vitest
 pnpm generate-routes  # regenerate the route tree after adding routes
@@ -39,7 +44,7 @@ pnpm generate-routes  # regenerate the route tree after adding routes
 ## Environment
 
 Committed templates `.env.local.tpl` / `.env.production.tpl` follow the
-1Password `op://` convention — generate a real env file with:
+1Password `op://` convention. Generate a real env file with:
 
 ```bash
 pnpm run env:generate:local   # op inject -i .env.local.tpl -o .env.local
@@ -57,40 +62,40 @@ environments (`vercel env add …`).
 
 ## Convex backend
 
-`convex/` holds the trades schema and functions (Clerk-authenticated via
-`identity.subject`). To bring it up:
+`convex/` holds the trades schema and functions. Every journal operation is
+scoped by Clerk's stable `identity.tokenIdentifier`. To bring it up:
 
-1. `pnpm dev:convex` — first run creates/links the Convex deployment and
+1. `pnpm dev:convex`: first run creates or links the Convex deployment and
    generates `convex/_generated`.
 2. In the Clerk dashboard, create a JWT template named `convex`, then set
    `CLERK_JWT_ISSUER_DOMAIN` on the Convex deployment
    (see https://docs.convex.dev/auth/clerk).
 
-The journal UI currently persists to localStorage; switching its data plane to
-these Convex functions is the intended next step (see `src/lib/journal.ts`).
+The journal UI reads and writes these Convex functions through
+`ConvexProviderWithClerk`. Imports use stable source keys, so the same file can
+be imported again without duplicating a trade.
 
 ## Data & privacy
 
-Local-first: analytics uploads are processed entirely in the browser, and the
-journal + gamification progress persist in `localStorage`, namespaced per
-Clerk user id (`qc:<userId>:journal`, `qc:<userId>:progress`). The journal
-supports lossless JSON export/import for backup and migration. The only
-server-side calls are Clerk auth and the price-lookup server function
-(`src/lib/prices.ts`), which keeps API keys off the client.
+Analytics uploads are processed entirely in the browser. Journal entries sync
+to an account-scoped Convex database. Gamification progress and analytics
+header mappings remain in browser storage. The journal supports lossless JSON
+export/import for backup and migration.
 
-To move the journal to a hosted database later, replace the `load`/`persist`
-pair in `src/lib/journal.ts` and make the operations async — the operation
-semantics intentionally mirror the original Convex backend.
+Live prices and benchmark bars use authenticated server functions in
+`src/lib/prices.ts`, so provider keys never reach the client. New account access
+goes through Clerk's waitlist at `/waitlist`.
 
 ## Architecture notes
 
-- `src/lib/stats.ts`, `monteCarlo.ts`, `invalidation.ts`, `headerMappings.ts` —
+- `src/lib/stats.ts`, `monteCarlo.ts`, `invalidation.ts`, `headerMappings.ts`:
   analytics math ported from the original app (Solid signals → TanStack Store)
-- `src/lib/journal.ts` — journal store with close/split P&L math
-- `src/lib/gamification.ts` — XP, ranks, streaks, achievements
-- `src/lib/positionSize.ts` — position sizing + liquidation math
-- `src/components/Plot.tsx` — client-only, code-split Plotly wrapper
-- `src/routes/journal.tsx` — Clerk-protected via `beforeLoad` server function
+- `src/lib/journal.ts`: validated JSON/JSONL import, portable export, and stable
+  import keys
+- `src/lib/gamification.ts`: XP, ranks, streaks, achievements
+- `src/lib/positionSize.ts`: position sizing and liquidation math
+- `src/components/Plot.tsx`: client-only, code-split Plotly wrapper
+- `src/routes/journal.tsx`: Clerk-protected Convex journal UI
 
 The legacy Chrome-extension build (TradingView page scraping) was retired with
 the SolidJS app; the git history (`main` prior to this replacement) retains it.

brand/brand.json

@@ -0,0 +1,16 @@
+{
+  "name": "Quant Companion",
+  "tagline": "Turn market lead into gold, one disciplined trade at a time.",
+  "description": "Strategy analytics, a private trading journal, and position sizing in the Quant Alchemy trading workbench.",
+  "ogSubtitle": "Strategy analytics · Trading journal · Risk sizing",
+  "url": "www.quant-companion.quantalchemy.io",
+  "themeColor": "#0A0D16",
+  "background": "#0A0D16",
+  "ink": "#E9ECF8",
+  "ink2": "#A7AECB",
+  "ink3": "#707897",
+  "fonts": {
+    "display": "brand/fonts/Fraunces-Italic.ttf",
+    "body": "brand/fonts/InstrumentSans.ttf"
+  }
+}

brand/fonts/LICENSE-Fraunces.txt

@@ -0,0 +1,93 @@
+Copyright 2018 The Fraunces Project Authors (https://github.com/undercasetype/Fraunces)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

brand/fonts/LICENSE-Instrument-Sans.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Instrument Sans Project Authors (https://github.com/Instrument/instrument-sans)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

convex/schema.ts

@@ -1,11 +1,16 @@
+import { authTables } from '@convex-dev/auth/server'
 import { defineSchema, defineTable } from 'convex/server'
 import { v } from 'convex/values'
 
-// Mirrors src/lib/journal.ts JournalTrade. userId is the Clerk user id
-// (identity.subject) — Clerk owns user records, so there is no users table.
+// Mirrors src/lib/journal.ts JournalTrade. userId is Clerk's stable
+// identity.tokenIdentifier, so every query stays scoped to one auth identity.
 export default defineSchema({
+  // Preserve the legacy Convex Auth tables during the Clerk transition. They
+  // are no longer used for new sessions, but their records remain intact.
+  ...authTables,
   trades: defineTable({
     userId: v.string(),
+    sourceId: v.optional(v.string()),
     assetName: v.string(),
     assetType: v.union(v.literal('crypto'), v.literal('traditional')),
     quantity: v.number(),
@@ -22,5 +27,7 @@ export default defineSchema({
     comments: v.optional(v.string()),
   })
     .index('by_userId', ['userId'])
-    .index('by_userId_and_status', ['userId', 'status']),
+    .index('by_userId_and_assetName', ['userId', 'assetName'])
+    .index('by_userId_and_status', ['userId', 'status'])
+    .index('by_userId_and_sourceId', ['userId', 'sourceId']),
 })