Doc system test
Page 3 of 6 · Old docs

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.

The old site

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.

By kind

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:

The 62 old-docs findings, by kind
says what the code does not do
35 findings
leaves out what a reader needs
21 findings
one concept split across pages
2 findings
no example
2 findings
one word used for two things
1 finding
hard to find
1 finding
out of date
0 findings
tells history as the present
0 findings
Show as table
findings
says what the code does not do35
leaves out what a reader needs21
one concept split across pages2
no example2
one word used for two things1
hard to find1
out of date0
tells history as the present0

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 ones

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

    wrong

    Old 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: merge

    Old doc: developer/templates/explanation/3-way-merge.mdx:47
    Code: iridium cyanprint/src/run.rs:140-173

  • What happens on a merge conflict

    wrong

    Old doc saysYou are prompted to resolve conflicts.

    The code doesGit conflict markers are written into the file. Nobody is asked anything.

    Trap word: conflict

    Old doc: user/explanation/3-way-merge.mdx:37
    Code: iridium cyancoordinator/src/fs/merger.rs:262-267

  • Where the state lives

    wrong

    Old 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:613

  • Whether deterministic state is kept

    wrong

    Old 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-24

  • When conflict resolvers run

    wrong

    Old 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: resolver

    Old doc: developer/resolvers/explanation/resolvers-in-pipeline.mdx:12
    Code: boron docker_executor/merger.go:362; iridium layerer.rs:213

  • How a resolver is picked between templates

    missing

    Old 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: resolver

    Old doc: no page
    Code: iridium conflict_file_resolver/consensus.rs:69-122

  • How long a resolver may take

    wrong

    Old doc saysResolvers have a 10-minute timeout.

    The code doesThe coordinator's proxy cuts them off at 30 seconds.

    Trap word: resolver

    Old doc: developer/resolvers/explanation/resolvers-in-pipeline.mdx:135
    Code: boron server.go:757

  • Which dependency's files win

    wrong

    Old 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: layer

    Old doc: developer/templates/how-to/compose-templates.mdx:91
    Code: iridium composition/resolver.rs:71

  • What happens on a version conflict

    wrong

    Old 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: conflict

    Old doc: contributor/architecture/execution-flow.mdx:185
    Code: zinc TemplateRepository.cs:975-1017; iridium composition/resolver.rs:63-117

  • What "dependency resolution" means

    one word, two things

    Old 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: layer

    Old 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.

Gaps

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.

Found while reading

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 update loses 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-161 against 244-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.

To be fair

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.

Why

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.