docs: record transactional rebuild candidate contract

CONTEXT.md

@@ -138,6 +138,37 @@ _Avoid_: receipt status, mutable receipt
 The bounded host-local patch, preimage, or structured metadata a Mutation Receipt may reference. Evidence is distinct from the compact Mutation Ledger, follows explicit redaction and retention policy, and never enters ordinary session sharing by default. Root quotas, pagination, retention, and compaction bound both receipt metadata and evidence.
 _Avoid_: ledger blob, session attachment
 
+### Development and installation
+
+**Rebuild candidate**:
+A complete platform-specific VSIX tied to an immutable source-pair manifest and
+independently verified before installation. A candidate identifies the Amicode
+main SHA, promoted fork SHA, overlay-manifest fingerprint, target platform, UI
+channel, artifact digest, and CI provenance. It is adopted only after a matching
+health receipt; it is never a directory of files copied into a live extension.
+_Avoid_: Rebuild output, partial deploy, local binary (when the complete VSIX is
+meant)
+
+**Managed rebuild environment**:
+The user-scoped toolchain cache, source cache, and owned temporary worktrees
+used by the rebuild coordinator. It contains pinned, integrity-checked tools and
+may never alter a developer checkout, global PATH, or system package-manager
+state.
+_Avoid_: Developer checkout, global toolchain, build folder
+
+**Rebuild operation**:
+One durable user-initiated lifecycle that preflights, resolves, builds or
+downloads, verifies, adopts, rolls back, or refuses one rebuild candidate. Its
+status survives a VS Code reload and has a receipt-backed terminal outcome.
+_Avoid_: Spinner, background rebuild (when the durable operation is meant)
+
+**Promoted fork SHA**:
+The immutable fork revision recorded by the merged Amicode main overlay
+manifest. It is the only fork revision a Main rebuild may consume. A newer
+`local/amicode` head is pending-promotion information, never a rebuild source.
+_Avoid_: Latest fork head, current branch (when referring to the Main rebuild
+source)
+
 ### Fleet & serving
 
 **Server mode**:

docs/adr/0015-managed-rebuild-candidates.md

@@ -0,0 +1,64 @@
+# 0015 - Adopt complete rebuild candidates through staged VSIX installation
+
+Status: proposed (2026-09-11)
+
+Tracking: harmoniqs/amicode#1016
+
+Depends on: harmoniqs/amicode#1010
+
+## Context
+
+A developer rebuild changes extension-host code, contributed metadata, bundled
+skills and templates, the app bundle, and a host-native engine. The existing
+rebuild paths copy portions of that closure into an installed extension after
+building against ambient dependencies. They cannot verify the complete payload,
+atomically activate it, or restore a known-good version when the next extension
+activation fails.
+
+Main source identity is constrained by the promoted-overlay contract. The
+authoritative fork revision is the immutable SHA recorded by the selected
+Amicode main manifest, not the current head of `local/amicode`. Falling forward
+to a newer fork head creates a mixed, unreviewable build.
+
+## Decision
+
+Developer rebuilds produce and adopt complete, platform-specific VSIX rebuild
+candidates. Each candidate is tied to an immutable manifest containing the
+selected Amicode main SHA, promoted fork SHA, overlay-manifest fingerprint,
+upstream-base SHA, platform, UI channel, artifact digest, and CI provenance.
+
+Rebuild from Main resolves and verifies a published candidate for that exact
+promoted pair first. If no compatible candidate is available, a separately
+confirmed source fallback uses an owned temporary worktree leased by the
+Amicode main SHA and manifest-pinned fork SHA. It never changes a developer
+checkout, promotion branch, or the current fork head.
+
+Before installation, the coordinator validates the candidate payload and its
+isolated runtime. It retains the prior VSIX, launches an external watchdog,
+installs the candidate through VS Code, and reloads. The candidate becomes
+current only after it emits a matching health receipt. The watchdog restores the
+retained VSIX on a failed or missing receipt.
+
+## Considered Options
+
+1. **Complete staged VSIX candidate** - chosen. It verifies the whole runtime
+   closure and gives a recoverable activation boundary.
+2. **Incremental installed-file copying** - rejected. It leaves partial states
+   and has no trustworthy rollback path.
+3. **Resolve the newest fork head during a Main rebuild** - rejected. It
+   violates the promoted-manifest contract in #1010.
+4. **Rebuild-time overlay promotion** - rejected. It turns a consumer into a
+   cross-repository source mutator.
+5. **Dynamic extension loader** - rejected. It expands the executable-code and
+   resource-root trust boundary beyond this need.
+
+## Consequences
+
+Rebuilds become user-scoped and reproducible on macOS arm64, Linux x64, Linux
+arm64, and WSL hosts. Native Windows remains a WSL-routing surface rather than
+a native rebuild host. The rebuild system owns candidate manifests, toolchain
+pins, temporary-worktree leases, health receipts, and rollback receipts. CI
+must publish durable candidate prereleases after the promoted source pair has
+passed required gates. The existing shell entry points remain supported wrappers
+over the coordinator. The old copy bridge is retired only after successful
+candidate adoption and rollback drills.