@@ -10,6 +10,12 @@
 # Distributable disk images (produced by scripts/make-dmg.sh)
 /*.dmg
 
+# Agent Sketch runtime state — per-workspace (autosaved session, sketches, exported runs); not source
+/.atompp/
+
+# Unsigned app artifacts pulled from the release CI and signed locally (see docs/RELEASING.md §7)
+/UNSIGNED-*.app.zip
+
 # Node / OS noise
 node_modules/
 .DS_Store
 
@@ -0,0 +1,163 @@
+# Atom++ — Agent Run Persistence → Cloud Sync (design + monetization)
+
+> **Status:** free local baseline **shipped** (SK1.2) · cloud sync **designed, not built**
+> **Date:** 2026-07-02 · **Owner:** Sergii Demianchuk
+> **One line:** an agentic run costs real money; losing it on a reload is unacceptable. Make local
+> durability **free and automatic**, and sell the **cloud layer** (cross-device sync, a durable
+> searchable run archive, cost analytics, team sharing) — never inference. This stays true to
+> Atom++'s BYOK-primary rule: [[atompp-cloud-byok-primary]].
+
+---
+
+## 1. The problem
+
+Agent Sketch (and the chat agent) can burn **real, user-billed tokens** on a long multi-agent run —
+the "Design a Key-Value Store" template alone is 11 agents, easily dollars per run. Yet the run's
+value — every node's **output text, token counts, and cost** — lived only in the webview's memory
+(`outputsByNode` / `usageByNode`). Worse, an *unsaved* sketch's **graph** was also memory-only. So:
+
+> Build a flow → run it (spend $2) → reopen the folder (or the window reloads) → **the graph and
+> every result are gone.** The money is spent; the work is not recoverable.
+
+`retainContextWhenHidden` survives a tab-hide, **not** a window/folder reload. This is the single
+most trust-damaging failure mode in the feature, and it's the natural wedge for a sync subscription —
+but only if we get the free/paid line right (§4).
+
+---
+
+## 2. The free local baseline (shipped)
+
+**Principle: durability of your own machine's work is free and automatic. Never paywall "don't lose
+my file."** Paywalling that reads as hostile and poisons the paid story.
+
+### 2.1 Session autosave + restore
+- The webview bundles the whole session — `{name, goal, nodes, edges, results:{outputs, usage,
+  turns, trunc}}` — via `fullSession()` and posts a debounced `persist` message. Every mutation
+  flows through `render()`, so autosave is automatic; drags/typing coalesce into one write (800 ms
+  debounce). Run **results** persist immediately on `runDone` (`persistNow()`), and a **cleared**
+  canvas persists immediately too (so a reopen doesn't resurrect a deleted graph).
+- The extension writes it to **`.atompp/.session.json`** with an atomic temp-write + rename, so a
+  crash mid-write can't corrupt it. Best-effort: persistence never throws into a run.
+- On panel reopen, the extension ships the saved session in the `init` message; the webview
+  `restoreSession()` repopulates the canvas **and** the per-node meters/outputs, then fits the view
+  and drops an Activity entry: *"Restored your last session (with run results)."* Results are kept
+  only for **surviving node ids**, so a hand-edited/renamed graph can't graft stale outputs.
+- Autosave is armed (`persistReady`) only **after** the restore, so the initial empty render can't
+  clobber the saved session.
+
+### 2.2 On-demand Markdown export
+A **Export** button renders the current run as a readable `.md` (goal, totals, then each agent's
+model/tokens/cost + full output) into `.atompp/runs/<name>-<ts>.md` and opens it. This is the
+"share it / drop it in a PR / paste to a teammate" deliverable.
+
+### 2.3 What is deliberately **not** free
+Cross-device sync, an unlimited/searchable archive, and cost analytics — see §4/§5.
+
+---
+
+## 3. Data model
+
+`fullSession()` / `.atompp/.session.json` (and the future cloud "run record"):
+
+```jsonc
+{
+  "name": "Design a Key-Value Store",
+  "goal": "Build ... in C",
+  "nodes": [{ "id": "n1", "agentId": "planner", "label": "requirements",
+              "instructions": "...", "model": "", "x": 60, "y": 60 }, ...],
+  "edges": [{ "from": "n1", "to": "n2" }, ...],
+  "results": {
+    "outputs": { "n1": "<full text>", ... },        // full, not the 400-char preview
+    "usage":   { "n1": { "input": 3571, "output": 8192, "model": "claude-opus-4-8" }, ... },
+    "turns":   { "n1": 2 },                          // auto-continuation turns
+    "trunc":   { "n7": true }                        // hit the safety cap
+  }
+}
+```
+
+Cost is derived, never stored (prices drift): `pricing.costOf(model, input, output)`. This same
+record is what the cloud archive stores per run, plus `{startedAt, finishedAt, provider, totals,
+aborted, failed}` envelope fields.
+
+---
+
+## 4. The Markdown tension (and the resolution)
+
+The instinct "on close, offer to save everything to a Markdown file" is well-meaning but wrong on
+two counts:
+
+1. **UX:** a save *prompt* on close is dismissed under time pressure — and then the work is lost
+   anyway. **Automatic** structured autosave is strictly safer; there's nothing to click.
+2. **Business:** a polished, portable Markdown archive of every run *is the sellable artifact.* If
+   the free tier hands users a complete, portable corpus of their runs, the cloud archive has little
+   left to sell — they'll keep their own `.md` files in git/Obsidian and never subscribe.
+
+**Resolution — put the free feature on app-internal state, not on the deliverable:**
+
+| | Free local | Paid cloud |
+|---|---|---|
+| Autosave/restore | `.atompp/.session.json` — **app-internal JSON**, restores *into the live canvas* with meters. Not a browsable corpus. | — |
+| Markdown export | **manual, per-run, one-way** — a single chosen deliverable to share. Not a searchable/restorable archive. | — |
+| Archive | — | Unlimited, searchable, restore-any-run-anywhere |
+| Portability | one machine | every device |
+| Insight | the last run's meters | cost analytics across all runs |
+
+The free tier gives you **durability and one-off sharing**; it does **not** give you a portable,
+aggregated, cross-device *system of record.* That system is the paid product.
+
+---
+
+## 5. Cloud sync — the paid layer
+
+### 5.1 Reuse the rails you already have
+Atom++ Sync already exists: Code-OSS **Settings Sync** pointed at an Atom++-operated store, with the
+`atompp` **auth provider** (`configurationSync.store` in `branding/product.overlay.json`; the
+`atompp.ai.account` sign-in). Cloud run sync is a **new resource type on the same account + server**,
+not a new product. A signed-in Plus user's `.atompp/` run records replicate to the cloud and back.
+
+### 5.2 The features that justify a subscription
+
+| Feature | Why it's worth paying for |
+|---|---|
+| **Cross-device sync** | Sketches + run results + Activity follow you laptop ↔ desktop; survive a dead machine. The classic sync value. |
+| **Unlimited, searchable run archive** | Local Activity caps at the last 100 and one `.session.json`; cloud keeps *every* run forever, searchable by goal/agent/model/cost — a **ledger of what you spent and what you got.** |
+| **Cost analytics dashboard** | You already meter tokens/$ per node and ship what-if repricing. Aggregating it — *"$X across N runs this month; the same flows on Haiku would've been $Y"* — is a small step from shipped data with high perceived value. **This is the hook**: a professional watching AI spend will pay for the ledger + the "cheaper-model" delta. |
+| **Team sharing** | Share a sketch + its results / a flow-template library; seat management. The collaboration upsell. |
+| **Restore-anywhere / backup** | Reinstall on a new Mac, sign in, every run is back. |
+
+### 5.3 Why this is defensible *and* on-strategy
+- **BYOK-primary, always.** The user brings their own key; Atom++ **never** marks up or resells
+  inference (you can't undercut the provider's own subscription — [[atompp-cloud-byok-primary]]).
+  We sell **software + cloud**: sync, archive, analytics, collaboration. No inference-margin problem.
+- **The pain funds the product.** Losing a costly run *creates* demand for durability → sync. The
+  metering already built makes the analytics/ledger nearly free to build and very compelling to buy.
+- **Ethical line:** local durability is free, so nobody pays "not to lose my own work." They pay for
+  *portability, permanence, insight, and collaboration* — real cloud value.
+
+### 5.4 Suggested tiers
+- **Free:** BYOK, all providers, Agent Sketch, **local autosave + restore**, Markdown export, local
+  Activity (last 100).
+- **Atom++ Plus (subscription):** cross-device sync (settings + sketches + runs), unlimited
+  searchable cloud archive, cost analytics dashboard, restore-anywhere.
+- **Team:** shared sketch/template libraries, shared run history, seats/admin.
+
+---
+
+## 6. Roadmap
+
+| Phase | Deliverable | State |
+|---|---|---|
+| **SK1.2** | Local session autosave + restore; Markdown export | ✅ shipped |
+| **RP1** | Local **run history** beyond the latest (keep last N runs per sketch under `.atompp/runs/`, restore any) — still free, still local | next |
+| **RP2** | Cloud sync of sketches + run records on the `atompp` account (extend Settings-Sync store); **Plus** gate | paid |
+| **RP3** | Cost analytics dashboard (aggregate the metering already captured) — the flagship Plus feature | paid |
+| **RP4** | Team sharing: shared libraries + run history + seats | paid |
+
+**Prerequisite for RP2+:** point `configurationSync.store.url` at the managed Atom++ Cloud host (it's
+a localhost placeholder today — see `product.overlay.json` `_syncComment`).
+
+---
+
+## 7. Attribution
+Builds on the shipped Agent Sketch (SK1), the multi-provider metering (P2/P4), and the Atom++ Sync /
+`atompp` auth rails. Persistence is app-internal; the cloud layer is the monetization surface.
@@ -118,9 +118,47 @@ files). Costs shown are planning estimates from list prices — the provider bil
 
 | Phase | Deliverable |
 |---|---|
-| **SK2** | **Tool-using nodes**: a node can run the full `agent.js` loop (read/edit/run with Keep-Undo review + per-run checkpoint) so a sketched flow actually edits the workspace; live streamed output in the inspector; run history. |
-| **SK3** | **Topologies**: coordinator/hierarchical patterns (a queen node that dispatches + collects, ruflo-style), conditional edges, retry/verify loops; per-flow token budgets with early stop. |
-| **SK4** | **Interop**: import/export ruflo swarm configs; publish sketches as shareable templates; sketch → `atompp.ai` chat-agent handoff ("run this flow on the current repo"). |
+| **SK1.3** | **Prompt → whole flow** (shipped): type a plain-English description into the (empty) board and the active model designs a complete DAG — `generateFlow()` returns `{goal, nodes, edges}`, normalized to a loadable sketch and auto-laid-out. Empty canvas = *build*; populated canvas = *edit* (the existing ops command). |
+| **SK2** | **Tool-using + connector nodes**: a node runs the full `agent.js` loop (read/edit/run with Keep-Undo review) so a sketched flow edits the workspace; **connector nodes actually act** — Telegram/Slack post, email send, webhook call, file write — behind credentials + per-flow permission (see §4). |
+| **SK3** | **Triggers & topologies**: a `scheduler`/`webhook-trigger` root fires the flow on a **cron cadence / inbound event** (Managed-Agents-style scheduled deployment); coordinator/hierarchical patterns, conditional edges, retry/verify loops; per-flow token budgets. |
+| **SK4** | **Interop**: import/export ruflo swarm configs; publish sketches as shareable templates; sketch → `atompp.ai` chat-agent handoff. |
+
+## 4. Node tiers: text → tools → connectors → triggers
+
+Not every node is the same *kind* of thing. The catalog now spans four execution tiers; SK1 runs them
+all as **text-only** (a connector emits the payload it *would* send; a trigger emits the context it
+*would* fire with), and later phases make the side-effecting tiers real — each with the safety it needs.
+
+| Tier | Examples | SK1 (today) | Later — what "real" needs |
+|---|---|---|---|
+| **Text** | coder, researcher, news-collector, copywriter, editor-in-chief | one LLM turn, in/out text | — (this is the whole SK1 model) |
+| **Tool / file** | file-writer, and any node run through `agent.js` | outputs the file + contents it *would* write | SK2: writes via the same **Keep/Undo review + per-run checkpoint** the chat agent uses |
+| **Connector (actuator)** | telegram-publisher, email-sender, slack-publisher, webhook-caller | outputs the exact message/email/HTTP payload it *would* send | SK2: real send. Needs **(a)** credentials in SecretStorage/keychain (bot token, SMTP creds — never in the sketch file), **(b)** a **per-flow send permission** the user grants once (sending is outward-facing — mirrors the harness "Explicit permission" rule: publishing/messaging requires a clear yes), **(c)** an **allowlist** (which chat/recipient/host), **(d)** a dry-run preview (show the message, click Send) |
+| **Trigger** | scheduler (cron), webhook-trigger | the ROOT node; outputs the run context ("collect news since the last run at <time>") | SK3: a **scheduled/triggered run** — cron cadence or inbound webhook fires the downstream DAG unattended. Maps onto the Managed-Agents *scheduled deployment* pattern (cron + per-firing run records) or a local scheduler; ties into the run-persistence archive so every firing is logged |
+
+**Why the tiering is the point:** it keeps SK1 shippable and safe (nothing sends, nothing runs on a
+timer — you can design and cost a Telegram-publishing pipeline today and see exactly what it *would*
+post), while giving a clear, honest path to real automation where each dangerous capability (send,
+write, schedule) is gated by the credential + permission model it deserves. The BYOK rule is unchanged
+— connectors use the *user's own* integration credentials; Atom++ never proxies or stores the content.
+
+### Worked example (what the generator produces)
+Prompt: *"5 agents collect recent AI & agentic-AI news; a head-of-press-release edits them; a
+copywriter verifies and composes one post; publish it to Telegram; run it daily."* →
+
+```
+daily-trigger (scheduler)
+  → [ai-research · agentic · products · funding · safety]  (5 news-collectors, parallel)
+      → press-desk (press-editor)
+        → copywriter (copywriter)
+          → editor-approval (editor-in-chief)
+            → telegram-post (telegram-publisher)
+```
+
+Today that runs text-only: the collectors produce cited news summaries, the copywriter composes the
+post, and `telegram-post` outputs the exact Markdown message it *would* send — metered, costed, and
+persisted. SK2 turns `telegram-post` into a real send (bot token + "allow send to @channel"); SK3
+makes `daily-trigger` actually fire the flow every morning.
 
 ## 3. Attribution & licensing
 Agent names/roles derived from ruflo's `.claude/agents/` library (MIT © 2024–2026 ruvnet) — metadata