@msn-control/liftoff 0.11.2 → 0.11.3

package/docs/cli-reference.md

@@ -273,6 +273,20 @@ liftoff update --check --json
 liftoff update --approve-plan <fingerprint> --json
 ```
 
+Run update from the project root or a subdirectory: Liftoff finds the nearest
+`liftoff.manifest.json`, so `--project` is not required for that project.
+Human follow-ups omit `--project` when discovery from the invocation directory
+selects the same target, and identify the selected project separately.
+When a positional path or `--project` selects a different project, follow-ups
+keep its explicit absolute target. An inner project never substitutes for an
+explicitly selected outer project. JSON remedies remain explicitly targeted so
+they can be used outside the originating shell.
+
+After apply, the recommended validation sequence omits a directory change when
+already at the project root. From other directories, including project
+subdirectories, it retains the change to that root. Validate must succeed before
+doctor runs; Liftoff prints these instructions without executing them.
+
 `liftoff update --check` is the human-first compatibility and migration preview.
 It changes no project bytes, but saves and discloses a project-bound preview
 receipt in user-local storage outside the repository. A receipt is not approval.
@@ -280,6 +294,10 @@ receipt in user-local storage outside the repository. A receipt is not approval.
 asks for explicit approval with a negative default. Missing or stale previews
 stop with instructions to rerun check. No-op inspection requires no approval.
 
+Run check and apply as separate commands; do not join check and apply with `&&`.
+Check returns exit code 2 for an actionable preview, so a success-only shell
+chain would skip apply even though the preview was created successfully.
+
 Noninteractive apply additionally requires the exact full plan fingerprint
 through `--approve-plan`. Check and apply must share the same materialized
 checkout and user-local storage; another runner, worktree, or moved project
@@ -348,8 +366,23 @@ repository:
 An empty or relative override is an error, not a request to use the fallback.
 Unsafe paths, links/junctions, or storage inside the project or repository also
 block the update; repair the reported storage issue rather than moving a receipt
-into the project. Commands containing spaces or shell metacharacters use literal
-native-shell quoting and retain the selected project path.
+into the project. When an explicit target is needed, commands containing spaces
+or shell metacharacters use literal native-shell quoting and retain the selected
+project path.
+
+`preview-missing` means no saved preview was found for the selected project.
+It does not mean project discovery failed or that storage is damaged. A receipt
+may have been consumed or may be absent from this user-local store; run a fresh
+check, review it, then approve the matching apply plan. `preview-mismatch` also
+requires a fresh check because the saved preview no longer matches the current
+plan. Repeating the project argument does not satisfy either prerequisite.
+
+Other preview failures retain their specific diagnosis: `preview-storage` names
+a storage operation or path to repair, `preview-invalid` identifies an invalid
+receipt, `preview-unsupported` reports a format incompatibility, and
+`preview-busy` reports concurrent access. Follow the named remedy rather than
+treating every failure as a missing preview. Do not remove an active lock or
+change project files to repair preview metadata.
 
 The immutable history snapshot travels inside the project. Preview receipts and
 approval records do not: another machine, checkout, worktree, or moved project

package/docs/configuration-and-manifests.md

@@ -210,7 +210,7 @@ comparisons to infer execution safety.
 
 | Contract | Current version |
 | --- | --- |
-| CLI package version | 0.11.2 |
+| CLI package version | 0.11.3 |
 | Activation package identity | 0.11.0 |
 | Manifest write / supported reads | 7 / 2-7 for API and GenAI |
 | Normative policy | 6 |
@@ -221,12 +221,12 @@ comparisons to infer execution safety.
 | Phase graph, supersession, credential policy | 1 |
 | Assessment report and control catalog | 1 |
 
-The 0.11.2 CLI patch retains the 0.11.0 activation identity because its phase
+The 0.11.3 CLI patch retains the 0.11.0 activation identity because its phase
 semantics and graph are unchanged. Independent infrastructure provenance
-explicitly recognizes generation versions 0.11.0, 0.11.1, and 0.11.2, including
-mixed component histories; unknown releases are not automatically trusted or
-treated as compatible. The mandatory preview/approval workflow and schema-3
-update reports are breaking CLI behavior despite the patch version.
+explicitly recognizes generation versions 0.11.0, 0.11.1, 0.11.2, and 0.11.3,
+including mixed component histories; unknown releases are not automatically
+trusted or treated as compatible. The mandatory preview/approval workflow and
+schema-3 update reports remain unchanged by this patch.
 
 Known activation-v1 history remains **diagnostic-only**, not executable proof.
 Compatibility metadata v3 separately declares the exact history-preserving

package/docs/troubleshooting.md

@@ -146,6 +146,34 @@ Restore `liftoff.manifest.json` from version control or regenerate the project
 with the matching Liftoff version. Do not weaken path validation or retain a
 hand-edited unsafe path.
 
+## Update reports a missing preview
+
+`preview-missing` means Liftoff found the project but has no saved update preview
+for it in the current user-local store. It is not a requirement to repeat the
+project folder or evidence of a storage fault. From inside the project, run
+these commands separately:
+
+```bash
+liftoff update --check
+liftoff update
+```
+
+Review the preview before approving apply. Check exits 2 when it finds actionable
+work, so joining check and apply with `&&` would skip the second command.
+A previously saved preview may have been consumed; run a fresh check rather than
+assuming the earlier check is still available.
+
+Human follow-ups omit a redundant `--project` when the current directory resolves
+to the selected project. They retain an explicit target when operating on another
+project or when the caller's context cannot be established. JSON remedies keep
+explicit targets. Completion omits a redundant directory change only when
+already at the project root.
+
+A stale preview (`preview-mismatch`) also needs a fresh check and approval.
+Storage, invalid-receipt, unsupported-format, and busy-operation failures have
+their own remedies; repair the named condition instead of changing the project
+argument or deleting an active lock.
+
 ## Update reports managed-core conflicts or orphans
 
 Run `liftoff update --check` before apply. `liftoff update` requires the matching

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msn-control/liftoff",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "Interactive CLI for governed GenAI applications and APIs.",
   "type": "module",
   "license": "GPL-3.0-only",