ltcai 2.0.0 → 2.2.0

package/auto_setup.py

@@ -443,8 +443,6 @@ class Recommendation:
 _MODEL_CATALOG: List[Dict[str, Any]] = [
     # (min_ram_mb, min_vram_mb, model_id, quant, runtime_preference)
     # OS 오버헤드(~4-6 GB) + KV 캐시 여유를 감안한 보수적 RAM 임계값
-    {"ram": 128 * 1024, "vram": 48 * 1024,
-     "id": "mlx-community/gpt-oss-120b-MXFP4-Q4", "q": "mxfp4", "multimodal": False},
     {"ram": 64 * 1024, "vram": 32 * 1024,
      "id": "mlx-community/gemma-4-31b-it-4bit", "q": "4bit", "multimodal": True},
     {"ram": 64 * 1024, "vram": 32 * 1024,
@@ -452,9 +450,13 @@ _MODEL_CATALOG: List[Dict[str, Any]] = [
     {"ram": 48 * 1024, "vram": 24 * 1024,
      "id": "mlx-community/gemma-4-31b-it-4bit", "q": "4bit", "multimodal": True},
     {"ram": 32 * 1024, "vram": 16 * 1024,
-     "id": "mlx-community/gpt-oss-20b-MXFP4-Q8", "q": "mxfp4", "multimodal": False},
+     "id": "mlx-community/gemma-4-26b-a4b-it-4bit", "q": "4bit", "multimodal": True},
     {"ram": 48 * 1024, "vram": 24 * 1024,
      "id": "Qwen/Qwen3-VL-30B-A3B-Instruct", "q": "q4_K_M", "multimodal": True},
+    {"ram": 24 * 1024, "vram": 12 * 1024,
+     "id": "mlx-community/Llama-4-Scout-17B-16E-Instruct-4bit", "q": "4bit", "multimodal": True},
+    {"ram": 16 * 1024, "vram": 8 * 1024,
+     "id": "mlx-community/gemma-4-12b-it-4bit", "q": "4bit", "multimodal": True},
     {"ram": 32 * 1024, "vram": 16 * 1024,
      "id": "Qwen/Qwen3-VL-8B-Instruct", "q": "q5_K_M", "multimodal": True},
     {"ram": 24 * 1024, "vram": 12 * 1024,
@@ -466,7 +468,7 @@ _MODEL_CATALOG: List[Dict[str, Any]] = [
     {"ram":  8 * 1024, "vram": 4 * 1024,
      "id": "Qwen/Qwen3-VL-4B-Instruct", "q": "q4_K_M", "multimodal": True},
     {"ram":  4 * 1024, "vram": 0,
-     "id": "google/gemma-3-1b-it", "q": "q4_K_M", "multimodal": False},
+     "id": "Qwen/Qwen3-VL-4B-Instruct", "q": "q4_K_M", "multimodal": True},
 ]
 
 
@@ -477,8 +479,8 @@ def recommend(profile: SystemProfile) -> Recommendation:
     # backend / runtime
     if profile.os == "darwin" and profile.gpu.vendor == "apple":
         backend = "metal+mlx"
-        runtime = "mlx" if _has_module("mlx") else "llama.cpp"
-        rationale.append("Apple Silicon → Metal + MLX")
+        runtime = "mlx" if _has_module("mlx_vlm") else "llama.cpp"
+        rationale.append("Apple Silicon → Metal + MLX-VLM")
     elif profile.gpu.vendor == "nvidia" and profile.cuda_available and (profile.os == "linux" or profile.is_wsl):
         backend = "cuda"
         runtime = "vllm" if profile.gpu.vram_mb >= 12 * 1024 else "llama.cpp"
@@ -612,10 +614,10 @@ def plan(profile: SystemProfile, rec: Recommendation) -> InstallPlan:
         need("node20", "VSCode 확장 / npm CLI 부트스트랩에 필요")
 
     # 런타임별 추가
-    if rec.runtime == "mlx" and not _has_module("mlx_lm"):
+    if rec.runtime == "mlx" and not _has_module("mlx_vlm"):
         steps.append(InstallStep(
-            name="mlx-lm", why="Apple Silicon LLM 추론",
-            command=["pip3", "install", "--upgrade", "mlx-lm"],
+            name="mlx-vlm", why="Apple Silicon 멀티모달 추론",
+            command=["pip3", "install", "--upgrade", "mlx-vlm"],
         ))
     if rec.runtime in {"llama.cpp", "ollama"} and not _which("ollama"):
         need("ollama", "llama.cpp 가중치를 가장 쉽게 받는 경로")
@@ -638,18 +640,16 @@ def plan(profile: SystemProfile, rec: Recommendation) -> InstallPlan:
     model_command = ["huggingface-cli", "download", rec.model_id, "--quiet"]
     if rec.runtime == "ollama":
         lower = rec.model_id.lower()
-        if "gpt-oss-120b" in lower:
-            model_command = ["ollama", "pull", "gpt-oss:120b"]
-        elif "gpt-oss-20b" in lower:
-            model_command = ["ollama", "pull", "gpt-oss:20b"]
-        elif "gemma-4-31b" in lower:
+        if "gemma-4-31b" in lower:
             model_command = ["ollama", "pull", "hf.co/ggml-org/gemma-4-31B-it-GGUF:Q4_K_M"]
+        elif "gemma-4-12b" in lower:
+            model_command = ["ollama", "pull", "hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M"]
+        elif "llama-4-scout" in lower:
+            model_command = ["ollama", "pull", "hf.co/ggml-org/Llama-4-Scout-17B-16E-Instruct-GGUF:Q4_K_M"]
         elif "qwen3-vl-8b" in lower:
             model_command = ["ollama", "pull", "qwen3-vl:8b"]
         elif "qwen3-vl-4b" in lower:
             model_command = ["ollama", "pull", "qwen3-vl:4b"]
-        elif "gemma-3-1b" in lower:
-            model_command = ["ollama", "pull", "gemma3:1b"]
     elif rec.runtime == "lmstudio":
         model_command = ["lms", "get", rec.model_id]
     steps.append(InstallStep(
@@ -696,7 +696,7 @@ def verify(profile: SystemProfile, rec: Recommendation) -> Dict[str, Any]:
         f"{profile.disk_free_mb} MB free")
 
     if rec.runtime == "mlx":
-        add("mlx_lm import", _has_module("mlx_lm"), "Apple Silicon 런타임")
+        add("mlx_vlm import", _has_module("mlx_vlm"), "Apple Silicon 멀티모달 런타임")
     if rec.runtime in {"llama.cpp", "ollama"}:
         add("ollama binary", _which("ollama") is not None,
             _which("ollama") or "not found")

package/docs/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## [2.2.0] - 2026-06-04
+
+> Multimodal-First Knowledge OS Release — Lattice AI is aligned around the
+> Knowledge Graph, multimodal inputs, source disclosure, and Gemma-4-first model
+> recommendations.
+
+### Added
+
+- **Source disclosure metadata** — recommended model catalog entries now include
+  maker country, maker company, execution method, internet requirement, and
+  model name.
+- **Principle documents** — added root-level `PROJECT_PRINCIPLES.md`,
+  `AI_PHILOSOPHY.md`, `MODEL_POLICY.md`, `KNOWLEDGE_GRAPH.md`,
+  `RELEASE_NOTES.md`, `ARCHITECTURE.md`, and `CHANGELOG.md`.
+- **Gemma-4 default path** — default local model configuration and recommendation
+  aliases now center on Gemma 4 12B/31B multimodal models.
+
+### Changed
+
+- **README / architecture rewrite** — current docs now describe Lattice AI as an
+  AI Knowledge OS rather than a chat app or model launcher.
+- **Multimodal recommendation logic** — local recommendation catalogs and setup
+  flows use current multimodal model families only: Gemma 4, Qwen3-VL, and
+  Llama 4.
+- **Mode language** — basic and advanced modes are feature-equivalent and differ
+  by explanation level; admin mode remains the authority boundary.
+- **Runtime policy** — Apple Silicon local execution now checks MLX-VLM instead
+  of MLX-LM.
+- **Version sync** — Python package, npm package, VS Code extension, Workspace
+  OS, runtime constants, FastAPI app, and `/health` metadata aligned at `2.2.0`.
+
+### Removed
+
+- MLX-LM as a current local text-only recommendation/install path.
+- Text-only low-spec fallback recommendations.
+- Current recommendation entries for Gemma 2, Gemma 3, Qwen2.5-VL, SmolLM,
+  Phi, Mistral, DeepSeek, GPT-OSS, and Llama 3.x.
+
+### Validation
+
+- Unit tests added/updated for multimodal catalog policy, source metadata,
+  Gemma-4 aliases, and version metadata.
+- Package-store publishing remains manual; release artifacts are version-scoped
+  and must use exact filenames.
+
+## [2.1.0] - 2026-06-01
+
+> Agent Platform Maturity Release — v2.1 operationalizes the v2.0 platform
+> without redesigning it. Agent handoff, context packets, review/retry loops,
+> timeline replay, memory snapshots, planning records, marketplace templates,
+> and realtime execution observability are now first-class and additive.
+
+### Added
+
+- **Explicit agent handoff** — handoff records now include `handoff_id`,
+  source/target agent ids, reason, task summary, context packet, status, and
+  timestamps. Handoffs are workspace-scoped, persisted, inspectable, and replayable.
+- **Agent context packets** — structured transfer packets include objective,
+  task summary, workspace/graph/memory/workflow context, plugin outputs,
+  constraints, reviewer notes, and retry metadata with obvious secret fields
+  redacted before persistence.
+- **Review / retry loops** — Planner -> Executor -> Reviewer records plan review,
+  reviewer outcomes (`approve`, `reject`, `retry`), retry history, retry limits,
+  reviewer notes, and failure propagation.
+- **Timeline / replay** — agent and workflow runs expose replay support through
+  persisted frames that show actor, time, reason, input, output, and decision.
+  UI pages add replay viewers for agent and workflow runs.
+- **Agent memory and planning** — `short_term`, `workspace`, and `long_term`
+  memory scopes are supported, memory snapshots are workspace-scoped and
+  replayable, and agent plans persist with plan-review metadata.
+- **Workflow / agent / plugin hardening** — plugin output enters agent context,
+  agent output enters workflow output, retry paths are bounded, and failures
+  propagate into run status and realtime events.
+- **Marketplace foundation** — local Plugin, Workflow, and Agent templates with
+  metadata, export/import, install hooks, and a template registry. No cloud
+  marketplace service is introduced.
+- **Realtime execution observability** — existing SSE feed emits
+  `agent_started`, `handoff_created`, `handoff_accepted`, `handoff_completed`,
+  `review_requested`, `review_approved`, `retry_requested`,
+  `workflow_started`, `plugin_started`, `plugin_completed`, `execution_failed`,
+  and related workspace-scoped events.
+
+### Changed
+
+- Python package, npm package, VS Code extension, Workspace OS, FastAPI app, and
+  `/health` version metadata aligned at `2.1.0`.
+- Multi-Agent Runtime, Plugin SDK, Workflow Engine, and Realtime surface
+  versions now report `2.1.0`.
+- Platform UI pages for agents, workflows, plugins, and activity now expose
+  handoff chains, review panels, retry history, replay, templates, and plugin
+  execution visibility.
+
+### Validation
+
+- Unit coverage added for handoff/context persistence, review/retry history,
+  memory snapshots, replay, workflow-agent-plugin output propagation,
+  marketplace template install, and realtime execution events.
+- Package-store publishing remains manual; release artifacts are version-scoped.
+
 ## [2.0.0] - 2026-06-01
 
 > Agentic Workspace Platform — Lattice AI becomes a local-first **Agentic

package/docs/MULTI_AGENT_RUNTIME.md

@@ -1,19 +1,37 @@
-# Lattice AI Multi-Agent Runtime 2.0
+# Lattice AI Multi-Agent Runtime 2.1
 
-The Multi-Agent Runtime is the **orchestration layer** introduced in v2.0.0. It sits
+The Multi-Agent Runtime is the **orchestration layer** introduced in v2.0.0 and
+operationalized in v2.2.0. It sits
 *above* the v1.x single-agent state machine ([`AgentRuntime`](../latticeai/core/agent.py))
 and coordinates a pipeline of named **roles** that hand off work to one another,
-retry on a failing review, and emit a fully observable timeline.
+retry on a failing review, and emit a fully observable, replayable timeline.
 
 - **Source of truth:** `latticeai/core/multi_agent.py`
 - **HTTP surface:** `latticeai/api/agents.py`
 - **Persistence / Knowledge Graph integration:** `latticeai/core/workspace_os.py`
-  (`WorkspaceOSStore.record_agent_run`)
+  (`WorkspaceOSStore.record_agent_run`, `replay_agent_run`, `list_handoffs`)
 
 ```python
-MULTI_AGENT_VERSION = "2.0.0"
+MULTI_AGENT_VERSION = "2.2.0"
 ```
 
+## What v2.2 adds
+
+v2.2 does not replace the v2.0 runtime; it makes the runtime's operational
+objects durable and inspectable:
+
+- **Explicit handoff records**: `handoff_id`, source/target agent ids, reason,
+  task summary, context packet, status, and timestamps.
+- **Agent context packets**: objective, task summary, workspace/graph/memory/
+  workflow context, plugin outputs, constraints, reviewer notes, and retry
+  metadata with obvious secret keys redacted.
+- **Review / retry history**: reviewer outcomes normalize to `approve`,
+  `reject`, or `retry`; retry reasons, notes, counts, and limits are persisted.
+- **Planning records**: plans include a `plan_id`, ordered executable steps, and
+  plan-review metadata.
+- **Replay**: persisted runs can be replayed as frames showing actor, time,
+  reason, input, output, and decision via `/agents/api/runs/{run_id}/replay`.
+
 ## How it relates to the v1 single-agent runtime
 
 v1.x shipped a single-agent state machine — `AgentRuntime` driving

package/docs/PLUGIN_SDK.md

@@ -1,9 +1,11 @@
 # Lattice AI Plugin SDK
 
-The Plugin SDK is the v2.0.0 extension layer for the Lattice AI Agentic Workspace
-Platform. It lets you package skills, tools, workflow templates, and actions into
-one versioned, permissioned unit — a *plugin*. A plugin is a directory under the
-configured `plugins` root that ships a `plugin.json` manifest.
+The Plugin SDK is the extension layer for the Lattice AI Agentic Workspace
+Platform. v2.2.0 keeps the v2.0 plugin model and adds execution observability plus
+local marketplace-template foundations. It lets you package skills, tools,
+workflow templates, and actions into one versioned, permissioned unit — a
+*plugin*. A plugin is a directory under the configured `plugins` root that ships
+a `plugin.json` manifest.
 
 The SDK is intentionally **additive**. Plugins *extend* the existing Skill, Tool,
 and Workflow surfaces; they never replace them. Standalone skills that are already
@@ -20,9 +22,19 @@ through the existing skill registry rather than owning a parallel one.
 The host SDK version is exposed as:
 
 ```python
-PLUGIN_SDK_VERSION = "2.0.0"
+PLUGIN_SDK_VERSION = "2.2.0"
 ```
 
+## v2.2 additions
+
+- `execute_action(...)` emits `plugin_started`, `plugin_completed`, and
+  `execution_failed` through the existing Workspace OS timeline/realtime feed.
+- Plugin outputs can be carried inside agent context packets and replayed from
+  agent/workflow run history.
+- The local template catalog (`latticeai.core.marketplace`) adds Plugin,
+  Workflow, and Agent template metadata, export/import, install hooks, and a
+  template registry without introducing a cloud marketplace service.
+
 ---
 
 ## The `plugin.json` manifest
@@ -39,7 +51,7 @@ parsed and validated into an immutable `PluginManifest`.
 | `version` | string | yes | Semantic version (`^\d+\.\d+\.\d+([.-][0-9A-Za-z.]+)?$`). |
 | `description` | string | no | Short summary. |
 | `author` | string | no | Author or organization. |
-| `lattice_version` | string | no | Minimum host version this plugin requires. May be bare (`"2.0.0"`) or prefixed (`">=2.0.0"`). Empty means "any host". |
+| `lattice_version` | string | no | Minimum host version this plugin requires. May be bare (`"2.2.0"`) or prefixed (`">=2.2.0"`). Empty means "any host". |
 | `permissions` | string[] | no | Must be a subset of the [permission allow-list](#permissions). Unknown values are rejected. |
 | `provides` | object | no | What the plugin contributes. Keys must be in `("skills", "tools", "workflows", "actions")`; each value is a list of names. |
 | `entrypoint` | string | no | Reserved for an optional code entrypoint. |
@@ -193,13 +205,14 @@ identically:
 { "lattice_version": ">=2.0.0" }
 ```
 
-Examples against a host of `2.0.0`:
+Examples against a host of `2.2.0`:
 
 | Required | Compatible | Why |
 | --- | --- | --- |
 | `""` (missing) | yes | Any host. |
 | `2.0.0` / `>=2.0.0` | yes | Same major, host `>=` required. |
-| `2.1.0` | no | Host is lower than the required minimum. |
+| `2.2.0` / `>=2.2.0` | yes | Same major, exact current host. |
+| `2.3.0` | no | Host is lower than the required minimum. |
 | `1.0.0` | no | Major mismatch. |
 | `3.0.0` | no | Major mismatch. |
 

package/docs/REALTIME_COLLABORATION.md

@@ -1,8 +1,10 @@
 # Lattice AI Realtime Collaboration
 
-Realtime Collaboration is the v2.0.0 subsystem that gives a Lattice AI workspace
-a live **presence** registry and an **activity feed**. It is delivered over
-Server-Sent Events (SSE) by an in-process pub/sub bus, the
+Realtime Collaboration is the subsystem that gives a Lattice AI workspace a live
+**presence** registry and an **activity feed**. In v2.2.0 it also carries
+workspace-scoped execution observability for agents, handoffs, reviews,
+workflows, plugins, retries, and failures. It is delivered over Server-Sent
+Events (SSE) by an in-process pub/sub bus, the
 [`RealtimeBus`](../latticeai/core/realtime.py).
 
 The design goal is to surface "what is happening in the workspace right now"
@@ -10,6 +12,17 @@ The design goal is to surface "what is happening in the workspace right now"
 who is online) without adding a new transport, a new dependency, or a second
 event system.
 
+The bus version is:
+
+```python
+REALTIME_VERSION = "2.2.0"
+```
+
+v2.2 execution event types include `agent_started`, `handoff_created`,
+`handoff_accepted`, `handoff_completed`, `review_requested`, `review_approved`,
+`retry_requested`, `workflow_started`, `workflow_completed`, `plugin_started`,
+`plugin_completed`, `execution_failed`, and `execution_cancelled`.
+
 ---
 
 ## Why SSE
@@ -288,7 +301,7 @@ defaults to `50` and is clamped to the `200`-entry buffer. Returns newest-first:
 {
   "events": [ /* enriched events, newest first */ ],
   "stats": {
-    "version": "2.0.0",
+    "version": "2.2.0",
     "subscribers": 1,
     "presence": 2,
     "feed_size": 17,
@@ -312,7 +325,7 @@ Returns the scope-filtered presence registry plus the same `stats` block:
       "last_seen": "2026-06-01T10:15:30"
     }
   ],
-  "stats": { "version": "2.0.0", "subscribers": 1, "presence": 1, "feed_size": 17, "transport": "sse" }
+  "stats": { "version": "2.2.0", "subscribers": 1, "presence": 1, "feed_size": 17, "transport": "sse" }
 }
 ```
 
@@ -406,5 +419,5 @@ no client-side filtering is needed.
   on top of it, not a replacement.
 - **Single process.** The bus is in-process by design for the local-first
   deployment; it does not coordinate across multiple server processes.
-- **`stats()`** reports `version` (`2.0.0`), live `subscribers`, `presence`
+- **`stats()`** reports `version` (`2.2.0`), live `subscribers`, `presence`
   count, `feed_size`, and the `transport` (`"sse"`) for health/observability.

package/docs/V2_ARCHITECTURE.md

@@ -1,11 +1,13 @@
-# Lattice AI v2.0 Architecture — Agentic Workspace Platform
+# Lattice AI v2 Architecture — Agentic Workspace Platform
 
-Lattice AI v2.0.0 turns the local-first Workspace OS into a full **Agentic
-Workspace Platform**: a single FastAPI application in which plugins, designed
-workflows, multi-agent runs, and a realtime collaboration feed all compose over
-the same local-first JSON store and Knowledge Graph.
+Lattice AI v2.0.0 turned the local-first Workspace OS into a full **Agentic
+Workspace Platform**. v2.2.0 keeps that architecture and matures the operational
+layer: explicit handoffs, context packets, review/retry loops, memory snapshots,
+planning records, replay, marketplace templates, and realtime execution
+observability all compose over the same local-first JSON store and Knowledge
+Graph.
 
-This document describes how the four v2.0 pillars fit together, the small set of
+This document describes how the v2 platform pillars fit together, the small set of
 **additive integration seams** that wire them, the cross-integration matrix that
 results, and the compatibility surfaces that v1.x callers and data keep relying
 on. Every claim below is grounded in the shipping source:
@@ -17,21 +19,23 @@ on. Every claim below is grounded in the shipping source:
 - Workflow engine: `latticeai/core/workflow_engine.py`, `latticeai/api/workflow_designer.py`
 - Multi-Agent runtime: `latticeai/core/multi_agent.py`, `latticeai/api/agents.py`
 - Realtime bus: `latticeai/core/realtime.py`, `latticeai/api/realtime.py`
+- Marketplace foundation: `latticeai/core/marketplace.py`, `latticeai/api/marketplace.py`
 - Project conventions: `AGENTS.md`
 
-All four subsystems share the same design rules from `AGENTS.md`: dependency
+All v2 subsystems share the same design rules from `AGENTS.md`: dependency
 injection, explicit interfaces, small focused modules, registry-based dispatch,
 and composition over global state. None of them import the FastAPI app; each is
 constructed by `server_app.py` and exposed through a router factory.
 
 ---
 
-## 1. The Four v2.0 Pillars
+## 1. The v2 Platform Pillars
 
 The platform version is the single source of truth `WORKSPACE_OS_VERSION =
-"2.0.0"` (`latticeai/core/workspace_os.py`). Each pillar module re-declares the
+"2.2.0"` (`latticeai/core/workspace_os.py`). Each pillar module re-declares the
 same version for its own surface (`PLUGIN_SDK_VERSION`, `WORKFLOW_ENGINE_VERSION`,
-`MULTI_AGENT_VERSION`, `REALTIME_VERSION`).
+`MULTI_AGENT_VERSION`, `REALTIME_VERSION`) and the marketplace foundation exposes
+`MARKETPLACE_VERSION`.
 
 ### 1.1 Plugin SDK (`latticeai.core.plugins`)
 
@@ -172,6 +176,13 @@ drive an injected `workflow_runner` / `plugin_runner`), and the `reviewer`
 returns `pass` / `retry`. The reviewer can rewind the pipeline to the executor up
 to `max_retries` times; the final `status` is `ok`, `retried_ok`, or `failed`.
 
+v2.2.0 matures that orchestration with first-class `AgentHandoff` and
+`AgentContextPacket` records, structured plan review, retry history, memory
+snapshots, and replay frames. Handoffs are workspace-scoped and persisted with
+source/target agents, task summary, reason, status, timestamps, and redacted
+context so a run can be inspected after the fact instead of inferred from a flat
+log.
+
 ### 1.4 Realtime Collaboration (`latticeai.core.realtime`)
 
 An in-process pub/sub bus, presence registry, and activity feed delivered over
@@ -197,21 +208,34 @@ class RealtimeBus:
         return self.publish(event)
 ```
 
+### 1.5 Marketplace Foundation (`latticeai.core.marketplace`)
+
+v2.2.0 adds a local marketplace foundation rather than a cloud marketplace
+service. `TemplateCatalog` manages Plugin, Workflow, and Agent templates with
+metadata, export/import, install hooks, and a template registry stored through
+Workspace OS. Marketplace templates are local extension points for the existing
+Plugin SDK, Workflow Engine, and Multi-Agent Runtime; they do not bypass plugin
+permissions, workflow execution guards, or workspace scoping.
+
 ---
 
 ## 2. How the Pillars Compose Into One Platform
 
-The four pillars are not parallel silos. They are stitched into one platform by
+The v2 platform pillars are not parallel silos. They are stitched into one platform by
 exactly **three additive seams**, all introduced without changing any existing
 behavior.
 
-### Seam 1 — Two new state keys with deep-merge backfill
+### Seam 1 — Additive state keys with deep-merge backfill
 
-`WorkspaceOSStore._default_state()` adds two new top-level keys to the local-first
-JSON state: **`plugin_registry`** (an object, mirroring `skill_registry`) and
-**`workflow_runs`** (a list, alongside the existing `workflows`). The default
-state also adds v2.0 feature flags (`plugin_sdk`, `workflow_designer`,
-`multi_agent_runtime`, `realtime_collaboration`) and a `plugins` navigation area.
+`WorkspaceOSStore._default_state()` adds new top-level keys to the local-first
+JSON state, including **`plugin_registry`** (an object, mirroring
+`skill_registry`), **`workflow_runs`** (a list, alongside the existing
+`workflows`), **`handoffs`**, **`memory_snapshots`**, and
+**`template_registry`**. The default state also adds v2 feature flags
+(`plugin_sdk`, `workflow_designer`, `multi_agent_runtime`,
+`realtime_collaboration`, `agent_handoff`, `agent_context_packets`,
+`review_retry_loop`, `timeline_replay`, `marketplace_foundation`, and related
+agent memory/planning flags) plus platform navigation areas.
 
 These are safe for existing data because `load_state()` runs `_deep_merge(default,
 loaded)` on every load. `_deep_merge` walks the default tree and fills in any key
@@ -230,14 +254,14 @@ def _deep_merge(default: Any, loaded: Any) -> Any:
     return loaded
 ```
 
-A v1.x `workspace_os.json` that has no `plugin_registry` / `workflow_runs` is
-therefore upgraded *in memory* on first load — the new keys are backfilled with
-their defaults, every pre-existing snapshot, trace, memory, agent run, workflow,
-and skill entry is preserved, and the file is only rewritten on the next normal
-`save_state`. The Plugin SDK lifecycle helpers (`list_plugin_registry`,
-`set_plugin_enabled`, `mark_plugin_installed`, `mark_plugin_uninstalled`) and
-workflow-run helpers (`record_workflow_run`, `list_workflow_runs`) operate on
-these keys, deliberately mirroring the existing skill-registry contract.
+A v1.x `workspace_os.json` that has none of these newer keys is therefore
+upgraded *in memory* on first load — the new keys are backfilled with their
+defaults, every pre-existing snapshot, trace, memory, agent run, workflow, and
+skill entry is preserved, and the file is only rewritten on the next normal
+`save_state`. Plugin lifecycle helpers, workflow-run helpers, handoff helpers,
+memory snapshot helpers, and marketplace template helpers operate on these keys,
+deliberately mirroring the existing skill-registry and workflow-history
+contracts.
 
 ### Seam 2 — A single `event_sink` on `record_timeline_event`
 
@@ -277,7 +301,7 @@ behavior change.
 
 ### Seam 3 — `PlatformRuntime` as the one cross-wiring point
 
-`latticeai/services/platform_runtime.py` is the single place the four subsystems
+`latticeai/services/platform_runtime.py` is the single place the v2 subsystems
 cross-wire to one another and to the workspace. Keeping it out of `server_app`
 honours the `AGENTS.md` preference for small, composable, independently testable
 modules; `server_app` only constructs it and mounts routers.
@@ -311,7 +335,7 @@ PLATFORM = PlatformRuntime(
   factories `build_workflow_runners`, `build_orchestrator`, and
   `plugin_capability_runners` that are handed to the routers.
 
-The four routers are wired entirely through `PLATFORM`:
+The v2 routers are wired entirely through `PLATFORM`:
 
 ```python
 app.include_router(create_plugins_router(
@@ -418,9 +442,9 @@ guarantee every cross-system run terminates.
 
 ---
 
-## 5. HTTP Surface (v2.0 additions)
+## 5. HTTP Surface (v2 additions)
 
-All v2.0 routes are namespaced so they never collide with existing paths
+All v2 routes are namespaced so they never collide with existing paths
 (`/plugins/registry` vs. the marketplace `/plugins/directory`; `/workflows` vs.
 `/workspace/workflows`; `/agents` plural vs. the single-agent `/agent`).
 
@@ -435,10 +459,18 @@ All v2.0 routes are namespaced so they never collide with existing paths
 /workflows/api/definitions/{id}`, `POST /workflows/api/validate`,
 `POST /workflows/api/definitions/{id}/run`,
 `GET /workflows/api/definitions/{id}/runs`, `GET /workflows/api/runs`,
+`GET /workflows/api/runs/{run_id}/replay`,
 `GET /workflows/api/export/{id}`, `POST /workflows/api/import`.
 
 **Multi-Agent Runtime** (`latticeai/api/agents.py`): `GET /agents`,
-`GET /agents/api/roles`, `GET /agents/api/runs`, `POST /agents/api/run`.
+`GET /agents/api/roles`, `GET /agents/api/runs`,
+`GET /agents/api/runs/{run_id}/replay`, `GET /agents/api/handoffs`,
+`GET|POST /agents/api/memory/snapshots`, `POST /agents/api/run`.
+
+**Marketplace foundation** (`latticeai/api/marketplace.py`):
+`GET /marketplace/templates`, `GET /marketplace/templates/{kind}/{id}/export`,
+`POST /marketplace/templates/import`, `POST /marketplace/templates/install`,
+`GET /marketplace/templates/registry`.
 
 **Realtime Collaboration** (`latticeai/api/realtime.py`): `GET /activity`,
 `GET /realtime/stream` (SSE), `GET /realtime/feed`, `GET /realtime/presence`,
@@ -460,7 +492,7 @@ Representative run request/response (Workflow Designer):
 
 ```json
 // POST /agents/api/run
-{ "goal": "Draft v2.0 release notes", "roles": ["planner", "executor", "reviewer"], "max_retries": 2 }
+{ "goal": "Draft v2.2 release notes", "roles": ["planner", "executor", "reviewer"], "max_retries": 2 }
 ```
 
 ```json
@@ -474,7 +506,7 @@ Representative run request/response (Workflow Designer):
 
 ## 6. Compatibility
 
-> **Compatibility note.** v2.0.0 is **additive**. All v1.x data and APIs are
+> **Compatibility note.** v2.2.0 is **additive**. All v1.x and v2.0 data and APIs are
 > preserved; the platform layers new capabilities on top of unchanged surfaces.
 
 Preserved surfaces, verified against source:
@@ -482,7 +514,7 @@ Preserved surfaces, verified against source:
 - **ASGI entrypoints.** `server:app` and `latticeai.server_app.app` remain the
   application objects. `server_app.py` still exposes the module-level `app =
   FastAPI(...)` plus the `main()` / `uvicorn.run(app, ...)` entry point.
-- **Version wiring.** `WORKSPACE_OS_VERSION = "2.0.0"` drives both
+- **Version wiring.** `WORKSPACE_OS_VERSION = "2.2.0"` drives both
   `APP_VERSION` (and thus the FastAPI `app.version`) and the `/health`
   response — the health router is constructed with `app_version=APP_VERSION`.
 - **Existing routes.** Every v1.x router (`auth`, `admin`, `security_dashboard`,

package/docs/WORKFLOW_DESIGNER.md

@@ -1,11 +1,11 @@
 # Lattice AI Workflow Designer
 
-The Workflow Designer (introduced in **v2.0.0**) lets you build, validate, run,
-inspect, export, and import automations as a small **directed graph of typed
-nodes**. A workflow starts from a single `trigger` node and walks node-to-node
-to an `output`, dispatching each executable node to an injected *runner* that
-calls the real tool registry, skill registry, plugin registry, or multi-agent
-orchestrator.
+The Workflow Designer (introduced in **v2.0.0** and hardened in **v2.2.0**) lets
+you build, validate, run, inspect, replay, export, and import automations as a
+small **directed graph of typed nodes**. A workflow starts from a single
+`trigger` node and walks node-to-node to an `output`, dispatching each executable
+node to an injected *runner* that calls the real tool registry, skill registry,
+plugin registry, or multi-agent orchestrator.
 
 The execution model lives in
 [`latticeai/core/workflow_engine.py`](../latticeai/core/workflow_engine.py)
@@ -17,9 +17,19 @@ is preserved.
 The engine version is exported as:
 
 ```python
-WORKFLOW_ENGINE_VERSION = "2.0.0"
+WORKFLOW_ENGINE_VERSION = "2.2.0"
 ```
 
+## v2.2 hardening
+
+- Agent node output is captured in workflow context and can flow into a later
+  plugin or output node through `last_output`.
+- Plugin node failures mark the run failed and emit realtime execution events.
+- Workflow runs are replayable via `/workflows/api/runs/{run_id}/replay`, with
+  frames for actor, time, reason, input, output, and decision.
+- `record_workflow_run` emits `workflow_started`, `workflow_completed`, and
+  `execution_failed` events over the existing SSE activity feed.
+
 ---
 
 ## Node types
@@ -439,7 +449,7 @@ or scope), stamped with the engine version and stripped of the internal
 
 ```json
 {
-  "lattice_workflow_export": "2.0.0",
+  "lattice_workflow_export": "2.2.0",
   "name": "Daily digest",
   "nodes": [ /* ... */ ],
   "metadata": {}