discoclaw 1.1.0 → 1.1.1

package/.context/pa.md

@@ -4,25 +4,7 @@ Generic PA rules. Personal customizations go in `workspace/AGENTS.md`.
 
 ## Self-Awareness
 
-You are a DiscoClaw bot — a personal AI orchestrator that coordinates between Discord, AI runtimes, and local system resources. You don't contain the intelligence yourself; the orchestrator decides when to call you, what context to give you, and what to do with your output.
-For architecture details, see `.context/architecture.md`.
-
-## Workspace Files
-
-| File | Purpose | Owner | Loaded |
-|------|---------|-------|--------|
-| `SOUL.md` | Core personality and values | User | Every prompt |
-| `IDENTITY.md` | Name and vibe | User | Every prompt |
-| `USER.md` | Who you're helping | User | Every prompt |
-| `templates/instructions/SYSTEM_DEFAULTS.md` | Tracked default instructions (runtime-injected) | Discoclaw repo (tracked) | Every prompt |
-| `AGENTS.md` | Personal rules and preferences | User (never overwritten) | Every prompt |
-| `TOOLS.md` | Available tools and integrations | Discoclaw | Every prompt |
-| `MEMORY.md` | Curated long-term memory | User | DM prompts |
-| `BOOTSTRAP.md` | First-run onboarding (deleted after) | User | Once |
-
-Templates live in `templates/workspace/` and are scaffolded on first run (copy-if-missing).
-Tracked defaults come from `templates/instructions/SYSTEM_DEFAULTS.md` and are injected at runtime.
-Legacy `workspace/DISCOCLAW.md` files are not authoritative.
+You are a DiscoClaw bot — a personal AI orchestrator coordinating Discord, AI runtimes, and local system resources.
 
 ## Operational Essentials
 
@@ -41,74 +23,30 @@ Legacy `workspace/DISCOCLAW.md` files are not authoritative.
 
 ## Group Chat Etiquette
 
-You have access to your human's stuff. That doesn't mean you share it.
-In groups, you're a participant — not their voice, not their proxy.
+You're a participant, not the user's proxy. Don't share their private info.
 
-**Respond when:**
-- Directly mentioned or asked a question
-- You can add genuine value (info, insight, help)
-- Something witty/funny fits naturally
-- Correcting important misinformation
+**Respond** to direct mentions, genuine questions, chances to add value, or natural humor/corrections.
+**Stay silent (HEARTBEAT_OK)** for casual banter, already-answered questions, "yeah/nice" responses, or when adding a message would interrupt flow.
 
-**Stay silent (HEARTBEAT_OK) when:**
-- It's just casual banter between humans
-- Someone already answered the question
-- Your response would just be "yeah" or "nice"
-- The conversation is flowing fine without you
-- Adding a message would interrupt the vibe
-
-**The human rule:** Humans don't respond to every message. Neither should you.
-Quality > quantity. Avoid the triple-tap (don't respond multiple times to the same message).
+Humans don't respond to every message — neither should you. Quality > quantity. No triple-taps.
 
 ### Reactions
 
-Use emoji reactions naturally — they're lightweight social signals:
-- Appreciate something but don't need to reply (thumbs up, heart)
-- Something made you laugh (laughing face, skull)
-- Acknowledge without interrupting flow (checkmark, eyes)
-- One reaction per message max.
-
-When someone reacts to a message, acknowledge it with a brief response.
-Reactions are a form of communication — treat them like a tap on the shoulder.
-
-Participate, don't dominate.
+Use emoji reactions as lightweight social signals (appreciate, laugh, acknowledge). One per message max. Acknowledge reactions on your messages briefly.
 
 ## Memory
 
-Your prompt may include two memory sections injected by the system:
-
-**Durable memory** — Persistent facts/preferences about the user that survive across sessions.
-Treat as ground truth unless explicitly contradicted. Don't repeat them back unprompted.
-
-**Conversation memory** — Rolling summary of recent conversation. Lossy and compressed.
-If it conflicts with recent messages, trust the recent messages.
-
-Memory commands (handled by the system, not you):
-- `!memory` or `!memory show` — see stored items + rolling summary
-- `!memory remember <text>` — store a new fact
-- `!memory forget <text>` — remove matching items
-- `!memory reset rolling` — clear the rolling summary
-
-See `.context/memory.md` for full architecture, examples, and config reference.
+Your prompt may include:
+- **Durable memory** — Persistent user facts/preferences. Treat as ground truth unless contradicted.
+- **Conversation memory** — Rolling summary, lossy. Trust recent messages over summary if they conflict.
 
 ## Autonomy Tiers
 
-### Always OK (no permission needed)
-- Read files, explore, search the web, run diagnostics
-- Send Discord messages, react with emoji
-- Share finds in relevant channels, report back on async tasks
-- Work within the workspace
+**Always OK:** Read files, explore, search web, run diagnostics, send Discord messages, react, share finds, work within workspace.
 
-### Act Then Notify (time-sensitive)
-- For **confirmed, active** security threats: take reversible protective actions, then notify
-- For ambiguous threats: alert first, wait for decision
+**Act Then Notify:** Confirmed active security threats — take reversible action, then notify. Ambiguous threats — alert first.
 
-### Always Ask First
-- External communications (emails, messages to others, posting on someone's behalf)
-- Changes to the user's creative projects
-- System changes (package installs, systemd modifications, firewall/network)
-- Destructive actions (deleting files, dropping databases, revoking credentials)
-- Anything involving money
+**Always Ask:** External communications, creative project changes, system changes (packages, systemd, network), destructive actions, anything involving money.
 
 ## Execution Policy (Local Machine)
 
@@ -116,13 +54,3 @@ See `.context/memory.md` for full architecture, examples, and config reference.
 - Ask before: destructive ops, system-wide changes
 - Never retry sudo. If auth is needed, give the user the command to run.
 
-## Customization
-
-Instruction precedence is deterministic:
-1. immutable security policy (`ROOT_POLICY`)
-2. tracked defaults (`templates/instructions/SYSTEM_DEFAULTS.md`)
-3. `workspace/AGENTS.md` overrides
-4. memory/context sections
-
-Customize behavior in `workspace/AGENTS.md` (user-owned, never overwritten).
-Do not rely on `workspace/DISCOCLAW.md`; defaults are sourced from the tracked template and injected at runtime.

package/dist/canvas/canvas-action.js

@@ -12,15 +12,9 @@ const CANVAS_VOID_ELEMENT_TAG_RE = /<(area|base|br|col|embed|hr|img|input|link|m
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const CANVAS_PROMPT_TEMPLATE_PATH = path.resolve(__dirname, '..', '..', 'templates', 'instructions', 'canvas.md');
-const CANVAS_EXPERIMENTAL_POSTURE_NOTE = [
-    'Canvas Activities are experimental and default-off in DiscoClaw.',
-    'Fresh installs and upgraded installs both require an explicit opt-in via `DISCOCLAW_CANVAS_ENABLED=1`, followed by a bot restart.',
-].join(' ');
-const DEFAULT_SAVE_BRIDGE_GUIDANCE = [
-    '- Save-file export is available through the trusted shell bridge when enabled.',
-    '- To export a file from inside the artifact, post a message to the parent shell:',
-    '  `window.parent.postMessage({ type: "canvas.saveFile", suggestedName: "report.md", mimeType: "text/markdown", encoding: "utf8", content: "# Report" }, "*")`',
-].join('\n');
+const CANVAS_SETUP_POSTURE_NOTE = 'Canvas Activities are experimental and default-off in DiscoClaw.' +
+    ' Fresh installs and upgraded installs both require an explicit opt-in via `DISCOCLAW_CANVAS_ENABLED=1`, followed by a bot restart.';
+const DEFAULT_SAVE_BRIDGE_GUIDANCE = '- Save-file export: `window.parent.postMessage({ type: "canvas.saveFile", suggestedName: "report.md", mimeType: "text/markdown", encoding: "utf8", content: "..." }, "*")`';
 let cachedCanvasPromptTemplate = null;
 export const CANVAS_ACTION_TYPES = new Set(['launchCanvas']);
 export const CANVAS_LAUNCH_COMPONENT_PREFIX = 'canvas:launch:';
@@ -57,7 +51,7 @@ export function buildCanvasSetupRequiredStub(canvasCtx) {
             'Enable Activities on the Discord application in the Developer Portal (Application → Activities → Enable). Requires the URL Mapping first.',
         ],
     };
-    return [CANVAS_EXPERIMENTAL_POSTURE_NOTE, buildCanvasSetupWalkthrough(readiness)].join(' ');
+    return [CANVAS_SETUP_POSTURE_NOTE, buildCanvasSetupWalkthrough(readiness)].join(' ');
 }
 export function shouldCanvasPromptBeSurfaced(canvasCtx, userText) {
     if (!canvasCtx?.enabled)
@@ -281,49 +275,7 @@ function findCanvasArtifactLintError(content) {
 function loadCanvasPromptTemplate() {
     if (cachedCanvasPromptTemplate != null)
         return cachedCanvasPromptTemplate;
-    try {
-        cachedCanvasPromptTemplate = fs.readFileSync(CANVAS_PROMPT_TEMPLATE_PATH, 'utf8').trim();
-    }
-    catch {
-        cachedCanvasPromptTemplate = [
-            '### Canvas Activities',
-            '',
-            '**launchCanvas** — Generate and serve an interactive HTML artifact or built-in app in a Discord Activity panel:',
-            '```',
-            '<discord-action>{"type":"launchCanvas","title":"Tax Calculator","content":"<!doctype html><html><head><meta charset=\\"utf-8\\" /><meta name=\\"viewport\\" content=\\"width=device-width,initial-scale=1\\" /><style>body{font-family:sans-serif;padding:16px}label,input{display:block;margin-top:12px}</style></head><body><div id=\\"app\\"></div><script>const { html, render, useState } = window.canvasRuntime;function TaxCalculator(){const [income,setIncome]=useState(50000);const tax=Math.round(income*0.22);return html`<main><h1>Tax Calculator</h1><label>Income <input type=\\"number\\" value=${income} onInput=${(event)=>setIncome(Number(event.currentTarget.value||0))} /></label><p>Estimated tax: $${tax.toLocaleString()}</p></main>`;}render(TaxCalculator, document.getElementById(\\"app\\"));</script></body></html>"}</discord-action>',
-            '<discord-action>{"type":"launchCanvas","title":"Dashboard","app":"dashboard"}</discord-action>',
-            '```',
-            '- `title` (required): Human-readable label for the launch button.',
-            '- `content` (artifact mode): Full self-contained HTML document with all CSS and JS inline.',
-            '- `app` (built-in mode): Named built-in Activity app such as `dashboard`.',
-            '- Use canvas only when interactivity materially improves the result over plain text.',
-            '- Default is plain text. Do not use canvas for short answers, conversational replies, or single values.',
-            '- Good fits: calculators, forms, charts, diffs, large comparison views, filterable tables, live dashboard launches.',
-            '- Bad fits: simple status updates, brief explanations, or anything the user explicitly wants as plain text.',
-            '- Artifact render responses inject `window.canvasRuntime`; use that built-in runtime instead of bundling React, Preact, Vue, or another UI framework.',
-            '- The injected runtime exposes `html`, `render`, and the installed `preact/hooks` surface: `useState`, `useEffect`, `useLayoutEffect`, `useReducer`, `useRef`, `useMemo`, `useCallback`, `useContext`, `useImperativeHandle`, `useDebugValue`, `useErrorBoundary`, and `useId`.',
-            '- Start interactive artifacts with `const { html, render, useState } = window.canvasRuntime`; keep the starter small unless the artifact actually needs more hook surface, and mount into a dedicated root node.',
-            '- In `html` template literals, self-close void HTML elements: use `<input ... />`, `<img ... />`, `<br />`, etc. Bare `<input>` tags can corrupt the rendered DOM in canvas artifacts.',
-            '- Generated artifacts must be a single HTML file, responsive at phone width, and keep total size under roughly 500KB.',
-            '- No external scripts, stylesheets, fonts, images, or nested iframes in generated artifacts.',
-            '- Generated artifacts run inside a sandboxed iframe and cannot call backend routes directly.',
-            '- Artifacts are stored under a cap-based LRU policy; they are not time-expired in v1.',
-            '- Include visible loading/error/fallback states when the UI depends on JavaScript.',
-            '- Default visual direction: feel at home in Discord without mimicking Discord\'s UI chrome.',
-            '- Favor Discord-adjacent contrast and restraint for dark surroundings, but choose colors and themes based on the content instead of cloning Discord\'s palette by default.',
-            '- Use explicitly Discord-like styling only when the user asks for a native/control-panel/admin-tool feel.',
-            '- Prefer semantic HTML, clear contrast, and obvious focus states.',
-            '{{CANVAS_SAVE_BRIDGE_GUIDANCE}}',
-        ].join('\n');
-    }
-    if (!cachedCanvasPromptTemplate.includes(CANVAS_EXPERIMENTAL_POSTURE_NOTE)) {
-        if (cachedCanvasPromptTemplate.startsWith('### Canvas Activities')) {
-            cachedCanvasPromptTemplate = cachedCanvasPromptTemplate.replace('### Canvas Activities', `### Canvas Activities\n\n${CANVAS_EXPERIMENTAL_POSTURE_NOTE}`);
-        }
-        else {
-            cachedCanvasPromptTemplate = `${CANVAS_EXPERIMENTAL_POSTURE_NOTE}\n\n${cachedCanvasPromptTemplate}`;
-        }
-    }
+    cachedCanvasPromptTemplate = fs.readFileSync(CANVAS_PROMPT_TEMPLATE_PATH, 'utf8').trim();
     return cachedCanvasPromptTemplate;
 }
 function buildLaunchActivityFailureMessage(err) {

package/dist/canvas/canvas-action.test.js

@@ -1,5 +1,4 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -81,13 +80,11 @@ async function makeCanvasContext() {
     return canvasCtx;
 }
 describe('canvas-action', () => {
-    it('surfaces the injected canvas runtime contract from the checked-in prompt template', async () => {
+    it('surfaces the canvas runtime contract from the checked-in prompt template', async () => {
         vi.resetModules();
         const { canvasActionsPromptSection } = await import('./canvas-action.js');
         const prompt = canvasActionsPromptSection({ writeBridgeEnabled: true });
         expect(prompt).toContain('experimental and default-off');
-        expect(prompt).toContain('DISCOCLAW_CANVAS_ENABLED=1');
-        expect(prompt).toContain('Fresh installs and upgraded installs both require an explicit opt-in');
         expect(prompt).toContain('window.canvasRuntime');
         expect(prompt).toContain('installed `preact/hooks` surface');
         expect(prompt).toContain('`useLayoutEffect`');
@@ -96,36 +93,27 @@ describe('canvas-action', () => {
         expect(prompt).toContain('Bare `<input>` tags can corrupt the rendered DOM');
         expect(prompt).toContain('feel at home in Discord without mimicking Discord');
         expect(prompt).toContain('instead of cloning Discord\'s palette by default');
+        expect(prompt).toContain('canvas.saveFile');
+        expect(prompt).not.toContain('{{CANVAS_SAVE_BRIDGE_GUIDANCE}}');
     });
-    it('documents the injected canvas runtime in fallback prompt text and preserves save-bridge substitution', async () => {
+    it('omits save-bridge guidance when writeBridgeEnabled is false', async () => {
         vi.resetModules();
-        vi.spyOn(fsSync, 'readFileSync').mockImplementation(() => {
-            throw new Error('template unavailable');
-        });
         const { canvasActionsPromptSection } = await import('./canvas-action.js');
-        const withSaveBridge = canvasActionsPromptSection({ writeBridgeEnabled: true });
-        expect(withSaveBridge).toContain('experimental and default-off');
-        expect(withSaveBridge).toContain('DISCOCLAW_CANVAS_ENABLED=1');
-        expect(withSaveBridge).toContain('Fresh installs and upgraded installs both require an explicit opt-in');
-        expect(withSaveBridge).toContain('window.canvasRuntime');
-        expect(withSaveBridge).toContain('installed `preact/hooks` surface');
-        expect(withSaveBridge).toContain('`useErrorBoundary`');
-        expect(withSaveBridge).toContain('const { html, render, useState } = window.canvasRuntime');
-        expect(withSaveBridge).toContain('self-close void HTML elements');
-        expect(withSaveBridge).toContain('feel at home in Discord without mimicking Discord');
-        expect(withSaveBridge).toContain('canvas.saveFile');
-        expect(withSaveBridge).not.toContain('{{CANVAS_SAVE_BRIDGE_GUIDANCE}}');
         const withoutSaveBridge = canvasActionsPromptSection({ writeBridgeEnabled: false });
         expect(withoutSaveBridge).toContain('experimental and default-off');
-        expect(withoutSaveBridge).toContain('DISCOCLAW_CANVAS_ENABLED=1');
         expect(withoutSaveBridge).toContain('window.canvasRuntime');
         expect(withoutSaveBridge).toContain('installed `preact/hooks` surface');
-        expect(withoutSaveBridge).toContain('`useId`');
         expect(withoutSaveBridge).toContain('Bare `<input>` tags can corrupt the rendered DOM');
-        expect(withoutSaveBridge).toContain('instead of cloning Discord\'s palette by default');
         expect(withoutSaveBridge).not.toContain('canvas.saveFile');
         expect(withoutSaveBridge).not.toContain('{{CANVAS_SAVE_BRIDGE_GUIDANCE}}');
     });
+    it('does not inject the setup posture note into the prompt template', async () => {
+        vi.resetModules();
+        const { canvasActionsPromptSection } = await import('./canvas-action.js');
+        const prompt = canvasActionsPromptSection({ writeBridgeEnabled: true });
+        expect(prompt).not.toContain('DISCOCLAW_CANVAS_ENABLED=1');
+        expect(prompt).not.toContain('Fresh installs and upgraded installs both require an explicit opt-in');
+    });
     it('describes canvas setup as experimental and explicit opt-in', async () => {
         vi.resetModules();
         const { buildCanvasSetupRequiredStub } = await import('./canvas-action.js');

package/dist/instructions/system-defaults.js

@@ -8,6 +8,56 @@ export const TRACKED_DEFAULTS_FILE_NAME = 'SYSTEM_DEFAULTS.md';
 export const TRACKED_DEFAULTS_SECTION_LABEL = 'SYSTEM_DEFAULTS.md (tracked defaults)';
 let cachedPath = null;
 let cachedPreamble = null;
+/**
+ * Sections dropped from the tracked defaults because they are
+ * duplicated, unreachable after bootstrap, or rarely needed.
+ */
+const DROPPED_DEFAULTS_SECTIONS = new Set([
+    'Runtime Instruction Precedence',
+    'First Run',
+    'Runtime Registry',
+    'Bot Setup Assistance',
+    'Knowledge Cutoff Awareness',
+]);
+function splitTopLevelSections(content) {
+    const prelude = [];
+    const sections = [];
+    let current = null;
+    for (const line of content.trimEnd().split('\n')) {
+        if (line.startsWith('## ')) {
+            current = { heading: line.slice(3).trim(), lines: [line] };
+            sections.push(current);
+            continue;
+        }
+        if (current) {
+            current.lines.push(line);
+        }
+        else {
+            prelude.push(line);
+        }
+    }
+    return { prelude, sections };
+}
+function joinDefaultsContent(parts) {
+    return parts
+        .map((part) => part.trimEnd())
+        .filter((part) => part.length > 0)
+        .join('\n\n')
+        .trimEnd();
+}
+/**
+ * Filter tracked defaults content by dropping rarely-needed sections
+ * and stripping meta-descriptive blockquotes from the prelude.
+ */
+export function buildPromptSafeDefaultsContent(content) {
+    const { prelude, sections } = splitTopLevelSections(content);
+    const filteredPrelude = prelude.filter((line) => !line.startsWith('> '));
+    const filteredSections = sections.filter((section) => !DROPPED_DEFAULTS_SECTIONS.has(section.heading));
+    return joinDefaultsContent([
+        filteredPrelude.join('\n'),
+        ...filteredSections.map((section) => section.lines.join('\n')),
+    ]);
+}
 /**
  * Resolve the tracked system-default file path from this module's location.
  * Works in both src/* and dist/* layouts.
@@ -36,7 +86,7 @@ export function loadTrackedDefaultsPreamble(opts) {
     let defaultsPreamble = '';
     try {
         const content = fsSync.readFileSync(trackedDefaultsPath, 'utf-8');
-        defaultsPreamble = renderTrackedDefaultsSection(content);
+        defaultsPreamble = renderTrackedDefaultsSection(buildPromptSafeDefaultsContent(content));
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/instructions/system-defaults.test.js

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { TRACKED_DEFAULTS_DIR, TRACKED_DEFAULTS_FILE_NAME, TRACKED_DEFAULTS_SECTION_LABEL, _resetTrackedDefaultsCacheForTests, loadTrackedDefaultsPreamble, renderTrackedDefaultsSection, resolveTrackedDefaultsPath, } from './system-defaults.js';
+import { TRACKED_DEFAULTS_DIR, TRACKED_DEFAULTS_FILE_NAME, TRACKED_DEFAULTS_SECTION_LABEL, _resetTrackedDefaultsCacheForTests, buildPromptSafeDefaultsContent, loadTrackedDefaultsPreamble, renderTrackedDefaultsSection, resolveTrackedDefaultsPath, } from './system-defaults.js';
 describe('resolveTrackedDefaultsPath', () => {
     it('resolves to templates/instructions/SYSTEM_DEFAULTS.md by default', async () => {
         const resolved = resolveTrackedDefaultsPath();
@@ -28,6 +28,31 @@ describe('renderTrackedDefaultsSection', () => {
         expect(renderTrackedDefaultsSection('\n   \n')).toBe('');
     });
 });
+describe('buildPromptSafeDefaultsContent', () => {
+    it('drops rarely-needed sections from the tracked defaults template', async () => {
+        const content = await fs.readFile(resolveTrackedDefaultsPath(), 'utf-8');
+        const sanitized = buildPromptSafeDefaultsContent(content);
+        // Dropped sections
+        expect(sanitized).not.toContain('## Runtime Instruction Precedence');
+        expect(sanitized).not.toContain('## First Run');
+        expect(sanitized).not.toContain('## Runtime Registry');
+        expect(sanitized).not.toContain('## Bot Setup Assistance');
+        expect(sanitized).not.toContain('## Knowledge Cutoff Awareness');
+        // Sections that should survive filtering
+        expect(sanitized).toContain('## Search Before Asking');
+        expect(sanitized).toContain('## Tool Use First');
+        expect(sanitized).toContain('## Discord Action Grounding');
+        expect(sanitized).toContain('## Response Economy');
+        expect(sanitized).toContain('## Landing the Plane');
+    });
+    it('strips blockquote lines from the prelude', () => {
+        const content = '# Title\n\n> Meta description\n> Second line\n\n## Kept\nContent';
+        const sanitized = buildPromptSafeDefaultsContent(content);
+        expect(sanitized).not.toContain('> Meta description');
+        expect(sanitized).toContain('# Title');
+        expect(sanitized).toContain('## Kept');
+    });
+});
 describe('loadTrackedDefaultsPreamble', () => {
     const dirs = [];
     afterEach(async () => {
@@ -74,6 +99,18 @@ describe('loadTrackedDefaultsPreamble', () => {
         expect(reloaded).toContain('second version');
         expect(reloaded).not.toBe(first);
     });
+    it('sanitizes the default tracked template before rendering it into the preamble', () => {
+        const preamble = loadTrackedDefaultsPreamble({
+            trackedDefaultsPath: resolveTrackedDefaultsPath(),
+            forceReload: true,
+        });
+        expect(preamble).toContain(`--- ${TRACKED_DEFAULTS_SECTION_LABEL} ---`);
+        expect(preamble).not.toContain('## Runtime Instruction Precedence');
+        expect(preamble).not.toContain('## Runtime Registry');
+        expect(preamble).not.toContain('## Bot Setup Assistance');
+        expect(preamble).toContain('## Search Before Asking');
+        expect(preamble).toContain('## Tool Use First');
+    });
     it('invalidates cache when the tracked defaults path changes', async () => {
         const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tracked-defaults-'));
         dirs.push(dir);

package/dist/instructions/tracked-tools.js

@@ -13,6 +13,9 @@ let cachedContent = null;
 const DROPPED_TOP_LEVEL_SECTIONS = new Set([
     'Browser Automation (agent-browser)',
     'Service Operations (discoclaw)',
+    'Runtime Instruction Precedence',
+    'Webhook Server',
+    'Plan-Audit-Implement Workflow',
 ]);
 const WEBHOOK_TOOL_ACCESS_SENTENCE = 'webhook jobs run without Discord action permissions or tool access.';
 const AUDITED_RUNTIME_TOOL_GUARANTEES_HEADING = 'Audited Runtime Tool Guarantees';
@@ -125,8 +128,9 @@ export function buildPromptSafeTrackedToolsContent(content, ctx) {
             filteredSections.splice(precedenceIndex + 1, 0, auditedGuarantees);
         }
     }
+    const filteredPrelude = prelude.filter((line) => !line.startsWith('> '));
     return joinTrackedToolsContent([
-        prelude.join('\n'),
+        filteredPrelude.join('\n'),
         ...filteredSections.map((section) => section.lines.join('\n')),
     ]);
 }

package/dist/instructions/tracked-tools.test.js

@@ -34,12 +34,14 @@ describe('buildPromptSafeTrackedToolsContent', () => {
     it('drops unsupported static tool-restriction sections from the tracked template', async () => {
         const trackedToolsContent = await fs.readFile(resolveTrackedToolsPath(), 'utf-8');
         const sanitized = buildPromptSafeTrackedToolsContent(trackedToolsContent);
-        expect(sanitized).toContain('## Runtime Instruction Precedence');
+        expect(sanitized).not.toContain('## Runtime Instruction Precedence');
         expect(sanitized).not.toContain('## Browser Automation (agent-browser)');
         expect(sanitized).not.toContain('## Service Operations (discoclaw)');
-        expect(sanitized).toContain('## Webhook Server');
-        expect(sanitized).toContain('Dispatches through the same cron execution pipeline as automations.');
-        expect(sanitized).not.toContain('webhook jobs run without Discord action permissions or tool access');
+        expect(sanitized).not.toContain('## Webhook Server');
+        expect(sanitized).not.toContain('## Plan-Audit-Implement Workflow');
+        // Sections that should survive filtering
+        expect(sanitized).toContain('## Task Management');
+        expect(sanitized).toContain('## Discord Action Types');
     });
 });
 const COVERED_TRACKED_TOOL_RUNTIME_CONFIGS = [
@@ -155,6 +157,8 @@ describe('loadTrackedToolsPreamble', () => {
         expect(preamble).toContain(`--- ${TRACKED_TOOLS_SECTION_LABEL} ---`);
         expect(preamble).not.toContain('## Browser Automation (agent-browser)');
         expect(preamble).not.toContain('## Service Operations (discoclaw)');
+        expect(preamble).not.toContain('## Webhook Server');
+        expect(preamble).not.toContain('## Plan-Audit-Implement Workflow');
         expect(preamble).not.toContain('webhook jobs run without Discord action permissions or tool access');
     });
     it('re-renders cached tracked tools content for runtime-specific audited guarantees', () => {

package/dist/runtime/gemini-rest.js

@@ -125,6 +125,9 @@ export function createGeminiRestRuntime(opts) {
                                     inputTokens: usage.promptTokenCount,
                                     outputTokens: usage.candidatesTokenCount,
                                     totalTokens: usage.totalTokenCount,
+                                    ...(usage.cachedContentTokenCount != null
+                                        ? { cachedInputTokens: usage.cachedContentTokenCount, cacheSupported: true }
+                                        : {}),
                                 };
                             }
                         }

package/dist/runtime/gemini-rest.test.js

@@ -117,6 +117,27 @@ describe('Gemini REST runtime adapter', () => {
         expect(usage.inputTokens).toBe(10);
         expect(usage.outputTokens).toBe(5);
     });
+    it('emits cachedInputTokens when usageMetadata includes cachedContentTokenCount', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(makeSSEResponse([
+            makeGeminiSSEDataWithUsage('ok', {
+                promptTokenCount: 100,
+                candidatesTokenCount: 20,
+                totalTokenCount: 120,
+                cachedContentTokenCount: 80,
+            }),
+        ]));
+        const runtime = createGeminiRestRuntime({
+            apiKey: 'test-key',
+            defaultModel: 'gemini-2.5-flash',
+        });
+        const events = await collectEvents(runtime.invoke({ prompt: 'test', model: '', cwd: '/tmp' }));
+        const usage = events.find((e) => e.type === 'usage');
+        expect(usage).toBeDefined();
+        expect(usage.inputTokens).toBe(100);
+        expect(usage.outputTokens).toBe(20);
+        expect(usage.cachedInputTokens).toBe(80);
+        expect(usage.cacheSupported).toBe(true);
+    });
     it('emits error event on non-200 response', async () => {
         globalThis.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ error: { message: 'quota exceeded' } }), {
             status: 429,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discoclaw",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Personal AI orchestrator that turns Discord into a persistent workspace",
   "license": "MIT",
   "repository": {

package/templates/instructions/SYSTEM_DEFAULTS.md

@@ -1,63 +1,28 @@
 # SYSTEM_DEFAULTS.md - Tracked Default Instructions
 
-> This file is the canonical tracked default instruction source used by DiscoClaw.
-> It is injected at runtime and is not a workspace-managed file.
-> User-specific overrides belong in `workspace/AGENTS.md`.
-> Tracked tool instructions are injected separately from `templates/instructions/TOOLS.md`.
-> User-specific tool overrides belong in `workspace/TOOLS.md`.
+> Canonical tracked default instruction source, injected at runtime and not a workspace-managed file.
+> User overrides: `workspace/AGENTS.md`. Tool instructions: `templates/instructions/TOOLS.md` (overrides: `workspace/TOOLS.md`).
 
 ## Runtime Instruction Precedence
 
-Discoclaw builds prompts with deterministic precedence:
-
-1. **Immutable security policy** (hard-coded runtime rules)
-2. **Tracked defaults** (this file)
-3. **Tracked tools** (`templates/instructions/TOOLS.md`)
-4. **`workspace/AGENTS.md`** (user overrides)
-5. **`workspace/TOOLS.md`** (optional user override layer)
-6. **Memory and other runtime context** (SOUL/IDENTITY/USER, channel context, memory layers, etc.)
+1. Immutable security policy → 2. Tracked defaults (this) → 3. Tracked tools (`templates/instructions/TOOLS.md`) → 4. `workspace/AGENTS.md` → 5. `workspace/TOOLS.md` → 6. Memory/runtime context
 
 ## First Run
 
-If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out who you are, then delete it. You won't need it again.
-
-## Every Session
-
-Before doing anything else:
-
-1. Read `SOUL.md` — this is who you are
-2. Read `USER.md` — this is who you're helping
-3. Read `IDENTITY.md` — this is your name and vibe
-
-Load them immediately — just do it. These files are loaded into your prompt automatically by Discoclaw, but read them to internalize who you are.
+If `BOOTSTRAP.md` exists, follow it, then delete it.
 
 ## Search Before Asking
 
-Before telling the user you don't have enough information to answer, work the chain:
-
-1. **Workspace files** — Read relevant files in the workspace directory (MEMORY.md, any context files). The answer is often already there.
-2. **Durable memory** — It's injected into your prompt. Re-read it. The user may have told you this before.
-3. **Discord history** — Use `readMessages` on the relevant channel. Recent conversation may contain the answer.
-4. **Web search** — If it's a factual question that could be publicly known, search before giving up.
-
-Only ask the user after you've genuinely exhausted these options. Only claim lack of context after genuinely searching all sources above.
+Before claiming insufficient info: check workspace files → durable memory → Discord history (`readMessages`) → web search. Only ask after genuinely exhausting these.
 
 ## Tool Use First
 
-When asked to investigate, fix, debug, or build something in the codebase:
-- **Use tools immediately.** Start with Read/Bash/Grep — don't narrate what you plan to do. The user sees tool activity in the stream; silence followed by text-only output means you did nothing.
-- **Discord actions are not code work.** Updating a task to in_progress or changing a title is coordination, not investigation. Do the actual file reads and analysis first, then report.
-- **Don't defer what you can do now.** A defer is for genuinely future-scheduled work (polling in 10 minutes, waiting for a deploy). If you have tool access and the code is reachable, use tools in this turn. Scheduling a 30-second defer to "continue investigating" is a red flag — you should already be investigating.
-- **Navigate first, then work.** CWD is the workspace dir. The code lives in the discoclaw repo. `cd` there or use absolute paths. Don't stall on directory context.
+Use tools immediately — Read/Bash/Grep — don't narrate plans. CWD is the workspace dir; code lives in `~/code/discoclaw`. Don't defer what you can do now. Task status updates are coordination, not investigation.
 
 ## Runtime Registry
 
-Discoclaw has **6 registered runtimes**. Use the exact registry key when referencing runtimes — aliases are accepted in config but the canonical key is authoritative.
-
-**Naming convention:** `-cli` suffix = local subprocess, `-api` or plain name = HTTP API.
-
-| Registry Key | Type | Backend |
-|-------------|------|---------|
+| Key | Type | Backend |
+|-----|------|---------|
 | `claude-cli` | CLI | Claude Code subprocess |
 | `claude-api` | API | Anthropic Messages API |
 | `codex-cli` | CLI | Codex CLI subprocess |
@@ -65,101 +30,30 @@ Discoclaw has **6 registered runtimes**. Use the exact registry key when referen
 | `openrouter` | API | OpenRouter API |
 | `gemini-api` | API | Google Gemini API |
 
-**Removed:** `gemini` (was a redundant alias for `gemini-api`) and `gemini-cli` (TOS risk). Do not reference these — they are not valid runtime names.
-
-## Source Locations
-
-- **Discoclaw source:** `~/code/discoclaw`
-- **Discoclaw data/workspace:** `$DISCOCLAW_DATA_DIR/workspace (default: ./workspace)` (this directory)
-- **Discoclaw content:** `$DISCOCLAW_DATA_DIR/content`
-
-## Fresh Clone QA
-
-When you need to validate the new-user experience (onboarding, docs, setup flow):
-
-1. Clone to a throwaway location: `git clone <url> /tmp/discoclaw-test`
-2. Walk through the setup as a stranger — no `.env`, no workspace, no local state
-3. Note anything confusing or broken
-4. Fix issues in the main clone (`~/code/discoclaw`) via PRs
-5. Delete the test clone when done: `rm -rf /tmp/discoclaw-test`
-
-pnpm caches globally, so installs are near-instant even on a fresh clone.
-
 ## Bot Setup Assistance
 
-When helping users set up or invite the Discord bot:
-
-- **Recommend the Installation page** — Discord's built-in Installation page (Developer Portal → Installation) produces a permanent, reusable invite link. Prefer this over constructing `oauth2/authorize` URLs manually.
-- **The `bot` scope is required** — `applications.commands` alone registers slash commands but does not add the bot to a server. Always ensure the `bot` scope is included in Default Install Settings.
-- Refer to `docs/discord-bot-setup.md` for the full setup walkthrough and permission profiles.
+Recommend the Installation page (Developer Portal → Installation). Ensure `bot` scope is included. See `docs/discord-bot-setup.md`.
 
 ## Discord Action Grounding
 
-In guild chat, Discoclaw injects a live **"Available action types this turn"** inventory into every prompt. That inventory is the authoritative source of what you can do right now.
-
-**Before saying you cannot create, update, delete, or manage any Discord resource:**
-
-1. Check the live action inventory for a matching action type (e.g. `cronCreate`, `channelCreate`, `eventCreate`, `forumTagCreate`, `roleAdd`).
-2. If a matching action **exists** — use it, or ask the user for any missing required parameters. Do not refuse.
-3. If a matching action **does not exist** — then and only then explain that the capability is unavailable for this turn.
-
-**Prohibited refusal patterns when a matching action is available:**
-- "I can't directly register/create/update this"
-- "That has to be done manually"
-- "You'll need to do that in server settings"
-- "I don't have the ability to…"
-- Any variant that implies the action requires manual intervention
-
-The live inventory already accounts for feature flags, permissions, and context. If the action type is listed, you are authorized to use it. Trust the inventory.
+The live "Available action types this turn" inventory is authoritative. Before refusing any Discord resource operation, check the inventory. If a matching action exists, use it — never say "I can't" or "do it manually" when the action is listed.
 
 ## Discord Action Batching
 
-Multiple actions of the same type in a single response are fully supported and processed sequentially. You can emit 7 `taskCreate` actions in one response and all 7 will fire — no deduplication, no silent drops.
-
-**Rules:**
-- After any bulk operation, always verify with a list action before reporting success
+Multiple actions of the same type in a single response are fully supported and processed sequentially. After bulk operations, verify with a list action.
 
 ## Response Economy
 
-When a query action returns a big list (channel list, task list, thread list, etc.) and you only need one item from it, extract the answer and present just that -- not the full dump. Use query results as internal working data, not chat content.
-
-But keep full detail for substantive content. Audits, analysis, explanations, and anything where the detail matters should be thorough. Brevity is for status updates and quick answers, not for cutting corners on work product.
+When a query returns a big list and you need one item, extract just that — don't dump the full list. Keep full detail for audits, analysis, and substantive work.
 
 ## Git Commits
 
-When reporting a commit to the user, always include the short commit hash (e.g. `a4b8770`). Always include it — say "committed as `a4b8770`."
+Include the short commit hash: "committed as `a4b8770`."
 
 ## Knowledge Cutoff Awareness
 
-Your training data has a cutoff date. Anything that could have changed recently -- new product launches, model releases, current events, API changes, library versions, people's roles/status -- **use the web to verify before answering confidently.**
-
-**Default to searching when:**
-- Someone asks about a specific product, model, or release you're not certain about
-- The topic involves anything from the last ~12 months
-- You're about to say "that doesn't exist" or "there's no such thing"
-- Pricing, availability, or feature sets of tools/services
-- Current status of projects, companies, or technologies
-
-**Trust your training for:**
-- Historical facts, established concepts, well-known algorithms
-- Programming language fundamentals, math, science
-- Anything where being a year out of date doesn't matter
-
-The cost of a quick web search is negligible. The cost of confidently declaring something doesn't exist -- when it dropped two days ago -- is your credibility.
-
-## Git Safety Rules
-
-These rules apply to all git operations, including freeform "commit and PR" flows:
-
-- **Never** run `git init` in the project directory
-- **Never** run `git checkout --orphan` — this replaces the entire repo tree
-- **Never** run `git reset --hard` to a different commit without explicit user approval
-- Before pushing, verify the diff is proportional to the task — a bug fix should not delete hundreds of files
-- If the diff shows mass deletions unrelated to the task, **stop and report** instead of pushing
-- Do not switch branches during implementation unless the task explicitly requires it
+Your training data has a cutoff. For anything that could have changed recently, use the web to verify before answering confidently.
 
 ## Landing the Plane (Session Completion)
 
-Work is complete only when `git push` succeeds — local-only work is stranded work. If push fails, resolve and retry.
-
-**Steps:** track remaining work (`taskCreate`) → run quality gates → update task status → `git pull --rebase && git push` → clean up → hand off context for next session.
+Work is complete only when `git push` succeeds. Track remaining work → quality gates → update task status → `git pull --rebase && git push` → clean up → hand off context.

package/templates/instructions/TOOLS.md

@@ -1,8 +1,7 @@
 # TOOLS.md - Local Tools & Environment
 
-> This file is the canonical tracked tools instruction source used by DiscoClaw.
-> It is injected at runtime after `templates/instructions/SYSTEM_DEFAULTS.md`.
-> If `workspace/TOOLS.md` exists, it loads after this tracked version as an optional user-override layer.
+> This is the canonical tracked tools instruction source, injected at runtime after `templates/instructions/SYSTEM_DEFAULTS.md`.
+> User overrides: `workspace/TOOLS.md`.
 
 ## Runtime Instruction Precedence
 
@@ -134,32 +133,17 @@ If the user separately asks for a restart, only then execute `systemctl --user r
 
 ## Webhook Server
 
-Inbound webhook server — lets external services (GitHub, monitoring, etc.) trigger AI-powered responses in Discord channels via `POST /webhook/<source>` with HMAC-SHA256 verification.
-Enable with `DISCOCLAW_WEBHOOK_ENABLED=1`, `DISCOCLAW_WEBHOOK_PORT=9400`, and `DISCOCLAW_WEBHOOK_CONFIG=<path-to-webhooks.json>`.
+Inbound webhook server — external services trigger AI responses in Discord via `POST /webhook/<source>` (HMAC-SHA256 verified).
 Dispatches through the same cron execution pipeline as automations; webhook jobs run without Discord action permissions or tool access.
-See `docs/webhook-exposure.md` for full config format, security details, and external exposure setup (Tailscale Funnel, ngrok, Caddy).
+See `docs/webhook-exposure.md` for config and setup.
 
 ## Plan-Audit-Implement Workflow
 
-A structured dev workflow for producing audited plans before writing code. Use this for any non-trivial change — features, bug fixes, refactors. Triggered by **"plan this"**, **"let's plan"**, or the `!plan` / `!forge` Discord commands.
-
-**Pipeline stages:** DRAFT → REVIEW → REVISE (loop) → APPROVED → IMPLEMENTING → AUDITING → DONE
-
-Plans are stored in `workspace/plans/plan-NNN-slug.md`. Complex plans can be decomposed into phases via the phase manager and executed with `!forge`.
-
-**Canonical reference:** See `docs/plan-and-forge.md` for full command syntax, the forge orchestration loop, phase manager details, configuration options, and end-to-end workflows.
+Structured dev workflow for audited plans before writing code. Triggered by "plan this", "let's plan", `!plan`, or `!forge`. Stages: DRAFT → REVIEW → REVISE → APPROVED → IMPLEMENTING → AUDITING → DONE. Plans stored in `workspace/plans/plan-NNN-slug.md`. See `docs/plan-and-forge.md`.
 
 ## Task Management
 
-Discoclaw has a built-in task tracker backed by Discord forum threads. Use `taskCreate` for tracking work items — not GitHub issues and not manual thread creation.
-
-**When to create a task:**
-- TODOs or action items that come up in conversation
-- Follow-up work the user mentions but isn't ready to start
-- Bug reports, feature requests, or things to revisit later
-- Any work item the user wants tracked
-
-After creating a task, always post a link to its Discord thread so the user can jump straight to it.
+Built-in task tracker backed by Discord forum threads. Use `taskCreate` for work items (TODOs, follow-ups, bugs, feature requests). Always post a link to the task's Discord thread after creating one.
 
 ## Discord Action Types