data-olympus 0.3.0__py3-none-any.whl

data_olympus/audit_log.py

@@ -0,0 +1,275 @@
+"""Append-only JSONL audit log of all writes, with a tamper-evident hash chain.
+
+Each appended event carries an ``event_id``, the ``prev_hash`` of the previous
+chained event, and its own ``hash`` over the canonical event body (which includes
+``prev_hash``). Any later edit/deletion/reordering of an event breaks the chain
+and is detected by :meth:`verify`. With ``KB_AUDIT_HMAC_KEY`` set the digest is a
+keyed HMAC-SHA256, so an attacker who can write the log file still cannot forge a
+valid chain without the key. Legacy lines without a ``hash`` are tolerated: the
+chain validates the hashed lines in order and ignores unhashed ones, so enabling
+the feature on an existing log does not retroactively flag it.
+
+Rotation (WP3a). When the live file grows past ``max_bytes`` a fresh append
+rotates it: the live file is renamed to ``<stem>-<UTC-timestamp><suffix>`` and a
+new live file is started. The hash chain carries across the boundary because
+``_last_hash`` is retained in memory across the rename, so the first event of the
+new file links to the last hash of the rotated one. :meth:`verify` replays every
+rotated segment in chronological order followed by the live file, so an intact
+chain validates across rotations and any break at the boundary is caught. Reads
+(:meth:`iter_filtered`) default to the live file only (cheap, matches the pre-
+rotation behaviour) but can walk rotated segments newest-first when
+``include_rotated=True`` so a ``since``-filtered query still sees history that has
+rotated out of the live file.
+"""
+from __future__ import annotations
+
+import glob
+import hashlib
+import hmac
+import json
+import os
+import threading
+import time
+import uuid
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+GENESIS = ""
+
+
+class AuditLog:
+    def __init__(
+        self, *, log_path: str, hmac_key: str = "", max_bytes: int = 0,
+    ) -> None:
+        self._path = log_path
+        self._hmac_key = hmac_key or ""
+        # Size-based rotation threshold in bytes. 0 (the default) disables
+        # rotation entirely, so an operator who never sets KB_AUDIT_MAX_BYTES keeps
+        # the single-file behaviour and existing logs are untouched.
+        self._max_bytes = max_bytes if max_bytes and max_bytes > 0 else 0
+        # append() is a read-modify-write on _last_hash plus a file write. Once
+        # handlers are offloaded to the anyio threadpool, appends can run
+        # concurrently; without this lock two threads read the same _last_hash
+        # and produce sibling events that break the hash chain. Reads (verify /
+        # iter_filtered) take the same lock so they never observe a torn append.
+        self._lock = threading.Lock()
+        self._last_hash = self._load_last_hash()
+
+    # --- hashing helpers ---------------------------------------------------
+    def _digest(self, payload: str) -> str:
+        if self._hmac_key:
+            return hmac.new(
+                self._hmac_key.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256
+            ).hexdigest()
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def _canonical(event: dict[str, Any]) -> str:
+        """Deterministic serialization of the event body excluding its own hash."""
+        body = {k: v for k, v in event.items() if k != "hash"}
+        return json.dumps(body, sort_keys=True, ensure_ascii=False)
+
+    def _load_last_hash(self) -> str:
+        """The last chained hash across ALL segments (rotated + live).
+
+        Reads rotated segments in chronological order then the live file so a
+        process that restarts after a rotation still chains its first append to
+        the true tail of the chain rather than to the (now-rotated-out) live
+        file's older content.
+        """
+        last = GENESIS
+        for path in [*self._rotated_paths(), self._path]:
+            if not os.path.exists(path):
+                continue
+            with open(path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        ev = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    if isinstance(ev, dict) and ev.get("hash"):
+                        last = ev["hash"]
+        return last
+
+    # --- rotation helpers --------------------------------------------------
+    def _rotated_paths(self) -> list[str]:
+        """Rotated segment paths, oldest-first.
+
+        Rotated files are named ``<stem>-<UTC-timestamp><suffix>`` next to the
+        live file. Sorting the glob lexically orders them chronologically because
+        the timestamp is fixed-width ``YYYYmmddTHHMMSSffffff``. The live file
+        itself is excluded (its name has no timestamp segment)."""
+        stem, suffix = os.path.splitext(self._path)
+        pattern = f"{glob.escape(stem)}-*{suffix}"
+        return sorted(p for p in glob.glob(pattern) if p != self._path)
+
+    def _rotated_path_for(self, when: float) -> str:
+        stem, suffix = os.path.splitext(self._path)
+        ts = time.strftime("%Y%m%dT%H%M%S", time.gmtime(when))
+        micros = int((when % 1) * 1_000_000)
+        candidate = f"{stem}-{ts}{micros:06d}{suffix}"
+        # Extremely unlikely, but never clobber an existing rotated segment.
+        n = 1
+        while os.path.exists(candidate):
+            candidate = f"{stem}-{ts}{micros:06d}-{n}{suffix}"
+            n += 1
+        return candidate
+
+    def _maybe_rotate_locked(self) -> None:
+        """Rotate the live file when it exceeds the size threshold. Caller holds
+        the lock. The in-memory ``_last_hash`` is deliberately NOT reset, so the
+        first event written to the fresh live file links to the last hash of the
+        rotated segment and the chain is continuous across the boundary."""
+        if self._max_bytes <= 0 or not os.path.exists(self._path):
+            return
+        try:
+            size = os.path.getsize(self._path)
+        except OSError:  # pragma: no cover - defensive
+            return
+        if size < self._max_bytes:
+            return
+        os.rename(self._path, self._rotated_path_for(time.time()))
+
+    # --- public API --------------------------------------------------------
+    def append(self, event: dict[str, Any]) -> None:
+        """Append a single JSON object as one line, chained to the previous event.
+
+        The parent directory is created lazily on first append so that
+        constructing an AuditLog with an unwritable default path (e.g. macOS
+        tests that never trigger a write) does not crash startup. When rotation
+        is enabled and the live file has passed the size threshold, it is rotated
+        BEFORE this event is written so the new event starts the fresh segment.
+        """
+        os.makedirs(os.path.dirname(self._path) or ".", exist_ok=True)
+        with self._lock:
+            self._maybe_rotate_locked()
+            chained = dict(event)
+            chained["event_id"] = uuid.uuid4().hex
+            chained["prev_hash"] = self._last_hash
+            chained["hash"] = self._digest(self._canonical(chained))
+            line = json.dumps(chained, ensure_ascii=False)
+            with open(self._path, "a", encoding="utf-8") as f:
+                f.write(line + "\n")
+            self._last_hash = chained["hash"]
+
+    def verify(self) -> tuple[bool, int]:
+        """Recompute the hash chain over the whole log (all rotated segments +
+        the live file, in chronological order).
+
+        Returns ``(True, -1)`` when intact (or empty / all-legacy), else
+        ``(False, line_index)`` for the 0-based index of the first offending line
+        counted across the concatenation of all segments (rotated oldest-first,
+        then live). So a single-file log verifies exactly as before, and a
+        rotated log verifies across the boundary: the first event of a new segment
+        must carry the last hash of the previous segment as its ``prev_hash``.
+
+        Unhashed legacy lines are tolerated ONLY as a prefix before the first
+        hashed event (the pre-chaining migration window). Once the chain has
+        started, any unhashed JSON line is treated as tampering and breaks
+        verification, so an attacker cannot append a legacy-shaped record to forge
+        an event while keeping verify green.
+        """
+        # Snapshot every segment under the lock (short hold), then verify in
+        # memory so a concurrent append cannot make us read a torn final line as
+        # tampering.
+        with self._lock:
+            segments: list[list[str]] = []
+            for path in [*self._rotated_paths(), self._path]:
+                if not os.path.exists(path):
+                    continue
+                with open(path, encoding="utf-8") as f:
+                    segments.append(f.readlines())
+        prev = GENESIS
+        seen_hashed = False
+        global_index = 0
+        for raw_lines in segments:
+            for raw in raw_lines:
+                i = global_index
+                global_index += 1
+                raw = raw.strip()
+                if not raw:
+                    continue
+                try:
+                    ev = json.loads(raw)
+                except json.JSONDecodeError:
+                    return (False, i)
+                if not (isinstance(ev, dict) and ev.get("hash")):
+                    if seen_hashed:
+                        return (False, i)  # unhashed line after the chain started
+                    continue  # legacy prefix, tolerated
+                if ev.get("prev_hash") != prev:
+                    return (False, i)
+                if self._digest(self._canonical(ev)) != ev["hash"]:
+                    return (False, i)
+                prev = ev["hash"]
+                seen_hashed = True
+        return (True, -1)
+
+    def iter_filtered(
+        self,
+        *,
+        since: float | None = None,
+        agent: str | None = None,
+        status: str | None = None,
+        include_rotated: bool = False,
+        max_scan_events: int | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        """Yield events matching the filters, most-recent first.
+
+        By default only the live file is read (cheap; matches the pre-rotation
+        behaviour). When ``include_rotated`` is True the rotated segments are also
+        walked, newest-first, AFTER the live file so results stay strictly most-
+        recent-first across the rotation boundary. Callers that pass a ``since``
+        filter should set ``include_rotated=True`` to see history that has already
+        rotated out of the live file.
+
+        ``max_scan_events`` bounds the reverse scan: once that many raw events
+        have been examined (across all scanned segments) iteration stops even if
+        more match. This caps the memory/time cost of a query against a large
+        rotated history; callers that only need "the most recent N" pass their N
+        so the scan does not walk the entire archive.
+        """
+        scanned = 0
+        # Live file first (newest events live here), then rotated newest-first.
+        paths = [self._path]
+        if include_rotated:
+            paths.extend(reversed(self._rotated_paths()))
+        for path in paths:
+            if not os.path.exists(path):
+                continue
+            # Read under the lock so we never see a torn append, then yield from
+            # the in-memory snapshot (holding the lock across yields would block
+            # appends for as long as the caller iterates).
+            with self._lock, open(path, encoding="utf-8") as f:
+                lines = f.readlines()
+            for line in reversed(lines):
+                if max_scan_events is not None and scanned >= max_scan_events:
+                    return
+                line = line.strip()
+                if not line:
+                    continue
+                scanned += 1
+                try:
+                    ev = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if since is not None and float(ev.get("ts", 0)) < since:
+                    # Events are appended in time order, so within a segment a
+                    # reverse scan that reaches an older-than-``since`` event has
+                    # no newer matches left below it; and every rotated segment is
+                    # strictly older than the live file we scan first. So the first
+                    # sub-floor event ends the whole scan. (A clock that ran
+                    # backwards mid-run could in theory hide a straggler; the audit
+                    # ts is server wall-clock and this is a best-effort recency
+                    # query, so the bound is worth the rare miss.)
+                    return
+                if agent is not None and ev.get("agent_identity") != agent:
+                    continue
+                if status is not None and ev.get("status") != status:
+                    continue
+                yield ev

data_olympus/audit_trailers.py

@@ -0,0 +1,42 @@
+"""Build commit messages with 7 audit trailers."""
+from __future__ import annotations
+
+from typing import Literal
+
+
+def build_commit_message(
+    *,
+    subject: str,
+    source_session: str,
+    agent_identity: str,
+    confidence_original: float,
+    operator_confirmed: bool,
+    proposal_type: Literal["memory", "edit"],
+    target_tier: str,
+    target_path: str,
+) -> str:
+    """Return a commit message with subject + blank line + 7 trailers.
+
+    Raises ValueError if any trailer value contains a newline (which would
+    break git's trailer parsing).
+    """
+    for label, value in [
+        ("subject", subject),
+        ("source_session", source_session),
+        ("agent_identity", agent_identity),
+        ("target_tier", target_tier),
+        ("target_path", target_path),
+    ]:
+        if "\n" in value or "\r" in value:
+            raise ValueError(f"trailer value for {label!r} contains newline")
+
+    trailers = [
+        f"KB-Source-Session: {source_session}",
+        f"KB-Agent-Identity: {agent_identity}",
+        f"KB-Confidence: {confidence_original:.2f}",
+        f"KB-Operator-Confirmed: {'yes' if operator_confirmed else 'no'}",
+        f"KB-Proposal-Type: {proposal_type}",
+        f"KB-Target-Tier: {target_tier}",
+        f"KB-Target-Path: {target_path}",
+    ]
+    return subject + "\n\n" + "\n".join(trailers) + "\n"

data_olympus/auth.py

@@ -0,0 +1,139 @@
+"""Structural rule (always applies, not configurable) + policy blocklist
+(operator-configurable, empty by default).
+
+Rules:
+- Structural rule rejects: empty, NUL, absolute, traversal, non-md, non-indexed,
+  structurally-excluded. Normalization happens BEFORE prefix match.
+- Policy blocklist consists of tier names (e.g. {"T1"}) and fnmatch globs
+  (e.g. ["decisions/ADR-008-*.md"]).
+
+By default both blocklists are empty (allow-by-default modulo the structural rule).
+"""
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import PurePosixPath
+
+# Generic, deployment-neutral default. A deployment with extra top-level
+# directories supplies its own writable set via KB_INDEXED_PREFIXES (a
+# comma-separated list), which replaces this default wholesale.
+DEFAULT_INDEXED_PREFIXES: tuple[str, ...] = (
+    "universal/", "tech-stacks/", "projects/",
+    "decisions/", "workflows/", "memory/",
+    "tooling/", "templates/",
+)
+
+
+def indexed_prefixes() -> tuple[str, ...]:
+    """Active writable prefixes: KB_INDEXED_PREFIXES if set, else default."""
+    raw = os.environ.get("KB_INDEXED_PREFIXES", "").strip()
+    if not raw:
+        return DEFAULT_INDEXED_PREFIXES
+    return tuple(s.strip() for s in raw.split(",") if s.strip())
+
+STRUCTURALLY_EXCLUDED: frozenset[str] = frozenset({
+    ".git", ".worktrees", ".ruff_cache", "__pycache__",
+    "to-delete", "archive", "_archive", "tools",
+    ".pytest_cache", ".mypy_cache", "node_modules",
+})
+
+
+def normalize_target_path(raw: str) -> str | None:
+    """Return the canonical relative POSIX path, or None if structurally invalid.
+
+    The returned string is the SINGLE authoritative form of the path: backslashes
+    are folded to ``/`` and the segments are re-joined with POSIX separators.
+    Every downstream operation (classification, blocklist match, filesystem join,
+    ``git add``) MUST use this canonical value, never the raw input. If callers
+    validated with the canonical form but then joined/wrote/git-added the raw
+    string, a value like ``decisions\\x.md`` would pass validation as
+    ``decisions/x.md`` on Linux yet land a literal root-level file named
+    ``decisions\\x.md`` that is outside every indexed prefix and invisible to
+    ``KB_WRITE_BLOCK_PATHS`` globs. Returning the canonical form and using it
+    everywhere keeps the policy decision and the filesystem effect in lockstep.
+
+    Rejections: empty/whitespace-only, NUL or any other control character
+    (``\\n``, ``\\r``, ``\\t``, etc. would let a payload smuggle newlines into a
+    path), absolute paths, Windows drive letters, ``.``/``..`` traversal, and any
+    structurally-excluded segment.
+    """
+    if not raw or not raw.strip():
+        return None
+    # Reject control characters (NUL, newline, CR, tab, and the rest of the
+    # C0/C1 range) before any normalization: a newline in a path is never a
+    # legitimate target and would otherwise smuggle through classification and
+    # audit records.
+    if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in raw):
+        return None
+    if raw.startswith("/") or (len(raw) >= 2 and raw[1] == ":"):
+        return None
+    parts = raw.replace("\\", "/").split("/")
+    if any(p == "" or p == "." or p == ".." for p in parts):
+        return None
+    if any(p in STRUCTURALLY_EXCLUDED for p in parts):
+        return None
+    return str(PurePosixPath(*parts))
+
+
+# Back-compat alias for the previous private name; both point at the same guard.
+_normalize_target_path = normalize_target_path
+
+
+def is_writable_path(target_path: str) -> bool:
+    """Structural rule. Independent of policy blocklist.
+
+    Callers that go on to write MUST first resolve the canonical form with
+    :func:`normalize_target_path` and operate on that; this predicate only
+    answers whether the canonical form is a writable indexed ``.md`` path.
+    """
+    canonical = normalize_target_path(target_path)
+    if canonical is None:
+        return False
+    if not canonical.endswith(".md"):
+        return False
+    return any(canonical.startswith(p) for p in indexed_prefixes())
+
+
+def safe_join_under_root(root: str, target_path: str) -> str | None:
+    """Join ``target_path`` under ``root`` and return the absolute path only when
+    it resolves to exactly that lexical location inside ``root``; else return None.
+
+    Two checks, both required:
+
+    1. The realpath-resolved location is strictly inside ``root``. This rejects
+       traversal and symlinks that point *outside* the worktree (e.g. a malicious
+       ``memory/inbox`` symlinked to ``/etc``).
+    2. The resolved location equals the lexical join of ``root`` and
+       ``target_path``. This additionally rejects a symlink component that
+       redirects to *another in-root path*: without it, an allowed lexical
+       ``target_path`` (which is what gets classified, blocklist-checked, audited,
+       and ``git add``-ed) could land its bytes on a different file, decoupling
+       the policy decision from the filesystem effect.
+
+    The returned value is the *unresolved* join so callers keep writing to the
+    in-tree path and ``git add`` the relative ``target_path`` exactly as before.
+    This is the single shared containment guard used by every write path (memory
+    propose, edit, resolve, bootstrap).
+    """
+    root_real = os.path.realpath(root)
+    full = os.path.join(root, target_path)
+    real = os.path.realpath(full)
+    expected = os.path.normpath(os.path.join(root_real, target_path))
+    inside = real != root_real and real.startswith(root_real + os.sep)
+    if inside and real == expected:
+        return full
+    return None
+
+
+class PathBlocklist:
+    """Operator-configured per-tier + per-path blocklist. Both default empty."""
+
+    def __init__(self, tier_blocks: list[str], path_blocks: list[str]) -> None:
+        self._tier_blocks = {t.strip() for t in tier_blocks if t.strip()}
+        self._path_blocks = [p.strip() for p in path_blocks if p.strip()]
+
+    def blocks(self, target_path: str, target_tier: str) -> bool:
+        if target_tier in self._tier_blocks:
+            return True
+        return any(fnmatch.fnmatch(target_path, p) for p in self._path_blocks)

data_olympus/cli/__init__.py

@@ -0,0 +1 @@
+"""data-olympus local-bundle CLI (lint, index, visualize)."""

data_olympus/cli/import_cmd.py

@@ -0,0 +1,115 @@
+"""`data-olympus import`: migrate an existing rule corpus into a draft bundle.
+
+Wires the CLI flags to ``data_olympus.importer.run_import`` and renders the
+import report either human-readably or as JSON (``--json``). Exit codes:
+- 0: import succeeded and the output is lint-clean.
+- 1: import succeeded but the output has lint errors (should not happen on the
+     happy path; surfaces a stamping regression instead of silently passing).
+- 2: bad input or a refused re-run (ImportError_).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING
+
+from data_olympus.importer import ImportError_, run_import
+
+if TYPE_CHECKING:
+    import argparse
+
+    from data_olympus.importer.model import ImportReport
+
+
+def _render_human(report: ImportReport) -> str:
+    lines: list[str] = []
+    lines.append(f"Imported {report.kind} from {report.source}")
+    lines.append(f"  output: {report.out_dir}")
+    lines.append(f"  created {len(report.created)} draft(s):")
+    for name in report.created:
+        lines.append(f"    + {name}")
+    if report.skipped:
+        lines.append(f"  skipped {len(report.skipped)} section(s) (too short):")
+        for s in report.skipped:
+            lines.append(f"    - {s.heading}: {s.reason}")
+    if report.inferences:
+        lines.append(f"  inferences ({len(report.inferences)}):")
+        for note in report.inferences:
+            lines.append(f"    * {note}")
+    if report.needs_review:
+        lines.append(f"  needs human review ({len(report.needs_review)}):")
+        for note in report.needs_review:
+            lines.append(f"    ! {note}")
+    if report.lint:
+        lines.append(f"  lint findings ({len(report.lint)}):")
+        for f in report.lint:
+            lines.append(f"    [{f.severity}] {f.path}: {f.field}: {f.message}")
+        lines.append(f"  lint clean: {report.lint_clean}")
+    else:
+        lines.append("  lint: clean (no findings)")
+    lines.append("  next steps:")
+    for step in report.next_steps:
+        lines.append(f"    - {step}")
+    return "\n".join(lines)
+
+
+def _cmd_import(args: argparse.Namespace) -> int:
+    try:
+        report = run_import(
+            source=args.source,
+            kind=args.kind,
+            tier=args.tier,
+            out=args.out,
+            category=args.category,
+            id_prefix=args.id_prefix,
+            force=args.force,
+        )
+    except ImportError_ as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps(report.to_dict()))
+    else:
+        print(_render_human(report))
+
+    return 0 if report.lint_clean else 1
+
+
+def add_import_subparser(sub: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    """Register the ``import`` subcommand on the CLI's subparser action."""
+    p = sub.add_parser(
+        "import",
+        help="migrate an existing rule corpus (CLAUDE.md/AGENTS.md/.cursorrules/ADR/OKF) "
+        "into a governed draft bundle",
+    )
+    p.add_argument("source", help="path to the source file (flat rule file) or directory (ADR/OKF)")
+    p.add_argument(
+        "--kind",
+        required=True,
+        choices=["claude-md", "agents-md", "gemini-md", "cursorrules", "adr", "okf"],
+        help="source corpus kind",
+    )
+    p.add_argument(
+        "--tier",
+        required=True,
+        help="governance tier for the imported drafts (T1|T2|T3|T4|meta, or a bare digit)",
+    )
+    p.add_argument(
+        "-o", "--out", default=None,
+        help="output bundle directory (default: <source>/imported-<kind>). Refuses to write "
+        "into a dir that already holds governed files unless --force is given.",
+    )
+    p.add_argument("--category", default=None, help="optional category stamped on every draft")
+    p.add_argument(
+        "--id-prefix", default=None,
+        help="id prefix for generated ids (default: per-kind, e.g. CLAUDE/AGENTS/OKF; "
+        "ADR imports always use ADR-NNNN)",
+    )
+    p.add_argument(
+        "--force", action="store_true",
+        help="overwrite an output dir that was already used as an import target",
+    )
+    p.add_argument("--json", action="store_true", help="emit the import report as JSON")
+    p.set_defaults(func=_cmd_import)

data_olympus/cli/indexgen.py

@@ -0,0 +1,60 @@
+"""Regenerate index.md files for progressive disclosure."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from data_olympus.format import Document
+from data_olympus.format.validate import RESERVED as _RESERVED
+
+_SKIP = {".git", "__pycache__", ".venv", ".pytest_cache", ".ruff_cache", "node_modules"}
+
+
+def _dirs_with_markdown(root: Path) -> list[Path]:
+    dirs: set[Path] = set()
+    for md in root.rglob("*.md"):
+        if any(part in _SKIP for part in md.parts):
+            continue
+        if md.name in _RESERVED:
+            continue
+        dirs.add(md.parent)
+    return sorted(dirs)
+
+
+def _entry(doc_path: Path) -> tuple[str, str, str]:
+    """Return (title, relative_url, description) for a concept file."""
+    doc = Document.load(doc_path)
+    title = doc.frontmatter.get("title") or doc_path.stem
+    desc = doc.frontmatter.get("description") or ""
+    return str(title), doc_path.name, str(desc)
+
+
+def regenerate_indexes(root: Path) -> list[Path]:
+    """Write an index.md into every directory that holds concept docs.
+    Returns the list of index.md paths written."""
+    root = Path(root)
+    written: list[Path] = []
+    for d in _dirs_with_markdown(root):
+        concepts = sorted(p for p in d.glob("*.md") if p.name not in _RESERVED)
+        subdirs = sorted(
+            sub
+            for sub in d.iterdir()
+            if sub.is_dir() and sub.name not in _SKIP and any(sub.rglob("*.md"))
+        )
+        lines: list[str] = [f"# {d.name or root.name}", ""]
+        if concepts:
+            lines.append("# Concepts")
+            for c in concepts:
+                title, url, desc = _entry(c)
+                suffix = f" - {desc}" if desc else ""
+                lines.append(f"* [{title}]({url}){suffix}")
+            lines.append("")
+        if subdirs:
+            lines.append("# Subdirectories")
+            for sub in subdirs:
+                lines.append(f"* [{sub.name}/]({sub.name}/)")
+            lines.append("")
+        idx_path = d / "index.md"
+        idx_path.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+        written.append(idx_path)
+    return written