LUCA OS — User Manual

Last trued: 2026-06-11 (Day-134) · Tracker stamp: ROADMAP TABLE v3 · 2026-06-10 · serials 1-63 · ✅19 🔵2 ⬜42 🅿️1 Live state source of truth: docs/handoff/LUCA_MASTER_TRACKER.md §R.2 — when this manual disagrees with R.2, R.2 wins. Re-true this file when the stamp bumps. Audience: the people using LUCA today — the creator first, beta-invitees on app.lucaos.app next. Mirror tier: TWIN_OWNER (writes about what the owner of a twin sees and does).

PAST — what LUCA was, briefly

LUCA OS spent its first 130 days building organs: memory, recall, the ingest river, persona prose, the trust/draft gate, federation, governance. A lot was built dark — code merged but flag-OFF in prod. What you used between Day-77 (GCP move) and Day-132 was a chat surface with a brain that had not been switched on. Day-133 (Sitting-2 attended evening) flipped the four core flags one at a time, found five reasons the brain stayed dark even after flipping (mode-gap inheritance, the 80K prompt cliff, self-poisoning recall, two legacy band-aids), shipped seven small fixes, and the memory promise went live on the bots. This manual describes the product as it stands the morning after.

PRESENT — what LUCA is, today (Day-134)

The product, in one sentence: a Telegram twin that remembers what you teach it and answers from that memory the next time you ask — at paise per answer on the cheapest model tier.

1. Where the product runs

2. The memory promise (this is the headline feature)

Teach the twin something in normal English. Ask about it later — even days later, even with a different phrasing. The twin answers from what you taught, not from a generic LLM hallucination.

Example, creator-verified Day-133 evening on Telegram:

Cost per memory answer: paise. Tier: haiku by design. This is not a tier ceiling that goes up later — basic memory is supposed to be cheap, forever.

3. The three human rules the fast-path uses

The memory path makes three judgements that any human would make without thinking. They are in code, not magic, but you should know they exist:

1. Generic-token guard. If you teach “the gym trainer’s number is …” and later “the math trainer’s number is …”, asking “trainer’s number?” will NOT merge them into one wrong answer. “Trainer” alone is too generic; the twin asks which one.
2. Finance family. “bill” and “fee” and “due payment” belong to the same family for memory purposes — asking “what bills do I have?” surfaces school fees too.
3. 120-second conversational adjacency. A pronoun like “his number” arriving within ~2 minutes of “vamsi’s number” sticks to vamsi, not to whoever else was mentioned five minutes ago.

If a memory answer ever looks wrong, the explanation is almost always one of these three rules firing or failing — and the fix is to re-teach in a re-worded sentence, because the gateway dedups exact repeats (see §6 “what to know”).

4. What the twin does NOT do yet (be precise about this)

A lot of the Living-Twin wave is built but not turned on in prod. The code is in the repo, the flag is default-OFF in deploy/docker-compose.full.yml, and the prod .env does not flip it. Today, the twin will not:

Rule of thumb: if you see it described in a SESSION_HANDOFF_* doc as “shipped” but you do not see it in the Sitting-2 LIVE table below, it is dark-built, not available. Ask the creator before promising it to anyone.

5. What IS live in prod (the only honest table)

This table is the load-bearing one. It must match SITTING2_COMPLETE §1. If the bots get re-deployed with different flags, this row needs to be updated the same session.

6. Things you should know before you teach the twin a lot

• Re-teaches need re-wording. The gateway dedups exact repeat sentences across days (“duplicate already processed”). If you taught a fact yesterday and want to correct it, re-phrase the new sentence — don’t paste the old one with one word changed at the end.
• Memory is per-twin. Your Mahesh Twin’s memory does not bleed into anybody else’s twin. Latusha’s twin, Nannu’s twin, Omshi’s twin — each has its own spine. This is enforced at the store layer (LUCA_TWIN_SPINE=1).
• You can teach in normal English. No special syntax. The ingest river is trained to spot facts in declarative sentences. Questions are filtered out before they reach the store (Sitting-2 fix — questions used to outrank facts in recall).
• The twin is not a chat companion. It is a memory + judgement engine that speaks through chat. It will not invent emotions, opinions, or events you did not teach it.
• Premium model upgrades are not the fix for “the twin forgot.” Architecture is. If a memory answer looks wrong, the right diagnosis is which of the three human rules failed, not “switch to Sonnet/Opus.” Premium tiers exist for the creative/long-form path, not for basic recall.

7. The dashboard at app.lucaos.app

After you accept an invite (see §8) you land in the web dashboard. What’s there today:

API endpoints are documented at docs/05-API-REFERENCE.md and the live auto-generated OpenAPI at https://api.lucaos.app/docs.

8. Onboarding — how you actually get in

LUCA is invite-gated. There is no public sign-up form. The path:

1. An organisation admin issues you an invite from the admin console (CQ-4). You receive a tokenised link app.lucaos.app/invite/<token>.
2. You open the link. The page calls GET /invite/<token> and shows you who invited you, which org you’d be joining, and how long the invite is valid.
3. You confirm. POST /invite/<token> either resolves your email to an existing personal LUID or mints a fresh one (rule: one LUID per email, no matter how many tenants you join). You’re attached as a member of the org, and a session JWT is returned.
4. You land in the dashboard.

Same email, different tenant invite → same personal LUID, same personal twin, with a second org membership attached. Your personal twin is created first; org memberships layer on top. This is enforced by tests test_public_invite_route.py (15/15 GREEN).

Note on activation: the public invite-acceptance route is default-OFF in prod (LUCA_PUBLIC_INVITE_ACCEPTANCE=0). Until the creator flips it in an attended window, invite acceptance happens through the admin console flow directly. Day-134 status: shipped, awaiting the activation window.

9. Pricing — what you pay

From docs/billing/BILLING_MODEL_V1.md (“Model C · Hybrid: LUCA pays inside the tier; user adds own keys above the tier”):

• GST: 18% (CGST+SGST for Hyderabad / Telangana, IGST for other states). Invoices generated by bridge/billing/subscription/invoice_generator.py.
• Razorpay subscription flips the tier on subscription.charged webhook. Payment failure → 3-day grace → on overrun the twin downgrades to Free (data preserved, quota tightens) — never deleted.
• BYOK overlay. At ≥ 80% of any tier quota, the chat UI surfaces a modal: paste your own Anthropic / OpenAI / Composio key and that provider’s quota check disables for your twin (your other providers still count against the tier).
• Free-tier phone verification: Personal tier requires a +91 SIM (Indian SIM only at launch).

10. Where things live (filesystem map, brief)

FUTURE — what’s next for you as a user

The Living-Twin wave (10 evidence-carrying SMs, all shipped Day-133 except where noted) is what moves the twin from “remembers” to “judges.” Once the creator attended-flips them in order:

• Detect-and-ask on conflicts. Two phone numbers for the same person? The twin asks which is current and supersedes the loser bitemporally.
• Draft-and-wait on mutations. Any chat that would write to CRM / Invoicing / Reminders drafts first, waits for your YES, then executes. Payments remain never-auto, even after this flips.
• Server-side contradiction sweep. A daemon judges contradictions where the memories live (the VM), not on the creator’s Mac. Telegram alerts when the queue grows.
• Async post-process. MAGMA / Ambient / Predictive-Query runs after the reply, so the brain gets smarter without making the reply slower.
• Prompt diet. The 67K-char creator-context photocopy currently sent on every message becomes a small identity-core + a query-aware dynamic slice. Faster replies, cheaper, better cache hits.
• Real semantic embeddings. Today the prod semantic engine falls back to TF-IDF because the embedding sidecar is default-OFF. Activation = “fee ≈ bill” works for every synonym, not just the ones the finance-family rule names.

After that comes G4: a real-user twin born from lucaos.app that reads its owner’s world (Gmail / WhatsApp / Drive via Composio). That’s still creator-gated.

Reference: when something doesn’t behave the way this manual says

1. Check the live flag table (§5). A prod redeploy may have flipped something. The truth is in deploy/.env on the VM, the doctrine is &luca-env in deploy/docker-compose.full.yml.
2. Check the tracker stamp. If LUCA_MASTER_TRACKER.md §R.2 has bumped past v3 · serials 1-63, this manual is stale — re-true it.
3. Look at the SESSION_HANDOFF for that day. The most recent handoff in docs/handoff/ is the honest state for everything not yet folded back into this manual.

LUCA OS — LUCAVERSE. Uma Mahesh Rajanala, Founder & CEO. Birth of Luca: 2026-01-28.