Every Signal Rail instance opens with a reading frame.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.
01_orientation.txt is that frame — it explains what the project is, why it exists, and how it should be understood. It does not describe what is happening right now. It does not record decisions. It gives the stable shape of the project so that every subsequent file can be read correctly without guessing what kind of thing it is describing.
What it is
01_orientation.txt explains what the project is. It gives the right frame before the rest is read. It prevents wrong readings of the project that arise when someone enters through a working file without first understanding what the project actually is.
This file is also one of the two mandatory reads before substantive action in every session — the other being 03_master_working.txt. Together they provide the minimum frame: what the project is, and where it currently stands.
What goes here
Each item below belongs in01_orientation.txt because it defines the identity-shape of the project — not what is happening now, but what remains true even when the work changes.
| Item | Why it belongs here |
|---|---|
| Project name | Closes what we are talking about immediately. Good naming gives instant orientation. |
| Clear description | Lets someone understand the project without reading everything else first. |
| Need or tension | Explains why the project exists. Focused well, it gives a more readable base for everything else. |
| Core direction | The guiding idea the project follows. Keeps the project legible even when work changes. |
| Accepted trade-offs | Shows how the project holds in reality — its relationship with time, cost, friction, and concrete limits. |
| Main boundaries | Shows what really belongs to the project and what does not. |
| Hard boundaries | Names the separations you do not want confused. Prevents recurring reading mistakes. |
What does NOT go here
The following material does not define project identity — it describes present or past state, and belongs elsewhere:
- Current work →
03_master_working.txt— describes the current live state, not project identity - Current blockers or next moves →
03_master_working.txt— belongs to work in progress - Decisions already taken →
04_decision_log.txt— records what has already won, not what the project is - Ideas still under evaluation →
05_latent_ideas.txt— not yet closed enough to read as true - Repos, key folders, entrypoints, sensitive surfaces, minimal runbook, critical dependencies →
08_surface_map.txt— describes where the project lives technically, not what it is - Document management methods or tool adoption — describes a working method, not the project
- Explanations about Signal Rail itself — system tooling does not define the project
- Backlog, diary, changelog, or manifesto — these accumulate; orientation should stay stable
When to update
Update01_orientation.txt only when the correct way to understand the project changes:
- The real perimeter changes
- A core direction changes
- Important trade-offs or boundaries change
- The project identity shifts in a substantial way
File sections
Project Name
Project Name
The real project name. Closes what we are talking about immediately. A well-named project gains instant orientation before a single further line is read.
What It Is
What It Is
A short, clear description in 1–3 sentences. A new person should be able to understand the project without reading anything else. Keep the tone clear, simple, and concrete — not promotional, not abstract.
Why It Exists
Why It Exists
The need, friction, or lack that made the project exist. This is not the project vision — it is the thing the project was made to address. Get to the point.
Core Direction
Core Direction
The guiding idea of the project. Temporary practical choices do not belong here. This section should remain true even when tools, working style, or team composition changes.
Accepted Trade-offs
Accepted Trade-offs
The trade-offs the project accepts to stay alive. This includes the relationship with time, cost, friction, maintenance, real use, and concrete limits. If you make them clear, the project becomes less abstract and more honest.
Main Boundaries
Main Boundaries
The boundaries that help explain what the project is and is not. Include only boundaries that genuinely improve understanding — not everything that could be a boundary.
Hard Boundaries
Hard Boundaries
The separations you do not want confused. Include only the ones that help read the project without error. These exist to prevent recurring misreading, not to define aspirations.
Section hygiene
Section titles in01_orientation.txt are operational anchors for reading and maintenance. Keep them stable.
- Do not create unnecessary duplicates of section titles when the file is live
- If you reopen template slots, close them again as soon as the file returns to being a real surface
- Open slots are acceptable only while the file is clearly incomplete — they should not become the normal form of a live orientation file
- Use
external referencefor useful material outside the canonical set; do not pretend external sources are canonical links
Typical errors
- Using it to explain what is happening right now — that belongs in
03_master_working.txt - Putting decisions or workflow changes here — that belongs in
04_decision_log.txt - Treating it as a manifesto or promotional page — orientation is for understanding, not persuasion
- Leaving it so abstract that the project still cannot be understood — a live orientation file should orient