Transition handbook

Everything I worked on for Sahara and where it lives, written for Jane and Frank. The first table is the map. Each section after it covers one project: what it is, what shipped, what is still open and where to find it.

Where everything is

Every project with its code, where it runs and where the design lives. The sections below have the detail.

Sorin webapp

The webapp is the companion surface: acquisition, chat, sharing and referral. Code lives in defi-agent-h5, the dev build is dev.usesorin.ai, and the team's GitHub Actions deploy it to Aliyun (dev, pre, prod). Everything is merged except #2325, the sidebar hierarchy, which was closed unmerged. Its branch is still on the repo if the team wants it.

What I shipped

Where things are in the code

• Design tokens: src/app/variables-new.scss holds the dark root block, color-new.json feeds Tailwind. Tailwind class names double the prefix on purpose, so a background class reads bg-bg-primary-bg-prim-110.
• Buttons: src/components/ui/button.tsx is the one button component. Every CTA goes through it.
• Page titles: the usePageTitle hook sets the title, and the desktop header in app-shell.tsx renders it. Mobile has no title yet.
• Empty chat: empty-chat.tsx owns the entrance timeline. greeting-prompts.ts is parked on purpose, do not delete it.
• Sidebar: side-menu-row.tsx is the shared row. The new signals count is tracked client side because the backend unread endpoint drains itself every poll.
• Chat responses: everything sits under src/components/page-specific/chat/chat-content/response-message/.
• The rules themselves: docs/DESIGN-RULES.md. The Design system section below has the short version.

Working on it

Yarn 4 through corepack and Node 20, yarn dev runs on localhost:3000. Run the test suite with the dev server stopped, two tests use wall clock timing and fail under load. Branch from main, push to the repo (no fork), and request Jiangzhe12 as reviewer, he reviewed all my PRs.

Sorin desktop app

The desktop app is the product anchor: the Tauri terminal in sorin-app. I ran three design passes on it. Three PRs merged. #293 and #298 have been open since June with no review, and both now conflict with main. The Figma source is the Chat Desktop App frame in Sorin Dev.

What I shipped

Where things are in the code

• Shell and sidebar: src/app/components/Sidebar.tsx, WindowTitlebar.tsx, src/app/shell/AppShell.tsx.
• Composer and the explore pills: src/app/views/NewTaskStage/components/.
• Paper trading: src/app/views/PaperTradingCampaign/ and the banner under PortfolioDashboardStage/components/.
• Connectors and signals: src/app/views/EventConnectorStage/, button classes in src/app/ui/styles.ts.
• Surface tokens: src/styles.css defines --surface-110 down to --surface-80. Use those, never raw hex, or the light theme breaks.
• The Event Monitor sub app in src/event-monitor/ was left alone on purpose. Its uppercase labels and green live indicator are the intended newsroom look.

Working on it

pnpm. The pnpm-workspace.yaml file is not tracked in the repo, so after a fresh clone recreate it with the allowBuilds entries set to true or nothing boots. pnpm dev on localhost:1420 is enough for UI work, pnpm tauri:dev runs the full app. Type check with node_modules/.bin/tsc --noEmit. One lesson from this repo: edit the existing components in place. Parallel rewrites of the sidebar and chat stage were tried and reverted.

Sorin Market Lens Chrome extension

Market Lens is the Chrome side panel that flags price moves on Polymarket and Kalshi and explains them. Code is in sorin-polymarket. The team owns the runtime. My part was the Sorin design tokens and the first side panel pass, and only the tokens made it to main.

How it is built

Three layers, written up in docs/R1_extension_backend_worker_architecture.md in the repo. The extension only reads cached moves. A cache only API serves them. A worker does the discovery, refresh, ranking and Codex attribution and stores everything in SQLite. The backend runs on an emergency GCP VM at 136-116-239-244.sslip.io, runbook in docs/operations/. There is no real production host, auth or store build yet.

What I did

What did not land

The visual pass from #2 lives only on the branch carlos/sidepanel-design-pass: a type scale of 11, 12, 14, 16 and 20px, radii of 8, 12 and 16, spacing tokens, Satoshi with tabular numbers everywhere, max weight 500, the colored price move chip, rounded mover rows and symmetric padding. If you want it, rebase just the CSS and visual bits onto main. The side panel plumbing conflicts are moot, theirs won.

Where things are

Tokens in src/index.css, the panel UI in src/panel/polymarketLens.tsx, the panel shell in src/extension/PanelApp.tsx. Yarn 4. yarn dev serves the demo wall, yarn extension:build writes dist/, which you load unpacked at chrome://extensions.

Design system

One system across the three Sorin surfaces: Satoshi, green on black, dark first, calm type. The full rules are in docs/DESIGN-RULES.md in the webapp repo, written so Codex and Cursor follow them when the dev team builds prototypes. This is the short version.

The palette, shared by the webapp and the desktop app

The webapp tokens were checked against the team's Semantic Tokens Figma file on 2026-05-20 with zero drift. Tailwind class names in the webapp double the prefix, so a background class reads bg-bg-primary-bg-prim-110.

The rules

1. No font weight above 500. Headings are 400, buttons are 500, numbers may be 500.
2. Apple style title case on titles, modal headers, button labels, nav items and tabs. Body copy, descriptions and placeholders stay sentence case.
3. Green only for strong CTAs and real status (live, healthy, connected). Never on selected tabs, chips, taglines or decorative icons.
4. Every CTA is filled, one radius (8px), with explicit hover and active states. No outlined buttons, no borders on buttons.
5. Radii nest outer to inner: popover 16, inner panel 12, triggers 8. On desktop: nav items 8, toolbar dropdowns 12, sidebar panel 18, modal 24.
6. Semantic tokens only, never raw hex. Raw hex is what broke the desktop light theme.
7. Page titles live in the navbar, not in page bodies.
8. Spacing on an 8pt grid.

Where the system lives

• Webapp: docs/DESIGN-RULES.md, the ten non negotiables in AGENTS.md, tokens in src/app/variables-new.scss and color-new.json.
• Desktop: the body of PR #236 and the surface tokens in src/styles.css.
• Chrome extension: src/index.css.
• Figma: Sorin Dev, with the Chat Desktop App frame as the desktop reference.

Analytics and growth

The numbers live in PostHog and the custom dashboard is the clean view of them. Use the bot filtered dashboards, the raw ones overstate everything by about half.

PostHog

Instance posthog-prod.heysorin.ai, project Sorin Beta. Access is by PostHog login, the API key I used is not in this doc.

Custom dashboard

Repo sorin_custom_dashboard, published on GitHub Pages at fluffy-carnival-2qy6ekq.pages.github.io for org members. Four sections: upper funnel, retention, engagement, acquisition quality. Plain HTML and Chart.js, no build step. data.js is the snapshot the page reads. GitHub Actions refresh it: hourly from PostHog (update-data.yml), daily bounded retention and daily credits from MaxCompute. A small Cloudflare Worker, sorin-dashboard-refresh, lets a viewer trigger the hourly workflow without seeing the PostHog key. The keys are repo secrets. docs/adding-maxcompute-source.md explains how a MaxCompute source was added.

What the data said (April to May 2026)

• Bots: about 55% of raw signups were fake (referral farming) in April, about 44% by May. Always filter.
• Referral is the engine. 58% of signups came through referral codes. Organic referral converted at 72%, paid referral at 83%, everything else under 15%.
• Google Ads converted at about 2%, which is normal for crypto, and 90% of those signups sent a message. Cost per lead and keyword match types were never pulled. That is the open question there.
• UTM tracking is broken in known ways: Twitter split across four source values, a browser user agent used as a source, utm_medium missing almost everywhere, over a thousand email events with no campaign. The Upper Funnel dashboard was filtering on the HTTP referrer instead of utm_source. The corrected queries are in the weekly report listed under Files and documents.
• Product usage: Portfolio is used six times more than the next feature. Intent Trading was dead at 5 views in 14 days and was cut from the plan. Investment DNA quiz completions collapsed from 88 a day to zero in April.
• Desktop users burn about 8 times the credits per session of web users and account for a third of credit usage.

The three surface plan

Desktop is the product anchor, the webapp is the companion (acquisition, chat, sharing, referral, descope rather than expand) and the Chrome extension is the greenfield bet. The plan with its data backing, the deck content and the weekly funnel report are markdown files listed under Files and documents. The forced actions were: cut Intent Trading, run a two week sharing promo experiment before anchoring the story on sharing, and instrument four gaps (wallet events, connector usage, desktop install funnel, asset class tag).

Chat response redesign

Sorin's chat answers read like AI slop: conversational openers, hedging, random bold. In May I scouted Minara, the closest competitor, measured their response anatomy and shipped the frontend half of the fix. The backend half is still owed by the chat service team.

The five changes

1. Strip the AI slop phrases from the system prompt and use editorial labels instead (Position, Risk, Summary).
2. Editorial header pills: how long it took and how many tools ran.
3. Bold only data points, never whole sentences.
4. Follow up chips that mix research and action, so a chat is not a dead end.
5. Match the length of the answer to the question. A two line question gets a short answer with no headings.

Frontend, shipped

#1893 in the webapp, merged 2026-05-27. A tools count pill next to the completed pill, the whole header hidden on trivial answers, and the suggestion chips already accept a type of research or action with an icon on action chips. Everything activates the moment the backend sends the field.

Backend, not shipped

It lives in the chat service repo, which was never mine. Four bundles of work: the phrase list to suppress, the bold rule, the follow up endpoint returning two research and two action chips with an action and params payload, and the short answer mode. The handoff doc has the exact phrases, the chip JSON schema, the brevity triggers and five test cases. It is listed under Files and documents, together with the Minara analysis and the screenshots.

What Minara does that Sorin does not

They show every tool call before the answer, give each tool its own output card, write the answer as a table plus bullets with linked sources, and end with chips like Buy 100 USD of BTC or Create a workflow to alert me. Their model list also exposes a fast model paired with a strong one, which is the composed routing Sorin runs invisibly in Auto mode.

CreatorLabs

CreatorLabs is the creator product. I owned the marketing site at creator-labs.ai from July to October (38 PRs, 34 merged), restyled the wizard app once, and produced the UGC ad videos. Everything on the site is live and verified as of 2026-10-06.

The site

Repo creatorlabs-landing, static HTML on Cloudflare Pages. A push to main is a production deploy, so always branch, open a PR and get a review. Repo admins are rich4here (Guang), lphuang0x00 and gugugugugujzheng. I have maintain, not admin.

How the site is built, the short version:

• Edit tools/pages/<slug>.html and tools/pages-legal/, never src/*.html. Then run, in order, build-pages.py, build-legal.py, build-structured-data.py, build-agent-files.py. Since #62 the generators reproduce src exactly, so a rebuild is safe.
• styles.css and script.js carry a ?v= cache token. The deploy workflow fails if either file changes without the token moving. Anything under /assets/ is cached for a year, so a changed asset needs a new filename, never the same path.
• The copy comes from the Website Copy Deck Google Doc, six tabs, one per page.
• The visual source is the CreatorLabs Figma: page CreatorAI V4 holds the v4 design and a capture of all six built pages, page App Flow holds the wizard screens, and the Motion agency page is a different product.
• The CCBill checklist is the CCBill Action Item CheckList sheet. The Web rows are done on the site. What CCBill actually reviewed was the old Vercel onboarding page, which I never had access to.
• Partners: Motion, Unruly and Behave link out. Wildroom, Alter and Unbound are unlinked because nobody gave me their URLs.
• The demo form posts to Formspark, the chat widget is LeadConnector. The chat consent text still says Agora AI Technologies Inc. in the LeadConnector dashboard and should say Here AI Technologies Americas Inc.
• Branch previews do not exist. The workflow for them is #21, open since July because my token lacks the workflow scope. My previews ran on my personal Cloudflare account and will go away.

The wizard app

creator-lab-webapp, live at app.creator-labs.ai. #152, merged 2026-07-10, restyled all 16 screens to brand kit v3 and added a demo mode (pnpm demo, any credentials work) for previews without a staging account. Branch carlos/signup-page turns the odd /onboarding/password step into a proper /signup page that matches the login card. It is pushed, has no PR, and the team asked to review before one is opened. Still open in the app: the signup Terms text names Creator Labs AI LLC and support@creator-labs.ai, and the in app 2257 notice waits on legal's custodian details.

UGC videos

Short vertical ads for outreach, first with generated creators, then real models, then clones of real models with their permission. Finals are in the Drive folder UGC Videos - CreatorLabs and in the Higgsfield team folder CreatorLabs UGC ads (finals). Every prompt, script and build script is in my local creatorlabs-ugc folder, listed under Files and documents, with PROMPTS.md and SHOOT-SCRIPT-real-model.md as the two files to read first. A spoken script alone does not reproduce these, the prompt is six parts and the script is one of them.

SEO handover docs

A five engine SEO playbook and a 29 page Article Writing Guide (PDF and DOCX) with a 40 article keyword bank. Both are local files right now, listed under Files and documents.

Motion

Motion is a creator agency with its own site at agency-motion.com. It is a separate product from CreatorLabs, never overwrite one with the other. V4 has been live since 2026-08-19 and nothing is pending.

What shipped

Where things are

• Repo motion-landing-page, site files at the repo root, images and video in Git LFS. tools/stage.sh builds dist/ from an allowlist so the README and notes are never uploaded.
• Shipping is a merge to main. The workflow deploys to the agency-motion Cloudflare Pages project. Its post deploy check hits the deployment URL, not the custom domain, so look at agency-motion.com yourself after a deploy.
• Design source: frame 1295:3545, "motion-landing, site build V4", on the Motion agency page of the CreatorLabs Figma.
• The hero video encodes are reproducible from a script in my local Motion folder, listed under Files and documents, with the reasoning for the flip, the loop crossfade and the 1440p choice inline.

Open, all decisions rather than bugs

• V4 dropped the four card roster section and the marquee, with four named creators whose figures are real. The nav still has a Roster item that anchors to the portrait section.
• PLACEHOLDER-FIGURES.md in the repo still says every number and person is invented. They are real. It is never served, but it will mislead the next reader.
• The apply form has no endpoint, the footer social and legal links go nowhere, and fonts load from Google rather than self hosted.
• The CreatorLabs partner band links to Motion. Motion has no link back.

Before April 2026

The sections above cover April to October 2026, when the design work moved into code. The earlier work, from the Sorin UX phases through the Sahara 2.0 rebrand, lives in Drive, Figma and Notion. These are the entry points, all linked under Files and documents.

• Sorin UX phases 1 to 4, mobile and PC: the UX/UI Roadmap doc (rules, chat experience by module, priorities) and the UX/UI Tracker doc (sprint by sprint, late 2025). The Agent Interaction Patterns doc explains how the chat shows thinking, tool calls and sub agents.
• Investment DNA: the reviewed trader personas and the quiz questions behind them.
• Sahara 2.0 rebrand: the Branding folder with the brand kit, guidelines, logos, fonts, templates, signatures and the Brand Guide 2026 PDF.
• Sahara 2.0 website: designed in the Web-Related Figma, handed to an outside Framer developer through the external Figma file, built in the Framer project, eight pages in light and dark.
• Sorin launch 2026: launch video, logo and icon, social posts and profiles in the shared folder.
• Video: the Sahara token video, the KBW booth loop, the DeFi Copilot video with its vendor brief and vendor sheet.
• Decks: the Sahara AI overview, the partner deck, the exchange partnership deck and the two templates.
• Deliverables were tracked on the Sorin Deliverables page in Notion.

Accounts and access

Everything I touched is reachable from accounts the company controls. Nothing in production depends on an account of mine. The one thing to do before my accounts close is move the ownership of my Drive files, listed in the next section.

Files and documents

Everything that is not code is either in my Drive or on my Mac. The Drive files stay if someone takes ownership before my account closes. The local files stay with me. Ask if you need one.

In my Drive (carlosl@saharalabs.ai)

On my Mac