The old docs are mostly wrong, not just out of date
35 of 62 findings say something the code does not do; 21 leave out something a reader needs.
Silicon is a large site, sorted by reader, kind and page type
Silicon is not a small or lazy site. It has 128 pages and about 35,600 lines Measured. Every page sits in a grid with three sides.
The first side is the reader: user, developer or contributor. The second is the artifact kind: template, processor, plugin or resolver. The third is the page type, from a scheme called Diátaxis: tutorial, how-to, explanation or reference.
We checked those pages line by line against the code. That gave 62 findings Measured, each with the old line and the code line.
Silicon is mostly wrong, not out of date. It reads like docs written from a plan. They were then never checked against the code Estimate.
35 of the 62 findings say something the code does not do
Each finding has one kind. If silicon were simply old, most findings would be "out of date". Here are the 62 findings by kind:
Show as table
| findings | |
|---|---|
| says what the code does not do | 35 |
| leaves out what a reader needs | 21 |
| one concept split across pages | 2 |
| no example | 2 |
| one word used for two things | 1 |
| hard to find | 1 |
| out of date | 0 |
| tells history as the present | 0 |
Old-docs audit against the code, 18 Nov 2026.
Two kinds make up 56 of the 62 findings: wrong, and missing Measured. The two zero bars matter as much. We found no page that matched an older version of the code.
The worst errors sit on words that mean two or three things in the code
A few words carry most of the damage: resolver, merge, layer, conflict, build and TemplateState. In the code, each means two or three different things. Silicon uses one word, so it blends the meanings.
Take "conflict". In the code it means two templates writing one file. In git it means a merge conflict. Silicon also uses it for version clashes, which the code never has. And TemplateState names both the outcome of the questions and one record in the state file.
Here are ten of the worst findings, side by side with the code. Each card gives the old claim, what the code does, and the kind:
Where the merge base comes from
wrongOld doc saysEach create stores its base in .cyan/base/.
The code doesNo base is stored. It is rebuilt each time, by re-running the old versions with the saved answers.
Trap word: mergeOld doc: developer/templates/explanation/3-way-merge.mdx:47
Code: iridium cyanprint/src/run.rs:140-173What happens on a merge conflict
wrongOld doc saysYou are prompted to resolve conflicts.
The code doesGit conflict markers are written into the file. Nobody is asked anything.
Trap word: conflictOld doc: user/explanation/3-way-merge.mdx:37
Code: iridium cyancoordinator/src/fs/merger.rs:262-267Where the state lives
wrongOld doc saysState lives in .cyan/generation.json.
The code doesState lives in .cyan_state.yaml.
Old doc: developer/templates/explanation/client-state.mdx:16
Code: iridium cyanprint/src/run.rs:613Whether deterministic state is kept
wrongOld doc saysDeterministic states are stored in the state file.
The code doesThey are always written empty, and the SDK's final reply carries none.
Old doc: developer/templates/how-to/pin-determinism.mdx:278
Code: iridium cyancoordinator/src/state/services.rs:64; helium node/src/domain/template/service.ts:21-24When conflict resolvers run
wrongOld doc saysResolvers run after processors, before plugins.
The code doesThey run in two places: in the coordinator between one template's processors, and in the CLI between templates.
Trap word: resolverOld doc: developer/resolvers/explanation/resolvers-in-pipeline.mdx:12
Code: boron docker_executor/merger.go:362; iridium layerer.rs:213How a resolver is picked between templates
missingOld doc saysNo page says.
The code doesEvery template that wrote the file must vote for the same resolver and config. Otherwise the last layer wins.
Trap word: resolverOld doc: no page
Code: iridium conflict_file_resolver/consensus.rs:69-122How long a resolver may take
wrongOld doc saysResolvers have a 10-minute timeout.
The code doesThe coordinator's proxy cuts them off at 30 seconds.
Trap word: resolverOld doc: developer/resolvers/explanation/resolvers-in-pipeline.mdx:135
Code: boron server.go:757Which dependency's files win
wrongOld doc saysLater templates override earlier ones.
The code doesSibling dependencies run in version-id order, a random-looking GUID, not the order in cyan.yaml.
Trap word: layerOld doc: developer/templates/how-to/compose-templates.mdx:91
Code: iridium composition/resolver.rs:71What happens on a version conflict
wrongOld doc saysVersion conflicts show a tree and suggest a fix.
The code doesThere is no version choice at run time. Every version was pinned when the template was published.
Trap word: conflictOld doc: contributor/architecture/execution-flow.mdx:185
Code: zinc TemplateRepository.cs:975-1017; iridium composition/resolver.rs:63-117What "dependency resolution" means
one word, two thingsOld doc saysVertical layering is dependency resolution.
The code doesThose are two different steps: flattening sets the run order, and layering joins the files.
Trap word: layerOld doc: developer/basics/introduction.mdx:52
Code: iridium composition/resolver.rs:63-117; iridium composition/layerer.rs:213-372
Look at the trap words. Seven of the ten sit on resolver, conflict or layer. The other three are about the merge base and the state file: the heart of your folder.
Precise words fix exactly this. The new docs give each meaning its own name. The file merger is a conflict resolver; the run order is dependency flattening.
Many ideas a reader needs never appear in the old docs at all
Gaps hurt too. The concept map counted 30 concepts that no silicon page explains. The studies named these gaps:
- resolver votes and their four outcomes
- stacking order, by latest history time
- answers scoped per template
- the node cache and its settings
- headless mode and its exit codes
- made-file and clash lists in the state file
- deleting files a template dropped
- the git dirty check and --force
- releasing sessions when a run fails
- blob images and blob volumes
- container names as the routing table
- the build phase returning a tar.gz
- readiness checks that pass after failing
- run-time lookup of processors and plugins
- keeping answers out of headless errors
Many of these are about what happens when something fails. That is exactly when a reader opens the docs.
Writing true examples found real bugs in the code
A true example means tracing what the code really does. That found bugs. Nothing was run: each was found while reading the code Measured.
cyanprint updateloses its own new history entries. It saves the copy of the state file it read before the run (update/orchestrator.rs:163,:279).- Deterministic state is never saved. A rerun makes new ids and dates, so the base of every update differs from what was written.
- Dependency layering reads resolver votes by position, but only templates with images make files. A template group early in the run order shifts the votes (
operator.rs:151-161against244-257). - The coordinator's processor and plugin readiness check reports success after every attempt fails (
executor.go:266-294). - A same-version create clears the answers of every stacked template, not just the one named (
run.rs:763). - The node cache key is made before any question is asked. A rerun can be served old answers without asking (
operator.rs:343,501). - With the cache on, a headless run prints a cache line on stdout, next to its JSON reply (
run.rs:854).
Two security-related findings are kept off this page.
Silicon also got five important things right
Silicon is wrong in many places, but not worthless. Five things in it are good, and worth keeping:
- The merge pictureBase, local and incoming, with a README example: the right way to teach the merge.
- All question typesOne page lists all six question types a template can ask.
- Make-once valuesThe d.get example shows lazy, make-once values correctly.
- The server boundaryIt names the server boundary and both layering passes, even if it then mixes them up.
- Per-kind sectionsTemplates, processors, plugins and resolvers each get a section, so an author finds their job fast.
Silicon pages: user/explanation/3-way-merge.mdx:16 · …/reference/sdk/inquirer.mdx:31 · …/explanation/determinism.mdx:91 · developer/basics/introduction.mdx:46
The fifth point matches the concept map. Authoring, the author's own context, had the most concepts right: 7 of 21.
The old docs probably drifted because of how they were organised and checked
How did a careful site end up mostly wrong? We can only infer the causes Estimate. Five stand out:
- Two doc setsEach repo also keeps its own developer docs: 156 files in five repos. They disagree with silicon and with each other.
- One idea, many pagesThe three-way merge sits on 9 pages, resolvers on 13. A fix to one page leaves the others wrong.
- No link from code to docLine numbers rot. The coordinator's own docs cite one function at line 264, six times. It now sits at line 362.
- No check at allNot one silicon page names a code path that a tool could check.
- History in code commentsSilicon has no history text. The history sits in 28 code comments instead, such as "R2 Fix".
None of these is about careless writers. Each is about structure: no owner per concept, and nothing that notices when the code moves.