@inkeep/open-knowledge 0.71.0-beta.6 → 0.71.0-beta.8

package/dist/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md

@@ -105,7 +105,7 @@ Atomic pages for domain terms and core abstractions (one term each): definition,
 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).
-   - **`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.)
+   - **`audit`** — fix every reported finding. A clean result proves every checked link resolves only when `brokenLinkSuppression` is absent; when that marker is present, reserved-log findings were deliberately withheld and are not repair work. (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.
 

package/dist/assets/skills/packs/knowledge-base/SKILL.md

@@ -77,6 +77,8 @@ Log: `ingest` runs (new sources), `research` / `consolidate` runs (provisional o
 
 **Reference docs as markdown links, not bare paths** — `[path/to/doc](./path/to/doc.md)`, so the entry shows up in `links({ kind: "backlinks" })` for those docs. A bare path string does not register in the graph.
 
+Because this append-only `log.md` is a reserved log, its broken links may be withheld from `audit`. When a clean result carries `brokenLinkSuppression`, it is filtered rather than proof that every raw link resolves; do not rewrite log history to clear those links.
+
 Entry shape:
 
 ```markdown

package/dist/assets/skills/project/SKILL.md

@@ -79,7 +79,7 @@ KB docs are factual artifacts: every claim traceable, and **the source lives ins
 - **No evidence?** Search and ingest the result, OR mark `(TODO: needs source)`, OR don't write the claim. Do NOT fabricate — unsourced speculation rots into untraceable tribal lore.
 ## Linking — standard markdown links (MUST)
 
-Link every noun-phrase that names another document — `[text](./relative/path.md)` — and link liberally. **Every link must resolve to a doc that exists by the time you're done** (a same-pass forward-reference you create later in the pass is fine; for one that genuinely won't exist, leave the mention as plain prose + a tracked task). Never backtick a link (`` `[text](./foo.md)` `` is a bug) and never use HTML `<a>`. **Read `brokenLinks` on every `write`/`edit` response: `[]` means all links resolve; a populated list names each broken `href` + `reason` (`no-such-doc` / `no-such-file` / `unresolvable`) — fix them in a follow-up `edit`.** `audit` is the authoritative end-state link check (the editor's red-underline is slug-tolerant and lies, so trust the tool). External web sources are NOT inline body links (see Grounding). Full rule set + the `[[Page]]` legacy note: `references/linking.md`.
+Link every noun-phrase that names another document — `[text](./relative/path.md)` — and link liberally. **Every link must resolve to a doc that exists by the time you're done** (a same-pass forward-reference you create later in the pass is fine; for one that genuinely won't exist, leave the mention as plain prose + a tracked task). Never backtick a link (`` `[text](./foo.md)` `` is a bug) and never use HTML `<a>`. **After every `write`/`edit`, read `brokenLinks`: fix reported `href`s; `[]` means all links resolve unless `brokenLinkSuppression` withheld reserved-log findings; those are not yours to repair.** `audit` is authoritative; its same marker carries the same meaning. External web sources are NOT inline body links (see Grounding). Full rule set + the `[[Page]]` legacy note: `references/linking.md`.
 
 ## Folders, frontmatter, templates
 

package/dist/assets/skills/project/references/linking.md

@@ -9,8 +9,9 @@
 - **Every link must resolve to a doc that exists by the time you're done.** Within a single multi-doc authoring pass, linking a page you'll create later in the same pass is fine — `brokenLinks` reports it as `no-such-doc` until the target lands, an expected transient forward-reference rather than a wrong-path error. What's not acceptable is *leaving* a dead link behind: create the target in the same pass, or record it as a tracked task (`TaskCreate`, or your host's task tool — if the host has none, tell the user) and leave the mention as plain prose.
 - **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 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).
+- **`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 only when `brokenLinkSuppression` is absent; 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`.
+- **An empty `brokenLinks` alongside a `brokenLinkSuppression` does not mean every link resolves.** That field appears only when the project's reserved-log policy withheld findings, and it carries `{ reason: "reserved-log-policy", count: N }` and nothing else. No href comes back because none of them is repair work: the write landed in a lowercase-stemmed `log.md` or `log.mdx`, an append-only history whose entries deliberately reference pages that moved or were never written. **Never rewrite a reserved log's existing entries to clear a link.** Append new entries instead, and treat `links({ kind: "dead" })` on that file as a deliberate audit of raw state, never as a repair queue. The project can turn the policy off (**Settings ▸ This project ▸ Preferences ▸ Content rules**), in which case those findings come back through the normal channels.
+- **`audit` is the authoritative end-state link check** — run it once at the end of a multi-doc pass. Read `brokenLinkSuppression` on its result too: when present, the reserved-log policy withheld `count` findings, so a clean result is filtered rather than proof that every raw link resolves. Do not repair those log findings; use `links({ kind: "dead" })` only when deliberately inspecting raw state. 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 skill-bundle docs excluded from the Problems plane (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.