seihou-cli-0.5.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.

  A targeted update stops if an unselected application also owns a path the
  selected applications would change. Name every required owner or run the
  no-target form; Seihou will not guess how to reconstruct an omitted layer.

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