moving

notes/error-as-empty.md

@@ -0,0 +1,10 @@
+# Error states rendered as empty states were the dominant novice-trust defect
+
+The single biggest "app feels broken/dumb" pattern was not missing features — it was hooks that
+captured `error` but components that never threaded it, so "No approvals yet" stood in for "the
+server is down" on trust/activity surfaces. A novice cannot distinguish broken from idle, which
+directly kills the "it remembers me" feeling (memory looks like it vanished). Fixed across 8
+surfaces in P7/D15 Track B (`Promise.allSettled` + explicit error/connecting/reconnect states in
+ApprovalsApp, RoomApp, CommandCenter, Files, Waggle/Events/Timeline). Rule going forward: every
+data surface needs loading / error / empty / populated as four distinct renders — empty must never
+be the fallback for failure.

notes/judge-round1-patterns.md

@@ -0,0 +1,17 @@
+# Judge round 1: self-contradiction kills trust faster than any missing feature
+
+All five personas (novice → senior skeptic) scored "it knows me" at 3-4 NOT because memory
+was weak, but because the surfaces contradicted themselves: "away 10 days" next to "active
+yesterday", the same memory listed twice with two different ages, "No agents yet" while an
+agent demonstrably worked. A memory product visibly misremembering itself reads as lying.
+Three patterns to enforce:
+1. **One source of truth per fact, end to end.** Two components computing "last active"
+   from different stores WILL diverge; machine activity (cron writes) must never count as
+   user activity.
+2. **Empty showcase surfaces actively disprove the pitch.** An Evolution tab with 0 runs
+   and an Agent Center with 0 agents scored "visible agent growth" 2/5 across the board —
+   worse than not having the screens. Either seed them with real product usage or make
+   the empty state tell the story.
+3. **Machine vocabulary is a tax on every persona below developer.** tool_result:,
+   entities/relations, YOLO, raw cron names, unrendered markdown — each one individually
+   "minor", collectively the #1 friction driver (2/5 average).

notes/memory-import-is-the-aha.md

@@ -0,0 +1,10 @@
+# The memory-import step is the first-session "it knows me" moment — protect it
+
+Onboarding was reworked (P2/2D) from a 7-step form with orphaned steps into a 5-step chain whose
+emotional peak is memory-import → memory-review: the user brings a ChatGPT/Claude/Gemini export and
+immediately sees the app articulate who they are. Everything before it must be minimal (who-are-you
+is short, tool-discovery auto-detects), and the step is skippable without guilt (vault may already
+have keys; exports may not exist). Caveat discovered in J-loop verification: returning-user
+auto-complete can skip onboarding entirely on a clean prod install — greeting quality on Home then
+carries the whole "it knows me" burden, so the Home cockpit greeting must work even with a thin
+identity layer.

notes/provenance-not-raw-logs.md

@@ -0,0 +1,10 @@
+# Frame agent self-evolution as provenance badges and benefits, never raw logs
+
+The agent authored skills to disk invisibly; surfacing that as event logs would read as machine
+noise to a novice. The shipped answer (P5/D4): every skill write flows through one
+`skill-write-service.ts` that stamps lossless provenance (initiator/source), and the UI renders it
+as a single calm `agent · review` badge on the skill row — a benefit statement ("your agent built
+this, you can review it"), not a log line. Adversarial review lesson embedded here: sticky
+file-provenance bled into the audit row so an agent editing a user's skill was logged as the user —
+file-author and actor must be decoupled. Same framing applies to cross-workspace knowledge: show
+"learned from your other workspace" badges, never bus traffic.

notes/risk-vocabulary-drift.md

@@ -0,0 +1,10 @@
+# One shared risk vocabulary; drifted enums silently inverted safety UX
+
+Five backend modules each grew their own risk/approval/audit enums. Two real consequences: a
+critical-sorts-below-low RBAC bug (string sort on drifted tiers), and the headline D4(ii) defect —
+the server computed full trust metadata but the FE card type dropped it, so the riskiest approval
+showed the least information. Fix: canonical `@waggle/shared/risk.ts` (widest-set enums +
+`riskRank`), all consumers re-pointed, `critical→critical` behavior-preserving, and "Always allow"
+gated by approvalClass so a critical op can never be permanently granted in one click. Lesson:
+safety UX degrades through type drift, not through missing features — unify vocabulary before
+polishing surfaces.

notes/silent-defaults-over-ratification.md

@@ -0,0 +1,8 @@
+# Ship silent sensible defaults; spend friction only on irreversible actions
+
+Founder-ratified principle from the onboarding/Phase-4 work: do not ask the user to ratify a
+default (e.g. "which tools do you want?" during onboarding). Connector tiles and skill chips ship
+with silent default ordering; capability appears progressively as the user engages. Friction
+(confirmation prompts) is reserved exclusively for irreversible or destructive actions via the
+approval runtime. This is the core of progressive reveal: novices never see a configuration
+decision they can't evaluate; experts fast-path via Ctrl+K instead of toggles.

notes/staged-evidence-catch22.md

@@ -0,0 +1,14 @@
+# Growth evidence cannot be staged — judges detect and penalize the staging
+
+The "visible agent growth" criterion plateaued at 2-3 across three judge rounds because the
+only honest evidence is longitudinal: weeks of evolution runs, agent run history, artifacts
+produced overnight. When I created a real agent via the product an hour before judging, the
+skeptic called it "a prop placed on the set an hour before the audience arrived" — correct,
+and unanswerable. The catch-22: staged evidence scores worse than absent evidence, and real
+evidence takes real calendar time. Consequence for demos and judging loops: ship the
+*pipeline* working (a real run, a real provenance badge) and let empty states tell the story
+honestly ("Your agent improves itself here… nothing changes without you") rather than
+manufacturing history. Also: adversarial no-caveat rubrics (any complaint → ≤4) plus fresh
+panels each round regenerate finer complaints indefinitely — complaint COUNT trends down
+(53→52→40) while scores plateau; treat declining counts, not unanimous top marks, as the
+convergence signal.