Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(docs): repair 3 broken doc links; extend link check to all docs (#4956)

LearningCircuitbc03e1cceb7d
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e89e2d0a78..cad3c1f56c 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -333,15 +333,16 @@ repos:
pass_filenames: false
description: "Ensure docs/decisions ADR numbers are unique (no two files share a NNNN prefix)"
- id: check-readme-links
- name: Check README links and examples
+ name: Check README/docs links and examples
entry: .pre-commit-hooks/check-readme-links.py
language: script
pass_filenames: false
files: ^(README\.md|SECURITY\.md|CONTRIBUTING\.md|docs/.*\.md|src/local_deep_research/web_search_engines/engine_registry\.py)$
- description: "Validate README.md relative links, heading anchors,
- python -m examples, and engine=... names against the repo, so
- renamed docs/headings or removed modules/engines can't silently
- break the project storefront"
+ description: "Validate relative links, heading anchors, python -m
+ examples, and engine=... names in README.md, SECURITY.md,
+ CONTRIBUTING.md, and docs/**.md against the repo, so renamed
+ files/headings or removed modules/engines can't silently break
+ the documentation"
- id: check-layer-imports
name: Check infrastructure packages don't import from web/
entry: .pre-commit-hooks/check-layer-imports.py
diff --git a/.pre-commit-hooks/check-readme-links.py b/.pre-commit-hooks/check-readme-links.py
index a5c5c41024..482f28e80f 100755
--- a/.pre-commit-hooks/check-readme-links.py
+++ b/.pre-commit-hooks/check-readme-links.py
@@ -6,7 +6,9 @@ get renamed, CLI entry points change, and example snippets keep naming
things that no longer exist. A 2026-07 audit found a benchmark command
that had never been runnable, a `reset` example missing its required
flag, and an MCP example querying a search engine that was never
-implemented. This hook catches those drift classes at commit time:
+implemented. This hook catches those drift classes at commit time, in
+README.md, SECURITY.md, CONTRIBUTING.md, and every markdown file under
+docs/:
1. Relative markdown links must point at files/directories that exist.
2. Anchor fragments (``docs/faq.md#some-heading`` or same-file
@@ -19,6 +21,11 @@ implemented. This hook catches those drift classes at commit time:
4. ``engine="<name>"`` examples must name an engine registered in
``ENGINE_REGISTRY`` (parsed from engine_registry.py).
+Links inside fenced code blocks are exempt from check 1/2 -- GitHub does
+not render them, and they are usually example markup (e.g. runtime
+``/static/...`` paths in an HTML snippet). Checks 3/4 deliberately DO
+look inside code blocks; that is where the examples live.
+
External (http/https/mailto) links are not checked -- no network access
at commit time.
"""
@@ -31,8 +38,9 @@ from urllib.parse import unquote, urlparse
REPO_ROOT = Path(__file__).resolve().parent.parent
-# Files whose internal references this hook validates.
-CHECKED_FILES = ["README.md"]
+# Fixed files whose internal references this hook validates; every
+# markdown file under docs/ is added at runtime in main().
+CHECKED_FILES = ["README.md", "SECURITY.md", "CONTRIBUTING.md"]
ENGINE_REGISTRY_PATH = Path(
"src/local_deep_research/web_search_engines/engine_registry.py"
@@ -91,6 +99,18 @@ def heading_slugs(md_text: str) -> set:
return {github_slug(h) for h in iter_headings(md_text)}
+def strip_fences(md_text: str) -> str:
+ """Blank out fenced code blocks; GitHub renders no links inside them."""
+ out, in_fence = [], False
+ for line in md_text.splitlines():
+ if FENCE.match(line):
+ in_fence = not in_fence
+ out.append("")
+ continue
+ out.append("" if in_fence else line)
+ return "\n".join(out)
+
+
def check_anchor(target: Path, fragment: str) -> str:
"""Return an error message for a bad anchor, or '' if it resolves."""
line_match = LINE_ANCHOR.match(fragment)
@@ -188,29 +208,34 @@ def main() -> int:
args = parser.parse_args()
root = args.root.resolve()
+ files = [root / name for name in CHECKED_FILES] + sorted(
+ root.glob("docs/**/*.md")
+ )
+
all_errors = []
- for name in CHECKED_FILES:
- md_path = root / name
+ for md_path in files:
+ name = str(md_path.relative_to(root))
if not md_path.is_file():
all_errors.append((name, "file is missing"))
continue
text = md_path.read_text(encoding="utf-8")
for error in (
- check_links(md_path, text)
+ check_links(md_path, strip_fences(text))
+ check_python_modules(root, text)
+ check_engine_names(root, text)
):
all_errors.append((name, error))
if all_errors:
- print("❌ README REFERENCES SOMETHING THAT DOES NOT EXIST")
+ print("❌ DOCUMENTATION REFERENCES SOMETHING THAT DOES NOT EXIST")
print("=" * 60)
for name, error in all_errors:
print(f"📄 {name}: {error}")
print("=" * 60)
print("FIX: update the link/example to match the repo, or fix the")
print("hook if GitHub's anchor rules are approximated incorrectly")
- print("(.pre-commit-hooks/check-readme-links.py).")
+ print("(.pre-commit-hooks/check-readme-links.py). Links inside")
+ print("fenced code blocks are already exempt.")
return 1
return 0
diff --git a/docs/deployment/unraid.md b/docs/deployment/unraid.md
index eeddd4139b..99bf3312aa 100644
--- a/docs/deployment/unraid.md
+++ b/docs/deployment/unraid.md
@@ -31,7 +31,7 @@ This is the easiest method for Unraid users.
1. Go back to **Docker** tab
2. Click **Add Container**
3. In the **Template** dropdown, select **LocalDeepResearch**
-4. Review the configuration (see [Configuration](#configuration) section below)
+4. Review the configuration (see [Configuration](#-configuration) section below)
5. Click **Apply**
#### Step 3: (Optional) Install Companion Containers
diff --git a/docs/processes/review-process/README.md b/docs/processes/review-process/README.md
index 95fd6e4a20..2e4c88f3f7 100644
--- a/docs/processes/review-process/README.md
+++ b/docs/processes/review-process/README.md
@@ -135,7 +135,7 @@ PR #3847 was the working example for this pattern: a moltenbot PR with a sound a
## When to escalate
-- **Security findings during review** (exposed secrets, auth bypass, injection): apply `security-review-needed` and ping `@LearningCircuit`. See [`docs/SECURITY_REVIEW_PROCESS.md`](../../SECURITY_REVIEW_PROCESS.md) for the security-specific flow.
+- **Security findings during review** (exposed secrets, auth bypass, injection): apply `security-review-needed` and ping `@LearningCircuit`. See the [security review process](../security-review-process/README.md) for the security-specific flow.
- **Legal or licensing concerns**: core team only (`@LearningCircuit @hashedviking @djpetti`). Do not merge.
- **Persistent disagreement on approach**: pause, take it to Discord or an issue for broader input rather than escalating in PR comments.
diff --git a/docs/release_notes/1.7.0.md b/docs/release_notes/1.7.0.md
index 6ea94b292b..704f388ade 100644
--- a/docs/release_notes/1.7.0.md
+++ b/docs/release_notes/1.7.0.md
@@ -11,7 +11,7 @@
### ✨ New Features
-- **Chat Mode** — Interactive multi-turn research conversations. Each session accumulates context across turns (entities, topics, source count), streams research steps and citations live as the answer is built, and persists in your per-user database (encrypted by default). Sessions can be archived, reactivated, deleted, or exported as Markdown. Reach it from the **Chat** sidebar link or `/chat/`. See [features.md#chat-mode](../docs/features.md#chat-mode) for the full feature description. ([#2953](https://github.com/LearningCircuit/local-deep-research/pull/2953))
+- **Chat Mode** — Interactive multi-turn research conversations. Each session accumulates context across turns (entities, topics, source count), streams research steps and citations live as the answer is built, and persists in your per-user database (encrypted by default). Sessions can be archived, reactivated, deleted, or exported as Markdown. Reach it from the **Chat** sidebar link or `/chat/`. See [features.md#chat-mode](../features.md#chat-mode) for the full feature description. ([#2953](https://github.com/LearningCircuit/local-deep-research/pull/2953))
- **"Summarizing…" indicator for Chat follow-ups** — When you send a follow-up question, the thinking indicator now reads "Summarizing previous conversation…" while the earlier turns are condensed into context for the new research, instead of showing blank dots. It clears the moment research starts streaming its progress.
- **Configurable follow-up context in Chat Mode** — Follow-up questions now build on the earlier conversation instead of starting cold. By default, the prior conversation is condensed into a short summary focused on your new question (using your configured LLM) and passed to the follow-up research as its "previous findings", keeping multi-turn research on-topic and within context limits. You can change this with the new **Follow-up Context Mode** setting (`chat.followup_context_mode`):
diff --git a/tests/hooks/test_check_readme_links.py b/tests/hooks/test_check_readme_links.py
index c1fba51e21..cb20c22783 100644
--- a/tests/hooks/test_check_readme_links.py
+++ b/tests/hooks/test_check_readme_links.py
@@ -2,9 +2,10 @@
Verifies that the hook flags broken relative links, dangling heading
anchors, non-runnable ``python -m`` examples, and unregistered
-``engine="..."`` names in README.md, while accepting a README whose
-references all resolve — including GitHub-style anchors for headings
-that contain emoji.
+``engine="..."`` names in README.md and docs/**/*.md, while accepting
+files whose references all resolve — including GitHub-style anchors for
+headings that contain emoji and links inside fenced code blocks (which
+GitHub does not render and must therefore be exempt).
"""
import subprocess
@@ -40,6 +41,10 @@ python -m local_deep_research.tool.cli run --flag
def _make_repo(tmp_path: Path, readme: str) -> Path:
"""Build a minimal fake repo the hook can be pointed at via --root."""
(tmp_path / "README.md").write_text(readme, encoding="utf-8")
+ (tmp_path / "SECURITY.md").write_text("# Security\n", encoding="utf-8")
+ (tmp_path / "CONTRIBUTING.md").write_text(
+ "# Contributing\n", encoding="utf-8"
+ )
docs = tmp_path / "docs"
docs.mkdir()
(docs / "real.md").write_text("## Real Heading\n", encoding="utf-8")
@@ -81,6 +86,18 @@ class TestAcceptsValidReadme:
result = _run_hook(_make_repo(tmp_path, "`python -m http.server`\n"))
assert result.returncode == 0, result.stdout
+ def test_links_inside_code_fences_are_ignored(self, tmp_path):
+ # GitHub renders no links inside fenced blocks, so example markup
+ # with runtime paths must not be flagged.
+ readme = (
+ "# T\n\n```html\n"
+ '<link href="/static/css/nope.css">\n'
+ "[fake](docs/nope.md)\n"
+ "```\n"
+ )
+ result = _run_hook(_make_repo(tmp_path, readme))
+ assert result.returncode == 0, result.stdout
+
class TestFlagsBrokenReferences:
def test_missing_link_target(self, tmp_path):
@@ -129,10 +146,21 @@ class TestFlagsBrokenReferences:
assert result.returncode == 1
assert "cannot verify engine names" in result.stdout
+ def test_broken_link_in_docs_file(self, tmp_path):
+ # docs/**/*.md is covered, not just README.md.
+ root = _make_repo(tmp_path, "# T\n")
+ (root / "docs" / "real.md").write_text(
+ "## Real Heading\n[gone](missing.md)\n", encoding="utf-8"
+ )
+ result = _run_hook(root)
+ assert result.returncode == 1
+ assert "docs/real.md" in result.stdout
+ assert "missing.md" in result.stdout
+
class TestRealRepo:
- def test_actual_readme_passes(self):
- """The repo's own README must satisfy its own storefront check."""
+ def test_actual_readme_and_docs_pass(self):
+ """The repo's own README and docs must satisfy their own check."""
result = subprocess.run(
[sys.executable, str(HOOK_SCRIPT)],
capture_output=True,