Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): skill-reference follow-ups from #3855 review (PRD-8283) (#3860)
tim-inkeep3ab979a199b0
diff --git a/.changeset/skill-references-tool-surface.md b/.changeset/skill-references-tool-surface.mdnew file mode 100644index 000000000..6d05a83db--- /dev/null+++ b/.changeset/skill-references-tool-surface.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++The bundled agent skills now match the MCP tool surface. `links` is called with the parameter names the tool accepts (`document`, `sourceDocuments`), `audit` is named as the end-state check and described by what it actually reports (every lint violation plus every broken internal link, not just dead links), with `links({ kind: "dead" })` as the graph reader and a superset of `audit` on the source side, external images route through the ingest procedure instead of an ad-hoc fetch, and the OKF reserved-file frontmatter exemption is documented. The project skill refreshes on its own. A pack skill already seeded into a project is yours to edit, so it keeps its old text and seeding again will not refresh it; update that skill from source, or delete it and reseed, to pick up the corrected wording.diff --git a/packages/server/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md b/packages/server/assets/skills/packs/codebase-wiki/references/generate-and-refresh.mdindex 856c6828e..0a5c78f47 100644--- a/packages/server/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md+++ b/packages/server/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md@@ -102,10 +102,10 @@ Atomic pages for domain terms and core abstractions (one term each): definition,### Phase 7 — Link-graph activation + audit1. Confirm **OVERVIEW links every page** (it is the nav hub). Add any missing nav links. This is OVERVIEW's check — it's a *source* (high out-degree), verified by forward links here, not by the `hubs` view below.-2. Run `links({ kind: ["orphans", "hubs"] })`, then `audit` for dead links:+2. Run `links({ kind: ["orphans", "hubs"] })`, then `audit`:- **orphans** — pages nothing links to. Adopt each by linking it from OVERVIEW or a relevant section page (or, rarely, justify it as intentionally standalone).- **hubs** — ranks by *inbound* links. Confirm your **concept/module pages** show up here — that's the signal cross-linking actually happened. Don't expect `OVERVIEW`: a freshly authored nav page has almost no inbound links, so it won't appear (and that's correct — its coverage was checked in step 1).- - **dead** (`audit`) — fix or remove every dead link. (Source-file links don't appear in this graph — only `.md`/`.mdx` edges are tracked — but they ARE validated by `brokenLinks` on each write/edit, per the code-reference rule above.)+ - **`audit`** — returns clean (every lint violation + broken internal link) — fix every finding. (This covers links to source files too, not just `.md`/`.mdx`: it's the `orphans`/`hubs` graph above that tracks doc-to-doc edges only. `brokenLinks` on each write/edit is the same check per-write, per the code-reference rule above.)3. Append a `wiki/log.md` entry (see *Log discipline*).4. Tell the user the wiki is ready and surface the OVERVIEW preview URL.diff --git a/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md b/packages/server/assets/skills/packs/knowledge-base/research/SKILL.mdindex 3cb684253..749015820 100644--- a/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md+++ b/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md@@ -336,7 +336,7 @@ Run this checklist before marking complete:- File exists at the chosen path under the content directory- Frontmatter has `title`, `description`, `type: research-note`, `status: draft`, `date`, and an object-shaped `sources:` list- `exec("ls -A <dir>")` lists the new file with frontmatter enrichment-- `audit({ path: "<doc-path>.md" })` returns clean — zero dead links (fix or remove every one)+- `audit({ path: "<doc-path>.md" })` returns clean (every lint violation + broken internal link) — fix every finding- Every factual claim in Findings cites a source inline- Linked source files from Step 3 all exist (broken source links → ingest went wrong somewhere)- At least 1-2 neighbor docs now link to this research (per Step 6's "After writing, update ..." rule)diff --git a/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.mdindex 27379357a..3640cd495 100644--- a/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md@@ -184,7 +184,7 @@ Run before you tell the user it's ready:- Every referenced decision, spec, or guide is a plain markdown relative link (`[text](./decisions/0004-x.md)`), never backticked, never an HTML anchor.- Add backlinks from 1–2 closely related docs so the proposal is discoverable — the accepted decision it revisits, a related spec, the relevant guide. `links({ kind: "backlinks", ... })` to see what already points where.-- `audit({ path: "proposals/0007-async-export-pipeline.md" })` returns clean — fix or remove every dead link.+- `audit({ path: "proposals/0007-async-export-pipeline.md" })` returns clean (every lint violation + broken internal link) — fix every finding.- Frontmatter complete: `type: proposal`, a one-line `description`, `status: draft`, `authors`, `created`, `tags: [proposal]`.- All five H2 sections present and non-empty: `## Motivation`, `## Design`, `## Drawbacks`, `## Alternatives`, `## Unresolved questions`. An empty Drawbacks or a strawman Alternatives fails this check even though the section technically exists.- `status` is still `draft`. You do not advance it — see Non-goals.diff --git a/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.mdindex 4ad6a2766..b3dc6943d 100644--- a/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md@@ -160,7 +160,7 @@ Then add a line near the top of the old record's Context (or a short `> Supersed## Step 8 — Link and validate- **Backlinks in:** ensure the parent proposal links forward to this decision, and any spec that *implements* this decision links back to it. `links({ kind: "backlinks", document: "decisions/0012-adopt-event-sourcing-for-orders" })` to see who points here; add the missing ones so the record is discoverable.-- **Dead links out:** `audit({ path: "decisions/0012-adopt-event-sourcing-for-orders.md" })` returns clean — zero dead links. Fix or remove every one; a broken link to a superseded record defeats the whole chain.+- **Validate:** `audit({ path: "decisions/0012-adopt-event-sourcing-for-orders.md" })` returns clean (every lint violation + broken internal link) — fix every finding; a broken link to a superseded record defeats the whole chain.- **Frontmatter complete:** `type`, `description`, `status`, `date`, `deciders`, `supersedes`, `tags` all present and correct.- **Status reflects reality:** if the deciders have accepted, flip `status: proposed` → `accepted`. If they haven't, leave it `proposed` and tell the user it's awaiting sign-off. Do not mark a decision `accepted` on the user's behalf.- **Body shape:** exactly `## Context`, `## Decision`, `## Consequences`, in order. No extra top-level sections — depth that doesn't fit these three belongs in a linked spec.diff --git a/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.mdindex b1d735716..8af6d570b 100644--- a/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md@@ -175,7 +175,7 @@ Pre-fill the stub with the **symptom** (how you'd recognize this again — "chec- Add a `## Related` section linking **every prior postmortem that shares a subsystem** (from Step 2), plus the `decisions/` and `specs/` implicated — the decision that set the config policy, the spec for the component that failed. `[2024-01-11 payments pool](./postmortems/2024-01-11-payments-pool.md)`, `[connection-pool sizing decision](./decisions/2023-11-04-pool-sizing.md)`.- Link the runbook stubs you created in Step 9 from their action items (done above) and from `## Related`.- Update the hub of any folder you touched if it has one (an `INDEX.md` in `postmortems/`) so the new incident shows up in the index — the preview becomes a live progress bar.-- Validate: `audit({ path: "postmortems/YYYY-MM-DD-name.md" })` returns clean — fix or drop every dead link. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.+- Validate: `audit({ path: "postmortems/YYYY-MM-DD-name.md" })` returns clean (every lint violation + broken internal link) — fix every finding. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.---diff --git a/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.mdindex 761441f3b..3d89e8f10 100644--- a/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md@@ -262,7 +262,7 @@ Specs that don't link back are islands. Wire the spec into the graph and prove i- **Backlink the parent proposal** inline in the spec body: `derived from [Payment retries proposal](./proposals/0004-payment-retries.md)`. Plain markdown relative link — never backticked, never an HTML anchor.- **Link every decision the spec depends on** — if the design rests on a frozen record in `decisions/`, link it where it's relied upon.- Update the parent proposal (and any hub) to link forward to this spec, so the spec is discoverable via backlinks. `links({ kind: "backlinks", ... })` to confirm the reverse edge registered.-- `audit({ path: "specs/004-payment-retries/spec.md" })` — returns clean, zero dead links. Fix or remove every one.+- `audit({ path: "specs/004-payment-retries/spec.md" })` returns clean (every lint violation + broken internal link) — fix every finding.- Frontmatter complete: `type`, `description`, `status`, `owner`, `parent_proposal`, `created`, `tags` all present.---diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.mdindex 7f43655d0..d54c723b4 100644--- a/packages/server/assets/skills/project/SKILL.md+++ b/packages/server/assets/skills/project/SKILL.md@@ -25,7 +25,7 @@ OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. Th## Tool index — 21 tools (router; the MCP tool descriptions carry each tool's full contract)-- **Reads** — `exec` (primary; read-only `cat`/`ls`/`grep`/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), `search` (ranked BM25 + recency), `history` (doc versions), `links` (`kind: backlinks|forward|dead|orphans|hubs|suggest`, or an array for one call), `skills` (search + read: `query` → skills.sh; omit `name` to LIST managed (Project + Global); `name` READs one — by `name`+`scope`, never path), `config` (resolved config), `palette` (authoring forms + `html preview` starters + theme tokens; `palette({ components })` for JSX schemas), `preview_url` (browser preview URL on demand), `share_link` (GitHub-substrate share URL; read-only, errors without a GitHub remote), `lint` (markdown-lint violations: `document` for one doc, omit for the project; `fix: true` with `document` auto-fixes fixable rules in place — attributed, live in the preview; the rest need `edit`/`write`), `audit` (every lint violation + broken internal link in one read-only report, by source file with lines; `path` scopes; for link VALIDATION use this, not `links`).+- **Reads** — `exec` (primary; read-only `cat`/`ls`/`grep`/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), `search` (ranked BM25 + recency), `history` (doc versions), `links` (`kind: backlinks|forward|dead|orphans|hubs|suggest`, or an array for one call), `skills` (search + read: `query` → skills.sh; omit `name` to LIST managed (Project + Global); `name` READs one — by `name`+`scope`, never path), `config` (resolved config), `palette` (authoring forms + `html preview` starters + theme tokens; `palette({ components })` for JSX schemas), `preview_url` (browser preview URL on demand), `share_link` (GitHub-substrate share URL; read-only, errors without a GitHub remote), `lint` (markdown-lint violations: `document` for one doc, omit for the project; `fix: true` with `document` auto-fixes fixable rules in place — attributed, live in the preview; the rest need `edit`/`write`), `audit` (every lint violation + broken internal link in one read-only report, by source file with lines; `path` scopes; for link VALIDATION use this, not `links`; caveats in `references/linking.md`).- **Writes** — four native CRUD verbs, polymorphic over `document` / `folder` / `template` / `skill` / `asset` (pass EXACTLY ONE target, nested under its address key): `write` (create/overwrite; `write({ skill: {…} })` authors a skill as a REAL folder at the project's default skill home — live immediately for that folder's agent), `edit` (body find/replace/frontmatter merge-patch; no asset), `delete` (remove), `move` (move/rename, rewrites referrers; a skill also takes `scope`/`toScope` for Project↔Global — history resets, re-`install`). Output mirrors the input key; the preview envelope (`previewUrl`, `warning`) stays top-level. Plus `install` (WHERE a `skill` lives: `add`/`remove` locations additively — editor ids, `agents`, or custom roots; `mode` + `convert` re-form ONLY the locations named; `source` moves the real folder. The source folder IS the skill — no "uninstall everywhere"; a skill dies only via `delete`), `import` (acquire a skill-dir into `add`'s locations; scripts never run), `checkpoint` (named version), and `restore_version` (roll back). A folder's frontmatter is open-shape and self-only (does NOT cascade); templates are what new docs start with.- **Conflicts** — `conflicts` (`kind: list|content`), `resolve_conflict` (write a resolution + commit; destructive). See `references/conflict-resolution.md`.diff --git a/packages/server/assets/skills/project/references/linking.md b/packages/server/assets/skills/project/references/linking.mdindex f4d71dc3e..fde832dd1 100644--- a/packages/server/assets/skills/project/references/linking.md+++ b/packages/server/assets/skills/project/references/linking.md@@ -10,7 +10,7 @@- **Never wrap a link in backticks.** `` `[text](./foo.md)` `` is a bug — the backticks make it render as literal code rather than a link.- **Never use HTML anchors** (`<a href="...">`). Markdown link syntax only.- **`brokenLinks` on the write/edit response is your primary check — read it before walking away.** Every `write`/`edit` returns `brokenLinks` in the SAME payload: `[]` means every outbound link resolves; a populated list names each broken `href` with its `resolvedTo` + `reason` (`no-such-doc` = resolved to a doc that doesn't exist; `no-such-file` = resolved to a linked asset / source file that isn't on disk at that path; `unresolvable` = the path escapes the content root, usually one `../` too many). This validates **every** local link, not just doc links: a wrong-depth `[src](../../foo.py)` to a source file is caught too. It is report-only — the write landed regardless; fix or remove every one in a follow-up `edit`.-- **`audit` is the authoritative end-state link check** — run it once at the end of a multi-doc pass. Caveat: `audit` reports links only while the project's `validation.links` setting is not `off` (at `off` it returns clean with no warning), so if the project has silenced link validation, fall back to `links({ kind: "dead" })` — the unconditional read of the same dead-link data (optionally scoped: `links({ kind: "dead", sourceDocuments: ["your/doc"] })`). Otherwise `links` is the graph-navigation reader, supplemental to `audit`, not a substitute. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).+- **`audit` is the authoritative end-state link check** — run it once at the end of a multi-doc pass. Caveat: `audit` reports links only while the project's `validation.links` setting is not `off` (at `off` it returns clean with no warning), so if the project has silenced link validation, fall back to `links({ kind: "dead" })` — the unconditional read of the dead-link graph, which also lists sources `audit` excludes, such as skill-bundle docs (optionally scoped: `links({ kind: "dead", sourceDocuments: ["your/doc"] })`). Otherwise `links` is the graph-navigation reader, supplemental to `audit`, not a substitute. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).- **The tool and the editor agree.** Both resolve a bare name the same way — exact, then slug, then folder index, then basename — so a link that opens when you click it is never reported dead, and a link reported dead is genuinely unresolvable. A target that names an asset, or names nothing at all, stays silent rather than being reported as a broken doc link.**Note on wiki-link syntax (`[[Page]]`):** the parser still handles it for legacy content, but it's NO LONGER the recommended default. Write new content with standard markdown links per above. Seed-pack templates (`ok seed --pack <name>`) may still emit `[[Page]]` placeholders inside template body text — those are legacy. When you instantiate a seed-pack template, replace the legacy placeholders with standard markdown links during the `{shape}`-fill pass.diff --git a/packages/server/assets/skills/project/references/onboard-existing-repo.md b/packages/server/assets/skills/project/references/onboard-existing-repo.mdindex 4777290d0..01c94759b 100644--- a/packages/server/assets/skills/project/references/onboard-existing-repo.md+++ b/packages/server/assets/skills/project/references/onboard-existing-repo.md@@ -179,7 +179,7 @@ Six sub-passes, each with its own STOP gate.### 5c. Dead-link sweep (STOP gate 5c)-1. Run `audit` (the authoritative end-state link check; it covers the whole corpus). `links({ kind: "dead" })` is the graph-navigation view of the same data, useful for browsing but not the validation step.+1. Run `audit` (the authoritative end-state link check; it covers the whole corpus — caveats in `references/linking.md`). `links({ kind: "dead" })` is the graph reader, not the validation step; it is a superset on the source side (it also lists dead links whose source is a skill-bundle doc, which `audit` skips).2. For each dead link, propose: a fix candidate (via `search` for the correct target), or deletion (remove the link, or the prose around it). Leaving it as an "intentional redlink" is not an option — every dead link is fixed or removed.3. Confirm per dead-link. Apply confirmed fixes via `edit`.diff --git a/packages/server/src/skill-links-params-contract.test.ts b/packages/server/src/skill-links-params-contract.test.tsindex 86327f3ad..93744e602 100644--- a/packages/server/src/skill-links-params-contract.test.ts+++ b/packages/server/src/skill-links-params-contract.test.ts@@ -1,14 +1,22 @@/**- * Shipped skill assets must call `links` with parameter names the MCP tool+ * Shipped skill assets must call `links` / `audit` with parameter names the MCP tool* actually declares (`docName` / `sourceDocNames` shipped for months- * and errored or silently audited the whole corpus). The key list mirrors the- * `inputSchema` in `src/mcp/tools/links.ts` — update both together.+ * and errored or silently audited the whole corpus). The key lists mirror the+ * `inputSchema`s in `src/mcp/tools/links.ts` and `src/mcp/tools/audit.ts` — update+ * all three together.+ *+ * Also guards the prose: no shipped skill may frame `audit` as a dead-link-only+ * check, since it merges lint + links. Wording for the project bundle specifically+ * is pinned in `skill-linking-contract.test.ts` — keep the two in their own lanes.*/import { readdirSync, readFileSync, statSync } from 'node:fs';import { join } from 'node:path';import { describe, expect, test } from 'vitest';-const LINKS_INPUT_KEYS = new Set(['kind', 'document', 'sourceDocuments', 'mode', 'limit', 'cwd']);+const TOOL_INPUT_KEYS = {+ links: new Set(['kind', 'document', 'sourceDocuments', 'mode', 'limit', 'cwd']),+ audit: new Set(['path', 'cwd']),+};const SKILLS_DIR = join(import.meta.dirname, '../assets/skills');function walk(dir: string): string[] {@@ -18,16 +26,42 @@ function walk(dir: string): string[] {});}-describe('shipped skills call links() with declared parameter names', () => {+const CALL_RE = /\b(links|audit)\(\{([^}]*)\}\)/g;++describe('shipped skills call links()/audit() with declared parameter names', () => {+ const callSites = { links: 0, audit: 0 };for (const file of walk(SKILLS_DIR)) {const text = readFileSync(file, 'utf-8');- const calls = [...text.matchAll(/links\(\{([^}]*)\}\)/g)];+ const calls = [...text.matchAll(CALL_RE)];if (calls.length === 0) continue;+ for (const [, tool] of calls) callSites[tool as keyof typeof callSites]++;test(file.slice(SKILLS_DIR.length + 1), () => {- for (const [, body] of calls) {- const keys = [...body.matchAll(/(?:^|,)\s*([A-Za-z_]+)\s*:/g)].map((m) => m[1]);- for (const key of keys) expect(LINKS_INPUT_KEYS, `links({ ${key}: … })`).toContain(key);+ expect.hasAssertions();+ for (const [, tool, body] of calls) {+ // Matches `key:` and ES2015 shorthand `{ kind, document }`.+ const keys = [...body.matchAll(/(?:^|,)\s*([A-Za-z_]+)\s*(?=[:,]|$)/g)].map((m) => m[1]);+ for (const key of keys) {+ expect(+ TOOL_INPUT_KEYS[tool as keyof typeof TOOL_INPUT_KEYS],+ `${tool}({ ${key}: … })`,+ ).toContain(key);+ }}});}+ test('scan is not vacuous', () => {+ expect(callSites.links).toBeGreaterThan(10);+ expect(callSites.audit).toBeGreaterThan(3);+ });+});++describe('shipped skills describe audit by what it reports', () => {+ test('no shipped skill frames `audit` as a dead-link-only check', () => {+ for (const file of walk(SKILLS_DIR)) {+ const text = readFileSync(file, 'utf-8');+ for (const stale of ['zero dead links', 'fix or remove every dead link']) {+ expect(text, `${file.slice(SKILLS_DIR.length + 1)}: ${stale}`).not.toContain(stale);+ }+ }+ });});