Sync ctx 333622a

GitHub commit: 333622a56de0a4acad72146b82611401bc076c69

README.md

@@ -18,7 +18,7 @@ tags:
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/Python-3.11+-green.svg)](https://python.org)
 [![PyPI](https://img.shields.io/pypi/v/claude-ctx.svg)](https://pypi.org/project/claude-ctx/)
-[![Tests](https://img.shields.io/badge/Tests-4054_collected-brightgreen.svg)](https://github.com/stevesolun/ctx/actions/workflows/test.yml)
+[![Tests](https://img.shields.io/badge/Tests-4058_collected-brightgreen.svg)](https://github.com/stevesolun/ctx/actions/workflows/test.yml)
 [![Graph](https://img.shields.io/badge/Graph-102%2C928_nodes_/_2.9M_edges-red.svg)](https://stevesolun.github.io/ctx/knowledge-graph/)
 [![Skills](https://img.shields.io/badge/Skills-91%2C464-blue.svg)](https://stevesolun.github.io/ctx/catalog/?type=skill)
 [![Agents](https://img.shields.io/badge/Agents-467-purple.svg)](https://stevesolun.github.io/ctx/catalog/?type=agent)

docs/catalog.md

@@ -44,6 +44,7 @@ It is public and always reachable. The full live catalog runs locally inside
   <p id="ctx-catalog-count" class="ctx-catalog-muted"></p>
 
   <div id="ctx-catalog-grid" class="ctx-catalog-grid">
+<!-- ctx-catalog:begin -->
     <article class="ctx-catalog-card" data-type="skill" data-search="skill prompt workflow testing code review frontend backend security research">
       <span class="ctx-catalog-pill">Skills</span>
       <h3>Skills</h3>
@@ -149,6 +150,7 @@ It is public and always reachable. The full live catalog runs locally inside
       <a class="md-button" href="./?type=harness&q=tool+access">Filter tiles</a>
       <a class="md-button" href="../dashboard/#catalog-badge-links">Open full catalog locally</a>
     </article>
+<!-- ctx-catalog:end -->
   </div>
 </div>
 

docs/dashboard.md

@@ -16,7 +16,8 @@ ctx-monitor serve --host 0.0.0.0 --port 8888  # LAN read-only with startup token
 Zero Python dependencies added by the dashboard. Everything runs on
 stdlib `http.server`, using daemon request threads so a live
 `/api/events.stream` client cannot block normal dashboard or JSON API
-requests. The graph page uses a built-in list renderer and does not load
+requests. The graph page uses a built-in dependency-free SVG neighborhood
+renderer with zoom, drag, hover details, and a list fallback. It does not load
 third-party JavaScript.
 
 ## Usage
@@ -130,10 +131,12 @@ frontmatter values are visibly marked as truncated.
 
 ### Explore the knowledge graph — `/graph`
 
-The graph tab is a built-in list view over the dashboard-supported
-skill/agent/MCP/harness graph. Imported skills are normal `skill`
-nodes in the graph. Harness nodes are browsable and filterable here;
-install/update actions remain in `ctx-harness-install`.
+The graph tab is a dependency-free interactive SVG view over the
+dashboard-supported skill/agent/MCP/harness graph. Imported skills are normal
+`skill` nodes in the graph. Harness nodes are browsable and filterable here;
+install/update actions remain in `ctx-harness-install`. If the SVG renderer
+cannot initialize, the dashboard falls back to a list view over the same graph
+payload.
 When you arrive with no
 slug selected, the page shows:
 
@@ -146,9 +149,9 @@ slug selected, the page shows:
 - the graph list panel itself, which activates as soon as you pick a
   seed
 
-Inside the graph list view, entity pills identify the node type. The
-focus row has `depth=0` in the page data, and neighbor rows are filterable
-by entity type and shared tag/token text.
+Inside the graph view, entity pills identify the node type. The focus node has
+`depth=0` in the page data, and neighbor rows remain filterable by entity type
+and shared tag/token text.
 
 The JSON endpoint still includes blended graph edge weights, combining
 semantic similarity, explicit tag overlap, and slug-token overlap where

docs/index.md

@@ -202,7 +202,7 @@ ones are flagged. New ones self-ingest.
     ---
 
     **v1.0.11** — MIT, CI-matrixed (Ubuntu 3.12 plus Windows/macOS 3.11/3.12),
-    4,054 tests collected. Ships console scripts including `ctx-init`,
+    4,058 tests collected. Ships console scripts including `ctx-init`,
     `ctx-monitor` (local dashboard with graph + wiki + load/unload for
     skills, agents, and MCP servers, plus Harness Setup for user-owned LLMs),
     `ctx-incremental-attach`, `ctx-incremental-shadow`, `ctx-dedup-check`

docs/knowledge-graph.md

@@ -148,8 +148,8 @@ quality clusters for the recommendation use case.
 ctx-monitor serve              # http://127.0.0.1:8765
 ```
 
-Then open `/graph?slug=<entity-slug>&type=<entity-type>` for a
-cytoscape neighborhood view, or
+Then open `/graph?slug=<entity-slug>&type=<entity-type>` for the
+dashboard's interactive SVG neighborhood view, or
 `/api/graph/<slug>.json?type=<entity-type>&hops=1&limit=40` for the
 dashboard-shaped JSON. The `type` query is optional for unique slugs and
 recommended for duplicate slugs such as `langgraph`. See the

src/backup_mirror.py

@@ -212,12 +212,6 @@ def _iter_memory_files() -> Iterable[tuple[str, Path]]:
 # ── Hashing + atomic copy ───────────────────────────────────────────────────
 
 
-def _sha256_bytes(data: bytes) -> str:
-    h = hashlib.sha256()
-    h.update(data)
-    return h.hexdigest()
-
-
 def _sha256_file(path: Path) -> str:
     # Reject symlinks before reading so verify never hashes a file the
     # attacker has pointed out of the snapshot.

src/ctx/adapters/claude_code/install/mcp_install.py

@@ -223,6 +223,26 @@ def _json_config_card_summary(parsed_config: object) -> str:
     return "; ".join(parts) if parts else "empty object"
 
 
+def _safe_manifest_command(command: object) -> str | None:
+    """Return command text safe enough to persist in advisory manifests."""
+    if not isinstance(command, str) or not command.strip():
+        return None
+    try:
+        tokens = _split_install_command(command)
+    except ValueError:
+        return None
+    if not tokens:
+        return None
+    if _find_inline_secret_arg(tokens) is not None:
+        return None
+    executable = _normalized_executable(tokens[0])
+    if executable not in _ALLOWED_CMD_EXECS:
+        return None
+    if _rejects_banned_args(tokens) is not None:
+        return None
+    return _redact_output(command)
+
+
 @dataclass(frozen=True)
 class InstallResult:
     slug: str
@@ -415,8 +435,8 @@ def install_mcp(
 
     if existing_status == "installed" and not force:
         skipped_extra: dict[str, str] = {}
-        install_cmd = fm.get("install_cmd")
-        if isinstance(install_cmd, str) and install_cmd:
+        install_cmd = _safe_manifest_command(fm.get("install_cmd"))
+        if install_cmd:
             skipped_extra["command"] = install_cmd
         record_install(
             slug,

src/ctx/adapters/generic/ctx_core_tools.py

@@ -40,7 +40,6 @@ from __future__ import annotations
 import hashlib
 import json
 import logging
-from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable
 
@@ -68,24 +67,6 @@ FileSignature = tuple[int, int, str]
 GraphSignature = tuple[FileSignature | None, FileSignature | None]
 
 
-@dataclass(frozen=True)
-class BundleEntry:
-    """One row of a recommendation result.
-
-    ``score`` is the raw graph-walk weight; ``normalized_score`` is
-    that value divided by the top score in the same result set (so
-    the highest-ranked entry is always 1.0 — lets a caller apply a
-    0.0-1.0 cutoff without knowing the absolute graph scale).
-    """
-
-    name: str
-    entity_type: str   # 'skill' | 'agent' | 'mcp-server'
-    score: float
-    normalized_score: float
-    shared_tags: tuple[str, ...]
-    via: tuple[str, ...]
-
-
 class CtxCoreToolbox:
     """ctx-core recommendation and lifecycle surface for harness tools.
 

src/ctx/core/entity_types.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Collection
 
 
 ENTITY_TYPES: tuple[str, ...] = (
@@ -48,6 +49,48 @@ RELATED_SECTION_FOR_ENTITY_TYPE: dict[str, str] = {
     "harness": "## Related Harnesses",
 }
 
+ENTITY_TYPE_ALIASES: dict[str, str] = {
+    "skills": "skill",
+    "skill": "skill",
+    "agents": "agent",
+    "agent": "agent",
+    "mcp": "mcp-server",
+    "mcp-server": "mcp-server",
+    "mcp-servers": "mcp-server",
+    "plugins": "plugin",
+    "plugin": "plugin",
+    "harness": "harness",
+    "harnesses": "harness",
+}
+
+
+def normalize_entity_type(
+    raw: object,
+    *,
+    allowed: Collection[str] = ENTITY_TYPES,
+) -> str | None:
+    """Return a canonical entity type for user/API aliases."""
+    if raw is None:
+        return None
+    value = str(raw).strip()
+    if not value:
+        return None
+    normalized = ENTITY_TYPE_ALIASES.get(value.lower(), value)
+    return normalized if normalized in allowed else None
+
+
+def entity_source_specs(
+    entity_types: Collection[str] = RECOMMENDABLE_ENTITY_TYPES,
+) -> tuple[tuple[str, str, bool], ...]:
+    """Return ``(subject_type, entity_type, recursive)`` wiki source specs."""
+    specs: list[tuple[str, str, bool]] = []
+    for entity_type in RECOMMENDABLE_ENTITY_TYPES:
+        if entity_type not in entity_types:
+            continue
+        subject_type = SUBJECT_TYPE_FOR_ENTITY_TYPE[entity_type]
+        specs.append((subject_type, entity_type, entity_type == "mcp-server"))
+    return tuple(specs)
+
 
 def mcp_shard(slug: str) -> str:
     """Return the shard segment for an MCP slug."""
@@ -71,6 +114,17 @@ def entity_page_path(wiki: Path, entity_type: str, slug: str) -> Path | None:
     return wiki / relpath if relpath is not None else None
 
 
+def entity_index_link(subject_type: str, slug: str) -> str | None:
+    """Return the extensionless wiki index target for a subject/slug pair."""
+    entity_type = ENTITY_TYPE_FOR_SUBJECT_TYPE.get(subject_type)
+    if entity_type is None:
+        return None
+    if entity_type == "mcp-server" and not slug:
+        return f"entities/{subject_type}/{mcp_shard(slug)}/"
+    relpath = entity_relpath(entity_type, slug)
+    return relpath.with_suffix("").as_posix() if relpath is not None else None
+
+
 def entity_wikilink(entity_type: str, slug: str) -> str | None:
     """Return an Obsidian-style wikilink for an entity."""
     relpath = entity_relpath(entity_type, slug)

src/ctx/core/wiki/wiki_sync.py

@@ -19,6 +19,12 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+from ctx.core.entity_types import (
+    ENTITY_TYPE_FOR_SUBJECT_TYPE,
+    INDEX_SECTION_FOR_SUBJECT,
+    SUBJECT_TYPE_FOR_ENTITY_TYPE,
+    entity_index_link,
+)
 from ctx.core.wiki.wiki_utils import SAFE_NAME_RE, get_field as _find_field
 from ctx.utils._file_lock import file_lock
 from ctx.utils._fs_utils import atomic_write_json, atomic_write_text
@@ -168,16 +174,8 @@ def _sanitize_yaml_value(value: str) -> str:
     return sanitized.strip()
 
 
-_SUBJECT_TYPE_FOR_ENTITY_TYPE: dict[str, str] = {
-    "skill": "skills",
-    "agent": "agents",
-    "mcp-server": "mcp-servers",
-    "plugin": "plugins",
-    "harness": "harnesses",
-}
-_ENTITY_TYPE_FOR_SUBJECT_TYPE: dict[str, str] = {
-    value: key for key, value in _SUBJECT_TYPE_FOR_ENTITY_TYPE.items()
-}
+_SUBJECT_TYPE_FOR_ENTITY_TYPE = SUBJECT_TYPE_FOR_ENTITY_TYPE
+_ENTITY_TYPE_FOR_SUBJECT_TYPE = ENTITY_TYPE_FOR_SUBJECT_TYPE
 
 
 def _subject_type_for_manifest_entry(entry: dict) -> str:
@@ -303,18 +301,11 @@ Detected and loaded by skill-router.
 
 
 
-# Section header used for each subject type in index.md. Adding a new
-# subject type requires extending this map and the entity-link helper
-# below. ``"skills"`` stays first so the default keyword arg for backward
-# compat (callers that predate the subject_type param) keeps writing
-# into the same section it always did.
-_INDEX_SECTION_FOR_SUBJECT: dict[str, str] = {
-    "skills": "## Skills",
-    "agents": "## Agents",
-    "mcp-servers": "## MCP Servers",
-    "plugins": "## Plugins",
-    "harnesses": "## Harnesses",
-}
+# Section header used for each subject type in index.md. The canonical map
+# lives in ctx.core.entity_types so wiki sync, graphify, and dashboard routing
+# stay aligned. ``"skills"`` stays first so the default keyword arg for
+# backward compat keeps writing into the same section it always did.
+_INDEX_SECTION_FOR_SUBJECT = INDEX_SECTION_FOR_SUBJECT
 
 
 def _entity_index_link(subject_type: str, slug: str) -> str:
@@ -325,11 +316,10 @@ def _entity_index_link(subject_type: str, slug: str) -> str:
     to keep ``ls`` and Obsidian fast at the projected ~12k+ scale —
     so their links must include the shard segment.
     """
-    if subject_type == "mcp-servers":
-        first = slug[0] if slug else ""
-        shard = first if first.isalpha() else "0-9"
-        return f"entities/mcp-servers/{shard}/{slug}"
-    return f"entities/{subject_type}/{slug}"
+    target = entity_index_link(subject_type, slug)
+    if target is None:
+        raise ValueError(f"unknown subject_type {subject_type!r}")
+    return target
 
 
 def update_index(

src/ctx/dashboard_docs.py

@@ -0,0 +1,810 @@
+"""Dashboard documentation rendering for ``ctx-monitor``.
+
+This module owns the local docs index, MkDocs-flavored Markdown rendering,
+sanitization, link rewriting, and docs HTML cache.  ``ctx_monitor`` supplies
+page chrome and asset readers; the docs implementation stays isolated here.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import json
+import re
+from pathlib import Path, PurePosixPath
+from typing import Any, Callable, Sequence
+from urllib.parse import quote, unquote
+
+from ctx.utils._fs_utils import atomic_write_text as _atomic_write_text
+
+PUBLIC_DOCS_URL = "https://stevesolun.github.io/ctx/"
+
+LayoutRenderer = Callable[[str, str], str]
+AssetReader = Callable[[str], str]
+InlineScriptRenderer = Callable[[str], str]
+MarkdownRenderer = Callable[[str, str], str]
+FallbackMarkdownRenderer = Callable[[str], str]
+
+_DOCS_RENDER_CACHE_KEY: tuple[Any, ...] | None = None
+_DOCS_RENDER_CACHE_VALUE: str | None = None
+
+
+def reset_docs_render_cache() -> None:
+    """Clear the in-process docs render cache."""
+    global _DOCS_RENDER_CACHE_KEY, _DOCS_RENDER_CACHE_VALUE
+    _DOCS_RENDER_CACHE_KEY = None
+    _DOCS_RENDER_CACHE_VALUE = None
+
+
+def _truncate_text(value: str, limit: int) -> tuple[str, bool]:
+    if limit <= 0 or len(value) <= limit:
+        return value, False
+    if limit <= 3:
+        return value[:limit], True
+    return value[: limit - 3].rstrip() + "...", True
+
+
+def _slugish(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+
+
+def docs_roots(current_dir: Path, package_root: Path) -> list[Path]:
+    roots: list[Path] = []
+    for root in (current_dir, package_root):
+        if root not in roots and (root / "docs").is_dir():
+            roots.append(root)
+    return roots
+
+
+def docs_cache_files(roots: Sequence[Path]) -> list[Path]:
+    files: list[Path] = []
+    seen: set[Path] = set()
+    for root in roots:
+        candidates = [root / "README.md", root / "graph" / "README.md", root / "mkdocs.yml"]
+        docs_dir = root / "docs"
+        if docs_dir.is_dir():
+            candidates.extend(sorted(docs_dir.rglob("*.md")))
+        for path in candidates:
+            if not path.is_file():
+                continue
+            try:
+                resolved = path.resolve()
+            except OSError:
+                resolved = path
+            if resolved in seen:
+                continue
+            seen.add(resolved)
+            files.append(path)
+    return files
+
+
+def docs_render_cache_key(
+    roots: Sequence[Path],
+    *,
+    asset_text: AssetReader,
+    cache_salt_paths: Sequence[Path] = (),
+    cache_extra: Sequence[Any] = (),
+) -> tuple[Any, ...]:
+    parts: list[Any] = []
+    for path in (Path(__file__), *cache_salt_paths):
+        try:
+            stat = path.stat()
+            parts.append(("source", str(path.resolve()), stat.st_mtime_ns, stat.st_size))
+        except OSError:
+            parts.append(("source", str(path), None, None))
+    for item in cache_extra:
+        parts.append(("extra", repr(item)))
+    for asset_name in ("monitor.css", "monitor-docs.js"):
+        try:
+            asset_hash = hashlib.sha256(asset_text(asset_name).encode("utf-8")).hexdigest()
+        except Exception:
+            asset_hash = ""
+        parts.append(("asset", asset_name, asset_hash))
+    for path in docs_cache_files(roots):
+        try:
+            stat = path.stat()
+            path_name = str(path.resolve())
+            parts.append((path_name, stat.st_mtime_ns, stat.st_size))
+        except OSError:
+            continue
+    return tuple(parts)
+
+
+def docs_render_disk_cache_path(claude_dir: Path) -> Path:
+    return claude_dir / ".ctx-monitor-docs-cache.json"
+
+
+def _disk_cache_token(cache_key: tuple[Any, ...]) -> str:
+    return json.dumps(cache_key, separators=(",", ":"), sort_keys=True)
+
+
+def _read_disk_cache_payload(path: Path, cache_token: str) -> dict[str, Any] | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    if data.get("schema_version") != 1 or data.get("cache_token") != cache_token:
+        return None
+    return data
+
+
+def _write_disk_cache_payload(
+    path: Path,
+    cache_token: str,
+    payload: dict[str, Any],
+    *,
+    sort_keys: bool = False,
+) -> None:
+    try:
+        _atomic_write_text(
+            path,
+            json.dumps(
+                {
+                    "schema_version": 1,
+                    "cache_token": cache_token,
+                    **payload,
+                },
+                ensure_ascii=False,
+                sort_keys=sort_keys,
+            ) + "\n",
+            encoding="utf-8",
+        )
+    except (OSError, TypeError, ValueError):
+        return
+
+
+def _read_html_disk_cache(path: Path, cache_token: str) -> str | None:
+    data = _read_disk_cache_payload(path, cache_token)
+    if data is None:
+        return None
+    html_text = data.get("html")
+    return html_text if isinstance(html_text, str) else None
+
+
+def _write_html_disk_cache(path: Path, cache_token: str, html_text: str) -> None:
+    _write_disk_cache_payload(path, cache_token, {"html": html_text})
+
+
+def doc_title(text: str, fallback: str) -> str:
+    for line in text.splitlines():
+        match = re.match(r"^#\s+(.+?)\s*$", line)
+        if match:
+            return match.group(1).strip()
+    return fallback
+
+
+def doc_summary(text: str) -> str:
+    in_frontmatter = text.startswith("---\n")
+    for block in re.split(r"\n\s*\n", text):
+        chunk = block.strip()
+        if not chunk:
+            continue
+        if in_frontmatter:
+            if chunk == "---" or chunk.endswith("\n---"):
+                in_frontmatter = False
+            continue
+        if chunk.startswith("#") or chunk.startswith("```") or chunk.startswith("<!--"):
+            continue
+        summary = re.sub(r"\s+", " ", chunk)
+        summary, _truncated = _truncate_text(summary, 180)
+        return summary
+    return ""
+
+
+def strip_doc_frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return text
+    parts = text.split("---", 2)
+    return parts[2].lstrip() if len(parts) == 3 else text
+
+
+def doc_anchor(value: str) -> str:
+    return _slugish(value) or "docs"
+
+
+def docs_index_entries(roots: Sequence[Path]) -> list[dict[str, Any]]:
+    entries: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for root in roots:
+        candidates = [root / "README.md", root / "graph" / "README.md"]
+        docs_dir = root / "docs"
+        if docs_dir.is_dir():
+            candidates.extend(sorted(docs_dir.rglob("*.md")))
+        for path in candidates:
+            if not path.is_file():
+                continue
+            rel = path.relative_to(root).as_posix()
+            if rel == "docs/SKILL.md":
+                continue
+            if rel in seen:
+                continue
+            seen.add(rel)
+            try:
+                text = path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            text = strip_doc_frontmatter(text)
+            title = doc_title(text, path.stem.replace("-", " ").title())
+            entries.append({
+                "title": title,
+                "path": rel,
+                "summary": doc_summary(text),
+                "body": text,
+            })
+    return sorted(entries, key=lambda row: str(row["path"]))
+
+
+def docs_nav_from_mkdocs(
+    root: Path,
+    entries_by_path: dict[str, dict[str, Any]],
+) -> list[dict[str, Any]]:
+    mkdocs_path = root / "mkdocs.yml"
+    if not mkdocs_path.is_file():
+        return []
+    try:
+        import yaml  # type: ignore[import-untyped]
+
+        data = yaml.load(mkdocs_path.read_text(encoding="utf-8"), Loader=yaml.BaseLoader) or {}
+    except Exception:
+        return []
+    raw_nav = data.get("nav")
+    if not isinstance(raw_nav, list):
+        return []
+
+    def pages_from_nav(value: Any) -> list[tuple[str, str]]:
+        if isinstance(value, str):
+            return [(Path(value).stem.replace("-", " ").title(), f"docs/{value}")]
+        if isinstance(value, list):
+            pages: list[tuple[str, str]] = []
+            for child in value:
+                pages.extend(pages_from_nav(child))
+            return pages
+        if isinstance(value, dict):
+            pages = []
+            for label, child in value.items():
+                if isinstance(child, str):
+                    pages.append((str(label), f"docs/{child}"))
+                else:
+                    pages.extend(pages_from_nav(child))
+            return pages
+        return []
+
+    tabs: list[dict[str, Any]] = []
+    for item in raw_nav:
+        if not isinstance(item, dict):
+            continue
+        for label, value in item.items():
+            pages = [
+                {**entries_by_path[path], "nav_title": page_label}
+                for page_label, path in pages_from_nav(value)
+                if path in entries_by_path
+            ]
+            if pages:
+                tabs.append({
+                    "label": str(label),
+                    "slug": doc_anchor(str(label)),
+                    "pages": pages,
+                })
+    return tabs
+
+
+def docs_tabs(entries: list[dict[str, Any]], roots: Sequence[Path]) -> list[dict[str, Any]]:
+    entries_by_path = {str(entry["path"]): entry for entry in entries}
+    tabs: list[dict[str, Any]] = []
+    used: set[str] = set()
+    for root in roots:
+        tabs = docs_nav_from_mkdocs(root, entries_by_path)
+        if tabs:
+            break
+    for tab in tabs:
+        for page in tab["pages"]:
+            used.add(str(page["path"]))
+
+    repo_pages = [
+        entries_by_path[path]
+        for path in ("README.md", "graph/README.md")
+        if path in entries_by_path
+    ]
+    if repo_pages:
+        tabs.append({"label": "Repo", "slug": "repo", "pages": repo_pages})
+        used.update(str(page["path"]) for page in repo_pages)
+
+    other_pages = [
+        entry
+        for entry in entries
+        if entry["path"] not in used and entry["path"] != "docs/SKILL.md"
+    ]
+    if other_pages:
+        tabs.append({"label": "Other", "slug": "other", "pages": other_pages})
+    if not tabs and entries:
+        tabs.append({"label": "Docs", "slug": "docs", "pages": entries})
+    return tabs
+
+
+def docs_heading_text(raw: str) -> str:
+    raw = re.sub(r"\s+\{#[^}]+\}\s*$", "", raw.strip())
+    raw = re.sub(r"`([^`]+)`", r"\1", raw)
+    raw = re.sub(r"!\[([^\]]*)\]\([^)]+\)", r"\1", raw)
+    raw = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", raw)
+    raw = re.sub(r"[*_~]+", "", raw)
+    return re.sub(r"\s+", " ", raw).strip()
+
+
+def docs_heading_id(page_anchor: str, title: str, seen: dict[str, int]) -> str:
+    base = f"{page_anchor}-{doc_anchor(title)}"
+    count = seen.get(base, 0)
+    seen[base] = count + 1
+    return base if count == 0 else f"{base}_{count}"
+
+
+def docs_heading_items(markdown_text: str, page_anchor: str) -> list[dict[str, Any]]:
+    headings: list[dict[str, Any]] = []
+    seen: dict[str, int] = {}
+    in_fence = False
+    for line in markdown_text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith(("```", "~~~")):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        match = re.match(r"^(#{1,4})\s+(.+?)\s*#*\s*$", line)
+        if not match:
+            continue
+        level = len(match.group(1))
+        title = docs_heading_text(match.group(2))
+        if not title:
+            continue
+        heading_id = docs_heading_id(page_anchor, title, seen)
+        if level >= 2:
+            headings.append({"level": level, "title": title, "id": heading_id})
+    return headings
+
+
+def docs_page_anchor(tab_slug: str, path: str) -> str:
+    return f"doc-{tab_slug}-{doc_anchor(path)}"
+
+
+def normalise_doc_path(path: str) -> str:
+    parts: list[str] = []
+    for part in PurePosixPath(path).parts:
+        if part in ("", "."):
+            continue
+        if part == "..":
+            if parts:
+                parts.pop()
+            continue
+        parts.append(part)
+    return PurePosixPath(*parts).as_posix() if parts else ""
+
+
+def resolve_docs_link_path(
+    source_path: str,
+    href_path: str,
+    page_anchors: dict[str, tuple[str, str]],
+) -> str | None:
+    base = PurePosixPath(source_path).parent
+    resolved = normalise_doc_path((base / href_path).as_posix())
+    candidates = [resolved]
+    if not resolved.endswith(".md"):
+        stripped = resolved.rstrip("/")
+        candidates.extend([f"{stripped}.md", f"{stripped}/index.md"])
+    for candidate in candidates:
+        if candidate in page_anchors:
+            return candidate
+    return None
+
+
+def docs_dashboard_link(
+    source_path: str,
+    source_tab: str,
+    source_anchor: str,
+    href: str,
+    page_anchors: dict[str, tuple[str, str]],
+) -> tuple[str, str, str] | None:
+    href = html.unescape(href).strip()
+    lowered = href.lower()
+    if (
+        not href
+        or lowered.startswith(("http://", "https://", "mailto:", "tel:", "javascript:"))
+        or href.startswith("/")
+    ):
+        return None
+    href_path, sep, fragment = href.partition("#")
+    if not href_path:
+        target_tab = source_tab
+        target_anchor = source_anchor
+    else:
+        resolved_path = resolve_docs_link_path(source_path, href_path, page_anchors)
+        if resolved_path is None:
+            return None
+        target_tab, target_anchor = page_anchors[resolved_path]
+    if sep and fragment:
+        fragment_anchor = doc_anchor(unquote(fragment))
+        if not fragment_anchor.startswith(target_anchor):
+            fragment_anchor = f"{target_anchor}-{fragment_anchor}"
+        return f"#{fragment_anchor}", target_tab, fragment_anchor
+    return f"#{target_anchor}", target_tab, target_anchor
+
+
+def rewrite_docs_links(
+    rendered_html: str,
+    source_path: str,
+    source_tab: str,
+    source_anchor: str,
+    page_anchors: dict[str, tuple[str, str]],
+) -> str:
+    def replace_link(match: re.Match[str]) -> str:
+        before = match.group(1)
+        href = match.group(2)
+        after = match.group(3)
+        resolved = docs_dashboard_link(source_path, source_tab, source_anchor, href, page_anchors)
+        if resolved is None:
+            return match.group(0)
+        dashboard_href, target_tab, target_anchor = resolved
+        return (
+            f"<a{before}href=\"{html.escape(dashboard_href, quote=True)}\""
+            f" data-doc-tab=\"{html.escape(target_tab, quote=True)}\""
+            f" data-doc-target=\"{html.escape(target_anchor, quote=True)}\"{after}>"
+        )
+
+    return re.sub(r"<a([^>]*?)href=\"([^\"]+)\"([^>]*)>", replace_link, rendered_html)
+
+
+def render_docs_markdown(
+    markdown_text: str,
+    page_anchor: str,
+    *,
+    fallback_renderer: FallbackMarkdownRenderer,
+) -> str:
+    """Render repo docs with MkDocs-like Markdown support when available."""
+    markdown_text = re.sub(r":octicons-arrow-right-24:", "->", markdown_text)
+    markdown_text = re.sub(r":octicons-[a-z0-9-]+:", "", markdown_text)
+    try:
+        import markdown as markdown_lib  # type: ignore[import-untyped]
+
+        rendered = str(markdown_lib.markdown(
+            markdown_text,
+            extensions=[
+                "admonition",
+                "attr_list",
+                "def_list",
+                "fenced_code",
+                "footnotes",
+                "md_in_html",
+                "tables",
+                "toc",
+                "pymdownx.details",
+                "pymdownx.superfences",
+                "pymdownx.tabbed",
+                "pymdownx.tasklist",
+                "pymdownx.inlinehilite",
+            ],
+            extension_configs={
+                "toc": {
+                    "permalink": True,
+                    "slugify": lambda value, separator: f"{page_anchor}-{doc_anchor(value)}",
+                },
+                "pymdownx.tabbed": {"alternate_style": True},
+                "pymdownx.tasklist": {"custom_checkbox": True},
+            },
+            output_format="html5",
+        ))
+        return sanitize_docs_html(rendered)
+    except Exception:
+        return fallback_renderer(markdown_text)
+
+
+def sanitize_docs_html(rendered_html: str) -> str:
+    """Remove active HTML from local docs before embedding in the dashboard."""
+    dangerous_blocks = (
+        "script",
+        "style",
+        "iframe",
+        "object",
+        "embed",
+        "form",
+        "textarea",
+        "select",
+    )
+    dangerous_tags = (
+        "base",
+        "button",
+        "input",
+        "link",
+        "meta",
+    )
+
+    def escape_match(match: re.Match[str]) -> str:
+        return html.escape(match.group(0))
+
+    def parse_attrs(tag_html: str) -> dict[str, str | None] | None:
+        attrs: dict[str, str | None] = {}
+        for match in re.finditer(
+            r"([a-zA-Z_:][\w:.-]*)(?:\s*=\s*(\"[^\"]*\"|'[^']*'|[^\s\"'>]+))?",
+            tag_html,
+        ):
+            name = match.group(1).lower()
+            if name == "input":
+                continue
+            if name in attrs:
+                return None
+            raw_value = match.group(2)
+            if raw_value is None:
+                attrs[name] = None
+                continue
+            value = raw_value.strip()
+            if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+                value = value[1:-1]
+            attrs[name] = html.unescape(value)
+        return attrs
+
+    def is_safe_tabbed_input(tag_html: str) -> bool:
+        attrs = parse_attrs(tag_html)
+        if attrs is None:
+            return False
+        if set(attrs) - {"checked", "id", "name", "type"}:
+            return False
+        input_type = (attrs.get("type") or "").lower()
+        input_id = attrs.get("id") or ""
+        input_name = attrs.get("name") or ""
+        if input_type != "radio":
+            return False
+        if not re.fullmatch(r"__tabbed_\d+_\d+", input_id):
+            return False
+        if not re.fullmatch(r"__tabbed_\d+", input_name):
+            return False
+        if not input_id.startswith(f"{input_name}_"):
+            return False
+        checked = attrs.get("checked")
+        return checked is None or checked.lower() == "checked"
+
+    def escape_input_unless_safe(match: re.Match[str]) -> str:
+        tag_html = match.group(0)
+        if is_safe_tabbed_input(tag_html):
+            return tag_html
+        return html.escape(tag_html)
+
+    for tag in dangerous_blocks:
+        rendered_html = re.sub(
+            rf"<\s*{tag}\b[^>]*>.*?<\s*/\s*{tag}\s*>",
+            escape_match,
+            rendered_html,
+            flags=re.IGNORECASE | re.DOTALL,
+        )
+        rendered_html = re.sub(
+            rf"<\s*/?\s*{tag}\b[^>]*>",
+            escape_match,
+            rendered_html,
+            flags=re.IGNORECASE,
+        )
+    for tag in dangerous_tags:
+        if tag == "input":
+            rendered_html = re.sub(
+                rf"<\s*/?\s*{tag}\b[^>]*>",
+                escape_input_unless_safe,
+                rendered_html,
+                flags=re.IGNORECASE,
+            )
+            continue
+        rendered_html = re.sub(
+            rf"<\s*/?\s*{tag}\b[^>]*>",
+            escape_match,
+            rendered_html,
+            flags=re.IGNORECASE,
+        )
+
+    rendered_html = re.sub(
+        r"\s+on[a-zA-Z0-9_-]+\s*=\s*(\"[^\"]*\"|'[^']*'|[^\s>]+)",
+        "",
+        rendered_html,
+        flags=re.IGNORECASE,
+    )
+    rendered_html = re.sub(
+        r"\s+(href|src)\s*=\s*(?:\"\s*(?:javascript:|data:text/html)[^\"]*\"|'\s*(?:javascript:|data:text/html)[^']*'|(?:javascript:|data:text/html)[^\s>]*)",
+        lambda match: f' {match.group(1)}="#"',
+        rendered_html,
+        flags=re.IGNORECASE,
+    )
+    return rendered_html
+
+
+def docs_search_text(entry: dict[str, Any]) -> str:
+    text = f"{entry['title']} {entry['path']} {entry['summary']} {entry['body']}"
+    text = re.sub(r"```.*?```", " ", text, flags=re.DOTALL)
+    text = re.sub(r"!!!\s+\w+(?:\s+\"[^\"]+\")?", " ", text)
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = re.sub(r"[*_`#>\[\]().!:-]+", " ", text)
+    return re.sub(r"\s+", " ", text).strip().lower()
+
+
+def render_docs_sidebar_page(
+    entry: dict[str, Any],
+    tab_slug: str,
+    page_anchors: dict[str, tuple[str, str]],
+) -> str:
+    page_anchor = page_anchors.get(
+        str(entry["path"]),
+        (tab_slug, docs_page_anchor(tab_slug, str(entry["path"]))),
+    )[1]
+    title = str(entry.get("nav_title") or entry["title"])
+    page_search = docs_search_text(entry)
+    heading_links = "".join(
+        "<a class='docs-heading-link "
+        f"docs-heading-level-{int(heading['level'])}' "
+        f"href='#{html.escape(str(heading['id']))}' "
+        f"data-doc-link data-doc-tab='{html.escape(tab_slug)}' "
+        f"data-doc-target='{html.escape(str(heading['id']))}' "
+        f"data-doc-search='{html.escape(str(heading['title']).lower())}' "
+        f"data-doc-label='{html.escape(title)} / {html.escape(str(heading['title']))}'>"
+        f"{html.escape(str(heading['title']))}</a>"
+        for heading in docs_heading_items(str(entry["body"]), page_anchor)
+    )
+    headings = f"<div class='docs-heading-list'>{heading_links}</div>" if heading_links else ""
+    return (
+        "<div class='docs-toc-page'>"
+        f"<a class='docs-page-link' href='#{html.escape(page_anchor)}' "
+        f"data-doc-link data-doc-tab='{html.escape(tab_slug)}' "
+        f"data-doc-target='{html.escape(page_anchor)}' "
+        f"data-doc-search='{html.escape(page_search)}' "
+        f"data-doc-label='{html.escape(title)}'>{html.escape(title)}</a>"
+        f"{headings}"
+        "</div>"
+    )
+
+
+def render_docs_page(
+    entry: dict[str, Any],
+    tab_slug: str,
+    page_anchors: dict[str, tuple[str, str]],
+    *,
+    render_markdown_func: MarkdownRenderer,
+) -> str:
+    page_anchor = page_anchors.get(
+        str(entry["path"]),
+        (tab_slug, docs_page_anchor(tab_slug, str(entry["path"]))),
+    )[1]
+    source_url = f"https://github.com/stevesolun/ctx/blob/main/{quote(str(entry['path']))}"
+    body_html = render_markdown_func(str(entry["body"]), page_anchor)
+    body_html = rewrite_docs_links(body_html, str(entry["path"]), tab_slug, page_anchor, page_anchors)
+    return (
+        f"<article id='{html.escape(page_anchor)}' class='docs-page wiki-body' "
+        f"data-doc-page='{html.escape(docs_search_text(entry))}'>"
+        "<div class='docs-page-source'>"
+        f"<code>{html.escape(str(entry['path']))}</code>"
+        f"<a href='{html.escape(source_url)}'>source -></a>"
+        "</div>"
+        f"{body_html}"
+        "</article>"
+    )
+
+
+def render_docs(
+    *,
+    roots: Sequence[Path],
+    layout: LayoutRenderer,
+    asset_text: AssetReader,
+    inline_script: InlineScriptRenderer,
+    cache_path: Path,
+    fallback_markdown: FallbackMarkdownRenderer,
+    cache_salt_paths: Sequence[Path] = (),
+    cache_extra: Sequence[Any] = (),
+    index_entries: Callable[[], list[dict[str, Any]]] | None = None,
+    tabs_for_entries: Callable[[list[dict[str, Any]]], list[dict[str, Any]]] | None = None,
+    render_markdown_func: MarkdownRenderer | None = None,
+    public_docs_url: str = PUBLIC_DOCS_URL,
+) -> str:
+    cache_key = docs_render_cache_key(
+        roots,
+        asset_text=asset_text,
+        cache_salt_paths=cache_salt_paths,
+        cache_extra=cache_extra,
+    )
+    global _DOCS_RENDER_CACHE_KEY, _DOCS_RENDER_CACHE_VALUE
+    if _DOCS_RENDER_CACHE_KEY == cache_key and _DOCS_RENDER_CACHE_VALUE is not None:
+        return _DOCS_RENDER_CACHE_VALUE
+    cache_token = _disk_cache_token(cache_key)
+    cached = _read_html_disk_cache(cache_path, cache_token)
+    if cached is not None:
+        _DOCS_RENDER_CACHE_KEY = cache_key
+        _DOCS_RENDER_CACHE_VALUE = cached
+        return cached
+
+    entries = index_entries() if index_entries is not None else docs_index_entries(roots)
+    tabs = tabs_for_entries(entries) if tabs_for_entries is not None else docs_tabs(entries, roots)
+    if render_markdown_func is None:
+        def default_render_markdown(text: str, anchor: str) -> str:
+            return render_docs_markdown(
+                text,
+                anchor,
+                fallback_renderer=fallback_markdown,
+            )
+
+        render_markdown_func = default_render_markdown
+    if not tabs:
+        body = (
+            "<h1>Docs</h1>"
+            "<div class='card'><strong>No local docs found.</strong>"
+            f"<p class='muted'>Open the public docs at "
+            f"<a href='{public_docs_url}'>{public_docs_url}</a>.</p></div>"
+        )
+        html_out = layout("Docs", body)
+        _write_html_disk_cache(cache_path, cache_token, html_out)
+        _DOCS_RENDER_CACHE_KEY = cache_key
+        _DOCS_RENDER_CACHE_VALUE = html_out
+        return html_out
+
+    tab_buttons = "".join(
+        f"<button class='docs-tab-button{' active' if idx == 0 else ''}' "
+        f"type='button' data-doc-tab='{html.escape(str(tab['slug']))}'>"
+        f"{html.escape(str(tab['label']))}</button>"
+        for idx, tab in enumerate(tabs)
+    )
+    panels: list[str] = []
+    page_count = sum(len(list(tab["pages"])) for tab in tabs)
+    page_anchors: dict[str, tuple[str, str]] = {}
+    for tab in tabs:
+        tab_slug = str(tab["slug"])
+        for page in list(tab["pages"]):
+            page_anchors[str(page["path"])] = (tab_slug, docs_page_anchor(tab_slug, str(page["path"])))
+    for idx, tab in enumerate(tabs):
+        tab_slug = str(tab["slug"])
+        pages = list(tab["pages"])
+        page_links = "".join(
+            render_docs_sidebar_page(page, tab_slug, page_anchors)
+            for page in pages
+        )
+        page_bodies = "".join(
+            render_docs_page(
+                page,
+                tab_slug,
+                page_anchors,
+                render_markdown_func=render_markdown_func,
+            )
+            for page in pages
+        )
+        hidden = " hidden" if idx else ""
+        panels.append(
+            f"<section class='docs-tab-panel' data-doc-panel='{html.escape(tab_slug)}'{hidden}>"
+            "<div class='docs-reader'>"
+            f"<aside class='docs-page-list'>{page_links}</aside>"
+            f"<div>{page_bodies}</div>"
+            "</div>"
+            "</section>"
+        )
+
+    body = (
+        "<div class='docs-shell'>"
+        "<section class='docs-hero'>"
+        "<div class='docs-hero-grid'>"
+        "<div>"
+        "<div class='docs-eyebrow'>Repo documentation</div>"
+        "<h1>Docs</h1>"
+        "<p>Read the same Markdown tree and MkDocs nav shipped with the repo. "
+        "Use tabs for sections, search across local docs, and jump to source when you need the exact file.</p>"
+        "</div>"
+        "<div class='docs-hero-meta'>"
+        f"<span class='docs-stat'>{len(tabs)} sections</span>"
+        f"<span class='docs-stat'>{page_count} pages</span>"
+        "</div>"
+        "</div>"
+        "<div class='docs-actions'>"
+        "<div class='docs-search-wrap'>"
+        "<input id='docs-search' type='text' placeholder='Search local docs...'>"
+        "</div>"
+        f"<a class='docs-public-link' href='{public_docs_url}'>public docs -></a>"
+        "</div>"
+        "<div id='docs-search-results' class='docs-search-results' hidden></div>"
+        "</section>"
+        f"<div class='docs-tabs' role='tablist'>{tab_buttons}</div>"
+        + "".join(panels)
+        + inline_script("monitor-docs.js")
+        + "</div>"
+    )
+    html_out = layout("Docs", body)
+    _write_html_disk_cache(cache_path, cache_token, html_out)
+    _DOCS_RENDER_CACHE_KEY = cache_key
+    _DOCS_RENDER_CACHE_VALUE = html_out
+    return html_out

src/ctx/dashboard_entities.py

@@ -0,0 +1,378 @@
+"""Dashboard entity search, CRUD, and runtime load/unload helpers.
+
+``ctx_monitor`` owns HTTP routing and local paths.  This module owns the
+catalog-management behavior so search/upsert/delete/load/unload logic can be
+tested and reviewed without the full monitor server surface.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass(frozen=True)
+class EntityCrudDeps:
+    is_safe_slug: Callable[[str], bool]
+    normalize_entity_type: Callable[[object], str | None]
+    wiki_entity_detail: Callable[[str, str | None], dict[str, Any] | None]
+    wiki_entity_target_path: Callable[[str, str], Path]
+    wiki_entity_path: Callable[[str, str | None], Path | None]
+    iter_wiki_entity_paths: Callable[[str | None], list[tuple[str, str, Path]]]
+    read_manifest: Callable[[], dict[str, Any]]
+    perform_unload: Callable[[str, str], tuple[bool, str]]
+    queue_entity_refresh: Callable[[str, str, Path, str, str], None]
+    file_lock: Callable[[Path], AbstractContextManager[Any]]
+    write_entity_text: Callable[[Path, str], None]
+    parse_frontmatter: Callable[[str], tuple[dict[str, Any], str]]
+    frontmatter_tags: Callable[[Any], list[str]]
+    frontmatter_text: Callable[[Any], str]
+    display_slug: Callable[[str], str]
+    display_label: Callable[[Any], str]
+    entity_wiki_href: Callable[[str, str], str]
+
+
+@dataclass(frozen=True)
+class EntityRuntimeDeps:
+    is_safe_slug: Callable[[str], bool]
+    normalize_entity_type: Callable[[object], str | None]
+    wiki_dir: Callable[[], Path]
+    claude_dir: Callable[[], Path]
+    log_dashboard_entity_event: Callable[[str, str, str], None]
+    remove_loaded_manifest_entry: Callable[[str, str], list[dict[str, Any]]]
+
+
+def normalize_entity_tags(raw: Any) -> list[str]:
+    if isinstance(raw, list):
+        parts = raw
+    else:
+        parts = re.split(r"[,\n]+", str(raw or ""))
+    tags: list[str] = []
+    seen: set[str] = set()
+    for part in parts:
+        tag = re.sub(r"[^a-z0-9_.+-]+", "-", str(part).lower()).strip("-_.+")
+        if tag and tag not in seen:
+            seen.add(tag)
+            tags.append(tag)
+    return tags
+
+
+def yaml_scalar(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float):
+        return str(value)
+    text = str(value).replace("\r\n", "\n").replace("\r", "\n").strip()
+    if not text:
+        return '""'
+    if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9 _./:+@-]*", text):
+        return text
+    return json.dumps(text, ensure_ascii=False)
+
+
+def frontmatter_to_text(frontmatter: dict[str, Any]) -> str:
+    lines = ["---"]
+    for key, value in frontmatter.items():
+        if value is None or value == "":
+            continue
+        if isinstance(value, list):
+            rendered = ", ".join(yaml_scalar(item) for item in value)
+            lines.append(f"{key}: [{rendered}]")
+        else:
+            lines.append(f"{key}: {yaml_scalar(value)}")
+    lines.append("---")
+    return "\n".join(lines) + "\n"
+
+
+def entity_content_from_payload(
+    payload: dict[str, Any],
+    *,
+    existing: dict[str, Any] | None = None,
+    is_safe_slug: Callable[[str], bool],
+    normalize_entity_type: Callable[[object], str | None],
+) -> tuple[str, str, str]:
+    slug = str(payload.get("slug", "")).strip()
+    if not is_safe_slug(slug):
+        raise ValueError(f"invalid slug: {slug!r}")
+    entity_type = str(payload.get("entity_type", "skill")).strip() or "skill"
+    normalized = normalize_entity_type(entity_type)
+    if normalized is None:
+        raise ValueError(f"unsupported entity_type: {entity_type!r}")
+    body = str(payload.get("body", "")).strip()
+    if not body:
+        raise ValueError("body is required")
+    title = str(payload.get("title") or slug).strip()
+    today = time.strftime("%Y-%m-%d", time.gmtime())
+    frontmatter = dict(existing or {})
+    frontmatter["title"] = title
+    frontmatter["type"] = normalized
+    frontmatter.setdefault("created", today)
+    frontmatter["updated"] = today
+    description = str(payload.get("description") or "").strip()
+    if description or "description" in payload:
+        frontmatter.pop("description", None)
+    if description:
+        frontmatter["description"] = description
+    tags = normalize_entity_tags(payload.get("tags"))
+    if tags or "tags" in payload:
+        frontmatter.pop("tags", None)
+    if tags:
+        frontmatter["tags"] = tags
+    source_url = str(payload.get("source_url") or "").strip()
+    if source_url or "source_url" in payload:
+        frontmatter.pop("source_url", None)
+    if source_url:
+        frontmatter["source_url"] = source_url
+    return slug, normalized, frontmatter_to_text(frontmatter) + body.rstrip() + "\n"
+
+
+def perform_load(
+    slug: str,
+    entity_type: str = "skill",
+    *,
+    command: str | None = None,
+    json_config: str | None = None,
+    deps: EntityRuntimeDeps,
+) -> tuple[bool, str]:
+    """Install/load one entity from the wiki. Returns (ok, message)."""
+    if not deps.is_safe_slug(slug):
+        return False, f"invalid slug: {slug!r}"
+    normalized_entity_type = deps.normalize_entity_type(entity_type)
+    if normalized_entity_type is None:
+        return False, f"unsupported entity_type: {entity_type!r}"
+    entity_type = normalized_entity_type
+    if entity_type == "harness":
+        return (
+            False,
+            "harness installs are managed by ctx-harness-install; "
+            f"run: ctx-harness-install {slug} --dry-run",
+        )
+    result: Any
+    try:
+        if entity_type == "agent":
+            from ctx.adapters.claude_code.install.agent_install import install_agent
+            result = install_agent(
+                slug,
+                wiki_dir=deps.wiki_dir(),
+                agents_dir=deps.claude_dir() / "agents",
+            )
+        elif entity_type == "mcp-server":
+            from ctx.adapters.claude_code.install.mcp_install import install_mcp
+            result = install_mcp(
+                slug,
+                wiki_dir=deps.wiki_dir(),
+                command=command,
+                json_config=json_config,
+                auto=True,
+            )
+        else:
+            from ctx.adapters.claude_code.install.skill_install import install_skill
+            result = install_skill(
+                slug,
+                wiki_dir=deps.wiki_dir(),
+                skills_dir=deps.claude_dir() / "skills",
+                security_scan=True,
+                security_scan_required=True,
+            )
+    except ImportError as exc:
+        return False, f"install import failed: {exc}"
+    except Exception as exc:  # noqa: BLE001
+        return False, f"{type(exc).__name__}: {exc}"
+    if result.status not in ("installed", "skipped-existing"):
+        return False, f"load failed: {result.message or result.status}"
+    deps.log_dashboard_entity_event(entity_type, "loaded", slug)
+    message = result.message or f"loaded {entity_type}:{slug}"
+    scan = getattr(result, "security_scan", None)
+    scan_output = str(getattr(scan, "output", "") or "").strip()
+    if scan_output:
+        message = f"{message}\n\nSkillSpector report:\n{scan_output}"
+    return True, message
+
+
+def perform_unload(
+    slug: str,
+    entity_type: str = "skill",
+    *,
+    deps: EntityRuntimeDeps,
+) -> tuple[bool, str]:
+    """Unload one entity by routing to the correct installer/uninstaller."""
+    if not deps.is_safe_slug(slug):
+        return False, f"invalid slug: {slug!r}"
+    normalized_entity_type = deps.normalize_entity_type(entity_type)
+    if normalized_entity_type is None:
+        return False, f"unsupported entity_type: {entity_type!r}"
+    entity_type = normalized_entity_type
+    if entity_type == "harness":
+        return (
+            False,
+            "harness installs are managed by ctx-harness-install; "
+            f"run: ctx-harness-install {slug} --uninstall --dry-run",
+        )
+    if entity_type == "mcp-server":
+        try:
+            from ctx.adapters.claude_code.install.mcp_install import uninstall_mcp
+        except ImportError as exc:
+            return False, f"mcp_install import failed: {exc}"
+        try:
+            result = uninstall_mcp(slug, wiki_dir=deps.wiki_dir())
+        except Exception as exc:  # noqa: BLE001
+            return False, f"{type(exc).__name__}: {exc}"
+        if result.status not in ("uninstalled",):
+            return False, f"uninstall failed: {result.message or result.status}"
+        deps.log_dashboard_entity_event("mcp-server", "unloaded", slug)
+        return True, f"unloaded mcp:{slug}"
+
+    if entity_type == "agent":
+        try:
+            removed_entries = deps.remove_loaded_manifest_entry(slug, "agent")
+        except Exception as exc:  # noqa: BLE001
+            return False, f"{type(exc).__name__}: {exc}"
+        if not removed_entries:
+            return False, f"{slug} was not in the loaded set"
+        deps.log_dashboard_entity_event("agent", "unloaded", slug)
+        return True, f"unloaded {slug}"
+
+    # Skills keep using the existing skill_unload module so skill-events.jsonl
+    # remains compatible with older usage and retention analytics.
+    try:
+        from ctx.adapters.claude_code.install.skill_unload import unload_from_session
+    except ImportError as exc:
+        return False, f"skill_unload import failed: {exc}"
+    try:
+        removed = unload_from_session([slug], entity_type=entity_type)
+    except Exception as exc:  # noqa: BLE001
+        return False, f"{type(exc).__name__}: {exc}"
+    if not removed:
+        return False, f"{slug} was not in the loaded set"
+    return True, f"unloaded {', '.join(removed)}"
+
+
+def search_wiki_entities(
+    query: str = "",
+    entity_type: str | None = None,
+    *,
+    limit: int = 80,
+    deps: EntityCrudDeps,
+) -> list[dict[str, Any]]:
+    terms = [term for term in re.split(r"\s+", query.lower().strip()) if term]
+    results: list[dict[str, Any]] = []
+    for slug, current_type, path in deps.iter_wiki_entity_paths(entity_type):
+        try:
+            head = path.read_text(encoding="utf-8", errors="replace")[:4096]
+        except OSError:
+            continue
+        frontmatter, body = deps.parse_frontmatter(head)
+        tags = deps.frontmatter_tags(frontmatter.get("tags", ""))
+        description = deps.frontmatter_text(frontmatter.get("description", ""))
+        display_slug = deps.display_slug(slug)
+        title = deps.display_label(
+            deps.frontmatter_text(frontmatter.get("title") or frontmatter.get("name") or slug),
+        )
+        haystack = " ".join(
+            [slug, display_slug, current_type, title, description, " ".join(tags), body],
+        ).lower()
+        if terms and not all(term in haystack for term in terms):
+            continue
+        results.append({
+            "slug": slug,
+            "display_slug": display_slug,
+            "type": current_type,
+            "title": title,
+            "description": description,
+            "tags": tags[:12],
+            "path": str(path),
+            "href": deps.entity_wiki_href(slug, current_type),
+        })
+        if len(results) >= max(1, limit):
+            break
+    return results
+
+
+def entity_live_in_manifest(slug: str, entity_type: str, *, deps: EntityCrudDeps) -> bool:
+    manifest = deps.read_manifest()
+    for entry in manifest.get("load", []):
+        if not isinstance(entry, dict):
+            continue
+        entry_slug = str(entry.get("skill") or entry.get("slug") or "")
+        entry_type = deps.normalize_entity_type(
+            str(entry.get("entity_type") or entry.get("type") or "skill"),
+        )
+        if entry_slug == slug and entry_type == entity_type:
+            return True
+    return False
+
+
+def upsert_wiki_entity(payload: dict[str, Any], *, deps: EntityCrudDeps) -> tuple[bool, str]:
+    try:
+        requested_slug = str(payload.get("slug", "")).strip()
+        requested_type = str(payload.get("entity_type", "skill")).strip() or "skill"
+        existing_detail = deps.wiki_entity_detail(requested_slug, requested_type)
+        existing_meta = (
+            existing_detail.get("frontmatter")
+            if isinstance(existing_detail, dict)
+            else None
+        )
+        confirm_update = str(payload.get("confirm_update", "")).strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "y",
+            "on",
+        }
+        if existing_detail is not None and not confirm_update:
+            return (
+                False,
+                f"existing {requested_type}:{requested_slug} found; review before "
+                "replacing. Benefit: keeps the catalog current. Risk: a lower-quality "
+                "manual edit can degrade recommendations. Resubmit with "
+                "confirm_update=true to apply.",
+            )
+        slug, entity_type, content = entity_content_from_payload(
+            payload,
+            existing=existing_meta if isinstance(existing_meta, dict) else None,
+            is_safe_slug=deps.is_safe_slug,
+            normalize_entity_type=deps.normalize_entity_type,
+        )
+        path = deps.wiki_entity_target_path(slug, entity_type)
+        with deps.file_lock(path):
+            deps.write_entity_text(path, content)
+        deps.queue_entity_refresh(entity_type, slug, path, content, "upsert")
+    except Exception as exc:  # noqa: BLE001
+        return False, f"{type(exc).__name__}: {exc}"
+    return True, f"saved {entity_type}:{slug} and queued graph refresh"
+
+
+def delete_wiki_entity(
+    slug: str,
+    entity_type: str,
+    *,
+    deps: EntityCrudDeps,
+) -> tuple[bool, str]:
+    try:
+        normalized = deps.normalize_entity_type(entity_type)
+        if normalized is None:
+            raise ValueError(f"unsupported entity_type: {entity_type!r}")
+        if not deps.is_safe_slug(slug):
+            raise ValueError(f"invalid slug: {slug!r}")
+        path = deps.wiki_entity_path(slug, normalized)
+        if path is None:
+            return False, f"no wiki entity found for {normalized}:{slug}"
+        if entity_live_in_manifest(slug, normalized, deps=deps):
+            unloaded, unload_detail = deps.perform_unload(slug, normalized)
+            if not unloaded:
+                return (
+                    False,
+                    f"{normalized}:{slug} is loaded; unload before delete failed: "
+                    f"{unload_detail}",
+                )
+        with deps.file_lock(path):
+            path.unlink()
+        deps.queue_entity_refresh(normalized, slug, path, "", "delete")
+    except Exception as exc:  # noqa: BLE001
+        return False, f"{type(exc).__name__}: {exc}"
+    return True, f"deleted {normalized}:{slug} and queued graph refresh"

src/ctx/dashboard_graph.py

@@ -0,0 +1,158 @@
+"""Dashboard graph response contract helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+GRAPH_SCHEMA = {
+    "name": "ctx.dashboard.graph.neighborhood",
+    "version": 1,
+}
+
+GRAPH_LAYOUT = {
+    "kind": "radial-3d",
+    "node_size_field": "node_size",
+    "node_size_min": 8.0,
+    "node_size_max": 24.0,
+    "edge_weight_field": "weight",
+}
+
+ENTITY_TYPES = ("skill", "agent", "mcp-server", "harness")
+SOURCE_EXPLANATIONS = {
+    "dashboard-index": "Served from the cached dashboard index for fast cold-start graph browsing.",
+    "networkx": "Served from the full in-memory graph because the cached dashboard index was unavailable or not current.",
+}
+
+
+def _node_data(node: Any) -> dict[str, Any]:
+    if not isinstance(node, dict):
+        raise ValueError("graph node must be an object")
+    data = node.get("data")
+    if not isinstance(data, dict):
+        raise ValueError("graph node data must be an object")
+    if not isinstance(data.get("id"), str) or not data["id"]:
+        raise ValueError("graph node data.id must be a non-empty string")
+    return data
+
+
+def _edge_data(edge: Any) -> dict[str, Any]:
+    if not isinstance(edge, dict):
+        raise ValueError("graph edge must be an object")
+    data = edge.get("data")
+    if not isinstance(data, dict):
+        raise ValueError("graph edge data must be an object")
+    if not isinstance(data.get("source"), str) or not data["source"]:
+        raise ValueError("graph edge data.source must be a non-empty string")
+    if not isinstance(data.get("target"), str) or not data["target"]:
+        raise ValueError("graph edge data.target must be a non-empty string")
+    return data
+
+
+def _int_value(value: Any, default: int = 0) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def graph_insights(
+    nodes: list[Any],
+    edges: list[Any],
+    *,
+    center: str | None,
+    source: str,
+) -> dict[str, Any]:
+    """Return dashboard-visible counts after validating graph response shape."""
+    by_type = {entity_type: 0 for entity_type in ENTITY_TYPES}
+    max_degree = 0
+    center_degree = 0
+    valid_ids: set[str] = set()
+
+    for node in nodes:
+        data = _node_data(node)
+        node_id = str(data["id"])
+        valid_ids.add(node_id)
+        entity_type = str(data.get("type") or "skill")
+        if entity_type in by_type:
+            by_type[entity_type] += 1
+        degree = _int_value(data.get("degree"))
+        max_degree = max(max_degree, degree)
+        if center is not None and node_id == center:
+            center_degree = degree
+
+    for edge in edges:
+        data = _edge_data(edge)
+        if data["source"] not in valid_ids or data["target"] not in valid_ids:
+            raise ValueError("graph edge endpoints must exist in nodes")
+
+    return {
+        "source": source,
+        "node_count": len(nodes),
+        "edge_count": len(edges),
+        "by_type": by_type,
+        "max_degree": max_degree,
+        "center_degree": center_degree,
+    }
+
+
+def graph_explanations(payload: dict[str, Any], *, source: str) -> dict[str, str]:
+    """Return plain-English graph/search explanations for the dashboard."""
+    resolved = payload.get("resolved")
+    if isinstance(resolved, dict) and resolved.get("query") and resolved.get("slug"):
+        if str(resolved.get("query")) != str(resolved.get("slug")):
+            focus = (
+                f"Focus search resolved {resolved['query']!r} to "
+                f"{resolved['slug']!r}."
+            )
+        else:
+            focus = f"Focus search matched {resolved['slug']!r}."
+    else:
+        center = payload.get("center")
+        focus = f"Focus search matched {center}." if center else "No graph focus matched."
+
+    return {
+        "source": SOURCE_EXPLANATIONS.get(
+            source,
+            f"Served from graph source {source}.",
+        ),
+        "search": (
+            "Focus search tries exact or normalized slug first, then display "
+            "slug, title, and tag matches."
+        ),
+        "layout": (
+            "Node size is cached metadata based on quality, usage, and graph "
+            "degree; it is bounded so important nodes stand out without "
+            "dominating the graph."
+        ),
+        "edges": (
+            "Edges are sorted by weight and expose shared_tags, reasons, and "
+            "available semantic/tag/slug-token signals."
+        ),
+        "focus": focus,
+    }
+
+
+def enrich_neighborhood(payload: dict[str, Any], *, source: str) -> dict[str, Any]:
+    """Attach schema, layout, and insight metadata to a graph neighborhood."""
+    nodes = payload.get("nodes")
+    edges = payload.get("edges")
+    if not isinstance(nodes, list):
+        raise ValueError("graph payload nodes must be a list")
+    if not isinstance(edges, list):
+        raise ValueError("graph payload edges must be a list")
+    center = payload.get("center")
+    if center is not None and not isinstance(center, str):
+        raise ValueError("graph payload center must be a string or null")
+
+    enriched = dict(payload)
+    enriched["schema"] = dict(GRAPH_SCHEMA)
+    enriched["layout"] = dict(GRAPH_LAYOUT)
+    enriched["insights"] = graph_insights(
+        nodes,
+        edges,
+        center=center,
+        source=source,
+    )
+    enriched["explanations"] = graph_explanations(payload, source=source)
+    return enriched

src/ctx_monitor.py

@@ -76,10 +76,12 @@ from collections import defaultdict, deque
 from http.cookies import CookieError, SimpleCookie
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from importlib.resources import files
-from pathlib import Path, PurePosixPath
+from pathlib import Path
 from typing import Any
 from urllib.parse import quote, unquote, urlsplit
 
+from ctx import dashboard_docs, dashboard_entities, dashboard_graph
+from ctx.core import entity_types as core_entity_types
 from ctx.core.wiki import wiki_queue
 from ctx.core.wiki.wiki_utils import parse_frontmatter_and_body
 from ctx.utils._file_lock import file_lock
@@ -102,8 +104,6 @@ _SIDECAR_FILTER_CACHE_VALUE: dict[tuple[Any, ...], list[dict[str, Any]]] = {}
 _KPI_SUMMARY_CACHE_KEY: tuple[Any, ...] | None = None
 _KPI_SUMMARY_CACHE_VALUE: Any | None = None
 _KPI_SUMMARY_CACHE_AT = 0.0
-_DOCS_RENDER_CACHE_KEY: tuple[Any, ...] | None = None
-_DOCS_RENDER_CACHE_VALUE: str | None = None
 _WIKI_RENDER_CACHE_KEY: tuple[Any, ...] | None = None
 _WIKI_RENDER_CACHE_VALUE: str | None = None
 _WIKI_INDEX_LIMIT_PER_TYPE = 500
@@ -229,16 +229,10 @@ def _load_dashboard_graph() -> Any:
 
 
 def _mcp_shard(slug: str) -> str:
-    first = slug[0] if slug else ""
-    return first if first.isalpha() else "0-9"
+    return core_entity_types.mcp_shard(slug)
 
 
-_DASHBOARD_ENTITY_SOURCES: tuple[tuple[str, str, bool], ...] = (
-    ("skills", "skill", False),
-    ("agents", "agent", False),
-    ("mcp-servers", "mcp-server", True),
-    ("harnesses", "harness", False),
-)
+_DASHBOARD_ENTITY_SOURCES: tuple[tuple[str, str, bool], ...] = core_entity_types.entity_source_specs()
 _DASHBOARD_ENTITY_TYPES: tuple[str, ...] = tuple(
     entity_type for _, entity_type, _ in _DASHBOARD_ENTITY_SOURCES
 )
@@ -246,21 +240,10 @@ _DEFAULT_GRAPH_FOCUS_SLUG = "github"
 
 
 def _normalize_dashboard_entity_type(raw: object) -> str | None:
-    if raw is None:
-        return None
-    value = str(raw).strip()
-    normalized = {
-        "skills": "skill",
-        "skill": "skill",
-        "agents": "agent",
-        "agent": "agent",
-        "mcp": "mcp-server",
-        "mcp-server": "mcp-server",
-        "mcp-servers": "mcp-server",
-        "harness": "harness",
-        "harnesses": "harness",
-    }.get(value, value)
-    return normalized if normalized in _DASHBOARD_ENTITY_TYPES else None
+    return core_entity_types.normalize_entity_type(
+        raw,
+        allowed=_DASHBOARD_ENTITY_TYPES,
+    )
 
 
 def _audit_entity_type(row: dict) -> str | None:
@@ -291,14 +274,12 @@ def _wiki_entity_path(slug: str, entity_type: str | None = None) -> Path | None:
     # Validate slug so a crafted request can't escape the wiki tree.
     if not _is_safe_slug(slug):
         return None
-    for sub, current_type, recursive in _DASHBOARD_ENTITY_SOURCES:
+    for _sub, current_type, _recursive in _DASHBOARD_ENTITY_SOURCES:
         if entity_type is not None and entity_type != current_type:
             continue
-        p = (
-            _wiki_dir() / "entities" / sub / _mcp_shard(slug) / f"{slug}.md"
-            if recursive
-            else _wiki_dir() / "entities" / sub / f"{slug}.md"
-        )
+        p = core_entity_types.entity_page_path(_wiki_dir(), current_type, slug)
+        if p is None:
+            continue
         if p.exists():
             return p
     return None
@@ -311,13 +292,10 @@ def _wiki_entity_target_path(slug: str, entity_type: str) -> Path:
     normalized = _normalize_dashboard_entity_type(entity_type)
     if normalized is None:
         raise ValueError(f"unsupported entity_type: {entity_type!r}")
-    for sub, current_type, recursive in _DASHBOARD_ENTITY_SOURCES:
-        if normalized != current_type:
-            continue
-        if recursive:
-            return _wiki_dir() / "entities" / sub / _mcp_shard(slug) / f"{slug}.md"
-        return _wiki_dir() / "entities" / sub / f"{slug}.md"
-    raise ValueError(f"unsupported entity_type: {entity_type!r}")
+    path = core_entity_types.entity_page_path(_wiki_dir(), normalized, slug)
+    if path is None:
+        raise ValueError(f"unsupported entity_type: {entity_type!r}")
+    return path
 
 
 def _iter_wiki_entity_paths(
@@ -369,121 +347,12 @@ def _search_wiki_entities(
     *,
     limit: int = 80,
 ) -> list[dict[str, Any]]:
-    terms = [term for term in re.split(r"\s+", query.lower().strip()) if term]
-    results: list[dict[str, Any]] = []
-    for slug, current_type, path in _iter_wiki_entity_paths(entity_type):
-        try:
-            head = path.read_text(encoding="utf-8", errors="replace")[:4096]
-        except OSError:
-            continue
-        frontmatter, body = _parse_frontmatter(head)
-        tags = _frontmatter_tags(frontmatter.get("tags", ""), limit=None)
-        description = _frontmatter_text(frontmatter.get("description", ""))
-        display_slug = _display_slug(slug)
-        title = _display_label(
-            _frontmatter_text(frontmatter.get("title") or frontmatter.get("name") or slug),
-            fallback_slug=slug,
-        )
-        haystack = " ".join(
-            [slug, display_slug, current_type, title, description, " ".join(tags), body],
-        ).lower()
-        if terms and not all(term in haystack for term in terms):
-            continue
-        results.append({
-            "slug": slug,
-            "display_slug": display_slug,
-            "type": current_type,
-            "title": title,
-            "description": description,
-            "tags": tags[:12],
-            "path": str(path),
-            "href": _entity_wiki_href(slug, current_type),
-        })
-        if len(results) >= max(1, limit):
-            break
-    return results
-
-
-def _normalize_entity_tags(raw: Any) -> list[str]:
-    if isinstance(raw, list):
-        parts = raw
-    else:
-        parts = re.split(r"[,\n]+", str(raw or ""))
-    tags: list[str] = []
-    seen: set[str] = set()
-    for part in parts:
-        tag = re.sub(r"[^a-z0-9_.+-]+", "-", str(part).lower()).strip("-_.+")
-        if tag and tag not in seen:
-            seen.add(tag)
-            tags.append(tag)
-    return tags
-
-
-def _yaml_scalar(value: Any) -> str:
-    if isinstance(value, bool):
-        return "true" if value else "false"
-    if isinstance(value, int | float):
-        return str(value)
-    text = str(value).replace("\r\n", "\n").replace("\r", "\n").strip()
-    if not text:
-        return '""'
-    if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9 _./:+@-]*", text):
-        return text
-    return json.dumps(text, ensure_ascii=False)
-
-
-def _frontmatter_to_text(frontmatter: dict[str, Any]) -> str:
-    lines = ["---"]
-    for key, value in frontmatter.items():
-        if value is None or value == "":
-            continue
-        if isinstance(value, list):
-            rendered = ", ".join(_yaml_scalar(item) for item in value)
-            lines.append(f"{key}: [{rendered}]")
-        else:
-            lines.append(f"{key}: {_yaml_scalar(value)}")
-    lines.append("---")
-    return "\n".join(lines) + "\n"
-
-
-def _entity_content_from_payload(
-    payload: dict[str, Any],
-    *,
-    existing: dict[str, Any] | None = None,
-) -> tuple[str, str, str]:
-    slug = str(payload.get("slug", "")).strip()
-    if not _is_safe_slug(slug):
-        raise ValueError(f"invalid slug: {slug!r}")
-    entity_type = str(payload.get("entity_type", "skill")).strip() or "skill"
-    normalized = _normalize_dashboard_entity_type(entity_type)
-    if normalized is None:
-        raise ValueError(f"unsupported entity_type: {entity_type!r}")
-    body = str(payload.get("body", "")).strip()
-    if not body:
-        raise ValueError("body is required")
-    title = str(payload.get("title") or slug).strip()
-    today = time.strftime("%Y-%m-%d", time.gmtime())
-    frontmatter = dict(existing or {})
-    frontmatter["title"] = title
-    frontmatter["type"] = normalized
-    frontmatter.setdefault("created", today)
-    frontmatter["updated"] = today
-    description = str(payload.get("description") or "").strip()
-    if description or "description" in payload:
-        frontmatter.pop("description", None)
-    if description:
-        frontmatter["description"] = description
-    tags = _normalize_entity_tags(payload.get("tags"))
-    if tags or "tags" in payload:
-        frontmatter.pop("tags", None)
-    if tags:
-        frontmatter["tags"] = tags
-    source_url = str(payload.get("source_url") or "").strip()
-    if source_url or "source_url" in payload:
-        frontmatter.pop("source_url", None)
-    if source_url:
-        frontmatter["source_url"] = source_url
-    return slug, normalized, _frontmatter_to_text(frontmatter) + body.rstrip() + "\n"
+    return dashboard_entities.search_wiki_entities(
+        query,
+        entity_type,
+        limit=limit,
+        deps=_entity_crud_deps(),
+    )
 
 
 def _queue_entity_refresh(
@@ -514,94 +383,59 @@ def _queue_entity_refresh(
     )
 
 
-def _upsert_wiki_entity(payload: dict[str, Any]) -> tuple[bool, str]:
-    try:
-        requested_slug = str(payload.get("slug", "")).strip()
-        requested_type = str(payload.get("entity_type", "skill")).strip() or "skill"
-        existing_detail = _wiki_entity_detail(requested_slug, requested_type)
-        existing_meta = (
-            existing_detail.get("frontmatter")
-            if isinstance(existing_detail, dict)
-            else None
-        )
-        confirm_update = str(payload.get("confirm_update", "")).strip().lower() in {
-            "1",
-            "true",
-            "yes",
-            "y",
-            "on",
-        }
-        if existing_detail is not None and not confirm_update:
-            return (
-                False,
-                f"existing {requested_type}:{requested_slug} found; review before "
-                "replacing. Benefit: keeps the catalog current. Risk: a lower-quality "
-                "manual edit can degrade recommendations. Resubmit with "
-                "confirm_update=true to apply.",
-            )
-        slug, entity_type, content = _entity_content_from_payload(
-            payload,
-            existing=existing_meta if isinstance(existing_meta, dict) else None,
-        )
-        path = _wiki_entity_target_path(slug, entity_type)
-        with file_lock(path):
-            _safe_atomic_write_text(path, content, encoding="utf-8")
-        _queue_entity_refresh(
+def _write_entity_text(path: Path, content: str) -> None:
+    _safe_atomic_write_text(path, content, encoding="utf-8")
+
+
+def _entity_crud_deps() -> dashboard_entities.EntityCrudDeps:
+    return dashboard_entities.EntityCrudDeps(
+        is_safe_slug=_is_safe_slug,
+        normalize_entity_type=_normalize_dashboard_entity_type,
+        wiki_entity_detail=_wiki_entity_detail,
+        wiki_entity_target_path=_wiki_entity_target_path,
+        wiki_entity_path=_wiki_entity_path,
+        iter_wiki_entity_paths=_iter_wiki_entity_paths,
+        read_manifest=_read_manifest,
+        perform_unload=_perform_unload,
+        queue_entity_refresh=lambda entity_type, slug, entity_path, content, action: _queue_entity_refresh(
             entity_type=entity_type,
             slug=slug,
-            entity_path=path,
+            entity_path=entity_path,
             content=content,
-            action="upsert",
-        )
-    except Exception as exc:  # noqa: BLE001
-        return False, f"{type(exc).__name__}: {exc}"
-    return True, f"saved {entity_type}:{slug} and queued graph refresh"
+            action=action,
+        ),
+        file_lock=file_lock,
+        write_entity_text=_write_entity_text,
+        parse_frontmatter=_parse_frontmatter,
+        frontmatter_tags=lambda value: _frontmatter_tags(value, limit=None),
+        frontmatter_text=_frontmatter_text,
+        display_slug=_display_slug,
+        display_label=lambda value: _display_label(value),
+        entity_wiki_href=_entity_wiki_href,
+    )
 
 
-def _entity_live_in_manifest(slug: str, entity_type: str) -> bool:
-    manifest = _read_manifest()
-    for entry in manifest.get("load", []):
-        if not isinstance(entry, dict):
-            continue
-        entry_slug = str(entry.get("skill") or entry.get("slug") or "")
-        entry_type = _normalize_dashboard_entity_type(
-            str(entry.get("entity_type") or entry.get("type") or "skill"),
-        )
-        if entry_slug == slug and entry_type == entity_type:
-            return True
-    return False
+def _entity_runtime_deps() -> dashboard_entities.EntityRuntimeDeps:
+    return dashboard_entities.EntityRuntimeDeps(
+        is_safe_slug=_is_safe_slug,
+        normalize_entity_type=_normalize_dashboard_entity_type,
+        wiki_dir=_wiki_dir,
+        claude_dir=_claude_dir,
+        log_dashboard_entity_event=_log_dashboard_entity_event,
+        remove_loaded_manifest_entry=_remove_loaded_manifest_entry,
+    )
+
+
+def _upsert_wiki_entity(payload: dict[str, Any]) -> tuple[bool, str]:
+    return dashboard_entities.upsert_wiki_entity(payload, deps=_entity_crud_deps())
 
 
 def _delete_wiki_entity(slug: str, entity_type: str) -> tuple[bool, str]:
-    try:
-        normalized = _normalize_dashboard_entity_type(entity_type)
-        if normalized is None:
-            raise ValueError(f"unsupported entity_type: {entity_type!r}")
-        if not _is_safe_slug(slug):
-            raise ValueError(f"invalid slug: {slug!r}")
-        path = _wiki_entity_path(slug, entity_type=normalized)
-        if path is None:
-            return False, f"no wiki entity found for {normalized}:{slug}"
-        if _entity_live_in_manifest(slug, normalized):
-            unloaded, unload_detail = _perform_unload(slug, normalized)
-            if not unloaded:
-                return (
-                    False,
-                    f"{normalized}:{slug} is loaded; unload before delete failed: "
-                    f"{unload_detail}",
-                )
-        with file_lock(path):
-            path.unlink()
-        _queue_entity_refresh(
-            entity_type=normalized,
-            slug=slug,
-            entity_path=path,
-            content="",
-            action="delete",
-        )
-    except Exception as exc:  # noqa: BLE001
-        return False, f"{type(exc).__name__}: {exc}"
-    return True, f"deleted {normalized}:{slug} and queued graph refresh"
+    return dashboard_entities.delete_wiki_entity(
+        slug,
+        entity_type,
+        deps=_entity_crud_deps(),
+    )
 
 
 def _parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
@@ -3015,13 +2849,13 @@ def _graph_neighborhood_from_index(
             frontier = next_frontier
             if len(nodes_out) >= limit:
                 break
-        return {
+        return dashboard_graph.enrich_neighborhood({
             "nodes": list(nodes_out.values()),
             "edges": edges_out,
             "center": center,
             "resolved": resolved or {"source": "dashboard-index"},
             "suggestions": [],
-        }
+        }, source="dashboard-index")
     except (OSError, sqlite3.Error, json.JSONDecodeError, zlib.error, KeyError, TypeError):
         return None
     finally:
@@ -3184,13 +3018,13 @@ def _graph_neighborhood(
         if len(nodes_out) >= limit:
             break
 
-    return {
+    return dashboard_graph.enrich_neighborhood({
         "nodes": list(nodes_out.values()),
         "edges": edges_out,
         "center": center,
         "resolved": resolved,
         "suggestions": suggestions,
-    }
+    }, source="networkx")
 
 
 def _graph_stats() -> dict:
@@ -4126,6 +3960,11 @@ def _render_graph(focus: str | None = None, focus_type: str | None = None) -> st
         "<span id='graph-match-count' class='muted'>—</span>"
         "</div>"
         "<div class='card'><span id='msg' class='muted'></span></div>"
+        "<div class='card'><strong>Why this view?</strong>"
+        "<p id='graph-explanation' class='muted' "
+        "style='font-size:0.78rem; margin:0.45rem 0 0 0;'>"
+        "Search a slug to see why ctx picked this neighborhood and how to read it."
+        "</p></div>"
         "</aside>"
         # Right: graph list panel
         "<div id='cy' style='width:100%; height:75vh; border:1px solid #ddd; "
@@ -4193,6 +4032,10 @@ def _render_graph(focus: str | None = None, focus_type: str | None = None) -> st
         "  const weight = Number(d.weight || 0).toFixed(3);\n"
         "  return nodeSlug(d.source) + ' ↔ ' + nodeSlug(d.target) + ' · weight ' + weight + ' · shared: ' + tags + ' · reasons: ' + reasons;\n"
         "}\n"
+        "function graphExplanation(g) {\n"
+        "  const e = g.explanations || {};\n"
+        "  return [e.focus, e.source, e.search, e.layout, e.edges].filter(Boolean).join(' ');\n"
+        "}\n"
         "function renderGraph3d(g) {\n"
         "  const nodes = g.nodes || [];\n"
         "  const edges = g.edges || [];\n"
@@ -4340,6 +4183,7 @@ def _render_graph(focus: str | None = None, focus_type: str | None = None) -> st
         "  try { renderGraph3d(g); } catch (err) { renderFallback(g); }\n"
         "  const resolved = g.resolved && g.resolved.query !== g.resolved.slug ? ' · showing ' + g.resolved.slug + ' for ' + g.resolved.query : '';\n"
         "  document.getElementById('msg').textContent = fmtCount(g.nodes.length) + ' nodes · ' + fmtCount(g.edges.length) + ' edges' + resolved;\n"
+        "  document.getElementById('graph-explanation').textContent = graphExplanation(g);\n"
         "  applyFilters();\n"
         "}\n"
         "function selectedFocusType() { return document.getElementById('focus-type').value || ''; }\n"
@@ -4838,42 +4682,63 @@ def _wiki_render_cache_key(
     )
 
 
-def _wiki_render_cache_token(cache_key: tuple[Any, ...]) -> str:
+def _disk_cache_token(cache_key: tuple[Any, ...]) -> str:
     return json.dumps(cache_key, separators=(",", ":"), sort_keys=True)
 
 
-def _wiki_render_disk_cache_path() -> Path:
-    return _claude_dir() / ".ctx-monitor-wiki-cache.json"
-
-
-def _read_wiki_render_disk_cache(cache_token: str) -> str | None:
+def _read_disk_cache_payload(path: Path, cache_token: str) -> dict[str, Any] | None:
     try:
-        data = json.loads(_wiki_render_disk_cache_path().read_text(encoding="utf-8"))
+        data = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
         return None
     if not isinstance(data, dict):
         return None
     if data.get("schema_version") != 1 or data.get("cache_token") != cache_token:
         return None
-    html_text = data.get("html")
-    return html_text if isinstance(html_text, str) else None
+    return data
 
 
-def _write_wiki_render_disk_cache(cache_token: str, html_text: str) -> None:
+def _write_disk_cache_payload(
+    path: Path,
+    cache_token: str,
+    payload: dict[str, Any],
+    *,
+    sort_keys: bool = False,
+) -> None:
     try:
         _atomic_write_text(
-            _wiki_render_disk_cache_path(),
-            json.dumps({
-                "schema_version": 1,
-                "cache_token": cache_token,
-                "html": html_text,
-            }, ensure_ascii=False) + "\n",
+            path,
+            json.dumps(
+                {
+                    "schema_version": 1,
+                    "cache_token": cache_token,
+                    **payload,
+                },
+                ensure_ascii=False,
+                sort_keys=sort_keys,
+            ) + "\n",
             encoding="utf-8",
         )
     except (OSError, TypeError, ValueError):
         return
 
 
+def _read_html_disk_cache(path: Path, cache_token: str) -> str | None:
+    data = _read_disk_cache_payload(path, cache_token)
+    if data is None:
+        return None
+    html_text = data.get("html")
+    return html_text if isinstance(html_text, str) else None
+
+
+def _write_html_disk_cache(path: Path, cache_token: str, html_text: str) -> None:
+    _write_disk_cache_payload(path, cache_token, {"html": html_text})
+
+
+def _wiki_render_disk_cache_path() -> Path:
+    return _claude_dir() / ".ctx-monitor-wiki-cache.json"
+
+
 def _render_wiki_index(entity_type: str | None = None, query: str = "") -> str:
     """Card grid of every wiki entity — search + type filter + sidecar grades."""
     selected_type = _normalize_dashboard_entity_type(entity_type) if entity_type else None
@@ -4888,8 +4753,8 @@ def _render_wiki_index(entity_type: str | None = None, query: str = "") -> str:
     if cache_key is not None:
         if _WIKI_RENDER_CACHE_KEY == cache_key and _WIKI_RENDER_CACHE_VALUE is not None:
             return _WIKI_RENDER_CACHE_VALUE
-        cache_token = _wiki_render_cache_token(cache_key)
-        cached = _read_wiki_render_disk_cache(cache_token)
+        cache_token = _disk_cache_token(cache_key)
+        cached = _read_html_disk_cache(_wiki_render_disk_cache_path(), cache_token)
         if cached is not None:
             _WIKI_RENDER_CACHE_KEY = cache_key
             _WIKI_RENDER_CACHE_VALUE = cached
@@ -5018,689 +4883,51 @@ def _render_wiki_index(entity_type: str | None = None, query: str = "") -> str:
     )
     html_out = _layout("Wiki", body)
     if cache_key is not None:
-        _write_wiki_render_disk_cache(cache_token, html_out)
+        _write_html_disk_cache(_wiki_render_disk_cache_path(), cache_token, html_out)
         _WIKI_RENDER_CACHE_KEY = cache_key
         _WIKI_RENDER_CACHE_VALUE = html_out
     return html_out
 
 
-def _docs_roots() -> list[Path]:
-    roots: list[Path] = []
-    for root in (Path.cwd(), Path(__file__).resolve().parent.parent):
-        if root not in roots and (root / "docs").is_dir():
-            roots.append(root)
-    return roots
-
-
-def _docs_cache_files() -> list[Path]:
-    files: list[Path] = []
-    seen: set[Path] = set()
-    for root in _docs_roots():
-        candidates = [root / "README.md", root / "graph" / "README.md", root / "mkdocs.yml"]
-        docs_dir = root / "docs"
-        if docs_dir.is_dir():
-            candidates.extend(sorted(docs_dir.rglob("*.md")))
-        for path in candidates:
-            if not path.is_file():
-                continue
-            try:
-                resolved = path.resolve()
-            except OSError:
-                resolved = path
-            if resolved in seen:
-                continue
-            seen.add(resolved)
-            files.append(path)
-    return files
-
-
-def _docs_render_cache_key() -> tuple[Any, ...]:
-    parts: list[Any] = []
-    try:
-        stat = Path(__file__).stat()
-        parts.append(("ctx_monitor", stat.st_mtime_ns, stat.st_size))
-    except OSError:
-        parts.append(("ctx_monitor", None, None))
-    for asset_name in ("monitor.css", "monitor-docs.js"):
-        try:
-            asset_text = _monitor_asset_text(asset_name)
-            asset_hash = hashlib.sha256(asset_text.encode("utf-8")).hexdigest()
-        except Exception:
-            asset_hash = ""
-        parts.append(("asset", asset_name, asset_hash))
-    for path in _docs_cache_files():
-        try:
-            stat = path.stat()
-            path_name = str(path.resolve())
-            parts.append((path_name, stat.st_mtime_ns, stat.st_size))
-        except OSError:
-            continue
-    return tuple(parts)
-
 
-def _docs_render_cache_token(cache_key: tuple[Any, ...]) -> str:
-    return json.dumps(cache_key, separators=(",", ":"), sort_keys=True)
+def _docs_roots() -> list[Path]:
+    return dashboard_docs.docs_roots(Path.cwd(), Path(__file__).resolve().parent.parent)
 
 
 def _docs_render_disk_cache_path() -> Path:
-    return _claude_dir() / ".ctx-monitor-docs-cache.json"
-
-
-def _read_docs_render_disk_cache(cache_token: str) -> str | None:
-    try:
-        data = json.loads(_docs_render_disk_cache_path().read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-    if not isinstance(data, dict):
-        return None
-    if data.get("schema_version") != 1 or data.get("cache_token") != cache_token:
-        return None
-    html_text = data.get("html")
-    return html_text if isinstance(html_text, str) else None
-
-
-def _write_docs_render_disk_cache(cache_token: str, html_text: str) -> None:
-    try:
-        _atomic_write_text(
-            _docs_render_disk_cache_path(),
-            json.dumps({
-                "schema_version": 1,
-                "cache_token": cache_token,
-                "html": html_text,
-            }, ensure_ascii=False) + "\n",
-            encoding="utf-8",
-        )
-    except (OSError, TypeError, ValueError):
-        return
-
-
-def _doc_title(text: str, fallback: str) -> str:
-    for line in text.splitlines():
-        match = re.match(r"^#\s+(.+?)\s*$", line)
-        if match:
-            return match.group(1).strip()
-    return fallback
-
+    return dashboard_docs.docs_render_disk_cache_path(_claude_dir())
 
-def _doc_summary(text: str) -> str:
-    in_frontmatter = text.startswith("---\n")
-    for block in re.split(r"\n\s*\n", text):
-        chunk = block.strip()
-        if not chunk:
-            continue
-        if in_frontmatter:
-            if chunk == "---" or chunk.endswith("\n---"):
-                in_frontmatter = False
-            continue
-        if chunk.startswith("#") or chunk.startswith("```") or chunk.startswith("<!--"):
-            continue
-        summary = re.sub(r"\s+", " ", chunk)
-        summary, _truncated = _truncate_text(summary, 180)
-        return summary
-    return ""
 
+def _docs_index_entries() -> list[dict[str, Any]]:
+    return dashboard_docs.docs_index_entries(_docs_roots())
 
-def _strip_doc_frontmatter(text: str) -> str:
-    if not text.startswith("---\n"):
-        return text
-    parts = text.split("---", 2)
-    return parts[2].lstrip() if len(parts) == 3 else text
 
-
-def _doc_anchor(value: str) -> str:
-    return _slugish(value) or "docs"
-
-
-def _docs_index_entries() -> list[dict[str, str]]:
-    entries: list[dict[str, str]] = []
-    seen: set[str] = set()
-    for root in _docs_roots():
-        candidates = [root / "README.md", root / "graph" / "README.md"]
-        candidates.extend(sorted((root / "docs").rglob("*.md")))
-        for path in candidates:
-            if not path.is_file():
-                continue
-            rel = path.relative_to(root).as_posix()
-            if rel == "docs/SKILL.md":
-                continue
-            if rel in seen:
-                continue
-            seen.add(rel)
-            try:
-                text = path.read_text(encoding="utf-8", errors="replace")
-            except OSError:
-                continue
-            text = _strip_doc_frontmatter(text)
-            title = _doc_title(text, path.stem.replace("-", " ").title())
-            entries.append({
-                "title": title,
-                "path": rel,
-                "summary": _doc_summary(text),
-                "body": text,
-            })
-    return sorted(entries, key=lambda row: row["path"])
-
-
-def _docs_nav_from_mkdocs(
-    root: Path,
-    entries_by_path: dict[str, dict[str, str]],
-) -> list[dict[str, Any]]:
-    mkdocs_path = root / "mkdocs.yml"
-    if not mkdocs_path.is_file():
-        return []
-    try:
-        import yaml  # type: ignore[import-untyped]
-
-        data = yaml.load(mkdocs_path.read_text(encoding="utf-8"), Loader=yaml.BaseLoader) or {}
-    except Exception:
-        return []
-    raw_nav = data.get("nav")
-    if not isinstance(raw_nav, list):
-        return []
-
-    def pages_from_nav(value: Any) -> list[tuple[str, str]]:
-        if isinstance(value, str):
-            return [(Path(value).stem.replace("-", " ").title(), f"docs/{value}")]
-        if isinstance(value, list):
-            pages: list[tuple[str, str]] = []
-            for child in value:
-                pages.extend(pages_from_nav(child))
-            return pages
-        if isinstance(value, dict):
-            pages = []
-            for label, child in value.items():
-                if isinstance(child, str):
-                    pages.append((str(label), f"docs/{child}"))
-                else:
-                    pages.extend(pages_from_nav(child))
-            return pages
-        return []
-
-    tabs: list[dict[str, Any]] = []
-    for item in raw_nav:
-        if not isinstance(item, dict):
-            continue
-        for label, value in item.items():
-            pages = [
-                {**entries_by_path[path], "nav_title": page_label}
-                for page_label, path in pages_from_nav(value)
-                if path in entries_by_path
-            ]
-            if pages:
-                tabs.append({
-                    "label": str(label),
-                    "slug": _doc_anchor(str(label)),
-                    "pages": pages,
-                })
-    return tabs
-
-
-def _docs_tabs(entries: list[dict[str, str]]) -> list[dict[str, Any]]:
-    entries_by_path = {entry["path"]: entry for entry in entries}
-    tabs: list[dict[str, Any]] = []
-    used: set[str] = set()
-    for root in _docs_roots():
-        tabs = _docs_nav_from_mkdocs(root, entries_by_path)
-        if tabs:
-            break
-    for tab in tabs:
-        for page in tab["pages"]:
-            used.add(str(page["path"]))
-
-    repo_pages = [
-        entries_by_path[path]
-        for path in ("README.md", "graph/README.md")
-        if path in entries_by_path
-    ]
-    if repo_pages:
-        tabs.append({"label": "Repo", "slug": "repo", "pages": repo_pages})
-        used.update(str(page["path"]) for page in repo_pages)
-
-    other_pages = [
-        entry
-        for entry in entries
-        if entry["path"] not in used and entry["path"] != "docs/SKILL.md"
-    ]
-    if other_pages:
-        tabs.append({"label": "Other", "slug": "other", "pages": other_pages})
-    if not tabs and entries:
-        tabs.append({"label": "Docs", "slug": "docs", "pages": entries})
-    return tabs
-
-
-def _docs_heading_text(raw: str) -> str:
-    raw = re.sub(r"\s+\{#[^}]+\}\s*$", "", raw.strip())
-    raw = re.sub(r"`([^`]+)`", r"\1", raw)
-    raw = re.sub(r"!\[([^\]]*)\]\([^)]+\)", r"\1", raw)
-    raw = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", raw)
-    raw = re.sub(r"[*_~]+", "", raw)
-    return re.sub(r"\s+", " ", raw).strip()
-
-
-def _docs_heading_id(page_anchor: str, title: str, seen: dict[str, int]) -> str:
-    base = f"{page_anchor}-{_doc_anchor(title)}"
-    count = seen.get(base, 0)
-    seen[base] = count + 1
-    return base if count == 0 else f"{base}_{count}"
-
-
-def _docs_heading_items(markdown_text: str, page_anchor: str) -> list[dict[str, Any]]:
-    headings: list[dict[str, Any]] = []
-    seen: dict[str, int] = {}
-    in_fence = False
-    for line in markdown_text.splitlines():
-        stripped = line.strip()
-        if stripped.startswith(("```", "~~~")):
-            in_fence = not in_fence
-            continue
-        if in_fence:
-            continue
-        match = re.match(r"^(#{1,4})\s+(.+?)\s*#*\s*$", line)
-        if not match:
-            continue
-        level = len(match.group(1))
-        title = _docs_heading_text(match.group(2))
-        if not title:
-            continue
-        heading_id = _docs_heading_id(page_anchor, title, seen)
-        if level >= 2:
-            headings.append({"level": level, "title": title, "id": heading_id})
-    return headings
-
-
-def _docs_page_anchor(tab_slug: str, path: str) -> str:
-    return f"doc-{tab_slug}-{_doc_anchor(path)}"
-
-
-def _normalise_doc_path(path: str) -> str:
-    parts: list[str] = []
-    for part in PurePosixPath(path).parts:
-        if part in ("", "."):
-            continue
-        if part == "..":
-            if parts:
-                parts.pop()
-            continue
-        parts.append(part)
-    return PurePosixPath(*parts).as_posix() if parts else ""
-
-
-def _resolve_docs_link_path(source_path: str, href_path: str, page_anchors: dict[str, tuple[str, str]]) -> str | None:
-    base = PurePosixPath(source_path).parent
-    resolved = _normalise_doc_path((base / href_path).as_posix())
-    candidates = [resolved]
-    if not resolved.endswith(".md"):
-        stripped = resolved.rstrip("/")
-        candidates.extend([f"{stripped}.md", f"{stripped}/index.md"])
-    for candidate in candidates:
-        if candidate in page_anchors:
-            return candidate
-    return None
-
-
-def _docs_dashboard_link(
-    source_path: str,
-    source_tab: str,
-    source_anchor: str,
-    href: str,
-    page_anchors: dict[str, tuple[str, str]],
-) -> tuple[str, str, str] | None:
-    href = html.unescape(href).strip()
-    lowered = href.lower()
-    if (
-        not href
-        or lowered.startswith(("http://", "https://", "mailto:", "tel:", "javascript:"))
-        or href.startswith("/")
-    ):
-        return None
-    href_path, sep, fragment = href.partition("#")
-    if not href_path:
-        target_tab = source_tab
-        target_anchor = source_anchor
-    else:
-        resolved_path = _resolve_docs_link_path(source_path, href_path, page_anchors)
-        if resolved_path is None:
-            return None
-        target_tab, target_anchor = page_anchors[resolved_path]
-    if sep and fragment:
-        fragment_anchor = _doc_anchor(unquote(fragment))
-        if not fragment_anchor.startswith(target_anchor):
-            fragment_anchor = f"{target_anchor}-{fragment_anchor}"
-        return f"#{fragment_anchor}", target_tab, fragment_anchor
-    return f"#{target_anchor}", target_tab, target_anchor
-
-
-def _rewrite_docs_links(
-    rendered_html: str,
-    source_path: str,
-    source_tab: str,
-    source_anchor: str,
-    page_anchors: dict[str, tuple[str, str]],
-) -> str:
-    def replace_link(match: re.Match[str]) -> str:
-        before = match.group(1)
-        href = match.group(2)
-        after = match.group(3)
-        resolved = _docs_dashboard_link(source_path, source_tab, source_anchor, href, page_anchors)
-        if resolved is None:
-            return match.group(0)
-        dashboard_href, target_tab, target_anchor = resolved
-        return (
-            f"<a{before}href=\"{html.escape(dashboard_href, quote=True)}\""
-            f" data-doc-tab=\"{html.escape(target_tab, quote=True)}\""
-            f" data-doc-target=\"{html.escape(target_anchor, quote=True)}\"{after}>"
-        )
-
-    return re.sub(r"<a([^>]*?)href=\"([^\"]+)\"([^>]*)>", replace_link, rendered_html)
+def _docs_tabs(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return dashboard_docs.docs_tabs(entries, _docs_roots())
 
 
 def _render_docs_markdown(markdown_text: str, page_anchor: str) -> str:
-    """Render repo docs with MkDocs-like Markdown support when available."""
-    markdown_text = re.sub(r":octicons-arrow-right-24:", "->", markdown_text)
-    markdown_text = re.sub(r":octicons-[a-z0-9-]+:", "", markdown_text)
-    try:
-        import markdown as markdown_lib  # type: ignore[import-untyped]
-
-        rendered = str(markdown_lib.markdown(
-            markdown_text,
-            extensions=[
-                "admonition",
-                "attr_list",
-                "def_list",
-                "fenced_code",
-                "footnotes",
-                "md_in_html",
-                "tables",
-                "toc",
-                "pymdownx.details",
-                "pymdownx.superfences",
-                "pymdownx.tabbed",
-                "pymdownx.tasklist",
-                "pymdownx.inlinehilite",
-            ],
-            extension_configs={
-                "toc": {
-                    "permalink": True,
-                    "slugify": lambda value, separator: f"{page_anchor}-{_doc_anchor(value)}",
-                },
-                "pymdownx.tabbed": {"alternate_style": True},
-                "pymdownx.tasklist": {"custom_checkbox": True},
-            },
-            output_format="html5",
-        ))
-        return _sanitize_docs_html(rendered)
-    except Exception:
-        return _render_wiki_markdown(markdown_text)
-
-
-def _sanitize_docs_html(rendered_html: str) -> str:
-    """Remove active HTML from local docs before embedding in the dashboard."""
-    dangerous_blocks = (
-        "script",
-        "style",
-        "iframe",
-        "object",
-        "embed",
-        "form",
-        "textarea",
-        "select",
-    )
-    dangerous_tags = (
-        "base",
-        "button",
-        "input",
-        "link",
-        "meta",
-    )
-
-    def escape_match(match: re.Match[str]) -> str:
-        return html.escape(match.group(0))
-
-    def parse_attrs(tag_html: str) -> dict[str, str | None] | None:
-        attrs: dict[str, str | None] = {}
-        for match in re.finditer(
-            r"([a-zA-Z_:][\w:.-]*)(?:\s*=\s*(\"[^\"]*\"|'[^']*'|[^\s\"'>]+))?",
-            tag_html,
-        ):
-            name = match.group(1).lower()
-            if name == "input":
-                continue
-            if name in attrs:
-                return None
-            raw_value = match.group(2)
-            if raw_value is None:
-                attrs[name] = None
-                continue
-            value = raw_value.strip()
-            if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
-                value = value[1:-1]
-            attrs[name] = html.unescape(value)
-        return attrs
-
-    def is_safe_tabbed_input(tag_html: str) -> bool:
-        attrs = parse_attrs(tag_html)
-        if attrs is None:
-            return False
-        if set(attrs) - {"checked", "id", "name", "type"}:
-            return False
-        input_type = (attrs.get("type") or "").lower()
-        input_id = attrs.get("id") or ""
-        input_name = attrs.get("name") or ""
-        if input_type != "radio":
-            return False
-        if not re.fullmatch(r"__tabbed_\d+_\d+", input_id):
-            return False
-        if not re.fullmatch(r"__tabbed_\d+", input_name):
-            return False
-        if not input_id.startswith(f"{input_name}_"):
-            return False
-        checked = attrs.get("checked")
-        return checked is None or checked.lower() == "checked"
-
-    def escape_input_unless_safe(match: re.Match[str]) -> str:
-        tag_html = match.group(0)
-        if is_safe_tabbed_input(tag_html):
-            return tag_html
-        return html.escape(tag_html)
-
-    for tag in dangerous_blocks:
-        rendered_html = re.sub(
-            rf"<\s*{tag}\b[^>]*>.*?<\s*/\s*{tag}\s*>",
-            escape_match,
-            rendered_html,
-            flags=re.IGNORECASE | re.DOTALL,
-        )
-        rendered_html = re.sub(
-            rf"<\s*/?\s*{tag}\b[^>]*>",
-            escape_match,
-            rendered_html,
-            flags=re.IGNORECASE,
-        )
-    for tag in dangerous_tags:
-        if tag == "input":
-            rendered_html = re.sub(
-                rf"<\s*/?\s*{tag}\b[^>]*>",
-                escape_input_unless_safe,
-                rendered_html,
-                flags=re.IGNORECASE,
-            )
-            continue
-        rendered_html = re.sub(
-            rf"<\s*/?\s*{tag}\b[^>]*>",
-            escape_match,
-            rendered_html,
-            flags=re.IGNORECASE,
-        )
-
-    rendered_html = re.sub(
-        r"\s+on[a-zA-Z0-9_-]+\s*=\s*(\"[^\"]*\"|'[^']*'|[^\s>]+)",
-        "",
-        rendered_html,
-        flags=re.IGNORECASE,
-    )
-    rendered_html = re.sub(
-        r"\s+(href|src)\s*=\s*([\"'])\s*(javascript:|data:text/html)",
-        r" \1=\2#",
-        rendered_html,
-        flags=re.IGNORECASE,
-    )
-    return rendered_html
-
-
-def _docs_search_text(entry: dict[str, str]) -> str:
-    text = f"{entry['title']} {entry['path']} {entry['summary']} {entry['body']}"
-    text = re.sub(r"```.*?```", " ", text, flags=re.DOTALL)
-    text = re.sub(r"!!!\s+\w+(?:\s+\"[^\"]+\")?", " ", text)
-    text = re.sub(r"<[^>]+>", " ", text)
-    text = re.sub(r"[*_`#>\[\]().!:-]+", " ", text)
-    return re.sub(r"\s+", " ", text).strip().lower()
-
-
-def _render_docs_sidebar_page(
-    entry: dict[str, str],
-    tab_slug: str,
-    page_anchors: dict[str, tuple[str, str]],
-) -> str:
-    page_anchor = page_anchors.get(entry["path"], (tab_slug, _docs_page_anchor(tab_slug, entry["path"])))[1]
-    title = str(entry.get("nav_title") or entry["title"])
-    page_search = _docs_search_text(entry)
-    heading_links = "".join(
-        "<a class='docs-heading-link "
-        f"docs-heading-level-{int(heading['level'])}' "
-        f"href='#{html.escape(str(heading['id']))}' "
-        f"data-doc-link data-doc-tab='{html.escape(tab_slug)}' "
-        f"data-doc-target='{html.escape(str(heading['id']))}' "
-        f"data-doc-search='{html.escape(str(heading['title']).lower())}' "
-        f"data-doc-label='{html.escape(title)} / {html.escape(str(heading['title']))}'>"
-        f"{html.escape(str(heading['title']))}</a>"
-        for heading in _docs_heading_items(entry["body"], page_anchor)
-    )
-    headings = f"<div class='docs-heading-list'>{heading_links}</div>" if heading_links else ""
-    return (
-        "<div class='docs-toc-page'>"
-        f"<a class='docs-page-link' href='#{html.escape(page_anchor)}' "
-        f"data-doc-link data-doc-tab='{html.escape(tab_slug)}' "
-        f"data-doc-target='{html.escape(page_anchor)}' "
-        f"data-doc-search='{html.escape(page_search)}' "
-        f"data-doc-label='{html.escape(title)}'>{html.escape(title)}</a>"
-        f"{headings}"
-        "</div>"
-    )
-
-
-def _render_docs_page(
-    entry: dict[str, str],
-    tab_slug: str,
-    page_anchors: dict[str, tuple[str, str]],
-) -> str:
-    page_anchor = page_anchors.get(entry["path"], (tab_slug, _docs_page_anchor(tab_slug, entry["path"])))[1]
-    source_url = f"https://github.com/stevesolun/ctx/blob/main/{quote(entry['path'])}"
-    body_html = _render_docs_markdown(entry["body"], page_anchor)
-    body_html = _rewrite_docs_links(body_html, entry["path"], tab_slug, page_anchor, page_anchors)
-    return (
-        f"<article id='{html.escape(page_anchor)}' class='docs-page wiki-body' "
-        f"data-doc-page='{html.escape(_docs_search_text(entry))}'>"
-        "<div class='docs-page-source'>"
-        f"<code>{html.escape(entry['path'])}</code>"
-        f"<a href='{html.escape(source_url)}'>source -></a>"
-        "</div>"
-        f"{body_html}"
-        "</article>"
+    return dashboard_docs.render_docs_markdown(
+        markdown_text,
+        page_anchor,
+        fallback_renderer=_render_wiki_markdown,
     )
 
 
 def _render_docs() -> str:
-    cache_key = _docs_render_cache_key()
-    global _DOCS_RENDER_CACHE_KEY, _DOCS_RENDER_CACHE_VALUE
-    if _DOCS_RENDER_CACHE_KEY == cache_key and _DOCS_RENDER_CACHE_VALUE is not None:
-        return _DOCS_RENDER_CACHE_VALUE
-    cache_token = _docs_render_cache_token(cache_key)
-    cached = _read_docs_render_disk_cache(cache_token)
-    if cached is not None:
-        _DOCS_RENDER_CACHE_KEY = cache_key
-        _DOCS_RENDER_CACHE_VALUE = cached
-        return cached
-
-    entries = _docs_index_entries()
-    public_docs_url = "https://stevesolun.github.io/ctx/"
-    tabs = _docs_tabs(entries)
-    if not tabs:
-        body = (
-            "<h1>Docs</h1>"
-            "<div class='card'><strong>No local docs found.</strong>"
-            f"<p class='muted'>Open the public docs at "
-            f"<a href='{public_docs_url}'>{public_docs_url}</a>.</p></div>"
-        )
-        html_out = _layout("Docs", body)
-        _write_docs_render_disk_cache(cache_token, html_out)
-        _DOCS_RENDER_CACHE_KEY = cache_key
-        _DOCS_RENDER_CACHE_VALUE = html_out
-        return html_out
-
-    tab_buttons = "".join(
-        f"<button class='docs-tab-button{' active' if idx == 0 else ''}' "
-        f"type='button' data-doc-tab='{html.escape(str(tab['slug']))}'>"
-        f"{html.escape(str(tab['label']))}</button>"
-        for idx, tab in enumerate(tabs)
-    )
-    panels: list[str] = []
-    page_count = sum(len(list(tab["pages"])) for tab in tabs)
-    page_anchors: dict[str, tuple[str, str]] = {}
-    for tab in tabs:
-        tab_slug = str(tab["slug"])
-        for page in list(tab["pages"]):
-            page_anchors[str(page["path"])] = (tab_slug, _docs_page_anchor(tab_slug, str(page["path"])))
-    for idx, tab in enumerate(tabs):
-        tab_slug = str(tab["slug"])
-        pages = list(tab["pages"])
-        page_links = "".join(
-            _render_docs_sidebar_page(page, tab_slug, page_anchors)
-            for page in pages
-        )
-        page_bodies = "".join(_render_docs_page(page, tab_slug, page_anchors) for page in pages)
-        hidden = " hidden" if idx else ""
-        panels.append(
-            f"<section class='docs-tab-panel' data-doc-panel='{html.escape(tab_slug)}'{hidden}>"
-            "<div class='docs-reader'>"
-            f"<aside class='docs-page-list'>{page_links}</aside>"
-            f"<div>{page_bodies}</div>"
-            "</div>"
-            "</section>"
-        )
-
-    body = (
-        "<div class='docs-shell'>"
-        "<section class='docs-hero'>"
-        "<div class='docs-hero-grid'>"
-        "<div>"
-        "<div class='docs-eyebrow'>Repo documentation</div>"
-        "<h1>Docs</h1>"
-        "<p>Read the same Markdown tree and MkDocs nav shipped with the repo. "
-        "Use tabs for sections, search across local docs, and jump to source when you need the exact file.</p>"
-        "</div>"
-        "<div class='docs-hero-meta'>"
-        f"<span class='docs-stat'>{len(tabs)} sections</span>"
-        f"<span class='docs-stat'>{page_count} pages</span>"
-        "</div>"
-        "</div>"
-        "<div class='docs-actions'>"
-        "<div class='docs-search-wrap'>"
-        "<input id='docs-search' type='text' placeholder='Search local docs...'>"
-        "</div>"
-        f"<a class='docs-public-link' href='{public_docs_url}'>public docs -></a>"
-        "</div>"
-        "<div id='docs-search-results' class='docs-search-results' hidden></div>"
-        "</section>"
-        f"<div class='docs-tabs' role='tablist'>{tab_buttons}</div>"
-        + "".join(panels)
-        + _monitor_inline_script("monitor-docs.js")
-        + "</div>"
+    return dashboard_docs.render_docs(
+        roots=_docs_roots(),
+        layout=_layout,
+        asset_text=_monitor_asset_text,
+        inline_script=_monitor_inline_script,
+        cache_path=_docs_render_disk_cache_path(),
+        fallback_markdown=_render_wiki_markdown,
+        cache_salt_paths=(Path(__file__),),
+        cache_extra=(id(_docs_index_entries), id(_docs_tabs)),
+        index_entries=_docs_index_entries,
+        tabs_for_entries=_docs_tabs,
+        render_markdown_func=_render_docs_markdown,
     )
-    html_out = _layout("Docs", body)
-    _write_docs_render_disk_cache(cache_token, html_out)
-    _DOCS_RENDER_CACHE_KEY = cache_key
-    _DOCS_RENDER_CACHE_VALUE = html_out
-    return html_out
 
 
 def _render_manage(mutations_enabled: bool | None = None) -> str:
@@ -6093,10 +5320,6 @@ def _kpi_summary_cache_key(sidecar_dir: Path) -> tuple[Any, ...]:
     return tuple(parts)
 
 
-def _kpi_summary_cache_token(cache_key: tuple[Any, ...]) -> str:
-    return json.dumps(cache_key, separators=(",", ":"), sort_keys=True)
-
-
 def _kpi_summary_disk_cache_path(sidecar_dir: Path) -> Path:
     return sidecar_dir / ".dashboard-kpi-summary.json"
 
@@ -6136,15 +5359,8 @@ def _read_kpi_summary_disk_cache(
     cache_token: str,
     summary_cls: Any,
 ) -> Any | None:
-    try:
-        data = json.loads(
-            _kpi_summary_disk_cache_path(sidecar_dir).read_text(encoding="utf-8")
-        )
-    except (OSError, json.JSONDecodeError):
-        return None
-    if not isinstance(data, dict):
-        return None
-    if data.get("schema_version") != 1 or data.get("cache_token") != cache_token:
+    data = _read_disk_cache_payload(_kpi_summary_disk_cache_path(sidecar_dir), cache_token)
+    if data is None:
         return None
     return _dashboard_summary_from_dict(summary_cls, data.get("summary"))
 
@@ -6154,19 +5370,12 @@ def _write_kpi_summary_disk_cache(
     cache_token: str,
     summary: Any,
 ) -> None:
-    try:
-        payload = {
-            "schema_version": 1,
-            "cache_token": cache_token,
-            "summary": summary.to_dict(),
-        }
-        _atomic_write_text(
-            _kpi_summary_disk_cache_path(sidecar_dir),
-            json.dumps(payload, ensure_ascii=False, sort_keys=True) + "\n",
-            encoding="utf-8",
-        )
-    except (OSError, TypeError, ValueError):
-        return
+    _write_disk_cache_payload(
+        _kpi_summary_disk_cache_path(sidecar_dir),
+        cache_token,
+        {"summary": summary.to_dict()},
+        sort_keys=True,
+    )
 
 
 def _kpi_summary():
@@ -6193,7 +5402,7 @@ def _kpi_summary():
         and time.monotonic() - _KPI_SUMMARY_CACHE_AT < _KPI_SUMMARY_CACHE_SECONDS
     ):
         return _KPI_SUMMARY_CACHE_VALUE
-    cache_token = _kpi_summary_cache_token(cache_key)
+    cache_token = _disk_cache_token(cache_key)
     summary = _read_kpi_summary_disk_cache(sidecar_dir, cache_token, DashboardSummary)
     if summary is not None:
         _KPI_SUMMARY_CACHE_KEY = cache_key
@@ -6799,119 +6008,21 @@ def _perform_load(
     command: str | None = None,
     json_config: str | None = None,
 ) -> tuple[bool, str]:
-    """Install/load one entity from the wiki. Returns (ok, message)."""
-    if not _is_safe_slug(slug):
-        return False, f"invalid slug: {slug!r}"
-    normalized_entity_type = _normalize_dashboard_entity_type(entity_type)
-    if normalized_entity_type is None:
-        return False, f"unsupported entity_type: {entity_type!r}"
-    entity_type = normalized_entity_type
-    if entity_type == "harness":
-        return (
-            False,
-            "harness installs are managed by ctx-harness-install; "
-            f"run: ctx-harness-install {slug} --dry-run",
-        )
-    result: Any
-    try:
-        if entity_type == "agent":
-            from ctx.adapters.claude_code.install.agent_install import install_agent
-            result = install_agent(
-                slug,
-                wiki_dir=_wiki_dir(),
-                agents_dir=_claude_dir() / "agents",
-            )
-        elif entity_type == "mcp-server":
-            from ctx.adapters.claude_code.install.mcp_install import install_mcp
-            result = install_mcp(
-                slug,
-                wiki_dir=_wiki_dir(),
-                command=command,
-                json_config=json_config,
-                auto=True,
-            )
-        else:
-            from ctx.adapters.claude_code.install.skill_install import install_skill
-            result = install_skill(
-                slug,
-                wiki_dir=_wiki_dir(),
-                skills_dir=_claude_dir() / "skills",
-                security_scan=True,
-            )
-    except ImportError as exc:
-        return False, f"install import failed: {exc}"
-    except Exception as exc:  # noqa: BLE001
-        return False, f"{type(exc).__name__}: {exc}"
-    if result.status not in ("installed", "skipped-existing"):
-        return False, f"load failed: {result.message or result.status}"
-    _log_dashboard_entity_event(entity_type, "loaded", slug)
-    message = result.message or f"loaded {entity_type}:{slug}"
-    scan = getattr(result, "security_scan", None)
-    scan_output = str(getattr(scan, "output", "") or "").strip()
-    if scan_output:
-        message = f"{message}\n\nSkillSpector report:\n{scan_output}"
-    return True, message
+    return dashboard_entities.perform_load(
+        slug,
+        entity_type,
+        command=command,
+        json_config=json_config,
+        deps=_entity_runtime_deps(),
+    )
 
 
 def _perform_unload(slug: str, entity_type: str = "skill") -> tuple[bool, str]:
-    """Unload the given entity.
-
-    Routes by ``entity_type``:
-      - ``skill`` / ``agent``: ``skill_unload.unload_from_session`` —
-        file-copy + manifest update, reversible via /api/load.
-      - ``mcp-server``: ``mcp_install.uninstall_mcp`` — wraps
-        ``claude mcp remove`` subprocess. Requires the claude CLI on
-        PATH; errors surface to the caller.
-    """
-    if not _is_safe_slug(slug):
-        return False, f"invalid slug: {slug!r}"
-    normalized_entity_type = _normalize_dashboard_entity_type(entity_type)
-    if normalized_entity_type is None:
-        return False, f"unsupported entity_type: {entity_type!r}"
-    entity_type = normalized_entity_type
-    if entity_type == "harness":
-        return (
-            False,
-            "harness installs are managed by ctx-harness-install; "
-            f"run: ctx-harness-install {slug} --uninstall --dry-run",
-        )
-    if entity_type == "mcp-server":
-        try:
-            from ctx.adapters.claude_code.install.mcp_install import uninstall_mcp
-        except ImportError as exc:
-            return False, f"mcp_install import failed: {exc}"
-        try:
-            result = uninstall_mcp(slug, wiki_dir=_wiki_dir())
-        except Exception as exc:  # noqa: BLE001
-            return False, f"{type(exc).__name__}: {exc}"
-        if result.status not in ("uninstalled",):
-            return False, f"uninstall failed: {result.message or result.status}"
-        _log_dashboard_entity_event("mcp-server", "unloaded", slug)
-        return True, f"unloaded mcp:{slug}"
-
-    if entity_type == "agent":
-        try:
-            removed_entries = _remove_loaded_manifest_entry(slug, "agent")
-        except Exception as exc:  # noqa: BLE001
-            return False, f"{type(exc).__name__}: {exc}"
-        if not removed_entries:
-            return False, f"{slug} was not in the loaded set"
-        _log_dashboard_entity_event("agent", "unloaded", slug)
-        return True, f"unloaded {slug}"
-
-    # Skills keep using the existing skill_unload module so skill-events.jsonl
-    # remains compatible with older usage and retention analytics.
-    try:
-        from ctx.adapters.claude_code.install.skill_unload import unload_from_session
-    except ImportError as exc:
-        return False, f"skill_unload import failed: {exc}"
-    try:
-        removed = unload_from_session([slug], entity_type=entity_type)
-    except Exception as exc:  # noqa: BLE001
-        return False, f"{type(exc).__name__}: {exc}"
-    if not removed:
-        return False, f"{slug} was not in the loaded set"
-    return True, f"unloaded {', '.join(removed)}"
+    return dashboard_entities.perform_unload(
+        slug,
+        entity_type,
+        deps=_entity_runtime_deps(),
+    )
 
 
 # ─── HTTP handler ────────────────────────────────────────────────────────────

src/harness_install.py

@@ -27,6 +27,7 @@ from urllib.request import url2pathname
 from ctx.core.entity_types import entity_page_path
 from ctx.core.wiki.wiki_utils import parse_frontmatter_and_body, validate_skill_name
 from ctx.utils._fs_utils import atomic_write_json, atomic_write_text, reject_symlink_path
+from ctx.utils._secret_scan import redact_secret_text
 from ctx_config import cfg
 
 _COMMAND_ENV_ALLOWLIST = {
@@ -435,7 +436,7 @@ def _command_env() -> dict[str, str]:
 
 
 def _redact_output(text: str) -> str:
-    redacted = text or ""
+    redacted = redact_secret_text(text or "")
     for key, value in os.environ.items():
         if not value or len(value) < 8:
             continue

src/tests/test_ctx_monitor.py

@@ -19,6 +19,8 @@ import pytest
 
 import ctx_monitor as cm
 import ctx_init as ci
+from ctx import dashboard_entities
+from ctx import dashboard_docs
 from ctx.core.wiki import wiki_queue
 
 
@@ -38,8 +40,7 @@ def fake_claude(tmp_path: Path, monkeypatch) -> Path:
     monkeypatch.setattr(cm, "_KPI_SUMMARY_CACHE_AT", 0.0)
     monkeypatch.setattr(cm, "_WIKI_RENDER_CACHE_KEY", None)
     monkeypatch.setattr(cm, "_WIKI_RENDER_CACHE_VALUE", None)
-    monkeypatch.setattr(cm, "_DOCS_RENDER_CACHE_KEY", None)
-    monkeypatch.setattr(cm, "_DOCS_RENDER_CACHE_VALUE", None)
+    dashboard_docs.reset_docs_render_cache()
     return claude
 
 
@@ -690,6 +691,11 @@ def test_perform_load_rejects_invalid_slug() -> None:
     ok, msg = cm._perform_load("../etc/passwd")
     assert ok is False
     assert "invalid slug" in msg
+    helper_ok, helper_msg = dashboard_entities.perform_load(
+        "../etc/passwd",
+        deps=cm._entity_runtime_deps(),
+    )
+    assert (helper_ok, helper_msg) == (ok, msg)
 
 
 def test_perform_load_runs_skill_security_scan_and_surfaces_output(
@@ -1541,6 +1547,8 @@ def test_render_graph_uses_builtin_3d_mount(monkeypatch: pytest.MonkeyPatch) ->
     assert "button id=\"graph-zoom-in\"" in html_out
     assert "button id=\"graph-zoom-out\"" in html_out
     assert "data-testid=\"graph-edge-detail\"" in html_out
+    assert "id='graph-explanation'" in html_out
+    assert "g.explanations" in html_out
     assert "Graph renderer unavailable" not in html_out
     assert "Enter a slug to render the graph" in html_out
     # Initial slug must be embedded as JSON literal so the JS picks it up.
@@ -1814,6 +1822,29 @@ def test_graph_neighborhood_uses_dashboard_index_without_full_graph_load(
         "skill:fastapi-pro",
     ]
     assert result["edges"][0]["data"]["shared_tags"] == ["python"]
+    assert result["schema"] == {
+        "name": "ctx.dashboard.graph.neighborhood",
+        "version": 1,
+    }
+    assert result["layout"] == {
+        "kind": "radial-3d",
+        "node_size_field": "node_size",
+        "node_size_min": 8.0,
+        "node_size_max": 24.0,
+        "edge_weight_field": "weight",
+    }
+    assert result["insights"] == {
+        "source": "dashboard-index",
+        "node_count": 2,
+        "edge_count": 1,
+        "by_type": {"skill": 2, "agent": 0, "mcp-server": 0, "harness": 0},
+        "max_degree": 10,
+        "center_degree": 10,
+    }
+    assert "cached dashboard index" in result["explanations"]["source"]
+    assert "exact or normalized slug" in result["explanations"]["search"]
+    assert "quality, usage, and graph degree" in result["explanations"]["layout"]
+    assert "shared_tags" in result["explanations"]["edges"]
     assert cm._graph_stats() == {"nodes": 2, "edges": 1, "available": True}
     assert cm._wiki_stats() == {
         "skills": 2,
@@ -3238,6 +3269,7 @@ def test_entity_delete_unloads_live_entity_before_removing_page(
     fake_claude: Path,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
+    assert dashboard_entities.normalize_entity_tags(["Code Review"]) == ["code-review"]
     skill_dir = fake_claude / "skill-wiki" / "entities" / "skills"
     skill_dir.mkdir(parents=True)
     entity_path = skill_dir / "python-patterns.md"
@@ -3500,8 +3532,7 @@ def test_layout_nav_includes_wiki_and_kpi() -> None:
 
 
 def _use_temp_docs_cache(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setattr(cm, "_DOCS_RENDER_CACHE_KEY", None)
-    monkeypatch.setattr(cm, "_DOCS_RENDER_CACHE_VALUE", None)
+    dashboard_docs.reset_docs_render_cache()
     monkeypatch.setattr(
         cm,
         "_docs_render_disk_cache_path",
@@ -3674,8 +3705,7 @@ def test_render_docs_reuses_disk_cache_after_process_cache_reset(
     first = cm._render_docs()
     assert (tmp_path / ".ctx-monitor-docs-cache.json").is_file()
 
-    monkeypatch.setattr(cm, "_DOCS_RENDER_CACHE_KEY", None)
-    monkeypatch.setattr(cm, "_DOCS_RENDER_CACHE_VALUE", None)
+    dashboard_docs.reset_docs_render_cache()
 
     def fail_render_markdown(*args: object, **kwargs: object) -> str:
         raise AssertionError("fresh process should read the rendered docs cache")
@@ -3694,7 +3724,11 @@ def test_render_docs_markdown_preserves_mkdocs_tab_controls() -> None:
         "    Second body\n"
     )
 
-    html_out = cm._render_docs_markdown(markdown_text, "doc-home")
+    html_out = dashboard_docs.render_docs_markdown(
+        markdown_text,
+        "doc-home",
+        fallback_renderer=cm._render_wiki_markdown,
+    )
 
     assert "<input" not in html_out
     assert 'type="radio"' in html_out

src/tests/test_ctx_monitor_3type.py

@@ -31,6 +31,7 @@ import pytest
 sys.path.insert(0, str(Path(__file__).parents[1]))
 
 import ctx_monitor as _cm
+from ctx.core import entity_types as _entity_types
 
 
 # ────────────────────────────────────────────────────────────────────
@@ -161,6 +162,8 @@ class TestWikiIndexEntries:
         assert slugs == {"anthropic-python-sdk", "atlassian-cloud", "pulsemcp-meta"}
 
     def test_wiki_entity_path_resolves_sharded_mcp_pages(self, wiki_3type):
+        assert _entity_types.normalize_entity_type("mcp") == "mcp-server"
+        assert _cm._DASHBOARD_ENTITY_SOURCES == _entity_types.entity_source_specs()
         path = _cm._wiki_entity_path("anthropic-python-sdk")
         assert path == (
             wiki_3type / "entities" / "mcp-servers" / "a" / "anthropic-python-sdk.md"

src/tests/test_security_hardening.py

@@ -5,6 +5,7 @@ Security-hardening tests covering:
 2. Cross-process advisory file-lock behavior.
 3. YAML validate-path misroute (toolbox.validate now reads the given file,
    not .toolbox.yaml in its parent directory).
+4. Dashboard/install regressions for active HTML and secret persistence.
 
 Each test targets a specific fix from the Phase 4b-6 code-review pass.
 """
@@ -15,7 +16,9 @@ import json
 import sys
 import threading
 import time
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 import pytest
 
@@ -24,8 +27,13 @@ if str(SRC) not in sys.path:
     sys.path.insert(0, str(SRC))
 
 import council_runner as cr  # noqa: E402
+import ctx_monitor as cm  # noqa: E402
+import harness_install  # noqa: E402
 import toolbox as tb  # noqa: E402
 import toolbox_verdict as tv  # noqa: E402
+from ctx import dashboard_docs  # noqa: E402
+from ctx.adapters.claude_code.install import install_utils  # noqa: E402
+from ctx.adapters.claude_code.install import mcp_install  # noqa: E402
 from ctx.utils._file_lock import file_lock  # noqa: E402
 
 
@@ -146,3 +154,115 @@ def test_validate_reads_supplied_yaml_file(tmp_path, capsys, monkeypatch):
     out = capsys.readouterr().out
     assert rc == 0
     assert "1 toolbox(es)" in out
+
+
+# ── dashboard/install hardening ─────────────────────────────────────────────
+
+def _write_mcp_entity(wiki_dir: Path, slug: str, frontmatter: dict[str, str]) -> Path:
+    shard = slug[0] if slug and slug[0].isalpha() else "0-9"
+    path = wiki_dir / "entities" / "mcp-servers" / shard / f"{slug}.md"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = ["---"]
+    lines.extend(f"{key}: {value}" for key, value in frontmatter.items())
+    lines.extend(["---", "", "# MCP"])
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return path
+
+
+def test_docs_sanitizer_rewrites_unquoted_active_urls() -> None:
+    cleaned = dashboard_docs.sanitize_docs_html(
+        '<a href=javascript:alert(1)>bad</a>'
+        '<img src=data:text/html,<svg/onload=alert(1)>>'
+    )
+
+    assert "javascript:" not in cleaned.lower()
+    assert "data:text/html" not in cleaned.lower()
+
+
+def test_dashboard_skill_load_requires_security_scan(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from ctx.adapters.claude_code.install import skill_install
+
+    calls: list[dict[str, object]] = []
+
+    class Result:
+        status = "installed"
+        message = "installed"
+        security_scan = None
+
+    def fake_install_skill(*_args: object, **kwargs: object) -> Result:
+        calls.append(kwargs)
+        return Result()
+
+    monkeypatch.setattr(cm, "_wiki_dir", lambda: tmp_path / "wiki")
+    monkeypatch.setattr(cm, "_claude_dir", lambda: tmp_path / ".claude")
+    monkeypatch.setattr(skill_install, "install_skill", fake_install_skill)
+
+    ok, _msg = cm._perform_load("python-patterns", entity_type="skill")
+
+    assert ok is True
+    assert calls
+    assert calls[0]["security_scan"] is True
+    assert calls[0]["security_scan_required"] is True
+
+
+def test_mcp_skip_path_does_not_persist_inline_secret_command(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    wiki = tmp_path / "wiki"
+    manifest = tmp_path / "skill-manifest.json"
+    monkeypatch.setattr(install_utils, "MANIFEST_PATH", manifest)
+    _write_mcp_entity(
+        wiki,
+        "gh",
+        {
+            "status": "installed",
+            "install_cmd": "npx -y pkg GITHUB_TOKEN=ghp_supersecret1234567890",
+        },
+    )
+
+    result = mcp_install.install_mcp("gh", wiki_dir=wiki, auto=True)
+
+    assert result.status == "skipped-existing"
+    manifest_data = json.loads(manifest.read_text(encoding="utf-8"))
+    assert manifest_data["load"] == [
+        {
+            "skill": "gh",
+            "entity_type": "mcp-server",
+            "source": "ctx-mcp-install",
+        }
+    ]
+
+
+@dataclass
+class _FakeRun:
+    returncode: int = 0
+    stdout: str = ""
+    stderr: str = ""
+
+
+def test_harness_run_redacts_token_shaped_output_not_present_in_parent_env(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+
+    def fake_run(_cmd: list[str], **_kwargs: Any) -> _FakeRun:
+        return _FakeRun(
+            stdout=(
+                "created OPENAI_API_KEY=sk-testsecret1234567890 "
+                "and ghp_supersecret1234567890"
+            )
+        )
+
+    monkeypatch.setattr(harness_install.subprocess, "run", fake_run)
+
+    run = harness_install._run_command("python --version", cwd=tmp_path)
+
+    assert "sk-testsecret" not in run["stdout"]
+    assert "ghp_supersecret" not in run["stdout"]
+    assert harness_install._REDACTION in run["stdout"]

src/tests/test_update_repo_stats.py

@@ -374,18 +374,13 @@ def test_patch_readme_checks_docs_and_catalog(
     docs_knowledge.write_text("| Total nodes | **10** |\n", encoding="utf-8")
     docs_catalog.write_text(
         "\n".join([
+            '<div id="ctx-catalog-grid" class="ctx-catalog-grid">',
+            "<!-- ctx-catalog:begin -->",
             '<article class="ctx-catalog-card" data-type="skill">',
             '<p class="ctx-catalog-muted">1 entities</p>',
             "</article>",
-            '<article class="ctx-catalog-card" data-type="agent">',
-            '<p class="ctx-catalog-muted">2 entities</p>',
-            "</article>",
-            '<article class="ctx-catalog-card" data-type="mcp-server">',
-            '<p class="ctx-catalog-muted">3 entities</p>',
-            "</article>",
-            '<article class="ctx-catalog-card" data-type="harness">',
-            '<p class="ctx-catalog-muted">4 entities</p>',
-            "</article>",
+            "<!-- ctx-catalog:end -->",
+            "</div>",
         ]),
         encoding="utf-8",
     )
@@ -418,6 +413,7 @@ def test_patch_readme_checks_docs_and_catalog(
     assert ">56 entities</p>" in patched
     assert ">7,890 entities</p>" in patched
     assert ">12 entities</p>" in patched
+    assert "./?type=harness&q=tool+access" in patched
 
 
 def test_read_test_count_prefers_project_python(

src/tests/test_wiki_sync.py

@@ -31,6 +31,7 @@ from pathlib import Path
 
 import pytest
 
+from ctx.core import entity_types
 from ctx.core.wiki import wiki_sync
 # ---------------------------------------------------------------------------
 # Helpers
@@ -587,6 +588,8 @@ class TestUpsertSkillPage:
 
 class TestEntityIndexLink:
     def test_skills_flat_path(self) -> None:
+        assert wiki_sync._SUBJECT_TYPE_FOR_ENTITY_TYPE is entity_types.SUBJECT_TYPE_FOR_ENTITY_TYPE
+        assert wiki_sync._INDEX_SECTION_FOR_SUBJECT is entity_types.INDEX_SECTION_FOR_SUBJECT
         result = wiki_sync._entity_index_link("skills", "my-skill")
         assert result == "entities/skills/my-skill"
 

src/toolbox.py

@@ -151,22 +151,6 @@ def cmd_show(args: argparse.Namespace) -> int:
     return 0
 
 
-def _seed_if_empty() -> ToolboxSet:
-    tset = load_global()
-    if tset.toolboxes:
-        return tset
-    starters = ["ship-it", "security-sweep", "refactor-safety",
-                "docs-review", "fresh-repo-init"]
-    for name in starters:
-        try:
-            raw = _load_template(name)
-        except FileNotFoundError as exc:
-            _print_err(f"[warn] {exc}")
-            continue
-        tset = tset.with_toolbox(Toolbox.from_dict(name, raw))
-    return tset
-
-
 def cmd_init(args: argparse.Namespace) -> int:
     tset = load_global()
     if tset.toolboxes and not args.force:

src/update_repo_stats.py

@@ -625,6 +625,79 @@ _ENTITY_COUNT_REPLACEMENTS: tuple[tuple[str, str, str, str], ...] = (
     ("mcps", "MCPs", "mcp-server", r"badge/MCPs-[0-9,%]+-"),
     ("harnesses", "Harnesses", "harness", r"badge/Harnesses-[0-9,%]+-"),
 )
+_CATALOG_BEGIN = "<!-- ctx-catalog:begin -->"
+_CATALOG_END = "<!-- ctx-catalog:end -->"
+_CATALOG_FILTER_CARDS: tuple[tuple[str, str, str, str, str], ...] = (
+    ("skill", "Skills", "Code review skills", "code review review pr diff quality bug tests", "code+review"),
+    ("skill", "Skills", "Testing skills", "testing pytest unit browser smoke regression", "testing"),
+    ("skill", "Skills", "Frontend skills", "frontend ui dashboard css react browser", "frontend"),
+    ("agent", "Agents", "Architecture agents", "architecture design refactor planning", "architecture"),
+    ("agent", "Agents", "Security agents", "security audit supply chain secrets", "security"),
+    ("mcp-server", "MCPs", "GitHub MCPs", "github repo issues pull requests graphql", "github"),
+    ("mcp-server", "MCPs", "Cloud MCPs", "cloud google cloud aws azure deploy", "cloud"),
+    ("mcp-server", "MCPs", "Browser MCPs", "browser automation web scraping", "browser"),
+    ("harness", "Harnesses", "Local/API model harnesses", "local api openai ollama vllm model harness", "local+model"),
+    ("harness", "Harnesses", "Verification harnesses", "harness test eval guardrail validate verification", "verification"),
+    ("harness", "Harnesses", "Tool-access harnesses", "harness tools sandbox filesystem cloud tool access", "tool+access"),
+)
+
+
+def _catalog_card(
+    *,
+    entity_type: str,
+    pill: str,
+    title: str,
+    search: str,
+    query_href: str,
+    muted: str,
+) -> str:
+    return "\n".join([
+        f'    <article class="ctx-catalog-card" data-type="{entity_type}" data-search="{search}">',
+        f"      <span class=\"ctx-catalog-pill\">{pill}</span>",
+        f"      <h3>{title}</h3>",
+        f"      <p class=\"ctx-catalog-muted\">{muted}</p>",
+        f"      <a class=\"md-button\" href=\"{query_href}\">Filter tiles</a>",
+        "      <a class=\"md-button\" href=\"../dashboard/#catalog-badge-links\">Open full catalog locally</a>",
+        "    </article>",
+    ])
+
+
+def render_catalog_cards(stats: Mapping[str, int | None]) -> str | None:
+    """Render the generated public catalog tile block from graph stats."""
+    required = {
+        "skills": stats.get("skills"),
+        "agents": stats.get("agents"),
+        "mcps": stats.get("mcps"),
+        "harnesses": stats.get("harnesses"),
+    }
+    if any(value is None for value in required.values()):
+        return None
+    count_cards = (
+        ("skill", "Skills", "Skills", "skill prompt workflow testing code review frontend backend security research", "skills"),
+        ("agent", "Agents", "Agents", "agent reviewer planner architect debugger security research", "agents"),
+        ("mcp-server", "MCPs", "MCP servers", "mcp server github filesystem browser database api cloud", "mcps"),
+        ("harness", "Harnesses", "Harnesses", "harness local model api model llm orchestration verification", "harnesses"),
+    )
+    cards: list[str] = []
+    for entity_type, pill, title, search, key in count_cards:
+        cards.append(_catalog_card(
+            entity_type=entity_type,
+            pill=pill,
+            title=title,
+            search=search,
+            query_href=f"./?type={entity_type}",
+            muted=f"{int(required[key] or 0):,} entities",
+        ))
+    for entity_type, pill, title, search, query in _CATALOG_FILTER_CARDS:
+        cards.append(_catalog_card(
+            entity_type=entity_type,
+            pill=pill,
+            title=title,
+            search=search,
+            query_href=f"./?type={entity_type}&q={query}",
+            muted="Filtered catalog launcher",
+        ))
+    return _CATALOG_BEGIN + "\n" + "\n".join(cards) + "\n" + _CATALOG_END
 
 
 def _append_badge_target_replacements(reps: list[Replacement]) -> None:
@@ -679,6 +752,13 @@ def _append_entity_count_replacements(
         ))
         _append_catalog_card_count(reps, entity_type=entity_type, count=count)
 
+    catalog_cards = render_catalog_cards(stats)
+    if catalog_cards is not None:
+        reps.append((
+            re.compile(rf"{re.escape(_CATALOG_BEGIN)}[\s\S]*?{re.escape(_CATALOG_END)}"),
+            catalog_cards,
+        ))
+
 
 def build_replacements(
     stats: Mapping[str, int | None],