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
| Word | Meaning |
|---|---|
| Target folder | The folder a user runs create or update on; it holds the made files and the state file. |
| State file | The .cyan_state.yaml file in a target folder - template records, managed files and file clash records. |
| Template record | One stacked template's entry in the state file - active flag, history entries and its file list. |
| 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 each stacked template on its own and laying their file sets on top of each other by history entry time. |
| Spec | One stacked template to run in a batch run - user, name, version number, answers, deterministic state and time. |
| Batch run | The run behind create and update - run every spec, stack, three-way merge, write, save state, run commands. |
| Three-way merge | Merging base (last run's output, rebuilt), local (the target folder) and incoming (this run's output) with git. |
| Base | In a three-way merge, what the stacked templates made on their last saved run, rebuilt by running them again. |
| 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. |
| Rerun | Create of a template already in the folder at the same version - the answers of every stacked template are cleared and asked again. |
| Upgrade | Moving one stacked template to another version, keeping its saved answers and asking only new questions. |
| Post-template command | A shell command a template version lists in cyan.yaml, run with sh -c in the target folder after files are written. |
Target folder
The folder a user runs create or update on; it holds the made files and the state file.
- Do not say: project, output, destination
- See: State file
Default is the current folder (run.rs:512). Not the registry's project field, which is a template's project URL.
Example: cyanprint create atomi/web ./shop - ./shop is the target folder.
State file
The .cyan_state.yaml file in a target folder - template records, managed files and file clash records.
- Do not say: client state, generation file, cyan state
- See: Template record, Managed files
Code: CyanState (cyancoordinator/src/state/models.rs:28-40). Template records are top-level keys (serde flatten), not under a templates: key.
Example:
atomi/web:active: truehistory:- version: 5time: 2026-03-01T10:00:00Zanswers: { name: { type: String, value: shop } }deterministic_states: {}files: [README.md, package.json]managed_files: [README.md, package.json]
Template record
One stacked template's entry in the state file - active flag, history entries and its file list.
- Do not say: template state
- See: History entry
Code type: TemplateState in state/models.rs:17-25. That name is also used by the prompt outcome type; say template record here.
The key is <username>/<template>.
History entry
One saved run of a stacked template - version number, time, answers and a deterministic state map.
- See: Template stacking
Code: TemplateHistoryEntry (state/models.rs:9-14). A new one is appended on each add, upgrade or rerun of that template.
The latest entry is what the next run replays. Its time orders the stack.
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. Only the state file links stacked templates.
Example: atomi/web then atomi/ci created into ./shop - two stacked templates.
Template stacking
Running each stacked template on its own and laying their file sets on top of each other by history entry time.
- Also called: client-side stacking
- Do not say: horizontal layering
- See: Dependency layering
The owner's word "client-side stacking". Code comments call it horizontal layering (run.rs:233).
Full flow: docs/domain/project-lifecycle/architecture/template-stacking.md
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
- See: Batch run
Code: TemplateSpec (update/spec.rs:15-23). Previous specs build the base; current specs build the incoming set.
Batch run
The run behind create and update - run every spec, stack, three-way merge, write, save state, run commands.
- See: Three-way merge
Code: batch_process (run.rs:103-349), phases MAP, LAYER, MERGE+WRITE.
Three-way merge
Merging base (last run's output, rebuilt), local (the target folder) and incoming (this run's output) with git.
- Also called: 3wm
- See: Merge conflict, Base
Code: GitLikeMerger (cyancoordinator/src/fs/merger.rs). Full walk-through: docs/domain/project-lifecycle/implementation/three-way-merge.md
Example: the user added a line to README.md and the template added another; both lines end up in the file.
Base
In a three-way merge, what the stacked templates made on their last saved run, rebuilt by running them again.
- Do not say: original, ours
Never stored. Built from the previous specs.
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
Not a file clash (that is between templates). There is no prompt; the markers are written to disk.
Managed files
The sorted list of paths the stacked templates make, kept per template record and as one union in the state file.
- See: State file
Code: set_managed_files (state/models.rs:52-61). Taken from template output, not from the merged folder.
Rerun
Create of a template already in the folder at the same version - the answers of every stacked template are cleared and asked again.
- Do not say: regenerate
Code: TemplateUpdateType::RerunTemplate (template/history.rs:21-26), TemplateSpecManager::reset (update/spec.rs:150-161).
Upgrade
Moving one stacked template to another version, keeping its saved answers and asking only new questions.
Via create with another version, or via update for every stacked template.
Post-template command
A shell command a template version lists in cyan.yaml, run with sh -c in the target folder after files are written.
- Do not say: hook, script
Collected from every template version in each current spec's tree. See docs/domain/project-lifecycle/implementation/post-template-commands.md