@msn-control/liftoff 0.7.0 → 0.8.0

package/docs/cli-reference.md

@@ -5,6 +5,7 @@ Run `liftoff help` or command-specific help for the authoritative syntax:
 ```bash
 liftoff init --help
 liftoff migrate --help
+liftoff upgrade --help
 liftoff update --help
 ```
 
@@ -14,7 +15,7 @@ duplicates, and extra positional arguments fail before generation.
 ## Lifecycle
 
 ```text
-plan -> init or migrate -> validate and doctor -> update -> dev and infra helpers
+install -> upgrade CLI -> plan -> init or migrate -> validate and doctor -> update project -> dev and infra helpers
 ```
 
 | Command | Behavior |
@@ -24,6 +25,8 @@ plan -> init or migrate -> validate and doctor -> update -> dev and infra helper
 | `liftoff migrate <source>` | Creates a new sibling scaffold and filtered source copy without changing the source |
 | `liftoff validate [project]` | Validates manifest identity, durable files, workload metadata, and framework markers |
 | `liftoff doctor [project]` | Runs read-only workload-derived project and workstation diagnostics |
+| `liftoff upgrade` | Replaces a verified global npm installation with the exact canonical stable release exposed by the configured registry |
+| `liftoff upgrade --check` | Checks installation origin and registry parity without installing; exits 2 when an installable update exists |
 | `liftoff update [project]` | Applies safe managed drift immediately, preserves unforced conflicts and orphans, and records the resulting manifest |
 | `liftoff update --check` | Reports drift without preflight or mutation; exits 0 when clean and 2 when drift exists |
 | `liftoff update --force` | Applies safe changes and overwrites only the exact guarded conflicts reported by update |
@@ -38,6 +41,11 @@ plan -> init or migrate -> validate and doctor -> update -> dev and infra helper
 The former `liftoff create` command is intentionally rejected with guidance to
 use `liftoff init`; there is no compatibility alias.
 
+Generation, validation, doctor, and update consume the packaged
+[supported-stack baseline](supported-stack.md). The current contract uses
+Node.js 24 LTS, Python 3.14, Go 1.27, OpenTofu 1.12, OpenSpec 1.11, and Spec Kit
+1.0 release lines; these commands never resolve mutable latest versions.
+
 ## Planning and initialization options
 
 Common noninteractive inputs include:
@@ -53,6 +61,7 @@ Common noninteractive inputs include:
 --spec openspec|spec-kit
 --agents copilot,claude
 --default-agent copilot|claude
+--governance single-maintainer-gitflow|none
 --code-apps-plugin | --no-code-apps-plugin
 ```
 
@@ -60,6 +69,44 @@ Power Apps rejects API, pattern, cloud, region, frontend, and API environment
 options rather than ignoring them.
 
 Consent options are documented in [safety and consent](safety-and-consent.md).
+Repository governance defaults to `single-maintainer-gitflow`. It generates a
+local policy handoff only; `none` omits it. See
+[repository governance](repository-governance.md).
+
+## CLI upgrade modes
+
+```bash
+liftoff upgrade
+liftoff upgrade --check
+liftoff upgrade --json
+liftoff upgrade --check --json
+```
+
+`liftoff upgrade` is an imperative request to replace the supported global npm
+installation of `@msn-control/liftoff`; it does not prompt or accept `--yes`,
+`--force`, `--install-tools`, project paths, or project dependency flags.
+Automatic replacement is refused for local dependencies, `npx` execution-cache
+copies, linked checkouts, unknown package-manager stores, ambiguous roots, or
+unsafe paths.
+
+Canonical npm's stable `latest` metadata selects one exact target. The effective
+configured npm registry remains the delivery path and must expose that exact
+version. Liftoff never edits `.npmrc`, embeds registry credentials, forces a
+canonical bypass around a stale mirror, invokes elevation, installs a
+prerelease, or performs a downgrade.
+
+`--check` performs the same origin, target, and parity checks without invoking
+installation. Apply uses one shell-free exact npm command with lifecycle scripts,
+audit, and funding prompts disabled, then verifies installed metadata, the
+confined binary, and exact `Liftoff <version>` output. A failed install or
+verification is not automatically rolled back; use the exact-version repair
+command printed by Liftoff.
+
+JSON results use schema version 1 and expose only `mode`, `status`,
+`currentVersion`, applicable `targetVersion`, applicable `registryKind`, and a
+stable `reasonCode`. Status is one of `current`, `update-available`, `upgraded`,
+`blocked`, or `failed`. Child progress goes to stderr so stdout remains one JSON
+object.
 
 ## Update modes
 
@@ -75,6 +122,9 @@ Plain `liftoff update` is imperative and prompt-free. It applies safe new,
 missing, untouched-upgrade, clean-move, and recorded-state changes in
 interactive terminals, redirected streams, and automation. Local or user-owned
 conflicts are skipped and reported. Orphans are reported without deletion.
+During legacy governance adoption, preserved unrecorded conflicts remain
+outside manifest ownership and set local state to `handoff-partial` until a
+later update can write or byte-identically adopt every required artifact.
 
 Use `--check` whenever no project bytes may change. Human check mode prints each
 drift state and recommends plain update for safe changes or a reviewed
@@ -92,6 +142,10 @@ stack, GenAI pattern, framework, selected-agent, or user-supplied Power Apps
 starter identity changes, and it cannot bypass project-boundary, symlink,
 structural-collision, or manifest guards.
 
+For a breaking supported-stack release, inspect `liftoff update --check` before
+plain update. Restore an unwanted applied migration through version control;
+running an older CLI is not a supported automatic downgrade.
+
 ### Migration from 0.6.x
 
 The `--apply` flag was removed in 0.7.0. These are historical 0.6.x commands,
@@ -113,6 +167,8 @@ Machine-readable maintenance contracts bypass decorative presentation:
 ```bash
 liftoff validate --json
 liftoff doctor --json
+liftoff upgrade --json
+liftoff upgrade --check --json
 liftoff update --json
 liftoff update --check --json
 ```
@@ -125,7 +181,8 @@ Exit codes:
 
 - `0`: success or a clean check.
 - `1`: invalid input, unsafe state, or command failure.
-- `2`: explicit update check mode found drift.
+- `2`: an explicit update check found project drift, or upgrade check found an
+  installable CLI release.
 
 Raw installer, framework, and dependency child stdout and stderr are forwarded
 unchanged.

package/docs/configuration-and-manifests.md

@@ -24,6 +24,7 @@ A Power Apps configuration contains only applicable fields:
   "projectType": "power-apps-code-app",
   "specWorkflow": "openspec",
   "agents": ["github-copilot"],
+  "governanceProfile": "single-maintainer-gitflow",
   "codeAppsPlugin": false
 }
 ```
@@ -33,7 +34,7 @@ workload rather than silently ignored.
 
 ## `liftoff.manifest.json`: CLI-owned compatibility record
 
-New projects use manifest schema v4. Its common project identity includes the
+New projects use manifest schema v5. Its common project identity includes the
 name, spec workflow, selected agents, and applicable Spec Kit default. A
 discriminated `project.workload` object contains only fields valid for one
 workload:
@@ -50,6 +51,8 @@ The manifest also records:
 - Durable artifact logical names.
 - OS-neutral path-part arrays.
 - `sha256:` content hashes.
+- Repository governance profile, policy version, and local
+  `handoff-generated`, `handoff-partial`, or disabled state.
 
 Power Apps source identity uses explicit repository, path, and 40-character
 commit fields. It is not inferred from mutable URLs or generated file paths.
@@ -60,16 +63,21 @@ paths, or hashes.
 
 ## Compatibility
 
-Readers support schemas v2, v3, and v4:
+Readers support schemas v2, v3, v4, and v5:
 
 - V2 normalizes the legacy flat API identity and records framework state as
   uncertain without inventing agents.
 - V3 normalizes flat GenAI or API identity plus framework and agent metadata.
 - V4 represents the discriminated workload model, including Power Apps.
+- V5 adds repository-governance handoff identity without claiming live
+  enforcement.
 
 `liftoff update --check`, including `--check --json`, leaves an old manifest
-byte-for-byte unchanged. A successful plain update writes v4 only after the
-file transaction succeeds. Skipped conflicts retain their recorded hashes.
+byte-for-byte unchanged. A successful plain update writes v5 only after the
+file transaction succeeds. Previously recorded skipped conflicts retain their
+hashes. A preserved unrecorded governance conflict has no artifact entry and
+sets the update-written manifest to `handoff-partial`; resolving every such
+conflict promotes the next manifest to `handoff-generated`.
 
 ## Artifact ownership
 
@@ -88,7 +96,7 @@ can follow their own lifecycle.
 
 ## Contract conventions
 
-- Writers use `artifactVersion` 4; readers support v2, v3, and v4.
+- Writers use `artifactVersion` 5; readers support v2, v3, v4, and v5.
 - Artifact logical names and catalog identifiers are append-only.
 - Rendering is deterministic and does not depend on timestamps, host versions,
   or network state.

package/docs/existing-repositories.md

@@ -74,6 +74,27 @@ automation, while preserving conflicts and orphans. Review every reported
 conflict and commit or copy local work before choosing `liftoff update --force`.
 For CI drift gates, use `liftoff update --check --json`.
 
+Projects created before manifest schema v5 automatically preview the default
+repository-governance handoff as new named drift. Plain update safely adopts
+collision-free policy, context, guide, and selected-agent launchers without
+rewriting a configuration that omitted `governanceProfile`. Existing different
+files remain unowned conflicts and the v5 manifest records `handoff-partial`.
+Resolving every conflict promotes a later update to `handoff-generated`.
+Selecting `none` leaves previously managed handoff files as undeleted orphans
+while unrecorded conflicts remain user-owned. No update mode runs an agent or
+activates GitHub settings.
+
+Major supported-stack releases can report many runtime, lock, Docker, provider,
+and framework artifact changes at once. Treat those releases as breaking:
+commit or copy local work, inspect `liftoff update --check`, and apply only after
+reviewing all upgrades and conflicts. Plain update preserves conflicting local
+bytes and never requires `--force` as the default migration path.
+
+If an applied baseline migration must be reversed, restore the project and
+manifest through version control and reinstall from the restored locks. Liftoff
+does not automatically downgrade generated dependencies and retains no backup
+after a successful update.
+
 ## Existing non-Liftoff application
 
 Use migration when you want a fresh governed scaffold and a filtered source

package/docs/getting-started.md

@@ -5,8 +5,8 @@ standard APIs, and Power Apps code apps.
 
 ## 1. Install the CLI
 
-Liftoff requires Node.js 20.19 or newer. Power Apps code app projects require
-Node.js 22.12 or newer for their generated framework.
+Liftoff and generated Node.js workloads require Node.js 24.20 or newer.
+Python workloads use Python 3.14 with frozen `uv` dependency locks.
 
 The canonical release registry is `https://registry.npmjs.org`:
 
@@ -23,6 +23,18 @@ canonical npm. Stop if the mirror is older or rejects the explicit current
 version; ask the mirror owner to synchronize or approve the release. Liftoff
 does not modify `.npmrc` or bypass registry policy.
 
+Versions predating the self-upgrade command require that manual global install
+once. After a capable version is installed globally with npm, use:
+
+```bash
+liftoff upgrade --check
+liftoff upgrade
+```
+
+`upgrade` replaces only the supported global CLI installation. It does not read
+or update a generated project; inspect project template changes separately with
+`liftoff update --check`.
+
 See [prerequisites](prerequisites.md) for the complete plan-derived tool model.
 
 ## 2. Start interactive initialization
@@ -37,16 +49,20 @@ The guided flow asks for:
 
 1. Project identity and workload: GenAI, API, or Power Apps code app.
 2. Only the architecture choices applicable to that workload.
-3. OpenSpec or Spec Kit.
-4. One or both coding agents. On a real TTY, Space toggles agents and Enter
+3. Whether to generate the default single-maintainer GitFlow repository-
+   governance handoff. Accepting it creates local files only.
+4. OpenSpec or Spec Kit.
+5. One or both coding agents. On a real TTY, Space toggles agents and Enter
    confirms the selection.
-5. A Spec Kit default agent when both agents are selected.
-6. The optional Preview Code Apps plugin preference for Power Apps projects.
-7. Plan confirmation, workstation readiness, and any separate install or
+6. A Spec Kit default agent when both agents are selected.
+7. The optional Preview Code Apps plugin preference for Power Apps projects.
+8. Plan confirmation, workstation readiness, and any separate install or
    overwrite permissions that are needed.
 
 Liftoff renders into temporary staging, runs the official framework initializer
 there, validates the complete result, and only then merges it into the target.
+Governance activation is a later selected-agent action after commit and push;
+see [repository governance](repository-governance.md).
 
 ## 3. Understand the target
 

package/docs/prerequisites.md

@@ -6,13 +6,21 @@ and a Go API is not asked to install Python.
 
 ## Baseline
 
-- Liftoff CLI: Node.js 20.19 or newer.
-- Power Apps code app: Node.js 22.12 or newer.
-- Selected framework: the Liftoff-tested OpenSpec or Spec Kit contract.
+- Liftoff CLI and generated Node.js workloads: Node.js 24.20 or newer.
+- Python projects: Python 3.14 and `uv` 0.12.7 or newer.
+- Go projects: Go 1.27 or newer.
+- Generated Azure infrastructure: OpenTofu 1.12.6 or newer.
+- Selected framework: OpenSpec 1.11.0 or Spec Kit 1.0.1 exactly.
 - Selected agents: GitHub Copilot, Claude Code, or both.
 
+Automatic `liftoff upgrade` additionally requires that the running canonical
+`@msn-control/liftoff` package is a normal global npm installation beneath
+`npm root --global`. Local dependencies, `npx` cache copies, linked checkouts,
+and other package-manager stores use the documented manual global npm command
+instead. Liftoff never requests elevation.
+
 API workloads additionally require their selected Python, Node.js, or Go
-runtime. GenAI uses Python 3.12 and the Python/FastAPI/PydanticAI stack.
+runtime. GenAI uses Python 3.14 and the Python/FastAPI/PydanticAI stack.
 
 ## Blocking and advisory checks
 
@@ -32,6 +40,11 @@ Advisory checks describe useful but deferrable capabilities:
 Authentication checks are read-only. Liftoff never stores credentials or signs
 in to a cloud or agent on your behalf.
 
+The default repository-governance handoff has no additional initialization
+prerequisite. `gh`, a remote, licensed GitHub security features, private runners,
+Slack, and deployment access are discovered only during post-push Phase 0 and
+may be reported as gaps; they do not block local generation.
+
 ## Preview requirements without writes
 
 `liftoff plan` shows both generated artifacts and workstation requirements
@@ -76,6 +89,19 @@ the project is ready.
 GenAI and API projects use their generated stack-native locked dependency
 commands.
 
+Python projects use the generated lock without resolving new versions:
+
+```bash
+uv sync --frozen --project backend --extra test
+```
+
+Worker-enabled GenAI projects add `--extra functions`. Node.js projects use
+`npm ci`, and Go projects use `go mod download`.
+
+Liftoff's npm locks are generated with npm 12.0.2 and verified in the supported
+compatibility lanes. Do not replace a committed lock with an install from
+open-ended manifest ranges.
+
 ## Power Apps local CLI
 
 The Power Apps CLI is supplied by the generated project dependency graph.

package/docs/project-structure.md

@@ -14,7 +14,13 @@ project/
 |-- .env.example
 |-- Dockerfile
 |-- docker-compose.yml
+|-- .liftoff/
+|   `-- governance/             # durable local handoff when enabled
+|       |-- policy.md
+|       |-- context.json
+|       `-- README.md
 |-- backend/
+|   `-- uv.lock                 # Python stacks only
 |-- database/
 |   |-- alembic.ini or stack-native migration config
 |   |-- migrations/
@@ -26,7 +32,10 @@ project/
 |-- infrastructure/
 |   `-- opentofu/
 |       `-- azure/
+|           `-- .terraform.lock.hcl
 |-- openspec/ or .specify/
+|-- .github/prompts/liftoff-repository-governance.prompt.md
+|   or .claude/commands/liftoff-repository-governance.md
 |-- frontend/                  # only when selected
 |-- functions/<worker-name>/  # only for worker-enabled GenAI patterns
 `-- migration/legacy/         # only after liftoff migrate
@@ -45,7 +54,11 @@ project/
   Functions settings when a worker is generated.
 - `docker-compose.yml` starts the selected backend, PostgreSQL, Redis,
   Azurite, and Mailpit. GenAI projects use pgvector where needed and include an
-  optional Langfuse profile.
+  optional Langfuse v4 web/worker profile backed by ClickHouse, dedicated Redis,
+  and MinIO.
+- Python Docker builds export the committed `uv.lock` in frozen mode and install
+  only hash-verified requirements. `UV_DEFAULT_INDEX` can select a
+  credential-free managed mirror without changing the lock.
 - `infrastructure/opentofu/azure` contains modules, environment tfvars, local
   state configuration, and a remote-state example.
 - `openspec` is created for OpenSpec. `.specify` and `specs` are created for
@@ -87,6 +100,12 @@ project/
 `-- openspec/ or .specify/
 ```
 
+The exact selected-agent governance launcher is generated only when the
+repository-governance profile is enabled. It is Liftoff-owned; neighboring
+framework files remain framework-owned. Agent-created governance changes and
+`governance/activation-baseline.json` remain user-owned and are not listed in
+the manifest.
+
 This root follows the pinned official Microsoft starter. It includes the
 Power Apps SDK, Vite plugin, and project-local CLI through locked npm
 dependencies.

package/docs/repository-governance.md

@@ -0,0 +1,91 @@
+# Repository governance handoff
+
+Repository governance is a common Liftoff project choice. The default
+`single-maintainer-gitflow` profile generates a deterministic local handoff;
+`none` opts out:
+
+**Local handoff generated; live enforcement is not active.**
+
+```bash
+liftoff plan --governance single-maintainer-gitflow
+liftoff init --governance none
+```
+
+Accepting the default or passing `--yes` authorizes only local project files. It
+does not run an agent, mutate Git, contact GitHub, configure security, install a
+ruleset, deploy, or create monitoring.
+
+## Generated files
+
+An enabled profile adds durable, hash-managed artifacts:
+
+```text
+.liftoff/governance/policy.md
+.liftoff/governance/context.json
+.liftoff/governance/README.md
+.github/prompts/liftoff-repository-governance.prompt.md  # Copilot selected
+.claude/commands/liftoff-repository-governance.md        # Claude selected
+```
+
+The complete canonical policy is also packaged with Liftoff at
+[`assets/governance/single-maintainer-gitflow/policy.md`](../assets/governance/single-maintainer-gitflow/policy.md).
+It covers GitFlow, zero-human-approval repository rules, designated security
+tools, fail-closed checks, immutable release evidence, build-once promotion,
+deployment and rollback, monitoring and health, DORA metrics, ruleset
+sequencing, negative tests, documentation, and workload adaptation.
+
+`context.json` contains generated project facts only. GitHub repository state,
+runner access, licensed features, deployments, monitoring, alert routes,
+traffic, and rollout capabilities remain `undiscovered`. Power Apps context
+explicitly marks Liftoff backend, Docker, OpenTofu, custom container promotion,
+and API DAST as inapplicable.
+
+## Activate after commit and push
+
+1. Review the policy and context.
+2. Commit the project and push it to the intended GitHub repository.
+3. Run `/liftoff-repository-governance` with a selected agent.
+4. The agent performs read-only Phase 0 and reports repository identity,
+   artifacts, working commands, refs, workflows and exact checks, rulesets,
+   releases, environments, security, runners, deployments, monitoring, alerts,
+   health depth, platform capabilities, gaps, and inapplicable controls.
+5. The agent proposes the current `main` SHA as the activation baseline,
+   presents an ordered plan, and stops.
+6. Explicitly approve or revise the conversational plan. This is not a human
+   merge or deployment approval gate.
+7. After approval, the agent creates a new OpenSpec or Spec Kit governance
+   change, proves required contexts green and deliberately red, applies
+   repository-scoped rulesets last, and reads live enforcement back.
+
+The user-owned `governance/activation-baseline.json` is created only after
+approval. Liftoff never owns or recreates it or the agent-created governance
+change. Complete local handoffs say `handoff-generated`, partial adoptions say
+`handoff-partial`, and neither state means `active`.
+
+## Existing projects
+
+Configurations without `governanceProfile` normalize to the enabled default
+without rewriting `liftoff.config.json`:
+
+```bash
+liftoff update --check
+liftoff update
+```
+
+Check mode previews the schema-v5 manifest and new named artifacts without
+writing. Plain update applies collision-free files; differing existing files
+remain conflicts unless individually reviewed with `--force`. An unrecorded
+conflict remains outside Liftoff ownership and produces `handoff-partial`.
+After every conflict is removed or matches the current artifact, the next
+update records the full artifact set as `handoff-generated`.
+
+Setting `"governanceProfile": "none"` stops future rendering. Previously managed
+handoff files are reported once as orphans and left on disk; Liftoff never
+deletes them automatically or changes live repository settings.
+
+## Capability gaps
+
+Phase 0 must report missing GitHub licenses, private runners, staging access,
+monitoring routes, parallel-version mechanisms, or statistically meaningful
+canary traffic. It must mark controls inapplicable or blocked rather than
+creating a skipped, hanging, duplicate, or success-shaped placeholder.

package/docs/safety-and-consent.md

@@ -14,6 +14,29 @@ project dependencies. No one permission implies another.
 
 Interactive sessions ask separately at the point each permission is needed.
 
+Selecting repository governance or passing `--yes` authorizes only deterministic
+local handoff files. It never authorizes agent execution, Git mutation, GitHub
+APIs, rulesets, security configuration, deployment, monitoring, file
+replacement, machine tools, or project dependencies. Live activation begins
+only after commit, push, read-only Phase 0, and explicit plan approval.
+
+## CLI self-upgrade boundary
+
+`liftoff upgrade` is itself the narrow authorization to replace a supported
+global npm installation with one exact stable version. It accepts no project
+path, `--yes`, `--force`, tool-install, or dependency-install permission.
+`liftoff upgrade --check` is read-only and invokes no npm installation.
+
+Both modes operate from a temporary neutral directory so a project `.npmrc`
+cannot redirect machine-level discovery. Canonical npm selects the target while
+the configured registry must provide that exact release. Liftoff does not expose
+registry credentials, rewrite npm configuration, bypass a stale mirror, invoke
+`sudo` or another elevation mechanism, or touch project files.
+
+npm replacement is not a Liftoff file transaction. If npm or post-install
+verification fails, Liftoff reports an exact-version repair command and does not
+claim automatic rollback.
+
 ## Staged initialization
 
 Initialization does not write generated files directly into the destination.
@@ -77,6 +100,8 @@ Update mode is selected explicitly rather than from terminal interactivity:
 - Default update skips conflicts and lists them by portable relative path.
   After reviewing every listed overwrite, `liftoff update --force` extends the
   transaction only to those guarded conflicts.
+- Unrecorded governance conflicts remain outside manifest ownership and produce
+  `handoff-partial` until a later update safely writes or adopts every artifact.
 - Orphans are reported and left on disk for manual review.
 - Dependency definitions may be updated, but update never installs
   dependencies.

package/docs/spec-workflows-and-agents.md

@@ -7,8 +7,8 @@ Liftoff workload.
 
 ### OpenSpec
 
-OpenSpec organizes proposed behavior changes as reviewable artifacts before
-implementation. Liftoff runs the pinned official OpenSpec initializer in
+OpenSpec 1.11.0 organizes proposed behavior changes as reviewable artifacts
+before implementation. Liftoff runs that pinned official initializer in
 temporary staging and passes every selected coding agent in stable order.
 
 Generated projects contain `openspec/` plus the selected agent integration
@@ -16,10 +16,9 @@ markers.
 
 ### Spec Kit
 
-Spec Kit provides a specification, planning, and implementation workflow.
-Liftoff initializes the selected default coding agent first, adds every
-secondary integration, and records the default separately from the full agent
-set.
+Spec Kit 1.0.1 provides a specification, planning, and implementation workflow.
+Liftoff initializes the selected default coding agent first, adds every secondary
+integration, and records the default separately from the full agent set.
 
 Generated projects contain `.specify/`, `specs/`, and the selected agent
 integration markers.
@@ -66,6 +65,20 @@ Framework files remain owned by the official initializer. Liftoff validates
 them but excludes framework-owned output from durable artifact hashes so a
 framework can manage its own lifecycle.
 
+Repository-governance launchers are separate durable Liftoff files at the exact
+Copilot prompt and Claude command paths documented in
+[repository governance](repository-governance.md). They reference one canonical
+policy and context rather than duplicating framework-owned content. After
+read-only Phase 0 and explicit approval, the agent creates a new change using
+the selected framework; Liftoff never pre-creates or restores that change.
+
+Install the exact selected framework release with its supported package manager:
+
+```bash
+npm install -g @fission-ai/openspec@1.11.0
+uv tool install specify-cli==1.0.1
+```
+
 ## Optional Code Apps plugin
 
 Power Apps projects can request Microsoft's

package/docs/supported-stack.md

@@ -0,0 +1,89 @@
+# Supported stack baseline
+
+Each Liftoff release packages one tested dependency baseline in
+`assets/supported-stack.json`. Project generation and update use that committed
+file; they never resolve mutable `latest` versions.
+
+## Runtime and framework baseline
+
+| Surface | Tested release |
+| --- | --- |
+| Node.js | 24.20.0 LTS |
+| npm | 12.0.2 |
+| Python | 3.14.7 |
+| `uv` | 0.12.7 |
+| Go | 1.27.0 |
+| OpenTofu | 1.12.6 |
+| OpenSpec | 1.11.0 |
+| Spec Kit | 1.0.1 |
+| AzureRM provider | 5.3.0 |
+| Power Apps SDK | 1.2.7 |
+
+Power Apps SDK 1.2.7 is an explicit compatibility selection. Versions 1.2.12
+and newer remove the project-local `power-apps` CLI required by Liftoff's
+current workload contract. Moving to Microsoft's global `pa` CLI is a separate
+reviewed workload migration; the freshness check recognizes only the recorded
+1.3.0 exclusion and will reopen the decision when a newer candidate appears.
+
+Generated npm projects include `package-lock.json`. Python projects include
+`uv.lock` and use `uv sync --frozen`. Go projects include `go.mod` and
+`go.sum`. Generated OpenTofu includes a multi-platform `.terraform.lock.hcl`.
+
+Container references include a readable stable tag and an immutable
+multi-architecture digest. The optional Langfuse profile uses the v4 web and
+worker services with pinned ClickHouse, Redis, and MinIO dependencies.
+
+## Refresh policy
+
+Maintainers compare the committed baseline with canonical ecosystem sources:
+
+```bash
+npm run check:supported-stack
+npm run check:supported-stack-freshness
+```
+
+The first command verifies that package manifests and lockfiles match the
+committed baseline. The second is a networked, fail-closed freshness check.
+A newer release is not promoted automatically: update manifests and source for
+compatibility, regenerate ecosystem-native locks, review immutable image
+digests and upstream provenance, then run:
+
+```bash
+npm run refresh:supported-stack
+npm run check
+npm run verify:standard-node-templates
+npm run verify:power-apps-starter
+```
+
+Power Apps source is refreshed only through its reviewed immutable upstream
+commit workflow. Do not edit Microsoft-owned starter files independently.
+
+## Existing generated projects
+
+Upgrade the globally installed Liftoff CLI, then inspect project-managed changes
+as a separate operation:
+
+```bash
+liftoff upgrade --check
+liftoff upgrade
+liftoff update --check
+liftoff update
+liftoff validate
+liftoff doctor
+```
+
+Untouched managed files and new lockfiles can be updated automatically.
+Locally modified files remain conflicts unless explicitly reviewed with
+`liftoff update --force`. Liftoff never installs the updated project
+dependencies during `update`; run the generated `npm ci`, `uv sync --frozen`,
+or `go mod download` command afterward. CLI upgrade does not discover or modify
+the project.
+
+This baseline is a breaking release boundary: it raises the Node.js, Python, Go,
+and OpenTofu floors and includes major framework, provider, frontend, container,
+and dependency migrations. Commit or otherwise preserve local work, run
+`liftoff update --check`, and review every named upgrade and conflict before
+applying. Do not use an older Liftoff release as an automatic downgrade tool.
+After a successful update, recover unwanted changes through version control and
+then reinstall from the restored locks; Liftoff does not retain a post-success
+backup.

package/docs/telemetry.md

@@ -24,6 +24,12 @@ code. It is an exit-status class, not an error diagnosis. Help requests are
 recorded as `help`, and rejected input that never resolves to a recognized
 command is not recorded.
 
+`upgrade` is recorded only as the aggregate command value. Check/apply mode,
+target or configured-registry details, installation origin, paths, npm output,
+reason codes, and errors are not added. The replacement binary's verification
+process runs with telemetry and disclosure disabled, so at most the originally
+invoked parent command emits an event.
+
 Liftoff does **not** send:
 
 - An installation, user, device, or session identifier.