True Build OS runs a working interior design studio end-to-end: how information comes in from the field, how it becomes structured records, how work gets routed, and how decisions get made and logged.

• Everything here is built and in production — every claim maps to real code, not roadmap.
• It follows one path: ingest → orchestration → decisions → surfaces, then the wider ecosystem it plugs into.
• I'd genuinely value your read on it — especially different ways to think about these problems, and where it could go next.

DocumentGenerationJob takes an unstructured transcript or email and returns a single structured object that the app commits in one transaction.

• Classifies into one of 11 record types (minutes, RFI, PCN, site report, spec, defect…).
• Emits a formatted document plus the side-effects: new action items, updates to existing items by ID, and closures with a resolution.
• Also extracts structured decisions, open questions and change requests — each with a source quote for traceability.
• It learns the studio's house style — when staff approve or edit a generated document, that final version is saved. Next time the same record type is generated for that project, a few of those approved documents are pasted into the prompt as worked examples, so the output matches how this studio actually writes. No fine-tuning, no retraining.
• Advisory-lock serialized per project so two concurrent transcripts can't both mutate the same action item.

The hard part of AI editing isn't generating text — it's telling the model which part to change without it quietly rewriting everything else. The studio's answer borrows from how people already mark up documents.

• Highlight any span in a generated record and leave a comment — "too formal", "wrong supplier", "merge these two". Like Google-Docs comments, except they regenerate.
• A general-instruction box handles document-wide asks — "make the tone more formal, fix the dates".
• Each comment is scoped to its section and its exact quoted text, so the model knows precisely where you mean — no guessing from a vague prompt.

• Word-level diff (LCS) renders the result as tracked changes — insertions in green, deletions struck through. You see exactly what moved.
• Accept or reject each change, or all at once; the preview stays editable for a manual touch-up before it lands.
• Consistency propagation — rename a supplier in one comment and it's corrected in every section, not just the line you marked. This is the part that's genuinely hard to get right.
• Nothing is persisted — annotations are a transient instruction, not data. The approved version then feeds the house-style learning loop.

Six different entity types — action items, issues, approvals, decisions, open questions, attention alerts — all share a Ball-in-Court concern: a polymorphic pointer to whoever currently owns the next move, plus a snooze.

• A single query assembles one unified queue per person across all six types.
• A shared urgency score ranks them: overdue +100, severity, staleness, age-of-pending-approval, due-soon.
• The ball shifts explicitly (staff → vendor → client) and every shift is an event.

Most tools give each object type its own backlog. Here the operational question — what is waiting on me, ranked — is answered in one place regardless of object type.

One polymorphic ClientApproval serves three different approvable things — an FF&E item, a variation order, or a design record. The client never logs in: the secure token is the authentication.

• Snapshot at send time — the approvable's state is frozen into the approval. If the item later changes, the client's decision still references exactly what they saw.
• One-shot, 72-hour token, consumed under a row lock — no double-submit, no replay.
• Approval drives side-effects — an approved FF&E item advances its lifecycle stage; a record flips to approved — emitted as events.
• Signed proof captured — IP, user-agent, timestamp on the decision.

Seven entity types embed their text into pgvector on write. "Ask Arqis" runs one semantic query spanning all of them, assembles a context window, and has Claude answer with the project's own history.

• No external vector DB. Embeddings live in the same Postgres as the data — HNSW cosine index, OpenAI text-embedding-3-small.
• Graceful fallback to recency if the embeddings provider is unavailable.
• Bi-temporal queries — reconstruct "what were the live decisions as of that date", walking supersession chains. This is the part most RAG stacks don't have.

I'll be candid on the next slide about which of these is genuinely differentiated and which is just 2024 table-stakes.

The throughline

• Minimise moving parts. No Redis, no external vector service, no Node build step, no SPA. One Postgres is the queue, the cache-bus, the relational store and the vector index.
• Data sovereignty. Sensitive client and contract data — including embeddings — never leaves the app's own database.
• The cost: you trade horizontal-scale headroom and specialised tooling for operational simplicity. For a studio's data volumes, that's the right side of the trade — and an explicit one.

• Runs on the Mac Studio — Apple Silicon, always-on, on the studio's own network. The same machine that runs CI.
• Local stack: Ollama, Apple MLX, and LM Studio / llama.cpp, serving open-weight models (Llama · Qwen · Mistral-class).
• Routing weighs three things at once — difficulty (cheap, high-volume work stays local), privacy (sensitive client data never leaves the machine), and cost (local-first to dodge API spend and rate limits).
• Claude online is reserved for the hard reasoning and final-quality generation where it clearly wins.

Forge is a genuine external AI agent with live read/write access to the studio — which makes the trust boundary the interesting engineering, not the connection itself.

• Shared-secret header on every call; the bridge holds one scoped credential, not a staff login.
• Server-side project isolation — when an item is linked to an inbound message, the lookup is scoped to that message's project, so a token-holder cannot attach project A's work to project B's conversation.
• Provenance on every write — items created this way are stamped "via Forge — {sender}", so machine-origin work is always distinguishable from human-origin.
• Outbound is pull, not push — TrueOS queues replies; Forge polls. The system never has to trust an inbound socket.

We spent two months building polished portals. The most-used — and frankly most enjoyable — way to put data into the system has turned out to be none of them. It's messaging.

• Telegram, and especially Forge, became the way entries actually get made. Talking to Forge is now my number-one way of putting things into the system.
• Why it works: as an agent talking to True Build OS through its MCP, Forge understands messy, half-formed input first — cleans it, fills the gaps, structures it — before anything touches the database. It feels like handing work to a capable colleague, not filling in a form.
• The honest part: Forge is unreliable in other respects. But on the "understand first, then write" path through the MCP, it's been genuinely powerful.
• The question it opens: should the system be chat-first — chat as the primary surface, with the interface dynamically assembling the right widget to show information, or to ask for exactly what it's missing?