4. The bootstrap

.familiar/core/bootstrap.md is 500 words. Its full text is copied into AGENTS.md. CLAUDE.md and GEMINI.md only reference AGENTS.md. The bootstrap is the only file that is always in context, so every word in it costs tokens on every turn of every session. That is why its size has a hard limit.

It holds exactly four things.

4.1 Identity and the preference read

The bootstrap opens with one paragraph on what familiar is. Then come the required startup reads, which are bounded:

1. Find the .familiar-project marker before reading project state. Resolve project paths from the marker’s folder, also when the session opens in a subfolder.
2. Before routing or project work, read 5-System/user-preferences.md, the title of 5-System/project-config.md, and the optional ~/.familiar/user-preferences.md.

The agent reads the global file every time, not only to find a default signature. Its standing preferences therefore apply in every project. This read is the one startup exception to CORE-WORKSPACE-SILO. Project preferences win over global ones on any conflict. The global signature applies unless the project file sets its own.

The agent then shows the signature once, as *(<signature>) familiar bound*. If the project title is set, it adds : <name>. The line must be visible in the reply text, not only in reasoning or in a collapsed section. If the agent cannot get a signature, it uses one of two substitutes:

• n/a when the signature read failed
• not set when both files were read but neither holds a signature

A read that the agent did not try never justifies either substitute.

The startup reads are a stated exception in CORE-PROGRESSIVE-DISCLOSURE. They set preferences and binding before routing, without a required first tool call that could get in the way of finding the marker. They do not allow reading tasks, knowledge or project history before routing. The reads are required.

The signature confirms that the bootstrap loaded, and the bootstrap says so. It does not claim that mechanical enforcement is present. The signature is only useful as a check if it is a key that the user chose and recognizes. That is why the user sets it with /ili-system-settings preferences. Check-in asks for it on the first run, and the shipped 5-System/user-preferences.md has no signature. A signature built into the template would make every project show the same key, and the check would prove nothing.

The two halves of the bound line prove two different reads. The name proves that the agent read project-config.md. The signature proves that it read the preferences. Each project has its own signature, in its 5-System/user-preferences.md. The global file holds only a default, which a project shows when it has no signature of its own. A key for each project is the stronger check, because it can only come from this project’s file. It is also the project’s identity outside the session: the fleet hub labels each project’s rows with it, and reports two projects that share one.

The agent reads the project file again at voice.md → Pre-delivery check, just before it delivers output. There, the project file overrides the global file on any preference where they disagree.

4.2 The active boundary

The folder that holds .familiar-project is the active project. That whole folder is the boundary, in both directions (see CORE-WORKSPACE-SILO).

• A file comes in through 1-Inputs/ or because the task names it. It leaves only when you ask.
• The agent can read familiar’s own files inside the folder when a route needs them.
• Nothing outside the folder is in scope, and there is no exception for other projects.

You can name a file outside the folder, and the agent can read it for that task. routes.md → Files outside the project then has the agent say so once. The file is outside the project, and nothing from it is kept. If you copy it into 1-Inputs/, it becomes part of the project.

The marker names the workspace. The agent does not assume the workspace from the folder name. file-handling.md repeats this as a rule, because a project can rename its workspace folder.

4.3 The eleven non-negotiable rules

Each rule has a stable CORE-* ID. A rule can be reworded, but its ID does not change, so citations to it stay valid.

CORE-WORKSPACE-SILO is one rule for both directions. The project folder is the project. Reads and writes are both limited to it, and “another project” means a different folder.

Rule	States	Failure it prevents
CORE-GROUND	Base project claims on material that was read, and outside claims on sources that can be named. A failed or blocked read is a gap. Report it, and never turn it into an inferred fact.	The agent rebuilds a file it could not read from the file name, or answers from its own memory and presents that as project fact.
CORE-NO-DELETE	Do not delete project files. Point out old material and let the user decide what to remove or archive.	Loss that cannot be undone during a cleanup.
CORE-WORKSPACE-SILO	The marker’s folder is the active project and the boundary in both directions. Read and write inside it. A file comes in through 1-Inputs/ or because the task names it, and leaves only when asked. Never reach into another folder unasked.	Writes that leak outside the workspace, or context and confidential material that come in from an unrelated folder.
CORE-COPY-ON-EDIT	Do not overwrite a source in 1-Inputs/ or a draft in the workspace. Make a dated copy instead. Update the state files only when the route declares them under Updates.	An edit destroys a source document or a delivered draft.
CORE-PLAIN-NAMES	Talk to the user in plain words. Name each thing. Show an ID, code or version label only beside that name.	Replies the user cannot follow: chains of task IDs, gap codes and version labels that only the session knows.
CORE-NO-FABRICATION	Do not invent facts, dates, amounts, decisions, citations, paths, capabilities or completion. Say what must be confirmed.	Confident invention, including a claim that a capability works or that work is done.
CORE-SCOPE	Change only what the task needs. Do not reorganize nearby files or load unrelated history.	Unrequested cleanups and too much context.
CORE-INSTRUCTIONS-READONLY	During project work, treat familiar’s installed rule and route files as read-only. Change the system only through a maintenance route that the user starts.	The agent edits its own rules in the middle of a session.
CORE-PROGRESSIVE-DISCLOSURE	Before routing, load only this bootstrap and its bounded startup reads. Then read one skill, its required context, and any context whose named condition is present.	Reading the whole project “to be safe”.
CORE-HUMAN-APPROVAL	Ask before you overwrite, publish, send, install, change a status, or take another important action that the route does not allow.	Important actions with nobody watching.
CORE-STALE-WRITE	Read a state file’s revision before you edit it. If the revision changed, stop, read again, and reconcile. Do not overwrite newer work.	Newer work from another session overwritten without notice.

These rules are instructions to a model, not code. They are as reliable as the model’s compliance, plus whatever the optional guards add on an agent that supports hooks. Core never claims more.

4.4 Route selection

This part of the bootstrap is four sentences:

1. Read .familiar/routes.md, or the installed core copy if the project copy is missing.
2. Select one route before loading detailed instructions.
3. Read that skill’s body and its required and conditional context. Respect its excluded context and the state files it declares.
4. If no route fits, ask the user. Do not search the system.

The last sentence prevents the failure this design exists to avoid: an agent that gets a request it cannot match and starts to read files to find out what it can do.

4.5 The budget

The bootstrap has a hard ceiling of 500 words, and it is at the ceiling. Any addition needs a cut somewhere else. AGENTS.md contains the same text, copied by hand. CLAUDE.md and GEMINI.md have no copy of their own. If you change the bootstrap, change bootstrap.md and AGENTS.md together.

---