seihou-cli-0.9.0.0: help/update.md

UPDATE

`seihou update` reconciles recorded module and recipe applications with newer
source content while preserving project-local edits. It is the routine way to
advance an existing project. `seihou run` remains the initial-generation and
explicit-reconfiguration command; `seihou upgrade` only refreshes the shared
installed cache.

BASIC WORKFLOW

  Preview every recorded application:

    seihou update --dry-run

  Update one recorded module or recipe application:

    seihou update master-plan

  Apply every recorded application in manifest order:

    seihou update

  Seihou stages newer source repositories before changing the installed cache,
  reuses the saved inputs for each module instance, plans migrations, renders
  new generated content, reconciles files, and runs only new or changed commands.
  The installed cache and manifest are published only after the managed update
  succeeds.

TARGET SELECTION

  TARGET may name a recorded module or recipe, or a module contained in a
  recorded application. Repeat TARGET to select several applications. With no
  target, every recorded application is selected.

  When a path the selected applications would change is also owned by an
  unselected one, Seihou asks whether every owner reaches that path through an
  additive, non-overlapping patch. `append-line-if-absent` and
  `append-section` occupy disjoint slices of a file, so replaying one owner
  leaves the others' lines untouched and the update proceeds -- the ordinary
  case for `.gitignore`.

  Otherwise the update stops, because regenerating the file for one owner
  would discard another's content. That covers any path an owner writes
  wholesale, and the position-dependent `append-file` / `prepend-file`
  patches. A manifest written before Seihou recorded this distinction has no
  answer and is treated conservatively. One no-target update records it: a
  missing answer counts as pending work even when nothing else has changed,
  and writing it down touches no project file.

  When the refusal is genuine, name every required owner, run the no-target
  form, or pass `--include-shared-owners` to expand the selection to exactly
  the owners required. Each added application is reported. Seihou will not
  guess how to reconstruct an omitted layer, and never broadens a named
  selection without being asked.

SAVED INPUTS

  An ordinary update reuses the exact accepted value recorded for each module
  instance. Override a value with a repeatable `--var KEY=VALUE`. A newly added
  required variable follows the normal resolution chain and may prompt in an
  interactive terminal.

  `--reconfigure` intentionally ignores saved values and resolves every input
  again. Use it to change configuration, not for routine source updates.

MIGRATIONS

  Applicable module migrations are always included. Declarative moves and
  deletes are staged so `--dry-run` can show the post-migration file plan.
  Migration shell commands are listed but cannot be simulated or rolled back
  outside Seihou's managed paths. There is no skip-migrations flag because new
  templates against an old project layout would be unsafe.

THREE-WAY FILE RECONCILIATION

  For each generated text file, Seihou compares:

    baseline    Content generated by the previous successful application
    current     Content now on disk, including user edits
    generated   Content produced from the candidate source

  If only one side changed, that change wins. Non-overlapping user and module
  changes merge automatically. Overlapping edits become a conflict with diff3
  markers labeled current, baseline, and generated. Interactive runs let the
  user choose generated content, current content, conflict markers, or abort.

  An obsolete generated file is deleted only when it is unchanged. An edited
  orphan can be retained, detached, or explicitly deleted. `--force` accepts
  permitted deterministic conflict choices but retains edited orphans; it does
  not silently delete user data. Binary content that changed on both sides
  remains a conflict.

COMMANDS

  By default, only new or changed generated commands run. `--run-all-commands`
  executes every command and `--no-commands` executes none; those flags are
  mutually exclusive. Successful command receipts are published only when the
  entire command phase succeeds.

PREVIEW, AUTOMATION, AND COMMITS

  `--dry-run` prints the complete plan without changing project files, cache,
  baselines, or manifest. `--json` emits one machine-readable JSON document and
  disables prompts. Supply required values and conflict choices in advance for
  non-interactive use.

  `--commit` commits only managed paths from a successful update.
  `--commit-message MSG` supplies the message and implies `--commit`. Neither
  commit option can be combined with `--dry-run`.

TRANSACTION SAFETY

  Before mutation, Seihou checks that the manifest, project files, and staged
  sources still match the accepted plan. Managed migrations, files, baseline
  blobs, installed-cache entries, and the manifest are protected by recovery
  journals. The manifest is the final publication marker.

  External effects from module or migration shell commands cannot be undone.
  A failure reports that limitation instead of claiming a full rollback.

LEGACY PROJECTS

  A manifest without recorded applications needs one explicit TARGET for its
  first update. That successful run seeds application identity, saved inputs,
  ownership, generated baselines, and command receipts. Ambiguous legacy values
  are reported rather than guessed.

SEE ALSO

  seihou update --help
  seihou help modules
  seihou help migrations
  seihou status --help
  docs/cli/update.md