Think. Throw. Unearth.
Signal Rail is a plain-text document governance system for personal and project material.
It gives your work separate rails for current state, decisions, unresolved material, hard constraints, surface maps, handoff, parking, and archive.
The point is not to make a project smaller than it is.
The point is to keep the material readable while the project grows, branches, changes shape, and comes back after interruption.
Project documentation usually breaks when everything lives in the same undifferentiated space.
A note becomes a decision.
A possibility becomes a constraint.
A current blocker gets buried under old context.
A useful thread disappears because it was never placed anywhere stable.
Signal Rail prevents that by giving material a destination before it becomes noise.
It asks one practical question:
What kind of material is this, and where should it live?
The answer changes the file.
A current live line belongs in 03_master_working.txt.
A decision that has already won belongs in 04_decision_log.txt.
A still-mobile but important direction belongs in 05_latent_ideas.txt.
A hard-to-reopen identity constant belongs in 02_protocol_freeze.txt.
A technical entrypoint or sensitive surface belongs in 08_surface_map.txt.
Nothing is promoted just because it sounds strong.
Create a Signal Rail instance in the project area you want to govern.
You can do that in two ways:
Run:
init_signal_rail.bat
Use this when you want the kit to create the instance structure for you.
You can also copy the needed Signal Rail files into the target folder yourself.
Manual copy is valid, but the copied instance must still preserve the required file names, marker structure, canonical roles, and entry flow.
After the instance exists:
- Open an AI chat inside the working context.
- Ask the agent to read:
00_runtime_entry.txt
- Then ask it to read:
06_ai_to_ai.txt
- Let the agent close the minimum frame:
- host project
- working object
- active mode
- source scope
- authority
- Start the work from that closed frame.
For a non-English version, use SR Localization Kit to create a separate localized copy before you begin.
Do not localize the baseline in place.
Signal Rail is mainly designed to be operated with an AI agent during real work.
You think, work, speak, paste material, or bring a messy source set.
The agent reads the Signal Rail entry layer, activates the lateral kernel, closes the working frame, and helps route material into the right document without mixing levels.
The human stays in charge of meaning, authority, and approval.
The agent helps with:
- 🧭 closing the active frame
- 🧩 separating material into units
- ⚖️ distinguishing current work, decision, idea, freeze, handoff, and map
- 🛑 stopping before unsafe promotion
- ✍️ preparing or applying document updates when authority is clear
- 🔁 recovering continuity without treating continuity as truth
This is the main use case: Signal Rail as a governed document system operated interactively while the project is alive.
Signal Rail also includes a local workstation:
signal_rail_workstation_final.html
The workstation gives the operator a clearer human surface for maintaining a live Signal Rail instance.
Use it to:
- 📚 read canonical files
- 🔎 inspect runtime state
- ✍️ stage edits
- 👁️ preview changes
- 💾 write back to the matching
.txtfiles when local folder access is available
The workstation does not replace the canonicals.
It does not change authority.
It exists because direct manual maintenance is possible, but easy to get wrong when routing, markers, authority, and promotion rules matter.
Signal Rail files are plain text.
You can maintain them with a simple editor.
Manual editing is a fallback, not the safest default.
If you edit by hand, you must respect:
- canonical destination
- file authority
- local templates
- entry markers
- append zones
- ID families
- source authority
- promotion boundaries
For append-driven files, write new live entries only inside their entry zone.
--- ENTRIES START ---
...
--- ENTRIES END ---
Do not turn manual editing into free-form note taking.
Signal Rail works because the rails stay strict.
07_guided_prompts_test.txt provides guided entry paths for higher-risk operating situations.
These are not casual prompt examples.
They exist to help the agent ask the smallest useful questions before reading, routing, rewriting, or rebuilding state.
Useful paths include:
| Situation | What the guided path protects |
|---|---|
| 🆕 New or near-blank instance | Opens a Signal Rail instance without inventing project reality. |
| 🧭 Safe session start | Closes host project, authority, working object, mode, goal, and source scope before action. |
| 🧱 Confused sources and authority rebuild | Separates messy sources, timeline uncertainty, live state, and governing authority before ingest. |
| 🧪 Review before rewrite | Prevents cleanup from rewriting material whose governing source is not closed. |
| 🗺️ Destination closure | Routes extracted material by nature, stability, and authority instead of by file proximity. |
Use these paths when a normal session opening is not enough.
Signal Rail separates material by role.
| Rail | File | What belongs there |
|---|---|---|
| 🚪 Runtime entry | 00_runtime_entry.txt |
Valid entry, minimum read, and reading boundaries. |
| 🧭 Orientation | 01_orientation.txt |
Project identity, perimeter, and reading frame. |
| 🧊 Freeze | 02_protocol_freeze.txt |
Identity constants that should be hard to reopen. |
| 🔥 Master working | 03_master_working.txt |
Current live state, blocker, active work, and next move. |
| ⚖️ Decision log | 04_decision_log.txt |
Choices already taken, already in effect, and already won against alternatives. |
| 🌱 Latent ideas | 05_latent_ideas.txt |
Important unresolved material that still needs motion or placement. |
| 🧠 Lateral kernel | 06_ai_to_ai.txt |
Agent operating behavior inside a Signal Rail instance. |
| 🧰 Guided prompts | 07_guided_prompts_test.txt |
Guided paths for safer starts, rebuilds, reviews, and routing passes. |
| 🗺️ Surface map | 08_surface_map.txt |
Real technical topology, entrypoints, sensitive surfaces, and minimal runbook. |
| 🔁 Handoff | 09_handoff_reentry.txt |
Re-entry support and continuity, not canonical project truth. |
| 🧲 Field findings | 97_field_findings.txt |
Lateral captures during an active pass before routing or discard. |
| 📌 Parking | 98_parking.txt |
Useful material that is not active now. |
| 📦 Archive | 99_archive.txt |
Closed, historical, duplicate, or no-longer-live material. |
06_ai_to_ai.txt is a lateral kernel.
It is not the host project.
It is not a global personality file.
It does not make every AI answer follow Signal Rail everywhere.
It governs the agent while the agent is operating inside a Signal Rail instance, so the agent can read, stop, ask, route, propose, and write without confusing document levels.
This is why Signal Rail stays light.
The kernel becomes active in the right context, for the right folder, with the right entry layer.
It does not turn the whole AI session into a permanent document-management contract outside Signal Rail.
Keep these separate.
| Surface | Meaning |
|---|---|
| Clean baseline kit | This repository. The reusable Signal Rail source. |
| Deployed instance | A copy of Signal Rail 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. |
A deployed instance marker only says that the folder is a Signal Rail instance.
It does not identify the host project by itself.
The agent must still close the host project, working object, mode, scope, and authority before substantive action.
Signal Rail is strict because project material becomes dangerous when level and authority blur.
These are the failures it blocks:
- a strong sentence becoming a decision
- a live blocker becoming project identity
- a temporary solution becoming freeze
- a hypothesis entering current work too early
- a handoff note becoming canonical truth
- a technical map becoming orientation
- a clean rewrite becoming less true than the messy source
- a deployed instance being mistaken for the host project
Signal Rail does not route material by convenience.
It routes by nature, stability, and authority.
⚙️ Technical canonical reference
01_orientation.txt
Project identity, perimeter, and reading frame. This is where the project remains understandable as itself.
02_protocol_freeze.txt
Identity constants. The points that, if removed, would make the project stop being itself. Hard to reopen by design.
03_master_working.txt
The current live state of the project: where it is now, what is active, what is blocking it, and what the next sensible move is.
04_decision_log.txt
Already-won decisions. Not preferences, not strong possibilities: choices that have already beaten a real alternative and are already in effect.
05_latent_ideas.txt
Material that matters but is still mobile. Where live but unresolved ideas stay visible without being promoted too early.
08_surface_map.txt
The real technical map: entrypoints, sensitive surfaces, critical dependencies, and the minimum safe runbook.
09_handoff_reentry.txt
Short continuity between sessions. Useful for re-entry, not canonical project truth.
97_field_findings.txt
Lateral captures during an active pass: signals, seeds, refinements, and observations before routing or discarding.
98_parking.txt
Not active now, could still matter later.
99_archive.txt
Closed, historical, no-longer-live.
00_runtime_entry.txt
Runtime entry manual. Closes valid entry and correct system reading before the kernel becomes operative.
06_ai_to_ai.txt
The operating kernel for agent behavior inside Signal Rail. It governs how the agent reads, stops, asks, proposes, and writes.
07_guided_prompts_test.txt
Guided prompts and safer opening flows for starts, bootstraps, source rebuilds, review-before-rewrite passes, and destination closure.
AI_TO_AI__DEPLOYED_INSTANCE_SIGNAL_RAIL.txt
Marker file. Identifies a folder as a deployed Signal Rail instance. It does not identify the host project or authoritative source by itself.
Signal Rail opens through a controlled runtime path:
00_runtime_entry.txtcloses how to enter.06_ai_to_ai.txtcloses how the agent may move.- Canonicals and support files are then read according to task sensitivity.
Minimum read before substantive action protects the project from wrong entry.
Reading does not authorize writing.
Understanding does not authorize promotion.
Signal Rail does not route material by convenience.
It routes by:
- nature
- stability
- authority
- destination
- current mode
- source closure
| If the material is... | Ask first... | Likely destination |
|---|---|---|
| project identity | does this define what the project is? | 01_orientation.txt |
| hard-to-reopen constant | would removing this change project identity? | 02_protocol_freeze.txt |
| current live work | is this already guiding present work? | 03_master_working.txt |
| already-won choice | has this already beaten a real alternative and entered effect? | 04_decision_log.txt |
| live but unresolved | does it matter, but still need to stay mobile? | 05_latent_ideas.txt |
| technical topology | is this about where to enter, what is sensitive, or what is minimally required to work safely? | 08_surface_map.txt |
| continuity only | is this mainly for handoff or re-entry? | 09_handoff_reentry.txt |
| out of cycle but still useful | is it not active now, but worth keeping available? | 98_parking.txt |
| closed or historical | is it no longer live? | 99_archive.txt |
A good sentence is not yet a decision.
A strong idea is not yet freeze.
Continuity is not the same thing as truth.
The kernel is strict about a few things because they prevent document drift:
- one active mode at a time
- minimum read before substantive action
- no promotion when level, authority, or destination are still unclear
- no inference of authority from freshness, cleanliness, or confidence
- fail-closed behavior on meaningful ambiguity
Signal Rail is not a “fill in the files” system.
It is a bounded operating model:
- read enough to close frame
- extract before classifying
- classify before promoting
- delay safely instead of forcing the wrong destination
Append-driven canonicals use one entries zone.
New live entries must go inside:
--- ENTRIES START ---
...
--- ENTRIES END ---
The marker contract must stay valid:
- exactly one start marker
- exactly one end marker
- correct order
- local template preserved as scaffold
[TEMPLATE ONLY]does not count as a live entry
If the marker contract is missing, duplicated, malformed, or ambiguous, stop before writing.
init_signal_rail.bat
Windows launcher. Gets you in.
init_signal_rail.ps1
Performs the bootstrap logic.
SR Localization Kit handles one job: turning the international baseline into one personal localized copy.
Intended flow:
- keep the baseline clean
- create a separate copy
- localize the copy
- validate the result
- work from that copy
It is not a runtime translation layer.
It is not a way to relocalize a live instance in place.
The kit repository is not the host project.
A deployed Signal Rail instance is not the same thing as the clean baseline repository.
A folder marked as a deployed instance does not identify the host project by itself.
Entry validity is closed in 00_runtime_entry.txt.
Execution behavior is governed in 06_ai_to_ai.txt.
If local tooling changes or disappears, the canonicals and the kernel should still remain readable and usable.
This project was developed with AI assistance.
The project, documentation, and repository materials were shaped through human-directed work supported by AI tools during drafting, structuring, review, and refinement.
AI assistance does not make the project automatically correct, complete, or suitable for every use case. Read it, test it, and adapt it to your own context.
See LICENSE.