Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdindex 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 sessWarnings 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.tsindex 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.tsindex 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 emitsconst 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.tsindex 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 sessWarnings 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.