feat: add setup-aware state management

CHANGELOG.md

@@ -6,6 +6,29 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-07-10
+
+### Added
+
+- Added `--setup <id>` as the canonical setup selector while preserving
+  `--marketplace <id>` as a backward-compatible native-format alias.
+- Added stable `list --json` setup discovery and `status [--target] [--json]`
+  inspection for missing, unmanaged, legacy-managed, and setup-aware managed
+  installations.
+- Added `BUILD-VERSION` schema 2 with a required `setup_id`, so installed and
+  backed-up trees retain the exact setup identity used to build them.
+
+### Changed
+
+- Upgraded the public product contract to version 3 and documented the setup
+  catalog, setup-selection aliases, machine-readable interfaces, and stamp
+  compatibility policy.
+- Made staged-build verification fail closed unless the schema-2 stamp setup
+  identity matches the selected setup. Legacy schema 0 and 1 stamps remain
+  readable for safe recovery operations and report an unknown setup identity.
+- Bumped the public build and `nddev-builder/core` component to 2.1.0. ZCode
+  application, CLI, runtime, and artifact identity pins are unchanged.
+
 ## [2.0.2] - 2026-07-10
 
 ### Security

README.md

@@ -2,13 +2,13 @@
 
 `nddev-zcode-app` is a reusable build system and installer for complete,
 version-stamped ZCode setups. It recreates `~/.zcode` from a selected local
-marketplace on macOS or Ubuntu, backs up the previous installation, and
+setup catalog entry on macOS or Ubuntu, backs up the previous installation, and
 selectively restores runtime state so sessions and credentials survive setup
 changes.
 
 - **Author:** Danil Silantyev (github:rldyourmnd), CEO NDDev
 - **License:** AGPL-3.0-or-later
-- **Build version:** 2.0.2
+- **Build version:** 2.1.0
 - **Verified ZCode runtime:** app 3.3.3, CLI 0.15.0, model GLM-5.2
 
 ## What this repository contains
@@ -47,8 +47,11 @@ cli-tools/scripts/install.sh bootstrap --apply
 
 # Inspect and install a setup.
 cli-tools/scripts/install.sh list
-cli-tools/scripts/install.sh install --marketplace nddev-builder --plan
-cli-tools/scripts/install.sh install --marketplace nddev-builder --apply
+cli-tools/scripts/install.sh list --json
+cli-tools/scripts/install.sh install --setup nddev-builder --plan
+cli-tools/scripts/install.sh install --setup nddev-builder --apply
+cli-tools/scripts/install.sh status
+cli-tools/scripts/install.sh status --json
 ```
 
 Plan mode performs no writes and does not invoke a locally installed `zcode`
@@ -77,8 +80,11 @@ hooks, MCP servers, or user-scope components. They take project-specific tools
 and policy from the active workspace, which keeps the profiles portable and
 their permanent context surface small.
 
-The installer copies exactly one selected marketplace into the target ZCode
-home. Marketplace content is ordinary source and can be adapted independently.
+The installer copies exactly one selected setup into the target ZCode home.
+`--setup` is the public selector; `--marketplace` remains a compatibility alias
+for the underlying ZCode-native storage format. Every new `BUILD-VERSION`
+schema-2 stamp records the selected `setup_id`, and `status` validates and
+reports it. Setup content is ordinary source and can be adapted independently.
 
 ## Backup and restore contract
 

VERSION

@@ -1 +1 @@
-2.0.2
+2.1.0

build/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "nddev-zcode-app",
-  "build_version": "2.0.2",
+  "build_version": "2.1.0",
   "source_root": "zcode_tools/marketplaces/",
-  "installer": "cli-tools/scripts/install.sh --marketplace <name>",
+  "installer": "cli-tools/scripts/install.sh install --setup <id>",
   "layout": {
-    "zcode_tools/marketplaces/<name>/": "each marketplace is a self-contained ~/.zcode setup (AGENTS.md, config templates, mcp/hooks, skills/commands/agents, plugins)",
-    "cli-tools/": "installer: --marketplace <name> selects one setup and builds ~/.zcode from it (macOS + Ubuntu)",
+    "zcode_tools/marketplaces/<name>/": "each native marketplace is a self-contained ~/.zcode setup (AGENTS.md, config templates, mcp/hooks, skills/commands/agents, plugins)",
+    "cli-tools/": "setup manager: --setup <id> selects one catalog entry and builds ~/.zcode from it (macOS + Ubuntu)",
     "build/": "build contracts: version.json, manifest.json, and the local secrets template shared across setups",
     "config/": "public repository and release contract metadata",
     "references/": "verified public ZCode compatibility baseline",
@@ -33,12 +33,21 @@
   },
   "command_option_policy": {
     "bootstrap": ["--platform", "--apply", "--plan", "--dry-run"],
-    "install": ["--marketplace", "--target", "--platform", "--apply", "--plan", "--dry-run", "--adopt-unmanaged"],
+    "install": ["--setup", "--marketplace", "--target", "--platform", "--apply", "--plan", "--dry-run", "--adopt-unmanaged"],
     "remove": ["--target", "--apply", "--plan", "--dry-run", "--keep-backup"],
     "restore": ["--slot", "--target", "--apply", "--plan", "--dry-run", "--allow-target-relocation"],
-    "list": ["-l", "--list", "--backups"],
+    "list": ["-l", "--list", "--backups", "--json"],
+    "status": ["--target", "--json"],
     "invalid_combination": "unknown, command-inapplicable, and mutually exclusive mode options are rejected instead of ignored"
   },
+  "setup_state_policy": {
+    "catalog_identity": "safe kebab-case directory id must equal marketplace.json:name",
+    "selection_option": "--setup <id>; --marketplace <id> remains a backward-compatible alias",
+    "new_stamp_schema": 2,
+    "new_stamp_identity": "BUILD-VERSION.setup_id must equal the selected setup id",
+    "legacy_recovery": "schema 0 and 1 stamps remain readable for backup, restore, remove, and status; their setup identity is reported as unknown",
+    "machine_interfaces": ["list --json", "status --json"]
+  },
   "runtime_probe_policy": {
     "resolution": "resolve and canonicalize one executable before invoking it",
     "timeout_seconds": 3,

build/version.json

@@ -1,5 +1,5 @@
 {
-  "build_version": "2.0.2",
+  "build_version": "2.1.0",
   "zcode_app_version": "3.3.3",
   "zcode_cli_version": "0.15.0",
   "zcode_runtime": "GLM-5.2",