compound-workflow 1.8.0 → 1.9.0

package/src/{.agents/references → references}/README.md

@@ -9,4 +9,4 @@ Rules of thumb:
 
 Indexing:
 
-- Link relevant reference docs from `src/AGENTS.md` (Skill Index) or from the owning skill under `src/.agents/skills/`.
+- Link relevant reference docs from `src/AGENTS.md` (Skill Index) or from the owning skill under `src/skills/`.

package/src/{.agents/skills → skills}/capture-skill/SKILL.md

@@ -12,7 +12,7 @@ This skill extracts reusable knowledge from the current conversation and stores
 `capture-skill` uses an overlay model by default:
 
 - Treat existing repo-provided skills as immutable unless the user explicitly asks to edit a specific one.
-- Store project-specific refinements in a project overlay skill (for example, `.agents/skills/project-standards/`).
+- Store project-specific refinements in a project overlay skill (for example, a `project-standards/` skill in the current harness skills directory — resolve from `harnesses` in AGENTS.md Repo Config).
 - Only modify an existing skill when the user clearly says to do so (for example, "update skill X").
 - Promote overlay content into base skills only as an explicit, deliberate follow-up action.
 

package/src/{.agents/skills → skills}/compound-docs/SKILL.md

@@ -153,8 +153,8 @@ Format: `YYYY-MM-DD-<module-slug>-<symptom-slug>.md`
 
 **Validate against schema:**
 
-1. Load `.agents/skills/compound-docs/schema.yaml`.
-2. If `.agents/skills/compound-docs/schema.project.yaml` exists, validate against it as the repo-specific overlay.
+1. Load `schema.yaml` from the same directory as this skill file.
+2. If `schema.project.yaml` exists in the same directory, validate against it as the repo-specific overlay.
 3. Use [yaml-schema.md](./references/yaml-schema.md) as the human-readable reference.
 
 Ensure all required fields are present and match allowed values exactly for enum fields.
@@ -335,8 +335,8 @@ Action:
 
 Example:
 
-- Add to `.agents/skills/<skill-name>/references/resources.md` under "Project-Specific Resources" (if it exists)
-- Add to `.agents/skills/<skill-name>/references/examples.md` with a link to the solution doc (if it exists)
+- Add to `<skill-name>/references/resources.md` in the current harness skills directory (resolve from `harnesses` in AGENTS.md Repo Config) under "Project-Specific Resources" (if it exists)
+- Add to `<skill-name>/references/examples.md` in the current harness skills directory with a link to the solution doc (if it exists)
 
 **Option 6: Create new skill**
 
@@ -344,8 +344,8 @@ User selects this when the solution represents the start of a new learning domai
 
 Action:
 1. Prompt: "What should the new skill be called? (e.g., stripe-billing, email-processing)"
-2. Create a new skill directory: `.agents/skills/<skill-name>/`
-3. Add `.agents/skills/<skill-name>/SKILL.md` with a clear description (what + when to use)
+2. Create a new skill directory: `<skill-name>/` in the skills directory of the current harness (resolve from `harnesses` in AGENTS.md Repo Config)
+3. Add `SKILL.md` in the new skill directory with a clear description (what + when to use)
 4. Create initial reference files (optional) and add this solution doc as the first example
 5. Confirm: "✓ Created new <skill-name> skill with this solution as first example"
 

package/src/{.agents/skills → skills}/compound-docs/references/yaml-schema.md

@@ -1,8 +1,8 @@
 # YAML Frontmatter Schema
 
-**See `.agents/skills/compound-docs/schema.yaml` for the core portable schema specification.**
+**See `schema.yaml` in the same directory as this skill for the core portable schema specification.**
 
-If present, `.agents/skills/compound-docs/schema.project.yaml` acts as an optional repo-specific overlay for stricter enums.
+If present, `schema.project.yaml` in the same directory acts as an optional repo-specific overlay for stricter enums.
 
 ## Required Fields
 

package/src/skills/setup-agents/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: setup-agents
+description: Create or update AGENTS.md for any project. Detects project stack and installed harness directories, prompts for missing config, curates the Skill Index from installed skills, and writes a clean minimal AGENTS.md. Use when onboarding a new project or refreshing an existing config.
+triggers:
+  - setting up a new project
+  - initialising AGENTS.md for the first time
+  - updating or refreshing an existing AGENTS.md
+  - onboarding a new repo to the workflow
+---
+
+# Setup AGENTS.md
+
+<!-- Structural source of truth for AGENTS.md format. The default template shipped in
+     src/AGENTS.md is a populated instance of the Phase 4 template below.
+     When changing the template here, update src/AGENTS.md to match (and vice versa). -->
+
+Create or update a minimal, authoritative `AGENTS.md` for any project.
+
+## Mode Detection
+
+Before doing anything, check whether `AGENTS.md` exists in the repo root.
+
+- **If it does not exist:** run in `init` mode — build from scratch.
+- **If it exists:** run in `update` mode — read the current file, preserve what is correct, update what is stale, and prompt for anything missing.
+
+Announce the mode before proceeding.
+
+---
+
+## Phase 1: Detect Harness Directories and Project Stack
+
+### Harness detection
+
+Check which directories exist at the project root. Do not assume any are present — record only what is actually found on disk.
+
+Known harness patterns to check: directories named `.agents`, `.claude`, `.cursor`. Check all three; others may exist.
+
+For each found harness, note where its skills live:
+- `<harness>/skills/` — if that subdirectory exists
+- `.claude/` has no skills directory (agents only, in `.claude/agents/`)
+
+Record detected harnesses as `$harnesses` (ordered list of directories found). This will be written to AGENTS.md.
+
+If **no harness directories exist**, stop and tell the user:
+> No harness directories found. Run `npx compound-workflow install` first, then re-run this skill.
+
+Use the **first found skills directory** across `$harnesses` as the canonical source for skill discovery in Phase 3. Record this as `$skills_dir`.
+
+> **Note:** `harnesses` in AGENTS.md Repo Config may become stale if harness directories are added or removed. Re-run `/setup-agents` to refresh it.
+
+### Project stack detection
+
+Read the following files if they exist (do not error if missing):
+
+- `package.json` (scripts, dependencies, devDependencies)
+- `vite.config.ts` / `vite.config.js`
+- `tsconfig.json`
+- `.eslintrc.*` / `eslint.config.*`
+- `vitest.config.ts` / `jest.config.*`
+- `turbo.json` / `nx.json` (monorepo signals)
+
+From these, infer:
+
+| Config key | Detection signal |
+| --- | --- |
+| `test_command` | `scripts.test` in package.json; vitest/jest config presence |
+| `test_fast_command` | `scripts.test:fast`, `scripts.test:watch`, or vitest equivalent |
+| `lint_command` | `scripts.lint` in package.json; eslint config presence |
+| `typecheck_command` | `scripts.typecheck` or `scripts.type-check`; tsconfig presence |
+| `format_command` | `scripts.format` in package.json; prettier config presence |
+| `dev_server_url` | vite config `server.port`; default `http://localhost:5173` for Vite, `http://localhost:3000` for others |
+| `worktree_install_command` | `package-lock.json` → `npm ci`; `yarn.lock` → `yarn install`; `pnpm-lock.yaml` → `pnpm install` |
+
+For each value, state whether it was detected or assumed.
+
+---
+
+## Phase 2: Prompt for Missing or Undetectable Values
+
+Ask for any values that could not be detected. Ask one at a time.
+
+Required:
+
+- `default_branch` — cannot be reliably detected; ask (suggest `main`)
+- `project_tracker` — ask: `github`, `linear`, or none
+- `dev_server_url` — confirm detected value or ask
+- `worktree_dir` — suggest `.worktrees`
+- `worktree_copy_files` — ask which env/config files should be copied into new worktrees (e.g. `.env.local`)
+- `harnesses` — show detected list from Phase 1; confirm or correct
+
+**Update mode only:** Show the current values and ask: "These values are already configured — confirm, update, or skip each?"
+
+---
+
+## Phase 3: Curate the Skill Index
+
+List all directories under `$skills_dir` (resolved in Phase 1). For each one, read `SKILL.md` frontmatter to get `name` and `description`. These are the only skills that may appear in the Skill Index — never reference a skill not present on disk.
+
+Present the full discovered list to the user as a numbered menu:
+
+```
+Installed skills (from <$skills_dir>):
+  1. <name> — <description from frontmatter>
+  2. <name> — <description from frontmatter>
+  ...
+
+Which should appear in the Skill Index? (Enter numbers, or "all", or "all except N,N")
+```
+
+**Init mode:** Ask which to include.
+**Update mode:** Show which are currently included and ask: "Keep, remove, or any to add?"
+
+Do not categorise skills in advance — the user decides what is relevant for their project.
+
+---
+
+## Phase 4: Write AGENTS.md
+
+Using all resolved values, write a clean `AGENTS.md` following this exact template.
+
+**Init mode:** write the full file.
+**Update mode:** preserve any sections the user confirmed as correct; replace only what changed.
+
+```markdown
+# Agent Operating Principles
+
+This workspace is portable and command-first.
+
+## Core Principles
+
+1. Commands are the public API. Skills and agents are composable internals.
+2. Core workflows stay generic. Domain-specific behavior loads only when context requires it.
+3. Planning quality is explicit via fidelity selection.
+4. Selection must be deterministic and visible: always state which skills/agents were selected and why.
+5. Brainstorm and plan do not write code.
+
+## Contract Precedence
+
+If workflow documents conflict, resolve in this order:
+
+1. `docs/principles/workflow-baseline-principles.md`
+2. This file — non-negotiables and repo config
+3. Workflow command specs
+4. Skill docs
+
+## Canonical Workflow
+
+1. `/workflow:brainstorm` — clarify what to build
+2. `/workflow:plan` — define how to build it
+3. `/workflow:work` — implement (includes triage gate)
+4. `/workflow:review` — validate quality
+5. `/workflow:compound` — capture durable learnings
+
+Optional:
+
+- `/workflow:triage` — manually curate/prioritize queue before execution
+- `/workflow:tech-review` — technical correctness check on a plan before build
+
+Continuous improvement:
+
+- `/metrics` — log + assess a session
+- `/assess` — aggregate metrics and propose improvements
+
+## Non-negotiables (Structure Integrity)
+
+- **Commands are the public API.** Keep `/workflow:*` command docs stable; add capability via skills/agents, not new command variants.
+- **Brainstorm = WHAT, Plan = HOW.** `/workflow:plan` must not re-litigate decisions already captured in `docs/brainstorms/`.
+- **Local grounding is mandatory.** Every plan must cite at least 1–3 internal file path/line refs and any relevant `docs/solutions/**` learnings.
+- **Fidelity + confidence are required declarations** in every plan file.
+- **Solution scope contract is mandatory in every plan.** Plans must declare `solution_scope` (`partial_fix|full_remediation|migration`) plus completion expectation and non-goals.
+- **Isolation preflight is a hard gate.** `/workflow:work` must complete and record worktree/isolation preflight before any implementation commands.
+- **Triage before execution is mandatory.** `/workflow:work` must run a triage pass before executing todos.
+- **Independent review is required for code/config changes.** `/workflow:review` must emit `review_independence_mode: independent|degraded`.
+- **Standards baseline is mandatory for code/config changes.** `/workflow:work` and `/workflow:review` must apply `skill: standards` as a hard gate.
+- **Todo completion requires evidence.** A todo may move to `complete` only after success criteria and quality gate evidence are recorded.
+- **No ad-hoc artifacts outside canonical outputs** (`docs/plans`, `todos`, `docs/solutions`, `docs/metrics`) unless explicitly requested.
+
+## Planning Fidelity Model
+
+`/workflow:plan` must always declare: `Fidelity`, `Confidence`, `solution_scope`, rationale, research mode, and open questions.
+
+- **Low** — problem, constraints, acceptance criteria, implementation outline, verification checklist.
+- **Medium** — all Low + alternatives/tradeoffs, dependency/risk table, rollout notes, observability/test notes.
+- **High** — all Medium + failure modes, rollback plan, deployment gates, migration/data safety checks, expanded test matrix.
+
+Select `High` if any high-risk trigger exists (security, payments, privacy, data migration, production infra). Default to `Medium` for mixed signals. Otherwise `Low`.
+
+## Routing Rules
+
+- **Centralized skill routing:** Add new domain/reference skill routing in this file (Skill Index) rather than per-command.
+- **Default selection order:** (1) safety/guardrail standards, (2) domain architecture/reference skills, (3) workflow execution skills. Minimal set that covers the problem.
+- **Explain selection:** Always state which skills were selected and why.
+- Run local repo + institutional learnings research first for planning. External research based on fidelity and risk.
+
+## Repo Config Block
+
+\`\`\`yaml
+default_branch: <value>
+project_tracker: <github|linear|none>
+dev_server_url: <value>
+test_command: <value>
+test_fast_command: <value or omit>
+lint_command: <value or omit>
+typecheck_command: <value or omit>
+format_command: <value or omit>
+worktree_dir: <value>
+worktree_install_command: <value>
+worktree_copy_files:
+  - <file1>
+harnesses:
+  - <detected harness dir 1>
+\`\`\`
+
+## Skill Index
+
+| Skill | Use when |
+| --- | --- |
+[... one row per skill the user selected in Phase 3; use the description from each skill's SKILL.md frontmatter ...]
+```
+
+Confirm: "AGENTS.md written."
+
+---
+
+## Phase 5: Validation
+
+After writing, verify:
+
+- [ ] All required Repo Config Block keys are present and non-empty
+- [ ] `harnesses` lists only directories detected on disk in Phase 1 — no invented entries
+- [ ] Every skill in the Skill Index was discovered from `$skills_dir` — no invented entries
+- [ ] All skill descriptions come from `SKILL.md` frontmatter — none invented by the agent
+- [ ] No hardcoded tool, platform, or directory names
+- [ ] File is under 130 lines
+
+If any check fails, fix before confirming completion.
+
+---
+
+## Rules
+
+- Never add sections beyond what the template defines — keep it minimal
+- Never hardcode skill names — discover everything from the detected skills directory
+- Never hardcode harness paths — detect what exists on disk first; `harnesses` in AGENTS.md reflects reality, not assumptions
+- Never invent skill descriptions — always read from the skill's `SKILL.md` frontmatter
+- Never hardcode tool or platform names
+- Never duplicate content that lives in command or skill docs
+- In update mode, never silently overwrite values the user confirmed as correct
+- If a detected value looks wrong, surface it and ask — do not assume
+- When the Phase 4 template changes, update `src/AGENTS.md` to match (it is the populated default instance)

package/src/skills/standards/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: standards
+description: >
+  Enforce frontend code standards when writing, reviewing, or refactoring frontend code.
+  Use this skill for all frontend work — new features, PR reviews, refactors,
+  component creation, or any code quality assessment. This skill defines mandatory pass/fail gates.
+  If the user is writing, reading, or evaluating frontend code in any form, use this skill
+  immediately — do not rely on general knowledge.
+---
+
+# Frontend Standards
+
+Five themes apply to all frontend work. All must be satisfied.
+
+| Theme | Concern |
+|---|---|
+| **Architecture** | Layered model, layer boundaries, data flow direction |
+| **Code Quality** | Control flow, immutability, error handling |
+| **Services** | IO boundary, Effect Layer structure, runtime composition |
+| **State Management** | Controller responsibilities, state and event contracts |
+| **Presentation** | Component structure, composition patterns, visual conventions |
+
+---
+
+## When to Load Reference Files
+
+Load the relevant reference before reviewing or writing code in that area.
+
+| Situation | Load |
+|---|---|
+| Layer structure, boundaries, or data flow | `references/architecture.md` |
+| Control flow, error handling, or data transforms | `references/code-quality.md` |
+| Effect services, Layers, or runtime composition | `references/services.md` |
+| State machines, events, context, or actor patterns | `references/state-management.md` |
+| Component structure or visual conventions | `references/presentation.md` |
+| Full review or uncertainty about which layer applies | All five |
+
+---
+
+## Mandatory Gates
+
+Each is **pass/fail**. A single `fail` means the work is incomplete.
+
+| Gate | Theme | Rule |
+|---|---|---|
+| `architecture` | Architecture | All layers honour their boundaries — no layer reaches past its neighbour |
+| `code_quality` | Code Quality | Control flow is flat, transforms are immutable, errors are handled explicitly |
+| `services` | Services | All IO is isolated to the service layer — no IO in entities, controllers, or containers |
+| `state_management` | State Management | Controllers own state; containers extract values and callbacks — never pass raw machine internals to components |
+| `presentation` | Presentation | Components follow the folder, composition, and visual conventions |
+
+---
+
+## Required Evidence Format
+
+Record in all work outputs and code reviews:
+
+```markdown
+standards_compliance:
+  - architecture: pass|fail (evidence: file:line)
+  - code_quality: pass|fail (evidence: file:line)
+  - services: pass|fail (evidence: file:line)
+  - state_management: pass|fail (evidence: file:line)
+  - presentation: pass|fail (evidence: file:line)
+```
+
+On any `fail`: load the relevant reference file, surface the specific violation with evidence, explain the rule broken, and show the corrected pattern. List **all** failures before summarising — do not stop at the first.
+
+---
+
+## Reference Files
+
+| File | Theme | Contents |
+|---|---|---|
+| `references/architecture.md` | Architecture | Layered model, layer responsibilities, file structure, import rules |
+| `references/code-quality.md` | Code Quality | Control flow, immutability, error handling, validation boundary |
+| `references/services.md` | Services | Effect Layer pattern, service structure, runtime composition |
+| `references/state-management.md` | State Management | XState v5 patterns, events, guards, actions, actor communication |
+| `references/presentation.md` | Presentation | Folder structure, compound components, barrel pattern, visual conventions |

package/src/skills/standards/references/architecture.md

@@ -0,0 +1,228 @@
+# Architecture Reference
+
+## The Layered Model
+
+All frontend code follows a strict five-layer architecture. Data flows in one direction. Layers do not skip.
+
+```
+Entities (pure functions — transforms and predicates)
+    ↓ consumed by
+Services (Effect Layers — all IO and side effects)
+    ↓ consumed by
+Controllers (XState machines — own state and transitions)
+    ↓ consumed by
+Containers (composition layer — wire state to UI)
+    ↓ consumed by
+Presentation (UI only)
+```
+
+Each layer has a single responsibility. No layer reaches past its neighbour.
+
+---
+
+## Layer Responsibilities
+
+### Entities
+
+Location: `src/features/{feature}/domain/entities/`
+
+Entities are pure functions. They have no knowledge of state machines, services, React, or the UI. They do two things:
+
+1. **Transforms** — `toX` functions, input → output, inbound and outbound data shaping
+2. **Predicates** — `hasX`, `isX` functions, inferring facts from data
+
+Entities are the data boundary for backend responses — they apply defaults and ensure correct shape as part of the transform. They may use Effect's typed utilities (`Effect.try`, `Option`, `Either`) for safe transforms, but must remain pure. No runtime, no Layer dependencies.
+
+**Rules:**
+- Pure functions only — no side effects, no framework imports, no IO
+- No classes — functions only
+- One file per concern (`PlaylistSelectionEntity.ts` vs `PlaylistReorderEntity.ts`)
+- Private helpers stay internal — no `export`
+
+**Naming conventions:**
+
+| Prefix | Purpose | Example |
+|---|---|---|
+| `hasX` | Boolean predicate | `hasAddedPlaylists` |
+| `isX` | Boolean predicate | `isValidState` |
+| `getX` | Retrieve/extract | `getAddedPlaylists` |
+| `toX` | Transform | `toPlaylistIds` |
+
+**Function signatures** — use object params for 2+ arguments:
+
+```typescript
+export const hasAddedPlaylists = ({
+  current,
+  incoming,
+}: {
+  current: InputOption[];
+  incoming: InputOption[];
+}): boolean => { ... };
+```
+
+**Imports** — import as namespace:
+
+```typescript
+import * as playlistSelectionEntity from "src/features/{feature}/domain/entities/PlaylistSelectionEntity";
+playlistSelectionEntity.hasAddedPlaylists({ ... });
+```
+
+---
+
+### Services
+
+Location: `src/features/{feature}/infrastructure/services/`
+
+Services own all IO and side effects. Controllers call services — they never perform IO directly.
+
+See `references/services.md` for the full Effect Layer pattern, service structure, and runtime composition.
+
+---
+
+### Controllers
+
+Location: `src/features/{feature}/application/controllers/`
+
+Controllers own state and transitions. They delegate transforms and predicates to entities, and IO to services via the injected runtime.
+
+See `references/state-management.md` for the full XState v5 pattern.
+
+---
+
+### Containers
+
+Location: `src/features/{feature}/application/containers/`
+
+Containers are the composition layer. Three responsibilities:
+
+1. **Map state** from the controller via `useSelector` and tags
+2. **Forward events** to the controller — unconditionally
+3. **Compose** hooks, translations, and presentation components
+
+**Rules:**
+- One container per controller
+- No logic — no transforms, no business rules
+- No conditionals around events — forward unconditionally, let the controller decide
+- Targeted `useSelector` — select only what this container needs
+- Never pass `send` or raw `snapshot` to presentation components — extract values and create specific callbacks
+
+```typescript
+// ❌ Bad — leaks machine internals into presentation
+<Sidebar snapshot={snapshot} send={send} />
+
+// ✅ Good — extract values, create specific callbacks
+const { sidebarCollapsed, currentRoute } = snapshot.context;
+const handleToggleSidebar = useCallback(() => send({ type: 'TOGGLE_SIDEBAR' }), [send]);
+
+<Sidebar collapsed={sidebarCollapsed} onToggle={handleToggleSidebar} currentRoute={currentRoute} />
+```
+
+**Folder naming:** The container folder name must match the exported component name **exactly**, including any suffix (e.g. `Container`). Never shorten the folder name.
+
+```
+application/containers/
+  AuthGuardContainer/        ← exports AuthGuardContainer   ✅
+  GlobalLoaderContainer/     ← exports GlobalLoaderContainer ✅
+
+  AuthGuard/                 ← exports AuthGuardContainer   ❌ (name mismatch)
+```
+
+This keeps the folder path and the import name in sync — reading either one tells you the other without opening the file.
+
+```typescript
+// ✅ Forwards unconditionally
+const onAction = useCallback(() => {
+  actor.send({ type: "playlist.action" });
+}, [actor]);
+
+// ❌ Container deciding — belongs in the controller
+const onAction = useCallback(() => {
+  if (isEditing) actor.send({ type: "playlist.save" });
+  else actor.send({ type: "playlist.cancel" });
+}, [actor, isEditing]);
+```
+
+---
+
+### Presentation
+
+Location: `src/features/{feature}/presentation/`
+
+Presentation components are UI only. They receive props and render. No state machines, no services, no business logic.
+
+See `references/presentation.md` for folder structure and composition rules.
+
+---
+
+## File Structure
+
+```
+src/
+├── effects.ts                          # App runtime — composed once here
+└── features/{feature}/
+    ├── application/
+    │   ├── containers/                 # Composition layer
+    │   └── controllers/               # State machines
+    ├── domain/
+    │   └── entities/                  # Pure functions
+    ├── infrastructure/
+    │   └── services/                  # Effect Layers — all IO
+    │       ├── PlaylistService.ts
+    │       ├── FolderService.ts
+    │       └── index.ts               # Feature layer composition
+    ├── presentation/                  # UI components
+    └── types.ts                       # Public events (create only when needed)
+```
+
+**Import paths** — use absolute paths from `src/`:
+
+```typescript
+import * as playlistSelectionEntity from "src/features/{feature}/domain/entities/PlaylistSelectionEntity";
+```
+
+Relative paths are acceptable within the same feature for deeply nested files.
+
+---
+
+## Quick Check — Common Violations
+
+**Logic in a container:**
+```typescript
+// ❌ Container deciding
+if (isEditing) actor.send({ type: "playlist.save" });
+
+// ✅ Controller decides — container forwards
+actor.send({ type: "playlist.action", payload: { isEditing } });
+```
+
+**Side effect in an entity:**
+```typescript
+// ❌ Entity performing IO
+export const fetchPlaylists = async (folderId: string) => {
+  return await api.get(`/folders/${folderId}/playlists`);
+};
+
+// ✅ Entity is a pure transform
+export const toPlaylistItems = (raw: RawPlaylist[]): PlaylistItem[] =>
+  raw.map(r => ({ id: r.playlistId, label: r.playlistTitle ?? "Untitled" }));
+```
+
+**Layer skipping:**
+```typescript
+// ❌ Container importing an entity directly
+import * as playlistEntity from "src/features/{feature}/domain/entities/PlaylistEntity";
+
+// ✅ Container reads from controller state only
+const playlists = useSelector(actor, s => s.context.playlists);
+```
+
+**Passing machine internals to presentation:**
+```typescript
+// ❌ Presentation receives send/snapshot — leaks machine contract into UI layer
+<Sidebar snapshot={snapshot} send={send} />
+
+// ✅ Container extracts values and creates callbacks
+const collapsed = snapshot.context.sidebarCollapsed;
+const onToggle = useCallback(() => send({ type: 'TOGGLE_SIDEBAR' }), [send]);
+<Sidebar collapsed={collapsed} onToggle={onToggle} />
+```