@@ -0,0 +1,128 @@
+# Atom++ — Agent Sketch — Design
+
+> **Status:** SK1 skeleton shipped · **Date:** 2026-07-01 · **Owner:** Sergii Demianchuk
+> **Vision:** Sketch a whole agentic system visually, right inside the Atom++ editor — connect
+> specialized agents into flows, watch **tokens burned per step**, and **recalculate the same flow
+> against different models** before committing to one. Chaining in the spirit of
+> [ruflo](https://github.com/ruvnet/ruflo) ("Agent = Model + Harness"; 100+ specialized agents),
+> with the canvas interaction model adapted from the SystemSketch (SysDes) prototype.
+
+## 0. Why this is a natural Atom++ feature
+
+Everything below sits on the multi-provider layer already shipped:
+
+| Need | Already built |
+|---|---|
+| Run one agent step on ANY provider, BYO-key | P1/P2 — `providers.streamAgentTurn` (Anthropic native + OpenAI-compatible translation) |
+| **Real token usage per step** | P2 — `usage` from `message_start`/`stream_options.include_usage` |
+| Per-model capabilities to pick sensible defaults | P4 — `providers/catalog.js` tiers/caps |
+| Cost math for the meter + what-if | `sketch/pricing.js` ($/MTok table; Anthropic published, others list-price estimates, labeled "est.") |
+| No middle-man backend, keys in the keychain | The Atom++ architecture invariant |
+
+## 1. The SK1 skeleton (shipped)
+
+```
+extensions/atom-ai/
+  sketch.js                  controller: panel, persistence, THE RUNNER (reentrancy-guarded, abortable)
+  sketch/agentCatalog.js     96 agent archetypes in 13 palette groups (derived from ruflo, MIT © ruvnet — names + one-line roles only)
+  sketch/templates.js        ready-made topologies — incl. the "Design a Key-Value Store" hero template   [unit-tested]
+  sketch/graph.js            pure DAG logic: validate (cycles/dangling), Kahn topo LEVELS, node-input builder   [unit-tested]
+  sketch/pricing.js          $/MTok table + exact→basename→family matching + costOf()                          [unit-tested]
+  media/sketch.html          the canvas webview (vanilla JS, no build step)
+```
+
+### Templates — drop a whole topology, set the goal, run
+`sketch/templates.js` ships pre-wired flows loadable from the **Templates…** dropdown; each is a full
+sketch (nodes + edges + per-node instructions) laid out on a grid. The hero is **Design a Key-Value
+Store**, a faithful 11-node / 6-level topology of the *System Design Interview* ("Design a Key-Value
+Store" / ByteByteGo) chapter:
+
+```
+requirements → architecture → [ storage-engine · consistent-hash · replication+quorum ·
+                                vector-clocks · gossip+failover ]  (parallel)
+             → integrate+server → [ tests · build+validate ] → review+run-guide
+```
+
+Every node carries a precise task pinning its aspect (WAL/memtable/SSTable/bloom/compaction;
+consistent-hashing ring; N/W/R quorum + read-repair; vector-clock reconciliation; gossip + sloppy
+quorum + hinted handoff + Merkle anti-entropy; coordinator/request routing; cluster tests). The
+flow **goal** (top of the canvas) sets the language — type *"build using C"* and the flow produces a
+C implementation covering every aspect. Other templates: feature-pipeline, research-synthesize,
+code-review-swarm, SPARC, TDD, bug-fix, API-service, security-audit, refactor.
+
+### Hardening (post adversarial review)
+The `Workflow` adversarial review surfaced 31 confirmed findings; the load-bearing ones are fixed:
+- **Reentrancy / unstoppable spend** — `runSketch` claims a run slot *synchronously* before any
+  `await` and clears it only if still its own; a double-clicked Run can't orphan the first run, so
+  **Stop always aborts** (real BYOK money).
+- **Abort ≠ failure** — a user Stop paints in-flight nodes `stopped`, not red `error`, and `runDone`
+  no longer reports `failed`.
+- **Truncation surfaced** — a node that hits the per-node cap is badged `⚠ truncated` and its stored
+  output marked incomplete (cap raised 4096 → 8192 so a full module fits).
+- **`uiError` channel** — save/load/clipboard failures no longer masquerade as run errors.
+- **Pricing drift killed** — the webview's hand-rolled matcher is gone; the extension resolves each
+  model's price once (authoritative matcher) and sends the map.
+- **Hostile-JSON safe** — loaded sketches are sanitized (array coercion, `__proto__`/dup-id
+  rejection, dangling-edge drop); disk-sourced strings are HTML-escaped before `innerHTML`.
+- **Cross-provider guard** — a per-node model override invalid on the active provider falls back to
+  the tier default with a note (no stray `gpt-4o` 400 on a Claude key).
+- **UX** — node rename, run-gating of Load/Templates/Clear, catalog descriptions de-truncated.
+
+- **Palette → canvas → connect → Run.** Drag agents (coder, planner, reviewer, security-manager,
+  raft-manager, pr-manager, …) onto the canvas; wire output→input ports into a DAG (cycles are
+  rejected live). `Run` executes **levels in parallel, chains in sequence** (Kahn levels — ruflo's
+  mesh/pipeline hybrid).
+- **Each node = one turn on the active provider** via `streamAgentTurn` (no tools in SK1): system
+  prompt = the agent's role from the catalog (+ optional per-node task), user message = flow goal +
+  upstream agents' outputs.
+- **Metering:** every node card shows real tokens in/out + estimated cost; the footer totals roll up
+  live. The **what-if selector re-prices the whole recorded run on a different model** without
+  re-running — the feature that answers "what would this flow cost on Haiku vs Opus?"
+- **Per-node model:** catalog `tier` (fast/balanced/powerful) → provider-specific default
+  (`MODEL_TIERS`), overridable per node in the inspector.
+- **Persistence:** named sketches in the workspace at `.atompp/sketches/<name>.json`.
+- Command: **`atompp.ai.sketch`** ("AI: Agent Sketch…"), also in the Customize panel.
+
+### Safety posture (SK1)
+Sketch nodes are **text-only** — no file edits, no commands, no tools. A sketch run cannot touch the
+workspace; it only spends the user's own tokens (BYOK, direct to provider, key never in the sketch
+files). Costs shown are planning estimates from list prices — the provider bills the user directly.
+
+### Canvas UX (SK1.1)
+- **No lost work.** A node runs to completion via `runNodeTurn` auto-continuation: `streamAgentTurn`
+  caps a single turn at 8192 tokens, and if the model stops on `max_tokens` the runner feeds its own
+  partial back with a "continue where you left off" instruction and keeps going — accumulating text
+  and usage across up to 8 turns. A whole code module (or the KV-store integrator's output) is no
+  longer truncated. Nodes that needed more than one turn show `⟳n`; only exhausting the 8-turn safety
+  cap marks a node truncated.
+- **Zoom + bigger board.** 12000×8000 world; `translate(pan)·scale(zoom)` with wheel-zoom (cursor-
+  anchored), +/−/reset/fit controls, ⌘0 / ⌘± shortcuts, and a **Fit** that frames the whole flow.
+  All drop/drag/wire math goes through `toWorld()` so it's correct at any zoom.
+- **Board command bar (LLM edits the graph).** Type an instruction — *"add a security-auditor after
+  coder"*, *"set every agent to Opus 4.8"*, *"tidy the layout"* — and the active model returns a JSON
+  op list (`add`/`connect`/`disconnect`/`remove`/`setModel` scoped all|agent|node/`setTask`/`setGoal`/
+  `layout`) applied deterministically in the webview. Unknown agents/refs are skipped with a note; the
+  DAG stays acyclic.
+- **Active-node highlight redesigned.** The marching-ants border is gone (it flickered over the
+  connector dots); the running node now has a breathing glow + a header shimmer, and ports sit above
+  it (`z-index`) so they never blink.
+- **Palette optimized.** Live search filter, per-agent tier chip (f/b/p), sticky group headers,
+  expand/collapse-all.
+- **What-if reworked.** Instead of one dropdown, a row of chips shows what *this exact flow* would cost
+  on each candidate model (the active provider's fast/balanced/powerful tiers + any model actually
+  used), cheapest first, current run marked. Clicking a chip switches every agent to that model — so
+  the comparison is also the action.
+- **Tidy.** One-click `autoLayout` (topological columns) re-arranges the flow left→right by dependency.
+
+## 2. Roadmap
+
+| 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"). |
+
+## 3. Attribution & licensing
+Agent names/roles derived from ruflo's `.claude/agents/` library (MIT © 2024–2026 ruvnet) — metadata
+only (name + one-line role); every node executes on Atom++'s own agent loop and providers. The canvas
+interaction model (palette/nodes/edges/live metrics) is adapted from the internal SysDes prototype.
@@ -77,7 +77,8 @@ function htmlFor(nonce, s) {
 		'<div class="btns">' + btn('Change model / provider', 'atompp.ai.pickModel', true) +
 			btn(keyBtn, 'atompp.ai.setApiKey', !s.keySet && !s.noKey) +
 			btn('Sign in to Atom++', 'atompp.ai.account') +
-			btn('Open chat', 'atompp.ai.focus') + '</div>');
+			btn('Open chat', 'atompp.ai.focus') +
+			btn('Agent Sketch', 'atompp.ai.sketch') + '</div>');
 
 	const look = section('🎨', 'Appearance & keys',
 		row('Theme', s.theme || '') +
 
@@ -56,7 +56,7 @@ function post(msg) { if (activeWebview) { activeWebview.postMessage(msg); } }
 function aiConfig() { return vscode.workspace.getConfiguration('atompp.ai'); }
 
 /** Inline debug trace — prints a 🐛 DEBUG line in the chat (gated by atompp.ai.debug). */
-function dbg(label, data) { if (aiConfig().get('debug', true)) { post({ type: 'debug', label, data: data != null ? data : null }); } }
+function dbg(label, data) { if (aiConfig().get('debug', false)) { post({ type: 'debug', label, data: data != null ? data : null }); } }
 
 /** The currently selected provider id (settings value; `claude` is the default/legacy Anthropic). */
 function currentProviderId() { return providers.normId(aiConfig().get('provider', 'claude')); }
@@ -688,6 +688,7 @@ async function agentFlow(text) {
 			apiKey: req.apiKey,
 			model: req.model,
 			maxSteps: Math.max(1, cfg.get('agent.maxSteps', 25)),
+			maxTokens: Math.max(1024, cfg.get('agent.maxTokens', 8192)),   // per-turn output cap; continued across turns if hit
 			post, dbg,
 			approve: requestApproval,           // run_command only
 			ask: requestQuestions,              // ask_user — clickable clarifying questions
@@ -714,6 +715,7 @@ async function agentFlow(text) {
 
 async function handleSend(text) {
 	if (!text || !text.trim()) { return; }
+	if (ctx) { ctx.globalState.update('atompp.ai.hasSentMessage', true); }   // user engaged → stop auto-revealing the panel on launch
 	if (agentMode) { await agentFlow(text); return; }
 	const cfg = aiConfig();
 	const providerId = currentProviderId();
@@ -1029,6 +1031,14 @@ function activate(context) {
 		vscode.window.onDidChangeActiveTextEditor(() => postActiveFile()),
 		vscode.commands.registerCommand('atompp.ai.focus', () => vscode.commands.executeCommand('atomAi.chat.focus')),
 		vscode.commands.registerCommand('atompp.customize', () => openCustomize(context)),
+		// Agent Sketch: the visual multi-agent flow canvas. Lazy require — only loads when opened.
+		vscode.commands.registerCommand('atompp.ai.sketch', () => {
+			try {
+				require('./sketch').openSketch(context, { prepProviderRequest, aiConfig, currentProviderId });
+			} catch (e) {
+				vscode.window.showErrorMessage('Agent Sketch failed to load: ' + ((e && e.message) || e));
+			}
+		}),
 		vscode.commands.registerCommand('atompp.import.vscode', () => importFromVscode(context)),
 		vscode.commands.registerCommand('atompp.ai.newChat', newChat),
 		vscode.commands.registerCommand('atompp.ai.pickModel', pickModel),
@@ -1081,12 +1091,19 @@ function activate(context) {
 		fastCompletionModel: catalog.fastCompletionModel
 	});
 
-	// AI-first: reveal the chat (in the secondary side bar) on first launch. We do this once
-	// and then defer to VS Code's own per-workspace layout persistence, so if the user later
-	// closes the panel we don't keep forcing it back open.
-	if (!context.globalState.get('atompp.ai.didAutoOpen')) {
-		context.globalState.update('atompp.ai.didAutoOpen', true);
-		setTimeout(() => { vscode.commands.executeCommand('atomAi.chat.focus'); }, 600);
+	// AI-first: reveal the chat (in the secondary side bar) on EVERY launch until the user has actually
+	// engaged (sent their first message). This makes sure new users always see it, instead of it only
+	// showing once. Once they've sent a message (handleSend sets the flag) we stop forcing it and defer
+	// to VS Code's own per-workspace layout persistence, so closing it stays closed.
+	// Fallback guard: if the webview never renders (provider error, missing resource) hasSentMessage
+	// is never set, which would otherwise force the panel open forever. Stop after a few launches.
+	const AUTO_REVEAL_MAX_LAUNCHES = 5;
+	if (!context.globalState.get('atompp.ai.hasSentMessage')) {
+		const launches = (Number(context.globalState.get('atompp.ai.autoRevealLaunches')) || 0) + 1;
+		context.globalState.update('atompp.ai.autoRevealLaunches', launches);
+		if (launches <= AUTO_REVEAL_MAX_LAUNCHES) {
+			setTimeout(() => { vscode.commands.executeCommand('atomAi.chat.focus'); }, 600);
+		}
 	}
 
 	// First-launch onboarding: open the Welcome walkthrough once.