Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
docs(ok): rewrite self-hosting docs for the server.* surface (PRD-7918) (#3426)
omar-inkeep3e2d03e1b614
diff --git a/docs/content/deploy/connecting-agents.mdx b/docs/content/deploy/connecting-agents.mdxdeleted file mode 100644index df3fc5289..000000000--- a/docs/content/deploy/connecting-agents.mdx+++ /dev/null@@ -1,77 +0,0 @@-----title: Connecting agents-icon: LuPlug-description: Point every agent (Claude Code, Cursor, Claude Desktop, agent harnesses) at one shared knowledge base.-----Prerequisite: a running server with [remote access set up](/docs/deploy/remote-access). That page is also where access control lives (the tunnel decides who can reach the URL; the server itself does not authenticate remote callers). To connect someone else's machine, get them access to the tunnel first (e.g. a tailnet invite or an edge-auth allowlist entry), then send them here.--Your knowledge base is one URL: `https://<your-tunnel-url>/mcp`. Every client below connects to that same address, whether the server is your laptop, a Mac mini, or a VPS.--## Connect every agent in one command--[`add-mcp`](https://github.com/neon-solutions/add-mcp) detects which agents are installed on the machine and writes each one's MCP config for you — Claude Code, Cursor, Codex, VS Code, Windsurf, Goose, Zed, and more:--```bash-npx add-mcp https://<your-tunnel-url>/mcp --name ok-remote-```--If your `/mcp` endpoint is behind **Basic Auth** at the tunnel (see [Restrict who can reach it](/docs/deploy/remote-access#4-restrict-who-can-reach-it)), pass the credential as a header so the agent connects with no browser step:--```bash-npx add-mcp https://<your-tunnel-url>/mcp --name ok-remote \- --header "Authorization: Basic $(printf 'user:pass' | base64)"-```--An **OAuth/SSO**-gated endpoint can't be used this way — a headless agent can't complete a browser login, so gate agent endpoints with Basic Auth, a [path-branched policy](/docs/deploy/remote-access#4-restrict-who-can-reach-it), or Tailscale instead.--## Claude Code--```bash-claude mcp add --transport http ok-remote https://<your-tunnel-url>/mcp-```--## Cursor--```json title="~/.cursor/mcp.json"-{- "mcpServers": {- "ok-remote": { "url": "https://<your-tunnel-url>/mcp" }- }-}-```--## Codex--Recent Codex versions take the URL directly:--```toml title="~/.codex/config.toml"-[mcp_servers.ok-remote]-url = "https://<your-tunnel-url>/mcp"-```--## Claude Desktop--Claude Desktop only takes command-type servers, so it reaches the server through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge — a local process that forwards to your `/mcp` URL.--Its config file — `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows. In Claude Desktop open **Settings → Developer → Edit Config**, which creates the file and reveals it. Then add:--```json title="claude_desktop_config.json"-{- "mcpServers": {- "ok-remote": {- "command": "npx",- "args": ["-y", "mcp-remote", "https://<your-tunnel-url>/mcp"]- }- }-}-```--## Agent harnesses (OpenClaw, Hermes, etc.)--Add the `/mcp` URL to your harness's MCP server config, the same way as above. Its agents can then read and write your knowledge base.--## Cloud connectors (Claude.ai, ChatGPT, etc.)--Cloud-dialed clients connect from the vendor's cloud, so your tunnel URL must be publicly reachable over HTTPS. The Claude and ChatGPT connectors require OAuth, which OpenKnowledge does not support as a server (for now). Connectors that accept a bearer token or API key instead (Microsoft Copilot Studio, Perplexity, etc.) can use a token you enforce at the tunnel: gate `/mcp` with a static bearer token in your tunnel's edge auth, then paste that same token into the connector's settings, the way an on-device agent presents its credential as a header.--Claude Desktop is not a cloud connector; it uses the `mcp-remote` bridge covered above.diff --git a/docs/content/deploy/meta.json b/docs/content/deploy/meta.jsondeleted file mode 100644index cdd01cfe1..000000000--- a/docs/content/deploy/meta.json+++ /dev/null@@ -1,5 +0,0 @@-{- "title": "Deploy",- "icon": "LuServer",- "pages": ["remote-access", "connecting-agents"]-}diff --git a/docs/content/deploy/remote-access.mdx b/docs/content/deploy/remote-access.mdxdeleted file mode 100644index c933f5908..000000000--- a/docs/content/deploy/remote-access.mdx+++ /dev/null@@ -1,274 +0,0 @@-----title: Remote access-icon: LuGlobe-description: Reach your knowledge base from your other devices.-----By default, only agents on the same machine as your knowledge base can reach it. Remote access puts that same endpoint behind an HTTPS tunnel (ngrok, Cloudflare Tunnel, Tailscale, or your own reverse proxy) so your other devices can connect to one shared knowledge base.--<Callout type="warn">-`--remote` is deprecated. It still works exactly as documented below, but it is now an alias for the general networking keys: `OK_IDLE_SHUTDOWN=off OK_ALLOW_EXTERNAL=1 ok start --external-url <url>` is the equivalent invocation (or set `server.externalUrl`, `server.allowExternal`, and `server.idleShutdown: off` in config — without `idleShutdown: off` the server shuts down after 30 idle minutes even while remote agents are using it, because the idle timer only counts editor connections). Prefer that spelling for new setups — `--remote` will be removed in a later release.-</Callout>--OpenKnowledge does not authenticate remote callers. Once you pass `--remote`, anyone who can reach your tunnel URL has full read-write control, so restricting who reaches it is up to the tunnel. Put it on a private network like Tailscale, add edge auth like ngrok OAuth or Cloudflare Access, or just keep the URL to yourself. The server ignores tunneled traffic until you start it with `--remote`, so you never expose the base by accident.--## Set up the machine--Remote access runs on the machine that holds your knowledge base. Pick where it lives and get OpenKnowledge running a project there.--### Your laptop or desktop--Your laptop or desktop, where OpenKnowledge is already installed and running your project. Nothing to prepare, so skip ahead to [Turn on remote access](#turn-on-remote-access).--The catch is that it's only reachable while that machine is awake. Close the lid and your agents lose access. For around-the-clock access, use a dedicated server instead.--### A dedicated server--A VPS, Mac mini, or any computer you can leave running. It keeps your knowledge base reachable around the clock, so agents never lose access. Set it up first.--<Callout>-**On a VPS:** providers like Hetzner, DigitalOcean, and Lightsail all work. Pick Ubuntu 24.04 (1 GB RAM is comfortable; 512 MB runs a small knowledge base), add your SSH key at creation, and `ssh root@<ip>` in. Every step below happens in that shell.-</Callout>--Install OpenKnowledge (and Node 24 first, on a fresh box):--```bash-curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash - && sudo apt-get install -y nodejs git-npm install -g @inkeep/open-knowledge-```--Create the project (`ok init` sets up git for you):--```bash-mkdir ~/knowledge && cd ~/knowledge && ok init-```--To start from existing notes, `git clone` them as the project directory instead of `mkdir`, then run `ok init` inside.--## Turn on remote access--Run these on the machine you set up.--### 1. Open a tunnel--Any HTTPS tunnel works. It forwards a public URL to the server's local port, `24550` by default (change it with `remote.port` in `.ok/config.yml`; see the [Configuration reference](/docs/reference/configuration)). Point your tunnel at that same port. Pick one:--<Callout type="info">-Install your tunnel's client on the machine first if it isn't already.-</Callout>--<Tabs groupId="ok-tunnel" persist items={['Tailscale', 'ngrok', 'Cloudflare Tunnel']}>--<Tab>--Private, only devices on your tailnet can reach it. Requires [HTTPS enabled in your tailnet](https://tailscale.com/kb/1153/enabling-https).--```bash-tailscale serve --bg 24550-# → https://<machine>.<tailnet>.ts.net-```--</Tab>--<Tab>--Public URL; add edge auth to restrict (see [Restrict who can reach it](#4-restrict-who-can-reach-it)).--```bash-ngrok http 24550-# → https://<something>.ngrok.app-```--</Tab>--<Tab>--Public URL on your own domain; pair with Cloudflare Access to restrict (see [Restrict who can reach it](#4-restrict-who-can-reach-it)).--```bash-cloudflared tunnel --url http://localhost:24550-```--</Tab>--</Tabs>--Each one gives you a public HTTPS URL. That URL is your `remote.url`.--### 2. Start the server with `--remote`--From the project directory:--```bash-ok start --remote https://<your-tunnel-url>-```--Or persist the URL in `.ok/config.yml` and start with a bare flag:--```yaml title=".ok/config.yml"-remote:- url: https://<your-tunnel-url>-```--```bash-ok start --remote-```--The flag is required every start. A `remote.url` sitting in config never turns remote access on by itself, and the server prints a warning banner on every remote start so the exposure is never silent. Without `--remote`, tunneled requests are refused with a hint rather than served.--<Callout>-Remote access is a command-line feature (`ok start --remote`), not a desktop toggle. To see what you're exposing, open the tunnel URL in a browser; the desktop app only connects to its own local server. The desktop app and `ok start` also can't run against the same project at once.-</Callout>--On a **dedicated server**, run it as a service instead, so it survives logout and reboots:--```ini title="/etc/systemd/system/openknowledge.service"-[Unit]-Description=OpenKnowledge server-After=network-online.target--[Service]-User=root-WorkingDirectory=/root/knowledge-ExecStart=/usr/bin/env ok start --remote-Restart=on-failure--[Install]-WantedBy=multi-user.target-```--This matches the `ssh root@<ip>` VPS setup above (project at `/root/knowledge`, `remote.url` set in config). If you log in as a different user, set `User` and `WorkingDirectory` to that user and their project path.--```bash-sudo systemctl enable --now openknowledge-```--<Callout>-**On macOS**, there's no systemd. Run `ok start --remote` in a terminal, and set the machine not to sleep (System Settings → Energy) for always-on use.-</Callout>--### 3. Verify--From any device that can reach the tunnel, do a real handshake:--```bash-curl -sS -X POST https://<your-tunnel-url>/mcp \- -H 'content-type: application/json' \- -H 'accept: application/json, text/event-stream' \- -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'-```--Your knowledge base introduces itself:--```json-{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"open-knowledge","version":"…"}},"jsonrpc":"2.0","id":1}-```--That's the whole path working. You now have an MCP URL for your knowledge base:--```-https://<your-tunnel-url>/mcp-```--### 4. Restrict who can reach it--The server admits whoever the tunnel lets through, so we recommend adding access control at the tunnel:--- **Tailscale `serve`** is restricted by construction: only devices on your tailnet can connect. Use [tailnet ACLs](https://tailscale.com/kb/1018/acls) to narrow it further. (`tailscale funnel` makes the URL public — treat it like any public tunnel.)-- **ngrok** can require a login at the edge before any request reaches you. Use **OAuth** (or **OIDC/SSO** — `--oidc`, for Okta / Azure AD / Google Workspace):-- ```bash- ngrok http 24550 --oauth google --oauth-allow-email [email protected]- ```--- **Cloudflare Tunnel** pairs with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) — a login policy on the hostname, checked at Cloudflare's edge.--A public tunnel URL with no edge auth is a capable but *open* knowledge base: fine for a deliberate share, wrong as a default. The URL itself is the only secret, and URLs leak.--<Callout type="warn">-**For the web UI, use login-based edge auth (OAuth or SSO), not HTTP Basic Auth.** Live editing needs a WebSocket, and browsers can't send Basic Auth over one, so a Basic Auth gate leaves the editor stuck loading. A login sets a cookie, which does work. (Basic Auth is fine for agent-only access.)-</Callout>--<Callout type="info" title="Serving the UI and headless agents from one gated tunnel">-The UI and a headless MCP agent need *opposite* auth: the browser needs a login (cookie), a headless agent needs a credential it can send with no browser. A single OAuth gate can't do both — an agent hitting an OAuth-gated `/mcp` just gets the login HTML. **ngrok** resolves it with a path-branched traffic policy — OAuth on the UI, Basic Auth on `/mcp`:--```yaml title="policy.yaml"-on_http_request:- - expressions: ["req.url.path.startsWith('/mcp')"]- actions:- - type: basic-auth- config: { credentials: ["agent:CHANGE_ME"] }- - expressions: ["!req.url.path.startsWith('/mcp')"]- actions:- - type: oauth- config: { provider: google }-```--Run with `--traffic-policy-file policy.yaml`. The agent then connects headlessly by presenting the Basic credential as a header (see [Connecting agents](/docs/deploy/connecting-agents)). **Cloudflare Access** can express the same split (a path-scoped login policy for the UI plus a service token for `/mcp`), but that recipe is not documented here. **Tailscale** sidesteps the whole thing — its network-layer auth covers UI and agents at once.-</Callout>--## Share your knowledge base--Now that it's reachable, there are two ways in: a browser for people, and the MCP endpoint for agents.--### In a browser--The same tunnel URL serves the web UI:--```-https://<your-tunnel-url>/-```--Open it in any browser that can reach the tunnel to browse and edit-the knowledge base. The UI and the MCP endpoint share the one URL (`/` is the editor,-`/mcp` is for agents); there is no separate UI port in remote mode.--Editing is live: changes sync in real time between every connected browser and agent.-A few behaviors to know:--- **Every remote browser acts as the server's owner.** Same identity, full access.-- **The Ask AI panel runs on the server.** Each conversation spawns an agent on the- machine hosting `ok start`, using that machine's installed agent and credentials (not- anything on your device), and its edits sync back like any agent's. Install and sign in- to an agent on the host for Ask AI to work over the tunnel.--Anyone you share the URL with can open it and edit alongside you, all as the same owner, since there are no per-person accounts. Share it deliberately and only with people you trust.--### With agents--Point any MCP client at your endpoint:--```-https://<your-tunnel-url>/mcp-```--See [Connecting agents](/docs/deploy/connecting-agents) for per-client setup (Claude, Cursor, Codex, and others), including how a headless agent passes edge-auth credentials.--Anyone who can reach this URL has full read-write access.--## Back up to a git remote--Optional, but recommended for a server. Your knowledge base is a plain git repository, and OpenKnowledge has a built-in sync engine: point it at a GitHub remote and it commits and pushes as agents write, on its own.--Create an empty **private** GitHub repo, then on the machine:--```bash-gh auth login # authorize this machine (or add a deploy key with write access)-cd ~/knowledge-git remote add origin https://github.com/you/knowledge.git-git branch -M main && git add -A && git commit -m "knowledge base" && git push -u origin main-```--Turn on auto-sync:--```bash-printf 'autoSync:\n enabled: true\n' > .ok/local/config.yml-sudo systemctl restart openknowledge-```--From now on every edit is committed and pushed automatically. The commit author comes from the machine's git identity (`git config user.name` / `user.email`). A fresh server has none set, so commits fall back to a service identity, **OpenKnowledge**. Signing in with `gh` handles pushing, not authorship. Set a git identity if you'd rather commits carry your name. See [GitHub sync](/docs/features/github-sync) for sync modes, conflict handling, and authentication.--The git remote is also a way to edit locally: `git clone` it on your laptop and open the clone in OK Desktop. That gives you a separate local copy with the full editor. It syncs with the server through git (each side pushes and pulls), not live, so changes cross over on the next sync rather than instantly.--## Turning it off--Stop the tunnel, or restart the server without `--remote` — either one closes remote access (without the flag, the server refuses tunneled requests outright). If the URL may have leaked further than intended, rotate it at the tunnel (ngrok and Cloudflare mint a fresh URL on restart; on Tailscale, tighten the ACL).diff --git a/docs/content/features/share.mdx b/docs/content/features/share.mdxindex 9d1eac970..2385c6e6c 100644--- a/docs/content/features/share.mdx+++ b/docs/content/features/share.mdx@@ -6,7 +6,7 @@ description: Copy a link to any doc or folder and send it to a teammate. OpenKnoOpenKnowledge has a Share button in the editor toolbar. Click it and the app copies a `https://openknowledge.ai/d/…` URL to your clipboard. Anyone you send it to lands on a splash page that knows the project and target, and a single click opens it in their copy of OpenKnowledge.-Share links give each recipient their own copy, kept in sync through GitHub. For real-time editing where everyone works on one live server instead, see [Remote access](/docs/deploy/remote-access).+Share links give each recipient their own copy, kept in sync through GitHub. For real-time editing where everyone works on one live server instead, see the [self-hosting overview](/docs/self-hosting/overview).## Sending a share linkdiff --git a/docs/content/get-started/overview.mdx b/docs/content/get-started/overview.mdxindex e1a06cbd3..bdc606d58 100644--- a/docs/content/get-started/overview.mdx+++ b/docs/content/get-started/overview.mdx@@ -22,7 +22,7 @@ OpenKnowledge is three layers working together: a WYSIWYG editor for you, MCP an- Annotate your knowledge base with **[comments](../features/comments.mdx)**, then resolve them with AI.- **[Auto-sync](../features/github-sync.mdx)** knowledge base changes with your team using Git.- Explore your knowledge base through **[graph and wiki-link visualizations](../reference/core-concepts.md#links-and-backlinks)**.-- [Connect to OpenKnowledge](../deploy/connecting-agents.mdx) remotely from local agents, remote agents, or other devices.+- [Connect to OpenKnowledge](../self-hosting/connecting-agents.mdx) remotely from local agents, remote agents, or other devices.## Where to startdiff --git a/docs/content/meta.json b/docs/content/meta.jsonindex 613c4302c..737d94760 100644--- a/docs/content/meta.json+++ b/docs/content/meta.json@@ -12,8 +12,8 @@"...features","---PLUGINS---","...plugins",- "---DEPLOY---",- "...deploy",+ "---SELF-HOSTING---",+ "...self-hosting","---ADVANCED---","...advanced","---IMPORT & TRY---",diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdxindex aced29b51..ac2a24604 100644--- a/docs/content/reference/cli.mdx+++ b/docs/content/reference/cli.mdx@@ -119,7 +119,7 @@ Each project runs its own local server. These commands let you see and stop them## Remote access-Serve this project's web UI and `/mcp` endpoint to your other devices through any HTTPS tunnel, both on one URL. Full setup (and the access-control model) in [Remote access](/docs/deploy/remote-access); point agents at the URL with [Connecting agents](/docs/deploy/connecting-agents).+Serve this project's web UI and `/mcp` endpoint to your other devices through any HTTPS tunnel, both on one URL. Full setup (and the access-control model) in the [self-hosting overview](/docs/self-hosting/overview); point agents at the URL with [Connecting agents](/docs/self-hosting/connecting-agents).| Command | What it does || --- | --- |diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdxindex 033420230..dbc20ec42 100644--- a/docs/content/reference/configuration.mdx+++ b/docs/content/reference/configuration.mdx@@ -52,9 +52,10 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi| `server.externalUrl` | string | (unset) | project | Canonical external origin the server is reached at, e.g. `https://kb.example.com` — its host joins the Host/Origin allowlists and issued URLs. Setting it declares external exposure, which additionally requires the `server.allowExternal` consent interlock. Supersedes `server.publicUrl` (the key's former name — still read as a deprecated alias while this key is absent) and `remote.url`. Env: `OK_EXTERNAL_URL` (`OK_PUBLIC_URL` remains a deprecated alias); flag: `ok start --external-url <url>`. Read at server start. Compatibility note: app versions from before this key existed read only `server.publicUrl` and silently ignore `server.externalUrl` (config is open-shape), so committing only the new key drops the declared host from those versions' Host/Origin allowlists and external requests 403. While collaborators are still on older versions, commit **both** keys with the same value — current versions prefer `server.externalUrl` (no deprecation notice when both are set) and older versions keep reading `server.publicUrl`; drop the old key once everyone has upgraded. || `server.publicUrl` | string | (unset) | project | Deprecated alias of `server.externalUrl` (the key's former name) — read only while that key is absent, with identical semantics; the CLI prints a rename notice when it is the one in effect. Env alias: `OK_PUBLIC_URL`; flag alias: `ok start --public-url <url>`. May be committed alongside `server.externalUrl` during a mixed-version window (see that key's compatibility note). Slated for removal after a deprecation window. || `server.allowExternal` | boolean | `false` | project-local | Exposure consent interlock: a non-loopback `server.bind` (or external requests behind a proxy declared via `server.externalUrl`) is refused without it. Per-machine — consent never travels via git, clone, or share; containers consent via `OK_ALLOW_EXTERNAL=1` instead. There is no server-side auth: restrict who can reach the server at the edge. |+| `server.openBrowser` | boolean | derived: `true` loopback-only, `false` otherwise | project-local | Open the editor in a browser once at start. The derived default means a laptop start pops the UI and an exposed or containerized server stays headless. Env: `OK_OPEN_BROWSER`; flag: `--no-open-browser`. || `server.idleShutdown` | `"off"` or duration (`90s`, `30m`, `2h`) | derived: `30m` loopback-only, `off` otherwise | project-local | Shut the server down after this long with no connected editor (WebSocket) clients. Remote MCP sessions are plain HTTP the timer cannot see — set `off` (or `OK_IDLE_SHUTDOWN=off`) when remote agents use the server, or it tears down under them mid-session. |-| `remote.url` | string | (unset) | project | Superseded by `server.externalUrl` (read only while that key is absent). Public tunnel URL remote clients connect to (e.g. `https://myproject.ngrok.app`); its host is admitted through the Host-header allowlist. Used only when the server is started with the deprecated `ok start --remote` (config alone never enables remote access, and there is no server-side auth). See [Remote access](/docs/deploy/remote-access). |-| `remote.port` | number | `24550` | project | Superseded by `server.port` (read only while that key is absent). Fixed TCP port the server binds when remote access is enabled, so the tunnel's port mapping survives restarts. See [Remote access](/docs/deploy/remote-access). |+| `remote.url` | string | (unset) | project | Superseded by `server.externalUrl` (read only while that key is absent). Public tunnel URL remote clients connect to (e.g. `https://myproject.ngrok.app`); its host is admitted through the Host-header allowlist. Used only when the server is started with the deprecated `ok start --remote` (config alone never enables remote access, and there is no server-side auth). See the [self-hosting overview](/docs/self-hosting/overview). |+| `remote.port` | number | `24550` | project | Superseded by `server.port` (read only while that key is absent). Fixed TCP port the server binds when remote access is enabled, so the tunnel's port mapping survives restarts. See the [self-hosting overview](/docs/self-hosting/overview). || `editor.wordWrap` | boolean | `true` | user | Soft-wrap long lines in the source-mode CodeMirror editor. A personal preference, not project-shared. Toggle from the Settings pane. || `editor.previewTabs` | boolean | `true` | user | Reuse one replaceable preview tab for single clicks in the Files tree and Skills sidebar, so browsing does not accumulate tabs. Double-click the tab title, pin it, or choose **Keep open** from its context menu to make it permanent. Set `false` to open every click in its own tab. Rename transitions still reuse the current tab; back/forward navigation focuses the target's existing tab, or opens a permanent one when it is no longer open. A personal preference; toggle it from **Settings → Preferences → Preview tabs**. || `appearance.preview.autoOpen` | boolean | `true` | user | Whether the agent should open or refresh the OpenKnowledge preview when it edits a doc through the MCP. Default `true` lets the agent route the preview by host capability: the host's in-app browser (Cursor preview pane, Codex's built-in browser, Claude Code Desktop) when one exists, the system browser otherwise. Set `false` to keep the agent's hands off your preview window. This is useful when you're already viewing the doc in OK Desktop, a browser tab on a second display, a non-default browser, or any flow where your extensions / accessibility tooling only work in your own browser. The agent then surfaces the URL on request but does not navigate. The change takes effect on the next preview-related tool call. Toggle from **Settings → Preferences → "Open preview when agent edits"**. |diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdxindex 3c867b3b2..522701450 100644--- a/docs/content/reference/mcp.mdx+++ b/docs/content/reference/mcp.mdx@@ -10,7 +10,7 @@ Every other read tool (`search`, `links`, `history`, etc.) and all write tools rThe surface is **21 tools**. The four write verbs — `write`, `edit`, `delete`, `move` — are native CRUD operations polymorphic over a target. `write`, `edit`, and `delete` nest per-target fields inside the address key (`write({ document: { path, content } })`) and take exactly one target per call: `document`, `folder`, `template`, or `skill` — plus `asset` for `write` and `delete`, and a `documents` batch on `write` that writes several docs in order, each entry carrying its own `summary`. `move` takes flat `from`/`to` paths and auto-detects a document, folder, or asset, with nested `template` and `skill` targets for those two.-To point an MCP client at this server, locally or over a tunnel from another machine, see [Connecting agents](/docs/deploy/connecting-agents).+To point an MCP client at this server, locally or over a tunnel from another machine, see [Connecting agents](/docs/self-hosting/connecting-agents).## Toolsdiff --git a/docs/content/self-hosting/authentication.mdx b/docs/content/self-hosting/authentication.mdxnew file mode 100644index 000000000..0ebc6e3be--- /dev/null+++ b/docs/content/self-hosting/authentication.mdx@@ -0,0 +1,264 @@+---+title: Authentication+icon: LuShieldCheck+description: Control who can reach your knowledge base.+---+## How access works++To control access, you put a gate in front of the server, and that gate has to cover two kinds of clients that sign in differently:++- **People** use the editor in a browser. They sign in with an ordinary login (Google or your SSO), and the browser then sends a session cookie on every request, including the live-editing connection.+- **AI agents** connect to `/mcp` with no browser, so an agent presents a token instead. Usually that is a preset token you generate. Some MCP-aware proxies can instead give the agent its own OAuth popup (via [dynamic client registration](https://datatracker.ietf.org/doc/html/rfc7591) or [client ID metadata documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)), so it signs in and receives its token automatically instead of using a preset one; see [MCP-native edges](#mcp-native-edges).++A login fits people but not agents, and a token fits agents but not the editor, so a complete setup provides **both**: a login on the editor and a token on `/mcp`. That pairing is the split, and it shapes every recipe below.++You add the gate in one of two places: on the tunnel or network that reaches the server, or in a proxy in front of it. A tunnel or private network is quickest when you run the server yourself ([npm method](/docs/self-hosting/methods/npm)); a proxy suits a container on a hosting platform ([Docker method](/docs/self-hosting/methods/docker)). The two mix, so a container can sit behind a tunnel and let the tunnel gate it.++## Tunnels and private networks++If you reach the server through a tunnel or private network, that same layer is the natural place to gate access.++### Tailscale++The simplest option: it sidesteps [the split](#how-access-works). `tailscale serve` admits only devices on your tailnet, so the network itself is the authentication: one gate covering the editor and agents alike, with no login pages and no tokens to mint. Narrow it further with [tailnet ACLs](https://tailscale.com/kb/1018/acls). But `serve` is tailnet-only: it can't reach mobile or cloud agents (Claude iOS, Cursor cloud), which dial from the provider's cloud, not your tailnet. For those, make it public with `tailscale funnel` plus a gate, see [Example: Pomerium](#example-pomerium). If everyone who needs access can join your tailnet, `serve` is usually the right answer.++### ngrok++It puts a login at its edge, and expresses the split in a single path-branched policy: an OAuth login for the browser, a Basic credential for agents.++```yaml title="policy.yaml"+on_http_request:+ - expressions: ["req.url.path.startsWith('/mcp')"]+ actions:+ - type: basic-auth+ config: { credentials: ["agent:CHANGE_ME"] }+ - expressions: ["!req.url.path.startsWith('/mcp')"]+ actions:+ - type: oauth+ config: { provider: google }+```++Run the tunnel with `--traffic-policy-file policy.yaml`. Browsers get the Google login; an agent connects headlessly by sending the Basic credential as a header (see [Connecting agents](/docs/self-hosting/connecting-agents)). Replace `CHANGE_ME` with a strong secret (`openssl rand -hex 24`). For SSO instead of consumer OAuth, ngrok's `--oidc` covers Okta, Azure AD, and Google Workspace.++### Cloudflare Tunnel++It pairs with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/): a login policy on the hostname for the browser, and [service tokens](https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/) for agents (standing credentials, with no hourly expiry). Its [Managed OAuth](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/) can go one step further and serve MCP's own OAuth popup to agents (see [MCP-native edges](#mcp-native-edges)); it requires your domain on Cloudflare.++## In front of a container++A container on a hosting platform gets a public domain with no login of its own, so the gate is a proxy you add. Browsers always get a login; the choice is how agents authenticate:++- A **static bearer token** you generate once and every agent sends as a header. Simplest to run, and the recipe below works this way; the trade-off is one secret shared by everyone.+- An **MCP OAuth popup**, where the agent logs in with nothing to copy, and the only path that reaches mobile and cloud connectors (Claude iOS, Cursor cloud). The [Pomerium recipe](#example-pomerium) below sets it up.++### Example: Caddy + oauth2-proxy++Two small proxy services sit in front of the server, and the routing is what makes the [split](#how-access-works) clean. **Caddy** is the public ingress: it sends `/mcp` straight to the server behind a shared bearer token, and everything else through **[oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/)**, which runs the Google login for the browser. Agents never touch the login; browsers never see the token; and because `/mcp` bypasses oauth2-proxy, its streaming stays clear of the login proxy entirely. Three services, none needing a database.++The hostnames below are Railway's private network (`*.railway.internal`, IPv6-only). On another Docker host, swap them for your compose service names.++**Caddy** is the public ingress. Bake the config into a small image, since managed platforms can't mount a file:++```dockerfile title="Dockerfile (caddy)"+FROM caddy:2+COPY Caddyfile /etc/caddy/Caddyfile+```++```text title="Caddyfile"+:{$PORT} {+ # Agents: a shared bearer token, straight to the server.+ @mcp path /mcp /mcp/*+ handle @mcp {+ route {+ @bad not header Authorization "Bearer {env.MCP_TOKEN}"+ respond @bad "Unauthorized" 401+ reverse_proxy ok.railway.internal:8080 {+ header_up Host {host}+ header_up X-Forwarded-Proto https+ }+ }+ }+ # Everyone else: through the Google login.+ handle {+ reverse_proxy oauth2-proxy.railway.internal:4180 {+ header_up Host {host}+ header_up X-Forwarded-Proto https+ }+ }+}+```++Set `MCP_TOKEN` on the Caddy service to a value from `openssl rand -hex 24`; that string is what agents send.++**oauth2-proxy** runs the browser login. Use the `quay.io/oauth2-proxy/oauth2-proxy:v7` image with your own Google OAuth client (a **Web application** client whose redirect URI is `https://<your-domain>/oauth2/callback`):++```bash title="oauth2-proxy service environment"+OAUTH2_PROXY_PROVIDER=google+OAUTH2_PROXY_CLIENT_ID=<your-google-client-id>+OAUTH2_PROXY_CLIENT_SECRET=<your-google-client-secret>+OAUTH2_PROXY_REDIRECT_URL=https://<your-domain>/oauth2/callback+OAUTH2_PROXY_EMAIL_DOMAINS=example.com+OAUTH2_PROXY_COOKIE_SECRET=<openssl rand -hex 16>+OAUTH2_PROXY_UPSTREAMS=http://ok.railway.internal:8080/+OAUTH2_PROXY_HTTP_ADDRESS=[::]:4180+OAUTH2_PROXY_WHITELIST_DOMAINS=<your-domain>+OAUTH2_PROXY_REVERSE_PROXY=true+OAUTH2_PROXY_SKIP_PROVIDER_BUTTON=true+OAUTH2_PROXY_FLUSH_INTERVAL=100ms+```++**The knowledge-base service** takes the usual two declarations plus the IPv6 bind, and no public domain of its own (Caddy is the only way in):++```bash title="knowledge-base service environment"+OK_ALLOW_EXTERNAL=1+OK_EXTERNAL_URL=https://<your-domain>+OK_BIND=::+```++An agent then connects with the token and no browser step:++```bash+--header "Authorization: Bearer <MCP_TOKEN>"+```++Four settings decide whether this boots the first time:++- **`OAUTH2_PROXY_WHITELIST_DOMAINS` must list your public domain.** Behind Caddy, oauth2-proxy builds its post-login redirect from the forwarded host and refuses any host not on this list, so without it the login silently loops back to itself.+- **`OAUTH2_PROXY_COOKIE_SECRET` must decode to 16, 24, or 32 bytes.** `openssl rand -hex 16` gives a valid 32-character value; `openssl rand -base64 32` gives 44 characters, and oauth2-proxy refuses to start.+- **Caddy must send `X-Forwarded-Proto: https`** (the two `header_up` lines above). TLS terminates at the platform edge, so Caddy speaks plain HTTP inward and would otherwise report the request as `http`, so the server hands the editor a `ws://` socket, which the browser blocks as mixed content on an `https` page and the editor hangs. oauth2-proxy relays that header to its upstream on its own; `OAUTH2_PROXY_REVERSE_PROXY=true` is what makes it trust the forwarded headers for its own client-IP and post-login redirect logic, which the `WHITELIST_DOMAINS` note above depends on. `FLUSH_INTERVAL=100ms` is the [never-buffer rule](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server) for the same path.+- **Bind to IPv6 where the platform's private network requires it.** Railway's is IPv6-only, so `OK_BIND=::` and `HTTP_ADDRESS=[::]:4180`, and Caddy dials the `*.railway.internal` names.++### Example: Pomerium++Use this when you need OpenKnowledge from mobile or cloud agents (Claude iOS, Cursor cloud) with a per-user login: a public endpoint where each agent gets its own OAuth token, no shared secret and no tailnet membership. It is two layers, not one. Any public recipe (ngrok, Cloudflare, the Caddy one above) gives you the **public endpoint**; [Pomerium](https://www.pomerium.com/) adds **per-user OAuth** at the gate, serving MCP's own OAuth on `/mcp` and a cookie login for the editor from one config.++The reason those clients specifically need this: Claude iOS and Cursor's cloud agents dial your server from the provider's cloud, not from the device, so the endpoint has to be genuinely public. A phone has no `mcp-remote` fallback and isn't on your tailnet, so `tailscale serve` can't reach it; `tailscale funnel` (public) plus Pomerium can.++```text+Internet (Claude / Cursor cloud dial in from here)+ | https://<host>/ (editor) + https://<host>/mcp (agents)+ v Tailscale funnel: public TLS on your *.ts.net name+ v Pomerium: per-user Google login; MCP OAuth on /mcp, cookie login on the editor+ v OpenKnowledge: loopback, told its public externalUrl+```++**OpenKnowledge** runs on loopback, told its public origin. Pomerium is the only way in, so the server keeps no exposure of its own:++```bash+OK_ALLOW_EXTERNAL=1 ok start -p 24550 --no-open-browser --idle-shutdown off \+ --external-url https://<host>+```++The "external access enabled, no server-side auth" banner is expected here: Pomerium is the auth, and the server stays on loopback.++**Pomerium** runs as a container with a persistent databroker, so sessions and tokens survive a restart. It needs your own Google OAuth client (a **Web application** client whose redirect URI is `https://<host>:8443/oauth2/callback`), plus two secrets and a signing key you generate locally:++```bash+# Run this to write .env (the $(...) execute now; they are not literal values).+cat > .env <<EOF+SHARED_SECRET=$(openssl rand -base64 32)+COOKIE_SECRET=$(openssl rand -base64 32)+SIGNING_KEY=$(openssl ecparam -genkey -name prime256v1 -noout | base64 | tr -d '\n')+IDP_PROVIDER=google+IDP_CLIENT_ID=<your-google-client-id>+IDP_CLIENT_SECRET=<your-google-client-secret>+EOF+```++Then edit `.env` and fill in `IDP_CLIENT_ID` and `IDP_CLIENT_SECRET` from your Google client.++```yaml title="config.yaml"+address: ":8080"+autocert: false++# Persistent databroker. The default `memory` store loses every session and+# token on restart, which surfaces as reconnect prompts and an OAuth login loop.+databroker_storage_type: file+databroker_storage_connection_string: file:///data/databroker++# Claude authenticates with client ID metadata documents (CIMD); Cursor with+# dynamic client registration (DCR). Enable both.+runtime_flags:+ mcp_dynamic_client_registration: true+mcp_allowed_client_id_domains:+ - 'claude.ai'+ - 'claude.com'+ - 'anthropic.com'+ - '*.anthropic.com'++authenticate_service_url: https://<host>:8443++routes:+ # Agents: the MCP endpoint, path-scoped to /mcp.+ - from: https://<host>+ to: http://host.docker.internal:24550+ name: OpenKnowledge MCP+ prefix: /mcp+ preserve_host_header: true+ mcp:+ server:+ path: /mcp+ policy: { allow: { and: [ { email: { is: [email protected] } } ] } }++ # People: the editor and everything else, behind the Google cookie login.+ - from: https://<host>+ to: http://host.docker.internal:24550+ name: OpenKnowledge UI+ preserve_host_header: true+ allow_websockets: true+ policy: { allow: { and: [ { email: { is: [email protected] } } ] } }+```++```yaml title="docker-compose.yaml"+services:+ pomerium:+ image: pomerium/pomerium:main+ restart: unless-stopped+ env_file: .env+ volumes:+ - ./config.yaml:/pomerium/config.yaml:ro+ - pomerium-data:/data+ ports:+ - "127.0.0.1:8085:8080"+ extra_hosts:+ - "host.docker.internal:host-gateway"+volumes:+ pomerium-data:+```++Bring it up with `docker compose up -d`. Two portability notes: the `pomerium/pomerium:main` tag is required for now, since Pomerium's MCP support is recent and not yet in a stable release. And on Linux without Docker Desktop, `host.docker.internal` may not reach a loopback-bound server (`host-gateway` resolves to the Docker bridge IP, not `127.0.0.1`); run Pomerium with `--network host`, or bind the server to the bridge gateway and restrict it with a firewall rule.++**Tailscale funnel** makes it public on your `*.ts.net` name (MagicDNS, HTTPS, and Funnel must be enabled for the node):++```bash+tailscale funnel --bg --https=443 https+insecure://127.0.0.1:8085+tailscale funnel --bg --https=8443 https+insecure://127.0.0.1:8085+```++Then point a custom MCP connector in Claude (iOS or Desktop) or Cursor at `https://<host>/mcp` and complete the Google login. [Connecting agents](/docs/self-hosting/connecting-agents) has the per-client steps.++The settings that are easy to miss:++- **Two routes, not one.** A single `mcp: server` route answers the browser with "This is an MCP route." Split `/mcp` (agents) from the catch-all (editor).+- **`allow_websockets: true`** on the editor route, or the editor loads but never syncs (the `/collab` socket is blocked).+- **`preserve_host_header: true`** so the public host reaches the server as its `externalUrl`; without it every request is a `403`.+- **Both DCR and CIMD.** `mcp_dynamic_client_registration: true` covers Cursor; `mcp_allowed_client_id_domains` covers Claude, whose `client_id` is a URL that Pomerium fetches and checks against that list.+- **A persistent databroker** (above), or a restart drops every token.++### MCP-native edges++Alternatives to the Pomerium recipe above, as pointers rather than full recipes:+- **[obot mcp-oauth-proxy](https://github.com/obot-platform/mcp-oauth-proxy)**: an MCP-aware OAuth proxy that implements dynamic client registration, the flavor today's clients (Cursor among them) speak.+- **[Cloudflare Managed OAuth](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/)**: serves the MCP OAuth popup at Cloudflare's edge, alongside the [Access](#tunnels-and-private-networks) login for the UI; it requires your domain on Cloudflare.++## Troubleshooting++Common symptoms and their fixes:++- **The editor loads but never syncs, and the browser console shows a `ws://` "Mixed Content" error.** The proxy terminates TLS but reports the request to the server as plain HTTP, so the server hands the editor an insecure `ws://` socket. Make the proxy forward `X-Forwarded-Proto: https` (Caddy: `header_up X-Forwarded-Proto https`).+- **Every request returns `403`.** The `Host` reaching the server doesn't match `OK_EXTERNAL_URL`, usually because the proxy rewrote `Host` to the upstream address. Preserve the client's `Host` (Caddy: `header_up Host {host}`) and point `OK_EXTERNAL_URL` at the public origin. Full [proxy rules](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server).+- **The browser login loops back to the login page.** oauth2-proxy is rejecting its own post-login redirect because the domain isn't allowed. Add your public domain to `OAUTH2_PROXY_WHITELIST_DOMAINS`.+- **An agent gets an HTML login page back from `/mcp`.** The `/mcp` path is behind the browser login instead of a token. Route `/mcp` around the login proxy and gate it with a token, or if you use an MCP-OAuth edge, confirm the client supports it (see [Connecting agents](/docs/self-hosting/connecting-agents)).+- **`/mcp` hangs or times out.** A proxy in front is buffering the streamed response. Turn buffering off on `/mcp` (nginx `proxy_buffering off;`, oauth2-proxy `FLUSH_INTERVAL=100ms`; Caddy streams by default).++Once auth is in place, [Connecting agents](/docs/self-hosting/connecting-agents) covers how each client presents its credential.diff --git a/docs/content/self-hosting/connecting-agents.mdx b/docs/content/self-hosting/connecting-agents.mdxnew file mode 100644index 000000000..b76a05774--- /dev/null+++ b/docs/content/self-hosting/connecting-agents.mdx@@ -0,0 +1,85 @@+---+title: Connecting agents+icon: LuPlug+description: Point your agents (Claude Code, Cursor, Claude Desktop, and more) at one shared knowledge base.+---+Prerequisite: a running server with [remote access](/docs/self-hosting/overview) set up. OpenKnowledge doesn't authenticate callers itself; the edge in front of it (a tunnel or proxy) decides who can reach the URL (see [Authentication](/docs/self-hosting/authentication)). To add someone else's machine, first get them through that edge (a tailnet invite, an allowlist entry, or the shared token), then send them here.++Every client below points at the same address, `https://<your-external-url>/mcp`, whether the server runs on your laptop, a VPS, or a container.++## Connect every agent in one command++[`add-mcp`](https://github.com/neon-solutions/add-mcp), a community tool, detects which agents are installed on the machine and writes each one's MCP config for you (Claude Code, Cursor, Codex, VS Code, Windsurf, Goose, Zed, and more):++```bash+npx add-mcp https://<your-external-url>/mcp --name ok-remote+```++If your `/mcp` endpoint is behind a token at the edge (a **bearer token** or **Basic Auth** from your [Authentication](/docs/self-hosting/authentication) setup), pass it as a header so the agent connects with no browser step:++```bash+npx add-mcp https://<your-external-url>/mcp --name ok-remote \+ --header "Authorization: Bearer <your-token>"+```++For Basic Auth, the header is `Authorization: Basic $(printf 'user:pass' | base64)` instead.++A plain **OAuth/SSO** login can't be used this way: a headless agent can't complete a browser sign-in. Gate `/mcp` with a token, a [path-branched policy](/docs/self-hosting/authentication#tunnels-and-private-networks), or Tailscale instead.++The exception is an [MCP-native edge](/docs/self-hosting/authentication#mcp-native-edges) (such as Pomerium), which lets the agent sign in through its own browser popup with no token to set. Pomerium serves CIMD by default (which Claude uses) and DCR when you enable `mcp_dynamic_client_registration` (which Cursor and `mcp-remote` use), so both work; the [Pomerium recipe](/docs/self-hosting/authentication#example-pomerium) turns both on.++The per-client setups below use a plain `/mcp` URL. If yours is behind a token, add the same `Authorization` header shown above (details in [Authentication](/docs/self-hosting/authentication)).++## Claude Code++```bash+claude mcp add --transport http ok-remote https://<your-external-url>/mcp+```++## Cursor++```json title="~/.cursor/mcp.json"+{+ "mcpServers": {+ "ok-remote": { "url": "https://<your-external-url>/mcp" }+ }+}+```++## Codex++Recent Codex versions take the URL directly:++```toml title="~/.codex/config.toml"+[mcp_servers.ok-remote]+url = "https://<your-external-url>/mcp"+```++## Claude Desktop++Claude Desktop only takes command-type servers, so it reaches the server through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, a local process that forwards to your `/mcp` URL.++Its config file is `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. In Claude Desktop open **Settings → Developer → Edit Config**, which creates the file and reveals it. Then add:++```json title="claude_desktop_config.json"+{+ "mcpServers": {+ "ok-remote": {+ "command": "npx",+ "args": ["-y", "mcp-remote", "https://<your-external-url>/mcp"]+ }+ }+}+```++If your `/mcp` is behind a token, add it to the `args` array: `"--header", "Authorization: Bearer <your-token>"`.++## Agent harnesses (OpenClaw, Hermes, etc.)++Add the `/mcp` URL to your harness's MCP server config, the same way as above. Its agents can then read and write your knowledge base.++## Cloud connectors (Claude.ai, ChatGPT, etc.)++Cloud-dialed clients connect from the vendor's cloud, so your URL must be publicly reachable over HTTPS. The Claude and ChatGPT connectors require OAuth, which OpenKnowledge does not serve itself; an MCP-aware OAuth edge in front of `/mcp` supplies it. The [Pomerium recipe](/docs/self-hosting/authentication#example-pomerium) is the path we've verified for the Claude connector (iOS and Desktop) and Cursor's cloud agents, though connector support otherwise varies by vendor. Connectors that accept a bearer token or API key instead (Microsoft Copilot Studio, Perplexity, etc.) can use a token you enforce at the edge: gate `/mcp` with a static bearer token (an ngrok traffic policy, a Cloudflare Access service token, or your auth proxy), then paste that same token into the connector's settings, the way an on-device agent presents its credential as a header.++Claude Desktop is not a cloud connector; it uses the `mcp-remote` bridge covered above.diff --git a/docs/content/self-hosting/meta.json b/docs/content/self-hosting/meta.jsonnew file mode 100644index 000000000..131ab405f--- /dev/null+++ b/docs/content/self-hosting/meta.json@@ -0,0 +1,5 @@+{+ "title": "Self-hosting",+ "icon": "LuServer",+ "pages": ["overview", "methods", "authentication", "connecting-agents"]+}diff --git a/docs/content/self-hosting/methods/docker.mdx b/docs/content/self-hosting/methods/docker.mdxnew file mode 100644index 000000000..75b03bc44--- /dev/null+++ b/docs/content/self-hosting/methods/docker.mdx@@ -0,0 +1,145 @@+---+title: Docker+icon: custom/Docker+description: Build the OpenKnowledge container image and run it on Railway, Fly.io, or any Docker host.+---+For an always-on knowledge base without managing a box, run the server as a container on a hosting platform (Railway, Fly.io, or your own Docker host). The platform provides the domain and TLS; a volume holds the project; the `OK_*` environment variables carry the same declarations as every other path. Read [How exposure works](/docs/self-hosting/overview#how-exposure-works) first if you haven't.++## What any host must provide++The recipes on this page are examples, not requirements. The server runs anywhere that provides:++- **One always-on instance.** The collaboration server is single-writer: exactly one server process per project. Don't scale to multiple replicas, and don't scale to zero between requests.+- **A persistent volume with a real filesystem**, mounted at `/data`. The project is a live git repository the server watches and writes. Container-layer storage is lost on recreate, and network filesystems built for object storage fit it poorly.+- **HTTP ingress that supports WebSockets and doesn't buffer streaming responses.** Live editing runs over a WebSocket, and `/mcp` streams server-sent events (details in the [proxy rules](#rules-for-anything-in-front-of-the-server) below).+- **TLS at the edge, with `X-Forwarded-Proto: https` preserved on the way in.** Every platform edge does this out of the box; if you insert your own plain-HTTP proxy, set the header yourself.+- **The two declarations from [How exposure works](/docs/self-hosting/overview#how-exposure-works)**: `OK_EXTERNAL_URL` naming the public origin, and `OK_ALLOW_EXTERNAL=1` consenting to exposure.++Anything that checks those boxes, whether a hosting platform, an orchestrator, or a box under your desk, will run the image.++## Build the image++There is no official OpenKnowledge image on a registry yet, so build your own from two small files:++```dockerfile title="Dockerfile"+FROM node:24-slim++# git is a hard boot requirement: the server runs a git preflight at boot+# and the version-history subsystems shell out to the binary.+RUN apt-get update \+ && apt-get install -y --no-install-recommends git ca-certificates \+ && rm -rf /var/lib/apt/lists/*++RUN npm install -g @inkeep/open-knowledge++# PORT is the platform-injection contract: Railway/Fly/Cloud Run override+# it at run time; 8080 is only the local-run default.+# OK_BIND=0.0.0.0 makes the listener reachable from the container network.+# Consent (OK_ALLOW_EXTERNAL=1) is deliberately NOT baked: a run without it+# refuses to boot and names the fix. That refusal is the secure default.+ENV PORT=8080 \+ OK_BIND=0.0.0.0++# No `VOLUME /data`: managed builders (Railway, Fly) reject the+# instruction, and for plain `docker run` it only creates anonymous+# volumes. Persistence is the operator's job: mount a volume at /data,+# or data lives in the container layer and is lost on recreate.+WORKDIR /data+EXPOSE 8080++COPY entrypoint.sh /usr/local/bin/entrypoint.sh+RUN chmod +x /usr/local/bin/entrypoint.sh+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]+```++The entrypoint is the container's boot script, run on every start. `ok start` needs an initialized project, and no one is inside the container to run `ok init` by hand, so the script does it: the first boot against an empty volume initializes the project, and every boot after finds `.ok/` already there and goes straight to the server. It's the same pattern the official database images use for an empty data directory. (`--no-mcp --no-skills` only skip scaffolding local agent config and skill files the container doesn't need; the server's own `/mcp` endpoint is always served.)++```sh title="entrypoint.sh"+#!/bin/sh+# First-boot init: scaffold the project exactly once, on an empty volume.+# Any initialized (or restored) volume skips straight to `ok start`.+# stdin is closed so `ok init` takes its non-TTY defaults and can never+# hang on a prompt.+set -eu+if [ ! -d /data/.ok ]; then+ echo "[entrypoint] /data not initialized — running: ok init --no-mcp --no-skills"+ ok init --no-mcp --no-skills < /dev/null+fi+exec ok start+```++Test it locally:++```bash+docker build -t open-knowledge:local .+docker run --rm -p 8080:8080 -e OK_ALLOW_EXTERNAL=1 -v ok-data:/data open-knowledge:local+# → http://localhost:8080+```++## The environment surface++| Variable | Container default | Meaning |+| --- | --- | --- |+| `PORT` | `8080` | Listen port. Platform-injected `PORT` (Railway, Fly, Cloud Run) overrides it at run time; don't set it yourself on those platforms. |+| `OK_BIND` | `0.0.0.0` | Bind address list. On an IPv6-only network set `::` instead (dual-stack, serves IPv4 too); don't combine `0.0.0.0 ::` on one port, since the dual-stack listener collides. |+| `OK_ALLOW_EXTERNAL` | unset | Run-time exposure consent. Without it the interlock refuses to boot. |+| `OK_EXTERNAL_URL` | unset | The public origin the deployment is reached at. Required behind any real domain, or hostname requests are rejected with `403`. |+| `OK_IDLE_SHUTDOWN` | unset | Idle shutdown already defaults to `off` on a non-loopback bind; set a duration (`30m`) to opt back in. |++Health endpoints for platform checks: `GET /healthz` (liveness) and `GET /readyz` (readiness).++<Callout type="warn" title="Run exactly one replica per volume">+The collaboration server is single-writer: one server process per project volume. Keep the service at **1 replica**, because scaling to 2+ silently runs two writers against the same data, and inside a container nothing enforces the exclusion. Multiple *projects* are fine as multiple services, each with its own container, volume, and domain.+</Callout>++## Deploy on Railway++Railway builds the Dockerfile server-side, injects `PORT` and TLS, and hands out a domain; the whole flow is one deploy. From the directory with the `Dockerfile` and `entrypoint.sh`:++```bash+railway login+railway init --name my-kb # create the project+railway add --service my-kb --variables "OK_ALLOW_EXTERNAL=1" # create the service + consent+railway volume --service <service-id> add --mount-path /data # persistent volume (see note below)+railway domain --service my-kb --port 8080 # generate the domain (works pre-deploy)+railway variables --service my-kb --set 'OK_EXTERNAL_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}'+railway up --service my-kb --detach # one deploy; externalUrl correct from first boot+railway logs --service my-kb # watch the first boot+```++`${{RAILWAY_PUBLIC_DOMAIN}}` is a Railway reference variable that resolves to the generated domain at deploy time, so `OK_EXTERNAL_URL` is right from the first boot, with no deploy-then-set-then-redeploy loop. On first boot the entrypoint initializes the empty volume, then the server comes up; the log shows the exposure banner naming your domain. Set the platform health check to `/readyz`.++A few Railway-specific caveats:++- **Don't set `PORT`.** Railway injects it, and setting it yourself fights the platform.+- **Leave replicas at 1** (see the single-writer callout above).+- **`railway volume` wants the service ID, not the name.** Every other command above accepts the service name, but on current CLIs `volume` can crash on a name. Get the ID from `railway status --json`.+- **Subcommand flags drift across Railway CLI versions.** If a command errors, check `railway <cmd> --help` for where the `--service` flag goes.+- **Setting a variable and immediately running `railway redeploy` can race.** The redeploy can snapshot the environment before the variable applies. Use `railway up`, or redeploy after the variable shows in `railway variables`.++## Other platforms++The same image runs anywhere Docker does. On Fly.io, mount a volume at `/data`, set the same two `OK_*` variables with the `.fly.dev` domain, and point a check at `/readyz`. With Docker Compose (on a platform *or* your own VPS; the pieces mix and match), you can instead add a `cloudflared` sidecar as the only ingress, skip the public domain entirely, and set `OK_EXTERNAL_URL` to the tunnel hostname.++The big clouds (AWS, GCP, Azure) run the image well on a VM with Docker, or you can use the [npm method](/docs/self-hosting/methods/npm#a-server-you-manage) directly. Their serverless container products are a weaker fit: they don't always provide a persistent disk that meets the [requirements above](#what-any-host-must-provide), and some scale in ways the single-writer server can't use. Fully serverless platforms (Vercel, Netlify) can't host it: the server is one long-lived stateful process, not request-scoped functions.++## Upgrading++The image installs whatever version of `@inkeep/open-knowledge` is current at build time, so upgrading means rebuilding the image and redeploying onto the same volume. The entrypoint finds the volume already initialized and goes straight to the server; your content, history, and settings all live on the volume and carry over. On Railway, that's `railway up` again from the Dockerfile directory.++Two practices make this predictable:++- **Pin the version in the Dockerfile** (`RUN npm install -g @inkeep/open-knowledge@<version>`) and bump the line to upgrade. An unpinned install can silently reuse Docker's cached build layer, leaving you on the old version while looking freshly deployed; a pinned bump changes the line, which busts the cache, and it gives you an exact version to rebuild if you ever want to go back.+- **Snapshot the volume before upgrading**: your platform's volume backup, or a plain tar of `/data`. A snapshot restored onto a fresh volume boots straight to the server, since the entrypoint treats any initialized volume as ready.++## Rules for anything in front of the server++Three rules apply to any proxy you place between clients and the container (an auth proxy, nginx, a CDN layer):++- **Preserve the original `Host` header.** The server admits requests by their `Host`, matched against `OK_EXTERNAL_URL`. Many reverse proxies rewrite `Host` to the *upstream* address (`ok:8080`) by default, which no longer matches and gets rejected with `403` on **every** request. Forward the client's host instead: Caddy `header_up Host {host}`, nginx `proxy_set_header Host $host;`. Platform edges preserve it automatically; a proxy you add yourself usually does not.+- **Never buffer `/mcp`.** It's a streaming (server-sent events) endpoint; a proxy that buffers or compresses it hangs every agent connection until timeout. nginx needs `proxy_buffering off;` on that path; Caddy streams by default; platform edges pass SSE through. The rule applies to any proxy *you* add.+- **A TLS-terminating proxy that speaks plain HTTP to the server must set `X-Forwarded-Proto: https`.** The server derives secure WebSocket URLs (`wss://`) from that header; a proxy that stamps it back to `http` makes the editor try an insecure `ws://` from an `https://` page, which browsers block, leaving the editor stuck on loading skeletons. Platform edges set it correctly; an auth proxy between the edge and the server often does not.++## Next steps++[Try the deployment](/docs/self-hosting/overview#try-it-out) with a real MCP handshake against the public domain, then lock it down: the platform domain has no login of its own, so anyone who finds the URL has full read-write control until you [add authentication](/docs/self-hosting/authentication).diff --git a/docs/content/self-hosting/methods/meta.json b/docs/content/self-hosting/methods/meta.jsonnew file mode 100644index 000000000..f92d690ad--- /dev/null+++ b/docs/content/self-hosting/methods/meta.json@@ -0,0 +1,6 @@+{+ "title": "Deployment methods",+ "icon": "LuBoxes",+ "defaultOpen": true,+ "pages": ["npm", "docker"]+}diff --git a/docs/content/self-hosting/methods/npm.mdx b/docs/content/self-hosting/methods/npm.mdxnew file mode 100644index 000000000..4d516d5eb--- /dev/null+++ b/docs/content/self-hosting/methods/npm.mdx@@ -0,0 +1,212 @@+---+title: npm+icon: custom/Npm+description: Run OpenKnowledge on your own machine, reached through a tunnel or reverse proxy.+---+Install OpenKnowledge from npm, then run the server yourself:++```bash+npm install -g @inkeep/open-knowledge+```++Run it on your laptop for the quickest start, or on a server to keep it always available. A tunnel or reverse proxy gives the server its public URL. New to these settings? Read [How exposure works](/docs/self-hosting/overview#how-exposure-works) first.++## Your laptop, behind a tunnel++The quickest path: OpenKnowledge already runs your project, and a tunnel gives it a public HTTPS URL. The catch is that it's only reachable while the machine is awake. Close the lid and your agents lose access. To keep it always available, use [a server you manage](#a-server-you-manage) or the [Docker method](/docs/self-hosting/methods/docker).++### 1. Pin a port and open a tunnel++A local start normally picks a free port dynamically, but a tunnel forwards to one fixed port, so pin it first. Add a `server:` block to the `.ok/config.yml` that `ok init` created (the file is all commented defaults until you add keys):++```yaml title=".ok/config.yml"+server:+ port: 8080+```++Any HTTPS tunnel works. It forwards a public URL to that local port. Pick one:++<Callout type="info">+Install your tunnel's client on the machine first if it isn't already.+</Callout>++<Tabs groupId="ok-tunnel" persist items={['Tailscale', 'ngrok', 'Cloudflare Tunnel']}>++<Tab>++Private, only devices on your tailnet can reach it. Requires [HTTPS enabled in your tailnet](https://tailscale.com/kb/1153/enabling-https).++```bash+tailscale serve --bg 8080+# → https://<machine>.<tailnet>.ts.net+```++If `serve` says Tailscale is stopped, run `tailscale up` first (on a Linux server you may also need `sudo systemctl start tailscaled`).++</Tab>++<Tab>++Public URL; add edge auth to restrict (see [Authentication](/docs/self-hosting/authentication)).++```bash+ngrok http 8080+# → https://<something>.ngrok.app+```++</Tab>++<Tab>++A quick public URL on a `*.trycloudflare.com` address, fresh each run. For a stable URL on your own domain, and to pair with [Cloudflare Access](/docs/self-hosting/authentication), set up a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) instead.++```bash+cloudflared tunnel --url http://localhost:8080+```++</Tab>++</Tabs>++Each one gives you a public HTTPS URL. That URL is your `server.externalUrl`.++### 2. Configure and start++Declare the public origin in the project config, next to the port:++```yaml title=".ok/config.yml"+server:+ port: 8080+ externalUrl: https://<your-tunnel-url>+```++<Callout type="warn">+**`server.externalUrl` must be the exact address people will use**: the full tunnel URL, with `https://` and no trailing path. If it doesn't match what the tunnel forwards, the server turns those requests away with a `403` error.+</Callout>++Then consent on this machine, in the gitignored per-machine config:++```yaml title=".ok/local/config.yml"+server:+ allowExternal: true+ idleShutdown: "off"+```++`idleShutdown: "off"` keeps the server from stopping after 30 idle minutes. The idle timer only counts editor connections, not agent calls, so without it a server busy with a remote agent looks idle and shuts down mid-session.++Now start it from the project directory:++```bash+ok start+```++The server prints a warning banner naming the public origin on every exposed start. For a one-off session, the environment does the same job without touching config files:++```bash+OK_ALLOW_EXTERNAL=1 OK_IDLE_SHUTDOWN=off ok start --external-url https://<your-tunnel-url> --port 8080+```++Now [try it out](/docs/self-hosting/overview#try-it-out).++## A server you manage++A VPS, Mac mini, or any computer you can leave running. It keeps your knowledge base available at all times, and you keep full control of the box.++### Set up the box++On a VPS, providers like Hetzner, DigitalOcean, and Lightsail all work. Pick Ubuntu 24.04 (1 GB RAM is comfortable; 512 MB runs a small knowledge base), add your SSH key at creation, and `ssh root@<ip>` in. Every step below happens in that shell.++Install OpenKnowledge (and Node 24 first, on a fresh box):++```bash+curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash - && sudo apt-get install -y nodejs git+npm install -g @inkeep/open-knowledge+```++Create the project (`ok init` sets up git for you):++```bash+mkdir ~/knowledge && cd ~/knowledge && ok init+```++To start from existing notes, `git clone` them as the project directory instead of `mkdir`, then run `ok init` inside.++### Give it a URL++Two good options:++- **A tunnel**: exactly the [laptop steps above](#1-pin-a-port-and-open-a-tunnel), run on the server. Tailscale is especially natural here: the box joins your tailnet and only your devices can reach it, with nothing exposed to the public internet.+- **Your own domain with a reverse proxy.** Point DNS at the server and let [Caddy](https://caddyserver.com/) terminate TLS (it provisions certificates automatically):++ ```text title="/etc/caddy/Caddyfile"+ notes.example.com {+ reverse_proxy 127.0.0.1:8080+ }+ ```++ ```yaml title=".ok/config.yml"+ server:+ port: 8080+ externalUrl: https://notes.example.com+ ```++ Caddy handles the [proxy rules](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server) (Host preservation, `X-Forwarded-Proto`, no buffering on `/mcp`) automatically; just don't add an `encode` directive on `/mcp`. A different proxy (nginx, etc.) needs those set by hand, or requests 403 and the editor's WebSocket fails.++Either way, consent on the box (`.ok/local/config.yml` with `allowExternal: true` and `idleShutdown: "off"`, as in the laptop path; the same [config-and-start step](#2-configure-and-start) applies unchanged).++### Run it as a service++So it survives logout and reboots:++```ini title="/etc/systemd/system/openknowledge.service"+[Unit]+Description=OpenKnowledge server+After=network-online.target++[Service]+User=root+WorkingDirectory=/root/knowledge+ExecStart=/usr/bin/env ok start+Restart=on-failure++[Install]+WantedBy=multi-user.target+```++This matches the `ssh root@<ip>` VPS setup above (project at `/root/knowledge`, `server.*` set in config; the unit needs no flags). If you log in as a different user, set `User` and `WorkingDirectory` to that user and their project path. For a hardened setup, run it under a dedicated unprivileged user (`sudo useradd --system --create-home openknowledge`) rather than `root`, with `User` and `WorkingDirectory` set to match.++Register the service so it starts on every boot, and launch it now:++```bash+sudo systemctl enable --now openknowledge+```++<Callout>+**On macOS**, there's no systemd. Run `ok start` in a terminal, and set the machine not to sleep (System Settings → Energy) for always-on use.+</Callout>++Now [try it out](/docs/self-hosting/overview#try-it-out), then [restrict who can reach it](/docs/self-hosting/authentication).++## Back up to a git remote++Optional, but recommended for a server. Your knowledge base is a plain git repository, and OpenKnowledge has a built-in sync engine: point it at a GitHub remote and it commits and pushes as agents write, on its own.++Create an empty **private** GitHub repo, then on the machine:++```bash+gh auth login # authorize this machine (or add a deploy key with write access)+cd ~/knowledge+git remote add origin https://github.com/you/knowledge.git+git branch -M main && git add -A && git commit -m "knowledge base" && git push -u origin main+```++Turn on auto-sync:++```bash+printf '\nautoSync:\n mode: full\n' >> .ok/local/config.yml+sudo systemctl restart openknowledge+```++From now on every edit is committed and pushed automatically. The commit author comes from the machine's git identity (`git config user.name` / `user.email`). A fresh server has none set, so commits fall back to a service identity, **OpenKnowledge**. Signing in with `gh` handles pushing, not authorship. Set a git identity if you'd rather commits carry your name. See [GitHub sync](/docs/features/github-sync) for sync modes, conflict handling, and authentication.++The git remote is also a way to edit locally: `git clone` it on your laptop and open the clone in OK Desktop. That gives you a separate local copy with the full editor. It syncs with the server through git (each side pushes and pulls), not live, so changes cross over on the next sync rather than instantly.diff --git a/docs/content/self-hosting/overview.mdx b/docs/content/self-hosting/overview.mdxnew file mode 100644index 000000000..0e22b3e23--- /dev/null+++ b/docs/content/self-hosting/overview.mdx@@ -0,0 +1,73 @@+---+title: Overview+icon: LuBookOpen+description: Run OpenKnowledge on a server or container for shared, always-on access from your other devices and agents.+---+By default, your knowledge base is only available on the machine it runs on. Set up remote access to open it from another device, point your agents at it, and let everyone work in the same place. Access control lives outside OpenKnowledge for now: a private network, or a login in front. See [Authentication](/docs/self-hosting/authentication).++## How exposure works++Three settings control remote access:++| Setting | What it is | Where it goes |+| --- | --- | --- |+| `server.externalUrl` | The address clients will use, e.g. `https://kb.example.com`. | `.ok/config.yml`, committed, so the project's setup is shared with your team. |+| `server.allowExternal` | Your permission to accept connections from outside the machine. | `.ok/local/config.yml`, which stays on this machine (gitignored), or the `OK_ALLOW_EXTERNAL=1` environment variable. |+| `server.bind` | Which network addresses the server listens on. Most setups never set it: tunnels work with the default, and the container image sets it for you. | `.ok/local/config.yml`, or the `OK_BIND` environment variable. |++These also exist as environment variables and CLI flags (`OK_EXTERNAL_URL` / `--external-url`) for one-off runs and for containers, where config files aren't the natural home; each walkthrough uses whichever fits. The [Configuration reference](/docs/reference/configuration) has the full details on these settings.++<Callout type="info">+**Everyone connects as the same owner.** There are no per-person accounts yet, so everyone who connects can read and edit everything, exactly as you can. You choose who that is with the options in [Authentication](/docs/self-hosting/authentication).+</Callout>++## Choose a deployment method++| You want | Method |+| --- | --- |+| To reach the machine you already work on, from your other devices | [npm: your laptop, behind a tunnel](/docs/self-hosting/methods/npm#your-laptop-behind-a-tunnel) |+| An always-on server you run yourself | [npm: a VPS or any box you manage](/docs/self-hosting/methods/npm#a-server-you-manage) |+| An always-on server, run for you by a hosting platform | [Docker: a container on a hosting platform](/docs/self-hosting/methods/docker) |++These are recommended pairings, not rules; the pieces mix and match. You can run the container on your own VPS, or run a tunnel next to a container on Railway and skip the public domain entirely. However you assemble it, the server reads the same settings, so every method ends at the same [try-it-out step](#try-it-out) and the same [access-control options](/docs/self-hosting/authentication).++## Try it out++Whichever method you picked, you now have one URL that works two ways: open it in a browser to edit, or point an agent at `/mcp`. Try both.++### In a browser++```+https://<your-external-url>/+```++Open it on any device that can reach the address. The editor loads, and edits sync in real time between every connected browser and agent. That's your first proof the whole path works.++Anyone who can open the URL can edit alongside you, all as the same owner, since there are no per-person accounts. Share it deliberately and only with people you trust.++### With agents++```+https://<your-external-url>/mcp+```++For a quick check without configuring an agent, do the handshake by hand from any device that can reach the address:++```bash+curl -sS -X POST https://<your-external-url>/mcp \+ -H 'content-type: application/json' \+ -H 'accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'+```++The server responds with its details:++```json+{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"open-knowledge","version":"…"}},"jsonrpc":"2.0","id":1}+```++Then point real agents at that URL. [Connecting agents](/docs/self-hosting/connecting-agents) has per-client setup (Claude, Cursor, Codex, and others), including how a headless agent passes edge-auth credentials. Anyone who can open this URL has full read-write access.++## Turning it off++Withdraw your permission by removing `server.allowExternal` from `.ok/local/config.yml` (or no longer passing `OK_ALLOW_EXTERNAL=1`) and restarting; on the default loopback bind the server goes back to refusing outside connections. A container built from the [Docker method](/docs/self-hosting/methods/docker) bakes a non-loopback `OK_BIND`, so dropping consent there makes it refuse to boot instead of falling back. Stopping the tunnel or removing the container's public domain cuts off access from the other side. If the address may have leaked further than intended, rotate it at the edge: ngrok and Cloudflare mint a fresh URL on restart, Tailscale ACLs can be tightened, and a platform domain can be regenerated.diff --git a/docs/next.config.ts b/docs/next.config.tsindex 234acac06..32d2b78ad 100644--- a/docs/next.config.ts+++ b/docs/next.config.ts@@ -111,6 +111,26 @@ const nextConfig: NextConfig = {destination: '/docs/migrate/obsidian',permanent: true,},+ {+ source: '/docs/deploy/remote-access',+ destination: '/docs/self-hosting/overview',+ permanent: true,+ },+ {+ source: '/docs/deploy/remote-access/',+ destination: '/docs/self-hosting/overview',+ permanent: true,+ },+ {+ source: '/docs/deploy/connecting-agents',+ destination: '/docs/self-hosting/connecting-agents',+ permanent: true,+ },+ {+ source: '/docs/deploy/connecting-agents/',+ destination: '/docs/self-hosting/connecting-agents',+ permanent: true,+ },{source: '/docs/advanced/content-rules/okf',destination: '/docs/plugins/okf',diff --git a/docs/src/components/icons/brand.ts b/docs/src/components/icons/brand.tsindex 7cab2843d..a49df39be 100644--- a/docs/src/components/icons/brand.ts+++ b/docs/src/components/icons/brand.ts@@ -3,9 +3,11 @@ import { AntigravityIcon } from './antigravity';import { ClaudeIcon } from './claude';import { CodexIcon } from './codex';import { CursorIcon } from './cursor';+import { DockerIcon } from './docker';import { GitHubIcon } from './github';import { HermesIcon } from './hermes';import { McpIcon } from './mcp';+import { NpmIcon } from './npm';import { ObsidianIcon } from './obsidian';import { OpenClawIcon } from './openclaw';import { OpenCodeIcon } from './opencode';@@ -27,6 +29,8 @@ export const brandIcons = {GitHub: GitHubIcon,Obsidian: ObsidianIcon,MCP: McpIcon,+ Npm: NpmIcon,+ Docker: DockerIcon,} as const satisfies Record<string, ComponentType<SVGProps<SVGSVGElement>>>;export type BrandIconName = keyof typeof brandIcons;diff --git a/docs/src/components/icons/docker.tsx b/docs/src/components/icons/docker.tsxnew file mode 100644index 000000000..b1aeef42b--- /dev/null+++ b/docs/src/components/icons/docker.tsx@@ -0,0 +1,24 @@+import type { SVGProps } from 'react';++// Docker whale mark (simple-icons path) — fill-based, tracks `currentColor`+// like the other nav icons.+export function DockerIcon(props: SVGProps<SVGSVGElement>) {+ return (+ <svg+ role="img"+ aria-label="Docker icon"+ width={24}+ height={24}+ viewBox="0 0 24 24"+ fill="none"+ xmlns="http://www.w3.org/2000/svg"+ {...props}+ >+ <title>Docker icon</title>+ <path+ fill="currentColor"+ d="M13.983 11.078h2.119a.186.186 0 00.186-.185V9.006a.186.186 0 00-.186-.186h-2.119a.185.185 0 00-.185.185v1.888c0 .102.083.185.185.185m-2.954-5.43h2.118a.186.186 0 00.186-.186V3.574a.186.186 0 00-.186-.185h-2.118a.185.185 0 00-.185.185v1.888c0 .102.082.185.185.185m0 2.716h2.118a.187.187 0 00.186-.186V6.29a.186.186 0 00-.186-.185h-2.118a.185.185 0 00-.185.185v1.887c0 .102.082.185.185.186m-2.93 0h2.12a.186.186 0 00.184-.186V6.29a.185.185 0 00-.185-.185H8.1a.185.185 0 00-.185.185v1.887c0 .102.083.185.185.186m-2.964 0h2.119a.186.186 0 00.185-.186V6.29a.185.185 0 00-.185-.185H5.136a.186.186 0 00-.186.185v1.887c0 .102.084.185.186.186m5.893 2.715h2.118a.186.186 0 00.186-.185V9.006a.186.186 0 00-.186-.186h-2.118a.185.185 0 00-.185.185v1.888c0 .102.082.185.185.185m-2.93 0h2.12a.185.185 0 00.184-.185V9.006a.185.185 0 00-.184-.186h-2.12a.185.185 0 00-.184.185v1.888c0 .102.083.185.185.185m-2.964 0h2.119a.185.185 0 00.185-.185V9.006a.185.185 0 00-.184-.186h-2.12a.186.186 0 00-.186.186v1.887c0 .102.084.185.186.185m-2.92 0h2.12a.185.185 0 00.184-.185V9.006a.185.185 0 00-.184-.186h-2.12a.185.185 0 00-.184.185v1.888c0 .102.082.185.185.185M23.763 9.89c-.065-.051-.672-.51-1.954-.51-.338.001-.676.03-1.01.087-.248-1.7-1.653-2.53-1.716-2.566l-.344-.199-.226.327c-.284.438-.49.922-.612 1.43-.23.97-.09 1.882.403 2.661-.595.332-1.55.413-1.744.42H.751a.751.751 0 00-.75.748 11.376 11.376 0 00.692 4.062c.545 1.428 1.355 2.48 2.41 3.124 1.18.723 3.1 1.137 5.275 1.137.983.003 1.963-.086 2.93-.266a12.248 12.248 0 003.823-1.389c.98-.567 1.86-1.288 2.61-2.136 1.252-1.418 1.998-2.997 2.553-4.4h.221c1.372 0 2.215-.549 2.68-1.009.309-.293.55-.65.707-1.046l.098-.288Z"+ />+ </svg>+ );+}diff --git a/docs/src/components/icons/npm.tsx b/docs/src/components/icons/npm.tsxnew file mode 100644index 000000000..b7d9ee02a--- /dev/null+++ b/docs/src/components/icons/npm.tsx@@ -0,0 +1,24 @@+import type { SVGProps } from 'react';++// npm mark (simple-icons path) — fill-based, tracks `currentColor` like the+// other nav icons.+export function NpmIcon(props: SVGProps<SVGSVGElement>) {+ return (+ <svg+ role="img"+ aria-label="npm icon"+ width={24}+ height={24}+ viewBox="0 0 24 24"+ fill="none"+ xmlns="http://www.w3.org/2000/svg"+ {...props}+ >+ <title>npm icon</title>+ <path+ fill="currentColor"+ d="M1.763 0C.786 0 0 .786 0 1.763v20.474C0 23.214.786 24 1.763 24h20.474c.977 0 1.763-.786 1.763-1.763V1.763C24 .786 23.214 0 22.237 0zM5.13 5.323l13.837.019-.009 13.836h-3.464l.01-10.382h-3.456L12.04 19.17H5.113z"+ />+ </svg>+ );+}diff --git a/knip.config.ts b/knip.config.tsindex f9179f2d4..78162ec09 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -123,9 +123,7 @@ export default {'packages/server': {entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],project: 'src/**',- ignoreDependencies: [- '@types/shell-quote',- ],+ ignoreDependencies: ['@types/shell-quote'],},'packages/cli': {entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.tsindex dfd95ef49..d7a845280 100644--- a/packages/core/src/bridge/bind-frontmatter-doc.ts+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts@@ -1,4 +1,3 @@-import type * as Y from 'yjs';import type { Err, Ok, Result } from '../config/result.ts';import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.tsindex 8bfdb40cd..005627195 100644--- a/packages/core/src/bridge/bridge-invariant.ts+++ b/packages/core/src/bridge/bridge-invariant.ts@@ -1,4 +1,3 @@-import { fnv1aDigest } from './hash-util.ts';export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.tsindex 2a597ec3d..f4cc8a286 100644--- a/packages/core/src/bridge/compose.ts+++ b/packages/core/src/bridge/compose.ts@@ -1,4 +1,3 @@-import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';diff --git a/packages/core/src/bridge/divergence-locate.ts b/packages/core/src/bridge/divergence-locate.tsindex d979f4b39..6b505314d 100644--- a/packages/core/src/bridge/divergence-locate.ts+++ b/packages/core/src/bridge/divergence-locate.ts@@ -1,4 +1,3 @@-import { findFirstDivergenceIndex } from './tolerance-telemetry.ts';export const BRIDGE_LINE_KINDS = [diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex 01ef76a9f..8fb428b90 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,4 +1,3 @@-import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.tsindex 463e89595..9d9c244b0 100644--- a/packages/core/src/bridge/growth-detect.ts+++ b/packages/core/src/bridge/growth-detect.ts@@ -1,4 +1,3 @@-const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.tsindex 0939885bb..c43fdd7e7 100644--- a/packages/core/src/bridge/intraline-predicate.ts+++ b/packages/core/src/bridge/intraline-predicate.ts@@ -1,4 +1,3 @@-export function rawLineCounts(doc: string): Map<string, number> {const counts = new Map<string, number>();for (const line of doc.split('\n')) {diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.tsindex c0dc65705..251560a35 100644--- a/packages/core/src/bridge/merge-three-way.ts+++ b/packages/core/src/bridge/merge-three-way.ts@@ -65,7 +65,6 @@ export function tryLineLevelCombine(return { clean: true, merged };}-export type BridgeMergeContentLossSide = 'user' | 'agent';export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.tsindex dcc5b0690..01ac80099 100644--- a/packages/core/src/bridge/normalize.ts+++ b/packages/core/src/bridge/normalize.ts@@ -1,4 +1,3 @@-import { stripFrontmatter } from '../extensions/frontmatter.ts';import { bodyEdgeEmpties } from './doc-boundary-space.ts';diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.tsindex 0be5203e4..754dc5cc2 100644--- a/packages/core/src/bridge/pm-structural-equivalence.ts+++ b/packages/core/src/bridge/pm-structural-equivalence.ts@@ -32,7 +32,6 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };const BR_LITERAL_RE = /^<br\s*\/?>$/i;-interface DegradeEntry {readonly label: string;readonly severity: ToleranceClassSeverity;@@ -128,7 +127,6 @@ export interface ComparePmStructuralOptions {ignoreAttrs?: (attrKey: string) => boolean;}-/** Rebuild a node with `fn` applied to each child; identity when childless.* Shared by the degrade canonicalizers so none re-implements the walk. */function mapChildren(@@ -250,7 +248,6 @@ function applyDegrades(tree: PmStructuralNode): {return { normalized: current, fired };}-export function comparePmStructural(expected: PmStructuralNode,actual: PmStructuralNode,diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.tsindex dca644141..af20de1e2 100644--- a/packages/core/src/bridge/subsequence.ts+++ b/packages/core/src/bridge/subsequence.ts@@ -1,4 +1,3 @@-/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):* insertions in `haystack` are free; any dropped or substituted `needle` byte* fails. */diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.tsindex a363dfd54..83d47404a 100644--- a/packages/core/src/markdown/callout-transformer.ts+++ b/packages/core/src/markdown/callout-transformer.ts@@ -1,4 +1,3 @@-import type { Blockquote, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.tsindex 4499dbc92..9807a7e82 100644--- a/packages/core/src/markdown/code-fence.ts+++ b/packages/core/src/markdown/code-fence.ts@@ -1,4 +1,3 @@-export function selectFenceChar(info: string): '`' | '~' {return info.includes('`') ? '~' : '`';}diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex 34704165b..7415c474a 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.tsindex b6299a948..ece5c02a1 100644--- a/packages/core/src/markdown/dedent-block-jsx-close.ts+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts@@ -1,4 +1,3 @@-import { findFencedRegions, isInsideFence } from './fence-regions.ts';const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.tsindex acd398aa6..54774764a 100644--- a/packages/core/src/markdown/details-accordion-promoter.ts+++ b/packages/core/src/markdown/details-accordion-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.tsindex ba9b56384..43ecdc709 100644--- a/packages/core/src/markdown/div-align-promoter.ts+++ b/packages/core/src/markdown/div-align-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.tsindex 4513da9bb..6d3f3643e 100644--- a/packages/core/src/markdown/fence-regions.ts+++ b/packages/core/src/markdown/fence-regions.ts@@ -1,4 +1,3 @@-const FENCE_RE = /^(`{3,}|~{3,})/gm;export function findFencedRegions(src: string): Array<[number, number]> {diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.tsindex 6931623c7..00f5771ee 100644--- a/packages/core/src/markdown/fixtures/index.ts+++ b/packages/core/src/markdown/fixtures/index.ts@@ -1,4 +1,3 @@-import { readFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -9,7 +8,6 @@ function fixturePath(...segments: string[]): string {return resolve(FIXTURES_DIR, ...segments);}-interface GfmExample {section: string;markdown: string;@@ -19,7 +17,6 @@ export function loadGfmExamples(): GfmExample[] {return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];}-interface MdxCrashEntry {id: string;input: string;@@ -71,7 +68,6 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {) as LargeEmbedFixture[];}-export function loadPrd6955Before(): string {return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');}@@ -80,7 +76,6 @@ export function loadPrd6955CorruptedTriplicated(): string {return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');}-export interface NgPinnedCase {id: string;name: string;@@ -97,7 +92,6 @@ export function loadNgPinnedCases(): NgPinnedCase[] {) as NgPinnedCase[];}-export function loadLargeRealistic(): string {return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');}diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.tsindex daa3ef82b..8b1eb8519 100644--- a/packages/core/src/markdown/fixtures/perf/generate.ts+++ b/packages/core/src/markdown/fixtures/perf/generate.ts@@ -1,4 +1,3 @@-import { writeFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -11,7 +10,6 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;const SEED = 0xf1de1117;-function mulberry32(seed: number): () => number {let a = seed >>> 0;return () => {@@ -38,7 +36,6 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {return items[items.length - 1][0];}-const WORDS = ['lorem','ipsum',@@ -156,7 +153,6 @@ function mdxBlock(rand: () => number): string {return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;}-type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';const MIX: readonly [BlockKind, number][] = [@@ -195,7 +191,6 @@ function generateDocument(blockCount: number, seed: number): string {return `${blocks.join('\n\n')}\n`;}-function main(): void {for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {const doc = generateDocument(count, SEED);diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.tsindex 32c055c5b..420dc0fe5 100644--- a/packages/core/src/markdown/guard-flanking-matrix.ts+++ b/packages/core/src/markdown/guard-flanking-matrix.ts@@ -7,7 +7,6 @@ import {import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';-export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;export type FlankClass = 'whitespace' | 'punctuation' | 'other';diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.tsindex 283913255..2653473da 100644--- a/packages/core/src/markdown/handler-shadow-audit.ts+++ b/packages/core/src/markdown/handler-shadow-audit.ts@@ -1,4 +1,3 @@-export interface HandlerShadowWitness {input: string;expect: 'byte' | 'byte-and-reparse-type';diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.tsindex 5d1000cc4..da0a81d23 100644--- a/packages/core/src/markdown/highlight-promoter.ts+++ b/packages/core/src/markdown/highlight-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.tsindex 9681c0056..787315157 100644--- a/packages/core/src/markdown/html-to-mdast.ts+++ b/packages/core/src/markdown/html-to-mdast.ts@@ -1,4 +1,3 @@-import type { Element as HastElement, Root as HastRoot } from 'hast';import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';import rehypeParse from 'rehype-parse';@@ -129,8 +128,7 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRothrow new HtmlPayloadTooLargeError(html.length, maxBytes);}- const processor = unified()- .use(rehypeParse, { fragment: true });+ const processor = unified().use(rehypeParse, { fragment: true });for (const plugin of cleanupPlugins) {processor.use(plugin);diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.tsindex 994eb6917..706fa9afb 100644--- a/packages/core/src/markdown/image-promoter.ts+++ b/packages/core/src/markdown/image-promoter.ts@@ -1,4 +1,3 @@-import type { Image, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.tsindex ec1ac1b7e..779e27500 100644--- a/packages/core/src/markdown/index.ts+++ b/packages/core/src/markdown/index.ts@@ -1,4 +1,3 @@-import {type FromProseMirrorOptions,fromPmMark,@@ -207,7 +206,6 @@ export class MarkdownManager {}}-const registry = createRegistry();function destructureAttrs(@@ -256,7 +254,6 @@ function destructureAttrs(return result;}-function hasDirtyDescendant(node: PmNode): boolean {let found = false;node.descendants((child) => {@@ -279,7 +276,6 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChecreturn freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;}-function isEmptyMdastParagraph(node: MdastNodes): boolean {if (node.type !== 'paragraph') return false;const children = node.children ?? [];@@ -348,7 +344,6 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {return out;}-import {AUDIO_EXTENSIONS,FILE_ATTACHMENT_EXTENSIONS,@@ -601,7 +596,6 @@ function buildMdastToPmHandlers(}));}-if (m.emphasis) {handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({sourceDelimiter: node.data?.sourceDelimiter ?? '*',@@ -682,7 +676,6 @@ function buildMdastToPmHandlers(}));}-if (m.link) {const sourceLiteralMark = m.sourceLiteral;handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {@@ -980,7 +973,6 @@ function buildMdastToPmHandlers(};}-const blockUnknownHandler = (node: {type: string;position?: { start: { offset: number }; end: { offset: number } };@@ -1106,7 +1098,6 @@ function buildMdastToPmHandlers(return handlers as RemarkProseMirrorOptions['handlers'];}-function buildPmToMdastHandlers(schema: Schema,freshness: FreshnessCheckerHolder,diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.tsindex b79e9aef7..fa0be9e86 100644--- a/packages/core/src/markdown/lint/applies-to.ts+++ b/packages/core/src/markdown/lint/applies-to.ts@@ -1,4 +1,3 @@-import picomatch from 'picomatch';import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.tsindex 94b34dee1..312c9c74b 100644--- a/packages/core/src/markdown/lint/config-files.ts+++ b/packages/core/src/markdown/lint/config-files.ts@@ -1,4 +1,3 @@-const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set(['.markdownlint.json','.markdownlint.jsonc',diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.tsindex 7d97004fb..3d4814597 100644--- a/packages/core/src/markdown/lint/config-schemas.ts+++ b/packages/core/src/markdown/lint/config-schemas.ts@@ -51,7 +51,6 @@ const fullPluginShape = Object.fromEntries(LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),) as z.ZodRawShape;-export const LinterConfigSchema = z.object({enabled: z.boolean(),plugins: z.object(fullPluginShape),diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.tsindex a51f2ffb0..d48eea5e4 100644--- a/packages/core/src/markdown/lint/default-config.ts+++ b/packages/core/src/markdown/lint/default-config.ts@@ -6,7 +6,6 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSettingMD013: false,};-export function resolveMarkdownlintConfig(rules: Record<string, MarkdownlintRuleSetting> | undefined,): Configuration {diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.tsindex 9c9542661..ef478e268 100644--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts@@ -1,4 +1,3 @@-import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';export interface FrontmatterFieldConstraint {diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.tsindex ca6eed91c..eba37cee7 100644--- a/packages/core/src/markdown/lint/frontmatter-validate.ts+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts@@ -1,4 +1,3 @@-import Ajv, { type ValidateFunction } from 'ajv';import Ajv2019 from 'ajv/dist/2019.js';import Ajv2020 from 'ajv/dist/2020.js';diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.tsindex 9c2a0875e..ae5ff2924 100644--- a/packages/core/src/markdown/lint/index.ts+++ b/packages/core/src/markdown/lint/index.ts@@ -1,4 +1,3 @@-import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';import type { LintDiagnostic } from './types.ts';diff --git a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts b/packages/core/src/markdown/lint/okf-frontmatter/materialize.tsindex f438f1b16..7a5af097e 100644--- a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts+++ b/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts@@ -1,4 +1,3 @@-import type { OkfRuleId } from '../okf-rule-meta.ts';import { fileNameFor, OKF_SCHEMA_DIR, okfSchemaPathFor } from './paths.ts';import { OKF_FRONTMATTER_REGISTRY } from './registry.ts';diff --git a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts b/packages/core/src/markdown/lint/okf-frontmatter/paths.tsindex c290b6878..1ee913527 100644--- a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts+++ b/packages/core/src/markdown/lint/okf-frontmatter/paths.ts@@ -1,4 +1,3 @@-import type { OkfRuleId } from '../okf-rule-meta.ts';export const OKF_SCHEMA_DIR = '.ok/okf';diff --git a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts b/packages/core/src/markdown/lint/okf-frontmatter/registry.tsindex 5168602d5..de09740c5 100644--- a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts+++ b/packages/core/src/markdown/lint/okf-frontmatter/registry.ts@@ -1,4 +1,3 @@-import { compileAppliesTo } from '../applies-to.ts';import { validateFrontmatterSource } from '../frontmatter-validate.ts';import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from '../okf-rule-meta.ts';diff --git a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts b/packages/core/src/markdown/lint/okf-frontmatter/schemas.tsindex 89845d3d5..f1c37671b 100644--- a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts+++ b/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts@@ -1,4 +1,3 @@-// file-level form is deliberate: the sibling `biome-ignore` must sit on the line// oxlint-disable unicorn/no-thenablediff --git a/packages/core/src/markdown/lint/okf-project/rules.ts b/packages/core/src/markdown/lint/okf-project/rules.tsindex 8b476332e..6d691ae2b 100644--- a/packages/core/src/markdown/lint/okf-project/rules.ts+++ b/packages/core/src/markdown/lint/okf-project/rules.ts@@ -1,4 +1,3 @@-import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from '../okf-rule-meta.ts';diff --git a/packages/core/src/markdown/lint/okf-rule-meta.ts b/packages/core/src/markdown/lint/okf-rule-meta.tsindex 44913a9dc..4de50d79f 100644--- a/packages/core/src/markdown/lint/okf-rule-meta.ts+++ b/packages/core/src/markdown/lint/okf-rule-meta.ts@@ -1,4 +1,3 @@-export const OKF_RULE_IDS = ['no-wiki-links','log-shape',diff --git a/packages/core/src/markdown/lint/okf-rules.ts b/packages/core/src/markdown/lint/okf-rules.tsindex d0999b62e..1d5538421 100644--- a/packages/core/src/markdown/lint/okf-rules.ts+++ b/packages/core/src/markdown/lint/okf-rules.ts@@ -1,4 +1,3 @@-import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from './okf-rule-meta.ts';import type { OkfRule } from './okf-runner.ts';import { indexShape } from './rules/index-shape.ts';diff --git a/packages/core/src/markdown/lint/okf-runner.ts b/packages/core/src/markdown/lint/okf-runner.tsindex fabb08d6e..de130e3f4 100644--- a/packages/core/src/markdown/lint/okf-runner.ts+++ b/packages/core/src/markdown/lint/okf-runner.ts@@ -1,4 +1,3 @@-import type { Root } from 'mdast';import remarkFrontmatter from 'remark-frontmatter';import remarkGfm from 'remark-gfm';diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.tsindex 03efcf66c..4b9df9c56 100644--- a/packages/core/src/markdown/lint/plugins.ts+++ b/packages/core/src/markdown/lint/plugins.ts@@ -1,4 +1,3 @@-import { z } from 'zod';import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';import {@@ -18,7 +17,6 @@ import {type OkfSlice,} from './types.ts';-const MarkdownlintRuleSettingSchema = z.union([z.boolean(),z.enum(MARKDOWNLINT_RULE_SEVERITIES),diff --git a/packages/core/src/markdown/lint/rules/index-shape.ts b/packages/core/src/markdown/lint/rules/index-shape.tsindex fcbb1b56c..59fe9b87d 100644--- a/packages/core/src/markdown/lint/rules/index-shape.ts+++ b/packages/core/src/markdown/lint/rules/index-shape.ts@@ -1,4 +1,3 @@-import type { List, ListItem } from 'mdast';import { EXIT, visit } from 'unist-util-visit';import { defineScopedOkfRule } from '../okf-runner.ts';diff --git a/packages/core/src/markdown/lint/rules/log-shape.ts b/packages/core/src/markdown/lint/rules/log-shape.tsindex 431e4e9c8..e0159519f 100644--- a/packages/core/src/markdown/lint/rules/log-shape.ts+++ b/packages/core/src/markdown/lint/rules/log-shape.ts@@ -1,4 +1,3 @@-import type { Heading } from 'mdast';import { toString as headingText } from 'mdast-util-to-string';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/lint/rules/no-wiki-links.ts b/packages/core/src/markdown/lint/rules/no-wiki-links.tsindex f75a04d15..2123e977f 100644--- a/packages/core/src/markdown/lint/rules/no-wiki-links.ts+++ b/packages/core/src/markdown/lint/rules/no-wiki-links.ts@@ -1,4 +1,3 @@-import type { Point } from 'unist';import { visit } from 'unist-util-visit';import { defineOkfRule } from '../okf-runner.ts';diff --git a/packages/core/src/markdown/lint/rules/reserved-casing.ts b/packages/core/src/markdown/lint/rules/reserved-casing.tsindex c8b4d8f28..89ef3e4a9 100644--- a/packages/core/src/markdown/lint/rules/reserved-casing.ts+++ b/packages/core/src/markdown/lint/rules/reserved-casing.ts@@ -1,4 +1,3 @@-import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';import { defineOkfRule } from '../okf-runner.ts';diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.tsindex 4fa9a5a27..2a8f4a279 100644--- a/packages/core/src/markdown/lint/types.ts+++ b/packages/core/src/markdown/lint/types.ts@@ -1,4 +1,3 @@-import type { BrokenLinkReason } from '../../schemas/api/agent-write.ts';import type { OkfRuleId } from './okf-rule-meta.ts';@@ -106,7 +105,6 @@ export interface OkfSlice {generate?: { index?: boolean };}-interface RuleOptionSpecBase {key: string;description: string;diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.tsindex 437cc539a..98238656e 100644--- a/packages/core/src/markdown/lint/validation-counts.ts+++ b/packages/core/src/markdown/lint/validation-counts.ts@@ -1,4 +1,3 @@-export interface ValidationSourceCounts {errorCount: number;warningCount: number;diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.tsindex bd79424c7..a5b511f25 100644--- a/packages/core/src/markdown/math-promoter.ts+++ b/packages/core/src/markdown/math-promoter.ts@@ -1,4 +1,3 @@-import type { Code, Root } from 'mdast';import type { Math as MdastMath } from 'mdast-util-math';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.tsindex 00fbc0035..ed89371d0 100644--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts@@ -1,4 +1,3 @@-import type { Comment, Element, ElementContent, Properties } from 'hast';import type { FootnoteDefinition, FootnoteReference } from 'mdast';import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.tsindex df788a80d..8ce2b2492 100644--- a/packages/core/src/markdown/mdast-to-html.ts+++ b/packages/core/src/markdown/mdast-to-html.ts@@ -1,4 +1,3 @@-import type { Element, Root as HastRoot, Text as HastText } from 'hast';import type { Root as MdastRoot, Text as MdastText } from 'mdast';import type { Handler } from 'mdast-util-to-hast';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex fa3cfcd86..bfd7e3109 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.tsindex 17ed2b829..1a897fca8 100644--- a/packages/core/src/markdown/mermaid-promoter.ts+++ b/packages/core/src/markdown/mermaid-promoter.ts@@ -1,4 +1,3 @@-import type { Code, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.tsindex 4aa0490c4..d988f4b8b 100644--- a/packages/core/src/markdown/parse-with-fallback.ts+++ b/packages/core/src/markdown/parse-with-fallback.ts@@ -168,7 +168,6 @@ export function parseRecursive(}}-interface VFilePlace {offset?: number;start?: { offset?: number };@@ -187,7 +186,6 @@ function extractErrorOffset(err: unknown): number | undefined {return undefined;}-interface Region {start: number;end: number;@@ -211,7 +209,6 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {return null;}-export interface TagEvent {kind: 'open' | 'close' | 'self-close';name: string;@@ -358,7 +355,6 @@ function findFallbackRegion(src: string, errorOffset: number): Region {return { start: blockStart, end: blockEnd };}-interface SourceBlock {src: string;start: number;@@ -456,7 +452,6 @@ function tryPerBlockFallback(};}-function wholeDocRawText(source: string): JSONContent {return {type: 'doc',diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.tsindex 43d420187..e6ab4fd57 100644--- a/packages/core/src/markdown/parser-drop-closure.ts+++ b/packages/core/src/markdown/parser-drop-closure.ts@@ -1,4 +1,3 @@-export type DroppedTokenAdjudication =| {kind: 'format-dof-axis';diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.tsindex 55736041c..0e3224206 100644--- a/packages/core/src/markdown/pipeline.ts+++ b/packages/core/src/markdown/pipeline.ts@@ -1,4 +1,3 @@-import {type FromProseMirrorOptions,fromProseMirror,diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.tsindex ccf06e94d..91cdf658f 100644--- a/packages/core/src/markdown/position-aware-join.ts+++ b/packages/core/src/markdown/position-aware-join.ts@@ -1,4 +1,3 @@-import type { Join } from 'mdast-util-to-markdown';import type { Position } from 'unist';import { isBlankLineParagraph } from './zero-emission-blocks.ts';diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.tsindex e5b4c9eba..0f399d34c 100644--- a/packages/core/src/markdown/position-slice.ts+++ b/packages/core/src/markdown/position-slice.ts@@ -1,4 +1,3 @@-import type { Nodes, Root } from 'mdast';import { visit } from 'unist-util-visit';import type { VFile } from 'vfile';@@ -477,8 +476,7 @@ export function applyPositionSliceToNode(const first = source[startOff];if (first !== '[' && first !== '<' && !node.title) {node.data.sourceStyle = 'gfm-autolink';- }- else if (first === '[') {+ } else if (first === '[') {const slice = source.slice(startOff, endOff);const closeBracketIdx = slice.lastIndexOf('](');if (closeBracketIdx !== -1) {diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.tsindex ca225ce9b..db10fa54b 100644--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts@@ -1,4 +1,3 @@-import type { Comment, Element, Root, Text } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.tsindex 3a2524a9a..34068d103 100644--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.tsindex 2279a0189..93151d43b 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.tsindex a0f467c42..188f02d83 100644--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.tsindex 4e8542a21..4ba2c3418 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.tsindex a3c96b24a..1a74b1272 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.tsindex e95cf43d6..de35e7b79 100644--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts@@ -1,4 +1,3 @@-import type { Comment, Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.tsindex ffdb4d5b5..b4be1b2ea 100644--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.tsindex e2a96d1a7..3c8d88b7c 100644--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.tsindex 0389575ac..cf2c9da8e 100644--- a/packages/core/src/markdown/resolve-image-url.ts+++ b/packages/core/src/markdown/resolve-image-url.ts@@ -1,4 +1,3 @@-import { isRelativeUrl } from './safe-url.ts';function isDevDiagnosticContext(): boolean {diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 8be632ba4..4d3250d3a 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,4 +1,3 @@-export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.tsindex 96304e7a5..0dd54070e 100644--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts@@ -1,4 +1,3 @@-import type { JSONContent } from '@tiptap/core';import type { Nodes } from 'mdast';import { expect } from 'vitest';diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.tsindex 93798cf83..7cac5b042 100644--- a/packages/core/src/markdown/serialize-helpers.ts+++ b/packages/core/src/markdown/serialize-helpers.ts@@ -1,4 +1,3 @@-import type { Node as PmNode } from '@tiptap/pm/model';import type {MdxJsxAttribute,diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.tsindex 8c08b7a04..b012a5aff 100644--- a/packages/core/src/markdown/single-dollar-math-promoter.ts+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts@@ -1,4 +1,3 @@-import type { PhrasingContent, Root, Text } from 'mdast';import type { InlineMath } from 'mdast-util-math';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.tsindex 959cc0bd2..3e79f8cb6 100644--- a/packages/core/src/markdown/to-markdown-handlers.ts+++ b/packages/core/src/markdown/to-markdown-handlers.ts@@ -1,4 +1,3 @@-import type { Nodes, Parents } from 'mdast';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { Handle, Info, State } from 'mdast-util-to-markdown';diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.tsindex 6e6d73400..0f1b0f27d 100644--- a/packages/core/src/markdown/underline-promoter.ts+++ b/packages/core/src/markdown/underline-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, Root } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.tsindex 932d7d2a8..1a082bda7 100644--- a/packages/core/src/markdown/unknown-mdast-guard.ts+++ b/packages/core/src/markdown/unknown-mdast-guard.ts@@ -1,4 +1,3 @@-import type { Root as MdastRoot } from 'mdast';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.tsindex ac9f5239b..d578476a7 100644--- a/packages/core/src/markdown/whitespace-char-ref.ts+++ b/packages/core/src/markdown/whitespace-char-ref.ts@@ -1,4 +1,3 @@-const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([[0x20, ' '],[0x09, '\t'],diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.tsindex afd9936fe..6dad26200 100644--- a/packages/core/src/markdown/wiki-link-micromark.ts+++ b/packages/core/src/markdown/wiki-link-micromark.ts@@ -17,7 +17,6 @@ declare module 'micromark-util-types' {}}-const CODE_BANG = 33; // !const CODE_LBRACKET = 91; // [const CODE_RBRACKET = 93; // ]@@ -261,7 +260,6 @@ export function wikiLinkSyntax(): Extension {};}-function enterWikiLink(this: CompileContext, token: Token) {this.enter({@@ -387,7 +385,6 @@ export const wikiLinkToMarkdown: {unsafe: [{ character: '[', inConstruct: ['phrasing'] }],};-const MICROMARK_EXT = wikiLinkSyntax();export function remarkWikiLink(this: Processor) {