@runcore-sh/runcore 0.2.1 → 0.2.2

package/brain-template/knowledge/notes/tier-gated-ui-spec.md

@@ -0,0 +1,187 @@
+# Tier-Gated UI
+
+> Status: **Approved by Dash**
+> Created: 2026-03-08
+
+## Problem
+
+A fresh `npx @runcore-sh/runcore` install shows the full settings panel — mesh config, LLM providers, voice settings, Google Workspace, Linear board integration, service registry, API key vault, and navigation to observatory, ops, roadmap, registry pages. None of these work on local tier. The UI promises capabilities the system cannot deliver.
+
+Worse: the UI implies infrastructure connectivity that doesn't exist. A fresh local install is a stranger — no bond, no governance, no membrane, no trust chain. The interface should reflect that.
+
+## Principle
+
+**The UI is a symptom of unresolved autonomy.** If the system can't do it, the button shouldn't exist. Progressive disclosure applies to UI surfaces the same way it applies to brain context — show what's relevant, hide what isn't, unlock as capability grows.
+
+## Tier Capability Matrix
+
+| Capability | Local | BYOK | Spawn | Hosted |
+|---|---|---|---|---|
+| Chat | yes | yes | yes | yes |
+| Brain (memory, knowledge) | yes | yes | yes | yes |
+| Ollama (local inference) | yes | yes | yes | yes |
+| Identity (name, personality) | yes | yes | yes | yes |
+| Safe word | yes | yes | yes | yes |
+| HTTP server + UI | yes | yes | yes | yes |
+| API key vault | no | yes | yes | yes |
+| Cloud LLM providers | no | yes | yes | yes |
+| Mesh (LAN discovery) | no | yes | yes | yes |
+| Voice (TTS/STT) | no | yes | yes | yes |
+| Integrations (Google, Linear, etc.) | no | yes | yes | yes |
+| Service registry | no | yes | yes | yes |
+| Agent spawning | no | no | yes | yes |
+| Governance (vouchers, policies) | no | no | yes | yes |
+| Alerting (SMS, email, webhook) | no | no | yes | yes |
+| Observatory (system metrics) | no | no | yes | yes |
+
+## UI Surface by Tier
+
+### Local Tier (fresh install)
+
+**Header nav:** None. No page links. Just the agent name and the chat.
+
+**Settings panel shows:**
+- Agent name (editable)
+- Personality / custom rules
+- Safe word mode
+- Ollama model selection (local models only)
+- Airplane mode toggle (locked ON, greyed out with "Local tier" label)
+
+**Settings panel hides:**
+- Mesh settings section
+- LLM provider section (OpenRouter, API keys)
+- Voice settings section
+- Google Workspace section
+- Task board / Linear section
+- Key vault section
+- "Manage Services & Capabilities" link
+
+**Pages accessible:** `/` (chat) only. All other pages return 404 or redirect to `/`.
+
+**Upgrade prompt:** Small, non-intrusive text at bottom of settings: "Unlock cloud models, voice, and integrations → `runcore register`"
+
+### BYOK Tier
+
+**Header nav:** `/library`, `/life`
+
+**Settings panel adds:**
+- API key vault
+- LLM provider selection (cloud models)
+- Airplane mode toggle (now functional)
+- Voice settings (if sidecar detected)
+- Integrations section (Google, Linear, etc.)
+- "Manage Services" link → `/registry`
+
+**Pages accessible:** `/`, `/library`, `/life`, `/registry`, `/help`
+
+### Spawn Tier
+
+**Header nav:** Full nav — `/library`, `/personal`, `/life`, `/registry`, `/observatory`, `/ops`, `/board`, `/roadmap`
+
+**Settings panel adds:**
+- Mesh settings (LAN announce, allow incoming)
+- Agent spawning controls
+- Governance dashboard link
+
+**Pages accessible:** All pages.
+
+### Hosted Tier
+
+Same as Spawn. No additional UI — hosted is about who runs the infrastructure, not what the UI shows.
+
+## Implementation
+
+### 1. Server: expose tier to client
+
+**Route:** `GET /api/tier` (already partially exists via settings)
+
+Response:
+```json
+{
+  "tier": "local",
+  "capabilities": {
+    "brain": true,
+    "ollama": true,
+    "server": true,
+    "ui": true,
+    "vault": false,
+    "mesh": false,
+    "spawning": false,
+    "governance": false,
+    "alerting": false,
+    "voice": false,
+    "integrations": false
+  }
+}
+```
+
+### 2. Client: fetch tier on load, gate UI
+
+On page load (after auth), fetch `/api/tier`. Store in `window.__TIER__`.
+
+Each settings section gets a `data-requires` attribute:
+```html
+<div id="mesh-settings-section" data-requires="mesh">
+<div id="llm-settings-section" data-requires="vault">
+<div id="voice-settings-section" data-requires="voice">
+<div id="google-settings-section" data-requires="integrations">
+<div id="board-settings-section" data-requires="integrations">
+```
+
+On tier load:
+```javascript
+function applyTierGating(caps) {
+  document.querySelectorAll('[data-requires]').forEach(el => {
+    const cap = el.dataset.requires;
+    if (!caps[cap]) el.remove();  // remove, not hide — don't tease
+  });
+}
+```
+
+### 3. Navigation: tier-gated links
+
+```javascript
+const NAV_BY_TIER = {
+  local:  [],
+  byok:   ['library', 'life', 'registry', 'help'],
+  spawn:  ['library', 'personal', 'life', 'registry', 'observatory', 'ops', 'board', 'roadmap'],
+  hosted: ['library', 'personal', 'life', 'registry', 'observatory', 'ops', 'board', 'roadmap'],
+};
+```
+
+Build nav dynamically from this map. No hardcoded links in HTML.
+
+### 4. Page-level gating
+
+Each sub-page (library.html, ops.html, etc.) also fetches `/api/tier` and redirects to `/` if the tier doesn't support it. Defense in depth — even if someone types the URL directly.
+
+### 5. Settings.json template cleanup
+
+The brain-template `settings.json` should reflect local tier defaults:
+
+```json
+{
+  "airplaneMode": true,
+  "models": { "chat": "auto", "utility": "auto" },
+  "encryptBrainFiles": false,
+  "safeWordMode": "always",
+  "instanceName": "Core",
+  "integrations": { "enabled": false, "services": {} }
+}
+```
+
+No TTS/STT/avatar/backup/pulse/mesh config — those get created when the tier unlocks them.
+
+## What This Does NOT Change
+
+- The server still boots all routes regardless of tier (defense in depth is at the UI and middleware level, not route registration)
+- The `requireSurface()` middleware already gates some pages — this complements it
+- Tier upgrades take effect immediately without restart (client re-fetches `/api/tier`)
+- The brain-template stays minimal — no personal data, no service configs
+
+## Verification
+
+1. Fresh `npx @runcore-sh/runcore` → chat screen only, minimal settings, no nav links
+2. `runcore register` + `runcore activate <token>` → settings expand, nav appears
+3. Direct URL to `/ops` on local tier → redirects to `/`
+4. Settings panel never shows capabilities the tier can't deliver

package/brain-template/settings.json

@@ -1,60 +1,14 @@
 {
-  "airplaneMode": false,
-  "privateMode": false,
+  "airplaneMode": true,
   "models": {
     "chat": "auto",
     "utility": "auto"
   },
   "encryptBrainFiles": false,
   "safeWordMode": "always",
-  "tts": {
-    "enabled": false,
-    "port": 3579,
-    "voice": "en_US-lessac-medium",
-    "autoPlay": true
-  },
-  "stt": {
-    "enabled": false,
-    "port": 3580,
-    "model": "ggml-base.en.bin"
-  },
-  "avatar": {
-    "enabled": false,
-    "port": 3581,
-    "musetalkPath": "",
-    "photoPath": "public/avatar/photo.png"
-  },
-  "backup": {
-    "enabled": false,
-    "schedule": "daily",
-    "providers": [
-      "local"
-    ],
-    "localBackupDir": ".core-backups",
-    "maxBackups": 7,
-    "backupHour": 3
-  },
-  "pulse": {
-    "threshold": 60,
-    "mode": "hybrid"
-  },
-  "mesh": {
-    "lanAnnounce": false,
-    "allowIncoming": false
-  },
   "instanceName": "Core",
   "integrations": {
-    "enabled": true,
-    "services": {
-      "google": false,
-      "github": true,
-      "slack": false,
-      "twilio": false,
-      "resend": true,
-      "openai": true,
-      "anthropic": true,
-      "openrouter": true,
-      "perplexity": false
-    }
+    "enabled": false,
+    "services": {}
   }
 }

package/dictionary.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.2.1",
-  "publishedAt": "2026-03-08T00:50:24.384Z",
+  "version": "0.2.2",
+  "publishedAt": "2026-03-08T01:08:29.667Z",
   "specs": [],
   "glossary": {
     "brain": "The local file-based data store for an instance. Always local. Never hosted.",

package/dist/instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAUvC;AAED,kEAAkE;AAClE,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE7D;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAEpD"}
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAWvC;AAED,kEAAkE;AAClE,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE7D;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAEpD"}

package/dist/instance.js

@@ -15,8 +15,9 @@ export function initInstanceName() {
     try {
         const raw = readFileSync(join(BRAIN_DIR, "settings.json"), "utf-8");
         const parsed = JSON.parse(raw);
-        if (typeof parsed.instanceName === "string" && parsed.instanceName.trim()) {
-            instanceName = parsed.instanceName.trim();
+        const name = parsed.instanceName ?? parsed.agentName;
+        if (typeof name === "string" && name.trim()) {
+            instanceName = name.trim();
         }
     }
     catch {

package/dist/instance.js.map

@@ -1 +1 @@
-{"version":3,"file":"instance.js","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,IAAI,YAAY,GAAG,MAAM,CAAC;AAE1B;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,EAAE,OAAO,CAAC,CAAC;QACpE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1E,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;QAC5C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,eAAe;IAC7B,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,MAAM,EAAE,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,MAAM,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC,kBAAkB,CAAC,IAAI,GAAG,oBAAoB,EAAE,YAAY,CAAC;AACjF,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"instance.js","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,IAAI,YAAY,GAAG,MAAM,CAAC;AAE1B;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,EAAE,OAAO,CAAC,CAAC;QACpE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,SAAS,CAAC;QACrD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAC5C,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,eAAe;IAC7B,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,MAAM,EAAE,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,MAAM,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC,kBAAkB,CAAC,IAAI,GAAG,oBAAoB,EAAE,YAAY,CAAC;AACjF,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACtC,CAAC"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuTH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AA2gKD,iBAAe,KAAK,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,iBAAiB,EAAE,QAAQ,CAAA;CAAE,iBAghBxE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuTH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAyhKD,iBAAe,KAAK,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,iBAAiB,EAAE,QAAQ,CAAA;CAAE,iBAihBxE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/server.js

@@ -344,7 +344,7 @@ async function getOrCreateChatSession(sessionId, name) {
     chatSessions.set(sessionId, cs);
     return cs;
 }
-// --- App ---
+let activeTier = "local";
 const app = new Hono();
 // Global error handler — return JSON with details instead of plain "Internal Server Error"
 app.onError((err, c) => {
@@ -459,6 +459,15 @@ app.get("/api/status", async (c) => {
         agentName: settings.agentName || "Core",
     });
 });
+// Tier: current tier + capability matrix for UI gating
+app.get("/api/tier", async (c) => {
+    const { TIER_CAPS } = await import("./tier/types.js");
+    const tier = activeTier;
+    return c.json({
+        tier,
+        capabilities: TIER_CAPS[tier] ?? TIER_CAPS.local,
+    });
+});
 // Pairing ceremony
 app.post("/api/pair", async (c) => {
     const body = await c.req.json();
@@ -482,6 +491,7 @@ app.post("/api/pair", async (c) => {
             const settingsPath = join(BRAIN_DIR, "settings.json");
             const raw = await readFile(settingsPath, "utf-8");
             const settings = JSON.parse(raw);
+            settings.instanceName = agentName.trim();
             settings.agentName = agentName.trim();
             await writeFile(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
         }
@@ -4916,6 +4926,7 @@ app.post("/api/import/files", async (c) => {
 // --- Startup ---
 async function start(opts) {
     const tier = opts?.tier ?? "byok";
+    activeTier = tier;
     const tierGate = await import("./tier/gate.js");
     // Initialize instance name before anything else
     initInstanceName();