Build log: shipping Unseen UI to npm
How the component library behind this site went from a private workspace to two published packages, including the three things the first consumer broke.
Everything written
Journal
Every entry, read by engineering discipline or in series. Each one also sits on the map, next to the component it is about.
121 entries: all 18 series complete, 100 parts, plus standalone pieces. Weekly notes live in Notes .
Start here
Read a path in order
October 2026 5
LangGraph vs the OpenAI Agents SDK
Two ways to write the same supervisor. Compared on control flow, tracing, provider coupling, testing and what each makes hard.
Every question your AI readiness review asks was answered months ago
The last six days of a sixty-day series, and the pattern is that operability gets bought early or it does not get bought at all.
RAG production-readiness checklist
Twelve checks to pass before a retrieval system answers a real user. Tick them locally; progress stays in your browser.
What an AI gateway actually costs to run
The operational bill for one gateway in front of a dozen tool servers, including the costs nobody budgets for.
September 2026 24
Working with Claude, practices that hold up
Prompting, agents and tools, Claude Code, evaluation and safety. The habits that make Claude-based systems reliable, as a checklist you can run against your own setup.
Pattern: the outbox for agent actions
Agents that write to systems of record need the same transactional outbox that event-driven services use. This entry covers the shape and the trade-offs.
Adding a second agent does not add intelligence, it adds a contract
Six posts on multi-agent systems, and the failures were never inside an agent. They were between two of them.
Designing a Multi-Agent System for Real-World Use
How to design and run a multi-agent system in production, using the supervisor pattern, with its trade-offs and where human approval belongs.
When to bring in a compliance review
The changes that should pull legal, privacy or compliance into an AI project early, and what to have ready when you do. Not legal advice; a way to ask at the right time.
Security review checklist for an AI feature
What to check before an assistant, RAG app or agent goes in front of real users. Grouped by area, ticked off locally; progress stays in your browser.
The retrieval cache that served stale policies
A well-meaning cache in front of retrieval kept answering from last quarter's HR policy for eleven days.
Six ways to wire agents together, and the same three things break every time
The topology gets all the design attention. Ownership, termination and traceability are what decide whether it survives contact with production.
Nothing broke, and the system is still getting worse
Drift is quiet by construction. SLOs and a standing review are what make it audible.
You cannot roll back a prompt you never versioned
AI failures cross model, prompt, retrieval, tool and data boundaries. The runbook and the rollback controls have to as well.
Real users ask questions your test set never imagined
Offline evals cover the questions you thought of. Production tells you the ones you did not.
Your AI feature has unit economics whether you measured them or not
Cost and latency belong to the workflow, not the model call. Budget them before rollout, not after the invoice.
Logging the answer tells you almost nothing
A trace that links intent, prompt, retrieval, tools and output is the only thing that makes an AI failure debuggable.
Most agent controls do not actually control anything
Six days of notes on supervising autonomous systems, and the same failure shape kept turning up: the control exists, it is documented, and nothing in the running system is bound by it.
The architecture review that happens before launch, not after the incident
Quality, safety, cost, latency, resilience and operations have to be visible on one diagram, at the same time.
Show 101 older entries, back to May 2026
An approve button is not human oversight
Approvals, events and tenant boundaries are architecture. Bolt them on as UI and they become theatre.
You are already building a control plane, badly
Policy, memory, evals and rollout get rebuilt inside every feature until someone names the layer they belong to.
Most agents are workflows wearing a costume
Chatbot, workflow, agent, RAG. Pick the wrong one and you spend a quarter debugging autonomy nobody asked for.
Every model call should go through something you own
Routing, budgets, fallbacks and policy need one place to live. Scattered SDK calls give you none of them.
The hard part of building an agent is not making it act. It is making it stop.
Six days of notes on agentic systems, and not one of the fixes that actually worked lived inside the model.
A wrong answer tells you nothing about which agent was wrong
Multi-agent systems need trace timelines, trajectory evals and designed recovery, because the final output hides everything that produced it.
An agent that stops when it feels finished has no stop condition
Permissions belong to roles, budgets belong to runs, and termination has to be something a machine can check.
Every multi-agent pattern is an answer to one question: who controls the run
Supervisor, orchestrator-worker, planner-executor, pipeline and judge differ mainly in where control lives and when it returns.
Write role contracts, not agent personalities
"You are a meticulous senior researcher" is a costume. Inputs, outputs, permissions and done criteria are a contract.
August 2026 25
Most teams reaching for multiple agents do not need them
Separation of work has to buy quality, control or throughput. Usually it buys a harder debugging problem.
Production RAG does not fail loudly, and that is the whole problem
Six days of notes on operating retrieval systems after launch, where nearly every real failure arrives dressed as a good answer.
You cannot instruct a model into data protection
Minimise what enters context, watch the paths data can leave by, and keep the evidence an incident will demand.
Blast radius is a design parameter
Narrow tools, staged writes, sandboxes and a tested kill switch. Containment is built before it is needed.
Untrusted text does not get to give orders
Injection defence is layered validation and clear authority, not a better-worded system prompt.
Your agent should not be a superuser
Bind every AI action to a user, a service and a run, then scope the verb rather than only the data.
Safety is an architecture decision, not a moderation setting
Assets, actors, abuse cases, controls, owners, evidence. Six things a team can actually write down before launch.
Most RAG failures are faithful answers to bad evidence
Six posts on reranking, citations and decomposition, and the uncomfortable thing they turn out to have in common.
Launch day is when evaluation starts
Offline scores expire on contact with real users. Sampling, groundedness, drift and outcomes are the parts that keep paying.
If it runs after the deploy, it is a postmortem
Regression gates only work when they sit in the release path, with a threshold, a slice and an owner.
A judge that cannot name the failure is not a judge
Deterministic checks first, one rubric per criterion, and a calibration loop against human review.
Your golden set is a product, not a spreadsheet
Labels, edge cases, versions, an owner. Skip those and the number moves without anyone knowing why.
An eval that cannot block a release is just a report
Decide which decision the number is allowed to stop, then build the harness around that.
No model can reason about evidence your retriever never returned
Six days of retrieval notes, and not one of the failures announced itself.
You cannot run RAG on user complaints
Groundedness scores, per-claim citations and an operations dashboard are what tell you quality is drifting before your users do.
Chunk for the question, not for the token limit
Chunk size is a decision about what a complete answer looks like. Reranking, context budgets and refusal thresholds finish the job.
Test retrieval on its own or you will tune the wrong thing
Most "the model is wrong" problems are recall problems. Hybrid search, query rewriting and versioned indexes are where they get fixed.
Ingestion is a data product, not a loader script
Parsing sets your quality ceiling, failures need a destination, and the update and delete paths are the half nobody tests.
Your vector index does not know who is allowed to read it
Embeddings carry no access control lists. Ownership, permissions, freshness and lineage have to be designed before anything is indexed.
Everything that makes an AI demo impressive is a constraint you have not added yet
Six posts on the distance between a system that answers well once and a system people are willing to depend on.
One MCP server is an integration. Thirty is why you need a gateway
Notes from building an MCP gateway. The protocol standardised how agents call tools, then stayed silent about credentials, context budgets and who may call what. That silence gets expensive as the servers multiply.
The 3am agent run that nobody is watching
Scheduled agent work fails quietly by default. Traces, release gates and a runbook are what make it fail loudly.
A retried agent job is a second chance to send the same email
Retries are the first thing teams switch on and the last thing they design for.
Four kinds of agent state, and only one of them is memory
Conversation, task, artifacts and product data end up in one store. Then a deletion request arrives and applies to all of it.
Your AI system's biggest problem is probably not the model
Six days of production AI notes, and the model choice never once turned out to be the thing that broke.
July 2026 28
Your tool registry is an access control list wearing a different name
A list of tools is documentation. A registry decides who may act, as whom, and leaves proof behind.
Autonomy is a runtime decision, not a model decision
Agents get more capable by default. They only get bounded on purpose.
When MCP earns its overhead, and when a direct API is better
One question settles most of these arguments: will more than one AI application need this capability?
A clean connector does not make a reliable agent
Connector correctness and agent behaviour are separate problems. Most teams only test the first one.
Tools, resources and prompts are not interchangeable
Choosing the wrong primitive hands the model authority a person was supposed to hold.
Where your MCP server runs is a production decision
Transport looks like a technical detail during the demo. It is really a choice about ownership, reachability and trust.
What the MCP protocol actually standardises
It settles how capabilities are described and discovered. Every decision about whether to trust them is still yours.
From model demos to mission-ready AI systems
A practical map for moving from impressive AI demos to systems people can trust.
Why governance belongs in the architecture
Why governance belongs in the architecture, not in a document after launch.
Why production AI is coordinated infrastructure
Why production AI is the coordination of data, models, tools, controls, evaluation, and people.
Why observability is not optional for AI systems
Why production AI needs traces across prompts, context, retrieval, tools, costs, and decisions.
Why evaluating the model is not enough
Why evaluating agents means measuring the whole workflow users experience.
Why retrieved content must stay untrusted
Why retrieved content must stay data, not become authority over the system.
Why multi-agent systems need decision rules
Why agents need arbitration rules before disagreement reaches the final answer.
Why handoffs need contracts
Why reliable handoffs need structured state, evidence, open questions, and ownership.
Why shared memory becomes a permission problem
Why shared memory becomes an access-control problem in multi-agent systems.
Why agents need a shared language
Why agents need shared message contracts before they can collaborate reliably.
Why role design matters more than agent count
Why agent roles need clear purpose, authority, tools, memory, and evaluation.
When decentralized agent behavior makes sense
Why decentralized agent behavior needs convergence rules before it earns production trust.
Why AI debate needs a reliable judge
Why AI debate is only useful when the judge has reliable criteria.
Why shared state needs structure and attribution
Why shared state needs structure, attribution, and versioning to stay debuggable.
Why peer agents need protocols, not vibes
Why peer agents need communication rules, round limits, and a final decision owner.
Why dynamic dispatch needs ownership rules
Why dynamic dispatch needs visible routing decisions and clear final ownership.
Why pipelines make AI handoffs inspectable
Why predictable AI workflows often benefit from pipeline structure before agent autonomy.
Why supervisor agents help and where they bottleneck
Why supervisor agents help only when routing, review, and authority are clear.
When hierarchy helps multi-agent work scale
Why hierarchy helps when work has real layers of authority and responsibility.
Why one giant agent is rarely the cleanest design
Why multi-agent systems should reduce complexity through specialization, not add agents for novelty.
Why autonomy needs budgets
Why autonomous systems need limits on cost, time, actions, retries, and risk.
June 2026 29
Why production agents need recovery design
Why retries, fallbacks, checkpoints, rollback, and escalation belong in the first design.
Why guardrails should enable safe action
Why guardrails should shape safe progress, not just block uncertain behavior.
Where human review actually belongs in AI workflows
Why human review needs timing, authority, and context to be useful.
Why agent memory is not one database
Why useful agent memory has to be separated, scoped, and governed.
Why reflection should change the next action
Why reflection is valuable only when it decides whether to revise, retry, escalate, or stop.
Why tool access is where AI becomes operational risk
Why giving AI tools means designing permissions, observability, rollback, and approval paths.
Why planning reduces wasted AI actions
Why planning matters when actions have cost, risk, or dependencies.
Why agent behavior is a loop, not a single prompt
Why reliable agent behavior comes from loop design, not a single clever prompt.
Why agents need outcomes, boundaries, and stop conditions
Why agents need clear outcomes, boundaries, budgets, and stop conditions before autonomy.
Why RAG must be evaluated in parts
Why RAG evaluation has to measure retrieval, grounding, generation, and citations separately.
Why weak evidence should trigger recovery, not confidence
Why weak evidence should trigger recovery, not a fluent answer with false confidence.
Why reflection only matters when tied to evidence
Why reflection only helps when it checks the answer against evidence and changes behavior.
Why freshness is part of correctness
Why freshness becomes part of correctness when the world changes faster than your index.
Why evidence is becoming multimodal
Why evidence quality changes when the source is visual, tabular, audio, or multimodal.
Why production knowledge often lives in systems, not PDFs
Why production knowledge often lives in systems of record, not only in documents.
Why some answers live in relationships, not documents
Why some answers depend on relationships that plain document search can miss.
Why one user question may need many searches
Why one user question may need multiple searches before the evidence is good enough.
Why complex AI questions need decomposition
Why complex questions become more reliable when the system answers them in parts.
Why RAG needs both broad context and precise evidence
Why good RAG often needs both precise snippets and enough surrounding context.
Why every important AI claim needs provenance
Why important AI claims need receipts that users and teams can inspect.
Why reranking is where retrieval becomes useful
How reranking turns broad retrieval candidates into evidence the answer can depend on.
Why relevant data can still be unauthorized data
Why relevant evidence is still wrong evidence if the user was not allowed to see it.
Why vector stores are infrastructure, not magic memory
Why vector databases need to be operated like infrastructure, not treated like magic memory.
Why keyword search and semantic search both matter
Why exact words and semantic meaning both matter in production retrieval.
Why hybrid search is often the practical default
Why combining retrieval signals is often more practical than betting on one search method.
Why embeddings are useful and easy to overtrust
Why semantic similarity is useful, but not the same as correctness or trust.
Why chunk boundaries shape answer quality
How chunk boundaries decide what evidence the system can actually retrieve.
Why retrieval quality starts before search
Why answer quality starts when knowledge enters the system, not when the user asks.
Why RAG is an evidence design problem, not a buzzword
Why RAG is really about trusted evidence, not just letting the model search.
May 2026 10
When to use a chatbot, workflow, or agent
A practical way to choose between conversation, repeatable workflows, and bounded autonomy.
Why production AI needs structured outputs
How structured output turns model text into something software can safely use.
Why a capable model is still not a product
Why strong model capability still needs workflow, product, and ownership design.
Why confident AI answers still need evidence
Why confident language still needs evidence, boundaries, and uncertainty paths.
Why creativity settings are product decisions
How sampling settings shape the user experience, not just the writing style.
Why more context can make an AI system worse
Why a larger context window does not remove the need for context discipline.
Why vague prompts become vague systems
Why prompts become operational instructions once real users depend on the system.
Why LLMs feel intelligent but still generate one step at a time
The practical reason LLM behavior needs constraints, validation, and repeatable output design.
Why tokenization quietly affects cost, limits, and reliability
How a low-level text detail quietly becomes a product constraint for cost, latency, and reliability.
Why model choice is rarely the first production AI problem
Why production AI succeeds or fails in the system around the model, not in the model choice alone.
Coverage by disciplineThinnest so far: Networking (5), Identity & Access (7)
Coverage
Disciplines down, series across. An entry counts once for each discipline it covers. Select a cell to read those entries.
Thinnest so far: Networking (5), Identity & Access (7)
| Discipline | Basics | Demo → product | Retrieval | Evidence RAG | RAG ops | Agents | Control | Multi-agent | Coordination | Readiness | MCP | Agent infra | Prod RAG | Evaluation | Safety | MAS design | Arch patterns | AI ops | Standalone | All |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| AI & Models | 6 | 5 | 1 | 3 | 2 | 5 | 4 | 6 | 4 | 2 | 1 | · | 2 | 1 | 1 | 5 | 1 | 1 | 10 | 60 |
| Data & Databases | 1 | 3 | 6 | 6 | 5 | 1 | · | 1 | 1 | 1 | · | 1 | 5 | 1 | 1 | · | · | 1 | 9 | 43 |
| Networking | · | · | · | · | · | · | · | · | · | · | 2 | · | · | · | · | · | 2 | · | 1 | 5 |
| Security | · | · | 1 | · | · | 2 | 2 | · | 1 | 2 | 1 | 2 | 1 | · | 5 | 1 | 1 | · | 9 | 28 |
| Identity & Access | · | · | 1 | · | · | · | · | · | 1 | · | · | 1 | · | · | 1 | · | 1 | · | 2 | 7 |
| Integration | · | 1 | · | · | 2 | 1 | · | 2 | 2 | 1 | 4 | 2 | · | · | · | 1 | 2 | · | 5 | 23 |
| Compute & Infra | · | 1 | 1 | · | · | 1 | 4 | · | · | 1 | 1 | 4 | · | 1 | 1 | 1 | 2 | 1 | 2 | 21 |
| Observability & Ops | · | · | · | · | 1 | · | 1 | 1 | · | 2 | · | 1 | 1 | 5 | · | 1 | 1 | 4 | 4 | 22 |
| Cost & Governance | 2 | · | · | 1 | · | 1 | 1 | · | 1 | 1 | · | · | · | · | 1 | 1 | 1 | 1 | 3 | 14 |
Series progressAll 18 series complete, 100 parts
Series
All series- AI Systems Basics6/6
- From LLM Demo to AI Product6/6
- Retrieval Foundations6/6
- Evidence-Driven RAG Patterns6/6
- Production RAG Operations6/6
- Agentic AI Foundations6/6
- Agent Control and Supervision6/6
- Multi-Agent Design Patterns6/6
- Agent Coordination Contracts6/6
- Production AI Readiness6/6
- 5 Days of MCP for Production AI5/5
- 5 Days of Agent Infrastructure5/5
- 5 Days of Production RAG5/5
- 5 Days of AI Evaluation5/5
- 5 Days of AI Safety Engineering5/5
- 5 Days of Multi-Agent System Design5/5
- 5 Days of AI Architecture Patterns5/5
- 5 Days of AI Operations and Observability5/5