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

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

@@ -9,6 +9,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ki-manager
-Version: 2.3.2.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.2.dev1 → ki_manager-2.3.2.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ki-manager"
-version = "2.3.2.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.2.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.2.dev1"
+__version__ = "2.3.2.dev2"

{ki_manager-2.3.2.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.2.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)
@@ -500,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.2.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.2.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.2.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.2.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.