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.
| Word | Meaning |
|---|---|
| Target folder | The folder a user runs create or update on; it holds the made files, the user's edits and the state file. |
| State file | The .cyan_state.yaml file in a target folder - one template record per stacked template, plus managed files and file clash records. |
| Template record | One stacked template's entry in the state file - an active flag, its history entries and the paths it made last run. |
| History entry | One saved run of a stacked template - version number, time, answers and a deterministic state map. |
| Stacked template | One of the templates installed into a target folder by its own create, side by side with the others. |
| Template stacking | Running every stacked template on its own and laying their file sets on top of each other, oldest history time first. |
| Template spec | One stacked template to run in a batch run - user, name, version number, answers, deterministic state and time. |
| Batch run | The shared run behind create and update - run every spec twice, stack each list, three-way merge, write, save state, run commands. |
| Three-way merge | Merging the merge base, the local set and the incoming set with git, so template changes land and user edits stay. |
| Merge base | In a three-way merge, what the stacked templates made on their last saved run, rebuilt by running them again. |
| Local set | In a three-way merge, every file in the target folder as it is now, except the state file. |
| Incoming set | In a three-way merge, what the stacked templates make now (new versions, new templates, fresh answers). |
| Merge conflict | A line both the user and the template changed; written into the file with git conflict markers for the user to fix. |
| Managed files | The sorted list of paths the stacked templates make, kept per template record and as one union in the state file. |
| 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. |
| Rerun | Create of a template the folder already has, at the same version - the answers of every stacked template are cleared. |
| Upgrade | Moving a stacked template to another version, keeping its saved answers and asking only questions they do not answer. |
| Git dirty check | Update's check for uncommitted changes in the target folder before it runs. |
| Post-template command | A 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
projectfield: 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.