Signal Rail’s operating model rests on a small number of firm distinctions. Understanding them correctly is what separates a governed document system from a pile of well-named files. This page defines the core concepts in the order you need them: what the surfaces are, how authority works, how material gets routed, where each level lives, and what conditions must be true before any write is allowed.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/xxyoudeadpunkxx/signal-rail/llms.txt
Use this file to discover all available pages before exploring further.
1. Baseline, instance, and host project
These three surfaces are distinct by design. Confusing them is one of the most common entry errors.| Surface | Meaning |
|---|---|
| Clean baseline kit | This repository. The reusable Signal Rail source. |
| Deployed instance | A copy used inside or beside a real project. |
| Host project | The actual project being governed. |
| Workstation | Optional local interface for reading, staging, previewing, and writing a live instance. |
AI_TO_AI__DEPLOYED_INSTANCE_SIGNAL_RAIL.txt) identifies the folder as a Signal Rail tool — it says nothing about what is being governed. The agent must always close the host project explicitly before any canonical action.
2. Canonical vs. lateral surfaces
Signal Rail files fall into two categories with different authority levels. Canonical surfaces are files01 through 09. Each canonical governs exactly one level. 01 governs project identity. 03 governs current live state. 04 governs taken decisions. None of them override each other outside their own domain — in any conflict, the file that governs the touched level decides the reading boundary.
Lateral surfaces are 97, 98, 99, and the instance marker. They provide support functions: temporary capture, parking, archive, and instance identification. Lateral surfaces do not override canonicals. 09_handoff_reentry.txt supports continuity but does not override canonical project truth, even when it summarizes canonical state for re-entry.
06_ai_to_ai.txt is a special case: it is a lateral kernel that governs horizontal protocol behavior across the whole system. It does not govern any single canonical level — it governs the agent’s movement between all of them.
3. The routing order
Every piece of material passes through three questions in a fixed order before it is placed anywhere. This order is not a suggestion — it is the discipline that keeps level and authority clean.Close what the unit IS
Classify the unit itself — not the file it came from, not the format it arrived in. What kind of material is this? Is it live work, a won decision, a latent idea, an identity constant, or a technical fact?
Close how STABLE it is
How settled is this material? Is it already in effect, or still mobile? Is it ready to be committed to a level, or does it still need to stay fluid?
Non-promotion rules. Clarity is not authority. Strength is not promotion. A summary is not a source. A strong sentence is not a decision. An elegant structure is not freeze. A plausible line is not live work. If destination is not closed enough, do not force promotion.
4. Level map
Each canonical file owns exactly one level. Material lands in the file whose level matches — nothing else.01 — Identity: 01_orientation.txt
01 — Identity: 01_orientation.txt
Project identity, perimeter, and reading frame. What the project is, why it exists, its core direction, accepted trade-offs, and the separations you do not want confused. This is not where current work, blockers, decisions, or unresolved ideas live. Update it only when the correct way to understand the project changes — not for operational movement.
02 — Freeze: 02_protocol_freeze.txt
02 — Freeze: 02_protocol_freeze.txt
Hard-to-reopen identity constants. The points that, if removed, would make the project stop being itself. Use this only for lines that have genuinely passed the threshold of identity-level commitment. Strong strategy that is still being tested does not belong here.
03 — Current live work: 03_master_working.txt
03 — Current live work: 03_master_working.txt
The live pulse of the project: current objective, dominant blocker, and next sensible move. This file has authority on current intended work state. It is not an orientation log, a boot log, or a history. It changes as work changes. Do not use it for proposals, likely next moves, or strong ideas that are not already adopted as current live work.
04 — Decisions: 04_decision_log.txt
04 — Decisions: 04_decision_log.txt
Already-won decisions that are already in effect. A line enters
04 only after it has already beaten a real alternative and entered effect. It is not brainstorming and not a deduced decision. 03 may show a live line before 04 records it — 04 records it only after it has already won.05 — Latent ideas: 05_latent_ideas.txt
05 — Latent ideas: 05_latent_ideas.txt
Live unresolved material that still needs motion or placement. This is the safe hold for material whose destination is not yet closed enough. If a unit shows repeated structural relevance, its gravity (strongest plausible level) can be labelled — but gravity is not authority until verified by the operator.
05 is not permanent archive.08 — Technical topology: 08_surface_map.txt
08 — Technical topology: 08_surface_map.txt
The real technical map: entrypoints, sensitive surfaces, critical dependencies, and the minimum safe runbook. Use this when the content maps where the project really lives — where to enter, where not to enter, what is sensitive, and what is minimally required to work safely. Do not use it for identity, current live work, taken decisions, or unresolved ideas.
09 — Continuity: 09_handoff_reentry.txt
09 — Continuity: 09_handoff_reentry.txt
Short continuity between sessions for re-entry and restart support. The output of
09 is non-canonical by default. It may summarize canonical state for continuity, but canonical updates must be routed separately. Do not treat 09 as canonical project truth.5. Append-driven entry zones
Seven files are append-driven:04, 05, 08, 09, 97, 98, and 99. These files do not accept free-form edits anywhere in the document. All new live entries must be written inside a single, well-formed entry zone:
- Exactly one
--- ENTRIES START ---marker per file - Exactly one
--- ENTRIES END ---marker per file - Correct order: START before END
- The local template is preserved as scaffolding inside the zone
[TEMPLATE ONLY] blocks inside the entry zone are scaffolding. They are not live entries. The agent must not count them as real entries during a structured read, and must not overwrite them when appending.
If the marker contract is missing, duplicated, malformed, or ambiguous in any file that will be written, the agent must stop before writing and ask for resolution.
6. ID families
Each append-driven canonical that tracks discrete entries uses a file-local ID prefix. IDs are local to their container — they do not migrate across files.| Container | ID prefix |
|---|---|
02_protocol_freeze.txt | F-xx |
04_decision_log.txt | D-xx |
05_latent_ideas.txt | L-xx |
98_parking.txt | P-xx |
99_archive.txt | A-xx |
04 that relates to an idea in 05 — the reference is recorded in a links to field using the original ID. The referenced ID does not become a new local ID in the target file. Cross-file IDs stay as references; they are never re-issued as local IDs.
7. The write gate
Before the agent writes to any canonical file, all of the following conditions must be true simultaneously. If any one condition is not met, the agent must stop — not assume, not infer, and not proceed.- Destination is clear — the target file is unambiguously identified
- Level is clear — the material’s canonical level is resolved
- Authority is clear — the source authority governing this material is closed
- Mode allows writing — the active mode is not read-only (orientation is always read-only)
- Source and target live files were read in-session — not recalled from memory or previous sessions
- If append-driven: the file has exactly one valid ENTRIES START/END pair — in correct order, without duplication or malformation
- If append-driven:
[TEMPLATE ONLY]scaffolding is preserved — it must remain intact after any write
8. Recovery states
When entry validation fails or a gate condition breaks during a task, the agent returns a state and a next correct move. There are four allowed states:| State | Meaning | Next correct move |
|---|---|---|
entry-valid | Frame is closed and minimum read is complete | Move to 06_ai_to_ai.txt section 1 and proceed with the task |
blocked | A gate condition failed — host project, mode, authority, scope, or entries contract is unclear | Stop and ask for the specific closure that is missing |
uninitialized-canonical-state | 01_orientation.txt and 03_master_working.txt are still template-like and do not close identity or live state | Stop and ask the operator for initialization instructions; do not interpret template content as live authority |
divergent | More than one valid reading of the material remains open | Return the smallest safe reading, declare what remains open, and do not promote |
entry-valid, the agent does not write, does not promote, and does not force a destination. The restart path in all cases is: re-enter from 00_runtime_entry.txt section 3, then 06_ai_to_ai.txt section 1, then the mandatory reads.
Runtime Entry Reference
The full specification of 00_runtime_entry.txt: entry rules, minimum read, permissions, and the valid shortest path.
Lateral Kernel
How 06_ai_to_ai.txt governs agent movement, trigger discipline, write gates, and operating procedure inside a Signal Rail instance.