Chapter 10

The brain gets ready to meet the world

March 21, 2026

Chapter 10 — The brain gets ready to meet the world

Verified sources: git log brain 2026-03-21 + git log brain-ui 2026-03-21 Same day as chapter 9 — a different angle: the fork simulation. Key commits: 699baec (numbers corrected) · d7c346c (symlinks removed) · 803abf3 (API auto-detect) · 62b88cc (CLAUDE.md template sync)

The template existed. The laptop had booted. But distributable and usable by someone else are two different sentences. The question comes up in the same session as chapter 9: if a friend forks the template tonight, what breaks?

The answer: almost everything.

The surface audit

First finding: the trio of agents forged earlier in the session — guide, catalogist, pathfinder — existed on the desktop but had never been committed. The onboarding agents, meant to welcome a new user, were invisible to anyone who forked. Commit. Push. The most embarrassing fix of the day.

The numbers that lie

The docs. The showcase on brain.tetardtek.com displayed “14 agents” in the free tier — it had been 17 since the trio was added. “75 agents” in full — it was 81. Numbers in markdown do not update themselves.

699baec (19:57) — docs: polish agents + chiffres corriges + trio onboarding + lien story.tetardtek.com (“docs: polish agents + numbers corrected + onboarding trio + story.tetardtek.com link”)

Correction. And a question that was missing at the top of the agents page: why a brain rather than Claude alone?

The answer fits in three lines: Claude starts from zero at every session. The brain does not. Your rules, your stack, your decisions persist. Your context survives.

That is the sentence that must be there the moment a visitor arrives. Not the specs — the why.

The fork simulation

The real work begins when you simulate a fork. The laptop — a sandbox machine — plays the first user. Clone. bash setup.sh. Build.

Crash.

The files in the dashboard were symlinks to absolute paths on the desktop. On the laptop, those paths do not exist. Vite fails. The build is dead before it starts.

d7c346c (20:20) — fix: supprimer symlinks brain-ui/public/docs/ — docs servies live par brain-engine (“fix: remove symlinks brain-ui/public/docs/ — docs served live by brain-engine”)

The symlinks — leftovers of a static mode that no longer has any reason to exist. Removed. The build passes.

The invisible 404

Dashboard open. “static” badge. Every page a 404. The API works — a direct request returns 15 files, full content. But the browser sees nothing.

First hypothesis: the API environment variable is empty, requests go out relative. Fix. Rebuild. Still 404.

DevTools open. The requests go to a path that only exists in production, behind a reverse proxy. Locally, with no proxy, it is a guaranteed 404.

“si quelqu’un qui fork doit directement bidouiller on est pas bien” (“if someone who forks has to tinker right away, we’re in trouble”)

803abf3 (21:14) — fix: docs.html auto-detect API path — fonctionne local ET derriere proxy (“fix: docs.html auto-detect API path — works locally AND behind proxy”)

The fix: auto-detection. The page tries both possible paths — direct local and reverse proxy. The first one to answer wins. Zero configuration. Works everywhere.

The leak on the showcase

Last round. The VPS showcase. Refresh. The Infra and Secrets tabs display the real production services and the real names of the secret keys. The template instance was exposing the infrastructure of the prod brain.

The tabs are switched to disabled with a “soon” badge. No more leak. The showcase is safe to share.

The fork’s CLAUDE.md

A detail that is not one:

62b88cc (15:29) — fix: CLAUDE.md template sync + brain boot depuis n'importe quel cwd (“fix: CLAUDE.md template sync + brain boot from any cwd”)

CLAUDE.md — the file Claude Code reads first — had to work from any working directory. Not only from /home/tetardtek/Dev/Brain. From any path, on any machine. The fork of a stranger who is not called tetardtek and does not have the same home directory.

End of the day. Three environments tested, three environments live.

Desktop (prod)  → dashboard local  → live
Laptop (fork)   → dashboard local  → live
VPS (vitrine)   → dashboard public → live

The template has not left the circle yet. But the circle has been tested. Every friction found — symlinks, hardcoded paths, API assumptions, code drift, data leaks — is one friction removed for the next human who types bash setup.sh.

“le fork doit juste marcher” (“the fork just has to work”)

Not yet. But soon.

What was fixed

Bug found	Fix	Commit
Agent trio not committed	Agents pushed + template sync	`1dc3d4e`
Stale doc numbers (14→17 free, 75→81 full)	Real count + correction	`699baec`
Symlinks to absolute desktop paths	Removed, docs served live	`d7c346c`
Hardcoded reverse proxy API path	Local/proxy auto-detect	`803abf3`
Path-dependent CLAUDE.md	Boot from any cwd	`62b88cc`
Infra/Secrets tabs expose prod	Disabled + “soon” badge	—

Key decisions

API auto-detection. The dashboard automatically detects whether it is behind a proxy or local. Zero config for the user.
setup.sh creates everything. .env.local, npm build, brain.db — a fork that runs bash setup.sh must get a working brain. No tinkering.
Sanitized showcase. The owner tabs are disabled on the template. The demo shows the capabilities without exposing the data.
The E2E test as a method. Simulate the user journey on a sandbox machine before distributing. Every bug found = one less friction.
The “why” before the “how”. The first thing a visitor sees must not be a technical spec — it is the reason for existing.

Quotes

“si quelqu’un qui fork doit directement bidouiller on est pas bien” — “if someone who forks has to tinker right away, we’re in trouble”

“le fork doit juste marcher” — “the fork just has to work”