ki-manager 2.3.1.dev1__tar.gz → 2.3.2.dev2__tar.gz

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/CHANGELOG.md

@@ -9,7 +9,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.3.1.dev1] — 2026-10-16
+## [2.3.2.dev2] — 2026-11-01
+
+### Added
+- **`ki_list` Navigation Tool**:
+  - Direct navigation tool to list registered Knowledge Items and Architecture Decision Records (ADRs) with summaries and covered modules without filesystem scans.
+  - Supports filtering by type (`scope: "all" | "ki" | "adr"`), output formats (`format: "markdown" | "json"`), and search query (`filter: "<text>"`).
+  - Available as a direct top-level tool in both full mode (35 tools) and compact facade mode (7 tools).
+- **BM25 Search Pagination (`ki_search`)**:
+  - Added 1-based `page` parameter for intuitive result pagination alongside `offset`.
+  - Prominent pagination header and next-page action hints (`[Page X/Y]`, `Next page: ki_search(query="...", page=X+1)`) in search outputs to prevent AI models from getting stuck in repeat queries.
+
+## [2.3.2.dev1] — 2026-10-20
+
+### Fixed
+- **`find_unmapped_files` Traversal & Scoping**:
+  - Automatically loads and enforces `.gitignore` patterns and `doc_config.json` `exclude` rules (in addition to `exclude_patterns`) during repository discovery.
+  - When scanning repository root by default, scopes file discovery to root segments of configured `tracked_modules`, avoiding timeouts and runaway directory walks across large external data trees.
+  - Made the CLI `path` argument optional, defaulting to root / tracked modules.
+- **`check_ki_drift` Markdown Table Header Validation**:
+  - Validates Markdown table headers explicitly for file path columns (`File`, `Path`, `Source`, `Location`) before inspecting cells for broken paths.
+  - Tables without file columns (e.g. `| Tool | Access | Purpose |`) are cleanly bypassed, eliminating false-positive `Missing file: Access` errors.
+
+## [2.3.1] — 2026-10-18
 
 ### Security & Hardening
 - **Path Traversal Protection**: Enforced strict directory boundary containment across all file discovery and inspection tools (`find_unmapped_files`, `analyze_module`, `ki_search`, and custom agent paths) to prevent prefix-based sandbox traversal attacks.

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ki-manager
-Version: 2.3.1.dev1
+Version: 2.3.2.dev2
 Summary: Knowledge Item (KI) management MCP server for AI-assisted development
 Project-URL: Homepage, https://github.com/Laeryid/KI-base
 Project-URL: Repository, https://github.com/Laeryid/KI-base

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ki-manager"
-version = "2.3.1.dev1"
+version = "2.3.2.dev2"
 description = "Knowledge Item (KI) management MCP server for AI-assisted development"
 readme = "README.md"
 license = { file = "LICENSE" }

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/__init__.py

@@ -1,3 +1,3 @@
 
 """ki-manager — Knowledge Item MCP server for AI-assisted development."""
-__version__ = "2.3.1.dev1"
+__version__ = "2.3.2.dev2"

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/cli.py

@@ -144,11 +144,14 @@ def main():
     if command == "install-skills":
         install_skills(sys.argv[2:])
     elif command in ("--version", "-v"):
-        import importlib.metadata
         try:
-            v = importlib.metadata.version("ki-manager")
+            from . import __version__ as v
         except Exception:
-            v = "unknown"
+            import importlib.metadata
+            try:
+                v = importlib.metadata.version("ki-manager")
+            except Exception:
+                v = "unknown"
         print(f"ki-manager {v}")
         sys.exit(0)
     else:

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/scripts/check_ki_drift.py

@@ -76,31 +76,87 @@ def parse_ki_file(ki_path: Path) -> Dict[str, Any]:
 
     # Extract Key Components table symbols
     # Expected table format: | `SymbolName` | `rel/path/file.ext` | Purpose |
+    # Only tables that explicitly contain a File/Path column header are inspected.
     table_symbols: List[Dict[str, str]] = []
     in_key_components = False
-    table_row_pattern = re.compile(r"\|\s*`?([A-Za-z0-9_]+)`?\s*\|\s*`?([^`|\s]+)`?\s*\|")
+    pending_header: Optional[List[str]] = None
+    current_table_active = False
+    sym_idx = -1
+    file_idx = -1
 
     for line in lines:
         if line.startswith("## Key Components"):
             in_key_components = True
+            pending_header = None
+            current_table_active = False
             continue
         elif in_key_components and line.startswith("## "):
             in_key_components = False
+            pending_header = None
+            current_table_active = False
             continue
 
-        if in_key_components and line.strip().startswith("|"):
-            lower = line.lower()
-            if any(k in lower for k in ["class / function", "component", "|---", "|:---", "| — |", "| - |"]):
-                continue
-            m = table_row_pattern.search(line)
-            if m:
-                sym_name = m.group(1).strip()
-                file_rel = m.group(2).strip()
-                header_keywords = {"component", "file", "purpose", "class", "function", "description"}
-                if sym_name.lower() in header_keywords or file_rel.lower() in header_keywords:
-                    continue
-                if sym_name and file_rel and not file_rel.startswith("—"):
-                    table_symbols.append({"symbol": sym_name, "file": file_rel})
+        if not in_key_components:
+            continue
+
+        stripped = line.strip()
+        if not stripped.startswith("|"):
+            pending_header = None
+            current_table_active = False
+            continue
+
+        raw_cells = [c.strip() for c in stripped.strip("|").split("|")]
+        # Check if separator row (e.g. |---|---| or |:---|---:|)
+        is_separator = (
+            len(raw_cells) > 0
+            and all(re.match(r"^:?-{2,}:?$", c) for c in raw_cells if c)
+        )
+
+        if is_separator:
+            if pending_header:
+                file_idx = -1
+                for i, col in enumerate(pending_header):
+                    col_lower = col.lower()
+                    if any(w in col_lower for w in ["file", "path", "source", "location"]):
+                        file_idx = i
+                        break
+
+                sym_idx = -1
+                for i, col in enumerate(pending_header):
+                    if i == file_idx:
+                        continue
+                    col_lower = col.lower()
+                    if any(w in col_lower for w in ["class", "function", "symbol", "component", "name", "element", "method", "tool"]):
+                        sym_idx = i
+                        break
+
+                if sym_idx == -1 and file_idx != -1:
+                    sym_idx = 0 if file_idx != 0 else 1
+
+                current_table_active = (file_idx != -1 and sym_idx != -1)
+                pending_header = None
+            continue
+
+        if pending_header is None and not current_table_active:
+            # Possible header row
+            pending_header = raw_cells
+            continue
+
+        if current_table_active:
+            if len(raw_cells) > max(sym_idx, file_idx):
+                sym_val = raw_cells[sym_idx].strip(" `").strip()
+                file_val = raw_cells[file_idx].strip(" `").strip()
+                header_keywords = {"component", "file", "path", "purpose", "class", "function", "description", "tool", "access"}
+                if (
+                    sym_val
+                    and file_val
+                    and not sym_val.startswith("—")
+                    and not file_val.startswith("—")
+                    and not file_val.startswith("-")
+                    and sym_val.lower() not in header_keywords
+                    and file_val.lower() not in header_keywords
+                ):
+                    table_symbols.append({"symbol": sym_val, "file": file_val})
 
     # Extract wiki-links [[KI_*.md]]
     wiki_links = []

ki_manager-2.3.2.dev2/src/ki_manager/scripts/find_unmapped_files.py

@@ -0,0 +1,143 @@
+import os
+import sys
+import argparse
+import json
+from pathlib import Path
+from typing import List
+
+# Add path to ki_utils
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ki_utils
+
+
+def _scan_path(target_path: str, project_root: str, mapped_paths: set, exclude_patterns: set, ignored_exts: set) -> List[str]:
+    abs_target = os.path.abspath(os.path.join(project_root, target_path))
+    if not ki_utils.is_subpath(abs_target, project_root) or not os.path.exists(abs_target):
+        return []
+
+    unmapped = []
+    if os.path.isfile(abs_target):
+        rel_to_project = os.path.relpath(abs_target, project_root).replace("\\", "/")
+        fname = os.path.basename(abs_target)
+        if fname.startswith(".") or any(fname.endswith(ext) for ext in ignored_exts):
+            return []
+        if ki_utils.should_exclude(fname, rel_to_project, exclude_patterns):
+            return []
+        if abs_target in mapped_paths:
+            return []
+        for mapped in mapped_paths:
+            if os.path.isdir(mapped) and abs_target.startswith(os.path.join(mapped, "")):
+                return []
+        return [rel_to_project]
+
+    for root, dirs, files in os.walk(abs_target):
+        dirs[:] = [
+            d for d in dirs
+            if not d.startswith(".")
+            and not ki_utils.should_exclude(d, os.path.relpath(os.path.join(root, d), project_root), exclude_patterns)
+        ]
+
+        for f in files:
+            if f.startswith(".") or any(f.endswith(ext) for ext in ignored_exts):
+                continue
+
+            full_path = os.path.abspath(os.path.join(root, f))
+            rel_to_project = os.path.relpath(full_path, project_root).replace("\\", "/")
+            if ki_utils.should_exclude(f, rel_to_project, exclude_patterns):
+                continue
+
+            if full_path in mapped_paths:
+                continue
+
+            is_parent_mapped = False
+            for mapped in mapped_paths:
+                if os.path.isdir(mapped):
+                    if full_path.startswith(os.path.join(mapped, "")):
+                        is_parent_mapped = True
+                        break
+
+            if not is_parent_mapped:
+                unmapped.append(rel_to_project)
+
+    return unmapped
+
+
+def get_unmapped_files(target_path: str = ".") -> List[str]:
+    """Returns a sorted list of unmapped files relative to project root."""
+    project_root = ki_utils.get_project_root()
+    doc_config = ki_utils.get_doc_config()
+
+    if not project_root or not doc_config:
+        return []
+
+    # 1. Collect all files that are already mapped in doc_config.json
+    mapped_paths = set()
+    knowledge_items = doc_config.get("knowledge_items", {})
+
+    for ki in knowledge_items.values():
+        depends_on = ki.get("depends_on", [])
+        for p in depends_on:
+            abs_p = os.path.abspath(os.path.join(project_root, p))
+            mapped_paths.add(abs_p)
+
+    ignored_exts = {'.pyc', '.pyo', '.pyd', '.obj', '.dll', '.exe', '.bin'}
+    exclude_patterns = ki_utils.get_exclude_patterns()
+
+    norm_target = (target_path or ".").strip()
+
+    # If target is root/empty, scope to tracked_modules if defined
+    if norm_target in (".", ""):
+        tracked_modules = doc_config.get("coverage_settings", {}).get("tracked_modules") or doc_config.get("tracked_modules", [])
+        target_dirs = set()
+        if isinstance(tracked_modules, list) and tracked_modules:
+            for m in tracked_modules:
+                mod_path = m[0] if isinstance(m, (list, tuple)) else m
+                if isinstance(mod_path, str) and mod_path.strip():
+                    norm_p = mod_path.replace("\\", "/").strip("/")
+                    top_segment = norm_p.split("/")[0] if "/" in norm_p else norm_p
+                    if top_segment:
+                        target_dirs.add(top_segment)
+
+        if target_dirs:
+            unmapped_set = set()
+            for td in sorted(target_dirs):
+                unmapped_set.update(_scan_path(td, project_root, mapped_paths, exclude_patterns, ignored_exts))
+            return sorted(unmapped_set)
+        else:
+            return sorted(_scan_path(".", project_root, mapped_paths, exclude_patterns, ignored_exts))
+
+    return sorted(_scan_path(norm_target, project_root, mapped_paths, exclude_patterns, ignored_exts))
+
+
+def find_unmapped_files(target_path: str = "."):
+    project_root = ki_utils.get_project_root()
+    doc_config = ki_utils.get_doc_config()
+
+    if not project_root or not doc_config:
+        print("Error: Could not resolve project root or doc_config.json")
+        return
+
+    display_target = (target_path or ".").strip()
+    if display_target != ".":
+        abs_target = os.path.abspath(os.path.join(project_root, display_target))
+        if not os.path.exists(abs_target):
+            print(f"Error: Target path '{display_target}' does not exist.")
+            return
+
+    unmapped = get_unmapped_files(display_target)
+    if unmapped:
+        print(f"### Unmapped Files in '{display_target}':")
+        for f in unmapped:
+            print(f"- {f}")
+    else:
+        print(f"All files in '{display_target}' are already mapped in doc_config.json.")
+
+
+if __name__ == "__main__":
+    if sys.platform == "win32":
+        sys.stdout.reconfigure(encoding="utf-8")
+    parser = argparse.ArgumentParser(description="Find files in a directory not covered by any KI in doc_config.json")
+    parser.add_argument("path", nargs="?", default=".", help="Relative path from project root to scan (default: tracked_modules or .)")
+    args = parser.parse_args()
+
+    find_unmapped_files(args.path)

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/scripts/ki_search.py

@@ -198,6 +198,7 @@ def search_knowledge(
     scope: str = "all",
     limit: int = 5,
     offset: int = 0,
+    page: Optional[int] = None,
     k1: float = 1.5,
     b: float = 0.75,
 ) -> Dict[str, Any]:
@@ -209,6 +210,7 @@ def search_knowledge(
     :param scope: "all", "ki", or "adr".
     :param limit: Max number of results to return (default: 5).
     :param offset: Offset index for pagination (default: 0).
+    :param page: 1-based page number for pagination (calculates offset if provided).
     :param k1: BM25 k1 parameter.
     :param b: BM25 b parameter.
     """
@@ -217,6 +219,14 @@ def search_knowledge(
     if not project_root:
         return {"error": "No project root found. Run ki_init_project or specify workspace.", "results": []}
 
+    if page is not None:
+        try:
+            p = int(page)
+            if p > 0:
+                offset = (p - 1) * limit
+        except (ValueError, TypeError):
+            pass
+
     knowledge_root = ki_utils.get_knowledge_root()
     if not knowledge_root or not os.path.exists(knowledge_root) or not ki_utils.is_subpath(knowledge_root, project_root):
         for cand in [
@@ -231,7 +241,7 @@ def search_knowledge(
 
     q_tokens = tokenize(query)
     if not q_tokens:
-        return {"query": query, "total": 0, "results": []}
+        return {"query": query, "total": 0, "offset": offset, "limit": limit, "page": 1, "total_pages": 1, "results": []}
 
     docs: List[Dict[str, Any]] = []
 
@@ -261,7 +271,7 @@ def search_knowledge(
 
     total_docs = len(docs)
     if total_docs == 0:
-        return {"query": query, "total": 0, "results": []}
+        return {"query": query, "total": 0, "offset": offset, "limit": limit, "page": 1, "total_pages": 1, "results": []}
 
     avg_dl = sum(d["weighted_len"] for d in docs) / total_docs
 
@@ -298,14 +308,19 @@ def search_knowledge(
             })
 
     scored_results.sort(key=lambda x: x["score"], reverse=True)
+    total_count = len(scored_results)
     safe_offset = max(0, offset)
     final_results = scored_results[safe_offset : safe_offset + limit]
+    current_page = (safe_offset // limit) + 1 if limit > 0 else 1
+    total_pages = max(1, math.ceil(total_count / limit)) if limit > 0 else 1
 
     return {
         "query": query,
-        "total": len(scored_results),
+        "total": total_count,
         "offset": safe_offset,
         "limit": limit,
+        "page": current_page,
+        "total_pages": total_pages,
         "results": final_results,
     }
 
@@ -317,13 +332,24 @@ def format_search_markdown(search_dict: Dict[str, Any]) -> str:
     results = search_dict.get("results", [])
     offset = search_dict.get("offset", 0)
     limit = search_dict.get("limit", 5)
+    page = search_dict.get("page")
+    total_pages = search_dict.get("total_pages")
 
     if total == 0 or not results:
         return f'No documentation matching "{query}" found.'
 
+    if page is None and limit > 0:
+        page = (offset // limit) + 1
+    if total_pages is None and limit > 0:
+        total_pages = max(1, math.ceil(total / limit))
+
     start_idx = offset + 1
     end_idx = offset + len(results)
-    out = [f'Found {total} result(s) for "{query}" (showing {start_idx}-{end_idx}):\n']
+    out = [f'Found {total} result(s) for "{query}" [Page {page}/{total_pages} (showing {start_idx}-{end_idx})]:\n']
+
+    if end_idx < total:
+        next_page = (page or 1) + 1
+        out.append(f'> 💡 **Next page**: `ki_search(query="{query}", page={next_page})` (or `offset={end_idx}`)\n')
 
     for i, r in enumerate(results, start=start_idx):
         doc_type = r.get("type", "ki").upper()
@@ -337,6 +363,7 @@ def format_search_markdown(search_dict: Dict[str, Any]) -> str:
             out.append(f"   > {snippet}")
 
     if end_idx < total:
-        out.append(f"\n*Showing {end_idx} of {total} results. Call ki_search(query='{query}', offset={end_idx}) to view more.*")
+        next_page = (page or 1) + 1
+        out.append(f"\n*Showing {end_idx} of {total} results. Call `ki_search(query='{query}', page={next_page})` (or `offset={end_idx}`) to view more.*")
 
     return "\n".join(out)

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/scripts/ki_utils.py

@@ -18,6 +18,7 @@ import tempfile
 import argparse
 import fnmatch
 from pathlib import Path
+from typing import Optional, Dict, Any, List, Union
 
 # Global state — set by MCP server on initialize
 ACTIVE_WORKSPACE_PATH = None
@@ -304,15 +305,20 @@ def get_project_root() -> str:
 
 def get_doc_config_path() -> str:
     root = get_knowledge_root()
-    return os.path.join(root, "doc_config.json") if root else ""
+    cand = os.path.join(root, "doc_config.json") if root else ""
+    if cand and os.path.exists(cand):
+        return cand
+    proj = get_project_root()
+    if proj:
+        for p in [os.path.join(proj, ".ki-base", "doc_config.json"), os.path.join(proj, "doc_config.json")]:
+            if os.path.exists(p):
+                return p
+    return cand
 
 
 def get_doc_config() -> dict:
-    root = get_knowledge_root()
-    if not root:
-        return {}
-    path = os.path.join(root, "doc_config.json")
-    if os.path.exists(path):
+    path = get_doc_config_path()
+    if path and os.path.exists(path):
         try:
             with open(path, "r", encoding="utf-8") as f:
                 return json.load(f)
@@ -335,6 +341,34 @@ def get_local_config() -> dict:
     return {}
 
 
+def load_gitignore_patterns(project_root: str = None) -> set:
+    """Parses .gitignore file in project_root if present, returning a set of pattern strings."""
+    if not project_root:
+        project_root = get_project_root()
+    if not project_root or not os.path.isdir(project_root):
+        return set()
+
+    gitignore_path = os.path.join(project_root, ".gitignore")
+    if not os.path.isfile(gitignore_path):
+        return set()
+
+    patterns = set()
+    try:
+        with open(gitignore_path, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or line.startswith("!"):
+                    continue
+                norm = line.replace("\\", "/").rstrip("/")
+                if norm.startswith("/"):
+                    norm = norm.lstrip("/")
+                if norm:
+                    patterns.add(norm)
+    except Exception:
+        pass
+    return patterns
+
+
 DEFAULT_EXCLUDED_DIRS = {
     ".git", "__pycache__", "node_modules", ".venv", "venv", "dist", "build",
     ".mypy_cache", ".pytest_cache", ".ruff_cache",
@@ -344,33 +378,45 @@ DEFAULT_EXCLUDED_DIRS = {
 def get_exclude_patterns() -> set:
     """
     Returns the set of directory/file exclude patterns.
-    Combines default excluded dirs with exclude_patterns from:
+    Combines default excluded dirs with exclude_patterns and exclude from:
     1. config.json (machine-specific)
-    2. doc_config.json (coverage_settings.exclude_patterns or top-level exclude_patterns)
+    2. doc_config.json (coverage_settings.exclude_patterns, coverage_settings.exclude,
+       top-level exclude_patterns, top-level exclude)
     3. ki_config.json
+    4. .gitignore in project root
     """
     patterns = set(DEFAULT_EXCLUDED_DIRS)
 
+    def _add_from_cfg(cfg_dict, key):
+        val = cfg_dict.get(key, [])
+        if isinstance(val, list):
+            for p in val:
+                if p:
+                    patterns.add(str(p))
+        elif isinstance(val, str) and val:
+            patterns.add(val)
+
     # 1. config.json
     local_cfg = get_local_config()
-    for p in local_cfg.get("exclude_patterns", []):
-        if p:
-            patterns.add(str(p))
+    _add_from_cfg(local_cfg, "exclude_patterns")
+    _add_from_cfg(local_cfg, "exclude")
 
     # 2. doc_config.json
     doc_cfg = get_doc_config()
-    for p in doc_cfg.get("exclude_patterns", []):
-        if p:
-            patterns.add(str(p))
-    for p in doc_cfg.get("coverage_settings", {}).get("exclude_patterns", []):
-        if p:
-            patterns.add(str(p))
+    _add_from_cfg(doc_cfg, "exclude_patterns")
+    _add_from_cfg(doc_cfg, "exclude")
+    cov_cfg = doc_cfg.get("coverage_settings", {})
+    if isinstance(cov_cfg, dict):
+        _add_from_cfg(cov_cfg, "exclude_patterns")
+        _add_from_cfg(cov_cfg, "exclude")
 
     # 3. ki_config.json
     ki_cfg = get_ki_cfg()
-    for p in ki_cfg.get("exclude_patterns", []):
-        if p:
-            patterns.add(str(p))
+    _add_from_cfg(ki_cfg, "exclude_patterns")
+    _add_from_cfg(ki_cfg, "exclude")
+
+    # 4. .gitignore
+    patterns.update(load_gitignore_patterns())
 
     return patterns
 
@@ -389,15 +435,17 @@ def should_exclude(name: str, rel_path: str = "", patterns: set = None) -> bool:
     norm_rel = rel_path.replace("\\", "/").strip("/") if rel_path else ""
 
     for pat in patterns:
-        if fnmatch.fnmatch(name, pat):
+        norm_pat = pat.replace("\\", "/").strip("/")
+        if not norm_pat:
+            continue
+        if fnmatch.fnmatch(name, norm_pat):
             return True
         if norm_rel:
-            norm_pat = pat.replace("\\", "/").strip("/")
             if norm_rel == norm_pat or norm_rel.startswith(norm_pat + "/"):
                 return True
             if fnmatch.fnmatch(norm_rel, norm_pat):
                 return True
-            if any(fnmatch.fnmatch(comp, pat) for comp in norm_rel.split("/")):
+            if any(fnmatch.fnmatch(comp, norm_pat) for comp in norm_rel.split("/")):
                 return True
 
     return False
@@ -458,6 +506,122 @@ def get_ki_list_table() -> str:
     return "\n".join(rows)
 
 
+def get_ki_list_data(scope: str = "all", filter_query: Optional[str] = None) -> Dict[str, Any]:
+    """Collects structured list of Knowledge Items and ADRs with optional filtering."""
+    jail = get_knowledge_root()
+    proj = get_project_root()
+    dec_dirs = get_decisions_dirs(proj, jail)
+    doc_config = get_doc_config() or {}
+    items = doc_config.get("knowledge_items", {})
+
+    flt = filter_query.lower().strip() if filter_query else None
+
+    ki_list = []
+    if scope in ("all", "ki"):
+        for name, info in sorted(items.items()):
+            summary = info.get("summary", info.get("description", "—"))
+            covers = info.get("covers", [])
+            display_name = name
+            if "path" in info and info["path"]:
+                display_name = info["path"]
+
+            if flt:
+                covers_str = " ".join(covers).lower() if isinstance(covers, list) else str(covers).lower()
+                if flt not in name.lower() and flt not in summary.lower() and flt not in covers_str and flt not in display_name.lower():
+                    continue
+
+            ki_list.append({
+                "name": name,
+                "path": display_name,
+                "summary": summary,
+                "covers": covers,
+                "type": "ki",
+            })
+
+    adr_list = []
+    if scope in ("all", "adr"):
+        adr_records = []
+        seen_files = set()
+        for c in dec_dirs:
+            if os.path.exists(c) and os.path.isdir(c):
+                for f in sorted(os.listdir(c)):
+                    if f.endswith(".md") and f not in seen_files:
+                        seen_files.add(f)
+                        full_p = os.path.join(c, f)
+                        adr_records.append(parse_adr_file(full_p, proj))
+
+        def _sort_key(r):
+            num = int(r["id"]) if r["id"].isdigit() else 999999
+            return (num, r["file"])
+        adr_records.sort(key=_sort_key)
+
+        for r in adr_records:
+            if flt:
+                target_text = f"{r['id']} {r['title']} {r['summary']} {r['file']} {r['status']}".lower()
+                if flt not in target_text:
+                    continue
+            adr_list.append({
+                "id": r["id"],
+                "title": r["title"],
+                "status": r["status"],
+                "date": r["date"],
+                "summary": r["summary"],
+                "file": r["file"],
+                "rel_path": r["rel_path"],
+                "type": "adr",
+            })
+
+    return {
+        "scope": scope,
+        "filter": filter_query,
+        "total_ki": len(ki_list),
+        "total_adr": len(adr_list),
+        "knowledge_items": ki_list,
+        "adrs": adr_list,
+    }
+
+
+def format_ki_list_markdown(data: Dict[str, Any]) -> str:
+    """Formats KI and ADR list into clean Markdown tables."""
+    scope = data.get("scope", "all")
+    flt = data.get("filter")
+    ki_list = data.get("knowledge_items", [])
+    adr_list = data.get("adrs", [])
+
+    sections = []
+    flt_msg = f" matching '{flt}'" if flt else ""
+
+    if scope in ("all", "ki"):
+        if ki_list:
+            rows = [
+                f"### Knowledge Items ({len(ki_list)}){flt_msg}\n",
+                "| File | Summary / Topic | Covered Modules |",
+                "|------|-----------------|-----------------|"
+            ]
+            for item in ki_list:
+                covers_str = ", ".join(f"`{c}`" for c in item.get("covers", [])) if item.get("covers") else "—"
+                rows.append(f"| `{item['path']}` | {item['summary']} | {covers_str} |")
+            sections.append("\n".join(rows))
+        else:
+            sections.append(f"No Knowledge Items{flt_msg} found.")
+
+    if scope in ("all", "adr"):
+        if adr_list:
+            rows = [
+                f"### Architecture Decision Records ({len(adr_list)}){flt_msg}\n",
+                "| ID | Title | Status | Date | File |",
+                "|----|-------|--------|------|------|"
+            ]
+            for r in adr_list:
+                link = f"[{r['file']}]({r['rel_path']})"
+                rows.append(f"| {r['id']} | {r['title']} | {r['status']} | {r['date']} | {link} |")
+            sections.append("\n".join(rows))
+        elif scope == "adr":
+            sections.append(f"No ADRs{flt_msg} found.")
+
+    return "\n\n".join(sections)
+
+
 def save_doc_config(config: dict) -> str:
     """Atomically saves doc_config.json for the active project."""
     path = get_doc_config_path()

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/server.py

@@ -80,12 +80,33 @@ CURRENT_TOOL_MODE: str = os.environ.get("KI_TOOL_MODE", "full").lower()
 GLOBAL_INSTRUCTIONS = """\
 # Global AI Instructions for ki-manager
 
-## 1. Project Navigation
+## 1. Project Navigation & Architecture
+`{{KI_DIR}}` (knowledge_root) is the **system container** for the entire knowledge infrastructure (analogous to `.git/` in Git).
+
+```
+<project_root>/
+├── {{KI_DIR}}/                 ← SYSTEM CONTAINER (do not pollute with .ki.md)
+│   ├── config.json             ← Machine-specific environment config (venv path, etc.)
+│   ├── ki_config.json          ← Project knowledge configuration
+│   ├── doc_config.json         ← Manifest of tracked modules and Knowledge Items
+│   ├── DIR_INDEX.md            ← Auto-generated project directory tree
+│   ├── coverage_matrix.md      ← Audit report (from audit_coverage)
+│   ├── knowledge/              ← STRICTLY ALL Knowledge Items (*.ki.md) live HERE!
+│   │   ├── _OVERVIEW.ki.md     ← Project overview stub (MUST NOT be deleted)
+│   │   └── <module>.ki.md      ← Module Knowledge Items
+│   └── decisions/              ← Architectural Decision Records (*.md ADRs)
+├── AGENTS.md                   ← Project instructions for AI agents in harness
+└── CLAUDE.md                   ← Instructions for Claude Code / Anthropic
+```
+
 - **`DIR_INDEX.md`** (`{{KI_DIR}}/DIR_INDEX.md`) — project directory tree.
 - **`doc_config.json`** (`{{KI_DIR}}/doc_config.json`) — manifest of tracked artifacts.
-- All Knowledge Items (KI) live in `{{KI_DIR}}/knowledge/`.
-- Architecture Decision Records (ADR) live in `{{KI_DIR}}/decisions/` or `decisions/`.
-- Start here: `{{KI_DIR}}/knowledge/_OVERVIEW.ki.md`
+- **`_OVERVIEW.ki.md`** (`{{KI_DIR}}/knowledge/_OVERVIEW.ki.md`) — start here for high-level architecture.
+- **Harness & Agent Instructions Guide**: see `ki://agent-rules.md` or `ki_instructions(document="agent-rules")` for recommended snippets for `AGENTS.md` and `CLAUDE.md`.
+
+> [!CAUTION]
+> 1. NEVER place `*.ki.md` files directly in the root of `{{KI_DIR}}/`. All Knowledge Items must reside in `{{KI_DIR}}/knowledge/`.
+> 2. NEVER delete `{{KI_DIR}}/knowledge/`. The initial `_OVERVIEW.ki.md` (~640 bytes) is a bootstrap stub, not a duplicate. Deleting `knowledge/` breaks audit, scaffolding, and dependency analysis.
 
 ## 2. Forced Efficiency (Anti-Hallucinations)
 1. **Mandatory Planning Template**:
@@ -97,12 +118,12 @@ GLOBAL_INSTRUCTIONS = """\
 2. **Strict Adherence**:
    - Always read relevant KIs before modifying a module.
 <!-- if-compact -->
-   - Use `ki_search(query="...")` and `ki_read(rel_path="...")` to discover and read documentation.
+   - Use `ki_list()` to view all documented items, `ki_search(query="...")` to find topics, and `ki_read(rel_path="...")` to read documentation.
    - For read-only analysis tools (`audit_coverage`, `generate_dir_index`, `ki_scaffold_status`, `git_diff_secured`), call `ki_call(tool="...")`.
    - For state-modifying operations (`git_checkpoint`, `write_know_file`, `edit_know_file`, `ki_scaffold`, `create_adr`), call `ki_mutate(tool="...", args={...})`.
    - To inspect schemas of available tools, call `ki_tools(name="<tool_name>")`.
 <!-- else-compact -->
-   - Use `ki_search(query="...")` and `ki_read(rel_path="...")` or `read_know_file(rel_path="...")` to explore documentation.
+   - Use `ki_list()` to view all documented items, `ki_search(query="...")` to find topics, and `ki_read(rel_path="...")` or `read_know_file(rel_path="...")` to explore documentation.
    - After significant changes, run `audit_coverage` via MCP.
    - Use `git_checkpoint` to save knowledge snapshots.
 <!-- /if-compact -->
@@ -1038,7 +1059,8 @@ MCP_TOOLS = [
             "idempotentHint": True,
         },
     },
-    # ─── Search & Read ───
+    # ─── Navigation, Search & Read ───
+    facade.KI_LIST_TOOL,
     facade.KI_SEARCH_TOOL,
     facade.KI_READ_TOOL,
 ]
@@ -1049,6 +1071,7 @@ facade.sync_dispatch_schemas(MCP_TOOLS)
 _INSTRUCTIONS_TOOL = next(t for t in MCP_TOOLS if t["name"] == "ki_instructions")
 COMPACT_TOOLS = [
     _INSTRUCTIONS_TOOL,
+    facade.KI_LIST_TOOL,
     facade.KI_SEARCH_TOOL,
     facade.KI_READ_TOOL,
     facade.KI_TOOLS_TOOL,
@@ -1970,14 +1993,29 @@ def handle_tool_call(name: str, args: dict) -> Any:
                 return ke.restore_mapping()
             return str(ke.save_state(ke.capture_full_state()))
 
-        # ─── Search & Read ───
+        # ─── Navigation, Search & Read ───
+        if name == "ki_list":
+            scope = args.get("scope", "all")
+            fmt = args.get("format", "markdown")
+            flt = args.get("filter")
+            data = ki_utils.get_ki_list_data(scope=scope, filter_query=flt)
+            if fmt == "json":
+                return json.dumps(data, ensure_ascii=False, indent=2)
+            return ki_utils.format_ki_list_markdown(data)
+
         if name == "ki_search":
             query = args.get("query", "").strip()
             scope = args.get("scope", "all")
             limit = int(args.get("limit", 5))
             offset = int(args.get("offset", 0))
+            page = args.get("page")
+            if page is not None:
+                try:
+                    page = int(page)
+                except (ValueError, TypeError):
+                    page = None
             fmt = args.get("format", "markdown")
-            res = ki_search.search_knowledge(query, project_root=get_project_root(), scope=scope, limit=limit, offset=offset)
+            res = ki_search.search_knowledge(query, project_root=get_project_root(), scope=scope, limit=limit, offset=offset, page=page)
             if fmt == "json":
                 return json.dumps(res, ensure_ascii=False, indent=2)
             return ki_search.format_search_markdown(res)
@@ -2273,6 +2311,7 @@ def main():
                 jail = get_jail_dir()
                 resources = [
                     {"uri": "ki://instructions.md", "name": "instructions.md (Global AI Rules)", "mimeType": "text/markdown"},
+                    {"uri": "ki://agent-rules.md", "name": "agent-rules.md (Harness & Agent Instructions Guide)", "mimeType": "text/markdown"},
                     {"uri": "ki://knowledge-items.md", "name": "knowledge-items.md (Dynamic KI List)", "mimeType": "text/markdown"},
                     {"uri": "ki://adr-list.md", "name": "adr-list.md (Dynamic ADR List)", "mimeType": "text/markdown"},
                 ]
@@ -2319,6 +2358,15 @@ def main():
                 if uri == "ki://instructions.md":
                     know_name = os.path.basename(ki_utils.get_knowledge_root()) or ".ki-base"
                     content = facade.render_instruction(GLOBAL_INSTRUCTIONS, CURRENT_TOOL_MODE, know_name)
+                elif uri == "ki://agent-rules.md":
+                    wf_path = (_WORKFLOWS_DIR / "agent-rules.md").resolve()
+                    if wf_path.exists():
+                        with open(wf_path, "r", encoding="utf-8") as f:
+                            raw = f.read()
+                        know_name = os.path.basename(ki_utils.get_knowledge_root()) or ".ki-base"
+                        content = facade.render_instruction(raw, CURRENT_TOOL_MODE, know_name)
+                    else:
+                        content = "agent-rules.md not found."
                 elif uri == "ki://knowledge-items.md":
                     ki_table = ki_utils.get_ki_list_table()
                     adr_table = ki_utils.get_adr_table()

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/tools/facade.py

@@ -49,6 +49,7 @@ TOOL_GROUPS: Dict[str, List[str]] = {
         "create_adr",
     ],
     "files": [
+        "ki_list",
         "read_know_file",
         "write_know_file",
         "edit_know_file",
@@ -66,6 +67,41 @@ TOOL_GROUPS: Dict[str, List[str]] = {
 
 # ─── Tool Schemas ─────────────────────────────────────────────────────────────
 
+KI_LIST_TOOL = {
+    "name": "ki_list",
+    "description": (
+        "List Knowledge Items (KI) and Architecture Decision Records (ADRs) registered in the active project. "
+        "Provides a structured overview of all documented modules, topics, and architectural decisions."
+    ),
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "scope": {
+                "type": "string",
+                "enum": ["all", "ki", "adr"],
+                "default": "all",
+                "description": "Filter by document type: 'all' (default), 'ki' (Knowledge Items), or 'adr' (Architecture Decision Records).",
+            },
+            "format": {
+                "type": "string",
+                "enum": ["markdown", "json"],
+                "default": "markdown",
+                "description": "Output format: 'markdown' (structured tables, default) or 'json'.",
+            },
+            "filter": {
+                "type": "string",
+                "description": "Optional substring to filter by filename, title, summary, or covered module.",
+            },
+        },
+    },
+    "annotations": {
+        "title": "List Knowledge Items & ADRs",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+    },
+}
+
 KI_SEARCH_TOOL = {
     "name": "ki_search",
     "description": (
@@ -96,6 +132,12 @@ KI_SEARCH_TOOL = {
                 "default": 0,
                 "description": "Result offset for pagination (default: 0).",
             },
+            "page": {
+                "type": "integer",
+                "minimum": 1,
+                "default": 1,
+                "description": "Page number for pagination (1-based, alternative to offset).",
+            },
             "format": {
                 "type": "string",
                 "enum": ["markdown", "json"],
@@ -245,7 +287,7 @@ KI_MUTATE_TOOL = {
 
 
 # Direct facade tools that cannot be called recursively via ki_call / ki_mutate
-DIRECT_FACADE_TOOLS = {"ki_instructions", "ki_search", "ki_read", "ki_tools", "ki_call", "ki_mutate"}
+DIRECT_FACADE_TOOLS = {"ki_instructions", "ki_list", "ki_search", "ki_read", "ki_tools", "ki_call", "ki_mutate"}
 
 
 def sync_dispatch_schemas(all_tools: List[Dict[str, Any]]) -> Tuple[Dict[str, Any], Dict[str, Any]]:

ki_manager-2.3.2.dev2/src/ki_manager/workflows/agent-rules.md

@@ -0,0 +1,152 @@
+---
+name: ki-manager-agent-rules
+description: Recommendations and reference snippets for configuring project-level AI instruction files (AGENTS.md, CLAUDE.md, .cursorrules) with ki-manager
+metadata:
+  author: ki-manager
+  version: "1.0"
+<!-- if-compact -->
+allowed-tools: ki_instructions ki_read ki_search ki_tools ki_call ki_mutate
+<!-- else-compact -->
+allowed-tools: ki_instructions ki_read sync_agents_md
+<!-- /if-compact -->
+---
+
+# /agent-rules — AI Rules & Guidelines for Project Harnesses (AGENTS.md, CLAUDE.md, IDE Rules)
+
+> [!IMPORTANT]
+> **Purpose of this Document**:
+> This document is **NOT a system file or magical hook** that automatically or invisibly directs AI agent behavior by its mere presence.
+> Rather, it is a **reference guide and collection of actionable snippets and recommendations** for developers and agents to configure project-level instruction files defined in the project harness (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.windsurfrules`).
+> Its goal is to ensure external AI agents understand the `ki-manager` architecture and use the available tools properly.
+
+---
+
+## 1. Knowledge Base Directory Layout
+
+Every AI agent working with the repository must distinguish between the **system container** and the **knowledge items directory**:
+
+```
+<project_root>/
+├── {{KI_DIR}}/                 ← SYSTEM CONTAINER (like .git/ for Git)
+│   ├── config.json             ← Environment config (Python venv path, etc.)
+│   ├── ki_config.json          ← Knowledge base configuration (knowledge_root: "{{KI_DIR}}")
+│   ├── doc_config.json         ← Manifest and registry of tracked modules & KIs
+│   ├── DIR_INDEX.md            ← Auto-generated project directory tree
+│   ├── coverage_matrix.md      ← Coverage audit report (generated by audit_coverage)
+│   ├── knowledge/              ← STRICTLY ALL Knowledge Items (*.ki.md) live HERE!
+│   │   ├── _OVERVIEW.ki.md     ← High-level project architecture stub (DO NOT DELETE!)
+│   │   └── <module>.ki.md      ← Knowledge Items for individual modules
+│   └── decisions/              ← Architecture Decision Records (*.md ADRs)
+├── AGENTS.md                   ← Instructions for Antigravity & general AI agents in harness
+└── CLAUDE.md                   ← Instructions for Claude Code / Anthropic
+```
+
+> [!CAUTION]
+> **Common Agent Pitfalls:**
+> 1. **`knowledge_root: "{{KI_DIR}}"` points to the root of the system container, NOT the folder for `.ki.md` files.**
+>    NEVER write `*.ki.md` files directly into the root of `{{KI_DIR}}/`.
+> 2. **NEVER delete `{{KI_DIR}}/knowledge/`!**
+>    The initial `_OVERVIEW.ki.md` (~640 bytes) is NOT a stale duplicate. It is the initial bootstrap stub created for enrichment. Deleting `knowledge/` breaks all analysis and scaffolding tools (`audit_coverage`, `analyze_dependencies`, `ki_scaffold`, `finalize_ki_scaffolds`).
+
+---
+
+## 2. Reference Snippet for `AGENTS.md` (Antigravity & General AI Agents)
+
+Add the following block to your project's `AGENTS.md` (or use `sync_agents_md` to keep tables synchronized):
+
+```markdown
+# AI Agent Guidelines (AGENTS.md)
+
+This project uses **ki-manager** (an MCP server for architectural knowledge management).
+
+## Knowledge Base Architecture
+- System container: `{{KI_DIR}}/`
+- Knowledge Items (KIs): strictly inside `{{KI_DIR}}/knowledge/*.ki.md`
+- Architecture Decision Records (ADRs): in `{{KI_DIR}}/decisions/*.md` (or `decisions/`)
+- Project overview & entry point: `{{KI_DIR}}/knowledge/_OVERVIEW.ki.md`
+- Project directory tree: `{{KI_DIR}}/DIR_INDEX.md`
+
+## Agent Operating Rules
+1. **Context Before Changes**:
+   - Inspect `{{KI_DIR}}/knowledge/_OVERVIEW.ki.md` first.
+   - Read relevant module KIs via `ki_read(rel_path="...")` or `read_know_file` before writing code.
+   - List read KIs and architectural constraints in your Implementation Plan.
+2. **File Safety**:
+   - NEVER delete `{{KI_DIR}}/knowledge/` and never save `.ki.md` files directly in `{{KI_DIR}}/` root.
+   - Use `ki-manager` tools (`write_know_file`, `edit_know_file`) rather than generic filesystem tools when modifying documentation.
+3. **Synchronization**:
+   - When modifying module logic, update the corresponding KI and run `sync_agents_md`.
+
+## Knowledge Items
+<!-- Auto-synchronized by sync_agents_md -->
+| File | Topic / Summary |
+|------|-----------------|
+| `_OVERVIEW.ki.md` | Project overview |
+
+## Architecture Decision Records (ADRs)
+<!-- Auto-synchronized by sync_agents_md -->
+```
+
+---
+
+## 3. Reference Snippet for `CLAUDE.md` (Claude Code / Anthropic)
+
+Add the following block to your project's `CLAUDE.md`:
+
+```markdown
+# Project Guidelines for Claude Code
+
+This project uses `ki-manager` MCP server for knowledge management.
+
+## Knowledge Base Architecture
+- System container: `{{KI_DIR}}/`
+- Knowledge Items (KIs): strictly inside `{{KI_DIR}}/knowledge/*.ki.md`
+- Architecture Decision Records (ADRs): inside `{{KI_DIR}}/decisions/*.md`
+- Project overview: `{{KI_DIR}}/knowledge/_OVERVIEW.ki.md`
+
+## Core Protocols
+- **Always read context first**: Check `{{KI_DIR}}/knowledge/_OVERVIEW.ki.md` and relevant KIs before implementing changes.
+- **Never mutate container root**: Do NOT write `*.ki.md` directly into `{{KI_DIR}}/`. Never delete `{{KI_DIR}}/knowledge/`.
+- **Tooling**: Prefer MCP tools (`ki_read`, `ki_search`, `write_know_file`) when inspecting or updating documentation.
+- **Verification**: Run tests via project virtual environment (`.venv`).
+```
+
+---
+
+## 4. Reference Snippet for Cursor (`.cursorrules` or `.cursor/rules/ki-manager.mdc`)
+
+```markdown
+---
+description: Rules for navigating and updating ki-manager knowledge base
+globs: ["**/*"]
+alwaysApply: true
+---
+
+# ki-manager Integration Rules
+
+- Project architecture is documented via Knowledge Items (KIs) located in `{{KI_DIR}}/knowledge/`.
+- Start exploring codebase with `{{KI_DIR}}/knowledge/_OVERVIEW.ki.md` and `{{KI_DIR}}/DIR_INDEX.md`.
+- When writing or updating documentation, always keep `*.ki.md` files inside `{{KI_DIR}}/knowledge/`.
+- Do NOT delete or modify the container directory structure (`{{KI_DIR}}/`).
+```
+
+---
+
+## 5. Tooling Interaction
+
+Depending on the active `--tool-mode` of the `ki-manager` MCP server, use the corresponding tools:
+
+<!-- if-compact -->
+- **Search documentation**: `ki_search(query="<keywords>")`
+- **Read KI or ADR**: `ki_read(rel_path="<filename>.ki.md")`
+- **Inspect tool catalog**: `ki_tools()`
+- **Coverage audit**: `ki_call(tool="audit_coverage")`
+- **Write / update KI**: `ki_mutate(tool="write_know_file", args={"rel_path": "<name>.ki.md", "content": "..."})`
+- **Sync AGENTS.md**: `ki_mutate(tool="sync_agents_md")`
+<!-- else-compact -->
+- **Search documentation**: `ki_search(query="<keywords>")`
+- **Read KI or ADR**: `ki_read(rel_path="<filename>.ki.md")` or `read_know_file(rel_path="<filename>.ki.md")`
+- **Coverage audit**: `audit_coverage()`
+- **Write / update KI**: `write_know_file(rel_path="<name>.ki.md", content="...")`
+- **Sync AGENTS.md**: `sync_agents_md()`
+<!-- /if-compact -->

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/workflows/expand-knowledge.md

@@ -54,7 +54,9 @@ Select **one** target with the highest priority in the following order:
 
 ## Safety & Tooling Rules (Mandatory)
 > [!IMPORTANT]
-> When working with this workflow, it is **STRICTLY PROHIBITED** to use general file editing tools (e.g., `filesystem.edit_file`) for files inside the <knowledge_root> directory.
+> - `{{KI_DIR}}` (knowledge_root) is the system container. All Knowledge Items (`*.ki.md`) live strictly in `{{KI_DIR}}/knowledge/`.
+> - **NEVER** write `.ki.md` files directly into `{{KI_DIR}}/` root, and **NEVER** delete `{{KI_DIR}}/knowledge/`.
+> - When working with this workflow, it is **STRICTLY PROHIBITED** to use general file editing tools (e.g., `filesystem.edit_file`) for files inside the `{{KI_DIR}}` directory.
 > 
 <!-- if-compact -->
 > You **MUST** use the following MCP tools from the `ki-manager` server:
@@ -94,7 +96,7 @@ Select **one** target with the highest priority in the following order:
 
 ## Step 4 — Create or Update a KI File
 
-Write the file using `write_know_file` or `edit_know_file`:
+Write the file using `write_know_file` or `edit_know_file` (passing `rel_path="<filename>.ki.md"` automatically writes inside `{{KI_DIR}}/knowledge/`):
 <!-- if-compact -->
 // turbo
 `ki_mutate(tool="write_know_file", args={"rel_path": "<filename>.ki.md", "content": "..."})`

{ki_manager-2.3.1.dev1 → ki_manager-2.3.2.dev2}/src/ki_manager/workflows/scaffold-knowledge.md

@@ -135,6 +135,10 @@ Replace the stub with the enriched version:
 `write_know_file(rel_path="<filename>.ki.md", content="...")`
 <!-- /if-compact -->
 
+> [!NOTE]
+> All Knowledge Items live in `{{KI_DIR}}/knowledge/`. Calling `write_know_file(rel_path="<filename>.ki.md", ...)` automatically targets `{{KI_DIR}}/knowledge/<filename>.ki.md`.
+> **Never** write `.ki.md` files to the root of `{{KI_DIR}}/`, and **never** delete `{{KI_DIR}}/knowledge/` (including `_OVERVIEW.ki.md`, which is the project bootstrap stub).
+
 > [!IMPORTANT]
 > The **first line must be `<!-- scaffold: enriched -->`**. This marker tells `ki_finalize_scaffolds` to process the file in Phase 3 (clean markers, update doc_config summary). The `Related KIs` section is left empty — it will be populated automatically in Phase 3.
 

ki_manager-2.3.1.dev1/src/ki_manager/scripts/find_unmapped_files.py

@@ -1,101 +0,0 @@
-import os
-import sys
-import argparse
-import json
-from pathlib import Path
-from typing import List
-
-# Add path to ki_utils
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-import ki_utils
-
-def get_unmapped_files(target_path: str = ".") -> List[str]:
-    """Returns a sorted list of unmapped files relative to project root."""
-    project_root = ki_utils.get_project_root()
-    doc_config = ki_utils.get_doc_config()
-
-    if not project_root or not doc_config:
-        return []
-
-    # 1. Collect all files that are already mapped in doc_config.json
-    mapped_paths = set()
-    knowledge_items = doc_config.get("knowledge_items", {})
-
-    for ki in knowledge_items.values():
-        depends_on = ki.get("depends_on", [])
-        for p in depends_on:
-            abs_p = os.path.abspath(os.path.join(project_root, p))
-            mapped_paths.add(abs_p)
-
-    # 2. Scan the target directory
-    abs_target = os.path.abspath(os.path.join(project_root, target_path))
-    if not ki_utils.is_subpath(abs_target, project_root):
-        return []
-    if not os.path.exists(abs_target):
-        return []
-
-    unmapped = []
-    ignored_exts = {'.pyc', '.pyo', '.pyd', '.obj', '.dll', '.exe', '.bin'}
-    exclude_patterns = ki_utils.get_exclude_patterns()
-
-    for root, dirs, files in os.walk(abs_target):
-        dirs[:] = [
-            d for d in dirs
-            if not d.startswith(".")
-            and not ki_utils.should_exclude(d, os.path.relpath(os.path.join(root, d), project_root), exclude_patterns)
-        ]
-
-        for f in files:
-            if f.startswith(".") or any(f.endswith(ext) for ext in ignored_exts):
-                continue
-
-            full_path = os.path.abspath(os.path.join(root, f))
-            rel_to_project = os.path.relpath(full_path, project_root).replace("\\", "/")
-            if ki_utils.should_exclude(f, rel_to_project, exclude_patterns):
-                continue
-
-            if full_path in mapped_paths:
-                continue
-
-            is_parent_mapped = False
-            for mapped in mapped_paths:
-                if os.path.isdir(mapped):
-                    if full_path.startswith(os.path.join(mapped, "")):
-                        is_parent_mapped = True
-                        break
-
-            if not is_parent_mapped:
-                unmapped.append(rel_to_project)
-
-    return sorted(unmapped)
-
-
-def find_unmapped_files(target_path: str):
-    project_root = ki_utils.get_project_root()
-    doc_config = ki_utils.get_doc_config()
-
-    if not project_root or not doc_config:
-        print("Error: Could not resolve project root or doc_config.json")
-        return
-
-    abs_target = os.path.abspath(os.path.join(project_root, target_path))
-    if not os.path.exists(abs_target):
-        print(f"Error: Target path '{target_path}' does not exist.")
-        return
-
-    unmapped = get_unmapped_files(target_path)
-    if unmapped:
-        print(f"### Unmapped Files in '{target_path}':")
-        for f in unmapped:
-            print(f"- {f}")
-    else:
-        print(f"All files in '{target_path}' are already mapped in doc_config.json.")
-
-if __name__ == "__main__":
-    if sys.platform == "win32":
-        sys.stdout.reconfigure(encoding="utf-8")
-    parser = argparse.ArgumentParser(description="Find files in a directory not covered by any KI in doc_config.json")
-    parser.add_argument("path", help="Relative path from project root to scan")
-    args = parser.parse_args()
-    
-    find_unmapped_files(args.path)