usage: kanon install [-h] [--refresh-lock | --refresh-lock-source NAME]
                     [--reconcile] [--strict-lock] [--strict-drift]
                     [--lock-file PATH]
                     [kanonenv_path]

Execute the full Kanon install lifecycle.

Parses the .kanon configuration file, then runs repo init/envsubst/sync
for each source defined in the .kanon file. Aggregates packages into
.packages/ via symlinks.

positional arguments:
  kanonenv_path         Path to the .kanon configuration file (default: auto-
                        discover from current directory)

options:
  -h, --help            show this help message and exit
  --refresh-lock        Ignore the existing lockfile, re-resolve every
                        transitive version from scratch against the committed
                        .kanon source declarations, and overwrite .kanon.lock
                        with the new state.
  --refresh-lock-source NAME
                        Re-resolve exactly one top-level source's full chain
                        from the committed .kanon while preserving every other
                        source's lockfile entries verbatim. NAME may be a
                        source name (the KANON_SOURCE_<name> key) or a catalog
                        entry name resolved via derive_source_name.
  --reconcile           Opt in to the lenient npm-install reconcile when
                        .kanon and .kanon.lock have drifted. By default a
                        drifted pair fails fast (exit 1) without mutating the
                        lock. With this flag, kanon prunes orphaned lock
                        entries, re-resolves added or changed sources, replays
                        unchanged sources, and rewrites .kanon.lock on
                        success. Use --refresh-lock to rebuild the entire lock
                        from scratch instead.
  --strict-lock         Upgrade orphaned lock entries to a hard error in the
                        consistent state. An orphaned lock entry is a source
                        present in .kanon.lock but absent from .kanon (e.g.
                        after 'kanon remove'). Drift between .kanon and
                        .kanon.lock already fails fast by default; this flag
                        additionally fails on an orphan that survives a
                        kanon_hash match. Remediation: restore the missing
                        KANON_SOURCE_<name>_* triples in .kanon, or run with
                        --reconcile to prune.
  --strict-drift        Upgrade branch drift to a hard error in the consistent
                        state. Branch drift occurs when the lockfile records a
                        SHA for a branch-shaped source but the branch's
                        current tip on the remote is a different SHA. Without
                        this flag, the locked SHA is reused and an info-line
                        is emitted (the content pin is replayed). With this
                        flag, kanon exits with an error listing every drifted
                        source. Remediation: run 'kanon install --refresh-
                        lock-source <source>' to accept the new branch tip.
  --lock-file PATH      Path to the lock file. Defaults to <kanon-file>.lock
                        (derived from --kanon-file). The KANON_LOCK_FILE
                        environment variable is consulted when this flag is
                        absent; the CLI flag takes precedence when both are
                        set.

Example:
  kanon install           # auto-discovers .kanon
  kanon install .kanon    # explicit path
