feat: toast_duration_ms = 0 disables toasts; README config links

Follow-up to the cherry-picked PR #92 (toast_duration_ms, by Csaba Kertesz):

- toast_duration_ms now accepts 0 = disable Magic Context toasts entirely
  (schema min 1000 → 0). showToast() skips when the effective duration is
  non-positive, so a config of 0 suppresses routine toasts while explicit
  positive per-call overrides (e.g. restart-required) still show. Both TUI
  toast routes (direct + server-pushed drain) funnel through showToast, so the
  one gate covers both. Regenerated assets/magic-context.schema.json + the docs
  config reference; updated CONFIGURATION.md.

- Replaced PR #92's module-level `mock.module("../../hooks/magic-context")` in
  create-session-hooks.test.ts — Bun's mock.module is process-global and
  mock.restore() does not undo it, so it leaked into hook.test.ts and failed 12
  of its hook-shape assertions in the full suite (the file passed alone). Fixed
  by extracting the pure buildMagicContextHookConfig() mapping and testing that
  directly — no mock, no leak (also a cleaner unit, portable to the future Rust
  MC module). +1 toast=0 passthrough test.

- README: added Docs (docs.cortexkit.io/magic-context) and Configuration links
  to the nav row, and pointed the Configuration section at both CONFIGURATION.md
  and the docs-site configuration reference.

Gate: plugin 2240/0, schema/config-parity green, dashboard config-parity 10/0.

Co-authored-by: Alfonso [Magic Context] <288211368+alfonso-magic-context@users.noreply.github.com>

Author: ualtinok

CONFIGURATION.md

@@ -113,7 +113,7 @@ Higher-tier models with longer cache windows benefit from a longer TTL. Setting
 | `ctx_reduce_enabled` | `boolean` | `true` | When `false`, hides `ctx_reduce` tool, disables all nudges/reminders, and strips reduction guidance from prompts. Heuristic cleanup, compartments, memory, and search still work. Useful for testing whether automatic cleanup alone is sufficient. |
 | `cache_ttl` | `string` or `object` | `"5m"` | Time after a response before applying pending ops. String or per-model map. |
 | `protected_tags` | `number` (1–100) | `20` | Last N active tags immune from immediate dropping. |
-| `toast_duration_ms` | `number` (1000–60000) | `5000` | TUI toast lifetime for Magic Context notifications in milliseconds. Increase this if toasts disappear too quickly. |
+| `toast_duration_ms` | `number` (0–60000) | `5000` | TUI toast lifetime for Magic Context notifications in milliseconds. Increase this if toasts disappear too quickly, or set to `0` to disable Magic Context toasts entirely. |
 | `execute_threshold_percentage` | `number` (20–80) or `object` | `65` | Context usage that forces queued ops to execute. Capped at 80% max for cache safety. Supports per-model map. |
 | `execute_threshold_tokens` | `object` (per-model map) | — | **Optional absolute-tokens variant of `execute_threshold_percentage`.** Per-model map (e.g. `{ "default": 150000, "github-copilot/gpt-5.2-codex": 40000 }`). When set for a model, overrides the percentage-based threshold for that model. Clamped to `80% × context_limit` with a warn log. Requires a resolvable context limit — falls through to percentage if unavailable. See below. |
 | `clear_reasoning_age` | `number` | `50` | Clear thinking/reasoning blocks older than N tags. |

README.md

@@ -26,6 +26,8 @@
   <a href="#-capture">Capture</a> ·
   <a href="#-consolidate">Consolidate</a> ·
   <a href="#-recall">Recall</a> ·
+  <a href="https://docs.cortexkit.io/magic-context">Docs</a> ·
+  <a href="./CONFIGURATION.md">Configuration</a> ·
   <a href="https://discord.gg/DSa65w8wuf">💬 Discord</a>
 </p>
 
@@ -239,7 +241,7 @@ It reads directly from Magic Context's SQLite database. No extra server, no API.
 
 ## Configuration
 
-Settings live in `magic-context.jsonc`. Everything has sensible defaults; project config merges on top of user-wide settings. See **[CONFIGURATION.md](./CONFIGURATION.md)** for the full reference: cache TTL tuning, per-model execute thresholds, historian and dreamer model selection, embedding providers, and memory settings.
+Settings live in `magic-context.jsonc`. Everything has sensible defaults; project config merges on top of user-wide settings. For the full reference — cache TTL tuning, per-model execute thresholds, historian and dreamer model selection, embedding providers, and memory settings — see **[CONFIGURATION.md](./CONFIGURATION.md)** or the **[configuration reference on docs.cortexkit.io](https://docs.cortexkit.io/magic-context/reference/configuration/)**.
 
 **Config locations** (merged in order, project overrides user):
 1. `<project-root>/magic-context.jsonc`

assets/magic-context.schema.json

@@ -478,9 +478,9 @@
     },
     "toast_duration_ms": {
       "default": 5000,
-      "description": "TUI toast lifetime in milliseconds for Magic Context notifications (min: 1000, max: 60000, default: 5000)",
+      "description": "TUI toast lifetime in milliseconds for Magic Context notifications. Set to 0 to disable Magic Context toasts entirely (min: 0, max: 60000, default: 5000)",
       "type": "number",
-      "minimum": 1000,
+      "minimum": 0,
       "maximum": 60000
     },
     "execute_threshold_percentage": {

packages/docs/src/content/docs/reference/configuration.md

@@ -192,3 +192,9 @@ Behavior tuning most installs never need to touch.
 | `sqlite` | object | — | SQLite connection tuning for Magic Context's own context.db. These are per-connection PRAGMAs applied at open; they do not change the schema or what is stored. |
 | `sqlite.cache_size_mb` | number (2–2048) | `64` | Page-cache size in MiB per connection (PRAGMA cache_size). Larger keeps more hot pages resident, cutting re-reads on repeated full-table scans. (min 2, max 2048, default 64) |
 | `sqlite.mmap_size_mb` | number (0–8192) | `0` | Memory-mapped I/O size in MiB (PRAGMA mmap_size). 0 disables mmap (SQLite default). Raising it can cut read overhead on large DBs at the cost of address space. (min 0, max 8192, default 0) |
+
+## Other
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `toast_duration_ms` | number (0–60000) | `5000` | TUI toast lifetime in milliseconds for Magic Context notifications. Set to 0 to disable Magic Context toasts entirely (min: 0, max: 60000, default: 5000) |

packages/plugin/src/config/schema/magic-context.ts

@@ -392,11 +392,11 @@ export const MagicContextConfigSchema = z
             ),
         toast_duration_ms: z
             .number()
-            .min(1_000)
+            .min(0)
             .max(60_000)
             .default(5_000)
             .describe(
-                "TUI toast lifetime in milliseconds for Magic Context notifications (min: 1000, max: 60000, default: 5000)",
+                "TUI toast lifetime in milliseconds for Magic Context notifications. Set to 0 to disable Magic Context toasts entirely (min: 0, max: 60000, default: 5000)",
             ),
         execute_threshold_percentage: z
             .union([

packages/plugin/src/plugin/hooks/create-session-hooks.test.ts

@@ -1,43 +1,32 @@
 /// <reference types="bun-types" />
 
-import { beforeEach, describe, expect, it, mock } from "bun:test";
+import { describe, expect, it } from "bun:test";
+import { buildMagicContextHookConfig } from "./create-session-hooks";
 
-const createMagicContextHookMock = mock(() => ({ mocked: true }));
+describe("buildMagicContextHookConfig", () => {
+    it("threads toast_duration_ms into the per-session hook config", () => {
+        const config = buildMagicContextHookConfig({
+            enabled: true,
+            protected_tags: 10,
+            cache_ttl: "5m",
+            toast_duration_ms: 30_000,
+        } as never);
 
-mock.module("../../hooks/magic-context", () => ({
-    createMagicContextHook: createMagicContextHookMock,
-}));
-
-describe("createSessionHooks", () => {
-    beforeEach(() => {
-        createMagicContextHookMock.mockClear();
+        expect(config.toast_duration_ms).toBe(30_000);
     });
 
-    it("threads notification config into the magic-context hook", async () => {
-        const { createSessionHooks } = await import("./create-session-hooks");
+    it("passes toast_duration_ms = 0 through unchanged (disables toasts)", () => {
+        const config = buildMagicContextHookConfig({
+            enabled: true,
+            toast_duration_ms: 0,
+        } as never);
+
+        expect(config.toast_duration_ms).toBe(0);
+    });
 
-        createSessionHooks({
-            ctx: {
-                client: {},
-                directory: "/tmp/project",
-            } as never,
-            liveSessionState: {
-                liveModelBySession: new Map(),
-                variantBySession: new Map(),
-                agentBySession: new Map(),
-            },
-            pluginConfig: {
-                enabled: true,
-                protected_tags: 10,
-                cache_ttl: "5m",
-                toast_duration_ms: 30_000,
-            } as never,
-        });
+    it("leaves toast_duration_ms undefined when unset (consumer applies default)", () => {
+        const config = buildMagicContextHookConfig({ enabled: true } as never);
 
-        expect(createMagicContextHookMock).toHaveBeenCalledTimes(1);
-        const args = createMagicContextHookMock.mock.calls[0]?.[0] as {
-            config?: { toast_duration_ms?: number };
-        };
-        expect(args.config?.toast_duration_ms).toBe(30_000);
+        expect(config.toast_duration_ms).toBeUndefined();
     });
 });

packages/plugin/src/plugin/hooks/create-session-hooks.ts

@@ -8,6 +8,41 @@ import { createMagicContextHook } from "../../hooks/magic-context";
 import type { LiveSessionState } from "../../hooks/magic-context/live-session-state";
 import type { PluginContext } from "../types";
 
+/**
+ * Map the full plugin config down to the per-session hook config. Pure and
+ * exported so it can be unit-tested directly — without a module-level
+ * `mock.module` of the hooks barrel, which in Bun leaks process-globally across
+ * test files (mock.restore() does not undo it) and corrupts sibling suites that
+ * import the real hook shape.
+ */
+export function buildMagicContextHookConfig(pluginConfig: MagicContextPluginConfig) {
+    return {
+        protected_tags: pluginConfig.protected_tags ?? DEFAULT_PROTECTED_TAGS,
+        ctx_reduce_enabled: pluginConfig.ctx_reduce_enabled,
+        cache_ttl: pluginConfig.cache_ttl,
+        clear_reasoning_age: pluginConfig.clear_reasoning_age,
+        toast_duration_ms: pluginConfig.toast_duration_ms,
+        execute_threshold_percentage:
+            pluginConfig.execute_threshold_percentage ?? DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE,
+        execute_threshold_tokens: pluginConfig.execute_threshold_tokens,
+        historian: pluginConfig.historian,
+        history_budget_percentage: pluginConfig.history_budget_percentage,
+        historian_timeout_ms: pluginConfig.historian_timeout_ms,
+        memory: pluginConfig.memory,
+        sidekick: pluginConfig.sidekick,
+        dreamer: pluginConfig.dreamer,
+        commit_cluster_trigger: pluginConfig.commit_cluster_trigger,
+        // Issue #53: per-agent system-prompt injection opt-out.
+        system_prompt_injection: pluginConfig.system_prompt_injection,
+        // Graduated from experimental.* — temporal_awareness and caveman are
+        // top-level; auto_search now rides inside `memory` (passed above), and
+        // git_commit_indexing is consumed at the dream-timer level in index.ts,
+        // not per-session.
+        temporal_awareness: pluginConfig.temporal_awareness,
+        caveman_text_compression: pluginConfig.caveman_text_compression,
+    };
+}
+
 export function createSessionHooks(args: {
     ctx: PluginContext;
     pluginConfig: MagicContextPluginConfig;
@@ -39,32 +74,7 @@ export function createSessionHooks(args: {
             scheduler,
             compactionHandler,
             liveSessionState,
-            config: {
-                protected_tags: pluginConfig.protected_tags ?? DEFAULT_PROTECTED_TAGS,
-                ctx_reduce_enabled: pluginConfig.ctx_reduce_enabled,
-                cache_ttl: pluginConfig.cache_ttl,
-                clear_reasoning_age: pluginConfig.clear_reasoning_age,
-                toast_duration_ms: pluginConfig.toast_duration_ms,
-                execute_threshold_percentage:
-                    pluginConfig.execute_threshold_percentage ??
-                    DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE,
-                execute_threshold_tokens: pluginConfig.execute_threshold_tokens,
-                historian: pluginConfig.historian,
-                history_budget_percentage: pluginConfig.history_budget_percentage,
-                historian_timeout_ms: pluginConfig.historian_timeout_ms,
-                memory: pluginConfig.memory,
-                sidekick: pluginConfig.sidekick,
-                dreamer: pluginConfig.dreamer,
-                commit_cluster_trigger: pluginConfig.commit_cluster_trigger,
-                // Issue #53: per-agent system-prompt injection opt-out.
-                system_prompt_injection: pluginConfig.system_prompt_injection,
-                // Graduated from experimental.* — temporal_awareness and caveman
-                // are top-level; auto_search now rides inside `memory` (passed
-                // above), and git_commit_indexing is consumed at the dream-timer
-                // level in index.ts, not per-session.
-                temporal_awareness: pluginConfig.temporal_awareness,
-                caveman_text_compression: pluginConfig.caveman_text_compression,
-            },
+            config: buildMagicContextHookConfig(pluginConfig),
         }),
     };
 }

packages/plugin/src/tui/index.tsx

@@ -44,6 +44,12 @@ function showToast(
         typeof input.durationOverrideMs === "number" && Number.isFinite(input.durationOverrideMs)
             ? input.durationOverrideMs
             : getToastDurationMs()
+    // toast_duration_ms = 0 disables Magic Context toasts entirely. An explicit
+    // positive per-call override (e.g. restart-required) still shows; only a
+    // non-positive effective duration suppresses the toast.
+    if (!(duration > 0)) {
+        return
+    }
     api.ui.toast({
         message: input.message,
         variant: input.variant,