Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): re-point preview at end of multi-doc workflow; don't over-claim (#1842)

tim-inkeep2c6df2bc422b
diff --git a/.changeset/preview-repoint-multidoc-workflow.md b/.changeset/preview-repoint-multidoc-workflow.md
new file mode 100644
index 000000000..d7dc965a6
--- /dev/null
+++ b/.changeset/preview-repoint-multidoc-workflow.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+OK skill guidance now tells agents to re-point the preview at the end of a multi-doc workflow and to stop claiming a doc is on screen when they haven't navigated there. The preview attaches once per session; later writes don't move the pane, so after a long workflow it could sit on an earlier doc while the agent reported the final file as "open." The Preview section now says: when a turn touches several docs, finish by navigating the preview to the doc the user should land on (via `preview_eval` / `preview_url`, honoring `autoOpen`), and don't tell the user a doc is open unless you navigated there this turn.
diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.md
index 6347f4d94..2bbca58c6 100644
--- a/packages/server/assets/skills/project/SKILL.md
+++ b/packages/server/assets/skills/project/SKILL.md
@@ -93,6 +93,8 @@ The user watches your edits land in a live browser preview. Open it once at sess
Warnings fire at most once per session in the fresh-start case.
+**Re-point at the end of a multi-doc workflow; don't claim a doc is on screen unless you put it there.** The one-shot attach (signal 3) opens the preview *once* — later writes do NOT move the pane; it stays on the doc you last navigated to. When a turn touches several docs, finish by navigating the preview to the doc the user should land on, using your host's move mechanism (`preview_eval` setting `window.location.hash` from the response `previewUrl`, or `preview_url` → in-app browser; honor `autoOpen`). Until you have navigated there *this* turn, don't tell the user a doc is "open" / "on screen" — at most, say the preview may still be on the doc you opened earlier.
+
**`previewUrl: null` only means "no UI reachable" on the two attach-warning tools: `write` / `edit`.** Workflow tools return prose and don't carry `previewUrl`. `delete` / `move` emit `previousPreviewUrl` (different field, for closing stale tabs) and don't fire attach warnings. `preview_url` auto-starts the backend on demand (same `OK_MCP_AUTOSTART` gate as writes; a cold first call can take seconds) and reports `running: false` + `url: null` only when no UI could be reached — its hint names the right command.
If you see `"Hocuspocus server is not running"`, run `ok start` and retry.
diff --git a/packages/server/scripts/generate-instructions.test.ts b/packages/server/scripts/generate-instructions.test.ts
index a154d47b2..41881de4d 100644
--- a/packages/server/scripts/generate-instructions.test.ts
+++ b/packages/server/scripts/generate-instructions.test.ts
@@ -123,7 +123,7 @@ describe('generateInstructions — byte budget', () => {
test('stays within the structural ceiling (truncation / cache-cost guard)', () => {
const skill = readFileSync(SKILL_PATH, 'utf8');
const result = generateInstructions(skill);
- expect(result.byteLength).toBeLessThan(11840);
+ expect(result.byteLength).toBeLessThan(12544);
});
test('reports per-section byte lengths so maintainers can spot the heaviest', () => {
diff --git a/packages/server/src/mcp/instructions.test.ts b/packages/server/src/mcp/instructions.test.ts
index b89826ade..603523e36 100644
--- a/packages/server/src/mcp/instructions.test.ts
+++ b/packages/server/src/mcp/instructions.test.ts
@@ -83,5 +83,5 @@ test('buildInstructions exceeds the legacy 2 KB Claude Code cap (generator emits
const text = buildInstructions(defaultContent());
const bytes = Buffer.byteLength(text, 'utf8');
expect(bytes).toBeGreaterThan(2048);
- expect(bytes).toBeLessThan(11840);
+ expect(bytes).toBeLessThan(12544);
});
diff --git a/packages/server/src/mcp/instructions.ts b/packages/server/src/mcp/instructions.ts
index 432297375..939d3f7bf 100644
--- a/packages/server/src/mcp/instructions.ts
+++ b/packages/server/src/mcp/instructions.ts
@@ -54,6 +54,8 @@ The user watches your edits land in a live browser preview. Open it once at sess
Warnings fire at most once per session in the fresh-start case.
+**Re-point at the end of a multi-doc workflow; don't claim a doc is on screen unless you put it there.** The one-shot attach (signal 3) opens the preview *once* — later writes do NOT move the pane; it stays on the doc you last navigated to. When a turn touches several docs, finish by navigating the preview to the doc the user should land on, using your host's move mechanism (\`preview_eval\` setting \`window.location.hash\` from the response \`previewUrl\`, or \`preview_url\` → in-app browser; honor \`autoOpen\`). Until you have navigated there *this* turn, don't tell the user a doc is "open" / "on screen" — at most, say the preview may still be on the doc you opened earlier.
+
**\`previewUrl: null\` only means "no UI reachable" on the two attach-warning tools: \`write\` / \`edit\`.** Workflow tools return prose and don't carry \`previewUrl\`. \`delete\` / \`move\` emit \`previousPreviewUrl\` (different field, for closing stale tabs) and don't fire attach warnings. \`preview_url\` auto-starts the backend on demand (same \`OK_MCP_AUTOSTART\` gate as writes; a cold first call can take seconds) and reports \`running: false\` + \`url: null\` only when no UI could be reached — its hint names the right command.
If you see \`"Hocuspocus server is not running"\`, run \`ok start\` and retry.