AI OS Platform — Onboarding for Nishil & Yashes

Welcome — what you’re building

Hey Nishil, hey Yashes — welcome aboard.

You’re joining a portfolio of projects that share one thesis: every company is about to be redesigned around AI, and the ones that build their own AI operating system will own the upside instead of renting it. Each “OS” you’ll see in this doc is one instantiation of that thesis — for a specific company, vertical, or product.

This doc is your map. It covers four things:

1. The Big Idea — the methodology and language we use. You’ll hear these terms in every meeting and code comment. Internalize them.
2. The platform model — what an OS actually is, mechanically: agents, brain, channels, workspaces, the closed-loop tuning surface.
3. Masterkey + the OS portfolio — what each project is, who it’s for, where it stands.
4. How we work — the rituals and conventions that keep parallel OS builds from colliding.

Read it once end-to-end. Bookmark it. Ping me on anything that’s unclear — gaps in this doc are bugs.

Part 1 — The Big Idea

The AI Org Chart

Every company has an org chart on paper. The real org chart is messier — who actually owns what decision, where the bottlenecks live, where work falls on the floor. The AI Org Chart is the parallel digital structure that mirrors the human one, with an explicit intelligence layer designed on top of each role.

You’re not building a SaaS product that bolts onto a company. You’re architecting that company’s intelligence layer deliberately, by design and not by default.

AAA — Automation → Augmentation → Autonomy

Three layers, always sequenced in this order:

• Automation (The Hands) — fully offload repetitive, rules-based work. Invoice processing, data routing, scheduling. Once built, runs 24/7 at near-zero marginal cost.
• Augmentation (The Suit) — make existing humans 2-3× more effective. A salesperson gets AI-prepped research and draft emails before every call. A finance analyst gets anomaly flags pre-computed. Humans stay; their throughput multiplies.
• Autonomy (The Brain) — an agent owns a function end-to-end. Tier-1 support, lead scoring, expense categorization. No human in the loop for the steady state; humans get exceptions.

The order matters. Hands first builds credibility (and removes existing risk). Suit second buys you talent leverage. Brain last scales without proportional hiring. Skip the order and you burn trust.

No-Go Zones

Places AI should not go, regardless of how capable the model gets:

• Relationships where trust is the product (CEO-to-client, partnership negotiations, condolences)
• Irreversible strategic decisions (firing, acquisitions, market exits)
• Situations requiring physical presence or personal accountability
• Moments demanding genuine empathy — the book calls fake AI empathy “artificial intimacy,” and customers notice

Every OS we design must identify the company’s No-Go Zones first, before any automation planning. This is non-negotiable. If you ever feel a feature is creeping into a No-Go Zone, flag it.

DERISK → UNCLOG → SCALE

The 90-day deployment sequence we use with every customer:

• DERISK (Days 1-30) — find where human error costs the most (compliance gaps, data hygiene, security). Eliminate existing risk with AI before chasing growth. This is how you earn the right to do more.
• UNCLOG (Days 30-60) — find the bottlenecks where talented people are stuck doing busywork. Augment them. Give back time. Redirect to high-leverage work.
• SCALE (Days 60-90+) — now deploy autonomous agents and new capabilities. Grow without proportional headcount.

When you’re designing a feature, ask: “Is this DERISK, UNCLOG, or SCALE?” Features land better when they match where the customer is in the sequence.

Own, Don’t Rent

The strategic core. Two companies, same revenue, same margins today.

• Company A rents intelligence — pays $400K/month for people. Intelligence walks out the door every Friday. To grow, hires more people. Costs scale linearly.
• Company B owns intelligence — invested $40K once to build an agent. Breaks even at month four. After that, the agent sits on the balance sheet as an asset. Margins widen as revenue grows.

The OS we build for each customer is the owned-intelligence asset. The market knows the difference — Company B gets a multiple premium on identical revenue.

The Empty Chair

The positions you never need to fill. If your customer is growing 30% YoY, the old playbook says hire 30% more people. With an AI Org Chart designed well, hire 10% — agents cover the gap. Each unfilled position is an Empty Chair: invisible value, real margin.

Intelligence Arbitrage

Why this whole thing exists commercially. There’s a gap between what AI can do today and what most organizations are actually doing. Agents can run prospecting, support, finance, and compliance at single-digit percent of human cost — but 95% of companies haven’t restructured because they don’t have a framework, a method, or someone to architect the transition.

Intelligence Arbitrage is exploiting that gap. The methodology (AI Org Chart + AAA + DERISK→UNCLOG→SCALE), the platform (Masterkey), and the OSs you’ll be building are all instruments for capturing the gap on behalf of customers.

This is also the bet behind the book that’s being co-authored with Tony Robbins — same thesis, same methodology, framed for the broader market.

Part 2 — What every OS actually is

The agent thesis

The OSs we build are not chat products. They are factories full of highly specialized agents that do tasks — unattended, in production, in a loop.

This is the opposite of the OpenClaw / “general AI assistant” pattern. A chat agent is broad and shallow: it can attempt anything, but it doesn’t own any single job. Our agents are narrow and deep: each one owns one workflow, runs on a schedule or an event, has scoped tools and a known evaluation surface. We aren’t trying to build one omniscient assistant — we’re trying to deploy unlimited specialists, each doing one job well.

The frame: highly capable but limited. A great agent is a deep expert at one specific workflow, not a generalist. Think “the agent that triages inbound leads every 15 minutes,” not “the agent that helps with everything.”

Why this matters: a specialist agent can be evaluated, tuned, version-controlled, and trusted. A generalist agent can’t — its surface is too big to measure, so you can’t tell when it’s degrading.

The anatomy of an agent

Every agent in every OS is composed of four configurable variables:

• Tools — what the agent can do. APIs, integrations, capabilities (send email, query CRM, write to brain, schedule meeting, post to Slack).
• Brain — what the agent knows when it runs (see brain layering below).
• Skills — codified procedures. Playbooks. “When you see X, do Y, then Z, then check W.” Skills are the agent’s runbook.
• Version control — every snapshot of (Tools × Brain × Skills × prompt × model × schedule) is versioned. Roll forward, roll back, A/B compare runs, trace any output to the exact config that produced it.

You improve an agent by tuning any one of these four variables and watching the eval score move. Wrong output? Maybe the brain is missing a fact. Maybe the skill is unclear. Maybe the wrong tool is available, or the wrong model. The variables are knobs; the journal tells you which knob to turn.

Channels — how agents reach humans

An agent is not a UI. It is a process. It reaches humans through whichever channel fits the situation:

Telegram · Slack · WhatsApp · email · SMS · in-app chat · voice · calendar invite · push notifications

The same agent can publish to multiple channels — the channel is a transport, not a behavior. The “Lead Triage” agent emails the rep on Mondays, DMs them on Slack when a hot lead comes in, and pushes a Telegram message when a deal is at risk over the weekend. One agent, three channels, one job.

The Brain — three layers concatenated on every run

Every agent run pulls context from three brains and concatenates them into the prompt:

• Agent brain — what this agent has learned. Its past corrections, its observed patterns, its preferences. Specific to this agent.
• Department brain — what everyone in this function knows. The Sales department brain is shared by every sales agent; Finance by every finance agent. Cross-agent learnings stay inside the department.
• Company brain — global org facts. The three-layer Knowledge / Context / Memory model (permanent facts, live state, organizational memory) shared across the entire OS.

At runtime: agent_brain + department_brain + company_brain → prompt (~50K char budget, prioritized).

This is how a Sales SDR agent “just knows” that Q2 is a launch quarter (company brain) and that this audience converts best on Wednesday emails (department brain) and that a human previously corrected it for being too pushy (agent brain) — every single time it runs, without anyone retelling it.

Bus agents — agents that orchestrate other agents

Not every agent does the work. Some agents route the work. We call these bus agents.

A bus agent listens to the event bus, watches what’s happening across the OS, and dispatches specialist agents when their preconditions hit. Patterns:

• A Sales Bus agent watches incoming events (form submission, calendar booked, deal moves stage). For each event it decides which specialist (Researcher, Drafter, Scheduler, Coach) to invoke.
• A Cross-Department Bus agent escalates when an event crosses functional boundaries — a customer issue that needs Sales + Support + Engineering at once.
• An Anomaly Bus agent watches for things that should have happened and didn’t (lead went cold, invoice never got sent) and re-dispatches.

Bus agents are how the OS stays coherent as the number of specialists grows. Without them you have a swarm. With them you have an orchestra.

Auto-improvement — the closed loop

Every agent run writes a journal entry: input, output, model, tokens, cost, eval score, any human correction. The journal is the gradient signal for the entire OS.

• Memory Curator (weekly cron, zero AI cost on the hot path) promotes journal insights into the relevant brain layer.
• Human corrections via remember() and know() hooks automatically update brain entries.
• A/B testing via AgentConfigVersion — try a new prompt or a new model against the previous version, compare eval scores, promote or roll back.
• Closed loop: the OS literally tunes itself over time. The more it runs, the better it gets — without anyone explicitly retraining.

This is the compounding moat. Each week of operation makes every customer’s OS smarter, in their own context, on their own data.

DejaDo — the onboarding engine

We can’t onboard a customer by interviewing them for six weeks. The onboarding engine is DejaDo: a tool that ingests the customer’s email history and infers their org from it.

DejaDo reads inbound and outbound email and identifies:

• People — who’s in the org, who reports to whom, who talks to whom
• Patterns — recurring conversations (this is a sales motion; this is a renewal cadence; this is a support escalation)
• Departments — what functions exist and what they actually do
• Pain — where the manual repetition is heaviest

Output: a proposed OS — which agents to deploy, what to seed the brain with, which playbooks to install. Self-serve target: a working OS in under an hour. Facilitated target: 5-day Strategy Workshop with the customer.

Status: designed in detail, not yet built. Critical path for the self-serve scaling story.

Agent Lab — the opportunity observer

Once the OS is running, Agent Lab keeps watching what humans in the org are doing — what they type, what they click, what they decide — and looks for patterns that should be automated next.

• Repetitive manual tasks → propose a new automation agent
• Predictable decisions → propose a new augmentation agent
• Recurring handoffs → propose a new bus agent

Agent Lab proposes; humans approve or reject; the OS deploys. The platform literally suggests its own next agents as it learns the business.

Workspaces & workflows — replace or integrate

The OS is not a chatbot bolted onto an existing stack. It is a workspace where humans and agents do work together. Each customer gets a real product surface — pages, dashboards, forms, queues, inboxes, dashboards — not just “talk to the bot.”

Our philosophy on third-party tools is binary:

• Replace where we can. Landing pages, CRM, basic content management, simple project tracking, internal comms, knowledge bases — all of these can be built natively into the OS workspace. Replacing them removes vendor cost, removes integration brittleness, and puts the data inside the brain where the agents can use it.
• Integrate where we must. Accounting (NetSuite, QuickBooks), payments (Stripe), enterprise SaaS the customer can’t displace (Salesforce in some shops, Microsoft 365 almost everywhere) — these we integrate to, not against. The OS reads and writes through adapters; the system of record stays where it is.

Default to replace. Integrate only when the customer’s reality forces it.

The extensibility thesis

The platform must support any new kind of workflow or app as a capability — and constantly absorb new agents to do work and new tooling to monitor those agents. That’s the whole game.

What this requires of the platform:

• A capability model flexible enough to add a new workflow (today a sales pipeline, tomorrow a clinical-trial intake, the day after a tax-filing flow) without forking the codebase.
• An agent runtime generic enough to host any specialist (give it tools + brain + skills + a schedule, it runs).
• Observability strong enough that as the agent count grows, we never lose track of what’s running, what’s broken, and what’s costing us money.

If we get this right, the platform doesn’t get more brittle as it grows — it gets more valuable. Every new vertical, every new customer, every new agent makes the next one cheaper to ship.

Part 3 — Masterkey and the OS portfolio

Masterkey is the factory

We hand-built four production OSs first — RRI-OS, CTOx OS, Omya OS, Momentis OS — to learn what works. Each proved patterns at real scale (real data, real users, real money). Masterkey is the factory we’re now extracting those patterns into, so we can stamp out new OSs in hours or days instead of months.

Think of it this way: the four early OSs are bespoke proofs. Masterkey is the manufacturing line. Future OSs will increasingly be configured outputs of Masterkey rather than hand-built from scratch.

Important — customer-owned code. Every custom OS we build today (RRI-OS, CTOx OS, Omya OS, Momentis OS, Intelligent Advisor) is a unique codebase owned by that customer. The customer gets the repo, the deploy, the data. We do not run shared infrastructure for them. “Own, Don’t Rent” applies to the OSs themselves: each customer owns their OS the same way they own their org chart. This is the durable trust mechanism — and the reason a future Salesforce-style acquirer can buy the platform without the customers feeling captured.

Masterkey has two SKUs (one shipping path is still aspirational)

The Cloud SKU is the eventual self-serve, multi-tenant product hosted by Masterkey itself. It doesn’t exist yet — every OS we have today is a custom-built, customer-owned codebase. Building the Cloud SKU is a future workstream; for now, everything is enterprise-pattern (per-customer repo).

Four core components

• Spec Library — the methodology made executable. Markdown + YAML declarations of capabilities (agents, skills, brain templates). Proprietary IP. Specs compile down to TypeScript / Next.js code per customer. Industry Packs are vertical-tuned bundles (MSP, Real Estate, Law, Coaching, Wealth Advisor).
• Gateway (gateway.masterkey.ai) — proprietary tollbooth. Every model call routes through it: license enforcement, usage logging, prompt firewall, smart routing (Haiku → Opus), volume discounts and caching. Net result: customers usually save money and the platform monetizes every interaction.
• Brain — three layers, shared infra:
  • Knowledge — permanent org facts (SOPs, products, team, pricing)
  • Context — temporary live state (active campaigns, current quarter, KPIs)
  • Memory — agent observations + human corrections (compounds over time) Auto-injected into every agent prompt (~50K char budget). Self-improving via remember() and know() hooks.
• Runtime (github.com/masterkey/runtime) — open-source, Apache 2.0. Agent orchestrator derived from the Botler engine. Identical execution pipeline across every OS instance: load state → compose prompt (soul + brain + context) → call LLM via Gateway → track cost → evaluate → event bus → mark complete.

Also in the stack: a Spec Compiler (specs → code), License Server (JWT, 24h validation), and a signed Registry for spec distribution.

Build state — honest snapshot

Live in the Masterkey codebase today: assessment engine, strategy report generator, OS activation pipeline, Pack install/configure/activate flow, agent execution (cron + event-driven, journals, governance), the Sales Foundation Pack, the Live Sales Coach Pack (Deepgram WebSocket coaching), 26-page app shell, ~50 Prisma models.

Not built yet — but on the roadmap:

• 🚧 The Spec Warehouse. This is the big one. Today every OS we build (RRI, CTOx, Omya, Momentis, IA) builds its features from scratch — we copy patterns by hand between codebases. The vision: a centralized Spec Warehouse where every reusable capability (agents, skills, dashboards, workflows, brain templates, integration adapters) is described as a versioned spec. When we kick off a new customer’s OS, the spec compiler reads the warehouse and generates the code into their repo, so they start with proven patterns instead of a blank file. The warehouse compounds: every new pattern we extract makes the next OS cheaper to build. This doesn’t exist yet. It’s the next foundational workstream and will be a primary focus for the new dev team.
• 🚧 Masterkey Cloud. The hosted multi-tenant SKU described above. Designed; not built.
• 🚧 DejaDo. Email-driven onboarding engine. Designed in detail; not built.
• 🚧 Agent Lab. Opportunity observer that proposes new agents. Not built.
• 🚧 Memory Curator. Weekly cron promoting journal insights to brain. Not built.
• 🚧 Master Agent Chat. Unified chat across departments. Not built.
• 🚧 Integration Hub. 22+ OAuth connectors (HubSpot, Slack, Salesforce, Calendar, etc.). Partially built per OS, not unified.
• 🚧 Spec compiler + signed registry + license server. The pipeline that turns specs into customer code. Not built.

Heads up: terminology is shifting. The current code says “Packs”; the future spec language calls them “Specs + Industry Packs.” Don’t be surprised when both terms show up. Spec format is not yet locked — actively being designed.

The OS portfolio

RRI-OS — flagship, Tony Robbins

• $180M enterprise OS for Robbins Research. 45-agent fleet across 6 departments.
• Stack: Next.js 16 + React 19, Prisma 7 + Supabase Postgres (3.3M CoreBuyers), Claude Sonnet 4, Clerk, Vercel.
• Scale: 889 TypeScript files, 113 models, 265 API routes.
• Notable: institutional brain with pgvector + version control, Skills Library (25 tools + 10 playbooks), Live Audio Coach (Deepgram), magic-link coaching client portal, dual-shell layout (backstage staff / frontstage customer), closed-loop self-improvement engine (prompt/model/schedule optimization), safety-gated outbound comms.
• RRI-OS is the most mature codebase in the portfolio — treat it as a reference architecture for patterns (agent fleet, brain, skills library, audit/governance), not as a finished product.

CTOx OS — unified marketing + sales + facilitator

• Merges three workflows into one Next.js platform at os.ctox.com.
• Stack: Next.js 16 + React 19 (Turbopack), Prisma 7 + Turso (76 models), Clerk, Claude Opus 4.6, Vercel.
• Scale: 65 Vercel crons, 7 roles, 719 Playwright tests across a 5-layer test pyramid.
• Notable: five-layer test pyramid (smoke / API contract / role-based / content / E2E flows), cron dispatch pattern (5 /api/cron/dispatch/[department] routes fan out to 65 agent routes), three-tier accounting models (Plan / FieldChange / Subscription), payment provider routing (FanBasis / Stripe / Whop), six-rule page performance framework born here.

Omya OS — HNW membership community

• Multi-tier membership platform for 100 members (Constellation, Advisory, Conscious Creator, Couple) + cohort programs (Heartland Gathering, Protocol, expeditions, retreats).
• Stack: Next.js 16 + React 19, Prisma 7 + Turso (60+ models), Clerk, Claude API, Stripe, Vercel.
• Scale: 32 cron routes, 7 roles, ~40s E2E suite.
• Notable: three-layer brain originated here (knowledge / context / memory) — ported into CTOx and now into Masterkey. Mandatory ISR caching + revalidation sweep (49 routes), multi-channel comms with allowlist gates (EMAIL_LIVE, SMS_LIVE, OUTBOUND_LIVE), mandatory Agent Framework (param schemas, versioned config snapshots, run traceability — see docs/AGENT-FRAMEWORK.md).

Momentis OS — Carson family office

• Agentic family office for ~50 investments, 7 verticals, 13K+ acres regenerative farmland. Long-horizon thesis.
• Stack: Next.js 16, Prisma 7 + Supabase, Clerk, Vercel AI SDK + Claude Sonnet 4. Dark theme.
• Scale: 27 entities, 420 investments, 5 active agents (deal-intake, due-diligence, portfolio-intelligence, report-builder, opportunity-observer), 15 agents planned.
• Notable: live Addepar sync (entity/bank/investment fuzzy matching), live snapshot for chat context, governance (budget enforcement + HumanTask queue), brain inject layer (know / context / remember).
• Blocked: NetSuite, Bill.com, Tipalti, Expensify integrations (waiting on credentials).

Intelligent Advisor — white-label OS for wealth management

• White-label AI OS for wealth management firms. Pacific Capital is customer zero. SOC2-compliant. AI client 360s, meeting prep, morning briefings, market intelligence, compliance dashboards, content generation.
• Stack: Next.js 16 + React 19, Prisma 7 + Turso (17 models, libsql driver adapter), Clerk (Microsoft + Google OAuth), Claude Opus 4.6 via Vercel AI SDK, Resend (briefings + alerts), Vercel.
• Scale: 6 scheduled agents across 5 departments (Client Services / Portfolio & Analysis / Market Intelligence / Business Operations / Content & Marketing). 4 roles (admin / advisor / analyst / viewer).
• Notable: firmId on every row for tenant isolation (the white-label primitive — same codebase, many firms), pluggable integration adapters per CRM / custodian / planning tool, Pacific Capital brand tokens (navy #1a2744, gold #c9a84c, teal #5BC6DA) abstracted via CSS variables so each firm gets its own palette.
• This is the first OS explicitly designed as a white-label template, not a single-customer bespoke. Watch how the firmId / integration-adapter pattern plays out — it’s the blueprint for multi-tenant OSs going forward.

Part 4 — How we work

Stack defaults

Unless a project says otherwise, expect:

• Next.js 16 + React 19, TypeScript, Turbopack, TailwindCSS 4
• Prisma 7 + Turso (libSQL) for new OSs; Supabase Postgres for OSs that outgrew libSQL or need pgvector (RRI, Momentis)
• Clerk for auth (Google OAuth + email/pw; Microsoft OAuth where the customer demands it, e.g. Intelligent Advisor)
• Vercel for hosting + crons. Custom production domain for any internal fetch() (see Vercel rules below).
• Playwright for E2E; 5-layer test pyramid (smoke / API / roles / content / flows) on the larger OSs.

Models — two different layers, don’t confuse them:

• Coding-time (you, while building): Claude Code with Opus 4.7 (1M context). This is what we use for everything dev — planning, code, refactors, reviews. Default to Opus; drop to Sonnet only if you’re running long-horizon background tasks and need to conserve.
• Runtime (what the OS itself calls from inside its agents): varies per OS, always via Vercel AI SDK. Current spread:
  • Opus 4.6 — CTOx OS, Intelligent Advisor (heavy reasoning, reports, advisor-grade output)
  • Sonnet 4 — RRI-OS, Momentis OS (agent fleet workhorse)
  • Haiku 4.5 — used everywhere for routing, classification, cheap pre-filtering
  • Pick per use case: Opus for advisor-facing reasoning, Sonnet for the general agent workload, Haiku for high-frequency cheap work.

The SDLC — one feature at a time, many in parallel

              ┌──────────────────────────────────────────────┐
              │              THE FEATURE LIFECYCLE            │
              └──────────────────────────────────────────────┘

  ① write plan ──▶ ② spawn worktree ──▶ ③ build + test ──▶ ④ open PR
  tasks/plan.md     git worktree add      code, prisma,       gh pr create
                    new branch            playwright

       │
       ▼
  ⑤ review ──▶ ⑥ merge to main ──▶ ⑦ deploy ──▶ ⑧ capture lesson
   code +       squash commit       vercel /     tasks/lessons.md
   behavior     `lior@cto.com`      cloudflare   (only if anything
   diff                                          went sideways)


              ┌──────────────────────────────────────────────┐
              │         MANY FEATURES IN PARALLEL            │
              └──────────────────────────────────────────────┘

              main branch ──────────────────────────────────▶
                    │                                ▲
                    ├─ worktree-1 ─ feature A ─ PR ──┤
                    ├─ worktree-2 ─ feature B ─ PR ──┤
                    └─ worktree-3 ─ feature C ─ PR ──┘
                          (each worktree is an isolated checkout;
                           agents can run in each one in parallel
                           without stepping on each other)

This is the current workflow — happy to change it if either of you have a better one. The goal is parallel-safe, reviewable, and reversible. If a tool or convention here is getting in your way, flag it and we’ll redesign.

Workflow rituals (these are non-negotiable)

1. Plan-first on anything non-trivial. 3+ steps or any architectural decision → write a plan before touching code. If the plan goes sideways mid-execution, stop and re-plan; don’t push through.
2. One feature = one plan = one worktree = one PR. When multiple features are in flight, each lives in its own git worktree with its own plan file. Agents run in parallel without colliding. Branch off main, PR back to main.
3. DB-driven, never hardcoded. If an entity is “live” — agents, products, dimensions, packs, anything the business sees — it sources from the DB. Hardcoded arrays/JSON for live entities are forbidden. Schema migrations replace them.
4. Capture lessons. After any correction from review, write the pattern to tasks/lessons.md in the relevant project. We iterate on these until the same mistake stops happening. Read the project’s lessons.md at the start of each session.
5. Verification before “done.” Never mark a task complete without proving it works. Run tests. Check logs. Diff behavior. If you can’t test a UI change, say so explicitly rather than claim success.
6. Commit author. Every commit across every Lior project uses lior@cto.com / liorwn. If git config user.email doesn’t match, fix it before committing.

Vercel + cron rules (these have bitten us, please internalize)

• Never fetch() a .vercel.app URL from inside a serverless function. Vercel Deployment Protection returns 401. Hardcode the production custom domain (e.g., os.ctox.com) for any cron dispatcher or internal route-to-route call.
• Env vars: use printf not echo. echo adds a trailing \n that breaks auth header comparisons. Always: printf 'value' | npx vercel env add KEY production.
• Always .trim() secrets (e.g., CRON_SECRET) before comparison in route handlers — HTTP normalizes whitespace, you don’t.

Page performance — the six rules

Both CTOx and Omya have done full perf sweeps. The rules:

1. Server-component auth shells — don’t wrap pages in Clerk’s client component (causes a double-auth waterfall).
2. One batched findMany not N nested selects — avoid the libSQL N+1.
3. Replace correlated _count subqueries with a single $queryRaw + GROUP BY for stats pages.
4. Watch the groupBy + _count pitfall — Prisma generates correlated queries.
5. ORDER BY DESC needs a direction-aware index, not just a column index.
6. export const dynamic = "force-dynamic" only works in server components.

DB bulk operations — what we learned the hard way

• Multi-row INSERT over individual statements (10-100× faster). Postgres param cap is 65,535 — max_rows = floor(65535 / num_columns).
• Never OFFSET for large tables. Cursor-based pagination only (WHERE id > $cursor ORDER BY id LIMIT N). OFFSET 2.8M takes 30+ seconds on libSQL.
• Resumable migrations: ID-diff pattern (cursor-read source IDs → load destination IDs → diff → fetch missing by ID → bulk insert). Used for the Turso → Supabase 3.3M-record migration.

Glossary

• AAA — Automation, Augmentation, Autonomy. The three intelligence layers, always in that order.
• AI Org Chart — parallel digital structure that mirrors a company’s human org chart with intelligence designed onto each role.
• Brain — the three-layer prompt-injection system (Knowledge / Context / Memory) auto-loaded into every agent.
• DERISK → UNCLOG → SCALE — the 90-day deployment sequence we use with customers.
• Empty Chair — a role you never need to fill because the AI Org Chart absorbs it.
• Industry Pack — a vertical-tuned spec bundle (MSP, Real Estate, Law, etc.).
• Intelligence Arbitrage — the strategic gap between AI capability and org adoption; what the OSs commercially exploit.
• No-Go Zone — a domain AI should never enter (trust relationships, irreversible decisions, physical presence, real empathy).
• OS — per-company AI operating system. Each is a bespoke instance built on shared primitives.
• Own, Don’t Rent — labor is rented intelligence (expense); code is owned intelligence (asset).
• Pack / Spec — a modular capability (e.g., Sales Foundation, Live Coach). “Pack” is the current code term; “Spec” is the future term — both will appear.
• Runtime — the open-source Apache-2.0 agent orchestrator (github.com/masterkey/runtime), Botler-derived.
• The Suit / The Hands / The Brain — colloquial names for Augmentation / Automation / Autonomy.

Closing

This is v1. There will be gaps — flag them. There will be terms used in code that don’t appear here yet — flag those too. Treat this doc as a living thing: whatever confused you in week 1 should be patched into it so the next person never hits the same wall.

Read in this order: 1. This doc (you’re doing it) 2. ~/Masterkey/CLAUDE.md + ~/Masterkey/ARCHITECTURE.md 3. The CLAUDE.md of whichever OS you’ll work on first 4. ~/rri-os/CLAUDE.md — the most mature OS codebase; useful as a reference architecture once you have context on your assigned project

We move fast. Default to shipping. Plan before code. Capture every lesson. Welcome aboard.