Doc system test

UL

Words: project-lifecycle

Namespace: durian.cloud/cyanprint/project-lifecycle

A target folder on the user's machine - the templates stacked in it, its state file, and how create and update change it. All project state lives here and nowhere else.

WordMeaning
Target folderThe folder a user runs create or update on; it holds the made files, the user's edits and the state file.
State fileThe .cyan_state.yaml file in a target folder - one template record per stacked template, plus managed files and file clash records.
Template recordOne stacked template's entry in the state file - an active flag, its history entries and the paths it made last run.
History entryOne saved run of a stacked template - version number, time, answers and a deterministic state map.
Stacked templateOne of the templates installed into a target folder by its own create, side by side with the others.
Template stackingRunning every stacked template on its own and laying their file sets on top of each other, oldest history time first.
Template specOne stacked template to run in a batch run - user, name, version number, answers, deterministic state and time.
Batch runThe shared run behind create and update - run every spec twice, stack each list, three-way merge, write, save state, run commands.
Three-way mergeMerging the merge base, the local set and the incoming set with git, so template changes land and user edits stay.
Merge baseIn a three-way merge, what the stacked templates made on their last saved run, rebuilt by running them again.
Local setIn a three-way merge, every file in the target folder as it is now, except the state file.
Incoming setIn a three-way merge, what the stacked templates make now (new versions, new templates, fresh answers).
Merge conflictA line both the user and the template changed; written into the file with git conflict markers for the user to fix.
Managed filesThe sorted list of paths the stacked templates make, kept per template record and as one union in the state file.
File clash recordOne entry in the state file's file_conflicts list - a path two templates wrote in the last layering pass and how it was settled.
RerunCreate of a template the folder already has, at the same version - the answers of every stacked template are cleared.
UpgradeMoving a stacked template to another version, keeping its saved answers and asking only questions they do not answer.
Git dirty checkUpdate's check for uncommitted changes in the target folder before it runs.
Post-template commandA shell command a template version lists, run in the target folder after files are written.

Target folder

The folder a user runs create or update on; it holds the made files, the user's edits and the state file.

  • Do not say: project, output, destination
  • See: State file

The only place a project exists. The registry and the coordinator keep nothing about it. Default is the current folder. The CLI creates it if missing; a headless run that stops before done removes what it created.

Example: cyanprint create atomi/web:5 ./shop - ./shop is the target folder.

Not to be confused with:

  • the registry's project field: a template's project URL, not a folder
  • the coordinator's work volume: a Docker volume for one session

State file

The .cyan_state.yaml file in a target folder - one template record per stacked template, plus managed files and file clash records.

  • Do not say: client state, generation file, cyan state
  • In code: CyanState, DefaultStateManager
  • See: Template record, Managed files, File clash record

The whole client-side state of a project. Template records are top-level keys (serde flatten), not under a templates: key. Read at the start of every create and update; written at the end. managed_files and file_conflicts are recomputed on every run. It is excluded from the managed files list and from the local file set the merge reads.

Example: After step 1 of the shop example: atomi/web: active: true history: - { version: 5, time: 2026-03-01T10:00:00Z, answers: {...}, deterministic_states: {} } files: [README.md, app.config.json, ...] managed_files: [README.md, app.config.json, ...]

Not to be confused with:

  • deterministic state: the d.get values, a field inside a history entry (always empty today)
  • prompt outcome: the CLI's in-memory result of one question walk

Template record

One stacked template's entry in the state file - an active flag, its history entries and the paths it made last run.

  • Do not say: template state
  • In code: TemplateState (state/models.rs)
  • See: History entry

Keyed <user>/<template> (no version). Only records with active: true are run. Nothing in the CLI sets active: false today.

Example: atomi/web: with active: true, two history entries (versions 5 and 6) and a files list.

Not to be confused with:

  • prompt outcome: also named TemplateState in code (cyanprompt), a different type

History entry

One saved run of a stacked template - version number, time, answers and a deterministic state map.

  • In code: TemplateHistoryEntry
  • See: Template stacking

Appended on each add, upgrade or rerun of that template; never removed. The LAST entry is what the next run replays, and its time orders the stack. deterministic_states is always written empty.

Example: { version: 5, time: 2026-03-01T10:00:00Z, answers: { name: { type: String, value: shop } }, deterministic_states: {} }

Stacked template

One of the templates installed into a target folder by its own create, side by side with the others.

  • Do not say: root template, installed template
  • See: Template stacking

Not a dependency: nothing in the registry links two stacked templates; only the state file does. Every stacked template is replayed on every create and update of the folder.

Example: atomi/web (step 1) and atomi/ci (step 3) are the two stacked templates of ./shop.

Not to be confused with:

  • dependency: a template another template version lists; it is part of that template's dependency tree
  • root template: the code's word, also used for the top of a dependency tree

Template stacking

Running every stacked template on its own and laying their file sets on top of each other, oldest history time first.

  • Also called: client-side stacking
  • Do not say: horizontal layering
  • See: Dependency layering

The owner's "client-side stacking". Uses the same per-file rules as dependency layering, with resolver votes only from the stacked templates themselves. Ordered by sort_specs (time) on update and on adding a new template; unsorted on rerun and upgrade-by-create.

Example: In ./shop, web:5 (1 Mar) then ci:2 (9 Mar): both write .editorconfig, no resolver, so ci:2's file wins.

Not to be confused with:

  • dependency layering: the same rules inside ONE template version's tree, run once per stacked template

Template spec

One stacked template to run in a batch run - user, name, version number, answers, deterministic state and time.

  • Also called: previous spec, current spec
  • Do not say: spec
  • In code: TemplateSpec, TemplateSpecManager, sort_specs
  • See: Batch run

Previous specs (from the state file) build the merge base; current specs (new versions, or a new template) build the incoming set. The time is the last history entry's time and sets the stack order.

Example: Step 4: previous = [web v5, ci v2], current = [web v6, ci v2]; web keeps time 1 Mar in both.

Batch run

The shared run behind create and update - run every spec twice, stack each list, three-way merge, write, save state, run commands.

  • In code: batch_process
  • See: Three-way merge, Template stacking

Phases in code: MAP (run specs), LAYER (stack), MERGE+WRITE. Every coordinator session it opens is released even when a later step fails.

Example: Step 3 runs web:5 (base), web:5 and ci:2 (incoming), stacks the two incoming outputs, merges with ./shop, writes.

Three-way merge

Merging the merge base, the local set and the incoming set with git, so template changes land and user edits stay.

  • Also called: 3wm
  • In code: GitLikeMerger
  • See: Merge base, Merge conflict

One git merge of whole file sets in a temporary repo (branches current and incoming from a base commit), rename detection at 50 percent. A line changed on both sides gets conflict markers in the file; there is no prompt.

Example: Step 4: README.md run line changed by the user and by web:6 gets conflict markers; notes.md (user only) is kept.

Merge base

In a three-way merge, what the stacked templates made on their last saved run, rebuilt by running them again.

  • Do not say: base, original, ours
  • See: Three-way merge

Never stored. Built from the previous template specs, so it is only right if the replay is deterministic.

Example: Step 4: the merge base is web:5 + ci:2 replayed with their saved answers.

Not to be confused with:

  • local set: the folder as it is now
  • the old docs' .cyan/base/ folder: does not exist

Local set

In a three-way merge, every file in the target folder as it is now, except the state file.

  • Do not say: local, current

Read from disk with no path filter. Includes user files that no template made.

Example: ./shop with the user's README edit and notes.md.

Incoming set

In a three-way merge, what the stacked templates make now (new versions, new templates, fresh answers).

  • Do not say: incoming, theirs

Example: Step 4: web:6 + ci:2 stacked.

Merge conflict

A line both the user and the template changed; written into the file with git conflict markers for the user to fix.

  • Do not say: conflict
  • See: File clash record

Not a file clash (that is between templates). Also happens when a template's own values change between runs (lost determinism).

Example: Step 4: README.md and app.config.json.

Not to be confused with:

  • file clash: two templates write one path; settled without the user

Managed files

The sorted list of paths the stacked templates make, kept per template record and as one union in the state file.

  • In code: set_managed_files, normalize_managed_paths
  • See: State file

Taken from each current spec's own output before stacking, not from the merged folder. Recomputed wholesale each run.

Example: ./shop: .editorconfig appears under both web and ci, and once in managed_files.

File clash record

One entry in the state file's file_conflicts list - a path two templates wrote in the last layering pass and how it was settled.

  • Do not say: file conflict
  • In code: FileConflictEntry, ConflictResolution
  • See: File clash

Holds path, resolution (resolver, lww_all_no_resolver, lww_no_consensus, lww_ambiguous_resolver), the winner or resolver, and every template that wrote it. Only the LAST layering pass is kept: with two or more stacked templates that is the stacking pass.

Example: { path: .editorconfig, resolution: lww_all_no_resolver, winner_template: 42c8… }

Rerun

Create of a template the folder already has, at the same version - the answers of every stacked template are cleared.

  • Do not say: regenerate
  • In code: RerunTemplate, TemplateSpecManager::reset

Not only the named template: every current spec is reset to empty answers. With the node cache on, the empty-answer keys of the first runs hit, so nothing is asked.

Example: Step 6: cyanprint create atomi/ci:2 ./shop again.

Upgrade

Moving a stacked template to another version, keeping its saved answers and asking only questions they do not answer.

  • In code: UpgradeTemplate

Via create with another version (one template) or update (every stacked template). The template keeps its old time.

Example: Step 4: web 5 → 6 asks only runtime.

Git dirty check

Update's check for uncommitted changes in the target folder before it runs.

  • In code: is_git_dirty

Dirty: interactive asks to proceed; headless fails. No git or not a repo: a warning, then it runs. --force skips it. Create has no such check.

Post-template command

A shell command a template version lists, run in the target folder after files are written.

  • Do not say: hook, script

Collected from every template version in each current spec's tree, never from the previous specs.