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

WordMeaning
Target folderThe folder a user runs create or update on; it holds the made files and the state file.
State fileThe .cyan_state.yaml file in a target folder - template records, managed files and file clash records.
Template recordOne stacked template's entry in the state file - active flag, history entries and its file list.
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 each stacked template on its own and laying their file sets on top of each other by history entry time.
SpecOne stacked template to run in a batch run - user, name, version number, answers, deterministic state and time.
Batch runThe run behind create and update - run every spec, stack, three-way merge, write, save state, run commands.
Three-way mergeMerging base (last run's output, rebuilt), local (the target folder) and incoming (this run's output) with git.
BaseIn a three-way merge, what the stacked templates made on their last saved run, rebuilt by running them again.
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.
RerunCreate of a template already in the folder at the same version - the answers of every stacked template are cleared and asked again.
UpgradeMoving one stacked template to another version, keeping its saved answers and asking only new questions.
Post-template commandA 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:

yamlyaml
atomi/web:
active: true
history:
- version: 5
time: 2026-03-01T10:00:00Z
answers: { 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