Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): reference assets by doc-relative path, never a server URL (#1841)
tim-inkeep6df070867e9e
diff --git a/.changeset/asset-doc-relative-paths.md b/.changeset/asset-doc-relative-paths.mdnew file mode 100644index 000000000..b47023299--- /dev/null+++ b/.changeset/asset-doc-relative-paths.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++OK skill guidance now tells agents to reference images and other assets by a doc-relative path and never by a server URL. Previously an agent (notably in Codex) could embed an absolute `http://localhost:<port>/…` preview-server URL — which is machine- and session-specific and breaks portability, sharing, and the published docs render. The Media section now states the rule explicitly, covers the "reference an asset already in the tree" case, and clarifies that `preview_url`'s URL navigates the preview and must never be pasted into an image embed.diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.mdindex ad281a4c4..f26b0eb85 100644--- a/packages/server/assets/skills/project/SKILL.md+++ b/packages/server/assets/skills/project/SKILL.md@@ -232,6 +232,7 @@ Knowledge-base docs are factual artifacts — whether the project is a wiki, an## Media — images and attachments- **Markdown syntax only:** ``. Do NOT emit HTML `<img>` tags — they don't participate in OK's content graph and don't render consistently across Fumadocs / preview surfaces. Paths resolve relative to the doc.+- **Always a doc-relative path — never a server URL.** Reference an asset by its path relative to the doc (`./image.png`, `../assets/foo.png`), never an absolute `http://localhost:<port>/…`, `127.0.0.1`, or other server URL. `preview_url`'s `url` navigates the *preview* — it is NOT an asset path; never paste it (or any `localhost` base) into an `![]()`. An asset already in the tree is the same rule: find its path with `exec("ls -A <dir>")` and write the relative link. (Upload via `write({ asset })` hands you the exact relative `` to copy.)- **Save locally, don't hot-link.** Hot-linked external image URLs rot when the source disappears. Fetch (`WebFetch` / `curl`), save to a local path, reference via relative markdown link, cite the source below.- **Placement model.** Free-form image embeds → co-located alongside the referencing doc (sha256 same-directory dedup). Raw sources via `ingest` → `external-sources/<slug>.<ext>` + `external-sources/<slug>.md` (the wrapper-binary pair). Check via `exec("ls -A")` if the project uses a different convention.- **Cannot fetch** (no network, paywall) → don't invent a local path. Omit, or mark inline `(TODO: image needs sourcing from <URL>)`.@@ -416,7 +417,7 @@ The skill carries the trigger ("KB content changed this turn — go look"). The| Make the Claude Code Desktop preview work | Read / diagnose / edit `.claude/launch.json` (host-managed config) | Call `preview_start("open-knowledge-ui")` and nothing else; the OK lock-collision proxy bridges any port mismatch transparently || Open a doc in the app from the Claude Code CLI | Print the `previewUrl` / `openknowledge://` string for the user to click | Run `ok open <doc>` — it opens the OK Desktop app (folders open in the browser), with browser fallback || Reference another doc | `` `[text](./page.md)` `` (backticked) or HTML `<a>` | `[text](./page.md)` (raw markdown) |-| Embed an image | `<img src="...">` (HTML) or hot-linked external URL | Fetch + save locally + `` |+| Embed an image | `<img src="...">` (HTML), a `localhost:<port>` / `preview_url` server URL, or hot-linked external URL | Fetch + save locally + doc-relative `` || Write a factual claim in a KB doc | plausible prose without citation, OR inline `[source](https://URL)` | `ingest` the source first, then cite the local path per Grounding || Cite a web source you just fetched | inline `[source](https://...)` because YOU did the fetch (not the user) | `ingest` it — agent-initiated fetches are not exempt from the closed-loop rule || Finish a turn that changed KB content | move on without checking for a log | check for a `log.md` and follow its contract per Log discipline |