feat(desktop): UX philosophy doc + Advanced Mode (chat-first, internals hidden) (#83)

Author: gryszzz

docs/desktop-ux-philosophy.md

@@ -0,0 +1,93 @@
+# OpenThymos Desktop — UX Philosophy
+
+This is the canonical guide for the desktop app's experience. Every desktop PR
+is measured against it.
+
+## The one principle
+
+**Standard AI chat experience first. OpenThymos capabilities second.**
+
+It should feel immediately familiar to anyone who has used ChatGPT, Claude,
+Cursor, LM Studio, or Open WebUI. We do **not** reinvent the chat experience — we
+add governance, replay, and auditability *on top of* a familiar one.
+
+> A premium AI desktop app that happens to have governance — **not** a governance
+> system that happens to have a chat box.
+
+The user chats normally. OpenThymos quietly provides skills, tools, providers,
+grants, replay, and audit **when needed** — never in the user's face by default.
+A user should understand the interface within seconds.
+
+## Default layout
+
+```
+┌───────────────┬───────────────────────────────────────────────┐
+│  + New chat   │   active model · provider · skills (quiet)     │
+│  ⌕ Search     ├───────────────────────────────────────────────┤
+│  Chat history │                                                │
+│   • …         │            conversation                        │
+│   • …         │                                                │
+│               ├───────────────────────────────────────────────┤
+│  Providers    │  [ + ] message…                       [ Send ] │
+│  Skills       │                                                │
+│  Tools        │  optional: provider · skill · model (light)    │
+│  Audit        │                                                │
+│  ⚙ Settings   │                                                │
+└───────────────┴───────────────────────────────────────────────┘
+```
+
+- **Chat is always the primary screen.** It opens to chat.
+- **Sidebar:** New Chat · Search · Chat history. Secondary nav (Providers,
+  Skills, Tools, Audit, Settings) lives below, lightweight.
+- **Composer at the bottom:** prompt · attachments · send. Optional
+  provider/skill/model selectors are *light*, not overwhelming.
+
+## How each capability should feel
+
+- **Skills** — like GPTs / Claude styles / agent profiles. Enable one, several,
+  or none without friction. (Multi-skill is shipped.)
+- **Tools** — capabilities the assistant has. Users never see schemas or
+  internals unless they enter **Advanced Mode**.
+- **Grants** — clean and modern. Plain language, not runtime jargon:
+  > **OpenThymos wants permission to use the File System tool.** `Allow` `Deny`
+  with an *Advanced details* expander, not a wall of writ/policy text.
+- **Replay** — "**View what happened**", not "inspect internal runtime
+  artifacts." Advanced users can expand into commits/writs.
+
+## Visual design
+
+Prioritize: whitespace · readable typography · smooth animation · modern cards ·
+clear icons · clean navigation. Avoid: clutter · developer-only terminology ·
+excessive JSON · overwhelming controls · exposing internals by default.
+
+## Advanced Mode
+
+A single toggle (Settings / header). **Off by default.** When off, normal users
+**never** see raw runtime data, policies, writs, commits, debug traces, or
+low-level tooling. When on, those reveal:
+
+- raw ledger entry data in the Mind inspector and Audit,
+- the custom-tool schema editor and raw skill/policy JSON,
+- writ / commit / proposal internals, debug/perf info,
+- experimental / unstable controls (also gated to Nightly).
+
+Implementation: a `body.advanced` class toggled + persisted; anything
+developer-facing is tagged `.adv-only` (hidden unless Advanced). New
+internals-exposing UI must be `.adv-only` by default.
+
+## Stable vs Nightly
+
+- **Stable** surfaces: multi-skill selection, basic skill/tool builders,
+  provider/model selection, grant cards, replay viewer, the Mind graph.
+- **Nightly / Advanced**: raw JSON editing, experimental automation, debug
+  traces, low-level runtime internals.
+
+## The test for any desktop change
+
+1. Does chat stay the primary, familiar experience?
+2. Is the new power *quiet* until needed?
+3. Would a non-engineer understand it in seconds?
+4. Is anything that exposes internals behind Advanced Mode?
+
+If a change makes the app feel like a governance console, it's wrong — governance
+is the substrate, not the surface.

thymos/clients/desktop/src/index.html

@@ -27,6 +27,9 @@
         <span id="ledger" class="pill">ledger: —</span>
       </div>
       <div class="controls">
+        <label class="adv-toggle" title="Show developer internals — raw ledger data, schemas, writs/commits. Off by default.">
+          <input type="checkbox" id="advToggle" /> Advanced
+        </label>
         <button id="startBtn">Start runtime</button>
         <button id="stopBtn" class="ghost">Stop</button>
       </div>
@@ -40,7 +43,7 @@
       <button class="tab" data-tab="skills">✦ Skills</button>
       <button class="tab" data-tab="tools">▣ Tools</button>
       <button class="tab" data-tab="audit">≡ Audit</button>
-      <button class="tab" data-tab="backups">↧ Backups</button>
+      <button class="tab adv-only" data-tab="backups">↧ Backups</button>
     </nav>
 
     <main>
@@ -276,7 +279,7 @@ <h3>Create / tune a skill</h3>
           <b>before</b> it runs — a tool can never exceed its class.
         </p>
 
-        <details class="addtool">
+        <details class="addtool adv-only">
           <summary><b>＋ Add a custom tool</b> — declare a governed tool (no code)</summary>
           <form id="toolForm" class="card provider-form">
             <div class="starter-row">

thymos/clients/desktop/src/main.js

@@ -48,6 +48,29 @@ document.querySelectorAll(".tab").forEach((btn) => {
   });
 });
 
+/* ---------- Advanced Mode ---------- */
+// Off by default: normal users never see raw runtime data, schemas, writs, or
+// commits. The toggle reveals everything tagged `.adv-only` (see the UX
+// philosophy doc). Persisted locally.
+const ADV_KEY = "thymos.advanced.v1";
+(function initAdvanced() {
+  const on = (() => { try { return localStorage.getItem(ADV_KEY) === "1"; } catch (_) { return false; } })();
+  document.body.classList.toggle("advanced", on);
+  const t = $("advToggle");
+  if (t) {
+    t.checked = on;
+    t.addEventListener("change", () => {
+      document.body.classList.toggle("advanced", t.checked);
+      try { localStorage.setItem(ADV_KEY, t.checked ? "1" : "0"); } catch (_) {}
+      // If an advanced-only tab was active and we just hid it, fall back to Chat.
+      const active = document.querySelector(".tab.active");
+      if (!t.checked && active && active.classList.contains("adv-only")) {
+        document.querySelector('.tab[data-tab="chat"]').click();
+      }
+    });
+  }
+})();
+
 /* ---------- runtime supervision + health ---------- */
 async function refreshStatus() {
   let running = false;

thymos/clients/desktop/src/styles.css

@@ -397,3 +397,14 @@ button.full { width: 100%; }
   border: 1px solid var(--line); border-radius: 6px; padding: 8px;
 }
 .mind-hint { font-size: 12px; margin: 8px 0; }
+
+/* Advanced Mode — developer internals hidden unless toggled (UX philosophy) */
+.adv-only { display: none; }
+body.advanced .adv-only { display: revert; }
+.adv-toggle {
+  display: inline-flex; align-items: center; gap: 5px;
+  font-size: 12px; color: var(--muted); cursor: pointer; user-select: none;
+  padding: 4px 8px; border-radius: 999px; border: 1px solid var(--line);
+}
+.adv-toggle:hover { border-color: var(--violet); color: var(--text); }
+.adv-toggle input { accent-color: var(--violet); margin: 0; }