Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-8301 Suppress reserved-log broken-link advisories (#4041)

serafin-garciab95ac3a64a3a
diff --git a/.changeset/log-md-broken-link-policy.md b/.changeset/log-md-broken-link-policy.md
new file mode 100644
index 000000000..e39827b87
--- /dev/null
+++ b/.changeset/log-md-broken-link-policy.md
@@ -0,0 +1,17 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Broken links inside a `log.md` no longer show up as work to do.
+
+A project log is an append-only history. Its entries name pages that have since moved, and pages nobody has written yet, so unresolved links are what a log is supposed to accumulate. Until now every one of them was reported as a broken link to repair: in the Problems panel, as a sidebar tint, as an editor squiggle, in `ok audit`, and in the advisory an agent gets back from every write or edit. That last one is what made this more than noise, because agents are told to read that advisory and fix what it names, and the only way to fix a stale entry in a log is to edit history that was meant to be permanent.
+
+A new project setting, **Ignore broken links in log.md** under **Settings ▸ This project ▸ Preferences ▸ Content rules**, leaves those links out of all of it. It is on by default and shared with the project through `config.yml` as `validation.suppressLogLinkAdvisories`. Turn it off and every finding comes straight back, everywhere, with no restart.
+
+If you gate CI on `ok audit --errors-only` with `validation.links: error`, reserved-log findings no longer contribute to `errorCount` while this default-on setting is enabled. Set `validation.suppressLogLinkAdvisories: false` to keep the previous gate.
+
+The match is deliberately narrow: the stem must be exactly lowercase `log`, with a supported Markdown extension, at any depth. The extension's case is not what decides, so `log.MD` is a reserved log too; `LOG.md` and `catalog.md` are ordinary documents and keep their findings. What decides is the file a link is written in, not the file it points at, so a broken link to a log from anywhere else still reports normally.
+
+Nothing is hidden from the views you use to inspect links on purpose. The Links panel, the editor's unresolved-link styling, `links({ kind: "dead" })`, and `GET /api/dead-links` all show a log's unresolved links in both states.
+
+For agents, filtered results are now explicitly conditional rather than quietly redefined. When the policy withholds findings, audit, write, and edit responses carry `brokenLinkSuppression`, naming the reason `reserved-log-policy` and how many final findings were withheld. On write and edit it sits beside `brokenLinks`. When `brokenLinkSuppression` is absent, `brokenLinks: []` still means what it always did: every outbound link resolves. When the marker is present, treat the empty list as filtered, not confirmed. No href or path comes back, because none of them is repair work, and the bundled project skill and MCP tool descriptions now say exactly that.
diff --git a/docs/content/advanced/content-rules/overview.mdx b/docs/content/advanced/content-rules/overview.mdx
index a8b69e18c..c05d61cfb 100644
--- a/docs/content/advanced/content-rules/overview.mdx
+++ b/docs/content/advanced/content-rules/overview.mdx
@@ -17,12 +17,14 @@ This page covers what's the same whatever linter runs; each linter's page covers
- **The Problems panel** — a tab in the document panel on the right, with a live count badge and two scopes:
- **This doc** — live diagnostics for the open document, in both WYSIWYG and source mode. Click a problem to jump to it: source mode lands on the exact line and column, WYSIWYG scrolls to the block it falls in.
- **Project** — an on-demand audit of every in-scope document. It runs when you first open the scope and on the refresh button — never in the background. Results group per file with error/warning totals; configuration problems (a malformed config file, a broken `extends`) surface at the top. Clicking a problem opens the offending doc at that position.
-- **The file sidebar** — a file with problems has its row tinted (red for errors, amber for warnings) and carries a count badge. The badge is a control: click it, or tab to it and press Enter or Space, and the file opens with the Problems panel showing that file's problems in **This doc** scope. Keyboard activation moves focus into the panel; clicking preserves pointer focus. Set `validation.fileTreeIndicators: false` in the project's `config.yml` to turn the tint and the badge off (see the [configuration reference](/docs/reference/configuration)).
+- **The file sidebar** — a file with problems has its row tinted (red for errors, amber for warnings) and carries a count badge. The badge is a control: click it, or tab to it and press Enter or Space, and the file opens with the Problems panel showing that file's problems in **This doc** scope. Keyboard activation moves focus into the panel; clicking preserves pointer focus. Set `validation.fileTreeIndicators: false` in the project's `config.yml` to turn the tint and the badge off (see the [configuration reference](/docs/reference/configuration)). A missing tint has one other cause: a `log.md` whose broken links the reserved-log policy below leaves out.
Skill documents are excluded from link checking: files in a skills folder (`.claude/skills`, `.agents/skills`, `.github/skills`, and the like) and the skill documents you open from the Skills panel. A skill's links routinely name files it creates only when it runs, so they report as broken by construction. What goes quiet is the Problems panel in both scopes, and with it the squiggles and gutter marks the panel drives. What stays is the link styling the editor resolves on its own as you type, so a wiki link to a file the skill has not created yet still renders as unresolved, and the Links panel still lists it under Missing. In short: the skill's Problems tab reads clean while the link itself may still look broken in the text. `links({ kind: "dead" })` and `GET /api/dead-links` list them too.
The exclusion is scoped to the skills folder itself, not to the dot-directory containing it, so ordinary documents that happen to live under a dot directory (`.github/CI_RUNBOOK.md`, a `.changeset` entry) keep their link findings. So do folder templates under `.ok/templates`, which you author like any document. A skills folder you added yourself at a visible path, such as `team/skills`, is ordinary content and is still checked. Links from your other documents to a skill still validate normally.
+A reserved `log.md` or `log.mdx` is left out the same way, at any depth, with one difference: this one is a switch you own. It is **Ignore broken links in log.md** under **Settings ▸ This project ▸ Preferences ▸ Content rules**, on by default, and shared with the project as `validation.suppressLogLinkAdvisories`. What goes quiet is the Problems panel in both scopes, the sidebar tint and badge, the editor's lint diagnostics, `ok audit`, and the advisory an agent gets back from a write or edit. What stays is the raw link state: the Links panel, the editor's unresolved-link styling, `links({ kind: "dead" })`, and `GET /api/dead-links` all still list those links. In both scopes the Problems panel carries a policy note with the number of findings left out, so an empty queue is not read as a clean log. The stem has to be lowercase, so `LOG.md` and `catalog.md` keep their findings, but the extension's case is not what decides, so `log.MD` is a reserved log too, and it is the file the link is written in that counts, not the file it points at. The [`ok audit` section](#what-it-returns) covers what the CLI and MCP audits disclose.
+
In both scopes, each row tags the validator that produced it in uppercase — for example `MARKDOWNLINT`, `FRONTMATTER`, or `LINKS` — next to the rule code, and a finding that repeats collapses into one row with an instance count you can expand to reach the individual lines.
The panel is also available in [single-file sessions](/docs/features/editor#open-a-single-file) (`ok <file>`).
@@ -168,7 +170,9 @@ Unlike `ok lint`, `ok audit` needs the project's server running (`ok start` or O
The audit's top-level `ran` array reports the selected source families: enabled document linters plus `links` unless link validation is `off`. OKF's document and project-tree checks share the public `okf` family, so `ran` reports selection, not the number of internal validators or a pass verdict.
-Broken links are warnings by default. The project's `validation.links` setting — **Settings ▸ This project ▸ Content rules** — decides both whether they appear and at what severity: `warning` (the default), `error` to gate CI on them with `--errors-only`, or `off` to drop them from the plane entirely. Content-rule findings keep their own severities, so `--errors-only` covers both planes at once. Skill documents are the one exception: their link findings are always excluded, whatever this setting says, because a skill's links name files it creates only at runtime.
+Broken links are warnings by default. The project's `validation.links` setting — **Settings ▸ This project ▸ Preferences ▸ Content rules** — decides both whether they appear and at what severity: `warning` (the default), `error` to gate CI on them with `--errors-only`, or `off` to drop them from the plane entirely. Content-rule findings keep their own severities, so `--errors-only` covers both planes at once. Skill documents are the one exception: their link findings are always excluded, whatever this setting says, because a skill's links name files it creates only at runtime.
+
+A reserved log is the other exclusion, and unlike skills it is a switch you own. **Ignore broken links in log.md** (`validation.suppressLogLinkAdvisories` in the project's `.ok/config.yml` — see the [configuration reference](/docs/reference/configuration)), next to the severity control and on by default, is described under [Where problems show up](#where-problems-show-up), along with the matching rules. `ok audit` and MCP `audit` both disclose the withheld count and warn that the result is filtered, each in the wording its audience needs. The terminal names both remedies, `validation.suppressLogLinkAdvisories: false` in `.ok/config.yml` and the **Settings ▸ This project ▸ Preferences ▸ Content rules** toggle. An agent is told the setting is not its to change, and to point you at that same Settings path if you ask to see the withheld findings. A log is an append-only history: its entries reference the past and pages nobody has written yet, so those links are expected rather than repair work, and an agent told to fix broken links would otherwise rewrite the history to clear them. Turn the switch off and every finding comes straight back, with no restart.
## AI agents
@@ -207,7 +211,7 @@ When the fix landed but the post-write re-lint could not report, the response ca
### The `audit` tool
-The agent-side `ok audit` — content-rule problems and broken links in one read-only call, grouped by file, same 10 × 10 + 10-warning cap with `omittedWarningCount` when warnings are dropped, no fix shape. Its text and structured results both report `ran`. If a selected validator degrades, its family remains in `ran` and the `warnings` channel explains why; a partial degradation may still have contributed findings.
+The agent-side `ok audit` — content-rule problems and broken links in one read-only call, grouped by file, same 10 × 10 + 10-warning cap with `omittedWarningCount` when warnings are dropped, no fix shape. Its text and structured results both report `ran`. If the reserved-log policy withholds one or more link findings, `brokenLinkSuppression: { reason: "reserved-log-policy", count: N }` makes that filtered result explicit without exposing paths or hrefs; the text result says the same. If a selected validator degrades, its family remains in `ran` and the `warnings` channel explains why; a partial degradation may still have contributed findings.
### Write responses
@@ -232,9 +236,20 @@ Every write response carries validation findings for the document it touched, on
}
```
-**`warnings`** carries up to 10 findings across the whole validation plane — lint violations and broken links alike, honoring the project's `validation.links` setting. Positions are 1-based (`line`/`column`), ready to echo back to a human, and a `links` finding adds `linkTarget`. The field is present only when the write produced findings.
+**`warnings`** carries up to 10 findings across the whole validation plane — lint violations and broken links alike, honoring the project's `validation.links` setting and, for a reserved log, the **Ignore broken links in log.md** switch. Positions are 1-based (`line`/`column`), ready to echo back to a human, and a `links` finding adds `linkTarget`. The field is present only when the write produced findings.
+
+**`brokenLinks`** is the dedicated link channel, and unlike `warnings` it is **always present**. An empty array is the positive "every outbound link resolves" confirmation, which saves a separate `links({ kind: "dead" })` round-trip, as long as no `brokenLinkSuppression` sits beside it. Each entry names the href exactly as authored, so an agent can grep for it. `reason` is `no-such-doc` (resolved to a docName that doesn't exist), `no-such-file` (a linked asset or source file missing from disk), or `unresolvable` (an empty href, or a relative path escaping the content root); `resolvedTo` is `null` for `unresolvable`.
+
+**`brokenLinkSuppression`** is present only when the project's reserved-log policy kept findings out of `brokenLinks`, which is what makes an empty array conditional rather than a clean bill of health:
+
+```json
+"document": {
+ "brokenLinks": [],
+ "brokenLinkSuppression": { "reason": "reserved-log-policy", "count": 2 }
+}
+```
-**`brokenLinks`** is the dedicated link channel, and unlike `warnings` it is **always present** — an empty array is the positive "every outbound link resolves" confirmation, which saves a separate `links({ kind: "dead" })` round-trip. Each entry names the href exactly as authored, so an agent can grep for it. `reason` is `no-such-doc` (resolved to a docName that doesn't exist), `no-such-file` (a linked asset or source file missing from disk), or `unresolvable` (an empty href, or a relative path escaping the content root); `resolvedTo` is `null` for `unresolvable`.
+`reason` names the policy and `count` is how many advisory entries it withheld. No href or path comes back, because none of them is repair work: the write landed in a reserved log, whose entries are meant to keep pointing at what has been moved or has not been written yet. Read `links({ kind: "dead" })` when you want to audit that raw state deliberately, and do not rewrite a log's history to clear it.
## See also
diff --git a/docs/content/reference/agentic-search.mdx b/docs/content/reference/agentic-search.mdx
index 60ea67bf1..83c3bb751 100644
--- a/docs/content/reference/agentic-search.mdx
+++ b/docs/content/reference/agentic-search.mdx
@@ -240,7 +240,7 @@ set("ok");
</script>
```
-`brokenLinks` comes back on every write and edit (empty when they all resolve), so the agent never needs a follow-up dead-link check. A brand-new doc nothing points to comes back flagged as an orphan with a hub to link it from. Every write and edit is versioned, attributed, and the preview updates as it lands. Append to a file by hand and the edit still lands: the file watcher folds it into the live doc and versions it, but anonymously, as `file-system`, and nothing talks back. [Skills](../features/skills/index.mdx) teach the conventions, and the write path enforces the connective tissue.
+`brokenLinks` comes back on every write and edit (empty when they all resolve, unless a `brokenLinkSuppression` beside it reports that the project's reserved-log policy withheld some), so the agent never needs a follow-up dead-link check. A brand-new doc nothing points to comes back flagged as an orphan with a hub to link it from. Every write and edit is versioned, attributed, and the preview updates as it lands. Append to a file by hand and the edit still lands: the file watcher folds it into the live doc and versions it, but anonymously, as `file-system`, and nothing talks back. [Skills](../features/skills/index.mdx) teach the conventions, and the write path enforces the connective tissue.
## The index is authored, not extracted
diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx
index af5c3052d..7482a9b4e 100644
--- a/docs/content/reference/configuration.mdx
+++ b/docs/content/reference/configuration.mdx
@@ -37,6 +37,7 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi
| `contentRules.frontmatter.enabled` | boolean | `false` | project | Enable the [Frontmatter schemas](/docs/advanced/content-rules/frontmatter) content-rules plugin for this project (shared via git). Off by default — turn it on in **Settings → This project → Plugins**. |
| `contentRules.frontmatter.schemas` | array | `[]` | project | Frontmatter schema mappings: each entry scopes one JSON Schema file to a set of docs — `file` (project-root-relative path), optional `appliesTo` (glob or list; leading `!` excludes; absent means every doc), optional `enabled: false` to park a mapping. Schema content lives in the mapped files, not here. See [Frontmatter schemas](/docs/advanced/content-rules/frontmatter). |
| `validation.links` | `"off" \| "warning" \| "error"` | `"warning"` | project | How broken internal links are reported on the validation plane: `off` hides them, `warning` (default) or `error` sets their severity. Shared via git, like `contentRules`. |
+| `validation.suppressLogLinkAdvisories` | boolean | `true` | project | Whether broken internal links in a reserved log are left out of the Problems panel, file sidebar tints and badges, editor diagnostics, `ok audit`, and the advisories a write or edit response hands an agent. On by default, because a log is an append-only history whose entries deliberately reference the past and pages not yet written, and an agent told to repair broken links would otherwise edit that history. It matches the name `log.md` or `log.mdx` at any depth. The stem has to be lowercase, so `LOG.md` and `catalog.md` keep their findings, but the extension's case is not what decides, so `log.MD` is a reserved log too. It matches on the file the link is written in, not the file it points at. Raw link state is untouched either way: the Links panel, the editor's unresolved-link styling, `links({ kind: "dead" })`, and `GET /api/dead-links` still show those links. Toggle it as **Ignore broken links in log.md** under **Settings → This project → Preferences → Content rules**. |
| `validation.fileTreeIndicators` | boolean | `true` | project | Whether the file sidebar tints and badges files that have validation problems. The badge is also the row's entry point into the Problems panel, so turning this off removes both the indicator and that shortcut (see [Where problems show up](/docs/advanced/content-rules/overview#where-problems-show-up)). |
| `appearance.theme` | `"light" \| "dark" \| "system"` | (unset) | user | Editor light/dark theme. |
| `appearance.language` | `"system" \| "en" \| "zh-Hans" \| "zh-Hant" \| "hi" \| "es" \| "ar" \| "fr" \| "bn" \| "pt-BR" \| "id" \| "ur" \| "ko"` | (unset) | user | Interface language. `system` (the effective value when unset) follows your operating system or browser, and keeps following it. A personal preference, not project-shared — and it applies to the app's own chrome only: your documents, titles, file and folder names, frontmatter values and tags stay in the language you wrote them in. **Settings → Preferences → Language** offers ten of them (English, 简体中文, 繁體中文, हिन्दी, Español, Français, বাংলা, Português do Brasil, Indonesia, 한국어). Every catalog is complete, but only `es` has been through a Spanish reader; the rest, `zh-Hans` included, are machine-translated and nobody who reads them has checked the wording. Treat it as provisional and [tell us what is wrong](/docs/contribute/translations). `ar` and `ur` are complete translations too, but they stay out of the picker until the interface lays out right to left; set either here by hand to run the app in it, and note the app will not select them from your OS language alone. `OK_LANG=<tag>` overrides the desktop app's native menus for a single run; the rest of the interface follows this field. |
diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx
index 30ee92ea1..991d19ad1 100644
--- a/docs/content/reference/mcp.mdx
+++ b/docs/content/reference/mcp.mdx
@@ -18,9 +18,9 @@ To point an MCP client at this server, locally or over a tunnel from another mac
| --- | --- |
| `exec` | Read-only shell (`cat`, `ls`, `grep`, `find`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`); reads return frontmatter, backlinks, recent history, and any unresolved [comments](/docs/features/comments) left on the doc. When the [frontmatter schemas](/docs/advanced/content-rules/frontmatter) plugin is on, doc and folder entries also carry `schemas: …` naming the JSON Schema files that govern them — the contract to read before writing. Fs-direct; works without the server. |
| `search` | Ranked workspace search (title boost + body BM25 + recency; same engine the cmd-K palette uses). `intent: "omnibar"` narrows to fast title/path matching (`full_text`, the default, includes the body); `scopes` filters hit kinds; `limit` caps rows (default 20, max 100). When [semantic search](/docs/reference/configuration#semantic-search) is enabled, an embeddings signal is additionally fused into `full_text` ranking (opt-in, content egress) — pass `semantic: false` to force pure-lexical. Right after boot, an empty result set with `ready: false` means the index is still building — retry after a couple of seconds rather than treating it as no matches. |
-| `links` | Wiki-link graph. `kind` selects: `backlinks`, `forward`, `dead`, `orphans`, `hubs`, or `suggest`. Accepts an array (e.g. `["dead", "orphans", "hubs"]`) to fetch several views in one call; each view nests under its own key in the response. `dead` is the raw graph view: unlike `audit`, it still lists unresolved links whose source is a skill document |
+| `links` | Wiki-link graph. `kind` selects: `backlinks`, `forward`, `dead`, `orphans`, `hubs`, or `suggest`. Accepts an array (e.g. `["dead", "orphans", "hubs"]`) to fetch several views in one call; each view nests under its own key in the response. `dead` is the raw graph view: unlike `audit`, it still lists unresolved links whose source is a skill document (always) or a lowercase-stemmed `log.md`/`log.mdx` (while the project's default-on `validation.suppressLogLinkAdvisories` is on, with `audit` reporting `brokenLinkSuppression` when it withheld them) — read those deliberately, not as a repair queue |
| `lint` | Report content-rule problems (markdownlint style rules, frontmatter schema validation, document-level OKF checks) for one `document` or a whole-project audit (`path` scopes it); each finding carries `source`/`code`/`message`/`range`/`severity`, audit capped at 10 files × 10 diagnostics and project-wide at 10 warnings with accurate totals; configuration or runtime degradation problems ride a separate `warnings` channel, with `omittedWarningCount` when warnings are dropped. Successful responses include `ran`, the enabled document-lint source families selected for that call (`markdownlint`, `frontmatter`, and/or document-level `okf`). A family absent from `ran` was not checked, and `[]` means no checks were selected at all. Pass `fix: true` with `document` to auto-fix fixable rules in place — the fix lands through the collaborative document (attributed, live preview), not a shell edit; the rest need `edit`/`write`. A fix that landed but could not be re-verified sets `diagnosticsArePreFix` (branch on it) and explains itself in `reLintFailure`, whose `reason` is a closed discriminant and whose `message` is the prose. Example output: [content rules overview](/docs/advanced/content-rules/overview#ai-agents) |
-| `audit` | Unified read-only validation audit: every content problem — content-rule violations (markdownlint, frontmatter schemas, OKF) **and** broken internal links — in one call, grouped by the file to fix (`path` scopes to a folder or doc). Each finding is tagged with its validator; broken links report under the source doc that contains them, at the offending line, as warnings by default (the project's `validation.links` setting can raise them to errors or hide them). Skill documents are excluded from the broken-link half: a skill's links routinely name files it creates only at runtime (use `links({ kind: "dead" })` to see them; links from other documents to a skill still validate; documents that merely sit under a dot directory, such as `.github/CI_RUNBOOK.md`, keep their findings). Successful responses include `ran`: enabled document-lint families plus `links` unless link validation is off. Document and project-tree OKF checks share the `okf` family, and a family absent from `ran` was not checked. A selected family remains in `ran` if it degrades, with the reason explained in `warnings`; a partial degradation may still have contributed findings. Same 10 × 10 output cap as `lint`'s audit, plus a warning cap set project-wide at 10 warnings, with accurate totals and `omittedWarningCount` when warnings are dropped. No fix shape — lint fixes go through `lint`, link repairs through `edit`/`write` |
+| `audit` | Unified read-only validation audit: every content problem — content-rule violations (markdownlint, frontmatter schemas, OKF) **and** broken internal links — in one call, grouped by the file to fix (`path` scopes to a folder or doc). Each finding is tagged with its validator; broken links report under the source doc that contains them, at the offending line, as warnings by default (the project's `validation.links` setting can raise them to errors or hide them). Skill documents are excluded from the broken-link half: a skill's links routinely name files it creates only at runtime (use `links({ kind: "dead" })` to see them; links from other documents to a skill still validate; documents that merely sit under a dot directory, such as `.github/CI_RUNBOOK.md`, keep their findings). A lowercase-stemmed `log.md` or `log.mdx` at any depth is excluded the same way while the project's default-on `validation.suppressLogLinkAdvisories` setting is on, because a log's entries deliberately reference pages that moved or were never written, and repairing them would rewrite the history (`links({ kind: "dead" })` is unconditional and still reports them, and `LOG.md` is an ordinary document that keeps its findings). Successful responses include `ran`: enabled document-lint families plus `links` unless link validation is off. Document and project-tree OKF checks share the `okf` family, and a family absent from `ran` was not checked. A selected family remains in `ran` if it degrades, with the reason explained in `warnings`; a partial degradation may still have contributed findings. Same 10 × 10 output cap as `lint`'s audit, plus a warning cap set project-wide at 10 warnings, with accurate totals and `omittedWarningCount` when warnings are dropped. No fix shape — lint fixes go through `lint`, link repairs through `edit`/`write` |
| `history` | Version timeline for a `document`, `folder`, or `skill`. Each entry carries a `version` (commit SHA) you pass to `restore_version`. Filter with `kind` (`checkpoint` / `wip` / `upstream`), `author` / `excludeAuthor`, and `branch`; paginate with `limit` / `offset` (default 50, max 200). `folder: ""` selects the project-root timeline |
| `skills` | Find skills. Pass `query` to search skills.sh and return import-ready rows (`name`, `source`, installs, publisher); omit `name` to list every managed skill across Project + Global (rows carry `installed` + `hosts`); pass `name` to read one (addressed by `name`+`scope`, never by path); pass `name` + `file` to read one bundle file's text — the read path for `references/` and `scripts/` content |
| `config` | Read the effective merged config (`config({ key: "appearance.theme" })` for a sub-tree; omit `key` for the whole config) |
diff --git a/packages/app/src/components/DocPanel.dom.test.tsx b/packages/app/src/components/DocPanel.dom.test.tsx
index 634b5b21a..b567b8c28 100644
--- a/packages/app/src/components/DocPanel.dom.test.tsx
+++ b/packages/app/src/components/DocPanel.dom.test.tsx
@@ -2,6 +2,7 @@ import { cleanup, render, screen } from '@testing-library/react';
import type { ReactNode } from 'react';
import { afterEach, describe, expect, test, vi } from 'vitest';
import { TooltipProvider } from '@/components/ui/tooltip';
+import type { DocLinkFindingsState } from '@/editor/validation-audit-client';
import { renderLinguiTemplate } from '@/test-utils/lingui-mock';
type WindowGlobals = { NodeFilter?: typeof NodeFilter };
@@ -47,10 +48,11 @@ vi.doMock('@/editor/lint-config-client', () => ({
vi.doMock('@/editor/useDocDiagnostics', () => ({
useDocDiagnostics: () => diagnosticsValue,
}));
+let docLinkFindingsValue: DocLinkFindingsState = { status: 'loaded', findings: [] };
vi.doMock('@/editor/validation-audit-client', () => ({
AUDIT_SUPERSEDED: 'audit-superseded',
runValidationAudit: async () => null,
- useDocLinkFindings: () => ({ status: 'loaded', findings: [] }),
+ useDocLinkFindings: () => docLinkFindingsValue,
}));
let terminalLaunchValue: unknown = null;
vi.doMock('@/components/handoff/TerminalLaunchContext', () => ({
@@ -99,6 +101,7 @@ afterEach(() => {
activeProviderValue = null;
terminalLaunchValue = null;
lastProblemsProps = null;
+ docLinkFindingsValue = { status: 'loaded', findings: [] };
});
describe('DocPanel — tab gating', () => {
@@ -123,6 +126,21 @@ describe('DocPanel — tab gating', () => {
expect(lastProblemsProps?.docName).toBe('notes');
expect(screen.getByRole('tabpanel').getAttribute('id')).toBe('panel-problems');
});
+
+ test('forwards reserved-log suppression from the document audit to Problems', () => {
+ docLinkFindingsValue = {
+ status: 'loaded',
+ findings: [],
+ brokenLinkSuppression: { reason: 'reserved-log-policy', count: 2 },
+ };
+
+ renderPanel('problems');
+
+ expect(lastProblemsProps?.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 2,
+ });
+ });
});
describe('DocPanel — Problems fix/ask-ai wiring', () => {
diff --git a/packages/app/src/components/DocPanel.tsx b/packages/app/src/components/DocPanel.tsx
index deebdc537..b3be0f535 100644
--- a/packages/app/src/components/DocPanel.tsx
+++ b/packages/app/src/components/DocPanel.tsx
@@ -225,6 +225,7 @@ export function DocPanel({
docName={docName}
diagnostics={diagnostics}
linkFindingsStatus={linkFindingsState.status}
+ brokenLinkSuppression={linkFindingsState.brokenLinkSuppression}
onFix={lintProvider !== null ? handleFix : undefined}
onAutoFix={lintProvider !== null ? handleAutoFix : undefined}
onAskAi={lintProvider !== null && terminalLaunch !== null ? handleAskAi : undefined}
diff --git a/packages/app/src/components/ProblemsPanel.dom.test.tsx b/packages/app/src/components/ProblemsPanel.dom.test.tsx
index 28ecfe1be..f4ef0c071 100644
--- a/packages/app/src/components/ProblemsPanel.dom.test.tsx
+++ b/packages/app/src/components/ProblemsPanel.dom.test.tsx
@@ -239,6 +239,75 @@ describe('ProblemsPanel', () => {
expect(screen.getByText('No problems found.')).toBeTruthy();
});
+ test('doc scope reports reserved-log suppression without claiming the document is clean', () => {
+ render(
+ <ProblemsPanel
+ docName="log"
+ diagnostics={[]}
+ brokenLinkSuppression={{ reason: 'reserved-log-policy', count: 2 }}
+ />,
+ );
+
+ const note = screen.getByTestId('problems-broken-link-suppression');
+ expect(note.getAttribute('role')).toBe('note');
+ expect(note.getAttribute('aria-live')).toBe('polite');
+ expect(note.textContent).toContain('Project policy hides 2 broken-link findings');
+ expect(screen.queryByText('No problems found.')).toBeNull();
+ });
+
+ test.each(['loading', 'failed'] as const)(
+ 'keeps the suppression note with the retained findings it qualifies mid-refresh (%s)',
+ (linkFindingsStatus) => {
+ render(
+ <ProblemsPanel
+ docName="log"
+ diagnostics={[diag({})]}
+ linkFindingsStatus={linkFindingsStatus}
+ brokenLinkSuppression={{ reason: 'reserved-log-policy', count: 2 }}
+ />,
+ );
+
+ expect(screen.getByText('Hard tabs')).toBeTruthy();
+ expect(screen.getByTestId('problems-broken-link-suppression').textContent).toContain(
+ 'Project policy hides 2 broken-link findings',
+ );
+ },
+ );
+
+ test('qualifies the failed link banner when suppression retains the only findings', () => {
+ render(
+ <ProblemsPanel
+ docName="log"
+ diagnostics={[]}
+ linkFindingsStatus="failed"
+ brokenLinkSuppression={{ reason: 'reserved-log-policy', count: 2 }}
+ />,
+ );
+
+ expect(screen.getByTestId('problems-links-failed').textContent).toContain(
+ 'Showing last known problems',
+ );
+ });
+
+ test('reserved-log suppression preserves the Enable plugins action without an all-clear', () => {
+ projectLintConfigData = lintConfigWith({ markdownlint: false, frontmatter: false });
+ render(
+ <ProblemsPanel
+ docName="log"
+ diagnostics={[]}
+ brokenLinkSuppression={{ reason: 'reserved-log-policy', count: 2 }}
+ />,
+ );
+
+ expect(screen.getByTestId('problems-broken-link-suppression')).toBeTruthy();
+ expect(screen.getByTestId('problems-no-plugins').textContent).toBe(
+ 'No lint plugins are enabled, so only links are checked.',
+ );
+ fireEvent.click(screen.getByTestId('problems-enable-plugins'));
+ expect(window.location.hash).toBe('#settings/plugins-manage');
+ expect(screen.getByTestId('problems-panel').textContent).not.toContain('No problems found');
+ });
+
test('qualifies the empty state when Markdown checks do not apply', () => {
render(<ProblemsPanel docName="glossary.csv" diagnostics={[]} />);
expect(screen.getByTestId('problems-markdown-not-applicable').textContent).toBe(
@@ -308,7 +377,9 @@ describe('ProblemsPanel', () => {
projectLintConfigData = lintConfigWith({ markdownlint: false, frontmatter: false });
render(<ProblemsPanel docName="notes" diagnostics={[]} />);
expect(screen.queryByTestId('problems-active-plugins')).toBeNull();
- expect(screen.getByTestId('problems-no-plugins')).toBeTruthy();
+ expect(screen.getByTestId('problems-no-plugins').textContent).toBe(
+ 'No problems found — but no lint plugins are enabled, so only links are checked.',
+ );
fireEvent.click(screen.getByTestId('problems-enable-plugins'));
expect(window.location.hash).toBe('#settings/plugins-manage');
});
@@ -996,6 +1067,23 @@ describe('ProblemsPanel — project scope', () => {
);
});
+ test('project audit shows a content-free note when reserved-log links are suppressed', async () => {
+ runLintAuditImpl = async () =>
+ auditResult({
+ brokenLinkSuppression: { reason: 'reserved-log-policy', count: 2 },
+ });
+ render(<ProblemsPanel docName="notes" diagnostics={[]} />);
+
+ fireEvent.click(screen.getByTestId('panel-scope-project'));
+ const note = await screen.findByTestId('problems-broken-link-suppression');
+ expect(note.getAttribute('role')).toBe('note');
+ expect(note.textContent).toContain('Project policy hides 2 broken-link findings');
+ expect(note.textContent).toContain('remain visible in Links');
+ expect(note.textContent).toContain('not part of the repair queue');
+ expect(note.querySelector('a')).toBeNull();
+ expect(screen.queryByText(/No problems across/)).toBeNull();
+ });
+
test('clicking a project-scope diagnostic for another doc navigates by hash and banks the intent', async () => {
runLintAuditImpl = async () =>
auditResult({
diff --git a/packages/app/src/components/ProblemsPanel.tsx b/packages/app/src/components/ProblemsPanel.tsx
index 213c86230..21714eb5a 100644
--- a/packages/app/src/components/ProblemsPanel.tsx
+++ b/packages/app/src/components/ProblemsPanel.tsx
@@ -1,6 +1,7 @@
// oxlint-disable ok/no-raw-html-interactive-element -- matches sibling OutlinePanel — positional list of <button> rows awaiting a shared shadcn list primitive; tracked at https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-raw-html-interactive-element
// oxlint-disable ok/no-physical-direction-utility -- pre-rule backlog — physical margin/padding/inset utilities predate the rule; drain by swapping ml/mr → ms/me, pl/pr → ps/pe, left/right → start/end, then deleting this line. See https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-physical-direction-utility
import {
+ type BrokenLinkSuppression,
type FrontmatterScope,
isEditableTextDocFile,
type ValidationAuditResponse,
@@ -16,6 +17,7 @@ import {
File as FileIcon,
FilePlus2,
Image as ImageIcon,
+ Info,
Link2,
type LucideIcon,
RefreshCw,
@@ -453,6 +455,7 @@ export function ProblemsPanel({
docName,
diagnostics,
linkFindingsStatus = 'loaded',
+ brokenLinkSuppression,
onFix,
onAutoFix,
onAskAi,
@@ -461,6 +464,7 @@ export function ProblemsPanel({
docName: string;
diagnostics: DiagnosticLike[];
linkFindingsStatus?: 'idle' | 'loading' | 'loaded' | 'failed';
+ brokenLinkSuppression?: BrokenLinkSuppression;
onFix?: (diagnostic: DiagnosticLike) => void;
onAutoFix?: () => void;
onAskAi?: (diagnostic: DiagnosticLike) => void;
@@ -479,6 +483,7 @@ export function ProblemsPanel({
? LINT_PLUGIN_META.filter((plugin) => lintConfig.effective.plugins[plugin.id].enabled)
: [];
const noPluginsEnabled = activePlugins !== null && activePlugins.length === 0;
+ const linkFindingsSuppressed = brokenLinkSuppression !== undefined;
const showActivePluginsPill =
(scope === 'project' || markdownChecksApply) &&
activePlugins !== null &&
@@ -700,13 +705,16 @@ export function ProblemsPanel({
</PanelEmpty>
) : linkFindingsStatus === 'failed' ? (
<PanelError className="px-2 pb-2" role="status" data-testid="problems-links-failed">
- {sorted.length > 0 ? (
+ {sorted.length > 0 || linkFindingsSuppressed ? (
<Trans>Link validation is unavailable. Showing last known problems.</Trans>
) : (
<Trans>Link validation is unavailable.</Trans>
)}
</PanelError>
) : null}
+ {linkFindingsSuppressed && (
+ <BrokenLinkSuppressionNote suppression={brokenLinkSuppression} />
+ )}
{sorted.length === 0 ? (
linkFindingsStatus !== 'loaded' ? null : !markdownChecksApply ? (
<PanelEmpty className="px-2" data-testid="problems-markdown-not-applicable">
@@ -715,9 +723,14 @@ export function ProblemsPanel({
) : noPluginsEnabled ? (
<>
<PanelEmpty className="px-2" data-testid="problems-no-plugins">
- <Trans>
- No problems found — but no lint plugins are enabled, so only links are checked.
- </Trans>
+ {linkFindingsSuppressed ? (
+ <Trans>No lint plugins are enabled, so only links are checked.</Trans>
+ ) : (
+ <Trans>
+ No problems found — but no lint plugins are enabled, so only links are
+ checked.
+ </Trans>
+ )}
</PanelEmpty>
<div className="px-2 pt-2">
<Button
@@ -730,7 +743,7 @@ export function ProblemsPanel({
</Button>
</div>
</>
- ) : (
+ ) : linkFindingsSuppressed ? null : (
<PanelEmpty className="px-2">
<Trans>No problems found.</Trans>
</PanelEmpty>
@@ -998,6 +1011,27 @@ function ProjectAuditBody({
);
}
+function BrokenLinkSuppressionNote({ suppression }: { suppression: BrokenLinkSuppression }) {
+ return (
+ <div
+ role="note"
+ aria-live="polite"
+ data-testid="problems-broken-link-suppression"
+ className="mx-2 mb-1 flex items-start gap-1.5 rounded-md border border-border/70 bg-muted/40 px-2 py-1.5 text-xs text-muted-foreground"
+ >
+ <Info aria-hidden="true" className="mt-0.5 size-3.5 shrink-0" />
+ <span className="min-w-0">
+ <Plural
+ value={suppression.count}
+ one="Project policy hides # broken-link finding from this audit."
+ other="Project policy hides # broken-link findings from this audit."
+ />{' '}
+ <Trans>These links remain visible in Links and are not part of the repair queue.</Trans>
+ </span>
+ </div>
+ );
+}
+
function ProjectAuditResults({
result,
onNavigate,
@@ -1030,14 +1064,19 @@ function ProjectAuditResults({
))}
</ul>
)}
+ {result.brokenLinkSuppression !== undefined && (
+ <BrokenLinkSuppressionNote suppression={result.brokenLinkSuppression} />
+ )}
{result.files.length === 0 ? (
- <PanelEmpty className="px-2">
- <Plural
- value={result.fileCount}
- one="No problems across # document."
- other="No problems across # documents."
- />
- </PanelEmpty>
+ result.brokenLinkSuppression === undefined ? (
+ <PanelEmpty className="px-2">
+ <Plural
+ value={result.fileCount}
+ one="No problems across # document."
+ other="No problems across # documents."
+ />
+ </PanelEmpty>
+ ) : null
) : (
result.files.map((file) => (
<ProjectFileGroup
diff --git a/packages/app/src/components/settings/ContentRulesSection.dom.test.tsx b/packages/app/src/components/settings/ContentRulesSection.dom.test.tsx
index 3e06cc485..cdc0625a2 100644
--- a/packages/app/src/components/settings/ContentRulesSection.dom.test.tsx
+++ b/packages/app/src/components/settings/ContentRulesSection.dom.test.tsx
@@ -58,6 +58,36 @@ describe('ContentRulesSection', () => {
);
});
+ test('the reserved-log advisory switch is on by default', () => {
+ render(<ContentRulesSection />);
+ const toggle = screen.getByRole('switch', { name: 'Ignore broken links in log.md' });
+ expect(toggle.getAttribute('data-state')).toBe('checked');
+ });
+
+ test('a persisted off value renders the reserved-log switch unchecked', () => {
+ projectConfigValue = { validation: { suppressLogLinkAdvisories: false } };
+ render(<ContentRulesSection />);
+ expect(screen.getByTestId('settings-content-rules-log-links').getAttribute('data-state')).toBe(
+ 'unchecked',
+ );
+ });
+
+ test('turning the reserved-log switch off writes a validation patch', () => {
+ render(<ContentRulesSection />);
+ fireEvent.click(screen.getByTestId('settings-content-rules-log-links'));
+ expect(patches).toEqual([{ validation: { suppressLogLinkAdvisories: false } }]);
+ });
+
+ test('the reserved-log description names both reserved extensions and the raw views', () => {
+ render(<ContentRulesSection />);
+ const description = describedTextOf('settings-content-rules-log-links');
+ expect(description).toContain('log.md');
+ expect(description).toContain('log.mdx');
+ expect(description).toContain('Links panel');
+ expect(description).toContain('file explorer indicators');
+ expect(description).toContain('at any folder depth');
+ });
+
test('persisted values render: links=error, indicators off', () => {
projectConfigValue = { validation: { links: 'error', fileTreeIndicators: false } };
render(<ContentRulesSection />);
@@ -74,6 +104,7 @@ describe('ContentRulesSection', () => {
'settings-content-rules-links',
'How missing project-local documents, files, and images are reported',
],
+ ['settings-content-rules-log-links', 'not the file it points at'],
['settings-content-rules-indicators', 'Tint and badge files'],
] as const) {
expect(describedTextOf(testId)).toContain(expected);
@@ -95,6 +126,38 @@ describe('ContentRulesSection', () => {
await new Promise((resolve) => setTimeout(resolve, 0));
});
+ test('the reserved-log switch is not operable while the project config is still loading', () => {
+ projectSyncedValue = false;
+ render(<ContentRulesSection />);
+ const toggle = screen.getByTestId('settings-content-rules-log-links');
+ expect(toggle.hasAttribute('disabled')).toBe(true);
+ fireEvent.click(toggle);
+ expect(patches).toEqual([]);
+ });
+
+ test('a failed reserved-log patch keeps the last confirmed value on screen', () => {
+ patchResult = { ok: false, error: 'nope' };
+ render(<ContentRulesSection />);
+ fireEvent.click(screen.getByTestId('settings-content-rules-log-links'));
+ expect(toastError).toHaveBeenCalledTimes(1);
+ expect(screen.getByTestId('settings-content-rules-log-links').getAttribute('data-state')).toBe(
+ 'checked',
+ );
+ });
+
+ test('a project-config change made elsewhere moves the reserved-log switch', () => {
+ const { rerender } = render(<ContentRulesSection />);
+ expect(screen.getByTestId('settings-content-rules-log-links').getAttribute('data-state')).toBe(
+ 'checked',
+ );
+ projectConfigValue = { validation: { suppressLogLinkAdvisories: false } };
+ rerender(<ContentRulesSection />);
+ expect(screen.getByTestId('settings-content-rules-log-links').getAttribute('data-state')).toBe(
+ 'unchecked',
+ );
+ expect(patches).toEqual([]);
+ });
+
test('a failed patch surfaces an error toast', () => {
patchResult = { ok: false, error: 'nope' };
render(<ContentRulesSection />);
diff --git a/packages/app/src/components/settings/ContentRulesSection.tsx b/packages/app/src/components/settings/ContentRulesSection.tsx
index 19c394101..2d76726d6 100644
--- a/packages/app/src/components/settings/ContentRulesSection.tsx
+++ b/packages/app/src/components/settings/ContentRulesSection.tsx
@@ -1,5 +1,6 @@
import {
DEFAULT_LINKS_VALIDATION,
+ DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
humanFormat,
type LinksValidationSetting,
} from '@inkeep/open-knowledge-core';
@@ -24,8 +25,14 @@ export function ContentRulesSection() {
const linksSetting: LinksValidationSetting =
projectConfig?.validation?.links ?? DEFAULT_LINKS_VALIDATION;
const indicatorsOn = projectConfig?.validation?.fileTreeIndicators !== false;
+ const suppressLogLinksOn =
+ projectConfig?.validation?.suppressLogLinkAdvisories ?? DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES;
- function write(patch: { links?: LinksValidationSetting; fileTreeIndicators?: boolean }): void {
+ function write(patch: {
+ links?: LinksValidationSetting;
+ fileTreeIndicators?: boolean;
+ suppressLogLinkAdvisories?: boolean;
+ }): void {
if (projectBinding === null) {
toast.error(t`Content rules not yet loaded — try again in a moment`);
return;
@@ -95,6 +102,33 @@ export function ContentRulesSection() {
</Select>
</div>
+ <div className="flex items-center justify-between gap-3 px-3 py-3">
+ <div className="min-w-0">
+ <Label htmlFor="settings-content-rules-log-links" className="text-sm font-medium">
+ <Trans>Ignore broken links in log.md</Trans>
+ </Label>
+ <p
+ id="settings-content-rules-log-links-description"
+ className="text-1sm text-muted-foreground"
+ >
+ <Trans>
+ Leave the broken links written inside a log.md or log.mdx at any folder depth out of
+ Problems, file explorer indicators, editor diagnostics, audits, and agent write
+ advisories. What counts is the file a link is written in, not the file it points at,
+ and LOG.md is an ordinary document. The Links panel and the editor still show them.
+ </Trans>
+ </p>
+ </div>
+ <Switch
+ id="settings-content-rules-log-links"
+ aria-describedby="settings-content-rules-log-links-description"
+ checked={suppressLogLinksOn}
+ disabled={!bindingReady}
+ onCheckedChange={(next) => write({ suppressLogLinkAdvisories: next })}
+ data-testid="settings-content-rules-log-links"
+ />
+ </div>
+
<div className="flex items-center justify-between gap-3 px-3 py-3">
<div className="min-w-0">
<Label htmlFor="settings-content-rules-indicators" className="text-sm font-medium">
diff --git a/packages/app/src/editor/validation-audit-client.dom.test.tsx b/packages/app/src/editor/validation-audit-client.dom.test.tsx
index d8dc97fe7..7e700388b 100644
--- a/packages/app/src/editor/validation-audit-client.dom.test.tsx
+++ b/packages/app/src/editor/validation-audit-client.dom.test.tsx
@@ -2,6 +2,7 @@ import type { ValidationAuditResponse } from '@inkeep/open-knowledge-core';
import { act, cleanup, renderHook, waitFor } from '@testing-library/react';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { emitDocumentsChanged } from '@/lib/documents-events';
+import { emitLintConfigChanged } from './lint-config-client';
import { runValidationAudit, useDocLinkFindings } from './validation-audit-client';
const origFetch = globalThis.fetch;
@@ -73,11 +74,16 @@ describe('useDocLinkFindings', () => {
errorCount: 1,
warningCount: 1,
warnings: [],
+ brokenLinkSuppression: { reason: 'reserved-log-policy', count: 2 },
};
const { result } = renderHook(() => useDocLinkFindings('notes'));
await waitFor(() => expect(result.current.status).toBe('loaded'));
expect(result.current.findings).toHaveLength(1);
expect(result.current.findings[0]?.code).toBe('dead-link');
+ expect(result.current.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 2,
+ });
expect(fetchUrls).toEqual(['/api/audit?doc=notes']);
});
@@ -108,6 +114,52 @@ describe('useDocLinkFindings', () => {
expect(fetchUrls).toHaveLength(4);
});
+ test('refreshes on a lint-config change so a policy toggle clears stale findings', async () => {
+ fetchBody = {
+ files: [{ file: 'log.md', diagnostics: [deadLink] }],
+ fileCount: 1,
+ errorCount: 1,
+ warningCount: 0,
+ warnings: [],
+ };
+ const { result } = renderHook(() => useDocLinkFindings('log'));
+ await waitFor(() => expect(result.current.findings).toHaveLength(1));
+
+ fetchBody = { files: [], fileCount: 1, errorCount: 0, warningCount: 0, warnings: [] };
+ act(() => emitLintConfigChanged());
+ await waitFor(() => expect(result.current.findings).toHaveLength(0));
+ expect(fetchUrls).toEqual(['/api/audit?doc=log', '/api/audit?doc=log']);
+ });
+
+ test('clears the suppression marker when a reload comes back without one', async () => {
+ fetchBody = {
+ files: [{ file: 'log.md', diagnostics: [] }],
+ fileCount: 1,
+ errorCount: 0,
+ warningCount: 0,
+ warnings: [],
+ brokenLinkSuppression: { reason: 'reserved-log-policy', count: 2 },
+ };
+ const { result } = renderHook(() => useDocLinkFindings('log'));
+ await waitFor(() =>
+ expect(result.current.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 2,
+ }),
+ );
+
+ fetchBody = {
+ files: [{ file: 'log.md', diagnostics: [deadLink] }],
+ fileCount: 1,
+ errorCount: 1,
+ warningCount: 0,
+ warnings: [],
+ };
+ act(() => emitLintConfigChanged());
+ await waitFor(() => expect(result.current.findings).toHaveLength(1));
+ expect(result.current.brokenLinkSuppression).toBeUndefined();
+ });
+
test('null docName serves no findings and never fetches', () => {
const { result } = renderHook(() => useDocLinkFindings(null));
expect(result.current).toEqual({ status: 'idle', findings: [] });
diff --git a/packages/app/src/editor/validation-audit-client.ts b/packages/app/src/editor/validation-audit-client.ts
index 51be754c4..7faff8406 100644
--- a/packages/app/src/editor/validation-audit-client.ts
+++ b/packages/app/src/editor/validation-audit-client.ts
@@ -1,4 +1,5 @@
import {
+ type BrokenLinkSuppression,
type ValidationAuditCountsResponse,
ValidationAuditCountsResponseSchema,
type ValidationAuditResponse,
@@ -8,6 +9,7 @@ import {
import { useEffect, useState } from 'react';
import type { z } from 'zod';
import { invalidatesLocalTargetAudit, subscribeToDocumentsChanged } from '@/lib/documents-events';
+import { subscribeToLintConfigChanged } from './lint-config-client';
type WireDiagnostic = ValidationDocResult['diagnostics'][number];
@@ -71,11 +73,14 @@ async function fetchAudit<T>(
}
}
-export type DocLinkFindingsState =
- | { status: 'idle'; findings: readonly WireDiagnostic[] }
- | { status: 'loading'; findings: readonly WireDiagnostic[] }
- | { status: 'loaded'; findings: readonly WireDiagnostic[] }
- | { status: 'failed'; findings: readonly WireDiagnostic[] };
+interface DocLinkFindingsSnapshot {
+ findings: readonly WireDiagnostic[];
+ brokenLinkSuppression?: BrokenLinkSuppression;
+}
+
+export type DocLinkFindingsState = DocLinkFindingsSnapshot & {
+ status: 'idle' | 'loading' | 'loaded' | 'failed';
+};
export function subscribeToDocLinkFindings(
docName: string,
@@ -85,8 +90,14 @@ export function subscribeToDocLinkFindings(
let inFlight = false;
let dirty = false;
let findings: readonly WireDiagnostic[] = [];
+ let brokenLinkSuppression: BrokenLinkSuppression | undefined;
let controller: AbortController | null = null;
+ const snapshot = (): DocLinkFindingsSnapshot => ({
+ findings,
+ ...(brokenLinkSuppression === undefined ? {} : { brokenLinkSuppression }),
+ });
+
const load = (): void => {
if (inFlight) {
dirty = true;
@@ -94,12 +105,12 @@ export function subscribeToDocLinkFindings(
}
inFlight = true;
controller = new AbortController();
- onState({ status: 'loading', findings });
+ onState({ status: 'loading', ...snapshot() });
void runValidationAudit({ kind: 'doc', docName }, controller.signal)
.then((result) => {
if (disposed || controller?.signal.aborted === true) return;
if (result === null) {
- onState({ status: 'failed', findings });
+ onState({ status: 'failed', ...snapshot() });
return;
}
if (result === AUDIT_SUPERSEDED) {
@@ -110,7 +121,8 @@ export function subscribeToDocLinkFindings(
findings = result.files
.flatMap((file) => file.diagnostics)
.filter((diagnostic) => diagnostic.source === 'links');
- onState({ status: 'loaded', findings });
+ brokenLinkSuppression = result.brokenLinkSuppression;
+ onState({ status: 'loaded', ...snapshot() });
})
.finally(() => {
if (disposed) return;
@@ -124,13 +136,15 @@ export function subscribeToDocLinkFindings(
};
load();
- const unsubscribe = subscribeToDocumentsChanged((channels) => {
+ const unsubscribeDocuments = subscribeToDocumentsChanged((channels) => {
if (channels.includes('backlinks') || invalidatesLocalTargetAudit(channels)) load();
});
+ const unsubscribeLintConfig = subscribeToLintConfigChanged(load);
return () => {
disposed = true;
controller?.abort();
- unsubscribe();
+ unsubscribeDocuments();
+ unsubscribeLintConfig();
};
}
diff --git a/packages/app/src/locales/ar/messages.json b/packages/app/src/locales/ar/messages.json
index e45ea57e9..3db325c55 100644
--- a/packages/app/src/locales/ar/messages.json
+++ b/packages/app/src/locales/ar/messages.json
@@ -3975,6 +3975,7 @@
"eVPynQ": ["افتح <0><1>", ["verificationUri"], "</1><2/></0> وأدخل هذا الرمز:"],
"eXPP7Z": ["يجري التفكير…"],
"e_ToF5": ["تسجيل الدخول باستخدام ", ["0"]],
+ "ea7AYn": ["تجاهل الروابط المعطلة في log.md"],
"eaHUxx": ["شريط أدوات الملفات"],
"eazHgv": [
"لا يستطيع Git تتبع هذا المجلد — فهو فارغ أو يحتوي على ملفات متجاهَلة فقط. لن يعمل الرابط حتى تضيف مستندًا متتبَّعًا."
@@ -4185,6 +4186,20 @@
"ggm6JX": ["هذه الصفحة غير موجودة بعد. افتحها لإنشائها في المحرر وطي الرسم البياني."],
"ggs9f8": ["ابحث في الملفات أو المجلدات أو الأوامر"],
"gh27t1": ["معاينات الروابط"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "zero": ["لا تخفي سياسة المشروع أي نتائج لروابط معطلة من هذا التدقيق."],
+ "one": ["تخفي سياسة المشروع نتيجة واحدة لرابط معطل من هذا التدقيق."],
+ "two": ["تخفي سياسة المشروع نتيجتين لرابطين معطلين من هذا التدقيق."],
+ "few": ["تخفي سياسة المشروع ", "#", " نتائج لروابط معطلة من هذا التدقيق."],
+ "many": ["تخفي سياسة المشروع ", "#", " نتيجة لرابط معطل من هذا التدقيق."],
+ "other": ["تخفي سياسة المشروع ", "#", " نتيجة لرابط معطل من هذا التدقيق."]
+ }
+ ]
+ ],
"gijbne": ["فشلت إعادة تسمية المسار"],
"gkOxmF": ["جارٍ النقل"],
"gk_-qj": ["تعذّرت إعادة تسمية القالب: ", ["0"]],
@@ -4668,6 +4683,7 @@
") لا تمس بقية نظامك."
],
"l87Deg": ["اختر ما تبدأ به علامة تبويب جديدة"],
+ "l91IVc": ["تظل هذه الروابط ظاهرة في «الروابط» وليست جزءًا من قائمة انتظار الإصلاح."],
"l9s3IX": ["تعذّر على ", ["agentName"], " بدء محادثة."],
"lAiyU_": ["المستند الحالي وحده يستخدم <0>#", ["tag"], "</0>."],
"lBN3T6": ["اتصالات الوكلاء"],
@@ -4768,6 +4784,7 @@
"mHVPm5": ["إعادة الاتصال مطلوبة"],
"mHf8mp": ["حذف ملف المخطط ", ["file"]],
"mHo0kp": ["انتهت مهلة طلب تفعيل أدوات Open Knowledge. تعمل هذه السلسلة بدونها."],
+ "mI1KPS": ["لا توجد إضافات فحص مفعّلة، لذا تُفحص الروابط فقط."],
"mPoOmg": ["ثبّت مهارة هنا أولاً"],
"mPy9lS": [
"نظّم مواصفاتي الحالية في فهرس مترابط مجمَّع حسب المجال، وأشِر إلى أي منها انحرف عن الكود الحالي."
@@ -4937,6 +4954,9 @@
"njBeMm": ["كلاهما"],
"njU86j": ["الخاصية «", ["trimmed"], "» موجودة بالفعل"],
"nmwqWS": ["بلا إجابة"],
+ "nnhrHd": [
+ "استبعد الروابط المعطلة المكتوبة داخل log.md أو log.mdx على أي عمق للمجلد من «المشكلات» ومؤشرات مستكشف الملفات وتشخيصات المحرر وعمليات التدقيق وتنبيهات كتابة الوكيل. المهم هو الملف الذي كُتب فيه الرابط، وليس الملف الذي يشير إليه، وLOG.md مستند عادي. تظل لوحة «الروابط» والمحرر تعرضانها."
+ ],
"noH1JX": [
"تعذّر الوصول إلى خادم التعاون — ",
["errorDetail"],
diff --git a/packages/app/src/locales/ar/messages.po b/packages/app/src/locales/ar/messages.po
index ca04a3fd1..afca6cc84 100644
--- a/packages/app/src/locales/ar/messages.po
+++ b/packages/app/src/locales/ar/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, zero {لا مشكلات في # مستند.} one {لا مشك
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, zero {إضافات} one {إضافة} two {إضافتان} few {إضافات} many {إضافة} other {إضافة}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, zero {لا تخفي سياسة المشروع أي نتائج لروابط معطلة من هذا التدقيق.} one {تخفي سياسة المشروع نتيجة واحدة لرابط معطل من هذا التدقيق.} two {تخفي سياسة المشروع نتيجتين لرابطين معطلين من هذا التدقيق.} few {تخفي سياسة المشروع # نتائج لروابط معطلة من هذا التدقيق.} many {تخفي سياسة المشروع # نتيجة لرابط معطل من هذا التدقيق.} other {تخفي سياسة المشروع # نتيجة لرابط معطل من هذا التدقيق.}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6993,6 +6998,10 @@ msgstr "إذا لم يعرض {agent} أدوات OpenKnowledge، ففعّل ال
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "إذا وصل تحديث لشيء تحرّره، فأنت من يختار أي نسخة يُبقي، مثل تعارض الدمج."
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "تجاهل الروابط المعطلة في log.md"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7688,6 +7697,10 @@ msgstr "اعرف المزيد عن {title}"
msgid "Learn more about config sharing"
msgstr "اعرف المزيد عن مشاركة الإعدادات"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "استبعد الروابط المعطلة المكتوبة داخل log.md أو log.mdx على أي عمق للمجلد من «المشكلات» ومؤشرات مستكشف الملفات وتشخيصات المحرر وعمليات التدقيق وتنبيهات كتابة الوكيل. المهم هو الملف الذي كُتب فيه الرابط، وليس الملف الذي يشير إليه، وLOG.md مستند عادي. تظل لوحة «الروابط» والمحرر تعرضانها."
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "استبعد هذه التعليقات من هذه الرسالة"
@@ -8942,6 +8955,10 @@ msgstr "لا توجد لغة مطابقة."
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "لا توجد روابط بعد. أضف روابط ويكي أو روابط Markdown لبناء رسم بياني."
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "لا توجد إضافات فحص مفعّلة، لذا تُفحص الروابط فقط."
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "لم يُحدَّد موقع. استخدم «استعراض» لاختيار مجلد."
@@ -13919,6 +13936,10 @@ msgstr "لا يوجد مجلد مشروع لهذه النافذة، لذا لا
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "تُقرأ هذه حاليًا من مجلد آخر. بعد الربط، ستُقرأ من {keep} بدلًا منه."
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "تظل هذه الروابط ظاهرة في «الروابط» وليست جزءًا من قائمة انتظار الإصلاح."
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "تأتي هذه القواعد من ملف <0>{configFile}</0> في مشروعك، وهو الذي يحكم الفحص لهذا المشروع بالكامل. شغّل القواعد أو أوقفها وحرّر خياراتها هنا؛ وتُكتب التغييرات في الملف."
diff --git a/packages/app/src/locales/bn/messages.json b/packages/app/src/locales/bn/messages.json
index 3e3eb6399..bda5ac8ac 100644
--- a/packages/app/src/locales/bn/messages.json
+++ b/packages/app/src/locales/bn/messages.json
@@ -3334,6 +3334,7 @@
"eVPynQ": ["<0><1>", ["verificationUri"], "</1><2/></0> খুলুন এবং এই কোডটি দিন:"],
"eXPP7Z": ["ভাবা হচ্ছে…"],
"e_ToF5": [["0"], " দিয়ে সাইন ইন করুন"],
+ "ea7AYn": ["log.md-এ ভাঙা লিংক উপেক্ষা করুন"],
"eaHUxx": ["Files টুলবার"],
"eazHgv": [
"Git এই ফোল্ডারের হিসাব রাখতে পারে না — এটি খালি বা এতে কেবল উপেক্ষিত ফাইল আছে। আপনি একটি হিসাবভুক্ত নথি যোগ না করা পর্যন্ত লিংকটি কাজ করবে না।"
@@ -3517,6 +3518,16 @@
"ggm6JX": ["এই পাতাটি এখনও নেই। সম্পাদকে পাতাটি তৈরি করতে ও গ্রাফ গুটিয়ে নিতে এটি খুলুন।"],
"ggs9f8": ["ফাইল, ফোল্ডার বা কমান্ড খুঁজুন"],
"gh27t1": ["লিংক প্রাকদর্শন"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "one": ["প্রকল্পের নীতি এই অডিট থেকে ", "#", "টি ভাঙা লিংকের ফলাফল লুকিয়ে রাখে।"],
+ "other": ["প্রকল্পের নীতি এই অডিট থেকে ", "#", "টি ভাঙা লিংকের ফলাফল লুকিয়ে রাখে।"]
+ }
+ ]
+ ],
"gijbne": ["পথের নাম বদলাতে ব্যর্থ"],
"gkOxmF": ["সরানো হচ্ছে"],
"gk_-qj": ["টেমপ্লেটের নাম বদলানো যায়নি: ", ["0"]],
@@ -3979,6 +3990,7 @@
" থেকে) যা আপনার সিস্টেমের বাকি অংশ স্পর্শ করবে না।"
],
"l87Deg": ["নতুন ট্যাব কী চালু করবে তা বেছে নিন"],
+ "l91IVc": ["এই লিংকগুলো লিংক প্যানেলে দৃশ্যমান থাকে এবং মেরামতের সারির অংশ নয়।"],
"l9s3IX": [["agentName"], " কথোপকথন শুরু করতে পারেনি।"],
"lAiyU_": ["কেবল বর্তমান নথিটিই <0>#", ["tag"], "</0> ব্যবহার করে।"],
"lBN3T6": ["এজেন্ট সংযোগ"],
@@ -4061,6 +4073,7 @@
"mHVPm5": ["পুনরায় যুক্ত হওয়া দরকার"],
"mHf8mp": ["স্কিমা ফাইল ", ["file"], " মুছুন"],
"mHo0kp": ["Open Knowledge টুল সক্ষম করার অনুরোধের সময় শেষ হয়েছে। এই থ্রেড সেগুলো ছাড়াই চলবে।"],
+ "mI1KPS": ["কোনো lint প্লাগইন চালু নেই, তাই শুধু লিংক পরীক্ষা করা হয়েছে।"],
"mPoOmg": ["প্রথমে এখানে একটি স্কিল ইনস্টল করুন"],
"mPy9lS": [
"আমার বিদ্যমান স্পেকগুলো এলাকা অনুযায়ী গোষ্ঠীবদ্ধ একটি যুক্ত সূচিতে সাজান, এবং যেগুলো বর্তমান কোডের সঙ্গে মিল হারিয়েছে সেগুলো চিহ্নিত করুন।"
@@ -4195,6 +4208,9 @@
"njBeMm": ["দুটোই"],
"njU86j": ["প্রপার্টি \"", ["trimmed"], "\" আগে থেকেই আছে"],
"nmwqWS": ["উত্তর দেওয়া হয়নি"],
+ "nnhrHd": [
+ "ফোল্ডারের যেকোনো গভীরতায় থাকা log.md বা log.mdx-এর ভেতরে লেখা ভাঙা লিংকগুলোকে সমস্যা, ফাইল এক্সপ্লোরারের সূচক, এডিটরের ডায়াগনস্টিক, অডিট এবং এজেন্ট লেখার পরামর্শ থেকে বাদ দিন। লিংকটি কোন ফাইলে লেখা হয়েছে সেটিই বিবেচ্য, এটি যে ফাইলকে নির্দেশ করে সেটি নয়; আর LOG.md একটি সাধারণ ডকুমেন্ট। লিংক প্যানেল ও এডিটরে এগুলো তবু দেখা যায়।"
+ ],
"noH1JX": [
"সহযোগিতা সার্ভারের নাগাল পাওয়া যায়নি — ",
["errorDetail"],
diff --git a/packages/app/src/locales/bn/messages.po b/packages/app/src/locales/bn/messages.po
index fb207da2d..f526a844b 100644
--- a/packages/app/src/locales/bn/messages.po
+++ b/packages/app/src/locales/bn/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, one {# নথিতে কোনো সমস্যা ন
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, one {প্লাগইন} other {প্লাগইন}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, one {প্রকল্পের নীতি এই অডিট থেকে #টি ভাঙা লিংকের ফলাফল লুকিয়ে রাখে।} other {প্রকল্পের নীতি এই অডিট থেকে #টি ভাঙা লিংকের ফলাফল লুকিয়ে রাখে।}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6989,6 +6994,10 @@ msgstr "{agent}-এ OpenKnowledge টুল না দেখালে, Settings
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "আপনি যা সম্পাদনা করছেন তার জন্য কোনো হালনাগাদ এলে আপনি বেছে নেন কোন সংস্করণটি রাখবেন, ঠিক মার্জ দ্বন্দ্বের মতো।"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "log.md-এ ভাঙা লিংক উপেক্ষা করুন"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7684,6 +7693,10 @@ msgstr "{title} সম্পর্কে আরও জানুন"
msgid "Learn more about config sharing"
msgstr "কনফিগ ভাগাভাগি সম্পর্কে আরও জানুন"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "ফোল্ডারের যেকোনো গভীরতায় থাকা log.md বা log.mdx-এর ভেতরে লেখা ভাঙা লিংকগুলোকে সমস্যা, ফাইল এক্সপ্লোরারের সূচক, এডিটরের ডায়াগনস্টিক, অডিট এবং এজেন্ট লেখার পরামর্শ থেকে বাদ দিন। লিংকটি কোন ফাইলে লেখা হয়েছে সেটিই বিবেচ্য, এটি যে ফাইলকে নির্দেশ করে সেটি নয়; আর LOG.md একটি সাধারণ ডকুমেন্ট। লিংক প্যানেল ও এডিটরে এগুলো তবু দেখা যায়।"
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "এই মন্তব্যগুলো এই বার্তার বাইরে রাখুন"
@@ -8938,6 +8951,10 @@ msgstr "কোনো ভাষা মেলে না।"
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "এখনও কোনো লিংক নেই। গ্রাফ গড়তে উইকি লিংক বা markdown লিংক যোগ করুন।"
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "কোনো lint প্লাগইন চালু নেই, তাই শুধু লিংক পরীক্ষা করা হয়েছে।"
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "কোনো জায়গা নির্বাচিত নেই। ফোল্ডার বাছতে Browse ব্যবহার করুন।"
@@ -13915,6 +13932,10 @@ msgstr "এই জানালার জন্য কোনো প্রকল
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "এগুলো বর্তমানে অন্য একটি ফোল্ডার থেকে পড়ে। লিংক করার পরে এগুলো পরিবর্তে {keep} থেকে পড়বে।"
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "এই লিংকগুলো লিংক প্যানেলে দৃশ্যমান থাকে এবং মেরামতের সারির অংশ নয়।"
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "এই নিয়মগুলো আপনার প্রকল্পের <0>{configFile}</0> ফাইল থেকে আসে, যা এই প্রকল্পের linting পুরোপুরি নিয়ন্ত্রণ করে। নিয়ম এখানে চালু বা বন্ধ করুন ও তাদের বিকল্প সম্পাদনা করুন; পরিবর্তন সেই ফাইলেই ফিরে লেখা হয়।"
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 3759b3e7f..b5d2c28d2 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -3423,6 +3423,7 @@
"eVPynQ": ["Open <0><1>", ["verificationUri"], "</1><2/></0> and enter this code:"],
"eXPP7Z": ["Contemplating…"],
"e_ToF5": ["Sign in with ", ["0"]],
+ "ea7AYn": ["Ignore broken links in log.md"],
"eaHUxx": ["Files toolbar"],
"eazHgv": [
"Git can't track this folder — it's empty or contains only ignored files. The link won't work until you add a tracked document."
@@ -3623,6 +3624,16 @@
],
"ggs9f8": ["Search files, folders, or commands"],
"gh27t1": ["Link previews"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "one": ["Project policy hides ", "#", " broken-link finding from this audit."],
+ "other": ["Project policy hides ", "#", " broken-link findings from this audit."]
+ }
+ ]
+ ],
"gijbne": ["Failed to rename path"],
"gkOxmF": ["Moving"],
"gk_-qj": ["Couldn't rename template: ", ["0"]],
@@ -4096,6 +4107,7 @@
") that won't touch the rest of your system."
],
"l87Deg": ["Choose what a new tab starts"],
+ "l91IVc": ["These links remain visible in Links and are not part of the repair queue."],
"l9s3IX": [["agentName"], " couldn't start a conversation."],
"lAiyU_": ["Only the current document uses <0>#", ["tag"], "</0>."],
"lBN3T6": ["Agent connections"],
@@ -4181,6 +4193,7 @@
"mHo0kp": [
"The request to enable Open Knowledge tools timed out. This thread runs without them."
],
+ "mI1KPS": ["No lint plugins are enabled, so only links are checked."],
"mPoOmg": ["install a skill here first"],
"mPy9lS": [
"Organize my existing specs into a linked index grouped by area, and flag any that have drifted out of sync with the current code."
@@ -4322,6 +4335,9 @@
"njBeMm": ["Both"],
"njU86j": ["Property \"", ["trimmed"], "\" already exists"],
"nmwqWS": ["Not answered"],
+ "nnhrHd": [
+ "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+ ],
"noH1JX": [
"Couldn't reach collab server — ",
["errorDetail"],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index 04e2002d0..1a28bf258 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, one {No problems across # document.} other {No problems acro
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, one {Plugin} other {Plugins}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6993,6 +6998,10 @@ msgstr "If {agent} shows no OpenKnowledge tools, turn the server on under Settin
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "Ignore broken links in log.md"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7688,6 +7697,10 @@ msgstr "Learn more about {title}"
msgid "Learn more about config sharing"
msgstr "Learn more about config sharing"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "Leave these comments out of this message"
@@ -8942,6 +8955,10 @@ msgstr "No language match."
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "No links yet. Add wiki links or markdown links to build a graph."
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "No lint plugins are enabled, so only links are checked."
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "No location selected. Use Browse to choose a folder."
@@ -13919,6 +13936,10 @@ msgstr "There's no project folder for this window, so a terminal can't start her
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "These currently read from another folder. After linking, they read from {keep} instead."
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "These links remain visible in Links and are not part of the repair queue."
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
diff --git a/packages/app/src/locales/es/messages.json b/packages/app/src/locales/es/messages.json
index b34572844..d6346e88d 100644
--- a/packages/app/src/locales/es/messages.json
+++ b/packages/app/src/locales/es/messages.json
@@ -3997,6 +3997,7 @@
"eVPynQ": ["Abre <0><1>", ["verificationUri"], "</1><2/></0> e introduce este código:"],
"eXPP7Z": ["Reflexionando…"],
"e_ToF5": ["Iniciar sesión con ", ["0"]],
+ "ea7AYn": ["Ignorar los enlaces rotos en log.md"],
"eaHUxx": ["Barra de herramientas de Archivos"],
"eazHgv": [
"Git no puede seguir esta carpeta: está vacía o solo contiene archivos ignorados. El enlace no funcionará hasta que añadas un documento seguido por git."
@@ -4232,6 +4233,29 @@
],
"ggs9f8": ["Busca archivos, carpetas o comandos"],
"gh27t1": ["Vista previa de enlaces"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "one": [
+ "La política del proyecto oculta ",
+ "#",
+ " hallazgo de enlace roto de esta auditoría."
+ ],
+ "many": [
+ "La política del proyecto oculta ",
+ "#",
+ " hallazgos de enlaces rotos de esta auditoría."
+ ],
+ "other": [
+ "La política del proyecto oculta ",
+ "#",
+ " hallazgos de enlaces rotos de esta auditoría."
+ ]
+ }
+ ]
+ ],
"gijbne": ["No se pudo renombrar la ruta"],
"gkOxmF": ["Moviendo"],
"gk_-qj": ["No se pudo renombrar la plantilla: ", ["0"]],
@@ -4736,6 +4760,9 @@
") que no tocará el resto de tu sistema."
],
"l87Deg": ["Elige qué inicia una pestaña nueva"],
+ "l91IVc": [
+ "Estos enlaces siguen visibles en Enlaces y no forman parte de la cola de reparación."
+ ],
"l9s3IX": [["agentName"], " no pudo iniciar una conversación."],
"lAiyU_": ["Solo el documento actual usa <0>#", ["tag"], "</0>."],
"lBN3T6": ["Conexiones de agentes"],
@@ -4838,6 +4865,9 @@
"mHo0kp": [
"La solicitud para habilitar las herramientas de Open Knowledge caducó. Este hilo funciona sin ellas."
],
+ "mI1KPS": [
+ "No hay ningún complemento de análisis activado, así que solo se comprueban los enlaces."
+ ],
"mPoOmg": ["instala primero una habilidad aquí"],
"mPy9lS": [
"Organiza mis especificaciones existentes en un índice enlazado y agrupado por área, y señala las que se hayan desincronizado del código actual."
@@ -4995,6 +5025,9 @@
"njBeMm": ["Ambos"],
"njU86j": ["La propiedad \"", ["trimmed"], "\" ya existe"],
"nmwqWS": ["Sin responder"],
+ "nnhrHd": [
+ "Deja fuera de Problemas, de los indicadores del explorador de archivos, de los diagnósticos del editor, de las auditorías y de los avisos de escritura para agentes los enlaces rotos escritos dentro de un log.md o log.mdx en cualquier nivel de carpeta. Lo que cuenta es el archivo donde está escrito el enlace, no el archivo al que apunta, y LOG.md es un documento normal. El panel Enlaces y el editor siguen mostrándolos."
+ ],
"noH1JX": [
"No se pudo contactar con el servidor de colaboración: ",
["errorDetail"],
diff --git a/packages/app/src/locales/es/messages.po b/packages/app/src/locales/es/messages.po
index 8fa36956e..578c6afd3 100644
--- a/packages/app/src/locales/es/messages.po
+++ b/packages/app/src/locales/es/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, one {Sin problemas en # documento.} many {Sin problemas en #
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, one {Complemento} many {Complementos} other {Complementos}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, one {La política del proyecto oculta # hallazgo de enlace roto de esta auditoría.} many {La política del proyecto oculta # hallazgos de enlaces rotos de esta auditoría.} other {La política del proyecto oculta # hallazgos de enlaces rotos de esta auditoría.}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6993,6 +6998,10 @@ msgstr "Si {agent} no muestra las herramientas de OpenKnowledge, activa el servi
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "Si llega una actualización de algo que estás editando, tú eliges qué versión conservar, como en un conflicto de fusión."
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "Ignorar los enlaces rotos en log.md"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7688,6 +7697,10 @@ msgstr "Más información sobre {title}"
msgid "Learn more about config sharing"
msgstr "Más información sobre compartir configuración"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "Deja fuera de Problemas, de los indicadores del explorador de archivos, de los diagnósticos del editor, de las auditorías y de los avisos de escritura para agentes los enlaces rotos escritos dentro de un log.md o log.mdx en cualquier nivel de carpeta. Lo que cuenta es el archivo donde está escrito el enlace, no el archivo al que apunta, y LOG.md es un documento normal. El panel Enlaces y el editor siguen mostrándolos."
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "Dejar estos comentarios fuera de este mensaje"
@@ -8942,6 +8955,10 @@ msgstr "Ningún idioma coincide."
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "Todavía no hay enlaces. Añade enlaces wiki o enlaces markdown para construir un grafo."
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "No hay ningún complemento de análisis activado, así que solo se comprueban los enlaces."
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "No hay ninguna ubicación seleccionada. Usa Examinar para elegir una carpeta."
@@ -13919,6 +13936,10 @@ msgstr "Esta ventana no tiene carpeta de proyecto, así que aquí no se puede in
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "Actualmente se leen desde otra carpeta. Después de vincularlas, se leerán desde {keep}."
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "Estos enlaces siguen visibles en Enlaces y no forman parte de la cola de reparación."
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "Estas reglas vienen del archivo <0>{configFile}</0> de tu proyecto, que gobierna por completo el análisis de este proyecto. Activa o desactiva reglas y edita sus opciones aquí; los cambios se escriben en el archivo."
diff --git a/packages/app/src/locales/fr/messages.json b/packages/app/src/locales/fr/messages.json
index 8ce9dbbb5..85e2504af 100644
--- a/packages/app/src/locales/fr/messages.json
+++ b/packages/app/src/locales/fr/messages.json
@@ -4038,6 +4038,7 @@
"eVPynQ": ["Ouvrez <0><1>", ["verificationUri"], "</1><2/></0> et saisissez ce code :"],
"eXPP7Z": ["Réflexion…"],
"e_ToF5": ["Se connecter avec ", ["0"]],
+ "ea7AYn": ["Ignorer les liens cassés dans log.md"],
"eaHUxx": ["Barre d'outils Fichiers"],
"eazHgv": [
"Git ne peut pas suivre ce dossier — il est vide ou ne contient que des fichiers ignorés. Le lien ne fonctionnera pas tant que vous n'aurez pas ajouté un document suivi."
@@ -4271,6 +4272,25 @@
],
"ggs9f8": ["Rechercher des fichiers, des dossiers ou des commandes"],
"gh27t1": ["Aperçus de liens"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "one": ["La politique du projet masque ", "#", " résultat de lien rompu de cet audit."],
+ "many": [
+ "La politique du projet masque ",
+ "#",
+ " résultats de liens rompus de cet audit."
+ ],
+ "other": [
+ "La politique du projet masque ",
+ "#",
+ " résultats de liens rompus de cet audit."
+ ]
+ }
+ ]
+ ],
"gijbne": ["Échec du renommage du chemin"],
"gkOxmF": ["Déplacement"],
"gk_-qj": ["Impossible de renommer le modèle : ", ["0"]],
@@ -4783,6 +4803,9 @@
") qui ne touchera pas au reste de votre système."
],
"l87Deg": ["Choisissez ce qu'ouvre un nouvel onglet"],
+ "l91IVc": [
+ "Ces liens restent visibles dans Liens et ne font pas partie de la file de réparation."
+ ],
"l9s3IX": [["agentName"], " n’a pas pu démarrer de conversation."],
"lAiyU_": ["Seul le document actuel utilise <0>#", ["tag"], "</0>."],
"lBN3T6": ["Connexions des agents"],
@@ -4887,6 +4910,7 @@
"mHo0kp": [
"La demande d'activation des outils Open Knowledge a expiré. Ce fil fonctionne sans eux."
],
+ "mI1KPS": ["Aucun plugin de vérification n'est activé, donc seuls les liens sont contrôlés."],
"mPoOmg": ["installez d'abord une compétence ici"],
"mPy9lS": [
"Organise mes spécifications existantes en un index lié, groupé par domaine, et signale celles qui ont divergé du code actuel."
@@ -5044,6 +5068,9 @@
"njBeMm": ["Les deux"],
"njU86j": ["La propriété « ", ["trimmed"], " » existe déjà"],
"nmwqWS": ["Sans réponse"],
+ "nnhrHd": [
+ "Excluez des Problèmes, des indicateurs de l’explorateur de fichiers, des diagnostics de l’éditeur, des audits et des avis d’écriture des agents les liens rompus écrits dans un fichier log.md ou log.mdx, quelle que soit la profondeur du dossier. C’est le fichier dans lequel le lien est écrit qui compte, et non celui qu’il cible, et LOG.md reste un document ordinaire. Le panneau Liens et l’éditeur continuent de les afficher."
+ ],
"noH1JX": [
"Impossible de joindre le serveur de collaboration — ",
["errorDetail"],
diff --git a/packages/app/src/locales/fr/messages.po b/packages/app/src/locales/fr/messages.po
index 4d28db961..afdd20f25 100644
--- a/packages/app/src/locales/fr/messages.po
+++ b/packages/app/src/locales/fr/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, one {Aucun problème dans # document.} many {Aucun problème
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, one {Extension} many {Extensions} other {Extensions}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, one {La politique du projet masque # résultat de lien rompu de cet audit.} many {La politique du projet masque # résultats de liens rompus de cet audit.} other {La politique du projet masque # résultats de liens rompus de cet audit.}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6993,6 +6998,10 @@ msgstr "Si {agent} n'affiche aucun outil OpenKnowledge, activez le serveur dans
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "Si une mise à jour arrive pour ce que vous êtes en train de modifier, vous choisissez quelle version conserver, comme pour un conflit de fusion."
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "Ignorer les liens cassés dans log.md"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7688,6 +7697,10 @@ msgstr "En savoir plus sur {title}"
msgid "Learn more about config sharing"
msgstr "En savoir plus sur le partage de la configuration"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "Excluez des Problèmes, des indicateurs de l’explorateur de fichiers, des diagnostics de l’éditeur, des audits et des avis d’écriture des agents les liens rompus écrits dans un fichier log.md ou log.mdx, quelle que soit la profondeur du dossier. C’est le fichier dans lequel le lien est écrit qui compte, et non celui qu’il cible, et LOG.md reste un document ordinaire. Le panneau Liens et l’éditeur continuent de les afficher."
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "Ne pas inclure ces commentaires dans ce message"
@@ -8942,6 +8955,10 @@ msgstr "Aucune langue correspondante."
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "Pas encore de liens. Ajoutez des liens wiki ou markdown pour construire un graphe."
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "Aucun plugin de vérification n'est activé, donc seuls les liens sont contrôlés."
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "Aucun emplacement sélectionné. Utilisez Parcourir pour choisir un dossier."
@@ -13919,6 +13936,10 @@ msgstr "Il n'y a pas de dossier de projet pour cette fenêtre, un terminal ne pe
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "Ces compétences sont actuellement lues depuis un autre dossier. Après la liaison, elles seront lues depuis {keep}."
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "Ces liens restent visibles dans Liens et ne font pas partie de la file de réparation."
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "Ces règles proviennent du fichier <0>{configFile}</0> de votre projet, qui régit entièrement la vérification pour ce projet. Activez ou désactivez des règles et modifiez leurs options ici ; les changements sont réécrits dans le fichier."
diff --git a/packages/app/src/locales/hi/messages.json b/packages/app/src/locales/hi/messages.json
index 514d4ce69..0de2ca10b 100644
--- a/packages/app/src/locales/hi/messages.json
+++ b/packages/app/src/locales/hi/messages.json
@@ -3319,6 +3319,7 @@
"eVPynQ": ["<0><1>", ["verificationUri"], "</1><2/></0> खोलें और यह कोड डालें:"],
"eXPP7Z": ["विचार किया जा रहा है…"],
"e_ToF5": [["0"], " से साइन इन करें"],
+ "ea7AYn": ["log.md में टूटे हुए लिंक अनदेखा करें"],
"eaHUxx": ["Files टूलबार"],
"eazHgv": [
"Git इस फ़ोल्डर पर नज़र नहीं रख सकता — यह खाली है या इसमें केवल अनदेखी की गई फ़ाइलें हैं। जब तक आप कोई ट्रैक की गई दस्तावेज़ नहीं जोड़ते तब तक लिंक काम नहीं करेगा।"
@@ -3507,6 +3508,16 @@
"ggm6JX": ["यह पेज अभी मौजूद नहीं है। संपादक में यह पेज बनाने और ग्राफ़ समेटने के लिए इसे खोलें।"],
"ggs9f8": ["फ़ाइलें, फ़ोल्डर या कमांड खोजें"],
"gh27t1": ["लिंक पूर्वावलोकन"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "one": ["प्रोजेक्ट नीति इस ऑडिट से टूटी लिंक का ", "#", " परिणाम छिपाती है।"],
+ "other": ["प्रोजेक्ट नीति इस ऑडिट से टूटी लिंक के ", "#", " परिणाम छिपाती है।"]
+ }
+ ]
+ ],
"gijbne": ["पथ का नाम बदलने में विफल"],
"gkOxmF": ["ले जा रहे हैं"],
"gk_-qj": ["टेम्पलेट का नाम नहीं बदला जा सका: ", ["0"]],
@@ -3971,6 +3982,7 @@
" से) जो आपके बाकी सिस्टम को नहीं छुएगी।"
],
"l87Deg": ["चुनें कि नया टैब क्या शुरू करे"],
+ "l91IVc": ["ये लिंक लिंक पैनल में दिखाई देती रहती हैं और मरम्मत कतार का हिस्सा नहीं हैं।"],
"l9s3IX": [["agentName"], " बातचीत शुरू नहीं कर सका।"],
"lAiyU_": ["केवल मौजूदा दस्तावेज़ <0>#", ["tag"], "</0> का उपयोग करता है।"],
"lBN3T6": ["एजेंट कनेक्शन"],
@@ -4050,6 +4062,7 @@
"mHVPm5": ["फिर से जुड़ना ज़रूरी"],
"mHf8mp": ["स्कीमा फ़ाइल ", ["file"], " हटाएँ"],
"mHo0kp": ["Open Knowledge टूल सक्षम करने के अनुरोध का समय समाप्त हो गया। यह थ्रेड उनके बिना चलता है।"],
+ "mI1KPS": ["कोई lint प्लगइन सक्षम नहीं है, इसलिए केवल लिंक जाँचे गए।"],
"mPoOmg": ["पहले यहाँ एक स्किल इंस्टॉल करें"],
"mPy9lS": [
"मेरी मौजूदा स्पेक को क्षेत्र के अनुसार समूहित एक जुड़ी हुई अनुक्रमणिका में व्यवस्थित करें, और जो मौजूदा कोड से तालमेल खो चुकी हों उन्हें चिह्नित करें।"
@@ -4187,6 +4200,9 @@
"njBeMm": ["दोनों"],
"njU86j": ["प्रॉपर्टी \"", ["trimmed"], "\" पहले से मौजूद है"],
"nmwqWS": ["उत्तर नहीं दिया गया"],
+ "nnhrHd": [
+ "किसी भी फ़ोल्डर की गहराई पर log.md या log.mdx के अंदर लिखी टूटी लिंक को समस्याओं, फ़ाइल एक्सप्लोरर संकेतकों, एडिटर निदान, ऑडिट और एजेंट लेखन सलाह से बाहर रखें। मायने उस फ़ाइल के हैं जिसमें लिंक लिखी गई है, न कि उस फ़ाइल के जिस पर वह जाती है, और LOG.md एक सामान्य दस्तावेज़ है। लिंक पैनल और एडिटर में वे फिर भी दिखाई देती हैं।"
+ ],
"noH1JX": [
"सहयोग सर्वर तक नहीं पहुँचा जा सका — ",
["errorDetail"],
diff --git a/packages/app/src/locales/hi/messages.po b/packages/app/src/locales/hi/messages.po
index d8628e177..5cef9ed44 100644
--- a/packages/app/src/locales/hi/messages.po
+++ b/packages/app/src/locales/hi/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, one {# दस्तावेज़ में कोई स
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, one {प्लगइन} other {प्लगइन}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, one {प्रोजेक्ट नीति इस ऑडिट से टूटी लिंक का # परिणाम छिपाती है।} other {प्रोजेक्ट नीति इस ऑडिट से टूटी लिंक के # परिणाम छिपाती है।}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6989,6 +6994,10 @@ msgstr "अगर {agent} में OpenKnowledge टूल नहीं दि
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "यदि आपके संपादित किए जा रहे किसी हिस्से के लिए कोई अपडेट आता है, तो आप चुनते हैं कि कौन सा संस्करण रखना है, ठीक मर्ज टकराव की तरह।"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "log.md में टूटे हुए लिंक अनदेखा करें"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7684,6 +7693,10 @@ msgstr "{title} के बारे में और जानें"
msgid "Learn more about config sharing"
msgstr "कॉन्फ़िग साझाकरण के बारे में और जानें"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "किसी भी फ़ोल्डर की गहराई पर log.md या log.mdx के अंदर लिखी टूटी लिंक को समस्याओं, फ़ाइल एक्सप्लोरर संकेतकों, एडिटर निदान, ऑडिट और एजेंट लेखन सलाह से बाहर रखें। मायने उस फ़ाइल के हैं जिसमें लिंक लिखी गई है, न कि उस फ़ाइल के जिस पर वह जाती है, और LOG.md एक सामान्य दस्तावेज़ है। लिंक पैनल और एडिटर में वे फिर भी दिखाई देती हैं।"
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "इन टिप्पणियों को इस संदेश से बाहर रखें"
@@ -8938,6 +8951,10 @@ msgstr "कोई भाषा मेल नहीं खाती।"
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "अभी कोई लिंक नहीं। ग्राफ़ बनाने के लिए विकी लिंक या markdown लिंक जोड़ें।"
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "कोई lint प्लगइन सक्षम नहीं है, इसलिए केवल लिंक जाँचे गए।"
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "कोई स्थान नहीं चुना गया। फ़ोल्डर चुनने के लिए Browse का उपयोग करें।"
@@ -13915,6 +13932,10 @@ msgstr "इस विंडो के लिए कोई प्रोजेक
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "ये अभी किसी दूसरे फ़ोल्डर से पढ़े जाते हैं। लिंक करने के बाद, ये उसकी जगह {keep} से पढ़े जाएँगे।"
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "ये लिंक लिंक पैनल में दिखाई देती रहती हैं और मरम्मत कतार का हिस्सा नहीं हैं।"
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "ये नियम आपके प्रोजेक्ट की <0>{configFile}</0> फ़ाइल से आते हैं, जो इस प्रोजेक्ट की linting पूरी तरह तय करती है। नियम यहाँ चालू या बंद करें और उनके विकल्प संपादित करें; बदलाव उसी फ़ाइल में लिखे जाते हैं।"
diff --git a/packages/app/src/locales/id/messages.json b/packages/app/src/locales/id/messages.json
index 1fd3035ec..71582484e 100644
--- a/packages/app/src/locales/id/messages.json
+++ b/packages/app/src/locales/id/messages.json
@@ -3441,6 +3441,7 @@
"eVPynQ": ["Buka <0><1>", ["verificationUri"], "</1><2/></0> lalu masukkan kode ini:"],
"eXPP7Z": ["Merenung…"],
"e_ToF5": ["Masuk dengan ", ["0"]],
+ "ea7AYn": ["Abaikan tautan rusak di log.md"],
"eaHUxx": ["Bilah alat Berkas"],
"eazHgv": [
"Git tidak bisa melacak folder ini — folder ini kosong atau hanya berisi berkas yang diabaikan. Tautannya tidak akan berfungsi sampai Anda menambahkan dokumen yang dilacak."
@@ -3640,6 +3641,15 @@
],
"ggs9f8": ["Cari berkas, folder, atau perintah"],
"gh27t1": ["Pratinjau tautan"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "other": ["Kebijakan proyek menyembunyikan ", "#", " temuan tautan rusak dari audit ini."]
+ }
+ ]
+ ],
"gijbne": ["Gagal mengganti nama jalur"],
"gkOxmF": ["Memindahkan"],
"gk_-qj": ["Templat tidak bisa diganti namanya: ", ["0"]],
@@ -4128,6 +4138,7 @@
") yang tidak akan menyentuh bagian lain sistem Anda."
],
"l87Deg": ["Pilih apa yang dimulai tab baru"],
+ "l91IVc": ["Tautan ini tetap terlihat di Tautan dan bukan bagian dari antrean perbaikan."],
"l9s3IX": [["agentName"], " tidak dapat memulai percakapan."],
"lAiyU_": ["Hanya dokumen saat ini yang memakai <0>#", ["tag"], "</0>."],
"lBN3T6": ["Koneksi agen"],
@@ -4212,6 +4223,7 @@
"mHo0kp": [
"Permintaan untuk mengaktifkan alat Open Knowledge kedaluwarsa. Utas ini berjalan tanpa alat itu."
],
+ "mI1KPS": ["Tidak ada plugin lint yang aktif, jadi hanya tautan yang diperiksa."],
"mPoOmg": ["instal dulu sebuah skill di sini"],
"mPy9lS": [
"Tata spesifikasi saya yang sudah ada menjadi indeks tertaut yang dikelompokkan per bidang, dan tandai mana saja yang sudah tidak selaras dengan kode saat ini."
@@ -4345,6 +4357,9 @@
"njBeMm": ["Keduanya"],
"njU86j": ["Properti \"", ["trimmed"], "\" sudah ada"],
"nmwqWS": ["Belum dijawab"],
+ "nnhrHd": [
+ "Kecualikan tautan rusak yang ditulis di dalam log.md atau log.mdx pada kedalaman folder mana pun dari Masalah, indikator penjelajah file, diagnostik editor, audit, dan saran penulisan agen. Yang menentukan adalah file tempat tautan ditulis, bukan file yang dituju, dan LOG.md adalah dokumen biasa. Panel Tautan dan editor tetap menampilkannya."
+ ],
"noH1JX": [
"Server kolaborasi tidak bisa dihubungi — ",
["errorDetail"],
diff --git a/packages/app/src/locales/id/messages.po b/packages/app/src/locales/id/messages.po
index 7bff5f4cb..5b23342a2 100644
--- a/packages/app/src/locales/id/messages.po
+++ b/packages/app/src/locales/id/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, other {Tidak ada masalah di # dokumen.}}"
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, other {Plugin}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, other {Kebijakan proyek menyembunyikan # temuan tautan rusak dari audit ini.}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6989,6 +6994,10 @@ msgstr "Jika {agent} tidak menampilkan alat OpenKnowledge, nyalakan server di Se
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "Jika sebuah pembaruan datang untuk hal yang sedang Anda sunting, Anda memilih versi mana yang disimpan, seperti konflik penggabungan."
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "Abaikan tautan rusak di log.md"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7684,6 +7693,10 @@ msgstr "Pelajari lebih lanjut tentang {title}"
msgid "Learn more about config sharing"
msgstr "Pelajari lebih lanjut tentang berbagi konfigurasi"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "Kecualikan tautan rusak yang ditulis di dalam log.md atau log.mdx pada kedalaman folder mana pun dari Masalah, indikator penjelajah file, diagnostik editor, audit, dan saran penulisan agen. Yang menentukan adalah file tempat tautan ditulis, bukan file yang dituju, dan LOG.md adalah dokumen biasa. Panel Tautan dan editor tetap menampilkannya."
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "Jangan sertakan komentar ini dalam pesan ini"
@@ -8938,6 +8951,10 @@ msgstr "Tidak ada bahasa yang cocok."
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "Belum ada tautan. Tambahkan tautan wiki atau tautan markdown untuk membangun sebuah graf."
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "Tidak ada plugin lint yang aktif, jadi hanya tautan yang diperiksa."
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "Tidak ada lokasi yang dipilih. Gunakan Telusuri untuk memilih folder."
@@ -13915,6 +13932,10 @@ msgstr "Tidak ada folder proyek untuk jendela ini, jadi terminal tidak bisa dimu
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "Saat ini keterampilan ini dibaca dari folder lain. Setelah ditautkan, keterampilan ini dibaca dari {keep}."
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "Tautan ini tetap terlihat di Tautan dan bukan bagian dari antrean perbaikan."
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "Aturan-aturan ini berasal dari berkas <0>{configFile}</0> proyek Anda, yang sepenuhnya mengatur lint untuk proyek ini. Nyalakan atau matikan aturan dan sunting opsinya di sini; perubahannya ditulis kembali ke berkas itu."
diff --git a/packages/app/src/locales/ko/messages.json b/packages/app/src/locales/ko/messages.json
index 3c24d580d..ca809a221 100644
--- a/packages/app/src/locales/ko/messages.json
+++ b/packages/app/src/locales/ko/messages.json
@@ -3303,6 +3303,7 @@
],
"eXPP7Z": ["숙고 중…"],
"e_ToF5": [["0"], "으로 로그인"],
+ "ea7AYn": ["log.md의 손상된 링크 무시"],
"eaHUxx": ["파일 도구 모음"],
"eazHgv": [
"Git이 이 폴더를 추적할 수 없습니다. 비어 있거나 무시된 파일만 포함되어 있습니다. 추적할 문서를 추가해야 링크가 작동합니다."
@@ -3494,6 +3495,13 @@
],
"ggs9f8": ["파일, 폴더 또는 명령 검색"],
"gh27t1": ["링크 미리보기"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ { "other": ["프로젝트 정책이 이 감사에서 깨진 링크 결과 ", "#", "개를 숨깁니다."] }
+ ]
+ ],
"gijbne": ["경로 이름을 바꾸지 못했습니다"],
"gkOxmF": ["이동 중"],
"gk_-qj": ["템플릿 이름을 바꾸지 못했습니다: ", ["0"]],
@@ -3952,6 +3960,7 @@
"에서)."
],
"l87Deg": ["새 탭 시작 화면 선택"],
+ "l91IVc": ["이 링크는 링크 패널에 계속 표시되며 수정 대기열에는 포함되지 않습니다."],
"l9s3IX": [["agentName"], " 대화 시작 실패."],
"lAiyU_": ["현재 문서만 <0>#", ["tag"], "</0>을 사용합니다."],
"lBN3T6": ["에이전트 연결"],
@@ -4031,6 +4040,7 @@
"mHo0kp": [
"Open Knowledge 도구 사용 설정 요청 시간이 초과되었습니다. 이 스레드는 도구 없이 실행됩니다."
],
+ "mI1KPS": ["lint 플러그인이 활성화되지 않아 링크만 확인합니다."],
"mPoOmg": ["여기에 먼저 스킬을 설치하세요"],
"mPy9lS": [
"기존 사양을 영역별로 그룹화한 연결된 색인으로 정리하고, 현재 코드와 동기화되지 않은 항목을 표시합니다."
@@ -4158,6 +4168,9 @@
"njBeMm": ["둘 다"],
"njU86j": ["속성 \"", ["trimmed"], "\"이 이미 있습니다"],
"nmwqWS": ["응답하지 않음"],
+ "nnhrHd": [
+ "어떤 폴더 깊이에 있든 log.md 또는 log.mdx 안에 작성된 깨진 링크를 문제, 파일 탐색기 표시, 편집기 진단, 감사 및 에이전트 쓰기 알림에서 제외합니다. 링크가 가리키는 파일이 아니라 링크가 작성된 파일을 기준으로 하며, LOG.md는 일반 문서입니다. 링크 패널과 편집기에는 계속 표시됩니다."
+ ],
"noH1JX": [
"협업 서버 연결 실패: ",
["errorDetail"],
diff --git a/packages/app/src/locales/ko/messages.po b/packages/app/src/locales/ko/messages.po
index 3b2f873a4..060c67a60 100644
--- a/packages/app/src/locales/ko/messages.po
+++ b/packages/app/src/locales/ko/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, other {#개 문서 전체에 문제가 없습니다.}}"
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, other {플러그인}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, other {프로젝트 정책이 이 감사에서 깨진 링크 결과 #개를 숨깁니다.}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6993,6 +6998,10 @@ msgstr "{agent}에 OpenKnowledge 도구가 보이지 않으면 Settings → Tool
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "편집 중인 항목에 업데이트가 도착하면 병합 충돌처럼 유지할 버전을 선택합니다."
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "log.md의 손상된 링크 무시"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7688,6 +7697,10 @@ msgstr "{title} 자세히 알아보기"
msgid "Learn more about config sharing"
msgstr "설정 공유에 대해 자세히 알아보기"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "어떤 폴더 깊이에 있든 log.md 또는 log.mdx 안에 작성된 깨진 링크를 문제, 파일 탐색기 표시, 편집기 진단, 감사 및 에이전트 쓰기 알림에서 제외합니다. 링크가 가리키는 파일이 아니라 링크가 작성된 파일을 기준으로 하며, LOG.md는 일반 문서입니다. 링크 패널과 편집기에는 계속 표시됩니다."
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "이 메시지에서 댓글 제외"
@@ -8942,6 +8955,10 @@ msgstr "일치하는 언어가 없습니다."
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "아직 링크가 없습니다. 위키 링크나 Markdown 링크를 추가하여 그래프를 만드세요."
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "lint 플러그인이 활성화되지 않아 링크만 확인합니다."
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "선택한 위치가 없습니다. 찾아보기를 사용하여 폴더를 선택하세요."
@@ -13919,6 +13936,10 @@ msgstr "이 창에 프로젝트 폴더 없음. 터미널 시작 불가."
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "현재 다른 폴더에서 읽습니다. 연결한 후에는 대신 {keep}에서 읽습니다."
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "이 링크는 링크 패널에 계속 표시되며 수정 대기열에는 포함되지 않습니다."
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "이 규칙은 프로젝트의 <0>{configFile}</0> 파일에서 가져오며, 이 파일이 프로젝트의 linting을 완전히 관리합니다. 여기서 규칙을 켜거나 끄고 옵션을 편집하면 파일에 다시 기록됩니다."
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 550e29a9a..0a2ba1f23 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -3423,6 +3423,7 @@
"eVPynQ": ["Ōƥēń <0><1>", ["verificationUri"], "</1><2/></0> àńď ēńţēŕ ţĥĩś ćōďē:"],
"eXPP7Z": ["Ćōńţēḿƥĺàţĩńĝ…"],
"e_ToF5": ["Śĩĝń ĩń ŵĩţĥ ", ["0"]],
+ "ea7AYn": ["Ĩĝńōŕē ƀŕōķēń ĺĩńķś ĩń ĺōĝ.ḿď"],
"eaHUxx": ["Ƒĩĺēś ţōōĺƀàŕ"],
"eazHgv": [
"Ĝĩţ ćàń'ţ ţŕàćķ ţĥĩś ƒōĺďēŕ — ĩţ'ś ēḿƥţŷ ōŕ ćōńţàĩńś ōńĺŷ ĩĝńōŕēď ƒĩĺēś. Ţĥē ĺĩńķ ŵōń'ţ ŵōŕķ ũńţĩĺ ŷōũ àďď à ţŕàćķēď ďōćũḿēńţ."
@@ -3623,6 +3624,16 @@
],
"ggs9f8": ["Śēàŕćĥ ƒĩĺēś, ƒōĺďēŕś, ōŕ ćōḿḿàńďś"],
"gh27t1": ["Ĺĩńķ ƥŕēvĩēŵś"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "one": ["ƤŕōĴēćţ ƥōĺĩćŷ ĥĩďēś ", "#", " ƀŕōķēń-ĺĩńķ ƒĩńďĩńĝ ƒŕōḿ ţĥĩś àũďĩţ."],
+ "other": ["ƤŕōĴēćţ ƥōĺĩćŷ ĥĩďēś ", "#", " ƀŕōķēń-ĺĩńķ ƒĩńďĩńĝś ƒŕōḿ ţĥĩś àũďĩţ."]
+ }
+ ]
+ ],
"gijbne": ["Ƒàĩĺēď ţō ŕēńàḿē ƥàţĥ"],
"gkOxmF": ["Ḿōvĩńĝ"],
"gk_-qj": ["Ćōũĺďń'ţ ŕēńàḿē ţēḿƥĺàţē: ", ["0"]],
@@ -4096,6 +4107,7 @@
") ţĥàţ ŵōń'ţ ţōũćĥ ţĥē ŕēśţ ōƒ ŷōũŕ śŷśţēḿ."
],
"l87Deg": ["Ćĥōōśē ŵĥàţ à ńēŵ ţàƀ śţàŕţś"],
+ "l91IVc": ["Ţĥēśē ĺĩńķś ŕēḿàĩń vĩśĩƀĺē ĩń Ĺĩńķś àńď àŕē ńōţ ƥàŕţ ōƒ ţĥē ŕēƥàĩŕ ǫũēũē."],
"l9s3IX": [["agentName"], " ćōũĺďń'ţ śţàŕţ à ćōńvēŕśàţĩōń."],
"lAiyU_": ["Ōńĺŷ ţĥē ćũŕŕēńţ ďōćũḿēńţ ũśēś <0>#", ["tag"], "</0>."],
"lBN3T6": ["Àĝēńţ ćōńńēćţĩōńś"],
@@ -4181,6 +4193,7 @@
"mHo0kp": [
"Ţĥē ŕēǫũēśţ ţō ēńàƀĺē Ōƥēń Ķńōŵĺēďĝē ţōōĺś ţĩḿēď ōũţ. Ţĥĩś ţĥŕēàď ŕũńś ŵĩţĥōũţ ţĥēḿ."
],
+ "mI1KPS": ["Ńō ĺĩńţ ƥĺũĝĩńś àŕē ēńàƀĺēď, śō ōńĺŷ ĺĩńķś àŕē ćĥēćķēď."],
"mPoOmg": ["ĩńśţàĺĺ à śķĩĺĺ ĥēŕē ƒĩŕśţ"],
"mPy9lS": [
"Ōŕĝàńĩźē ḿŷ ēxĩśţĩńĝ śƥēćś ĩńţō à ĺĩńķēď ĩńďēx ĝŕōũƥēď ƀŷ àŕēà, àńď ƒĺàĝ àńŷ ţĥàţ ĥàvē ďŕĩƒţēď ōũţ ōƒ śŷńć ŵĩţĥ ţĥē ćũŕŕēńţ ćōďē."
@@ -4322,6 +4335,9 @@
"njBeMm": ["ßōţĥ"],
"njU86j": ["Ƥŕōƥēŕţŷ \"", ["trimmed"], "\" àĺŕēàďŷ ēxĩśţś"],
"nmwqWS": ["Ńōţ àńśŵēŕēď"],
+ "nnhrHd": [
+ "Ĺēàvē ţĥē ƀŕōķēń ĺĩńķś ŵŕĩţţēń ĩńśĩďē à ĺōĝ.ḿď ōŕ ĺōĝ.ḿďx àţ àńŷ ƒōĺďēŕ ďēƥţĥ ōũţ ōƒ Ƥŕōƀĺēḿś, ƒĩĺē ēxƥĺōŕēŕ ĩńďĩćàţōŕś, ēďĩţōŕ ďĩàĝńōśţĩćś, àũďĩţś, àńď àĝēńţ ŵŕĩţē àďvĩśōŕĩēś. Ŵĥàţ ćōũńţś ĩś ţĥē ƒĩĺē à ĺĩńķ ĩś ŵŕĩţţēń ĩń, ńōţ ţĥē ƒĩĺē ĩţ ƥōĩńţś àţ, àńď ĹŌĜ.ḿď ĩś àń ōŕďĩńàŕŷ ďōćũḿēńţ. Ţĥē Ĺĩńķś ƥàńēĺ àńď ţĥē ēďĩţōŕ śţĩĺĺ śĥōŵ ţĥēḿ."
+ ],
"noH1JX": [
"Ćōũĺďń'ţ ŕēàćĥ ćōĺĺàƀ śēŕvēŕ — ",
["errorDetail"],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index a161ddb15..6865954ee 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -261,6 +261,11 @@ msgstr ""
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr ""
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr ""
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6989,6 +6994,10 @@ msgstr ""
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr ""
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr ""
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7684,6 +7693,10 @@ msgstr ""
msgid "Learn more about config sharing"
msgstr ""
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr ""
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr ""
@@ -8938,6 +8951,10 @@ msgstr ""
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr ""
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr ""
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr ""
@@ -13915,6 +13932,10 @@ msgstr ""
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr ""
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr ""
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr ""
diff --git a/packages/app/src/locales/pt-BR/messages.json b/packages/app/src/locales/pt-BR/messages.json
index 35e9190c4..d318aae9d 100644
--- a/packages/app/src/locales/pt-BR/messages.json
+++ b/packages/app/src/locales/pt-BR/messages.json
@@ -3918,6 +3918,7 @@
"eVPynQ": ["Abra <0><1>", ["verificationUri"], "</1><2/></0> e digite este código:"],
"eXPP7Z": ["Refletindo…"],
"e_ToF5": ["Entrar com ", ["0"]],
+ "ea7AYn": ["Ignorar links quebrados em log.md"],
"eaHUxx": ["Barra de ferramentas de Arquivos"],
"eazHgv": [
"O git não consegue rastrear esta pasta — ela está vazia ou só tem arquivos ignorados. O link não vai funcionar até você adicionar um documento rastreado."
@@ -4145,6 +4146,29 @@
"ggm6JX": ["Esta página ainda não existe. Abra para criá-la no editor e recolher o grafo."],
"ggs9f8": ["Busque arquivos, pastas ou comandos"],
"gh27t1": ["Pré-visualização de links"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "one": [
+ "A política do projeto oculta ",
+ "#",
+ " ocorrência de link quebrado desta auditoria."
+ ],
+ "many": [
+ "A política do projeto oculta ",
+ "#",
+ " ocorrências de links quebrados desta auditoria."
+ ],
+ "other": [
+ "A política do projeto oculta ",
+ "#",
+ " ocorrências de links quebrados desta auditoria."
+ ]
+ }
+ ]
+ ],
"gijbne": ["Falha ao renomear o caminho"],
"gkOxmF": ["Movendo"],
"gk_-qj": ["Não deu para renomear o modelo: ", ["0"]],
@@ -4654,6 +4678,7 @@
") que não vai mexer no resto do seu sistema."
],
"l87Deg": ["Escolha o que uma nova aba inicia"],
+ "l91IVc": ["Esses links continuam visíveis em Links e não fazem parte da fila de reparo."],
"l9s3IX": [["agentName"], " não conseguiu iniciar uma conversa."],
"lAiyU_": ["Só o documento atual usa <0>#", ["tag"], "</0>."],
"lBN3T6": ["Conexões de agentes"],
@@ -4748,6 +4773,7 @@
"mHo0kp": [
"O pedido para ativar as ferramentas do Open Knowledge expirou. Esta conversa funciona sem elas."
],
+ "mI1KPS": ["Nenhum plugin de análise está ativado, então só os links são verificados."],
"mPoOmg": ["instale primeiro uma habilidade aqui"],
"mPy9lS": [
"Organize minhas especificações existentes em um índice interligado e agrupado por área, e sinalize as que se desencontraram do código atual."
@@ -4907,6 +4933,9 @@
"njBeMm": ["Ambos"],
"njU86j": ["A propriedade \"", ["trimmed"], "\" já existe"],
"nmwqWS": ["Sem resposta"],
+ "nnhrHd": [
+ "Deixe os links quebrados escritos em um log.md ou log.mdx, em qualquer profundidade de pasta, fora de Problemas, dos indicadores do explorador de arquivos, dos diagnósticos do editor, das auditorias e dos avisos de escrita do agente. O que conta é o arquivo em que o link foi escrito, não o arquivo para o qual ele aponta, e LOG.md é um documento comum. O painel Links e o editor continuam exibindo esses links."
+ ],
"noH1JX": [
"Não deu para contatar o servidor de colaboração — ",
["errorDetail"],
diff --git a/packages/app/src/locales/pt-BR/messages.po b/packages/app/src/locales/pt-BR/messages.po
index 7e3d059e8..e5317800d 100644
--- a/packages/app/src/locales/pt-BR/messages.po
+++ b/packages/app/src/locales/pt-BR/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, one {Nenhum problema em # documento.} many {Nenhum problema
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, one {Plugin} many {Plugins} other {Plugins}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, one {A política do projeto oculta # ocorrência de link quebrado desta auditoria.} many {A política do projeto oculta # ocorrências de links quebrados desta auditoria.} other {A política do projeto oculta # ocorrências de links quebrados desta auditoria.}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6989,6 +6994,10 @@ msgstr "Se o {agent} não mostrar as ferramentas do OpenKnowledge, ative o servi
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "Se chegar uma atualização de algo que você está editando, você escolhe qual versão manter, como em um conflito de mesclagem."
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "Ignorar links quebrados em log.md"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7684,6 +7693,10 @@ msgstr "Saiba mais sobre {title}"
msgid "Learn more about config sharing"
msgstr "Saiba mais sobre compartilhamento de configuração"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "Deixe os links quebrados escritos em um log.md ou log.mdx, em qualquer profundidade de pasta, fora de Problemas, dos indicadores do explorador de arquivos, dos diagnósticos do editor, das auditorias e dos avisos de escrita do agente. O que conta é o arquivo em que o link foi escrito, não o arquivo para o qual ele aponta, e LOG.md é um documento comum. O painel Links e o editor continuam exibindo esses links."
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "Deixar estes comentários fora desta mensagem"
@@ -8938,6 +8951,10 @@ msgstr "Nenhum idioma corresponde."
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "Ainda não há links. Adicione links wiki ou links markdown para montar um grafo."
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "Nenhum plugin de análise está ativado, então só os links são verificados."
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "Nenhum local selecionado. Use Procurar para escolher uma pasta."
@@ -13915,6 +13932,10 @@ msgstr "Esta janela não tem pasta de projeto, então não dá para iniciar um t
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "Elas são lidas de outra pasta no momento. Após a vinculação, serão lidas de {keep}."
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "Esses links continuam visíveis em Links e não fazem parte da fila de reparo."
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "Estas regras vêm do arquivo <0>{configFile}</0> do seu projeto, que governa por completo a análise deste projeto. Ligue ou desligue regras e edite as opções delas aqui; as alterações são gravadas no arquivo."
diff --git a/packages/app/src/locales/ur/messages.json b/packages/app/src/locales/ur/messages.json
index b8e267601..ff89af839 100644
--- a/packages/app/src/locales/ur/messages.json
+++ b/packages/app/src/locales/ur/messages.json
@@ -3508,6 +3508,7 @@
"eVPynQ": ["<0><1>", ["verificationUri"], "</1><2/></0> کھولیں اور یہ کوڈ درج کریں:"],
"eXPP7Z": ["غور کیا جا رہا ہے…"],
"e_ToF5": [["0"], " سے سائن اِن کریں"],
+ "ea7AYn": ["log.md میں ٹوٹے ہوئے لنکس نظر انداز کریں"],
"eaHUxx": ["فائلوں کا ٹول بار"],
"eazHgv": [
"Git اس فولڈر کو ٹریک نہیں کر سکتا — یہ خالی ہے یا اس میں صرف نظر انداز شدہ فائلیں ہیں۔ جب تک آپ کوئی ٹریک شدہ دستاویز شامل نہ کریں لنک کام نہیں کرے گا۔"
@@ -3705,6 +3706,16 @@
"ggm6JX": ["یہ صفحہ ابھی موجود نہیں۔ ایڈیٹر میں صفحہ بنانے اور گراف سکیڑنے کے لیے اسے کھولیں۔"],
"ggs9f8": ["فائلیں، فولڈرز یا کمانڈز تلاش کریں"],
"gh27t1": ["لنک کے پیش منظر"],
+ "gi9c0-": [
+ [
+ "0",
+ "plural",
+ {
+ "one": ["پروجیکٹ پالیسی اس آڈٹ سے خراب لنک کا ", "#", " نتیجہ چھپاتی ہے۔"],
+ "other": ["پروجیکٹ پالیسی اس آڈٹ سے خراب لنکس کے ", "#", " نتائج چھپاتی ہے۔"]
+ }
+ ]
+ ],
"gijbne": ["راستے کا نام نہیں بدلا جا سکا"],
"gkOxmF": ["منتقل کیا جا رہا ہے"],
"gk_-qj": ["ٹیمپلیٹ کا نام نہیں بدلا جا سکا: ", ["0"]],
@@ -4188,6 +4199,7 @@
" سے) جو آپ کے باقی سسٹم کو نہیں چھوئے گی۔"
],
"l87Deg": ["منتخب کریں کہ نیا ٹیب کیا شروع کرے"],
+ "l91IVc": ["یہ لنکس، لنکس پینل میں نظر آتے رہتے ہیں اور مرمت کی قطار کا حصہ نہیں ہیں۔"],
"l9s3IX": [["agentName"], " گفتگو شروع نہ کر سکا۔"],
"lAiyU_": ["صرف موجودہ دستاویز <0>#", ["tag"], "</0> استعمال کرتی ہے۔"],
"lBN3T6": ["ایجنٹ کنکشنز"],
@@ -4279,6 +4291,7 @@
"mHo0kp": [
"Open Knowledge ٹولز فعال کرنے کی درخواست کا وقت ختم ہو گیا۔ یہ تھریڈ ان کے بغیر چلے گا۔"
],
+ "mI1KPS": ["کوئی لِنٹ پلگ اِن فعال نہیں، اس لیے صرف لنکس جانچے جاتے ہیں۔"],
"mPoOmg": ["پہلے یہاں ایک اسکل انسٹال کریں"],
"mPy9lS": [
"میری موجودہ اسپیکس کو شعبے کے لحاظ سے گروپ شدہ ایک مربوط اشاریے میں منظم کریں، اور ان میں سے کسی کو نشان زد کریں جو موجودہ کوڈ سے ہم آہنگ نہ رہی ہو۔"
@@ -4421,6 +4434,9 @@
"njBeMm": ["دونوں"],
"njU86j": ["خصوصیت «", ["trimmed"], "» پہلے سے موجود ہے"],
"nmwqWS": ["جواب نہیں دیا گیا"],
+ "nnhrHd": [
+ "کسی بھی فولڈر کی گہرائی میں log.md یا log.mdx کے اندر لکھے خراب لنکس کو مسائل، فائل ایکسپلورر کے اشاروں، ایڈیٹر کی تشخیص، آڈٹس اور ایجنٹ تحریری مشوروں سے باہر رکھیں۔ اہم وہ فائل ہے جس میں لنک لکھا گیا ہے، نہ کہ وہ فائل جس کی طرف لنک اشارہ کرتا ہے، اور LOG.md ایک عام دستاویز ہے۔ لنکس پینل اور ایڈیٹر میں یہ لنکس پھر بھی دکھائی دیتے ہیں۔"
+ ],
"noH1JX": [
"اشتراکی سرور تک رسائی نہیں ہو سکی — ",
["errorDetail"],
diff --git a/packages/app/src/locales/ur/messages.po b/packages/app/src/locales/ur/messages.po
index 80ab765a8..c9e231266 100644
--- a/packages/app/src/locales/ur/messages.po
+++ b/packages/app/src/locales/ur/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, one {# دستاویز میں کوئی مسئلہ نہیں۔}
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, one {پلگ اِن} other {پلگ اِنز}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, one {پروجیکٹ پالیسی اس آڈٹ سے خراب لنک کا # نتیجہ چھپاتی ہے۔} other {پروجیکٹ پالیسی اس آڈٹ سے خراب لنکس کے # نتائج چھپاتی ہے۔}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6993,6 +6998,10 @@ msgstr "اگر {agent} میں OpenKnowledge ٹولز نظر نہ آئیں تو S
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "اگر آپ جس چیز میں ترمیم کر رہے ہیں اس کی اپ ڈیٹ آ جائے تو آپ خود منتخب کرتے ہیں کہ کون سا ورژن رکھنا ہے، بالکل ضم کے تصادم کی طرح۔"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "log.md میں ٹوٹے ہوئے لنکس نظر انداز کریں"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7688,6 +7697,10 @@ msgstr "{title} کے بارے میں مزید جانیں"
msgid "Learn more about config sharing"
msgstr "کنفیگ کے اشتراک کے بارے میں مزید جانیں"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "کسی بھی فولڈر کی گہرائی میں log.md یا log.mdx کے اندر لکھے خراب لنکس کو مسائل، فائل ایکسپلورر کے اشاروں، ایڈیٹر کی تشخیص، آڈٹس اور ایجنٹ تحریری مشوروں سے باہر رکھیں۔ اہم وہ فائل ہے جس میں لنک لکھا گیا ہے، نہ کہ وہ فائل جس کی طرف لنک اشارہ کرتا ہے، اور LOG.md ایک عام دستاویز ہے۔ لنکس پینل اور ایڈیٹر میں یہ لنکس پھر بھی دکھائی دیتے ہیں۔"
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "ان تبصروں کو اس پیغام سے باہر رکھیں"
@@ -8942,6 +8955,10 @@ msgstr "کوئی زبان مماثل نہیں۔"
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "ابھی کوئی لنک نہیں۔ گراف بنانے کے لیے وکی لنکس یا Markdown لنکس شامل کریں۔"
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "کوئی لِنٹ پلگ اِن فعال نہیں، اس لیے صرف لنکس جانچے جاتے ہیں۔"
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "کوئی مقام منتخب نہیں۔ فولڈر منتخب کرنے کے لیے «براؤز کریں» استعمال کریں۔"
@@ -13919,6 +13936,10 @@ msgstr "اس ونڈو کے لیے کوئی پروجیکٹ فولڈر نہیں،
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "یہ اس وقت کسی دوسرے فولڈر سے پڑھی جاتی ہیں۔ لنک کرنے کے بعد، یہ اس کی بجائے {keep} سے پڑھی جائیں گی۔"
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "یہ لنکس، لنکس پینل میں نظر آتے رہتے ہیں اور مرمت کی قطار کا حصہ نہیں ہیں۔"
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "یہ قواعد آپ کے پروجیکٹ کی <0>{configFile}</0> فائل سے آتے ہیں، جو اس پروجیکٹ کے لِنٹنگ کو مکمل طور پر چلاتی ہے۔ قواعد یہاں فعال یا بند کریں اور ان کے آپشنز میں ترمیم کریں؛ تبدیلیاں واپس فائل میں لکھی جاتی ہیں۔"
diff --git a/packages/app/src/locales/zh-Hans/messages.json b/packages/app/src/locales/zh-Hans/messages.json
index 55ad10604..16a117cbc 100644
--- a/packages/app/src/locales/zh-Hans/messages.json
+++ b/packages/app/src/locales/zh-Hans/messages.json
@@ -2989,6 +2989,7 @@
"eVPynQ": ["打开 <0><1>", ["verificationUri"], "</1><2/></0>,并输入这个验证码:"],
"eXPP7Z": ["正在思考…"],
"e_ToF5": ["使用 ", ["0"], " 登录"],
+ "ea7AYn": ["忽略 log.md 中失效的链接"],
"eaHUxx": ["「文件」工具栏"],
"eazHgv": [
"Git 无法跟踪这个文件夹——它是空的,或者只包含被忽略的文件。在你添加一个受跟踪的文档之前,链接不会生效。"
@@ -3154,6 +3155,9 @@
"ggm6JX": ["这个页面还不存在。打开它即可在编辑器中创建该页面并折叠关系图。"],
"ggs9f8": ["搜索文件、文件夹或命令"],
"gh27t1": ["链接预览"],
+ "gi9c0-": [
+ ["0", "plural", { "other": ["项目策略从此次审计中隐藏了 ", "#", " 个失效链接问题。"] }]
+ ],
"gijbne": ["重命名路径失败"],
"gkOxmF": ["正在移动"],
"gk_-qj": ["无法重命名模板:", ["0"]],
@@ -3589,6 +3593,7 @@
"),不会影响你系统的其余部分。"
],
"l87Deg": ["选择新标签页启动的内容"],
+ "l91IVc": ["这些链接仍会显示在“链接”中,但不属于修复队列。"],
"l9s3IX": [["agentName"], " 无法开始对话。"],
"lAiyU_": ["只有当前文档使用 <0>#", ["tag"], "</0>。"],
"lBN3T6": ["智能体连接"],
@@ -3663,6 +3668,7 @@
"mHVPm5": ["需要重新连接"],
"mHf8mp": ["删除架构文件 ", ["file"]],
"mHo0kp": ["启用 Open Knowledge 工具的请求已超时。此线程将在没有这些工具的情况下运行。"],
+ "mI1KPS": ["没有启用任何检查插件,所以只检查了链接。"],
"mPoOmg": ["请先在此处安装一个技能"],
"mPy9lS": ["把我现有的规格整理成一个按领域分组的链接索引,并标出与当前代码脱节的部分。"],
"mPzgTS": ["打开 ", ["docName"]],
@@ -3769,6 +3775,9 @@
"njBeMm": ["两者"],
"njU86j": ["属性 \"", ["trimmed"], "\" 已存在"],
"nmwqWS": ["未回答"],
+ "nnhrHd": [
+ "无论文件夹层级多深,都不在“问题”、文件资源管理器指示器、编辑器诊断、审计和代理写入建议中显示写在 log.md 或 log.mdx 内的失效链接。判断依据是链接写在哪个文件中,而不是它指向哪个文件;LOG.md 是普通文档。“链接”面板和编辑器仍会显示这些链接。"
+ ],
"noH1JX": [
"无法连接到协作服务器——",
["errorDetail"],
diff --git a/packages/app/src/locales/zh-Hans/messages.po b/packages/app/src/locales/zh-Hans/messages.po
index e9f8f72f3..dbffd3ecd 100644
--- a/packages/app/src/locales/zh-Hans/messages.po
+++ b/packages/app/src/locales/zh-Hans/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, other {# 个文档均无问题。}}"
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, other {插件}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, other {项目策略从此次审计中隐藏了 # 个失效链接问题。}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6993,6 +6998,10 @@ msgstr "如果 {agent} 没有显示 OpenKnowledge 工具,请在 Settings → T
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "如果你正在编辑的内容收到更新,你可以像处理合并冲突那样选择保留哪个版本。"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "忽略 log.md 中失效的链接"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7688,6 +7697,10 @@ msgstr "了解更多关于 {title} 的信息"
msgid "Learn more about config sharing"
msgstr "了解更多关于配置共享的信息"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "无论文件夹层级多深,都不在“问题”、文件资源管理器指示器、编辑器诊断、审计和代理写入建议中显示写在 log.md 或 log.mdx 内的失效链接。判断依据是链接写在哪个文件中,而不是它指向哪个文件;LOG.md 是普通文档。“链接”面板和编辑器仍会显示这些链接。"
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "不要把这些评论放进这条消息"
@@ -8942,6 +8955,10 @@ msgstr "没有匹配的语言。"
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "还没有链接。添加维基链接或 markdown 链接来构建关系图。"
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "没有启用任何检查插件,所以只检查了链接。"
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "未选择位置。请用「浏览」选择一个文件夹。"
@@ -13919,6 +13936,10 @@ msgstr "这个窗口没有对应的项目文件夹,因此无法在这里启动
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "这些技能目前从另一个文件夹读取。链接后,它们将改为从 {keep} 读取。"
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "这些链接仍会显示在“链接”中,但不属于修复队列。"
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "这些规则来自你项目的 <0>{configFile}</0> 文件,该文件完全决定了这个项目的检查行为。可以在这里开关规则并编辑它们的选项;更改会写回该文件。"
diff --git a/packages/app/src/locales/zh-Hant/messages.json b/packages/app/src/locales/zh-Hant/messages.json
index d562a4e47..6fbee98e7 100644
--- a/packages/app/src/locales/zh-Hant/messages.json
+++ b/packages/app/src/locales/zh-Hant/messages.json
@@ -3013,6 +3013,7 @@
"eVPynQ": ["開啟 <0><1>", ["verificationUri"], "</1><2/></0>,然後輸入這組驗證碼:"],
"eXPP7Z": ["思考中…"],
"e_ToF5": ["使用 ", ["0"], " 登入"],
+ "ea7AYn": ["忽略 log.md 中失效的連結"],
"eaHUxx": ["「檔案」工具列"],
"eazHgv": [
"Git 無法追蹤這個資料夾——它是空的,或者只有被忽略的檔案。在你加入一份被追蹤的文件之前,連結不會生效。"
@@ -3186,6 +3187,9 @@
"ggm6JX": ["這個頁面還不存在。開啟它就能在編輯器中建立這個頁面並摺疊關係圖。"],
"ggs9f8": ["搜尋檔案、資料夾或指令"],
"gh27t1": ["連結預覽"],
+ "gi9c0-": [
+ ["0", "plural", { "other": ["專案政策從此次稽核中隱藏了 ", "#", " 個失效連結問題。"] }]
+ ],
"gijbne": ["重新命名路徑失敗"],
"gkOxmF": ["移動中"],
"gk_-qj": ["無法重新命名範本:", ["0"]],
@@ -3617,6 +3621,7 @@
"),不會動到你系統的其他部分。"
],
"l87Deg": ["選擇新分頁啟動的內容"],
+ "l91IVc": ["這些連結仍會顯示在「連結」中,但不屬於修復佇列。"],
"l9s3IX": [["agentName"], " 無法開始對話。"],
"lAiyU_": ["只有目前這份文件用到 <0>#", ["tag"], "</0>。"],
"lBN3T6": ["智慧代理連線"],
@@ -3691,6 +3696,7 @@
"mHVPm5": ["需要重新連接"],
"mHf8mp": ["刪除結構描述檔案 ", ["file"]],
"mHo0kp": ["啟用 Open Knowledge 工具的請求已逾時。此執行緒將在沒有這些工具的情況下運作。"],
+ "mI1KPS": ["沒有啟用任何檢查外掛,所以只檢查了連結。"],
"mPoOmg": ["請先在此處安裝一個技能"],
"mPy9lS": ["把我現有的規格整理成一個依領域分組的連結索引,並標出和目前程式碼已經脫節的部分。"],
"mPzgTS": ["開啟 ", ["docName"]],
@@ -3799,6 +3805,9 @@
"njBeMm": ["兩者"],
"njU86j": ["屬性「", ["trimmed"], "」已存在"],
"nmwqWS": ["未回答"],
+ "nnhrHd": [
+ "無論資料夾層級多深,都不在「問題」、檔案總管指示器、編輯器診斷、稽核和代理程式寫入建議中顯示寫在 log.md 或 log.mdx 內的失效連結。判斷依據是連結寫在哪個檔案中,而不是它指向哪個檔案;LOG.md 是一般文件。「連結」面板和編輯器仍會顯示這些連結。"
+ ],
"noH1JX": [
"無法連上協作伺服器——",
["errorDetail"],
diff --git a/packages/app/src/locales/zh-Hant/messages.po b/packages/app/src/locales/zh-Hant/messages.po
index 2a77a1654..839341927 100644
--- a/packages/app/src/locales/zh-Hant/messages.po
+++ b/packages/app/src/locales/zh-Hant/messages.po
@@ -261,6 +261,11 @@ msgstr "{0, plural, other {# 份文件都沒有問題。}}"
msgid "{0, plural, one {Plugin} other {Plugins}}"
msgstr "{0, plural, other {外掛程式}}"
+#. placeholder {0}: suppression.count
+#: src/components/ProblemsPanel.tsx
+msgid "{0, plural, one {Project policy hides # broken-link finding from this audit.} other {Project policy hides # broken-link findings from this audit.}}"
+msgstr "{0, plural, other {專案政策從此次稽核中隱藏了 # 個失效連結問題。}}"
+
#. placeholder {0}: skillRows.length
#: src/components/CreatedItemsList.tsx
msgid "{0, plural, one {Skill} other {Skills}}"
@@ -6993,6 +6998,10 @@ msgstr "如果 {agent} 沒有顯示 OpenKnowledge 工具,請到 Settings → T
msgid "If an update arrives for something you are editing, you choose which version to keep, like a merge conflict."
msgstr "如果你正在編輯的東西收到更新,你可以像處理合併衝突那樣選擇要保留哪個版本。"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Ignore broken links in log.md"
+msgstr "忽略 log.md 中失效的連結"
+
#: src/components/ConsentDialogBody.tsx
#: src/components/settings/OkignoreSection.tsx
#: src/components/settings/SettingsDialogShell.tsx
@@ -7688,6 +7697,10 @@ msgstr "進一步了解 {title}"
msgid "Learn more about config sharing"
msgstr "了解更多關於設定分享的資訊"
+#: src/components/settings/ContentRulesSection.tsx
+msgid "Leave the broken links written inside a log.md or log.mdx at any folder depth out of Problems, file explorer indicators, editor diagnostics, audits, and agent write advisories. What counts is the file a link is written in, not the file it points at, and LOG.md is an ordinary document. The Links panel and the editor still show them."
+msgstr "無論資料夾層級多深,都不在「問題」、檔案總管指示器、編輯器診斷、稽核和代理程式寫入建議中顯示寫在 log.md 或 log.mdx 內的失效連結。判斷依據是連結寫在哪個檔案中,而不是它指向哪個檔案;LOG.md 是一般文件。「連結」面板和編輯器仍會顯示這些連結。"
+
#: src/comments/comment-chips.tsx
msgid "Leave these comments out of this message"
msgstr "不要把這些註解放進這則訊息"
@@ -8942,6 +8955,10 @@ msgstr "沒有相符的語言。"
msgid "No links yet. Add wiki links or markdown links to build a graph."
msgstr "還沒有連結。加上維基連結或 markdown 連結來建立關係圖。"
+#: src/components/ProblemsPanel.tsx
+msgid "No lint plugins are enabled, so only links are checked."
+msgstr "沒有啟用任何檢查外掛,所以只檢查了連結。"
+
#: src/components/CreateProjectDialog.tsx
msgid "No location selected. Use Browse to choose a folder."
msgstr "沒有選取位置。請用「瀏覽」挑一個資料夾。"
@@ -13919,6 +13936,10 @@ msgstr "這個視窗沒有對應的專案資料夾,所以無法在這裡啟動
msgid "These currently read from another folder. After linking, they read from {keep} instead."
msgstr "這些技能目前從另一個資料夾讀取。連結後,它們將改為從 {keep} 讀取。"
+#: src/components/ProblemsPanel.tsx
+msgid "These links remain visible in Links and are not part of the repair queue."
+msgstr "這些連結仍會顯示在「連結」中,但不屬於修復佇列。"
+
#: src/components/settings/markdownlint-rule-browser.tsx
msgid "These rules come from your project's <0>{configFile}</0> file, which fully governs linting for this project. Turn rules on or off and edit their options here; changes write back to the file."
msgstr "這些規則來自你專案的 <0>{configFile}</0> 檔案,那個檔案完全決定了這個專案的檢查行為。可以在這裡開關規則並編輯它們的選項;變更會寫回那個檔案。"
diff --git a/packages/app/tests/integration/advisory-warnings.test.ts b/packages/app/tests/integration/advisory-warnings.test.ts
index c3ffa9a2a..262d233b8 100644
--- a/packages/app/tests/integration/advisory-warnings.test.ts
+++ b/packages/app/tests/integration/advisory-warnings.test.ts
@@ -16,6 +16,8 @@ afterAll(async () => {
interface WriteResponse {
timestamp?: string;
warnings?: AdvisoryWarning[];
+ brokenLinks?: { href: string }[];
+ brokenLinkSuppression?: { reason: string; count: number };
[key: string]: unknown;
}
@@ -256,4 +258,43 @@ describe('content-rule (lint) violations on the agent write path', () => {
writeFileSync(cfgPath, '', 'utf-8');
}
});
+
+ test('the reserved-log policy moves both link channels together, not just brokenLinks', async () => {
+ const { writeFileSync } = await import('node:fs');
+ const { join } = await import('node:path');
+ const cfgPath = join(server.contentDir, '.ok', 'config.yml');
+ const target = `rw-log-ghost-${crypto.randomUUID().slice(0, 8)}`;
+ const body = `# Log\n\nSee [[${target}]].\n`;
+ const logDoc = `${uniqueDoc('rw-logdir')}/log`;
+
+ const deadLinkWarning = (r: { body: WriteResponse }) =>
+ (r.body.warnings ?? []).find((w) => w.kind === 'lint-violation' && w.code === 'dead-link');
+
+ const suppressed = await writeMd(body, logDoc);
+ expect(suppressed.status).toBe(200);
+ expect(suppressed.body.brokenLinks).toEqual([]);
+ expect(suppressed.body.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 1,
+ });
+ expect(deadLinkWarning(suppressed)).toBeUndefined();
+
+ const ordinary = await writeMd(body, uniqueDoc('rw-logsibling'));
+ expect(ordinary.status).toBe(200);
+ const ordinaryDead = deadLinkWarning(ordinary);
+ expect(ordinaryDead?.kind === 'lint-violation' && ordinaryDead.linkTarget).toBe(target);
+ expect(ordinary.body.brokenLinkSuppression).toBeUndefined();
+
+ writeFileSync(cfgPath, 'validation:\n suppressLogLinkAdvisories: false\n', 'utf-8');
+ try {
+ const restored = await writeMd(body, `${uniqueDoc('rw-logdir-off')}/log`);
+ expect(restored.status).toBe(200);
+ expect((restored.body.brokenLinks ?? []).length).toBe(1);
+ expect(restored.body.brokenLinkSuppression).toBeUndefined();
+ const restoredDead = deadLinkWarning(restored);
+ expect(restoredDead?.kind === 'lint-violation' && restoredDead.linkTarget).toBe(target);
+ } finally {
+ writeFileSync(cfgPath, '', 'utf-8');
+ }
+ });
});
diff --git a/packages/app/tests/integration/audit-config-epoch.test.ts b/packages/app/tests/integration/audit-config-epoch.test.ts
index c8ef652a1..151556f44 100644
--- a/packages/app/tests/integration/audit-config-epoch.test.ts
+++ b/packages/app/tests/integration/audit-config-epoch.test.ts
@@ -1,9 +1,20 @@
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
-import { ValidationAuditResponseSchema } from '@inkeep/open-knowledge-core';
+import { HocuspocusProvider } from '@hocuspocus/provider';
+import {
+ bindConfigDoc,
+ CONFIG_DOC_NAME_PROJECT,
+ ValidationAuditResponseSchema,
+} from '@inkeep/open-knowledge-core';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
-import { createTestServer, type TestServer } from './test-harness.ts';
+import {
+ awaitBacklinkIndexed,
+ createTestServer,
+ pollUntil,
+ type TestServer,
+} from './test-harness.ts';
let server: TestServer;
@@ -88,4 +99,91 @@ describe('GET /api/audit across a lint-config change', () => {
},
TEST_TIMEOUT_MS,
);
+
+ test(
+ 'an in-flight audit is superseded when the committed project config changes',
+ async () => {
+ const folder = join(server.contentDir, SCOPE);
+ const configPath = join(server.contentDir, '.ok', 'config.yml');
+ seedTabbedCorpus(folder);
+ writeFileSync(join(folder, 'log.md'), '# Log\n\n[[missing-history-target]]\n', 'utf-8');
+
+ const ydoc = new Y.Doc();
+ const provider = new HocuspocusProvider({
+ url: `ws://127.0.0.1:${server.port}/collab`,
+ name: CONFIG_DOC_NAME_PROJECT,
+ document: ydoc,
+ connect: true,
+ });
+ const binding = bindConfigDoc(provider, 'project');
+
+ try {
+ await pollUntil(
+ () => binding.hasSynced(),
+ 10_000,
+ 100,
+ 'the project config provider to sync',
+ );
+ await awaitBacklinkIndexed(server, 'missing-history-target', `${SCOPE}/log`);
+
+ const before = await fetch(api(`/api/audit?path=${SCOPE}%2Flog.md`));
+ expect(before.status).toBe(200);
+ const beforeBody = ValidationAuditResponseSchema.parse(await before.json());
+ expect(beforeBody.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 1,
+ });
+ expect(
+ beforeBody.files.flatMap((file) => file.diagnostics).some((d) => d.code === 'dead-link'),
+ ).toBe(false);
+
+ const first = auditScope();
+
+ const patch = binding.patch({ validation: { suppressLogLinkAdvisories: false } });
+ expect(patch.ok).toBe(true);
+ await pollUntil(
+ () => /suppressLogLinkAdvisories:\s*false/.test(readFileSync(configPath, 'utf-8')),
+ 15_000,
+ 25,
+ 'the project config change to reach disk',
+ );
+
+ const firstRes = await first;
+ expect(firstRes.status).toBe(409);
+ const problem = (await firstRes.json()) as { type?: string };
+ expect(problem.type).toBe('urn:ok:error:audit-superseded');
+
+ let after: Response | undefined;
+ await pollUntil(
+ async () => {
+ const candidate = await auditScope();
+ if (candidate.status === 200) {
+ after = candidate;
+ return true;
+ }
+ expect(candidate.status).toBe(409);
+ return false;
+ },
+ 15_000,
+ 100,
+ 'the post-config audit generation to stabilize',
+ );
+ expect(after).toBeDefined();
+ const afterBody = ValidationAuditResponseSchema.parse(await after?.json());
+ expect(md010Count(afterBody)).toBeGreaterThan(0);
+ expect(afterBody.brokenLinkSuppression).toBeUndefined();
+ expect(
+ afterBody.files
+ .find((file) => file.file === `${SCOPE}/log.md`)
+ ?.diagnostics.some((diagnostic) => diagnostic.code === 'dead-link'),
+ ).toBe(true);
+ } finally {
+ binding.dispose();
+ provider.destroy();
+ ydoc.destroy();
+ rmSync(folder, { recursive: true, force: true });
+ }
+ },
+ TEST_TIMEOUT_MS,
+ );
});
diff --git a/packages/app/tests/integration/audit-link-policy.test.ts b/packages/app/tests/integration/audit-link-policy.test.ts
new file mode 100644
index 000000000..0df09c3e8
--- /dev/null
+++ b/packages/app/tests/integration/audit-link-policy.test.ts
@@ -0,0 +1,85 @@
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ValidationAuditResponseSchema } from '@inkeep/open-knowledge-core';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { awaitBacklinkIndexed, createTestServer, type TestServer } from './test-harness.ts';
+
+let server: TestServer;
+
+const BASE_CONFIG_YML = 'contentRules:\n markdownlint:\n enabled: true\n';
+const POLICY_OFF_CONFIG_YML = `${BASE_CONFIG_YML}validation:\n suppressLogLinkAdvisories: false\n`;
+const POLICY_ON_CONFIG_YML = `${BASE_CONFIG_YML}validation:\n suppressLogLinkAdvisories: true\n`;
+
+beforeAll(async () => {
+ server = await createTestServer({ seedProjectConfigYml: BASE_CONFIG_YML });
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+const SCOPE = 'audit-log-policy';
+
+const GHOST_TARGET = 'audit-log-policy-ghost';
+
+const TEST_TIMEOUT_MS = 60_000;
+
+function api(pathAndQuery: string): string {
+ return `http://127.0.0.1:${server.port}${pathAndQuery}`;
+}
+
+async function deadLinkFiles(res: Response): Promise<string[]> {
+ expect(res.status).toBe(200);
+ return ValidationAuditResponseSchema.parse(await res.json())
+ .files.filter((f) => f.diagnostics.some((d) => d.code === 'dead-link'))
+ .map((f) => f.file);
+}
+
+async function auditScope(): Promise<string[]> {
+ return deadLinkFiles(await fetch(api(`/api/audit?path=${SCOPE}`)));
+}
+
+async function auditDoc(docName: string): Promise<string[]> {
+ return deadLinkFiles(await fetch(api(`/api/audit?doc=${encodeURIComponent(docName)}`)));
+}
+
+describe('GET /api/audit under the reserved-log advisory policy', () => {
+ test(
+ 'the reserved log is suppressed by default and returns live when the policy is switched off',
+ async () => {
+ const folder = join(server.contentDir, SCOPE);
+ const configPath = join(server.contentDir, '.ok', 'config.yml');
+ const wikiLink = `# Doc\n\nSee [[${GHOST_TARGET}]].\n`;
+ mkdirSync(join(folder, 'upper'), { recursive: true });
+ writeFileSync(join(folder, 'log.md'), wikiLink, 'utf-8');
+ writeFileSync(join(folder, 'journal.md'), wikiLink, 'utf-8');
+ writeFileSync(join(folder, 'upper', 'LOG.md'), wikiLink, 'utf-8');
+ try {
+ for (const source of ['log', 'journal', 'upper/LOG']) {
+ await awaitBacklinkIndexed(server, GHOST_TARGET, `${SCOPE}/${source}`);
+ }
+
+ expect(await auditScope()).toEqual([`${SCOPE}/journal.md`, `${SCOPE}/upper/LOG.md`]);
+
+ writeFileSync(configPath, POLICY_OFF_CONFIG_YML, 'utf-8');
+ expect(await auditScope()).toEqual([
+ `${SCOPE}/journal.md`,
+ `${SCOPE}/log.md`,
+ `${SCOPE}/upper/LOG.md`,
+ ]);
+
+ writeFileSync(configPath, POLICY_ON_CONFIG_YML, 'utf-8');
+ expect(await auditScope()).toEqual([`${SCOPE}/journal.md`, `${SCOPE}/upper/LOG.md`]);
+
+ expect(await auditDoc(`${SCOPE}/log`)).toEqual([]);
+ writeFileSync(configPath, POLICY_OFF_CONFIG_YML, 'utf-8');
+ expect(await auditDoc(`${SCOPE}/log`)).toEqual([`${SCOPE}/log.md`]);
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ writeFileSync(configPath, BASE_CONFIG_YML, 'utf-8');
+ }
+ },
+ TEST_TIMEOUT_MS,
+ );
+});
diff --git a/packages/app/tests/meta/link-audit-seams.manifest.ts b/packages/app/tests/meta/link-audit-seams.manifest.ts
index 87eecd8d5..7fd1e7fe4 100644
--- a/packages/app/tests/meta/link-audit-seams.manifest.ts
+++ b/packages/app/tests/meta/link-audit-seams.manifest.ts
@@ -120,6 +120,7 @@ export const LINK_AUDIT_SEAMS: readonly LinkAuditSeam[] = [
'packages/app/src/editor/source-lint/local-target-diagnostics.ts',
'packages/app/src/editor/extensions/link-resolution.ts',
'packages/app/src/editor/validation-audit-client.ts',
+ 'packages/app/src/components/settings/ContentRulesSection.tsx',
],
tests: [
{
@@ -137,6 +138,45 @@ export const LINK_AUDIT_SEAMS: readonly LinkAuditSeam[] = [
],
requiredTiers: ['dom', 'integration', 'browser-e2e'],
},
+ {
+ id: 'reserved-log-advisory-policy',
+ priority: 'P0',
+ owner: 'core reserved identity + server link-advisory policy',
+ failureClass:
+ 'the reserved change-history log is suppressed inconsistently, case-folded onto ordinary documents, or left stale after a policy change',
+ modules: [
+ 'packages/core/src/constants/reserved-docs.ts',
+ 'packages/server/src/link-advisory-policy.ts',
+ 'packages/server/src/lint/validation-audit.ts',
+ 'packages/server/src/lint/audit-generation.ts',
+ 'packages/server/src/api-extension.ts',
+ 'packages/server/src/mcp/tools/advisory-warnings.ts',
+ 'packages/app/src/editor/validation-audit-client.ts',
+ 'packages/app/src/components/settings/ContentRulesSection.tsx',
+ ],
+ tests: [
+ { path: 'packages/core/src/constants/reserved-docs.test.ts', tier: 'unit' },
+ { path: 'packages/server/src/lint/validation-audit.test.ts', tier: 'unit' },
+ { path: 'packages/server/src/lint/audit-generation.test.ts', tier: 'unit' },
+ { path: 'packages/server/src/mcp/tools/advisory-warnings.test.ts', tier: 'unit' },
+ { path: 'packages/app/tests/integration/audit-link-policy.test.ts', tier: 'integration' },
+ { path: 'packages/server/src/api-write-link-policy.test.ts', tier: 'integration' },
+ {
+ path: 'packages/server/src/mcp/tools/write-link-suppression.test.ts',
+ tier: 'integration',
+ },
+ { path: 'packages/app/src/editor/validation-audit-client.dom.test.tsx', tier: 'dom' },
+ {
+ path: 'packages/app/src/components/settings/ContentRulesSection.dom.test.tsx',
+ tier: 'dom',
+ },
+ {
+ path: 'packages/app/tests/stress/unified-problems.e2e.ts',
+ tier: 'browser-e2e',
+ },
+ ],
+ requiredTiers: ['unit', 'dom', 'integration', 'browser-e2e'],
+ },
{
id: 'image-error-state-rendering',
priority: 'P0',
@@ -183,6 +223,23 @@ export const LINK_AUDIT_COMPOSITION_ROOTS: readonly LinkAuditCompositionRoot[] =
path: 'packages/app/src/editor/SourceEditor.tsx',
requiredText: 'createLocalTargetDiagnosticsExtension(docName)',
},
+ {
+ path: 'packages/server/src/lint/validation-audit.ts',
+ requiredText: 'shouldSuppressLogLinkAdvisories(source, suppressLogAdvisories)',
+ },
+ {
+ path: 'packages/server/src/http/lint-routes.ts',
+ requiredText: 'const linkPolicy = getLinkAdvisoryPolicy()',
+ maskingText: 'suppressLogLinkAdvisories: true',
+ },
+ {
+ path: 'packages/server/src/api-extension.ts',
+ requiredText: 'const linkPolicy = getLinkAdvisoryPolicy()',
+ },
+ {
+ path: 'packages/server/src/api-extension.ts',
+ requiredText: 'linkPolicy.suppressLogLinkAdvisories,',
+ },
{
path: 'packages/app/src/editor/TiptapEditor.tsx',
requiredText: "ext.name === 'imageReference'",
diff --git a/packages/app/tests/stress/unified-problems.e2e.ts b/packages/app/tests/stress/unified-problems.e2e.ts
index ced957e2a..10ca35e2c 100644
--- a/packages/app/tests/stress/unified-problems.e2e.ts
+++ b/packages/app/tests/stress/unified-problems.e2e.ts
@@ -7,6 +7,7 @@ import {
filterCriticalErrors,
type LogEntry,
openProjectPluginsPanel,
+ openSettingsSection,
setPluginEnabled,
test,
waitForActiveProviderSynced as waitForProvider,
@@ -406,3 +407,104 @@ test.describe('unified Problems — file-tree indicators', () => {
.toBe('warning');
});
});
+
+async function openProjectProblems(page: Page) {
+ await page.locator('#tab-problems').click();
+ const scope = page.getByTestId('panel-scope-project');
+ if ((await scope.getAttribute('data-state')) !== 'on') await scope.click();
+ await expect(page.getByTestId('problems-project-scope')).toBeVisible({ timeout: 5_000 });
+}
+
+function auditGroupsFor(page: Page, filePath: string) {
+ return page.getByText(filePath, { exact: true });
+}
+
+async function setContentRules(
+ page: Page,
+ docName: string,
+ rules: { linksSeverity?: string; ignoreLogLinks?: boolean },
+) {
+ await openSettingsSection(page, 'project-preferences', 'settings-project-preferences');
+
+ if (rules.linksSeverity !== undefined) {
+ const severity = page.getByTestId('settings-content-rules-links');
+ await expect(severity).toBeEnabled({ timeout: 15_000 });
+ await severity.click();
+ await page.getByRole('option', { name: rules.linksSeverity, exact: true }).click();
+ await expect(severity).toContainText(rules.linksSeverity);
+ }
+
+ if (rules.ignoreLogLinks !== undefined) {
+ const target = String(rules.ignoreLogLinks);
+ const toggle = page.getByTestId('settings-content-rules-log-links');
+ await expect(toggle).toBeEnabled({ timeout: 15_000 });
+ if ((await toggle.getAttribute('aria-checked')) !== target) await toggle.click();
+ await expect(toggle).toHaveAttribute('aria-checked', target);
+ }
+
+ await page.goto(`/#/${docName}`);
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+}
+
+test.describe('unified Problems — reserved-log advisory policy', () => {
+ test('the reserved-log policy clears only exact lowercase log findings, live, and never hides raw link state', async ({
+ page,
+ api,
+ }) => {
+ test.setTimeout(180_000);
+
+ const suffix = randomUUID().slice(0, 8);
+ const folder = `uv-log-${suffix}`;
+ const reservedDoc = `${folder}/history/log`;
+ const uppercaseDoc = `${folder}/shouting/LOG`;
+ const ordinaryDoc = `${folder}/notes`;
+ const ghostDoc = `ghost-${suffix}`;
+ const body = `# History\n\nEarlier this moved to [the retired entry](./${ghostDoc}.md).\n`;
+
+ for (const docName of [reservedDoc, uppercaseDoc, ordinaryDoc]) {
+ await api.createPage(`${docName}.md`);
+ await api.replaceDoc(docName, body);
+ }
+
+ await page.goto(`/#/${reservedDoc}`);
+ await waitForProvider(page);
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+
+ const unresolvedMarks = page.locator(
+ '.ProseMirror:not(.composer-prosemirror) [data-resolution-state="unresolved"]',
+ );
+ const missingPageRow = page.getByRole('button', {
+ name: new RegExp(`Missing page: .*${ghostDoc}\\. Click to create\\.`),
+ });
+
+ await expect(unresolvedMarks).toHaveCount(1, { timeout: 15_000 });
+ await page.locator('#tab-links').click();
+ await expect(missingPageRow).toBeVisible({ timeout: 15_000 });
+
+ await openProjectProblems(page);
+ await expect(auditGroupsFor(page, `${ordinaryDoc}.md`)).toBeVisible({ timeout: 30_000 });
+ await expect(auditGroupsFor(page, `${uppercaseDoc}.md`)).toBeVisible();
+ await expect(auditGroupsFor(page, `${reservedDoc}.md`)).toHaveCount(0);
+
+ await setContentRules(page, reservedDoc, { linksSeverity: 'Warning', ignoreLogLinks: false });
+
+ await openProjectProblems(page);
+ await expect
+ .poll(() => auditGroupsFor(page, `${reservedDoc}.md`).count(), { timeout: 30_000 })
+ .toBe(1);
+ await expect(auditGroupsFor(page, `${ordinaryDoc}.md`)).toBeVisible();
+ await expect(auditGroupsFor(page, `${uppercaseDoc}.md`)).toBeVisible();
+
+ await page.locator('#tab-links').click();
+ await expect(missingPageRow).toBeVisible();
+ await expect(unresolvedMarks).toHaveCount(1);
+
+ await setContentRules(page, reservedDoc, { ignoreLogLinks: true });
+ await openProjectProblems(page);
+ await expect
+ .poll(() => auditGroupsFor(page, `${reservedDoc}.md`).count(), { timeout: 30_000 })
+ .toBe(0);
+ await expect(auditGroupsFor(page, `${ordinaryDoc}.md`)).toBeVisible();
+ await expect(auditGroupsFor(page, `${uppercaseDoc}.md`)).toBeVisible();
+ });
+});
diff --git a/packages/cli/src/commands/audit.test.ts b/packages/cli/src/commands/audit.test.ts
index 5c7e989c0..4bc95b616 100644
--- a/packages/cli/src/commands/audit.test.ts
+++ b/packages/cli/src/commands/audit.test.ts
@@ -139,6 +139,33 @@ describe('runAudit', () => {
expect(out.join('\n')).toContain('Checks run: markdownlint, links.');
});
+ test('a filtered clean audit reports reserved-log suppression without exposing links', async () => {
+ stubFetch(
+ payload({
+ fileCount: 3,
+ brokenLinkSuppression: { reason: 'reserved-log-policy', count: 2 },
+ }),
+ );
+ const { io, out } = collectIo();
+
+ const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);
+
+ expect(code).toBe(0);
+ const text = out.join('\n');
+ expect(text).toContain('2 broken-link findings withheld by project policy');
+ expect(text).toContain('audit result is filtered');
+ expect(text).toContain('does NOT prove every link resolves');
+ expect(text).toContain('http://127.0.0.1:54321/api/dead-links');
+ expect(text).toContain('validation.suppressLogLinkAdvisories: false');
+ expect(text).toContain('.ok/config.yml');
+ expect(text).toContain('Settings ▸ This project ▸ Preferences ▸ Content rules');
+ expect(text).not.toContain('links({ kind: "dead" })');
+ expect(text).toContain('not as a repair queue');
+ expect(text).toContain('protect that history');
+ expect(text).not.toContain('the user');
+ expect(text).not.toContain('turning the project setting off yourself');
+ });
+
test('scopes the query to the contentDir-relative target', async () => {
const { urls } = stubFetch(payload());
const { io } = collectIo();
diff --git a/packages/cli/src/commands/audit.ts b/packages/cli/src/commands/audit.ts
index 6541fb579..94c60db70 100644
--- a/packages/cli/src/commands/audit.ts
+++ b/packages/cli/src/commands/audit.ts
@@ -6,6 +6,7 @@ import {
} from '@inkeep/open-knowledge-core';
import {
type Config,
+ formatAuditBrokenLinkSuppressionLine,
RUNTIME_VERSION,
readServerLock,
resolveContentDir,
@@ -77,10 +78,11 @@ export async function runAudit(
return 1;
}
+ const serverBaseUrl = `http://127.0.0.1:${lock.port}`;
const query = target === undefined ? '' : `?path=${encodeURIComponent(target)}`;
let res: Response;
try {
- res = await fetch(`http://127.0.0.1:${lock.port}/api/audit${query}`, {
+ res = await fetch(`${serverBaseUrl}/api/audit${query}`, {
headers: clientVersionHeaders({ kind: 'cli', runtimeVersion: RUNTIME_VERSION }),
});
} catch (e) {
@@ -111,7 +113,18 @@ export async function runAudit(
if (opts.json === true) {
io.out(JSON.stringify(result, null, 2));
} else {
- io.out(formatLintReport(toReportInput(result)));
+ const suppressionLine = result.brokenLinkSuppression
+ ? formatAuditBrokenLinkSuppressionLine(result.brokenLinkSuppression, {
+ surface: 'cli',
+ serverBaseUrl,
+ })
+ : undefined;
+ io.out(
+ [
+ formatLintReport(toReportInput(result)),
+ ...(suppressionLine === undefined ? [] : [suppressionLine]),
+ ].join('\n'),
+ );
}
const failed =
diff --git a/packages/core/src/config/field-registry.test.ts b/packages/core/src/config/field-registry.test.ts
index 78cf6d97d..2637f53d6 100644
--- a/packages/core/src/config/field-registry.test.ts
+++ b/packages/core/src/config/field-registry.test.ts
@@ -219,6 +219,7 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
'telemetry.localSink.spans.maxBytes',
'validation.fileTreeIndicators',
'validation.links',
+ 'validation.suppressLogLinkAdvisories',
]);
});
diff --git a/packages/core/src/config/schema-jsonschema.test.ts b/packages/core/src/config/schema-jsonschema.test.ts
index 74cbed590..9da2252b7 100644
--- a/packages/core/src/config/schema-jsonschema.test.ts
+++ b/packages/core/src/config/schema-jsonschema.test.ts
@@ -213,6 +213,16 @@ const FIXTURES: Fixture[] = [
input: { server: { idleShutdown: '1d' } },
shouldAccept: false,
},
+ {
+ name: 'validation.suppressLogLinkAdvisories boolean accepted',
+ input: { validation: { suppressLogLinkAdvisories: false } },
+ shouldAccept: true,
+ },
+ {
+ name: 'validation.suppressLogLinkAdvisories string rejected',
+ input: { validation: { suppressLogLinkAdvisories: 'yes' } },
+ shouldAccept: false,
+ },
];
describe('JSON Schema ↔ runtime equivalence', () => {
@@ -239,6 +249,16 @@ describe('JSON Schema ↔ runtime equivalence', () => {
});
expect(editorSchema.required ?? []).not.toContain('previewTabs');
});
+
+ test('published schema documents the reserved-log advisory policy with its default', () => {
+ const validationSchema = jsonSchema.properties?.validation as {
+ properties?: Record<string, { type?: string; default?: unknown; description?: string }>;
+ };
+ const leaf = validationSchema.properties?.suppressLogLinkAdvisories;
+ expect(leaf).toMatchObject({ type: 'boolean', default: true });
+ expect(leaf?.description).toContain('log.md');
+ expect(leaf?.description).toContain('log.mdx');
+ });
});
describe('loose-mode forgiveness', () => {
diff --git a/packages/core/src/config/schema.test.ts b/packages/core/src/config/schema.test.ts
index ad2a4c2d0..8a37351bb 100644
--- a/packages/core/src/config/schema.test.ts
+++ b/packages/core/src/config/schema.test.ts
@@ -227,6 +227,63 @@ describe('linkPreviews.enabled (external link-hover preview egress default)', ()
});
});
+describe('validation.suppressLogLinkAdvisories (reserved-log advisory policy)', () => {
+ test('defaults to enabled when the validation block is absent', () => {
+ expect(ConfigSchema.parse({}).validation.suppressLogLinkAdvisories).toBe(true);
+ });
+
+ test('defaults to enabled when validation is present but the key is absent', () => {
+ expect(
+ ConfigSchema.parse({ validation: { links: 'error' } }).validation.suppressLogLinkAdvisories,
+ ).toBe(true);
+ });
+
+ test('accepts an explicit opt-out', () => {
+ expect(
+ ConfigSchema.parse({ validation: { suppressLogLinkAdvisories: false } }).validation
+ .suppressLogLinkAdvisories,
+ ).toBe(false);
+ });
+
+ test('accepts an explicit opt-in', () => {
+ expect(
+ ConfigSchema.parse({ validation: { suppressLogLinkAdvisories: true } }).validation
+ .suppressLogLinkAdvisories,
+ ).toBe(true);
+ });
+
+ test('rejects a non-boolean value', () => {
+ expect(
+ ConfigSchema.safeParse({ validation: { suppressLogLinkAdvisories: 'yes' } }).success,
+ ).toBe(false);
+ expect(ConfigSchema.safeParse({ validation: { suppressLogLinkAdvisories: 1 } }).success).toBe(
+ false,
+ );
+ });
+
+ test('is a project-shared, live, non-agent-settable field', () => {
+ expect(
+ getLeafFieldMeta(ConfigSchema, ['validation', 'suppressLogLinkAdvisories']),
+ ).toMatchObject({
+ scope: 'project',
+ defaultScope: 'project',
+ agentSettable: false,
+ reload: 'live',
+ });
+ });
+
+ test('names the reserved logs and the stem/extension casing split in its published description', () => {
+ const description = getLeafFieldMeta(ConfigSchema, [
+ 'validation',
+ 'suppressLogLinkAdvisories',
+ ])?.description;
+ expect(description).toContain('log.md');
+ expect(description).toContain('log.mdx');
+ expect(description).toContain("the extension's case does not matter");
+ expect(description).toContain('LOG.md');
+ });
+});
+
describe('slides.enabled (Slides plugin toggle default)', () => {
test('resolves to disabled when the section is absent', () => {
expect(ConfigSchema.parse({}).slides).toEqual({ enabled: false });
diff --git a/packages/core/src/config/schema.ts b/packages/core/src/config/schema.ts
index d602aad92..2b414944e 100644
--- a/packages/core/src/config/schema.ts
+++ b/packages/core/src/config/schema.ts
@@ -1,7 +1,11 @@
import { z } from 'zod';
import { DEFAULT_ATTACHMENT_FOLDER_PATH } from '../constants/upload.ts';
import { SUPPORTED_LOCALES } from '../i18n/locales.ts';
-import { DEFAULT_LINKS_VALIDATION, LINKS_VALIDATION_SETTINGS } from '../markdown/lint/types.ts';
+import {
+ DEFAULT_LINKS_VALIDATION,
+ DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
+ LINKS_VALIDATION_SETTINGS,
+} from '../markdown/lint/types.ts';
import { BASE16_SLOT_ROLES, BASE16_SLOTS } from '../theme/base16.ts';
import { THEME_ID_PATTERN, THEME_PLUGIN_IDS } from '../theme/theme-plugins.ts';
import {
@@ -990,8 +994,23 @@ export const ConfigSchema = z.looseObject({
'Whether the file tree tints and badges files that have validation problems.',
})
.default(true),
+ suppressLogLinkAdvisories: z
+ .boolean()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ reload: 'live',
+ defaultScope: 'project',
+ description:
+ "Whether unresolved links in the reserved change-history documents (lowercase-stemmed log.md / log.mdx at any depth, where the extension's case does not matter and the stem's does) are omitted from broken-link advisories: the Problems panel, file-tree indicators, source diagnostics, audits, and agent write/edit results. Default true. Raw link views still show them, and LOG.md, Log.md, and every other stem spelling are ordinary documents.",
+ })
+ .default(DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES),
})
- .default({ links: DEFAULT_LINKS_VALIDATION, fileTreeIndicators: true }),
+ .default({
+ links: DEFAULT_LINKS_VALIDATION,
+ fileTreeIndicators: true,
+ suppressLogLinkAdvisories: DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
+ }),
linkPreviews: z
.looseObject({
enabled: z
diff --git a/packages/core/src/constants/reserved-docs.test.ts b/packages/core/src/constants/reserved-docs.test.ts
new file mode 100644
index 000000000..fa27655cb
--- /dev/null
+++ b/packages/core/src/constants/reserved-docs.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, test } from 'vitest';
+import { docStem, isReservedLogDoc, RESERVED_LOG_STEM } from './reserved-docs.ts';
+
+describe('isReservedLogDoc', () => {
+ test('matches the exact lowercase reserved log at the root', () => {
+ expect(isReservedLogDoc('log')).toBe(true);
+ expect(isReservedLogDoc('log.md')).toBe(true);
+ expect(isReservedLogDoc('log.mdx')).toBe(true);
+ });
+
+ test('matches the reserved log at any directory depth', () => {
+ expect(isReservedLogDoc('notes/log')).toBe(true);
+ expect(isReservedLogDoc('notes/log.md')).toBe(true);
+ expect(isReservedLogDoc('a/b/c/log.mdx')).toBe(true);
+ });
+
+ test('does not match uppercase or mixed-case STEM spellings', () => {
+ for (const name of ['LOG', 'LOG.md', 'Log.md', 'lOg.mdx', 'notes/LOG.md', 'notes/Log']) {
+ expect(isReservedLogDoc(name)).toBe(false);
+ }
+ });
+
+ test('matches a mixed-case EXTENSION, which the doc-file gate also folds', () => {
+ for (const name of ['log.MD', 'log.Md', 'log.MDX', 'notes/log.MDX']) {
+ expect(isReservedLogDoc(name)).toBe(true);
+ }
+ });
+
+ test('does not match a stem that merely contains the reserved word', () => {
+ for (const name of ['catalog.md', 'log-2026.md', 'changelog', 'notes/catalog.mdx']) {
+ expect(isReservedLogDoc(name)).toBe(false);
+ }
+ });
+
+ test('does not match a non-Markdown file named log', () => {
+ for (const name of ['log.txt', 'log.json', 'notes/log.png']) {
+ expect(isReservedLogDoc(name)).toBe(false);
+ }
+ });
+
+ test('does not match a folder segment named log', () => {
+ expect(isReservedLogDoc('log/entries.md')).toBe(false);
+ });
+});
+
+describe('docStem', () => {
+ test('strips only supported doc extensions', () => {
+ expect(docStem('log.md')).toBe('log');
+ expect(docStem('log.mdx')).toBe('log');
+ expect(docStem('log.txt')).toBe('log.txt');
+ });
+
+ test('reads the final path segment', () => {
+ expect(docStem('a/b/notes.md')).toBe('notes');
+ expect(docStem('a.md/b')).toBe('b');
+ });
+
+ test('leaves a dotfile intact', () => {
+ expect(docStem('.md')).toBe('.md');
+ });
+
+ test('strips an uppercase spelling of a supported extension', () => {
+ expect(docStem('LOG.MD')).toBe('LOG');
+ });
+});
+
+test('the reserved stem is the lowercase spelling the format recognizes', () => {
+ expect(RESERVED_LOG_STEM).toBe('log');
+});
diff --git a/packages/core/src/constants/reserved-docs.ts b/packages/core/src/constants/reserved-docs.ts
new file mode 100644
index 000000000..6f13097c7
--- /dev/null
+++ b/packages/core/src/constants/reserved-docs.ts
@@ -0,0 +1,15 @@
+import { SUPPORTED_DOC_EXTENSIONS } from './doc-extensions.ts';
+
+export function docStem(docName: string): string {
+ const base = docName.slice(docName.lastIndexOf('/') + 1);
+ const dot = base.lastIndexOf('.');
+ if (dot <= 0) return base;
+ const ext = base.slice(dot).toLowerCase();
+ return (SUPPORTED_DOC_EXTENSIONS as readonly string[]).includes(ext) ? base.slice(0, dot) : base;
+}
+
+export const RESERVED_LOG_STEM = 'log';
+
+export function isReservedLogDoc(docName: string): boolean {
+ return docStem(docName) === RESERVED_LOG_STEM;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 36fe0949e..27f6479df 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -506,6 +506,7 @@ export {
type PreviewThemeToken,
} from './constants/preview-theme-tokens.ts';
export { PRODUCT_NAME } from './constants/product.ts';
+export { isReservedLogDoc } from './constants/reserved-docs.ts';
export { DEFAULT_SERVER_HOST } from './constants/server.ts';
export {
AGENTS_SKILLS_ROOT,
@@ -865,6 +866,7 @@ export {
DEFAULT_LINTER_CONFIG,
DEFAULT_MARKDOWNLINT_CONFIG,
DEFAULT_SCHEMA_DIALECT,
+ DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
deriveValidationRunSources,
displayCategoryForRule,
emptyFrontmatterSchemaText,
@@ -1131,11 +1133,15 @@ export {
type BatchEntryError,
BatchEntryErrorSchema,
BROKEN_LINK_REASONS,
+ BROKEN_LINK_SUPPRESSION_REASONS,
type BranchInfoResponse,
BranchInfoResponseSchema,
type BrokenLink,
type BrokenLinkReason,
BrokenLinkSchema,
+ type BrokenLinkSuppression,
+ type BrokenLinkSuppressionReason,
+ BrokenLinkSuppressionSchema,
BrokenLinksSchema,
type CheckoutFailureReason,
CheckoutFailureReasonSchema,
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index 75723530c..c93dd2f8c 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -1,6 +1,9 @@
import { z } from 'zod';
import { agentIdentityFields, safeDocNameField, summaryField } from '../../schemas/api/_shared.ts';
-import { LocalTargetDiagnosticEvidenceSchema } from '../../schemas/api/agent-write.ts';
+import {
+ BrokenLinkSuppressionSchema,
+ LocalTargetDiagnosticEvidenceSchema,
+} from '../../schemas/api/agent-write.ts';
import { DEFAULT_MARKDOWNLINT_CONFIG } from './default-config.ts';
import type { OkfRuleId } from './okf-rule-meta.ts';
import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';
@@ -201,6 +204,7 @@ export const ValidationAuditResponseSchema = z.object({
warningCount: z.number(),
warnings: z.array(z.string()),
ran: RunSourcesSchema,
+ brokenLinkSuppression: BrokenLinkSuppressionSchema.optional(),
});
export type ValidationDocResult = z.infer<typeof ValidationDocResultSchema>;
@@ -223,6 +227,7 @@ export const ValidationAuditCountsResponseSchema = z.object({
errorCount: z.number().int().nonnegative(),
warningCount: z.number().int().nonnegative(),
warnings: z.array(z.string()),
+ brokenLinkSuppression: BrokenLinkSuppressionSchema.optional(),
});
export type ValidationDocCounts = z.infer<typeof ValidationDocCountsSchema>;
diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.ts
index 31c3b366c..a205a28ce 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -228,6 +228,7 @@ export type {
} from './types.ts';
export {
DEFAULT_LINKS_VALIDATION,
+ DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
isFrontmatterScoped,
LINKS_VALIDATION_SETTINGS,
LINT_PLUGIN_IDS,
diff --git a/packages/core/src/markdown/lint/rules/reserved-casing.ts b/packages/core/src/markdown/lint/rules/reserved-casing.ts
index 89ef3e4a9..395e0bf75 100644
--- a/packages/core/src/markdown/lint/rules/reserved-casing.ts
+++ b/packages/core/src/markdown/lint/rules/reserved-casing.ts
@@ -1,20 +1,12 @@
-import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';
+import { docStem, RESERVED_LOG_STEM } from '../../../constants/reserved-docs.ts';
import { defineOkfRule } from '../okf-runner.ts';
-const RESERVED_STEMS = ['index', 'log'] as const;
-
-function stemOf(docName: string): string {
- const base = docName.slice(docName.lastIndexOf('/') + 1);
- const dot = base.lastIndexOf('.');
- if (dot <= 0) return base;
- const ext = base.slice(dot).toLowerCase();
- return (SUPPORTED_DOC_EXTENSIONS as readonly string[]).includes(ext) ? base.slice(0, dot) : base;
-}
+const RESERVED_STEMS = ['index', RESERVED_LOG_STEM] as const;
export const reservedCasing = defineOkfRule('reserved-casing', (_tree, file) => {
const docName = file.data.okfDocName;
if (docName === undefined) return;
- const stem = stemOf(docName);
+ const stem = docStem(docName);
const lower = stem.toLowerCase();
if (!RESERVED_STEMS.includes(lower as (typeof RESERVED_STEMS)[number])) return;
if (stem === lower) return;
diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.ts
index 2cffecae6..204a8472c 100644
--- a/packages/core/src/markdown/lint/types.ts
+++ b/packages/core/src/markdown/lint/types.ts
@@ -76,6 +76,8 @@ export const LINKS_VALIDATION_SETTINGS = ['off', 'warning', 'error'] as const;
export type LinksValidationSetting = (typeof LINKS_VALIDATION_SETTINGS)[number];
export const DEFAULT_LINKS_VALIDATION: LinksValidationSetting = 'warning';
+export const DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES = true;
+
type MarkdownlintRuleParams = Record<string, unknown>;
export const MARKDOWNLINT_RULE_SEVERITIES = ['error', 'warning'] as const;
diff --git a/packages/core/src/schemas/api/agent-write.test.ts b/packages/core/src/schemas/api/agent-write.test.ts
index 8e49b8e89..5ae869906 100644
--- a/packages/core/src/schemas/api/agent-write.test.ts
+++ b/packages/core/src/schemas/api/agent-write.test.ts
@@ -4,10 +4,13 @@ import {
AgentPatchSuccessSchema,
AgentUndoRequestSchema,
AgentUndoSuccessSchema,
+ AgentWriteBatchResultSchema,
AgentWriteMdRequestSchema,
AgentWriteMdSuccessSchema,
AgentWriteRequestSchema,
AgentWriteSuccessSchema,
+ BrokenLinkSuppressionSchema,
+ FrontmatterPatchSuccessSchema,
LintViolationWarningSchema,
LocalTargetDiagnosticEvidenceSchema,
ProblemTypeSchema,
@@ -435,6 +438,116 @@ describe('AgentWriteMdSuccessSchema', () => {
});
});
+describe('BrokenLinkSuppressionSchema (reserved-log advisory policy)', () => {
+ test('parses the reason token and a positive omitted count', () => {
+ const result = BrokenLinkSuppressionSchema.safeParse({
+ reason: 'reserved-log-policy',
+ count: 3,
+ });
+ expect(result.success).toBe(true);
+ });
+
+ test('rejects a zero or negative count (present only when entries were omitted)', () => {
+ expect(
+ BrokenLinkSuppressionSchema.safeParse({ reason: 'reserved-log-policy', count: 0 }).success,
+ ).toBe(false);
+ expect(
+ BrokenLinkSuppressionSchema.safeParse({ reason: 'reserved-log-policy', count: -1 }).success,
+ ).toBe(false);
+ });
+
+ test('rejects a non-integer count', () => {
+ expect(
+ BrokenLinkSuppressionSchema.safeParse({ reason: 'reserved-log-policy', count: 1.5 }).success,
+ ).toBe(false);
+ });
+
+ test('accepts an unknown reason token so a newer policy still qualifies the empty list', () => {
+ const parsed = BrokenLinkSuppressionSchema.safeParse({
+ reason: 'some-future-policy',
+ count: 1,
+ });
+ expect(parsed.success).toBe(true);
+ expect(parsed.success && parsed.data.reason).toBe('some-future-policy');
+ });
+
+ test('rejects an empty reason token', () => {
+ expect(BrokenLinkSuppressionSchema.safeParse({ reason: '', count: 1 }).success).toBe(false);
+ });
+
+ test('carries no href, path, or content channel', () => {
+ const parsed = BrokenLinkSuppressionSchema.parse({
+ reason: 'reserved-log-policy',
+ count: 2,
+ });
+ expect(Object.keys(parsed).sort()).toEqual(['count', 'reason']);
+ });
+});
+
+describe('brokenLinkSuppression on write/edit success bodies', () => {
+ const suppression = { reason: 'reserved-log-policy', count: 2 } as const;
+
+ test('every write/edit success family accepts the additive suppression field', () => {
+ expect(
+ AgentWriteMdSuccessSchema.safeParse({
+ timestamp: '2026-04-30T00:00:00.000Z',
+ subscriberCount: 0,
+ systemSubscriberCount: 0,
+ brokenLinks: [],
+ brokenLinkSuppression: suppression,
+ }).success,
+ ).toBe(true);
+ expect(
+ AgentPatchSuccessSchema.safeParse({
+ timestamp: '2026-04-30T00:00:00.000Z',
+ subscriberCount: 0,
+ systemSubscriberCount: 0,
+ brokenLinks: [],
+ brokenLinkSuppression: suppression,
+ }).success,
+ ).toBe(true);
+ expect(
+ FrontmatterPatchSuccessSchema.safeParse({
+ timestamp: '2026-04-30T00:00:00.000Z',
+ subscriberCount: 0,
+ systemSubscriberCount: 0,
+ appliedKeys: ['type'],
+ brokenLinks: [],
+ brokenLinkSuppression: suppression,
+ }).success,
+ ).toBe(true);
+ expect(
+ AgentWriteBatchResultSchema.safeParse({
+ status: 'written',
+ docName: 'notes/log',
+ brokenLinks: [],
+ brokenLinkSuppression: suppression,
+ }).success,
+ ).toBe(true);
+ });
+
+ test('the field stays optional so a no-suppression response omits it', () => {
+ const result = AgentWriteMdSuccessSchema.safeParse({
+ timestamp: '2026-04-30T00:00:00.000Z',
+ subscriberCount: 0,
+ systemSubscriberCount: 0,
+ brokenLinks: [],
+ });
+ expect(result.success && result.data.brokenLinkSuppression).toBeUndefined();
+ });
+
+ test('a malformed suppression field is rejected rather than passed through', () => {
+ const result = AgentWriteMdSuccessSchema.safeParse({
+ timestamp: '2026-04-30T00:00:00.000Z',
+ subscriberCount: 0,
+ systemSubscriberCount: 0,
+ brokenLinks: [],
+ brokenLinkSuppression: { reason: 'reserved-log-policy', count: 0 },
+ });
+ expect(result.success).toBe(false);
+ });
+});
+
describe('LintViolationWarningSchema', () => {
test('round-trips a links violation carrying local-target evidence', () => {
const warning = {
diff --git a/packages/core/src/schemas/api/agent-write.ts b/packages/core/src/schemas/api/agent-write.ts
index b3a49bd37..649054b26 100644
--- a/packages/core/src/schemas/api/agent-write.ts
+++ b/packages/core/src/schemas/api/agent-write.ts
@@ -211,6 +211,17 @@ export type BrokenLink = z.infer<typeof BrokenLinkSchema>;
export const BrokenLinksSchema = z.array(BrokenLinkSchema);
+export const BROKEN_LINK_SUPPRESSION_REASONS = ['reserved-log-policy'] as const;
+export type BrokenLinkSuppressionReason = (typeof BROKEN_LINK_SUPPRESSION_REASONS)[number];
+
+export const BrokenLinkSuppressionSchema = z
+ .object({
+ reason: z.string().min(1),
+ count: z.number().int().positive(),
+ })
+ .loose() satisfies StandardSchemaV1;
+export type BrokenLinkSuppression = z.infer<typeof BrokenLinkSuppressionSchema>;
+
export const AgentWriteSuccessSchema = z
.object({
timestamp: z.string().min(1),
@@ -229,6 +240,7 @@ export const AgentWriteMdSuccessSchema = z
summary: SummaryResponseFieldSchema.optional(),
warnings: AdvisoryWarningsSchema.optional(),
brokenLinks: BrokenLinksSchema,
+ brokenLinkSuppression: BrokenLinkSuppressionSchema.optional(),
})
.loose() satisfies StandardSchemaV1;
export type AgentWriteMdSuccess = z.infer<typeof AgentWriteMdSuccessSchema>;
@@ -241,6 +253,7 @@ export const AgentPatchSuccessSchema = z
summary: SummaryResponseFieldSchema.optional(),
warnings: AdvisoryWarningsSchema.optional(),
brokenLinks: BrokenLinksSchema,
+ brokenLinkSuppression: BrokenLinkSuppressionSchema.optional(),
})
.loose() satisfies StandardSchemaV1;
export type AgentPatchSuccess = z.infer<typeof AgentPatchSuccessSchema>;
@@ -292,6 +305,7 @@ export const AgentWriteBatchResultSchema = z.discriminatedUnion('status', [
summary: SummaryResponseFieldSchema.optional(),
warnings: AdvisoryWarningsSchema.optional(),
brokenLinks: BrokenLinksSchema,
+ brokenLinkSuppression: BrokenLinkSuppressionSchema.optional(),
})
.loose(),
z
@@ -334,6 +348,7 @@ export const FrontmatterPatchSuccessSchema = z
summary: SummaryResponseFieldSchema.optional(),
warnings: AdvisoryWarningsSchema.optional(),
brokenLinks: BrokenLinksSchema,
+ brokenLinkSuppression: BrokenLinkSuppressionSchema.optional(),
})
.loose() satisfies StandardSchemaV1;
export type FrontmatterPatchSuccess = z.infer<typeof FrontmatterPatchSuccessSchema>;
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.md
index 0a5c78f47..269599eff 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
@@ -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.
diff --git a/packages/server/assets/skills/packs/knowledge-base/SKILL.md b/packages/server/assets/skills/packs/knowledge-base/SKILL.md
index a34c56913..8dcad5b2f 100644
--- a/packages/server/assets/skills/packs/knowledge-base/SKILL.md
+++ b/packages/server/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
diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.md
index d789159b0..ca4ef8bb8 100644
--- a/packages/server/assets/skills/project/SKILL.md
+++ b/packages/server/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
diff --git a/packages/server/assets/skills/project/references/linking.md b/packages/server/assets/skills/project/references/linking.md
index fde832dd1..4cb2bbc3a 100644
--- a/packages/server/assets/skills/project/references/linking.md
+++ b/packages/server/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.
diff --git a/packages/server/src/api-extension.test-helper.ts b/packages/server/src/api-extension.test-helper.ts
index 23dd34df3..b57f26cdd 100644
--- a/packages/server/src/api-extension.test-helper.ts
+++ b/packages/server/src/api-extension.test-helper.ts
@@ -1,4 +1,8 @@
import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+ DEFAULT_LINKS_VALIDATION,
+ DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
+} from '@inkeep/open-knowledge-core';
import type { ApiExtensionOptions } from './api-extension.ts';
import { createApiExtension as createApiExtensionBase } from './api-extension.ts';
import type { BacklinkIndex } from './backlink-index.ts';
@@ -7,6 +11,7 @@ import type {
DerivedDocumentIndexMutation,
} from './derived-document-index.ts';
import { DocumentDurabilityState } from './document-durability-state.ts';
+import type { LinkAdvisoryPolicy } from './link-advisory-policy.ts';
import type { TagIndex } from './tag-index.ts';
export * from './api-extension.ts';
@@ -219,15 +224,36 @@ function createLegacyDerivedIndexPort(
}
export function createApiExtension(
- options: Omit<ApiExtensionOptions, 'durabilityState' | 'derivedDocumentIndex' | 'signalChannel'> &
+ options: Omit<
+ ApiExtensionOptions,
+ | 'durabilityState'
+ | 'derivedDocumentIndex'
+ | 'signalChannel'
+ | 'getProjectConfigEpoch'
+ | 'getLinkAdvisoryPolicy'
+ > &
LegacyIndexOptions & {
derivedDocumentIndex?: DerivedDocumentIndexApiPort;
signalChannel?: LegacySignalChannel;
+ getProjectConfigEpoch?: () => number;
+ getLinkAdvisoryPolicy?: () => LinkAdvisoryPolicy;
},
): ReturnType<typeof createApiExtensionBase> {
- const { backlinkIndex, tagIndex, derivedDocumentIndex, ...apiOptions } = options;
+ const {
+ backlinkIndex,
+ tagIndex,
+ derivedDocumentIndex,
+ getProjectConfigEpoch = () => 0,
+ getLinkAdvisoryPolicy = () => ({
+ links: DEFAULT_LINKS_VALIDATION,
+ suppressLogLinkAdvisories: DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
+ }),
+ ...apiOptions
+ } = options;
const extension = createApiExtensionBase({
...apiOptions,
+ getProjectConfigEpoch,
+ getLinkAdvisoryPolicy,
durabilityState: new DocumentDurabilityState(),
derivedDocumentIndex:
derivedDocumentIndex ??
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 3c68c3c74..6b7fa4a60 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -43,7 +43,6 @@ import {
colorFromSeed,
composeWithDerivedFrontmatter,
createCodeFenceTracker,
- DEFAULT_LINKS_VALIDATION,
DEFAULT_LINTER_CONFIG,
type DiskEditReconciledWarning,
type DocumentListEntry,
@@ -57,7 +56,6 @@ import {
type InlineAssetMediaKind,
isManagedArtifactDocName,
LEGACY_SKILL_STORE_ROOT,
- type LinksValidationSetting,
LintConfigResponseSchema,
type LinterConfig,
LintFixRequestSchema,
@@ -178,6 +176,7 @@ import { createSkillsTrackingRoutes } from './http/skills-tracking-routes.ts';
import { findHubCandidates } from './hub-candidates.ts';
import { recordSkillInstall, removeSkillInstall } from './installed-skills-marker.ts';
import { collectDocFiles, lintAndFixSource } from './lint/audit.ts';
+import { composeAuditGeneration } from './lint/audit-generation.ts';
import {
createEmptyFrontmatterSchemaFile,
deleteFrontmatterSchemaFile,
@@ -331,6 +330,11 @@ import {
isHostAdmitted,
isPeerAdmitted,
} from './ingress-policy.ts';
+import {
+ type LinkAdvisoryPolicy,
+ projectWriteAdvisoryLinks,
+ type WriteLinkAdvisoryProjection,
+} from './link-advisory-policy.ts';
import type { GuardedFetch } from './link-preview/metadata.ts';
import {
checkLocalOpSecurity as checkLocalOpSecurityBase,
@@ -1381,7 +1385,8 @@ export interface ApiExtensionOptions {
embeddingsSecretsFile?: string;
readSemanticProviderConfig?: () => ResolvedSemanticConfig;
getLinterBaseConfig?: () => LinterConfig;
- getLinksValidationSetting?: () => LinksValidationSetting;
+ getLinkAdvisoryPolicy: () => LinkAdvisoryPolicy;
+ getProjectConfigEpoch: () => number;
}
export function extractHeadings(content: string): HeadingEntry[] {
@@ -1494,7 +1499,8 @@ export function createApiExtension(
embeddingsSecretsFile,
readSemanticProviderConfig,
getLinterBaseConfig,
- getLinksValidationSetting,
+ getLinkAdvisoryPolicy,
+ getProjectConfigEpoch,
ephemeral = false,
linkPreviewFetch,
getLinkPreviewsEnabled,
@@ -3477,6 +3483,7 @@ export function createApiExtension(
AgentWriteMdRequestSchema,
async (_req, res, body) => {
try {
+ const linkPolicy = getLinkAdvisoryPolicy();
const position = body.position ?? 'append';
const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'agent-write-md');
if (effectiveDocName === null) return;
@@ -3643,12 +3650,16 @@ export function createApiExtension(
const admittedForLinks = await collectAdmittedDocNames();
admittedForLinks.add(resolvedDocName);
- const brokenLinks = computeWriteAdvisoryLinks(
- writtenSource,
+ const linkAdvisory = projectWriteAdvisoryLinks(
+ computeWriteAdvisoryLinks(
+ writtenSource,
+ resolvedDocName,
+ admittedForLinks,
+ createLinkedFileExists(),
+ createLinkedFolderExists(),
+ ),
resolvedDocName,
- admittedForLinks,
- createLinkedFileExists(),
- createLinkedFolderExists(),
+ linkPolicy.suppressLogLinkAdvisories,
);
const subscriberCount = getSubscriberCount(resolvedDocName);
@@ -3671,6 +3682,7 @@ export function createApiExtension(
...(await computeLintViolations(
session.dc.document.getText('source').toString(),
resolvedDocName,
+ linkPolicy,
)),
];
successResponse(
@@ -3684,7 +3696,7 @@ export function createApiExtension(
...(hints ? { hints } : {}),
...(summaryResponse ? { summary: summaryResponse } : {}),
...(writeMdAdvisories.length > 0 ? { warnings: writeMdAdvisories } : {}),
- brokenLinks,
+ ...linkAdvisory,
},
{ handler: 'agent-write-md' },
);
@@ -3721,6 +3733,7 @@ export function createApiExtension(
AgentWriteBatchRequestSchema,
async (_req, res, body) => {
try {
+ const linkPolicy = getLinkAdvisoryPolicy();
const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
extractAgentIdentity(body);
@@ -3731,12 +3744,11 @@ export function createApiExtension(
docName: string;
error: BatchEntryError;
}
- interface BatchWrittenResult {
+ interface BatchWrittenResult extends WriteLinkAdvisoryProjection {
status: 'written';
docName: string;
summary?: SummaryResponse;
warnings?: AdvisoryWarning[];
- brokenLinks: ReturnType<typeof computeWriteAdvisoryLinks>;
}
type BatchResult = BatchWrittenResult | BatchErrorResult;
@@ -3977,19 +3989,22 @@ export function createApiExtension(
}
const writtenSource = p.session.dc.document.getText('source').toString();
registerWrittenDocInFileIndex(p.docName, writtenSource);
- const brokenLinks = computeWriteAdvisoryLinks(
- writtenSource,
- p.docName,
- admittedForLinks,
- linkedFileExists,
- linkedFolderExists,
- );
results[p.index] = {
status: 'written',
docName: p.docName,
...(p.summaryResponse ? { summary: p.summaryResponse } : {}),
...(p.warnings.length > 0 ? { warnings: p.warnings } : {}),
- brokenLinks,
+ ...projectWriteAdvisoryLinks(
+ computeWriteAdvisoryLinks(
+ writtenSource,
+ p.docName,
+ admittedForLinks,
+ linkedFileExists,
+ linkedFolderExists,
+ ),
+ p.docName,
+ linkPolicy.suppressLogLinkAdvisories,
+ ),
};
lastWrittenDoc = p.docName;
}
@@ -4044,6 +4059,7 @@ export function createApiExtension(
FrontmatterPatchRequestSchema,
async (_req, res, body) => {
try {
+ const linkPolicy = getLinkAdvisoryPolicy();
const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'frontmatter-patch');
if (effectiveDocName === null) return;
const resolvedDocName = resolveAlias(effectiveDocName);
@@ -4264,11 +4280,15 @@ export function createApiExtension(
const admittedForLinks = await collectAdmittedDocNames();
admittedForLinks.add(resolvedDocName);
- const brokenLinks = computeWriteAdvisoryLinks(
- session.dc.document.getText('source').toString(),
+ const linkAdvisory = projectWriteAdvisoryLinks(
+ computeWriteAdvisoryLinks(
+ session.dc.document.getText('source').toString(),
+ resolvedDocName,
+ admittedForLinks,
+ createLinkedFileExists(),
+ ),
resolvedDocName,
- admittedForLinks,
- createLinkedFileExists(),
+ linkPolicy.suppressLogLinkAdvisories,
);
successResponse(
@@ -4282,7 +4302,7 @@ export function createApiExtension(
appliedKeys,
...(summaryResponse ? { summary: summaryResponse } : {}),
...(fmWarning ? { warnings: [fmWarning] } : {}),
- brokenLinks,
+ ...linkAdvisory,
},
{ handler: 'frontmatter-patch' },
);
@@ -4311,6 +4331,7 @@ export function createApiExtension(
AgentPatchRequestSchema,
async (_req, res, body) => {
try {
+ const linkPolicy = getLinkAdvisoryPolicy();
const { find, replace, offset } = body;
const effectivePatchDocName = requireNonEmptyDocName(body.docName, res, 'agent-patch');
if (effectivePatchDocName === null) return;
@@ -4585,11 +4606,15 @@ export function createApiExtension(
const admittedForLinks = await collectAdmittedDocNames();
admittedForLinks.add(docName);
- const brokenLinks = computeWriteAdvisoryLinks(
- patchedSource,
+ const linkAdvisory = projectWriteAdvisoryLinks(
+ computeWriteAdvisoryLinks(
+ patchedSource,
+ docName,
+ admittedForLinks,
+ createLinkedFileExists(),
+ ),
docName,
- admittedForLinks,
- createLinkedFileExists(),
+ linkPolicy.suppressLogLinkAdvisories,
);
const patchWarning = buildReconcileWarning(patchReconcile);
@@ -4602,6 +4627,7 @@ export function createApiExtension(
...(await computeLintViolations(
session.dc.document.getText('source').toString(),
docName,
+ linkPolicy,
)),
];
successResponse(
@@ -4614,7 +4640,7 @@ export function createApiExtension(
systemSubscriberCount,
...(summaryResponse ? { summary: summaryResponse } : {}),
...(patchAdvisories.length > 0 ? { warnings: patchAdvisories } : {}),
- brokenLinks,
+ ...linkAdvisory,
},
{ handler: 'agent-patch' },
);
@@ -6349,15 +6375,20 @@ export function createApiExtension(
signalChannel?.('lint-config');
}
- const readAuditGeneration = (): string =>
- `${lintConfigEpoch} ${durabilityState.getActiveBranch()} ${
- derivedDocumentIndex?.readLocalTargetGeneration?.() ?? 0
- }`;
+ const readAuditGeneration = (): string => {
+ return composeAuditGeneration({
+ lintConfigEpoch,
+ projectConfigEpoch: getProjectConfigEpoch(),
+ activeBranch: durabilityState.getActiveBranch(),
+ localTargetGeneration: derivedDocumentIndex?.readLocalTargetGeneration?.() ?? 0,
+ });
+ };
const LINT_VIOLATION_CAP = 10;
async function computeLintViolations(
source: string,
docName: string,
+ linkPolicy: LinkAdvisoryPolicy,
): Promise<LintViolationWarning[]> {
const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
try {
@@ -6369,15 +6400,14 @@ export function createApiExtension(
const lintFindings = await lintDocument(source, effective, docName);
let linkFindings: ValidationDiagnostic[] = [];
- const linksSetting = getLinksValidationSetting?.() ?? DEFAULT_LINKS_VALIDATION;
- if (derivedDocumentIndex && linksSetting !== 'off' && !isLinkIndexExcludedDoc(docName)) {
+ if (derivedDocumentIndex && linkPolicy.links !== 'off' && !isLinkIndexExcludedDoc(docName)) {
await recordDerivedLinkRewriteBestEffort(docName, source, 'lint-validation');
const linksValidator = createProjectValidators({
projectDir: projectDir ?? contentDir,
contentDir,
baseConfig: base,
derivedDocumentIndex,
- linksValidation: linksSetting,
+ linkPolicy,
admittedDocNames: collectAdmittedDocNames,
docFilePathFor: (d) => resolveDocFilePath(contentDir, d),
}).find((validator) => validator.id === 'links');
@@ -6917,7 +6947,7 @@ export function createApiExtension(
isValidRelativeContentPath,
streamShowAllEntries,
getLinterBaseConfig,
- getLinksValidationSetting,
+ getLinkAdvisoryPolicy,
derivedDocumentIndex,
collectAdmittedDocNames,
unmatchedGlobProblems,
diff --git a/packages/server/src/api-write-link-policy.test.ts b/packages/server/src/api-write-link-policy.test.ts
new file mode 100644
index 000000000..6ce91cee3
--- /dev/null
+++ b/packages/server/src/api-write-link-policy.test.ts
@@ -0,0 +1,297 @@
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { Hocuspocus } from '@hocuspocus/server';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import {
+ AGENT_WRITE_ORIGIN,
+ AgentSessionManager,
+ applyAgentMarkdownWrite,
+} from './agent-sessions.ts';
+import { createApiExtension } from './api-extension.test-helper.ts';
+
+interface CapturedResponse {
+ status: number;
+ body: string;
+}
+
+interface LinkAdvisoryBody {
+ brokenLinks?: { href: string }[];
+ brokenLinkSuppression?: { reason: string; count: number };
+}
+
+function makeJsonPostReq(url: string, body: unknown): IncomingMessage {
+ const readable = Readable.from(Buffer.from(JSON.stringify(body))) as unknown as IncomingMessage;
+ readable.method = 'POST';
+ readable.url = url;
+ readable.headers = { host: 'localhost', 'content-type': 'application/json' };
+ return readable;
+}
+
+function makeRes(): { res: ServerResponse; captured: CapturedResponse } {
+ const captured: CapturedResponse = { status: 0, body: '' };
+ const res = {
+ writeHead(status: number) {
+ captured.status = status;
+ },
+ end(body?: string) {
+ captured.body = body ?? '';
+ },
+ } as unknown as ServerResponse;
+ return { res, captured };
+}
+
+const TWO_BROKEN_FORMS = '# Log\n\nSee [[ghost-doc]].\n\n![missing](./ghost-image.png)\n';
+
+let projectDir: string;
+let contentDir: string;
+let hocuspocus: Hocuspocus;
+let sessionManager: AgentSessionManager;
+
+beforeEach(() => {
+ projectDir = mkdtempSync(join(tmpdir(), 'ok-write-link-policy-'));
+ contentDir = join(projectDir, 'content');
+ mkdirSync(contentDir, { recursive: true });
+ hocuspocus = new Hocuspocus({ quiet: true });
+ sessionManager = new AgentSessionManager(hocuspocus);
+});
+
+afterEach(async () => {
+ await sessionManager.closeAll();
+ rmSync(projectDir, { recursive: true, force: true });
+});
+
+async function post(
+ url: string,
+ body: unknown,
+ options: { suppressLogLinkAdvisories?: boolean } = {},
+): Promise<CapturedResponse> {
+ const ext = createApiExtension({
+ hocuspocus,
+ sessionManager,
+ contentDir,
+ getFileIndex: () => new Map(),
+ ...(options.suppressLogLinkAdvisories === undefined
+ ? {}
+ : {
+ getLinkAdvisoryPolicy: () => ({
+ links: 'warning' as const,
+ suppressLogLinkAdvisories: options.suppressLogLinkAdvisories as boolean,
+ }),
+ }),
+ });
+ const req = makeJsonPostReq(url, body);
+ const { res, captured } = makeRes();
+ await (
+ ext as {
+ onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
+ }
+ ).onRequest({ request: req, response: res });
+ return captured;
+}
+
+async function writeMd(
+ docName: string,
+ markdown: string,
+ options?: { suppressLogLinkAdvisories?: boolean },
+): Promise<LinkAdvisoryBody> {
+ const response = await post(
+ '/api/agent-write-md',
+ { docName, markdown, position: 'replace', agentId: 'claude-1', agentName: 'Claude' },
+ options,
+ );
+ expect(response.status).toBe(200);
+ return JSON.parse(response.body) as LinkAdvisoryBody;
+}
+
+async function seed(docName: string, markdown: string): Promise<void> {
+ const session = await sessionManager.getSession(docName);
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, markdown, 'replace');
+ }, AGENT_WRITE_ORIGIN);
+}
+
+describe('write-time broken-link advisories under the reserved-log policy', () => {
+ test('a reserved log withholds every detected link and reports how many were omitted', async () => {
+ const body = await writeMd('log', TWO_BROKEN_FORMS);
+
+ expect(body.brokenLinks).toEqual([]);
+ expect(body.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
+ });
+
+ test('an ordinary document keeps its repair candidates and carries no suppression', async () => {
+ const body = await writeMd('journal', TWO_BROKEN_FORMS);
+
+ expect(body.brokenLinks?.map((link) => link.href)).toEqual([
+ '[[ghost-doc]]',
+ './ghost-image.png',
+ ]);
+ expect(body.brokenLinkSuppression).toBeUndefined();
+ });
+
+ test('the same reserved log reports its links again once the policy is switched off', async () => {
+ const body = await writeMd('log', TWO_BROKEN_FORMS, { suppressLogLinkAdvisories: false });
+
+ expect(body.brokenLinks?.map((link) => link.href)).toEqual([
+ '[[ghost-doc]]',
+ './ghost-image.png',
+ ]);
+ expect(body.brokenLinkSuppression).toBeUndefined();
+ });
+
+ test('reserved identity is exact: a nested log is suppressed, an uppercase LOG is not', async () => {
+ const nested = await writeMd('notes/2026/log', TWO_BROKEN_FORMS);
+ expect(nested.brokenLinks).toEqual([]);
+ expect(nested.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
+
+ const upper = await writeMd('notes/LOG', TWO_BROKEN_FORMS);
+ expect(upper.brokenLinks).toHaveLength(2);
+ expect(upper.brokenLinkSuppression).toBeUndefined();
+ });
+
+ test('a reserved log whose links all resolve reports no suppression', async () => {
+ const body = await writeMd('log', '# Log\n\nNothing unresolved here.\n');
+
+ expect(body.brokenLinks).toEqual([]);
+ expect(body.brokenLinkSuppression).toBeUndefined();
+ });
+
+ test('the count is the post-dedup entry count, not the number of occurrences', async () => {
+ const body = await writeMd(
+ 'log',
+ '# Log\n\n[[ghost-doc]] and [[ghost-doc]] again, plus [[ghost-doc]].\n',
+ );
+
+ expect(body.brokenLinks).toEqual([]);
+ expect(body.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 1 });
+ });
+
+ test('a patch to a reserved log projects the post-edit links the same way', async () => {
+ await seed('log', TWO_BROKEN_FORMS);
+ const response = await post('/api/agent-patch', {
+ docName: 'log',
+ find: 'See',
+ replace: 'Still see',
+ agentId: 'claude-1',
+ agentName: 'Claude',
+ });
+
+ expect(response.status).toBe(200);
+ const body = JSON.parse(response.body) as LinkAdvisoryBody;
+ expect(body.brokenLinks).toEqual([]);
+ expect(body.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
+ });
+
+ test('a frontmatter patch to a reserved log projects the body links the same way', async () => {
+ await seed('log', TWO_BROKEN_FORMS);
+ const response = await post('/api/frontmatter-patch', {
+ docName: 'log',
+ patch: { title: 'Change log' },
+ agentId: 'claude-1',
+ agentName: 'Claude',
+ });
+
+ expect(response.status).toBe(200);
+ const body = JSON.parse(response.body) as LinkAdvisoryBody;
+ expect(body.brokenLinks).toEqual([]);
+ expect(body.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
+ });
+
+ test('every batch entry is projected by its own source document', async () => {
+ const response = await post('/api/agent-write-batch', {
+ docs: [
+ { docName: 'log', markdown: TWO_BROKEN_FORMS, position: 'replace' },
+ { docName: 'notes/log', markdown: TWO_BROKEN_FORMS, position: 'replace' },
+ { docName: 'journal', markdown: TWO_BROKEN_FORMS, position: 'replace' },
+ ],
+ agentId: 'claude-1',
+ agentName: 'Claude',
+ });
+
+ expect(response.status).toBe(200);
+ const results = (JSON.parse(response.body) as { results: LinkAdvisoryBody[] }).results;
+ expect(results.map((entry) => entry.brokenLinkSuppression)).toEqual([
+ { reason: 'reserved-log-policy', count: 2 },
+ { reason: 'reserved-log-policy', count: 2 },
+ undefined,
+ ]);
+ expect(results.map((entry) => entry.brokenLinks?.length)).toEqual([0, 0, 2]);
+ });
+
+ test('a policy change during assembly cannot split one batch response', async () => {
+ let effectivePolicy = true;
+ let policyReads = 0;
+ const ext = createApiExtension({
+ hocuspocus,
+ sessionManager,
+ contentDir,
+ getFileIndex: () => {
+ effectivePolicy = false;
+ return new Map();
+ },
+ getLinkAdvisoryPolicy: () => {
+ policyReads += 1;
+ return {
+ links: 'warning',
+ suppressLogLinkAdvisories: effectivePolicy,
+ };
+ },
+ });
+ const req = makeJsonPostReq('/api/agent-write-batch', {
+ docs: [
+ { docName: 'log', markdown: TWO_BROKEN_FORMS, position: 'replace' },
+ { docName: 'notes/log', markdown: TWO_BROKEN_FORMS, position: 'replace' },
+ ],
+ agentId: 'claude-1',
+ agentName: 'Claude',
+ });
+ const { res, captured } = makeRes();
+ await (
+ ext as {
+ onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
+ }
+ ).onRequest({ request: req, response: res });
+
+ expect(captured.status).toBe(200);
+ const results = (JSON.parse(captured.body) as { results: LinkAdvisoryBody[] }).results;
+ expect(policyReads).toBe(1);
+ expect(effectivePolicy).toBe(false);
+ expect(results.map((entry) => entry.brokenLinkSuppression)).toEqual([
+ { reason: 'reserved-log-policy', count: 2 },
+ { reason: 'reserved-log-policy', count: 2 },
+ ]);
+ });
+
+ test('switching link validation off does not empty an ordinary write advisory', async () => {
+ const ext = createApiExtension({
+ hocuspocus,
+ sessionManager,
+ contentDir,
+ getFileIndex: () => new Map(),
+ getLinkAdvisoryPolicy: () => ({
+ links: 'off',
+ suppressLogLinkAdvisories: true,
+ }),
+ });
+ const req = makeJsonPostReq('/api/agent-write-md', {
+ docName: 'journal',
+ markdown: TWO_BROKEN_FORMS,
+ position: 'replace',
+ agentId: 'claude-1',
+ agentName: 'Claude',
+ });
+ const { res, captured } = makeRes();
+ await (
+ ext as {
+ onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
+ }
+ ).onRequest({ request: req, response: res });
+
+ expect(captured.status).toBe(200);
+ const body = JSON.parse(captured.body) as LinkAdvisoryBody;
+ expect(body.brokenLinks).toHaveLength(2);
+ expect(body.brokenLinkSuppression).toBeUndefined();
+ });
+});
diff --git a/packages/server/src/broken-link-suppression.test.ts b/packages/server/src/broken-link-suppression.test.ts
new file mode 100644
index 000000000..f6c84a1d5
--- /dev/null
+++ b/packages/server/src/broken-link-suppression.test.ts
@@ -0,0 +1,169 @@
+import type { BrokenLinkSuppression } from '@inkeep/open-knowledge-core';
+import { describe, expect, test } from 'vitest';
+import {
+ createReservedLogBrokenLinkSuppression,
+ formatAuditBrokenLinkSuppressionLine,
+ formatBrokenLinkSuppressionBrief,
+ formatBrokenLinkSuppressionLine,
+ formatUnreadableAuditSuppressionWarning,
+} from './broken-link-suppression.ts';
+
+describe('createReservedLogBrokenLinkSuppression', () => {
+ test('constructs only positive-count observations with the canonical reason', () => {
+ expect(createReservedLogBrokenLinkSuppression(2)).toEqual({
+ reason: 'reserved-log-policy',
+ count: 2,
+ });
+ expect(createReservedLogBrokenLinkSuppression(0)).toBeUndefined();
+ expect(createReservedLogBrokenLinkSuppression(-1)).toBeUndefined();
+ });
+});
+
+describe('formatAuditBrokenLinkSuppressionLine', () => {
+ test('makes a filtered audit explicit and preserves the surface-specific raw route', () => {
+ const line = formatAuditBrokenLinkSuppressionLine(
+ { reason: 'reserved-log-policy', count: 2 },
+ { surface: 'mcp' },
+ );
+
+ expect(line).toContain('audit result is filtered');
+ expect(line).toContain('does NOT prove every link resolves');
+ expect(line).toContain('Settings ▸ This project ▸ Preferences ▸ Content rules');
+ expect(line).toContain('links({ kind: "dead" })');
+ expect(line).toContain('not as a repair queue');
+ expect(line).toContain('only when the user asks');
+ expect(line).not.toContain('when you need the unfiltered view');
+ expect(line).not.toContain('validation.suppressLogLinkAdvisories');
+ expect(line).not.toContain('/api/dead-links');
+ });
+
+ test('does not mislabel an unknown future policy as the reserved-log policy', () => {
+ const suppression = { reason: 'future-policy', count: 1 } as BrokenLinkSuppression;
+ const line = formatAuditBrokenLinkSuppressionLine(suppression, { surface: 'mcp' });
+
+ expect(line).toContain('does not recognize the project policy "future-policy"');
+ expect(line).not.toContain('reserved `log.md`');
+ });
+
+ test('keeps human CLI guidance free of agent-directed instructions', () => {
+ const line = formatAuditBrokenLinkSuppressionLine(
+ { reason: 'reserved-log-policy', count: 2 },
+ { surface: 'cli', serverBaseUrl: 'http://127.0.0.1:54321' },
+ );
+
+ expect(line).toContain('protect that history');
+ expect(line).toContain('validation.suppressLogLinkAdvisories: false');
+ expect(line).toContain('.ok/config.yml');
+ expect(line).toContain('Settings ▸ This project ▸ Preferences ▸ Content rules');
+ expect(line).toContain('http://127.0.0.1:54321/api/dead-links');
+ expect(line).not.toMatch(/\/api\/dead-links\S/);
+ expect(line).not.toContain('links({ kind: "dead" })');
+ expect(line).toContain('when you need the unfiltered view');
+ expect(line).not.toContain('the user');
+ expect(line).not.toContain('point them at Settings');
+ });
+
+ test('an unknown policy has audience-correct human fallback guidance', () => {
+ const suppression = { reason: 'future-policy', count: 1 } as BrokenLinkSuppression;
+ const line = formatAuditBrokenLinkSuppressionLine(suppression, {
+ surface: 'cli',
+ serverBaseUrl: 'http://127.0.0.1:54321',
+ });
+
+ expect(line).toContain('cannot explain why these findings were withheld');
+ expect(line).not.toContain('ask the user');
+ });
+
+ test('opens with its own status glyph, because it is emitted as a standalone line', () => {
+ const line = formatAuditBrokenLinkSuppressionLine(
+ { reason: 'reserved-log-policy', count: 1 },
+ { surface: 'mcp' },
+ );
+
+ expect(line).toMatch(/^ℹ /);
+ });
+});
+
+describe('formatUnreadableAuditSuppressionWarning', () => {
+ test('derives the agent raw-state route and guidance rather than restating them', () => {
+ const line = formatUnreadableAuditSuppressionWarning({ surface: 'mcp' });
+
+ expect(line).toContain('in a form this build cannot read');
+ expect(line).toContain('audit result is filtered');
+ expect(line).toContain('does NOT prove every link resolves');
+ expect(line).toContain('links({ kind: "dead" })');
+ expect(line).toContain('only when the user asks');
+ expect(line).toContain('not as a repair queue');
+ expect(line).not.toContain('when you need the unfiltered view');
+ expect(line).not.toContain('validation.suppressLogLinkAdvisories');
+ expect(line).not.toContain('/api/dead-links');
+ });
+
+ test('keeps the human CLI route free of agent-directed instructions', () => {
+ const line = formatUnreadableAuditSuppressionWarning({
+ surface: 'cli',
+ serverBaseUrl: 'http://127.0.0.1:54321',
+ });
+
+ expect(line).toContain('in a form this build cannot read');
+ expect(line).toContain('http://127.0.0.1:54321/api/dead-links');
+ expect(line).not.toMatch(/\/api\/dead-links\S/);
+ expect(line).toContain('when you need the unfiltered view');
+ expect(line).not.toContain('links({ kind: "dead" })');
+ expect(line).not.toContain('the user');
+ });
+
+ test('does not claim a count it cannot read', () => {
+ const line = formatUnreadableAuditSuppressionWarning({ surface: 'mcp' });
+
+ expect(line).not.toMatch(/\d+ broken-link finding/);
+ expect(line).not.toContain('undefined');
+ });
+
+ test('carries no leading status glyph, because degradationBlock supplies its own in the warnings channel', () => {
+ const line = formatUnreadableAuditSuppressionWarning({ surface: 'mcp' });
+
+ expect(line).not.toMatch(/^[ℹ⚠]/);
+ });
+});
+
+describe('write and edit suppression lines', () => {
+ const suppression = (count: number): BrokenLinkSuppression => ({
+ reason: 'reserved-log-policy',
+ count,
+ });
+
+ test('the full line reinterprets the empty list and routes the remedy to the user', () => {
+ const line = formatBrokenLinkSuppressionLine(suppression(2));
+ expect(line).toContain('2 broken-link findings withheld');
+ expect(line).toContain('does NOT mean every link resolves');
+ expect(line).toContain('Settings ▸ This project ▸ Preferences ▸ Content rules');
+ expect(line).not.toContain('validation.suppressLogLinkAdvisories');
+ });
+
+ test('an unrecognized reason still says the empty list is not an all-clear', () => {
+ const line = formatBrokenLinkSuppressionLine({ reason: 'some-future-policy', count: 2 });
+ expect(line).toContain('2 broken-link findings withheld');
+ expect(line).toContain('does NOT mean every link resolves');
+ expect(line).toContain('some-future-policy');
+ expect(line).toContain('not yours to repair');
+ });
+
+ test('one withheld finding reads singular', () => {
+ expect(formatBrokenLinkSuppressionLine(suppression(1))).toContain('1 broken-link finding ');
+ expect(formatBrokenLinkSuppressionBrief(suppression(1))).toContain('1 broken-link finding ');
+ });
+
+ test('the brief points at the structured field and states the filtered-result invariant', () => {
+ const brief = formatBrokenLinkSuppressionBrief(suppression(4));
+ expect(brief).toContain('4 broken-link findings withheld');
+ expect(brief).toContain('brokenLinkSuppression');
+ expect(brief).toContain('does NOT mean every link resolves');
+ expect(brief).toContain('nothing to repair');
+ });
+
+ test('both open with their own status glyph, because no consumer supplies one', () => {
+ expect(formatBrokenLinkSuppressionLine(suppression(1))).toMatch(/^ℹ /);
+ expect(formatBrokenLinkSuppressionBrief(suppression(1))).toMatch(/^ℹ /);
+ });
+});
diff --git a/packages/server/src/broken-link-suppression.ts b/packages/server/src/broken-link-suppression.ts
new file mode 100644
index 000000000..0630d8216
--- /dev/null
+++ b/packages/server/src/broken-link-suppression.ts
@@ -0,0 +1,103 @@
+import {
+ BROKEN_LINK_SUPPRESSION_REASONS,
+ type BrokenLinkSuppression,
+ type BrokenLinkSuppressionReason,
+} from '@inkeep/open-knowledge-core';
+
+type AuditSuppressionAudience = 'agent' | 'human';
+export type AuditSuppressionTarget = { surface: 'cli'; serverBaseUrl: string } | { surface: 'mcp' };
+type AuditSuppressionSurface = AuditSuppressionTarget['surface'];
+
+const SUPPRESSION_EXPLANATIONS = {
+ agent: {
+ 'reserved-log-policy':
+ 'a reserved `log.md` records history whose links are expected not to resolve. Nothing here is yours to repair — repairing them rewrites the history the log exists to keep, and turning the project setting off yourself is not a workaround. If the user asks to see these findings, point them at Settings ▸ This project ▸ Preferences ▸ Content rules.',
+ },
+ human: {
+ 'reserved-log-policy':
+ 'a reserved `log.md` records history whose links are expected not to resolve. These findings stay out of the repair queue to protect that history. Set `validation.suppressLogLinkAdvisories: false` in `.ok/config.yml` to bring them back, or turn off "Ignore broken links in log.md" under Settings ▸ This project ▸ Preferences ▸ Content rules.',
+ },
+} as const satisfies Record<AuditSuppressionAudience, Record<BrokenLinkSuppressionReason, string>>;
+
+const UNKNOWN_SUPPRESSION_EXPLANATIONS = {
+ agent: (reason: string) =>
+ `this build does not recognize the project policy "${reason}", so it cannot say why. Treat the withheld findings as not yours to repair and ask the user if they need to see them.`,
+ human: (reason: string) =>
+ `this build does not recognize the project policy "${reason}", so it cannot explain why these findings were withheld.`,
+} as const satisfies Record<AuditSuppressionAudience, (reason: string) => string>;
+
+const RAW_STATE_GUIDANCE = {
+ agent: 'inspect it only when the user asks, not as a repair queue.',
+ human: 'inspect it when you need the unfiltered view, not as a repair queue.',
+} as const satisfies Record<AuditSuppressionAudience, string>;
+
+const AUDIT_SUPPRESSION_SURFACES = {
+ cli: {
+ audience: 'human',
+ },
+ mcp: {
+ audience: 'agent',
+ },
+} as const satisfies Record<
+ AuditSuppressionSurface,
+ {
+ audience: AuditSuppressionAudience;
+ }
+>;
+
+function isKnownSuppressionReason(reason: string): reason is BrokenLinkSuppressionReason {
+ return (BROKEN_LINK_SUPPRESSION_REASONS as readonly string[]).includes(reason);
+}
+
+function suppressionExplanation(reason: string, audience: AuditSuppressionAudience): string {
+ if (isKnownSuppressionReason(reason)) {
+ return SUPPRESSION_EXPLANATIONS[audience][reason];
+ }
+ return UNKNOWN_SUPPRESSION_EXPLANATIONS[audience](reason);
+}
+
+function assertNeverAuditSuppressionTarget(target: never): never {
+ throw new Error(`Unhandled AuditSuppressionTarget: ${JSON.stringify(target as unknown)}`);
+}
+
+function rawStateRoute(target: AuditSuppressionTarget): string {
+ switch (target.surface) {
+ case 'cli':
+ return `${target.serverBaseUrl}/api/dead-links`;
+ case 'mcp':
+ return 'links({ kind: "dead" })';
+ default:
+ return assertNeverAuditSuppressionTarget(target);
+ }
+}
+
+function suppressionCountPhrase(suppression: BrokenLinkSuppression): string {
+ return `${suppression.count} broken-link finding${suppression.count === 1 ? '' : 's'}`;
+}
+
+export function createReservedLogBrokenLinkSuppression(
+ count: number,
+): BrokenLinkSuppression | undefined {
+ return count > 0 ? { reason: 'reserved-log-policy', count } : undefined;
+}
+
+export function formatBrokenLinkSuppressionLine(suppression: BrokenLinkSuppression): string {
+ return `ℹ ${suppressionCountPhrase(suppression)} withheld by project policy, so \`brokenLinks: []\` above does NOT mean every link resolves — ${suppressionExplanation(suppression.reason, 'agent')}`;
+}
+
+export function formatBrokenLinkSuppressionBrief(suppression: BrokenLinkSuppression): string {
+ return `ℹ ${suppressionCountPhrase(suppression)} withheld by project policy (see brokenLinkSuppression); this filtered result does NOT mean every link resolves, and there is nothing to repair.`;
+}
+
+export function formatAuditBrokenLinkSuppressionLine(
+ suppression: BrokenLinkSuppression,
+ target: AuditSuppressionTarget,
+): string {
+ const { audience } = AUDIT_SUPPRESSION_SURFACES[target.surface];
+ return `ℹ ${suppressionCountPhrase(suppression)} withheld by project policy. This audit result is filtered, so it does NOT prove every link resolves — ${suppressionExplanation(suppression.reason, audience)} Raw state remains available through ${rawStateRoute(target)} — ${RAW_STATE_GUIDANCE[audience]}`;
+}
+
+export function formatUnreadableAuditSuppressionWarning(target: AuditSuppressionTarget): string {
+ const { audience } = AUDIT_SUPPRESSION_SURFACES[target.surface];
+ return `Broken-link findings were withheld by project policy in a form this build cannot read. This audit result is filtered, so it does NOT prove every link resolves. Raw state remains available through ${rawStateRoute(target)} — ${RAW_STATE_GUIDANCE[audience]}`;
+}
diff --git a/packages/server/src/http/lint-routes.ts b/packages/server/src/http/lint-routes.ts
index 80bc568c5..93e3a7243 100644
--- a/packages/server/src/http/lint-routes.ts
+++ b/packages/server/src/http/lint-routes.ts
@@ -7,7 +7,6 @@ import {
EmptyRequestSchema,
FrontmatterSchemasListSuccessSchema,
isFrontmatterSchemaAsset,
- type LinksValidationSetting,
LintAuditResponseSchema,
LintConfigResponseSchema,
LintDocResultSchema,
@@ -19,6 +18,7 @@ import {
import type { ContentFilter } from '../content-filter.ts';
import type { DerivedDocumentIndexApiPort } from '../derived-document-index.ts';
import { isContainmentRejection } from '../fs-safety.ts';
+import type { LinkAdvisoryPolicy } from '../link-advisory-policy.ts';
import { AuditSupersededError, auditProject, lintDoc } from '../lint/audit.ts';
import { AuditCache } from '../lint/audit-cache.ts';
import { listProjectSchemaFiles, SCHEMA_LIST_CAP } from '../lint/frontmatter-schemas.ts';
@@ -55,7 +55,7 @@ export interface LintRouteDeps {
maxEntries: number;
}) => AsyncGenerator<DocumentListEntry, { truncated: boolean }, void>;
getLinterBaseConfig: (() => LinterConfig) | undefined;
- getLinksValidationSetting: (() => LinksValidationSetting) | undefined;
+ getLinkAdvisoryPolicy: () => LinkAdvisoryPolicy;
derivedDocumentIndex: DerivedDocumentIndexApiPort | undefined;
collectAdmittedDocNames: () => Promise<Set<string>>;
unmatchedGlobProblems: (effective: LinterConfig) => string[];
@@ -78,7 +78,7 @@ export function createLintRoutes(deps: LintRouteDeps): LintRoutes {
isValidRelativeContentPath,
streamShowAllEntries,
getLinterBaseConfig,
- getLinksValidationSetting,
+ getLinkAdvisoryPolicy,
derivedDocumentIndex,
collectAdmittedDocNames,
unmatchedGlobProblems,
@@ -326,13 +326,14 @@ export function createLintRoutes(deps: LintRouteDeps): LintRoutes {
target = resolveDocFilePath(contentDir, docParam) ?? `${docParam}.md`;
}
const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
+ const linkPolicy = getLinkAdvisoryPolicy();
const validators = createProjectValidators({
projectDir: projectDir ?? contentDir,
contentDir,
baseConfig,
liveSourceFor: liveLintSourceFor,
derivedDocumentIndex: derivedDocumentIndex ?? null,
- linksValidation: getLinksValidationSetting?.(),
+ linkPolicy,
admittedDocNames: collectAdmittedDocNames,
docFilePathFor: (docName) => resolveDocFilePath(contentDir, docName),
cache: auditCache,
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index 35a8284f6..20f831931 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -84,6 +84,10 @@ export {
restoreLifecycleFromConflictsJson,
type ServerExitReason,
} from './boot.ts';
+export {
+ type AuditSuppressionTarget,
+ formatAuditBrokenLinkSuppressionLine,
+} from './broken-link-suppression.ts';
export {
type BuildSkillZipOptions,
type BuildSkillZipResult,
diff --git a/packages/server/src/link-advisory-policy.ts b/packages/server/src/link-advisory-policy.ts
new file mode 100644
index 000000000..cc8638bbb
--- /dev/null
+++ b/packages/server/src/link-advisory-policy.ts
@@ -0,0 +1,41 @@
+import {
+ type BrokenLinkSuppression,
+ isReservedLogDoc,
+ type LinksValidationSetting,
+} from '@inkeep/open-knowledge-core';
+import { createReservedLogBrokenLinkSuppression } from './broken-link-suppression.ts';
+import type { WriteAdvisoryLink } from './write-advisory-links.ts';
+
+export interface LinkAdvisoryPolicy {
+ links: LinksValidationSetting;
+ suppressLogLinkAdvisories: boolean;
+}
+
+export function shouldSuppressLogLinkAdvisories(
+ sourceDocName: string,
+ suppressLogLinkAdvisories: boolean,
+): boolean {
+ return suppressLogLinkAdvisories && isReservedLogDoc(sourceDocName);
+}
+
+export interface WriteLinkAdvisoryProjection {
+ brokenLinks: WriteAdvisoryLink[];
+ brokenLinkSuppression?: BrokenLinkSuppression;
+}
+
+export function projectWriteAdvisoryLinks(
+ detected: WriteAdvisoryLink[],
+ sourceDocName: string,
+ suppressLogLinkAdvisories: boolean,
+): WriteLinkAdvisoryProjection {
+ if (
+ detected.length === 0 ||
+ !shouldSuppressLogLinkAdvisories(sourceDocName, suppressLogLinkAdvisories)
+ ) {
+ return { brokenLinks: detected };
+ }
+ return {
+ brokenLinks: [],
+ brokenLinkSuppression: createReservedLogBrokenLinkSuppression(detected.length),
+ };
+}
diff --git a/packages/server/src/lint/audit-generation.test.ts b/packages/server/src/lint/audit-generation.test.ts
new file mode 100644
index 000000000..066ca07bd
--- /dev/null
+++ b/packages/server/src/lint/audit-generation.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'vitest';
+import { type AuditGenerationInputs, composeAuditGeneration } from './audit-generation.ts';
+
+const BASE: AuditGenerationInputs = {
+ lintConfigEpoch: 0,
+ projectConfigEpoch: 0,
+ activeBranch: 'main',
+ localTargetGeneration: 0,
+};
+
+const MOVES_THE_TOKEN: ReadonlyArray<[string, Partial<AuditGenerationInputs>]> = [
+ ['a lint-config mutation', { lintConfigEpoch: 1 }],
+ ['a committed project-config mutation', { projectConfigEpoch: 1 }],
+ ['a branch switch', { activeBranch: 'detached-abc1234' }],
+ ['a local-target index update', { localTargetGeneration: '7' }],
+];
+
+describe('composeAuditGeneration', () => {
+ test.each(MOVES_THE_TOKEN)('%s changes the token', (_label, change) => {
+ expect(composeAuditGeneration({ ...BASE, ...change })).not.toBe(composeAuditGeneration(BASE));
+ });
+
+ test('an unchanged world composes the same token, so audits still coalesce', () => {
+ expect(composeAuditGeneration({ ...BASE })).toBe(composeAuditGeneration(BASE));
+ });
+
+ test('no field can bleed into its neighbour across the separator', () => {
+ expect(
+ composeAuditGeneration({ ...BASE, lintConfigEpoch: 1, projectConfigEpoch: 15 }),
+ ).not.toBe(composeAuditGeneration({ ...BASE, lintConfigEpoch: 11, projectConfigEpoch: 5 }));
+ });
+});
diff --git a/packages/server/src/lint/audit-generation.ts b/packages/server/src/lint/audit-generation.ts
new file mode 100644
index 000000000..501e5466c
--- /dev/null
+++ b/packages/server/src/lint/audit-generation.ts
@@ -0,0 +1,15 @@
+export interface AuditGenerationInputs {
+ lintConfigEpoch: number;
+ projectConfigEpoch: number;
+ activeBranch: string;
+ localTargetGeneration: string | number;
+}
+
+export function composeAuditGeneration(inputs: AuditGenerationInputs): string {
+ return [
+ inputs.lintConfigEpoch,
+ inputs.projectConfigEpoch,
+ inputs.activeBranch,
+ inputs.localTargetGeneration,
+ ].join(' ');
+}
diff --git a/packages/server/src/lint/validation-audit.test.ts b/packages/server/src/lint/validation-audit.test.ts
index 1fc14a670..05e67c1b0 100644
--- a/packages/server/src/lint/validation-audit.test.ts
+++ b/packages/server/src/lint/validation-audit.test.ts
@@ -10,6 +10,7 @@ import {
} from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { BacklinkIndex } from '../backlink-index.ts';
+import type { LinkAdvisoryPolicy } from '../link-advisory-policy.ts';
import { LocalTargetIndex } from '../local-target-index.ts';
import {
createProjectValidators,
@@ -64,11 +65,16 @@ function docFilePathFor(docName: string): string | null {
return null;
}
+function linkPolicy(overrides: Partial<LinkAdvisoryPolicy> = {}): LinkAdvisoryPolicy {
+ return { links: 'warning', suppressLogLinkAdvisories: true, ...overrides };
+}
+
function deps(overrides: Partial<ValidationAuditDeps> = {}): ValidationAuditDeps {
return {
projectDir: root,
contentDir: root,
baseConfig: lintOn,
+ linkPolicy: linkPolicy(),
derivedDocumentIndex: {
getDeadLinks: (a, s) => index.getDeadLinks(a, s),
getLocalTargetAssessmentsForSources: (s) => localTargets.getAssessmentsForSources(s),
@@ -128,12 +134,14 @@ describe('runValidationAudit', () => {
seedDoc('linker', '# Linker\n\nSee [[ghost]].\n');
const asError = await runValidationAudit(
- createProjectValidators(deps({ linksValidation: 'error' })),
+ createProjectValidators(deps({ linkPolicy: linkPolicy({ links: 'error' }) })),
);
expect(asError.files[0]?.diagnostics[0]?.severity).toBe('error');
expect(asError.errorCount).toBe(1);
- const off = await runValidationAudit(createProjectValidators(deps({ linksValidation: 'off' })));
+ const off = await runValidationAudit(
+ createProjectValidators(deps({ linkPolicy: linkPolicy({ links: 'off' }) })),
+ );
expect(off.files.every((f) => f.diagnostics.every((d) => d.source !== 'links'))).toBe(true);
expect(off.ran).toEqual(['markdownlint']);
expect(off.warnings).toEqual([]);
@@ -298,7 +306,9 @@ describe('runValidationAudit', () => {
test('a lint-walk failure keeps its label whatever the enabled plugin count is', async () => {
const walkFailure = async (baseConfig: LinterConfig) => {
- const validators = createProjectValidators(deps({ baseConfig, linksValidation: 'off' }));
+ const validators = createProjectValidators(
+ deps({ baseConfig, linkPolicy: linkPolicy({ links: 'off' }) }),
+ );
const lint = validators.find((validator) => validator.id === 'lint');
if (!lint) throw new Error('lint validator missing');
const failing: ProjectValidator = {
@@ -325,7 +335,9 @@ describe('runValidationAudit', () => {
...lintOn,
plugins: { ...lintOn.plugins, okf: { enabled: true } },
} as LinterConfig;
- const validators = createProjectValidators(deps({ baseConfig: okfOn, linksValidation: 'off' }));
+ const validators = createProjectValidators(
+ deps({ baseConfig: okfOn, linkPolicy: linkPolicy({ links: 'off' }) }),
+ );
const okfProject = validators.find((validator) => validator.id === 'okf-project');
if (!okfProject) throw new Error('okf project validator missing');
const failing: ProjectValidator = {
@@ -602,12 +614,14 @@ describe('local-target findings (files, images, reference-style)', () => {
test('validation.links=off silences file findings; =error raises them uniformly with dead links', async () => {
seedDoc('doc', '# Doc\n\n[report](./report.pdf)\n');
- const off = await runValidationAudit(createProjectValidators(deps({ linksValidation: 'off' })));
+ const off = await runValidationAudit(
+ createProjectValidators(deps({ linkPolicy: linkPolicy({ links: 'off' }) })),
+ );
expect(off.files).toEqual([]);
expect(off.warnings).toEqual([]);
const asError = await runValidationAudit(
- createProjectValidators(deps({ linksValidation: 'error' })),
+ createProjectValidators(deps({ linkPolicy: linkPolicy({ links: 'error' }) })),
);
expect(asError.files[0]?.diagnostics[0]?.severity).toBe('error');
expect(asError.errorCount).toBe(1);
@@ -667,7 +681,9 @@ describe('the OKF project validator', () => {
const auditOkf = async (overrides: Partial<ValidationAuditDeps> = {}) =>
runValidationAudit(
- createProjectValidators(deps({ baseConfig: okfOnly, linksValidation: 'off', ...overrides })),
+ createProjectValidators(
+ deps({ baseConfig: okfOnly, linkPolicy: linkPolicy({ links: 'off' }), ...overrides }),
+ ),
);
test('reports okf in ran exactly once — the lint and tree validators share the family', async () => {
@@ -689,7 +705,9 @@ describe('the OKF project validator', () => {
writeFile('guide.md');
writeFile('guide.mdx');
const scoped = await runValidationAudit(
- createProjectValidators(deps({ baseConfig: okfOnly, linksValidation: 'off' })),
+ createProjectValidators(
+ deps({ baseConfig: okfOnly, linkPolicy: linkPolicy({ links: 'off' }) }),
+ ),
{ targetPath: 'guide.mdx' },
);
expect(scoped.files.flatMap((f) => f.diagnostics).map((d) => d.code)).toEqual([
@@ -702,7 +720,9 @@ describe('the OKF project validator', () => {
writeFile('guide.md');
writeFile('guide.mdx');
const scoped = await runValidationAudit(
- createProjectValidators(deps({ baseConfig: okfOnly, linksValidation: 'off' })),
+ createProjectValidators(
+ deps({ baseConfig: okfOnly, linkPolicy: linkPolicy({ links: 'off' }) }),
+ ),
{ targetPath: 'guide.mdx' },
);
const message = scoped.files.flatMap((f) => f.diagnostics)[0]?.message ?? '';
@@ -714,7 +734,9 @@ describe('the OKF project validator', () => {
writeFile('one.mdx');
writeFile('two.mdx');
const scoped = await runValidationAudit(
- createProjectValidators(deps({ baseConfig: okfOnly, linksValidation: 'off' })),
+ createProjectValidators(
+ deps({ baseConfig: okfOnly, linkPolicy: linkPolicy({ links: 'off' }) }),
+ ),
{ targetPath: 'one.mdx' },
);
expect(scoped.files.map((f) => f.file)).toEqual(['one.mdx']);
@@ -776,7 +798,9 @@ describe('the OKF project validator', () => {
);
const scoped = await runValidationAudit(
- createProjectValidators(deps({ baseConfig: okfOnly, linksValidation: 'off' })),
+ createProjectValidators(
+ deps({ baseConfig: okfOnly, linkPolicy: linkPolicy({ links: 'off' }) }),
+ ),
{ targetPath: 'sub' },
);
expect(scoped.files.flatMap((f) => f.diagnostics)).toEqual([]);
@@ -995,3 +1019,189 @@ describe('skill-bundle doc scoping', () => {
expect(plane.files).toEqual([]);
});
});
+
+describe('reserved-log link advisory policy', () => {
+ const EVERY_LINK_FORM = [
+ '# Log',
+ '',
+ 'Wiki: [[ghost]]',
+ '',
+ 'Markdown: [doc](./ghost-doc.md)',
+ '',
+ 'File: [report](./report.pdf)',
+ '',
+ 'Image: ![logo](./logo.png)',
+ '',
+ 'Reference: [one][r]',
+ '',
+ '[r]: ./missing.pdf',
+ '',
+ ].join('\n');
+
+ function seedMdxDoc(docName: string, markdown: string): void {
+ const abs = join(root, `${docName}.mdx`);
+ mkdirSync(join(abs, '..'), { recursive: true });
+ writeFileSync(abs, markdown, 'utf-8');
+ index.updateDocumentFromMarkdown(docName, markdown);
+ localTargets.setSource(docName, markdown);
+ admitted.add(docName);
+ }
+
+ const deadLinkFilesIn = (result: {
+ files: { file: string; diagnostics: { code: string }[] }[];
+ }) =>
+ result.files
+ .filter((f) => f.diagnostics.some((d) => d.code === 'dead-link'))
+ .map((f) => f.file);
+
+ test('the reserved lowercase log document contributes no link findings by default', async () => {
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ seedDoc('log', '# Log\n\nSee [[ghost]].\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const control = result.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+ expect(result.files.find((f) => f.file === 'log.md')).toBeUndefined();
+ expect(result.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 1,
+ });
+ expect(result.warnings).toEqual([]);
+ expect(result.ran).toContain('links');
+ });
+
+ test('a nested log is suppressed at any depth', async () => {
+ seedDoc('team/notes/log', '# Log\n\nSee [[ghost]].\n');
+ seedDoc('team/notes/journal', '# Journal\n\nSee [[ghost]].\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ expect(deadLinkFilesIn(result)).toEqual(['team/notes/journal.md']);
+ });
+
+ test('an .mdx reserved log is suppressed like its .md spelling', async () => {
+ seedMdxDoc('log', '# Log\n\nSee [[ghost]].\n');
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ expect(deadLinkFilesIn(result)).toEqual(['control.md']);
+ });
+
+ test('LOG.md and other casings are ordinary documents that keep their findings', async () => {
+ seedDoc('LOG', '# Log\n\nSee [[ghost]].\n');
+ seedDoc('notes/Log', '# Log\n\nSee [[ghost]].\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ expect(deadLinkFilesIn(result)).toEqual(['LOG.md', 'notes/Log.md']);
+ expect(result.brokenLinkSuppression).toBeUndefined();
+ });
+
+ test('a stem that merely ends in the reserved word keeps its findings', async () => {
+ seedDoc('catalog', '# Catalog\n\nSee [[ghost]].\n');
+ seedDoc('changelog', '# Changelog\n\nSee [[ghost]].\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ expect(deadLinkFilesIn(result)).toEqual(['catalog.md', 'changelog.md']);
+ });
+
+ test('both detection planes are suppressed, not just the graph', async () => {
+ seedDoc('log', EVERY_LINK_FORM);
+ seedDoc('control', EVERY_LINK_FORM);
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const control = result.files.find((f) => f.file === 'control.md');
+ const forms = new Set(
+ (control?.diagnostics ?? []).map((d) => d.localTarget?.sourceForm ?? 'graph'),
+ );
+ expect(forms).toEqual(new Set(['graph', 'markdown-inline', 'markdown-reference']));
+ expect(result.files.find((f) => f.file === 'log.md')).toBeUndefined();
+ expect(result.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 5,
+ });
+ expect(toValidationCountsPlane(result).brokenLinkSuppression).toEqual(
+ result.brokenLinkSuppression,
+ );
+ });
+
+ test('the findings return in full when the policy is disabled', async () => {
+ seedDoc('log', EVERY_LINK_FORM);
+ seedDoc('control', EVERY_LINK_FORM);
+
+ const on = await runValidationAudit(createProjectValidators(deps()));
+ const off = await runValidationAudit(
+ createProjectValidators(
+ deps({ linkPolicy: linkPolicy({ suppressLogLinkAdvisories: false }) }),
+ ),
+ );
+
+ const controlDiagnostics = (result: typeof off) =>
+ result.files.find((f) => f.file === 'control.md')?.diagnostics;
+ const logRow = off.files.find((f) => f.file === 'log.md');
+ expect(logRow?.diagnostics).toEqual(controlDiagnostics(off));
+ expect(controlDiagnostics(on)).toEqual(controlDiagnostics(off));
+ expect(on.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 5 });
+ expect(off.brokenLinkSuppression).toBeUndefined();
+ });
+
+ test('a doc-scoped audit of the reserved log answers empty, and reports when disabled', async () => {
+ seedDoc('log', '# Log\n\nSee [[ghost]].\n');
+ const scope = { targetPath: 'log.md' };
+
+ const suppressed = await runValidationAudit(createProjectValidators(deps()), scope);
+ expect(suppressed.files).toEqual([]);
+ expect(suppressed.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 1,
+ });
+
+ const reported = await runValidationAudit(
+ createProjectValidators(
+ deps({ linkPolicy: linkPolicy({ suppressLogLinkAdvisories: false }) }),
+ ),
+ scope,
+ );
+ expect(reported.files.map((f) => f.file)).toEqual(['log.md']);
+ expect(reported.brokenLinkSuppression).toBeUndefined();
+ });
+
+ test('dead links from an ordinary doc INTO a log document are still reported', async () => {
+ seedDoc('control', '# Control\n\nWiki: [[archive/log]]\n\nMd: [log](archive/log.md)\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const control = result.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.filter((d) => d.code === 'dead-link').length).toBeGreaterThan(0);
+ });
+
+ test('the raw graph and assessment views keep the sources the plane suppresses', async () => {
+ seedDoc('log', '# Log\n\nSee [[ghost]] and [report](./report.pdf).\n');
+
+ const rawGraph = await index.getDeadLinks([...admitted]);
+ expect(rawGraph.some(({ sources }) => sources.some((o) => o.source === 'log'))).toBe(true);
+ const rawAssessed = await localTargets.getAssessmentsForSources(['log']);
+ expect(
+ rawAssessed.some(({ assessments }) => assessments.some((a) => a.status === 'missing')),
+ ).toBe(true);
+
+ const plane = await runValidationAudit(createProjectValidators(deps()));
+ expect(plane.files).toEqual([]);
+ });
+
+ test('validation.links=off silences the plane whatever the log policy says', async () => {
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ seedDoc('log', '# Log\n\nSee [[ghost]].\n');
+
+ const result = await runValidationAudit(
+ createProjectValidators(deps({ linkPolicy: linkPolicy({ links: 'off' }) })),
+ );
+
+ expect(result.files).toEqual([]);
+ expect(result.brokenLinkSuppression).toBeUndefined();
+ });
+});
diff --git a/packages/server/src/lint/validation-audit.ts b/packages/server/src/lint/validation-audit.ts
index 305ad456b..578b8b8e5 100644
--- a/packages/server/src/lint/validation-audit.ts
+++ b/packages/server/src/lint/validation-audit.ts
@@ -1,8 +1,7 @@
import {
+ type BrokenLinkSuppression,
countDiagnosticsBySource,
- DEFAULT_LINKS_VALIDATION,
deriveValidationRunSources,
- type LinksValidationSetting,
type LinterConfig,
type LintPluginId,
SUPPORTED_DOC_EXTENSIONS,
@@ -10,8 +9,13 @@ import {
type ValidationDocCounts,
type ValidationSource,
} from '@inkeep/open-knowledge-core';
+import { createReservedLogBrokenLinkSuppression } from '../broken-link-suppression.ts';
import { isProblemsPlaneExcludedDoc } from '../cc1-broadcast.ts';
import type { DerivedDocumentIndexApiPort } from '../derived-document-index.ts';
+import {
+ type LinkAdvisoryPolicy,
+ shouldSuppressLogLinkAdvisories,
+} from '../link-advisory-policy.ts';
import {
buildLocalTargetEvidence,
type LocalTargetAssessment,
@@ -53,6 +57,7 @@ export interface ValidationAuditResult {
warningCount: number;
warnings: string[];
ran: ValidationSource[];
+ brokenLinkSuppression?: BrokenLinkSuppression;
}
export interface ValidationAuditCountsResult {
@@ -61,6 +66,7 @@ export interface ValidationAuditCountsResult {
errorCount: number;
warningCount: number;
warnings: string[];
+ brokenLinkSuppression?: BrokenLinkSuppression;
}
export function toValidationCountsPlane(
@@ -75,6 +81,9 @@ export function toValidationCountsPlane(
errorCount: result.errorCount,
warningCount: result.warningCount,
warnings: result.warnings,
+ ...(result.brokenLinkSuppression === undefined
+ ? {}
+ : { brokenLinkSuppression: result.brokenLinkSuppression }),
};
}
@@ -87,6 +96,7 @@ interface ValidatorRunResult<Source extends ValidationSource = ValidationSource>
fileCount: number;
warnings: string[];
ran?: readonly Source[];
+ suppressedBrokenLinkCount?: number;
}
export interface ProjectValidator<Source extends ValidationSource = ValidationSource> {
@@ -122,7 +132,7 @@ export interface ValidationAuditDeps {
baseConfig: LinterConfig;
liveSourceFor?: (docRelPath: string) => string | null;
derivedDocumentIndex: ValidationDerivedIndexReader | null;
- linksValidation?: LinksValidationSetting;
+ linkPolicy: LinkAdvisoryPolicy;
admittedDocNames: () => Iterable<string> | Promise<Iterable<string>>;
docFilePathFor: (docName: string) => string | null;
cache?: AuditCache;
@@ -169,10 +179,12 @@ export async function runValidationAudit(
const byFile = new Map<string, ValidationDiagnostic[]>();
const warnings: string[] = [];
const ran = new Set<ValidationSource>();
+ let suppressedBrokenLinkCount = 0;
let fileCount = 0;
for (const result of results) {
warnings.push(...result.warnings);
for (const source of result.ran ?? []) ran.add(source);
+ suppressedBrokenLinkCount += result.suppressedBrokenLinkCount ?? 0;
fileCount = Math.max(fileCount, result.fileCount);
for (const entry of result.files) {
const merged = byFile.get(entry.file);
@@ -194,7 +206,17 @@ export async function runValidationAudit(
}
}
- return { files, fileCount, errorCount, warningCount, warnings, ran: [...ran] };
+ const brokenLinkSuppression = createReservedLogBrokenLinkSuppression(suppressedBrokenLinkCount);
+
+ return {
+ files,
+ fileCount,
+ errorCount,
+ warningCount,
+ warnings,
+ ran: [...ran],
+ ...(brokenLinkSuppression === undefined ? {} : { brokenLinkSuppression }),
+ };
}
function byPosition(a: ValidationDiagnostic, b: ValidationDiagnostic): number {
@@ -232,7 +254,8 @@ function createLintValidator(deps: ValidationAuditDeps): ProjectValidator<LintPl
}
function createLinksValidator(deps: ValidationAuditDeps): ProjectValidator<'links'> {
- const setting = deps.linksValidation ?? DEFAULT_LINKS_VALIDATION;
+ const setting = deps.linkPolicy.links;
+ const suppressLogAdvisories = deps.linkPolicy.suppressLogLinkAdvisories;
const sourceFamilies = deriveValidationRunSources(deps.baseConfig, {
mode: 'audit',
linksValidation: setting,
@@ -272,6 +295,9 @@ function createLinksValidator(deps: ValidationAuditDeps): ProjectValidator<'link
}
const deadLinks = await deps.derivedDocumentIndex.getDeadLinks(admitted, sourceFilter);
+ const isSuppressedLogAdvisorySource = (source: string): boolean =>
+ shouldSuppressLogLinkAdvisories(source, suppressLogAdvisories);
+
const byFile = new Map<string, ValidationDiagnosticFor<'links'>[]>();
const push = (file: string, diagnostic: ValidationDiagnosticFor<'links'>): void => {
const diagnostics = byFile.get(file) ?? [];
@@ -286,16 +312,19 @@ function createLinksValidator(deps: ValidationAuditDeps): ProjectValidator<'link
const documentTargetsFromAssessment = new Set<string>();
const resolvedTargetsFromAssessment = new Set<string>();
const warnings: string[] = [];
+ let suppressedBrokenLinkCount = 0;
try {
const assessed =
await deps.derivedDocumentIndex.getLocalTargetAssessmentsForSources(sourceFilter);
for (const { source, assessments } of assessed) {
if (isProblemsPlaneExcludedDoc(source)) continue;
+ const suppressSource = isSuppressedLogAdvisorySource(source);
const file = deps.docFilePathFor(source) ?? `${source}.md`;
for (const assessment of assessments) {
const diagnostic = toLocalTargetDiagnostic(assessment, severity);
if (!diagnostic) continue;
- localTargetDiagnostics.push({ file, diagnostic });
+ if (suppressSource) suppressedBrokenLinkCount++;
+ else localTargetDiagnostics.push({ file, diagnostic });
if (assessment.targetKind === 'document' && assessment.resolvedTarget !== null) {
documentTargetsFromAssessment.add(`${source}\0${assessment.resolvedTarget}`);
}
@@ -331,6 +360,10 @@ function createLinksValidator(deps: ValidationAuditDeps): ProjectValidator<'link
) {
continue;
}
+ if (isSuppressedLogAdvisorySource(occurrence.source)) {
+ suppressedBrokenLinkCount++;
+ continue;
+ }
const file = deps.docFilePathFor(occurrence.source) ?? `${occurrence.source}.md`;
const line = occurrence.line ?? 0;
const character = occurrence.column ?? 0;
@@ -353,6 +386,7 @@ function createLinksValidator(deps: ValidationAuditDeps): ProjectValidator<'link
files: [...byFile.entries()].map(([file, diagnostics]) => ({ file, diagnostics })),
fileCount: 0,
warnings,
+ ...(suppressedBrokenLinkCount > 0 ? { suppressedBrokenLinkCount } : {}),
};
},
};
diff --git a/packages/server/src/mcp/tools/advisory-warnings.test.ts b/packages/server/src/mcp/tools/advisory-warnings.test.ts
index 22849101d..381582d1c 100644
--- a/packages/server/src/mcp/tools/advisory-warnings.test.ts
+++ b/packages/server/src/mcp/tools/advisory-warnings.test.ts
@@ -15,6 +15,7 @@ import {
formatRenderWarningsBrief,
formatRenderWarningsLine,
parseAdvisoryWarnings,
+ parseBrokenLinkSuppression,
parseBrokenLinks,
} from './advisory-warnings.ts';
@@ -338,6 +339,32 @@ describe('unrecognized-kind fallback', () => {
});
});
+describe('parseBrokenLinkSuppression', () => {
+ const wellFormed = { reason: 'reserved-log-policy', count: 3 };
+
+ test('a well-formed observation parses', () => {
+ expect(parseBrokenLinkSuppression(wellFormed)).toEqual(wellFormed);
+ });
+
+ test.each([
+ ['absent', undefined],
+ ['a non-object', 'reserved-log-policy'],
+ ['a zero count', { reason: 'reserved-log-policy', count: 0 }],
+ ['a fractional count', { reason: 'reserved-log-policy', count: 1.5 }],
+ ['a missing count', { reason: 'reserved-log-policy' }],
+ ['an empty reason', { reason: '', count: 3 }],
+ ])('%s yields undefined rather than a half-relayed observation', (_label, value) => {
+ expect(parseBrokenLinkSuppression(value)).toBeUndefined();
+ });
+
+ test('a reason this build has no prose for still parses', () => {
+ expect(parseBrokenLinkSuppression({ reason: 'some-future-policy', count: 3 })).toEqual({
+ reason: 'some-future-policy',
+ count: 3,
+ });
+ });
+});
+
describe('the write-warning kind set is the one source both filters read', () => {
const fabricated = {
kind: 'byte-ledger-drift',
diff --git a/packages/server/src/mcp/tools/advisory-warnings.ts b/packages/server/src/mcp/tools/advisory-warnings.ts
index 3f33351da..c2e9eb17c 100644
--- a/packages/server/src/mcp/tools/advisory-warnings.ts
+++ b/packages/server/src/mcp/tools/advisory-warnings.ts
@@ -4,6 +4,8 @@ import {
assertNeverWriteWarning,
type BrokenLink,
BrokenLinkSchema,
+ type BrokenLinkSuppression,
+ BrokenLinkSuppressionSchema,
isWriteWarningKind,
type LintViolationWarning,
type RenderWarning,
@@ -28,6 +30,11 @@ export function parseBrokenLinks(value: unknown): BrokenLink[] {
});
}
+export function parseBrokenLinkSuppression(value: unknown): BrokenLinkSuppression | undefined {
+ const parsed = BrokenLinkSuppressionSchema.safeParse(value);
+ return parsed.success ? parsed.data : undefined;
+}
+
export function formatBrokenLinkLines(links: BrokenLink[]): string[] {
if (links.length === 0) return [];
const header = `⚠ ${links.length} broken outbound link${
diff --git a/packages/server/src/mcp/tools/audit.test.ts b/packages/server/src/mcp/tools/audit.test.ts
index b1f0e7a68..f277fca23 100644
--- a/packages/server/src/mcp/tools/audit.test.ts
+++ b/packages/server/src/mcp/tools/audit.test.ts
@@ -24,6 +24,8 @@ import {
const describe = process.env.CI ? _bunDescribe.skip : _bunDescribe;
+const describeEvenOnCI = _bunDescribe;
+
const BASE_CONFIG: Config = ConfigSchema.parse({});
interface ToolResult {
@@ -154,6 +156,28 @@ beforeAll(async () => {
warnings: [],
});
}
+ if (path === 'suppressed') {
+ return Response.json({
+ ok: true,
+ files: [],
+ fileCount: 4,
+ errorCount: 0,
+ warningCount: 0,
+ warnings: [],
+ brokenLinkSuppression: { reason: 'reserved-log-policy', count: 3 },
+ });
+ }
+ if (path === 'suppressed-malformed') {
+ return Response.json({
+ ok: true,
+ files: [],
+ fileCount: 4,
+ errorCount: 0,
+ warningCount: 0,
+ warnings: [],
+ brokenLinkSuppression: { reason: 'reserved-log-policy' },
+ });
+ }
if (path === 'over-cap') {
return Response.json(auditPayloadOf(AUDIT_FILE_CAP + 2, AUDIT_FILE_DIAGNOSTIC_CAP + 3));
}
@@ -345,6 +369,51 @@ describe('audit — unified project audit', () => {
});
});
+describeEvenOnCI('audit — broken-link suppression', () => {
+ test('a filtered clean audit exposes a content-free suppression marker', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps(baseUrl, tmpDir));
+ const result = await getTool().handler({ path: 'suppressed' });
+ const s = result.structuredContent as {
+ brokenLinkSuppression?: { reason: string; count: number };
+ };
+ expect(s.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 3 });
+ const text = result.content[0]?.text ?? '';
+ expect(text).toContain('3 broken-link findings withheld by project policy');
+ expect(text).toContain('audit result is filtered');
+ expect(text).toContain('does NOT prove every link resolves');
+ expect(text).toContain('links({ kind: "dead" })');
+ expect(text).toContain('not as a repair queue');
+ });
+
+ test('a suppression this build cannot read reaches structuredContent, not only the text block', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps(baseUrl, tmpDir));
+
+ const clean = await getTool().handler({ path: 'clean' });
+ expect((clean.structuredContent as { warnings?: string[] }).warnings).toBeUndefined();
+
+ const result = await getTool().handler({ path: 'suppressed-malformed' });
+ const s = result.structuredContent as {
+ brokenLinkSuppression?: unknown;
+ warnings?: string[];
+ };
+ expect(s.brokenLinkSuppression).toBeUndefined();
+ expect(s.warnings ?? []).toEqual([expect.stringContaining('in a form this build cannot read')]);
+ expect(s.warnings?.[0]).toContain('does NOT prove every link resolves');
+
+ const text = result.content[0]?.text ?? '';
+ expect(text).not.toContain('undefined');
+ expect(text).toContain('could not fully complete');
+ expect(text).toContain('Audit incomplete');
+ expect(text).toContain('withheld by project policy in a form this build cannot read');
+ expect(text).toContain('does NOT prove every link resolves');
+ expect((text.match(/does NOT prove every link resolves/g) ?? []).length).toBe(1);
+ expect(text).toContain('links({ kind: "dead" })');
+ expect(text).toContain('not as a repair queue');
+ });
+});
+
describe('audit — degradation visibility', () => {
test('a degraded run surfaces the warning in text and is not reported as clean', async () => {
const { server, getTool } = createFakeServer();
diff --git a/packages/server/src/mcp/tools/audit.ts b/packages/server/src/mcp/tools/audit.ts
index 021ca077b..8cecbb680 100644
--- a/packages/server/src/mcp/tools/audit.ts
+++ b/packages/server/src/mcp/tools/audit.ts
@@ -1,5 +1,10 @@
-import { validationCoverageLines } from '@inkeep/open-knowledge-core';
+import { BrokenLinkSuppressionSchema, validationCoverageLines } from '@inkeep/open-knowledge-core';
import { z } from 'zod';
+import {
+ formatAuditBrokenLinkSuppressionLine,
+ formatUnreadableAuditSuppressionWarning,
+} from '../../broken-link-suppression.ts';
+import { parseBrokenLinkSuppression } from './advisory-warnings.ts';
import type { ConfigOrResolver, ServerInstance, ServerUrlOrResolver } from './shared.ts';
import {
AUDIT_FILE_CAP,
@@ -25,6 +30,7 @@ export const DESCRIPTION = [
'- The result reports `ran`, the source families selected for this run. Project audit can report `markdownlint`, `frontmatter`, `okf`, and `links`. A family absent from `ran` was not checked. `okf` covers both document and project-tree OKF checks here.',
'- A selected family stays in `ran` if it degrades, with the reason in `warnings`. A partial degradation may still have contributed findings.',
'- To CHECK whether links resolve, use this tool: each broken link is reported under the SOURCE doc that contains it, at the offending line. (The `links` tool is the navigation/graph reader — backlinks, forward links, orphans, hubs — not the validation surface.)',
+ '- Broken links written INSIDE a lowercase-stemmed `log.md`/`log.mdx` are omitted at any depth while the project\'s default-on `validation.suppressLogLinkAdvisories` setting is enabled. When findings are withheld, `brokenLinkSuppression: { reason: "reserved-log-policy", count: N }` makes the filtered result explicit without exposing paths or hrefs. A log is an append-only history whose entries deliberately reference pages that moved or were never written, so repairing them would rewrite that history. `LOG.md` is an ordinary doc and keeps its findings, and `links({ kind: "dead" })` reads the raw state unconditionally.',
'',
"Each diagnostic carries a `source` naming the validator ('markdownlint' rule violations; 'links' broken internal links), a `code` (e.g. MD010, dead-link), `message`, a 0-based LSP `range` (for links: line exact, column approximate), and `severity` ('error' | 'warning' — broken links default to warnings; the project's `validation.links` setting can raise them to errors or hide them). Only files with at least one problem are listed, plus `fileCount`/`errorCount`/`warningCount` totals. Output (text and structured) is capped at 10 files × 10 diagnostics per file and project-wide at 10 warnings, with explicit '… and N more' indicators and `omittedWarningCount` when warnings are dropped; the counts always reflect the full scan — re-run with `path` scoped to a folder or file to see what was omitted.",
'',
@@ -62,6 +68,7 @@ interface AuditResponsePayload {
warningCount?: number;
warnings?: string[];
ran?: string[];
+ brokenLinkSuppression?: unknown;
}
export interface AuditDeps {
@@ -103,6 +110,9 @@ export function register(server: ServerInstance, deps: AuditDeps): void {
.describe(
'Validation source families selected for this run. A family absent from `ran` was not checked.',
),
+ brokenLinkSuppression: BrokenLinkSuppressionSchema.optional().describe(
+ 'Present when the reserved-log policy withheld broken-link findings. Carries only the reason and count, never paths or hrefs. Absent both when nothing was withheld and when a withholding arrived in a shape this build cannot validate. In that second case `warnings` carries the disclosure, so an empty `brokenLinkSuppression` beside a non-empty `warnings` is not an all-clear.',
+ ),
omittedWarningCount: z
.number()
.optional()
@@ -144,6 +154,13 @@ async function runAudit(path: string | undefined, url: string, cwd: string) {
const errorCount = data.errorCount ?? 0;
const warningCount = data.warningCount ?? 0;
const coverageLines = validationCoverageLines(data.ran);
+ const rawSuppression = data.brokenLinkSuppression;
+ const suppressionPresent = rawSuppression !== undefined && rawSuppression !== null;
+ const suppression = parseBrokenLinkSuppression(rawSuppression);
+ const suppressionUnreadable = suppressionPresent && suppression === undefined;
+ const suppressionLine = suppression
+ ? formatAuditBrokenLinkSuppressionLine(suppression, { surface: 'mcp' })
+ : undefined;
const shownFiles = files.slice(0, AUDIT_FILE_CAP).map((file) => {
const diagnostics = file.diagnostics ?? [];
@@ -157,7 +174,10 @@ async function runAudit(path: string | undefined, url: string, cwd: string) {
});
const omittedFileCount = files.length - shownFiles.length;
- const warnings = data.warnings ?? [];
+ const warnings = [
+ ...(suppressionUnreadable ? [formatUnreadableAuditSuppressionWarning({ surface: 'mcp' })] : []),
+ ...(data.warnings ?? []),
+ ];
const { shownWarnings, omittedWarningCount } = capAuditWarnings(warnings);
const structured = {
@@ -166,6 +186,7 @@ async function runAudit(path: string | undefined, url: string, cwd: string) {
errorCount,
warningCount,
...(data.ran === undefined ? {} : { ran: data.ran }),
+ ...(suppression === undefined ? {} : { brokenLinkSuppression: suppression }),
...(shownWarnings.length > 0 ? { warnings: shownWarnings } : {}),
...(omittedWarningCount > 0 ? { omittedWarningCount } : {}),
...(omittedFileCount > 0 ? { omittedFileCount } : {}),
@@ -180,7 +201,15 @@ async function runAudit(path: string | undefined, url: string, cwd: string) {
warnings.length > 0
? `No problems found across ${fileCount} document${fileCount === 1 ? '' : 's'}${scope}, but the audit could not fully complete.`
: `No problems across ${fileCount} document${fileCount === 1 ? '' : 's'}${scope}.`;
- return textPlusStructured([summary, ...coverageLines, ...warningBlock].join('\n'), structured);
+ return textPlusStructured(
+ [
+ summary,
+ ...(suppressionLine === undefined ? [] : [suppressionLine]),
+ ...coverageLines,
+ ...warningBlock,
+ ].join('\n'),
+ structured,
+ );
}
const header = `${files.length} of ${fileCount} document${fileCount === 1 ? '' : 's'}${scope} with problems — ${countSummary(errorCount, warningCount)}:`;
const fileBlocks = shownFiles.map((file) => {
@@ -197,9 +226,15 @@ async function runAudit(path: string | undefined, url: string, cwd: string) {
? [`… and ${omittedFileCount} more file${omittedFileCount === 1 ? '' : 's'} with problems`]
: [];
return textPlusStructured(
- [header, ...fileBlocks, ...footer, ...warningBlock, FIX_ROUTING_HINT, ...coverageLines].join(
- '\n',
- ),
+ [
+ header,
+ ...fileBlocks,
+ ...footer,
+ ...warningBlock,
+ ...(suppressionLine === undefined ? [] : [suppressionLine]),
+ FIX_ROUTING_HINT,
+ ...coverageLines,
+ ].join('\n'),
structured,
);
}
diff --git a/packages/server/src/mcp/tools/edit.ts b/packages/server/src/mcp/tools/edit.ts
index 87fc41dbe..6fccc6f1e 100644
--- a/packages/server/src/mcp/tools/edit.ts
+++ b/packages/server/src/mcp/tools/edit.ts
@@ -7,6 +7,7 @@ import {
} from '@inkeep/open-knowledge-core';
import { parse as parseYaml } from 'yaml';
import { z } from 'zod';
+import { formatBrokenLinkSuppressionLine } from '../../broken-link-suppression.ts';
import { resolveContentDir, resolveLockDir } from '../../config/paths.ts';
import { mergePatch } from '../../content/frontmatter-merge.ts';
import type { TemplateFrontmatter } from '../../content/templates-write.ts';
@@ -16,6 +17,7 @@ import {
formatAdvisoryLines,
formatBrokenLinkLines,
parseAdvisoryWarnings,
+ parseBrokenLinkSuppression,
parseBrokenLinks,
} from './advisory-warnings.ts';
import { resolveWithinRoot } from './path-safety.ts';
@@ -273,6 +275,7 @@ function composeWritePreviewResult(
const summaryHint = typeof summaryResult?.hint === 'string' ? summaryResult.hint : undefined;
const advisoryWarnings = parseAdvisoryWarnings(result.warnings);
const brokenLinks = parseBrokenLinks(result.brokenLinks);
+ const brokenLinkSuppression = parseBrokenLinkSuppression(result.brokenLinkSuppression);
const lines: string[] = [leadLine];
if (noPreviewAnywhere && !preview) lines.push(START_UI_TEXT_HINT);
@@ -281,10 +284,12 @@ function composeWritePreviewResult(
lines.push(...formatAdvisoryLines(advisoryWarnings));
}
lines.push(...formatBrokenLinkLines(brokenLinks));
+ if (brokenLinkSuppression) lines.push(formatBrokenLinkSuppressionLine(brokenLinkSuppression));
const text = lines.join('\n');
const document: Record<string, unknown> = {
brokenLinks,
};
+ if (brokenLinkSuppression) document.brokenLinkSuppression = brokenLinkSuppression;
if (summaryResult) document.summary = summaryResult;
if (advisoryWarnings) document.warnings = advisoryWarnings;
const warning = noPreviewAnywhere ? buildPreviewAttachWarning(preview, autoOpen) : undefined;
@@ -651,7 +656,7 @@ export function register(server: ServerInstance, deps: EditDeps): void {
.object(documentResultBaseShape)
.optional()
.describe(
- 'Document edit result. Always present on a successful document edit (body or frontmatter) — it carries `brokenLinks` (possibly `[]`) plus any `summary`/`warnings`. Absent only for folder/template edits.',
+ 'Document edit result. Always present on a successful document edit (body or frontmatter) — it carries `brokenLinks` (possibly `[]`) plus any `brokenLinkSuppression`/`summary`/`warnings`. Read `brokenLinkSuppression` before concluding anything from an empty `brokenLinks`: when it is present, a project policy withheld findings and none of them is yours to repair. Absent only for folder/template edits.',
),
folder: z
.object({
diff --git a/packages/server/src/mcp/tools/links.ts b/packages/server/src/mcp/tools/links.ts
index e50437726..75f0f56fa 100644
--- a/packages/server/src/mcp/tools/links.ts
+++ b/packages/server/src/mcp/tools/links.ts
@@ -24,7 +24,7 @@ export const DESCRIPTION = [
'[Requires: Hocuspocus server] Read the wiki-link graph. `kind` takes one value, or an array for a one-call audit — results merge into a single payload; any per-kind failure lands in an `errors` map.',
'',
'- `backlinks` / `forward` / `suggest` — operate on one page; require `document`. `suggest` finds prose mentions of the page not yet wrapped in link syntax. Each mention returns an `excerpt` (a normalized, `…`-trimmed snippet for context — NOT an edit-ready literal) plus an `offset`. To wrap one: re-read the doc (`exec("cat …")`), find the real mention text, and `edit` it into a `[[wiki-link]]`.',
- '- `dead` — missing internal link targets corpus-wide; optional `sourceDocuments` filter (OR semantics).',
+ "- `dead` — missing internal link targets corpus-wide; optional `sourceDocuments` filter (OR semantics). This is the raw graph read: unlike `audit`, it still lists unresolved links whose source is a skill document or a lowercase-stemmed `log.md`/`log.mdx` — read those to audit deliberately, never as a repair queue, and never rewrite a log's existing entries to clear one.",
'- `orphans` — disconnected pages; optional `mode`: `incoming` | `outgoing` | `both`.',
'- `hubs` — most-linked pages; optional `limit` (default 20).',
].join('\n');
diff --git a/packages/server/src/mcp/tools/shared.ts b/packages/server/src/mcp/tools/shared.ts
index 1943d3367..2e618534e 100644
--- a/packages/server/src/mcp/tools/shared.ts
+++ b/packages/server/src/mcp/tools/shared.ts
@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
import {
AdvisoryWarningSchema,
BrokenLinkSchema,
+ BrokenLinkSuppressionSchema,
validateDocName,
} from '@inkeep/open-knowledge-core';
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -82,9 +83,13 @@ export const previewAttachWarningField = z
const brokenLinksOutputField = z
.array(BrokenLinkSchema)
.describe(
- 'Outbound internal links in the just-written doc that do not resolve. Always present — `[]` means every link resolves. Each: `{ href (as written), resolvedTo (the docName or content-root file path it pointed at, or null), reason: "no-such-doc" | "no-such-file" | "unresolvable" }`. Report-only — the write landed regardless; fix in a follow-up edit.',
+ 'Outbound internal links in the just-written doc that do not resolve. Always present — `[]` means every link resolves UNLESS `brokenLinkSuppression` is also present, in which case a project policy withheld findings. A withholding that arrives in a shape this build cannot validate is dropped rather than relayed, so `brokenLinkSuppression` stays absent even though findings were withheld. The `audit` tool is the surface that discloses that case, through its `warnings`. Each: `{ href (as written), resolvedTo (the docName or content-root file path it pointed at, or null), reason: "no-such-doc" | "no-such-file" | "unresolvable" }`. Report-only — the write landed regardless; fix in a follow-up edit.',
);
+const brokenLinkSuppressionOutputField = BrokenLinkSuppressionSchema.optional().describe(
+ 'Present ONLY when a project policy omitted detected broken links from `brokenLinks` — so an empty `brokenLinks` beside it does NOT mean every link resolves. `{ reason, count }`; `reason` today is `"reserved-log-policy"` (a reserved `log.md` records history whose links are expected not to resolve) and is an open token, so treat one you do not recognize as a withholding policy all the same. `count` is how many findings were withheld; the hrefs are deliberately not returned, because none of them is yours to repair.',
+);
+
export function docExtensionOnDisk(
contentDir: string,
docName: string,
@@ -106,6 +111,7 @@ export const documentResultBaseShape = {
"Advisory entries discriminated by `kind`. Write-integrity kinds — `content-divergence` (converged Y.Text didn't byte-match what you composed) and `disk-edit-reconciled` (an out-of-band disk edit was folded in before your write) — mean re-read the doc. The renderability kind `mermaid-parse-error` means the write landed but that fence will not render — fix it and re-edit.",
),
brokenLinks: brokenLinksOutputField,
+ brokenLinkSuppression: brokenLinkSuppressionOutputField,
templateHint: z
.array(z.object({ name: z.string(), description: z.string().optional() }))
.min(1)
diff --git a/packages/server/src/mcp/tools/write-link-suppression.test.ts b/packages/server/src/mcp/tools/write-link-suppression.test.ts
new file mode 100644
index 000000000..06ecabd0d
--- /dev/null
+++ b/packages/server/src/mcp/tools/write-link-suppression.test.ts
@@ -0,0 +1,243 @@
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { normalizeObjectSchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
+import { describe, expect, test } from 'vitest';
+import { type Config, ConfigSchema } from '../../config/schema.ts';
+import { register as registerEdit } from './edit.ts';
+import { startFetchTestServer } from './fetch-test-server.test-helper.ts';
+import type { ServerInstance } from './shared.ts';
+import { register as registerWrite } from './write.ts';
+
+const BASE_CONFIG: Config = ConfigSchema.parse({});
+
+interface ToolResult {
+ content: Array<{ type: 'text'; text: string }>;
+ structuredContent?: Record<string, unknown>;
+ isError?: true;
+}
+type Handler = (args: Record<string, unknown>) => Promise<ToolResult>;
+
+const REPAIR_HEADER = 'broken outbound link';
+
+function textOf(r: ToolResult): string {
+ return r.content.map((c) => c.text).join('\n');
+}
+
+function docOf(r: ToolResult): Record<string, unknown> {
+ return (r.structuredContent?.document ?? {}) as Record<string, unknown>;
+}
+
+function batchOf(r: ToolResult): Array<Record<string, unknown>> {
+ return (r.structuredContent?.documents ?? []) as Array<Record<string, unknown>>;
+}
+
+interface CapturedTool {
+ handler: Handler;
+ clientSchema: Record<string, unknown>;
+}
+
+interface StubbedTools {
+ write: Handler;
+ edit: Handler;
+ writeTool: CapturedTool;
+ editTool: CapturedTool;
+}
+
+async function withStub(
+ payload: Record<string, unknown>,
+ body: (tools: StubbedTools) => Promise<void>,
+): Promise<void> {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-mcp-link-suppression-'));
+ const stub = await startFetchTestServer({
+ port: 0,
+ async fetch(req) {
+ if (req.method !== 'POST') return Response.json({ error: 'unexpected' }, { status: 404 });
+ const reqBody = (await req.json()) as { docName?: string };
+ return Response.json({
+ docName: reqBody.docName,
+ systemSubscriberCount: 1,
+ timestamp: '2026-08-28T00:00:00.000Z',
+ ...payload,
+ });
+ },
+ });
+ const capture = <D>(register: (server: ServerInstance, deps: D) => void): CapturedTool => {
+ let captured: CapturedTool | undefined;
+ const server = {
+ registerTool(_name: string, cfg: { outputSchema?: unknown }, handler: Handler) {
+ const normalized = normalizeObjectSchema(cfg.outputSchema);
+ if (!normalized) throw new Error('outputSchema did not normalize to an object schema');
+ captured = {
+ handler,
+ clientSchema: toJsonSchemaCompat(normalized, {
+ strictUnions: true,
+ pipeStrategy: 'output',
+ }) as Record<string, unknown>,
+ };
+ },
+ } as unknown as ServerInstance;
+ register(server, {
+ serverUrl: `http://127.0.0.1:${stub.port}`,
+ config: BASE_CONFIG,
+ resolveCwd: async () => cwd,
+ } as unknown as D);
+ if (!captured) throw new Error('tool did not register');
+ return captured;
+ };
+ try {
+ const writeTool = capture(registerWrite);
+ const editTool = capture(registerEdit);
+ await body({
+ write: writeTool.handler,
+ edit: editTool.handler,
+ writeTool,
+ editTool,
+ });
+ } finally {
+ stub.stop(true);
+ }
+}
+
+const SUPPRESSED_TWO = {
+ brokenLinks: [],
+ brokenLinkSuppression: { reason: 'reserved-log-policy', count: 2 },
+};
+
+describe('write/edit relay a policy suppression instead of a bare empty list', () => {
+ test('a suppressed single-doc write reports the count and no repair work', async () => {
+ await withStub(SUPPRESSED_TWO, async ({ write }) => {
+ const r = await write({ document: { path: 'notes/log', content: '# Log\n' } });
+ expect(r.isError).toBeUndefined();
+ expect(docOf(r).brokenLinks).toEqual([]);
+ expect(docOf(r).brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
+ const text = textOf(r);
+ expect(text).toContain('2');
+ expect(text).not.toContain(REPAIR_HEADER);
+ });
+ });
+
+ test('a suppressed body edit reports the count and no repair work', async () => {
+ await withStub(SUPPRESSED_TWO, async ({ edit }) => {
+ const r = await edit({ document: { path: 'notes/log', find: 'a', replace: 'b' } });
+ expect(r.isError).toBeUndefined();
+ expect(docOf(r).brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
+ expect(textOf(r)).not.toContain(REPAIR_HEADER);
+ });
+ });
+
+ test('a suppressed frontmatter edit reports the count', async () => {
+ await withStub(SUPPRESSED_TWO, async ({ edit }) => {
+ const r = await edit({ document: { path: 'notes/log', frontmatter: { title: 'Log' } } });
+ expect(r.isError).toBeUndefined();
+ expect(docOf(r).brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
+ });
+ });
+
+ test('a suppressed batch entry carries its own count', async () => {
+ await withStub(
+ { brokenLinks: [], brokenLinkSuppression: { reason: 'reserved-log-policy', count: 1 } },
+ async ({ write }) => {
+ const r = await write({
+ documents: [
+ { path: 'notes/log', content: '# Log\n' },
+ { path: 'archive/log', content: '# Archive log\n' },
+ ],
+ });
+ expect(r.isError).toBeUndefined();
+ const entries = batchOf(r);
+ expect(entries).toHaveLength(2);
+ for (const entry of entries) {
+ expect(entry.brokenLinks).toEqual([]);
+ expect(entry.brokenLinkSuppression).toEqual({
+ reason: 'reserved-log-policy',
+ count: 1,
+ });
+ }
+ const text = textOf(r);
+ expect(text).toContain('1 broken-link finding withheld');
+ expect(text).not.toContain(REPAIR_HEADER);
+ },
+ );
+ });
+
+ test('a suppressed body validates against the schema the client enforces', async () => {
+ await withStub(SUPPRESSED_TWO, async ({ write, edit, writeTool, editTool }) => {
+ const validator = new AjvJsonSchemaValidator();
+ const cases: Array<[CapturedTool, ToolResult]> = [
+ [writeTool, await write({ document: { path: 'notes/log', content: '# Log\n' } })],
+ [editTool, await edit({ document: { path: 'notes/log', find: 'a', replace: 'b' } })],
+ ];
+ for (const [tool, result] of cases) {
+ expect(docOf(result).brokenLinkSuppression).toBeDefined();
+ const validate = validator.getValidator(tool.clientSchema);
+ expect(validate(result.structuredContent)).toMatchObject({ valid: true });
+ }
+ });
+ });
+
+ test('the text says an empty list is not a clean bill of health', async () => {
+ await withStub(SUPPRESSED_TWO, async ({ write }) => {
+ const r = await write({ document: { path: 'notes/log', content: '# Log\n' } });
+ expect(textOf(r)).toContain('does NOT mean every link resolves');
+ });
+ });
+
+ test('a policy this build predates still qualifies the empty list on both channels', async () => {
+ await withStub(
+ { brokenLinks: [], brokenLinkSuppression: { reason: 'some-future-policy', count: 2 } },
+ async ({ write, writeTool }) => {
+ const r = await write({ document: { path: 'notes/log', content: '# Log\n' } });
+ expect(docOf(r).brokenLinkSuppression).toEqual({
+ reason: 'some-future-policy',
+ count: 2,
+ });
+ expect(textOf(r)).toContain('does NOT mean every link resolves');
+ expect(textOf(r)).not.toContain(REPAIR_HEADER);
+ const validate = new AjvJsonSchemaValidator().getValidator(writeTool.clientSchema);
+ expect(validate(r.structuredContent)).toMatchObject({ valid: true });
+ },
+ );
+ });
+});
+
+describe('an unsuppressed response is relayed exactly as before', () => {
+ test('real broken links keep their repair lines and carry no suppression', async () => {
+ await withStub(
+ { brokenLinks: [{ href: './gone.md', resolvedTo: 'gone', reason: 'no-such-doc' }] },
+ async ({ write, edit }) => {
+ for (const r of [
+ await write({ document: { path: 'notes/plan', content: '# Plan\n' } }),
+ await edit({ document: { path: 'notes/plan', find: 'a', replace: 'b' } }),
+ ]) {
+ expect(r.isError).toBeUndefined();
+ expect(docOf(r).brokenLinkSuppression).toBeUndefined();
+ expect(textOf(r)).toContain('1 broken outbound link — fix or remove');
+ expect(textOf(r)).toContain('./gone.md → gone (no-such-doc)');
+ }
+ },
+ );
+ });
+
+ test('a clean write carries neither repair lines nor a suppression field', async () => {
+ await withStub({ brokenLinks: [] }, async ({ write }) => {
+ const r = await write({ document: { path: 'notes/plan', content: '# Plan\n' } });
+ expect(docOf(r).brokenLinks).toEqual([]);
+ expect(docOf(r).brokenLinkSuppression).toBeUndefined();
+ expect(textOf(r)).not.toContain('withheld');
+ });
+ });
+
+ test('a malformed suppression object is dropped rather than relayed, because a write advisory has no untyped warnings channel to disclose it through', async () => {
+ await withStub(
+ { brokenLinks: [], brokenLinkSuppression: { reason: 'reserved-log-policy', count: 0 } },
+ async ({ write }) => {
+ const r = await write({ document: { path: 'notes/log', content: '# Log\n' } });
+ expect(docOf(r).brokenLinkSuppression).toBeUndefined();
+ expect(textOf(r)).not.toContain('withheld');
+ },
+ );
+ });
+});
diff --git a/packages/server/src/mcp/tools/write.ts b/packages/server/src/mcp/tools/write.ts
index c02204046..ce5fd8638 100644
--- a/packages/server/src/mcp/tools/write.ts
+++ b/packages/server/src/mcp/tools/write.ts
@@ -14,6 +14,10 @@ import {
withFences,
} from '@inkeep/open-knowledge-core';
import { z } from 'zod';
+import {
+ formatBrokenLinkSuppressionBrief,
+ formatBrokenLinkSuppressionLine,
+} from '../../broken-link-suppression.ts';
import { resolveContentDir, resolveLockDir } from '../../config/paths.ts';
import { mergePatch } from '../../content/frontmatter-merge.ts';
import { parentFolderOf } from '../../content/nested-folder-rules.ts';
@@ -28,6 +32,7 @@ import {
formatBrokenLinkBrief,
formatBrokenLinkLines,
parseAdvisoryWarnings,
+ parseBrokenLinkSuppression,
parseBrokenLinks,
} from './advisory-warnings.ts';
import { buildPreviewAttachWarning, resolvePreviewUrl, START_UI_TEXT_HINT } from './preview-url.ts';
@@ -661,6 +666,7 @@ async function handleBatch(
const preview = resolvePreviewUrl(r.docName, { lockDir });
const warnings = parseAdvisoryWarnings(r.raw.warnings);
const brokenLinks = parseBrokenLinks(r.raw.brokenLinks);
+ const brokenLinkSuppression = parseBrokenLinkSuppression(r.raw.brokenLinkSuppression);
return {
docName: r.docName,
ok: true as const,
@@ -669,6 +675,7 @@ async function handleBatch(
...(warnings ? { warnings } : {}),
...(r.templateHint ? { templateHint: r.templateHint } : {}),
brokenLinks,
+ ...(brokenLinkSuppression ? { brokenLinkSuppression } : {}),
};
});
const okCount = docOut.filter((d) => d.ok).length;
@@ -687,6 +694,9 @@ async function handleBatch(
if (d?.ok) {
const brokenBrief = formatBrokenLinkBrief(d.brokenLinks);
if (brokenBrief) baseParts.push(brokenBrief);
+ if (d.brokenLinkSuppression) {
+ baseParts.push(formatBrokenLinkSuppressionBrief(d.brokenLinkSuppression));
+ }
}
if (r.ok && r.templateHint) {
baseParts.push(
@@ -737,6 +747,7 @@ async function handleSingleDoc(
const summaryHint = typeof summaryResult?.hint === 'string' ? summaryResult.hint : undefined;
const advisoryWarnings = parseAdvisoryWarnings(result.warnings);
const brokenLinks = parseBrokenLinks(result.brokenLinks);
+ const brokenLinkSuppression = parseBrokenLinkSuppression(result.brokenLinkSuppression);
const noOpNote = emptyAppendNoOpNote(w.position, spec.content);
const lines: string[] = [
@@ -759,12 +770,14 @@ async function handleSingleDoc(
lines.push(...formatAdvisoryLines(advisoryWarnings));
}
lines.push(...formatBrokenLinkLines(brokenLinks));
+ if (brokenLinkSuppression) lines.push(formatBrokenLinkSuppressionLine(brokenLinkSuppression));
if (w.templateHint) lines.push(formatTemplateHintLine(w.templateHint));
const text = lines.join('\n');
const document: Record<string, unknown> = {
brokenLinks,
};
+ if (brokenLinkSuppression) document.brokenLinkSuppression = brokenLinkSuppression;
if (hints) document.hints = hints;
if (summaryResult) document.summary = summaryResult;
if (advisoryWarnings) document.warnings = advisoryWarnings;
@@ -910,7 +923,7 @@ export function register(server: ServerInstance, deps: WriteDeps): void {
})
.optional()
.describe(
- 'Single-document write result. Always present on a successful single-doc write — it carries `brokenLinks` (possibly `[]`) plus any `summary`/`hints`/`warnings`.',
+ 'Single-document write result. Always present on a successful single-doc write — it carries `brokenLinks` (possibly `[]`) plus any `brokenLinkSuppression`/`summary`/`hints`/`warnings`. Read `brokenLinkSuppression` before concluding anything from an empty `brokenLinks`: when it is present, a project policy withheld findings and none of them is yours to repair.',
),
folder: z
.object({
@@ -964,7 +977,7 @@ export function register(server: ServerInstance, deps: WriteDeps): void {
documents: looseObjectArray
.optional()
.describe(
- 'Batch write: per-doc result `{ docName, ok, position?, previewUrl?, warnings?, brokenLinks, error? }`. `brokenLinks` (possibly `[]`) is present on each successful entry, same as a single-doc write.',
+ 'Batch write: per-doc result `{ docName, ok, position?, previewUrl?, warnings?, brokenLinks, brokenLinkSuppression?, error? }`. `brokenLinks` (possibly `[]`) is present on each successful entry, same as a single-doc write — and, same as a single-doc write, an empty list means every link resolves only on entries carrying no `brokenLinkSuppression`.',
),
previewUrl: previewUrlOutputField.optional(),
previewUrlSource: previewUrlSourceField,
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 20bba1fcc..87595bae1 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -25,10 +25,10 @@ import {
DEFAULT_ATTACHMENT_FOLDER_PATH,
DEFAULT_LINKS_VALIDATION,
DEFAULT_LINTER_CONFIG,
+ DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
DOCUMENT_OPEN_BYTE_LIMIT,
humanFormat,
isKnownConfigError,
- type LinksValidationSetting,
type LinterConfig,
type MarkdownManager,
modeFromCommittedDefault,
@@ -190,6 +190,7 @@ import {
isHostAdmitted,
isPeerAdmitted,
} from './ingress-policy.ts';
+import type { LinkAdvisoryPolicy } from './link-advisory-policy.ts';
import { ensureOkfSchemaFiles } from './lint/write-okf-schemas.ts';
import { createLiveDerivedIndexExtension } from './live-derived-index.ts';
import { localTargetInventoryFromWatcher } from './local-target-inventory.ts';
@@ -590,14 +591,18 @@ export function createServer(options: ServerOptions): ServerInstance {
return base;
}
- function readLinksValidationSetting(): LinksValidationSetting {
+ function readLinkAdvisoryPolicy(): LinkAdvisoryPolicy {
const project = readConfigSafely({
absPath: resolveConfigPath('project', projectDir),
sideline: false,
warn: (message) =>
log.warn({ message }, '[config] could not read project config for link validation'),
});
- return project.value.validation?.links ?? DEFAULT_LINKS_VALIDATION;
+ return {
+ links: project.value.validation?.links ?? DEFAULT_LINKS_VALIDATION,
+ suppressLogLinkAdvisories:
+ project.value.validation?.suppressLogLinkAdvisories ?? DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
+ };
}
function readSemanticSearchConfig(): ResolvedSemanticConfig {
@@ -668,6 +673,7 @@ export function createServer(options: ServerOptions): ServerInstance {
}
let lastAppliedAttachmentFolderPath: string | undefined;
+ let projectConfigEpoch = 0;
function applyPersistedConfigToConsumers(
configDocName: string,
@@ -697,6 +703,7 @@ export function createServer(options: ServerOptions): ServerInstance {
maxBatchSize: semCfg.maxBatchSize,
});
if (configDocName === CONFIG_DOC_NAME_PROJECT) {
+ projectConfigEpoch += 1;
try {
const nextAttachmentFolderPath = readProjectAttachmentFolderPath({ requireValid: true });
contentFilter?.setAttachmentFolderPath(nextAttachmentFolderPath);
@@ -2068,7 +2075,8 @@ export function createServer(options: ServerOptions): ServerInstance {
semanticSearch,
getSemanticSimilarityFloor: () => readSemanticSearchConfig().similarityFloor,
getLinterBaseConfig: () => readLinterBaseConfig(),
- getLinksValidationSetting: () => readLinksValidationSetting(),
+ getLinkAdvisoryPolicy: readLinkAdvisoryPolicy,
+ getProjectConfigEpoch: () => projectConfigEpoch,
getLinkPreviewsEnabled: readLinkPreviewsEnabled,
getConfigDiagnostics: readConfigDiagnostics,
embeddingsSecretsFile: secretsFilePath(configHomedirOverride),
diff --git a/packages/server/src/skill-linking-contract.test.ts b/packages/server/src/skill-linking-contract.test.ts
index af8459cc1..3dcf714c9 100644
--- a/packages/server/src/skill-linking-contract.test.ts
+++ b/packages/server/src/skill-linking-contract.test.ts
@@ -30,6 +30,18 @@ describe('bundled project skill — link-authoring contract', () => {
expect(linking).toContain('Never glue `./` onto a content-root path');
});
+ test('core keeps the positive rule AND qualifies it with the suppression field', () => {
+ expect(skill).toContain('`[]` means all links resolve');
+ expect(skill).toContain('brokenLinkSuppression');
+ expect(skill).toContain('not yours to repair');
+ });
+
+ test('linking reference makes the empty list conditional and forbids repairing log history', () => {
+ expect(linking).toContain('`brokenLinkSuppression`');
+ expect(linking).toContain('does not mean every link resolves');
+ expect(linking).toContain('Never rewrite a reserved log');
+ });
+
test('linking reference makes brokenLinks the primary check + names `audit` as the end-state check', () => {
expect(linking).toMatch(/`brokenLinks`[^\n]*primary check/);
expect(linking).toContain('`audit` is the authoritative end-state link check');