@inkeep/open-knowledge 0.50.0-beta.1 → 0.50.0-beta.10

package/dist/config-schema.json

@@ -14,14 +14,16 @@
           "type": "string",
           "scope": "project",
           "agentSettable": false,
+          "reload": "boot",
           "defaultScope": "project",
-          "description": "Folder OpenKnowledge reads and writes documents under, relative to the project root (the folder that contains .ok/). Defaults to the project root. Exclude paths with .okignore."
+          "description": "Folder OpenKnowledge reads and writes documents under, relative to the project root (the folder that contains .ok/). Defaults to the project root. Exclude paths with .okignore. Read at server start; changing it requires a restart."
         },
         "attachmentFolderPath": {
           "default": "./",
           "type": "string",
           "scope": "project",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "project",
           "description": "Where pasted and dropped assets are stored, relative to the content root. './' colocates beside the current document (default); '/' targets the content root; './subdir' targets a subfolder under the current document folder; 'folder' targets a fixed folder under the content root. Whitespace-only values are treated as './'."
         }
@@ -45,6 +47,7 @@
           ],
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
           "description": "Editor color theme: 'light', 'dark', or 'system' (follow the OS). A personal preference (user scope) — not shared with the project."
         },
@@ -66,64 +69,42 @@
           ],
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
           "description": "Interface language. 'system' follows the operating system. A personal preference (user scope) — not shared with the project, and never applied to document content."
         },
         "colorThemeLight": {
           "type": "string",
-          "enum": [
-            "default",
-            "dracula",
-            "catppuccin-frappe",
-            "catppuccin-latte",
-            "monokai",
-            "gruvbox",
-            "solarized",
-            "custom"
-          ],
+          "pattern": "^[a-z0-9-]{1,32}$",
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
-          "description": "IDE color palette applied in light mode: 'default' (no palette), 'custom' (your own colors from appearance.customTheme), or one of 'dracula', 'catppuccin-frappe', 'catppuccin-latte', 'monokai', 'gruvbox', 'solarized'. A personal preference (user scope) — not shared with the project."
+          "description": "IDE color palette applied in light mode: 'default' (no palette), 'custom' (your own colors from appearance.customTheme), one of 'dracula', 'catppuccin-frappe', 'catppuccin-latte', 'monokai', 'gruvbox', 'solarized', or the id of a saved theme. A short id of lowercase letters, digits, and hyphens (max 32 characters); an id no palette matches falls back to 'default' for this mode only, leaving the rest of your config untouched. A personal preference (user scope) — not shared with the project."
         },
         "colorThemeDark": {
           "type": "string",
-          "enum": [
-            "default",
-            "dracula",
-            "catppuccin-frappe",
-            "catppuccin-latte",
-            "monokai",
-            "gruvbox",
-            "solarized",
-            "custom"
-          ],
+          "pattern": "^[a-z0-9-]{1,32}$",
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
-          "description": "IDE color palette applied in dark mode: 'default' (no palette), 'custom' (your own colors from appearance.customTheme), or one of 'dracula', 'catppuccin-frappe', 'catppuccin-latte', 'monokai', 'gruvbox', 'solarized'. A personal preference (user scope) — not shared with the project."
+          "description": "IDE color palette applied in dark mode: 'default' (no palette), 'custom' (your own colors from appearance.customTheme), one of 'dracula', 'catppuccin-frappe', 'catppuccin-latte', 'monokai', 'gruvbox', 'solarized', or the id of a saved theme. A short id of lowercase letters, digits, and hyphens (max 32 characters); an id no palette matches falls back to 'default' for this mode only, leaving the rest of your config untouched. A personal preference (user scope) — not shared with the project."
         },
         "colorTheme": {
           "type": "string",
-          "enum": [
-            "default",
-            "dracula",
-            "catppuccin-frappe",
-            "catppuccin-latte",
-            "monokai",
-            "gruvbox",
-            "solarized",
-            "custom"
-          ],
+          "pattern": "^[a-z0-9-]{1,32}$",
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
-          "description": "Superseded by appearance.colorThemeLight / appearance.colorThemeDark. Read as the palette for both modes while neither of those is set. A personal preference (user scope) — not shared with the project."
+          "description": "Superseded by appearance.colorThemeLight / appearance.colorThemeDark. Read as the palette for both modes while neither of those is set. A short theme id (lowercase letters, digits, and hyphens; max 32 characters); an id no palette matches falls back to 'default'. A personal preference (user scope) — not shared with the project."
         },
         "colorThemeEnabled": {
           "type": "boolean",
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
           "description": "Whether the Themes plugin appears in Settings → Plugins. A personal preference (user scope). Default on."
         },
@@ -134,6 +115,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: the scheme's display name."
             },
@@ -141,6 +123,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: the scheme's author credit, carried through from an imported base16 scheme."
             },
@@ -152,6 +135,7 @@
               ],
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: whether the scheme is 'dark' or 'light'. Auto-detected from the palette when omitted."
             },
@@ -159,6 +143,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base00 — default background, as a #rrggbb hex string."
             },
@@ -166,6 +151,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base01 — alt background — cards, popovers, sidebar, as a #rrggbb hex string."
             },
@@ -173,6 +159,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base02 — selection background, borders, as a #rrggbb hex string."
             },
@@ -180,6 +167,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base03 — comments, invisibles, as a #rrggbb hex string."
             },
@@ -187,6 +175,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base04 — secondary text, as a #rrggbb hex string."
             },
@@ -194,6 +183,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base05 — default foreground, as a #rrggbb hex string."
             },
@@ -201,6 +191,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base06 — light foreground, as a #rrggbb hex string."
             },
@@ -208,6 +199,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base07 — lightest foreground, as a #rrggbb hex string."
             },
@@ -215,6 +207,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base08 — red — variables, tags, diff deleted, as a #rrggbb hex string."
             },
@@ -222,6 +215,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base09 — orange — numbers, constants, as a #rrggbb hex string."
             },
@@ -229,6 +223,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base0A — yellow — classes, search highlight, as a #rrggbb hex string."
             },
@@ -236,6 +231,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base0B — green — strings, diff inserted, as a #rrggbb hex string."
             },
@@ -243,6 +239,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base0C — cyan — support, escapes, quotes, as a #rrggbb hex string."
             },
@@ -250,6 +247,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base0D — blue — functions, headings, accent, as a #rrggbb hex string."
             },
@@ -257,6 +255,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base0E — magenta — keywords, storage, as a #rrggbb hex string."
             },
@@ -264,6 +263,7 @@
               "type": "string",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Custom theme: base16 base0F — deprecated markers, embedded tags, as a #rrggbb hex string."
             }
@@ -281,6 +281,7 @@
               "type": "boolean",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "When on, the agent opens or refreshes the live preview after each edit. Turn off if you manage your own preview window. A personal preference (user scope)."
             }
@@ -295,6 +296,7 @@
               "type": "boolean",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Show dot-prefixed entries (e.g. .ok/, .okignore) in the file tree. Per-machine (project-local) — not shared with collaborators."
             },
@@ -303,6 +305,7 @@
               "type": "boolean",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Show only markdown documents (.md/.mdx) and folders in the file tree, hiding other file types from view. View-only: hidden files stay on disk and remain reachable via links and search. Per-machine (project-local) — not shared with collaborators."
             },
@@ -311,6 +314,7 @@
               "type": "boolean",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Show the Skills section in the sidebar. Skill documents remain reachable via links and search while the section is hidden. Per-machine (project-local) — not shared with collaborators."
             },
@@ -319,6 +323,7 @@
               "type": "boolean",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Show .ok folders (skills, templates, and other OpenKnowledge-managed state) in the file tree as read-only entries. .ok/worktrees and .ok/local never appear. Per-machine (project-local) — not shared with collaborators."
             }
@@ -340,6 +345,7 @@
           "type": "boolean",
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
           "description": "Soft-wrap long lines in the source (CodeMirror) editor. A personal preference (user scope)."
         },
@@ -348,6 +354,7 @@
           "type": "boolean",
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
           "description": "Reuse one tab when clicking through the Files and Skills sidebars, the way an editor preview tab works. Turn off to open every click in its own tab. Pinned tabs keep their own tab either way. A personal preference (user scope)."
         }
@@ -365,6 +372,7 @@
           "type": "boolean",
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
           "description": "Auto-approve OpenKnowledge's own tools (and `ok open` on Claude) for agents launched from the built-in terminal. Destructive tools (delete/move/share/install) still prompt. Per-machine personal preference (user scope)."
         }
@@ -392,6 +400,7 @@
               ],
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "How this machine syncs this project with its git remote: 'off' (no sync), 'follow' (one-directional — pull remote changes, never push your own; 'pull' is accepted as a legacy alias), or 'full' (bidirectional pull and push). null = not chosen yet (onboarding asks). Per-machine (project-local) — not shared. Supersedes the legacy autoSync.enabled boolean."
             },
@@ -407,6 +416,7 @@
               "type": "boolean",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Legacy per-machine sync toggle, superseded by autoSync.mode. Read only when mode is absent (true = full, false = off). null = not chosen yet. Per-machine (project-local) — not shared."
             },
@@ -424,6 +434,7 @@
           ],
           "scope": "project-local",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "project-local",
           "description": "When sync is paused (autoSync.mode 'off') after having been enabled, the active mode to resume into ('follow' | 'full'). Per-machine UI memory; ignored while a mode is active. Not shared."
         },
@@ -447,6 +458,7 @@
               ],
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Committed project default for a machine's sync mode on first open: 'off' | 'follow' | 'full', or the legacy boolean (true = full, false = off). null = ask (show the onboarding prompt). Shared via git. A per-machine autoSync.mode choice overrides it."
             },
@@ -471,6 +483,7 @@
               "type": "boolean",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Opt-out for the in-app terminal (a real OS shell at full user privilege). The terminal is on by default; set false to disable it for this project on this machine. Per-machine (project-local) — never shared via git, clone, or sync."
             },
@@ -493,6 +506,7 @@
           "type": "boolean",
           "scope": "user",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "user",
           "description": "Whether the Slides plugin appears in Settings → Plugins. When on, a document whose frontmatter has `slides: true` offers an action that opens the deck in a dedicated window (desktop only, requires a resolvable slidev). A personal preference (user scope). Default off."
         }
@@ -553,6 +567,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Write local diagnostic spans + logs under .ok/local/ for `ok diagnose bundle`. Local-only — never leaves the machine until you run bundle. Set false for sensitive workspaces. Shared across collaborators."
             },
@@ -567,6 +582,7 @@
                   "type": "number",
                   "scope": "project",
                   "agentSettable": false,
+                  "reload": "live",
                   "defaultScope": "project",
                   "description": "Maximum size, in bytes, of the local diagnostic spans file before it rotates (default ~50 MB)."
                 }
@@ -584,6 +600,7 @@
                   "type": "number",
                   "scope": "project",
                   "agentSettable": false,
+                  "reload": "live",
                   "defaultScope": "project",
                   "description": "Maximum size, in bytes, of the local diagnostic logs file before it rotates (default ~25 MB)."
                 }
@@ -607,6 +624,7 @@
               },
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Telemetry attribute keys whose values are redacted before any local span/log is written (credential / secret guard). Extends the built-in denylist."
             }
@@ -624,6 +642,7 @@
               "type": "boolean",
               "scope": "user",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "user",
               "description": "Report skill installs to skills.sh so a published skill shows an accurate install count. Sends the skill name, its source repo, and which agent tools it was installed for — never file contents, and never for a private or local source. One report per skill per machine. Default on; the DO_NOT_TRACK and DISABLE_TELEMETRY environment variables also turn it off."
             }
@@ -645,6 +664,7 @@
           "type": "boolean",
           "scope": "project",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "project",
           "description": "Record bridge loss-class events (content-free) under .ok/local/loss-capture/ for `ok diagnose bundle`. Local-only — never leaves the machine until you run bundle. Set false for sensitive workspaces. Shared across collaborators."
         },
@@ -653,6 +673,7 @@
           "type": "number",
           "scope": "project",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "project",
           "description": "Maximum size, in bytes, of the local loss-capture file before it rotates (default ~12 MB)."
         }
@@ -693,6 +714,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Keep the desktop window's timers running at full rate while it holds unsynced work, so backgrounding the app never starves sync or recovery; when the window is idle the OS-default background throttling is restored (battery). Honored by the desktop app. Default ON — disable only to isolate a suspected regression."
             }
@@ -710,6 +732,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Defer a drain-shaped Observer B re-derive when the WYSIWYG fragment holds an un-propagated keystroke Y.Text lacks, so the keystroke survives instead of being stomped. Default ON — disable only to isolate a suspected regression."
             }
@@ -727,6 +750,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Detect content the bridge silently dropped at its reconciliation boundary (an Observer-A apply arm or a paired agent-undo derive) and write a recovery checkpoint plus a content-free loss event. Detection only — never blocks a write. Default ON — disable only to isolate a suspected regression."
             }
@@ -744,6 +768,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Bound the Y.Text→WYSIWYG re-derive loop with a drain-count backstop: a run of re-derive drains that never reaches a raw-byte fixed point freezes the re-derive loop and writes a recovery checkpoint plus a content-free loss event, instead of churning unbounded. Default ON — disable only to isolate a suspected regression."
             }
@@ -761,6 +786,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Before an agent write or undo rebuilds the WYSIWYG fragment, flush an un-propagated keystroke that provably does not overlap the operation into Y.Text so the keystroke survives instead of needing recovery; overlapping or unmodellable cases fall back to the checkpoint floor. Scope: appending writes and single-frame undos — a write that replaces the whole body (replace / edit) overwrites the keystroke either way, so those always take the checkpoint floor. Default ON — disable only to isolate a suspected regression."
             }
@@ -778,6 +804,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "On tab hide/unload, force-send each doc's unsynced work to the server and commit its local cache, and re-sync on return to foreground, so a backgrounded tab never strands edits that IndexedDB alone would lose on recycle. Honored client-side. Default ON — disable only to isolate a suspected regression."
             }
@@ -810,6 +837,7 @@
               "type": "boolean",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Add semantic (embeddings) ranking to the MCP search tool, fused with the lexical engine so conceptually-related pages surface even with no shared keywords. When ON and an API key is set (`ok embeddings set-key`), the search query and matching document content are sent to the configured embeddings provider — content egress. Default OFF. Per-machine (project-local) — not shared with collaborators."
             },
@@ -818,6 +846,7 @@
               "type": "string",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Base URL of the OpenAI-compatible embeddings API (default https://api.openai.com/v1). Override to point at a self-hosted server (Ollama / vLLM / LM Studio) or another provider. The API key is NOT stored here — set it with `ok embeddings set-key` (`~/.ok/secrets.yml`); it is sent to whichever endpoint this names."
             },
@@ -826,6 +855,7 @@
               "type": "string",
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Embeddings model id (default text-embedding-3-small). Must be served by the provider at baseUrl. Changing it re-embeds the corpus (the cache is keyed by provider + model + dimensions)."
             },
@@ -835,6 +865,7 @@
               "maximum": 9007199254740991,
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Optional output vector dimensions. Omit (recommended) to detect the model's native size from its first response — that is what lets a non-OpenAI model work without knowing its size up front. Set a smaller value (text-embedding-3 supports e.g. 512 / 1024) to shrink the on-disk cache, trading a little retrieval quality; a server that ignores the request param then fails loudly instead of silently. Changing it re-embeds the corpus."
             },
@@ -844,6 +875,7 @@
               "maximum": 1,
               "scope": "project-local",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project-local",
               "description": "Optional hard cutoff: drop any \"by meaning\" match whose cosine similarity is below this value. Off by default (0) because retrieval is rank-based (the closest pages are returned regardless of absolute score) and the right cutoff is model-specific. Set it only to suppress weak matches for a specific provider/model whose cosine scale you know. Most setups should leave it unset and rely on the result-count cap."
             }
@@ -876,6 +908,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Whether the markdownlint plugin (body rules) contributes diagnostics."
             }
@@ -893,6 +926,7 @@
               "type": "boolean",
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Whether the frontmatter plugin (JSON-Schema validation of document frontmatter) contributes diagnostics."
             },
@@ -928,6 +962,7 @@
               },
               "scope": "project",
               "agentSettable": false,
+              "reload": "live",
               "defaultScope": "project",
               "description": "Frontmatter schema mappings: which docs (appliesTo globs) validate against which JSON Schema file (project-root-relative path)."
             }
@@ -953,6 +988,7 @@
           ],
           "scope": "project",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "project",
           "description": "How broken internal links are reported on the validation plane: 'off' hides them, 'warning' (default) or 'error' sets their severity."
         },
@@ -961,6 +997,7 @@
           "type": "boolean",
           "scope": "project",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "project",
           "description": "Whether the file tree tints and badges files that have validation problems."
         }
@@ -978,6 +1015,7 @@
           "type": "boolean",
           "scope": "project-local",
           "agentSettable": false,
+          "reload": "live",
           "defaultScope": "project-local",
           "description": "Show a rich preview card (site name, page title, description, favicon) when you hover an external link in the editor. When ON, hovering an external link sends that link's URL to the destination site to fetch its preview metadata — outbound egress, one request per previewed link. Default ON; set to false to turn external previews off. Per-machine (project-local) — not shared with collaborators. Previews of links to other documents in this project are read from the local index with no network request and are always on."
         }
@@ -985,27 +1023,107 @@
       "additionalProperties": {}
     },
     "remote": {
-      "default": {
-        "port": 24550
-      },
+      "default": {},
       "type": "object",
       "properties": {
         "url": {
           "type": "string",
           "scope": "project",
           "agentSettable": false,
+          "reload": "boot",
           "defaultScope": "project",
-          "description": "Public URL your tunnel gives you, e.g. https://myproject.ngrok.app. Used only with `ok start --remote` (config alone never enables remote access); its host is admitted through the Host-header allowlist. There is no server-side auth, so restrict access at the tunnel (ngrok OAuth, Cloudflare Access, Tailscale ACLs)."
+          "description": "Superseded by server.publicUrl — read only while server.publicUrl is absent. Public URL your tunnel gives you, e.g. https://myproject.ngrok.app. Used only with `ok start --remote` (config alone never enables remote access); its host is admitted through the Host-header allowlist. There is no server-side auth, so restrict access at the tunnel (ngrok OAuth, Cloudflare Access, Tailscale ACLs)."
         },
         "port": {
-          "default": 24550,
           "type": "integer",
           "minimum": 1,
           "maximum": 65535,
           "scope": "project",
           "agentSettable": false,
+          "reload": "boot",
+          "defaultScope": "project",
+          "description": "Superseded by server.port — read only while server.port is absent. TCP port the server binds when remote access is enabled (default 24550). Fixed so the tunnel's port mapping survives restarts. Set it only on a conflict. An explicit --port still wins; the PORT env var is ignored in remote mode."
+        }
+      },
+      "additionalProperties": {}
+    },
+    "server": {
+      "default": {
+        "bind": [
+          "127.0.0.1"
+        ],
+        "allowExternal": false
+      },
+      "type": "object",
+      "properties": {
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535,
+          "scope": "project",
+          "agentSettable": false,
+          "reload": "boot",
+          "defaultScope": "project",
+          "description": "TCP port the server listens on. Unset by default: a local start picks a free port dynamically, and deployment platforms inject the PORT environment variable instead. Supersedes remote.port (still read while this key is absent). Read at server start; changing it requires a restart."
+        },
+        "bind": {
+          "default": [
+            "127.0.0.1"
+          ],
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "scope": "project",
+          "agentSettable": false,
+          "reload": "boot",
           "defaultScope": "project",
-          "description": "TCP port the server binds when remote access is enabled (default 24550). Fixed so the tunnel's port mapping survives restarts. Set it only on a conflict. An explicit --port still wins; the PORT env var is ignored in remote mode."
+          "description": "Addresses the server binds, e.g. [127.0.0.1] or [0.0.0.0]. Default loopback-only ([127.0.0.1]): nothing off this machine can connect. A non-loopback bind additionally requires the server.allowExternal consent interlock. Lists replace, never merge. Read at server start; changing it requires a restart."
+        },
+        "publicUrl": {
+          "type": "string",
+          "pattern": "^https?:\\/\\/",
+          "scope": "project",
+          "agentSettable": false,
+          "reload": "boot",
+          "defaultScope": "project",
+          "description": "Canonical external origin the server is reached at, e.g. https://kb.example.com — drives issued URLs and CORS. Unset by default: a loopback server derives http://localhost:<port>. Setting it declares external exposure, which additionally requires the server.allowExternal consent interlock. Supersedes remote.url (still read while this key is absent). Read at server start; changing it requires a restart."
+        },
+        "allowExternal": {
+          "default": false,
+          "type": "boolean",
+          "scope": "project-local",
+          "agentSettable": false,
+          "reload": "boot",
+          "defaultScope": "project-local",
+          "description": "Exposure consent interlock. Once the unified server boot lands, a non-loopback server.bind or a server.publicUrl without allowExternal: true will be refused at boot with a one-line fix. Default off. Per-machine (project-local) — consent never travels via git, clone, or share; containers consent via the environment instead."
+        },
+        "openBrowser": {
+          "type": "boolean",
+          "scope": "project-local",
+          "agentSettable": false,
+          "reload": "boot",
+          "defaultScope": "project-local",
+          "description": "Open the UI in a browser when the server starts. Default derived: true when every bind address is loopback (a laptop start pops the UI), false otherwise (a container or exposed bind is headless and must never try). Acts once at start. Per-machine (project-local) — not shared."
+        },
+        "idleShutdown": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "off"
+            },
+            {
+              "type": "string",
+              "pattern": "^[1-9]\\d*(s|m|h)$"
+            }
+          ],
+          "scope": "project-local",
+          "agentSettable": false,
+          "reload": "live",
+          "defaultScope": "project-local",
+          "description": "Shut the server down after this long with no activity: a duration like '30m' (positive integer with unit s, m, or h), or 'off'. Default derived: '30m' when every bind address is loopback, 'off' otherwise (an exposed or containerized server stays up). Reloadable — a valid change applies without a restart. Per-machine (project-local) — not shared."
         }
       },
       "additionalProperties": {}