ki-manager 2.3.0.dev3__tar.gz → 2.3.1.dev1__tar.gz

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/.gitignore

@@ -29,3 +29,6 @@ posts/
 
 # Private plans (moved to KI-enterprise)
 plans/
+
+# Agent/MCP state
+.serena/

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/CHANGELOG.md

@@ -9,7 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.3.0.dev3] — 2026-10-09
+## [2.3.1.dev1] — 2026-10-16
+
+### 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.
+- **Secured Git Operations (`git_diff_secured`)**: Added hardened diff inspection tool protecting against flag injection (`--output`, etc.), shell command chaining, and repository boundary escapes.
+- **Restricted File Modifications**: Extended write protection to block direct modifications of shell/executable scripts (`.sh`, `.bash`, `.zsh`, `.js`, `.ts`, `.vbs`, `.wsf`) and internal system state files (`doc_config.json`, `ki_config.json`, `config.json`, `doc_state.json`) via direct file editing tools.
+
+### Changed
+- **Unified Tool Dispatch Schema**: In compact facade mode, dynamically bind `ki_call` and `ki_mutate` tool validation schemas (`enum` and `description`) directly to tool `readOnlyHint` annotations, eliminating dispatch conflicts and preventing model confusion.
+- **Date Format Resilience in `update_last_verified`**: Extended `update_last_verified` to automatically detect and update all supported date notation variants (HTML comment `<!-- last_verified: YYYY-MM-DD -->`, YAML frontmatter `last_verified: "YYYY-MM-DD"`, and Markdown bold `**Last verified**: YYYY-MM-DD`), and automatically insert the verification tag if missing.
+- **Workflow Instructions Alignment**: Synchronized tool arguments and signatures across `/expand-knowledge` and `/sync-knowledge` instructions, ensuring seamless execution in both compact facade and full tool modes.
+- **Daily MCP Log Rotation**: Server diagnostics now rotate daily (`mcp_YYYY-MM-DD.log`) with payload truncation to prevent runaway disk usage during high-frequency sessions.
+
+## [2.3.0] — 2026-10-11
+
+### Added
+- **Unified Cascade Path Resolution (`resolve_know_path`)**: `read_know_file`, `write_know_file`, and `edit_know_file` now share `ki_read`'s smart cascade resolver. AI agents can access and edit Knowledge Items using flat basenames (e.g. `KI_data_persistence.md`) without requiring explicit `knowledge/` directory prefixes.
+- **Smart Directory Placement for New KIs**: `write_know_file` now updates existing files in place across `knowledge/` rather than creating duplicates in the sandbox root, and automatically routes newly created flat KI files (`KI_*.md`, `*.ki.md`) into `<jail>/knowledge/`.
+- **ADR Name & Prefix Tolerance**: `resolve_know_path` and `ki_read` gracefully handle variations with or without `ADR_`/`adr_`/`ADR-` prefixes (e.g., resolving `ADR_002_node_status_queue_and_ui_feedback.md` to `002_node_status_queue_and_ui_feedback.md`) as well as numeric ADR IDs.
+- **Accurate Document Listings**: `get_ki_list_table()` dynamically reconciles registered entries in `doc_config.json` against filesystem reality, outputting exact on-disk filenames in document overviews.
+- **Comprehensive Project Overview**: `ki_instructions(document="knowledge-items")`, prompts, and `ki://knowledge-items.md` now present both Knowledge Items and Architecture Decision Records (ADRs) tables together when ADRs exist.
+
+### Highlights from 2.3.0 Development Cycle
+- Compact Facade Mode (`--tool-mode compact`) reducing MCP tools footprint from 34 schemas to 6 tools (`ki_instructions`, `ki_search`, `ki_read`, `ki_tools`, `ki_call`, `ki_mutate`), saving thousands of context tokens.
+- Native BM25 search engine (`ki_search`) with bilingual EN/RU stemming and field-weighted ranking.
+- Token-efficient reader with section filtering and character offset pagination (`ki_read`, `read_know_file`).
+- Batch ADR superseding (`create_adr`) with automatic status transitions, warning banners, git/environment snapshots, and quality sections (`rejected_alternatives`, `invariants`, `verification`).
+- Automated drift analysis (`check_ki_drift`) and Python AST pre-enrichment during scaffolding.
 
 ### Added
 - `create_adr` batch `supersedes` support: accept a list of previous ADR IDs (`supersedes: ["001", "002"]`) to supersede multiple older records simultaneously; automatically updates deprecated ADR files with warning banners and `Superseded by ADR XXX` statuses, updates `doc_config.json`, and embeds bi-directional cross-links in the generated ADR.

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/PKG-INFO

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

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

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/__init__.py

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

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/analyze_module.py

@@ -32,6 +32,9 @@ def analyze_path(target_path: str, recursive: bool = False):
     
     # Resolve absolute path
     abs_target = os.path.normpath(os.path.join(project_root, target_path))
+    if not ki_utils.is_subpath(abs_target, project_root):
+        print(f"Error: Path '{target_path}' escapes project root.")
+        return
 
     if not os.path.exists(abs_target):
         print(f"Error: Path {target_path} not found.")

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/audit_coverage.py

@@ -65,7 +65,7 @@ def load_ki_files() -> list:
     ki_dir = os.path.join(get_knowledge_root(), "knowledge")
     if not os.path.isdir(ki_dir):
         return []
-    return [f for f in os.listdir(ki_dir) if f.startswith("KI_") and f.endswith(".md")]
+    return [f for f in os.listdir(ki_dir) if ki_utils.is_ki_filename(f)]
 
 
 # ─── Metrics ──────────────────────────────────────────────────────────────────

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/check_ki_drift.py

@@ -286,7 +286,7 @@ def run_drift_check(
         return [check_single_ki(target_name, target_path, doc_config, project_root, knowledge_dir)]
 
     results = []
-    for f in sorted(knowledge_dir.glob("KI_*.md")):
+    for f in sorted(f for f in knowledge_dir.glob("*.md") if ki_utils.is_ki_filename(f.name)):
         results.append(check_single_ki(f.name, f, doc_config, project_root, knowledge_dir))
 
     return results

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/finalize_ki_scaffolds.py

@@ -70,7 +70,7 @@ def finalize_scaffolds(dry_run: bool = False) -> None:
     skipped_clean = 0
 
     for fname in sorted(os.listdir(ki_dir)):
-        if not (fname.startswith("KI_") and fname.endswith(".md")):
+        if not ki_utils.is_ki_filename(fname):
             continue
 
         ki_path = os.path.join(ki_dir, fname)

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/find_unmapped_files.py

@@ -29,6 +29,8 @@ def get_unmapped_files(target_path: str = ".") -> List[str]:
 
     # 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 []
 

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/generate_ki_scaffolds.py

@@ -514,7 +514,7 @@ def print_scaffold_status() -> None:
     enriched_count = 0
     
     for fname in sorted(os.listdir(ki_dir)):
-        if not (fname.startswith("KI_") and fname.endswith(".md")):
+        if not ki_utils.is_ki_filename(fname):
             continue
             
         ki_path = os.path.join(ki_dir, fname)

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

@@ -0,0 +1,81 @@
+"""
+git_diff_secured.py
+
+Safely runs git status and git diff for project files within the project sandbox.
+Prevents argument/flag injection and path traversal.
+"""
+
+import os
+import sys
+import argparse
+import subprocess
+from pathlib import Path
+from typing import List
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ki_utils
+
+
+def git_diff_secured(paths: List[str] = None) -> str:
+    project_root = ki_utils.get_project_root()
+    if not project_root or not os.path.exists(project_root):
+        return "Error: No active project context."
+
+    safe_paths = []
+    if paths:
+        for p in paths:
+            clean_p = p.strip()
+            if not clean_p:
+                continue
+            if clean_p.startswith("-") or any(char in clean_p for char in [";", "|", "&", ">", "<", "`"]):
+                return f"Error: Suspicious argument or path '{clean_p}'."
+            abs_p = os.path.abspath(os.path.join(project_root, clean_p))
+            if not ki_utils.is_subpath(abs_p, project_root):
+                return f"Access Denied: Path '{clean_p}' escapes project root."
+            safe_paths.append(os.path.relpath(abs_p, project_root).replace("\\", "/"))
+
+    try:
+        if safe_paths:
+            stat_cmd = ["git", "status", "--short", "--"] + safe_paths
+            diff_cmd = ["git", "diff", "HEAD", "--"] + safe_paths
+        else:
+            stat_cmd = ["git", "status", "--short"]
+            diff_cmd = ["git", "diff", "HEAD"]
+
+        stat_res = subprocess.run(
+            stat_cmd, cwd=project_root, capture_output=True, text=True, encoding="utf-8"
+        )
+        diff_res = subprocess.run(
+            diff_cmd, cwd=project_root, capture_output=True, text=True, encoding="utf-8"
+        )
+
+        output = []
+        if stat_res.stdout.strip():
+            output.append("### Git Status:\n" + stat_res.stdout.strip())
+        if diff_res.stdout.strip():
+            output.append("### Git Diff:\n" + diff_res.stdout.strip())
+        if not output:
+            output.append("No changes detected in git.")
+
+        return "\n\n".join(output)
+    except Exception as e:
+        return f"Git execution error: {str(e)}"
+
+
+def main():
+    if sys.platform == "win32":
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+    parser = argparse.ArgumentParser(description="Secured git diff for project files.")
+    parser.add_argument("paths", nargs=argparse.REMAINDER, help="File or directory paths relative to project root")
+    args = parser.parse_args()
+
+    result = git_diff_secured(args.paths)
+    print(result)
+
+
+if __name__ == "__main__":
+    main()

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/ki_search.py

@@ -218,7 +218,7 @@ def search_knowledge(
         return {"error": "No project root found. Run ki_init_project or specify workspace.", "results": []}
 
     knowledge_root = ki_utils.get_knowledge_root()
-    if not knowledge_root or not os.path.exists(knowledge_root) or not os.path.normcase(os.path.abspath(knowledge_root)).startswith(os.path.normcase(os.path.abspath(project_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 [
             os.path.join(project_root, ".ki-base", "knowledge"),
             os.path.join(project_root, "knowledge"),

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/ki_utils.py

@@ -58,6 +58,28 @@ def normalize_path(path_str: str, make_absolute: bool = True) -> str:
     return path_str
 
 
+def is_subpath(target: str, root: str) -> bool:
+    """Checks whether target path is strictly within or equal to root directory."""
+    if not target or not root:
+        return False
+    try:
+        norm_t = os.path.normcase(os.path.abspath(target))
+        norm_r = os.path.normcase(os.path.abspath(root))
+        return os.path.commonpath([norm_t, norm_r]) == norm_r
+    except (ValueError, OSError):
+        return False
+
+
+def is_ki_filename(name: str, include_overview: bool = False) -> bool:
+    """Checks if a file name matches Knowledge Item convention (KI_*.md or *.ki.md)."""
+    if not name or not name.endswith(".md"):
+        return False
+    base = os.path.basename(name)
+    if not include_overview and base in ("_OVERVIEW.ki.md", "_OVERVIEW.md"):
+        return False
+    return base.startswith("KI_") or base.endswith(".ki.md")
+
+
 # ─── Registry Management ─────────────────────────────────────────────────────
 
 def get_registry_path() -> Path:
@@ -139,7 +161,7 @@ def find_project_by_cwd(cwd=None) -> dict:
 
     for proj_root, data in registry["projects"].items():
         norm_proj = normalize_path(proj_root)
-        if os.path.normcase(cwd).startswith(os.path.normcase(norm_proj)):
+        if is_subpath(cwd, norm_proj):
             if len(norm_proj) > max_len:
                 max_len = len(norm_proj)
                 best_match = data
@@ -409,10 +431,30 @@ def get_ki_list_table() -> str:
     items = doc_config.get("knowledge_items", {})
     if not items:
         return "No Knowledge Items registered yet."
+    jail = get_knowledge_root()
+    proj = get_project_root()
+    dec_dirs = get_decisions_dirs(proj, jail)
+
     rows = ["| File | Topic / Summary |", "|------|-----------------|"]
     for name, info in sorted(items.items()):
         summary = info.get("summary", info.get("description", "—"))
-        rows.append(f"| `{name}` | {summary} |")
+        display_name = name
+        if "path" in info and info["path"]:
+            display_name = info["path"]
+        elif jail or proj:
+            # Check if name exists literally
+            exists_literal = False
+            for root_cand in ([jail] if jail else []) + dec_dirs:
+                if os.path.exists(os.path.join(root_cand, name)) or os.path.exists(os.path.join(root_cand, "knowledge", name)):
+                    exists_literal = True
+                    break
+            if not exists_literal and re.match(r"^(?:ADR|adr)[_\-]", name):
+                stripped = re.sub(r"^(?:ADR|adr)[_\-]", "", name)
+                for d in dec_dirs:
+                    if os.path.exists(os.path.join(d, stripped)):
+                        display_name = stripped
+                        break
+        rows.append(f"| `{display_name}` | {summary} |")
     return "\n".join(rows)
 
 

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/knowledge_engine.py

@@ -201,11 +201,11 @@ class KnowledgeEngine:
         if not knowledge_dir.exists():
             return "Knowledge directory not found"
 
-        path_pattern = re.compile(r"`((?:app|ui|extensions|\.know|\.agent|scripts|tests)/[a-zA-Z0-9_\-\./]+)`")
+        path_pattern = re.compile(r"`([a-zA-Z0-9_\-\.]+/[a-zA-Z0-9_\-\./]+)`")
         
         updated_count = 0
         for filename in os.listdir(knowledge_dir):
-            if not filename.endswith(".md"):
+            if not ki_utils.is_ki_filename(filename, include_overview=True):
                 continue
                 
             ki_path = knowledge_dir / filename
@@ -215,8 +215,9 @@ class KnowledgeEngine:
             mentioned = path_pattern.findall(content)
             valid_paths = set()
             for p in mentioned:
-                p = p.rstrip(".,")
-                if (self.project_root / p).exists():
+                p = p.rstrip(".,;:)")
+                target_file = (self.project_root / p).resolve()
+                if ki_utils.is_subpath(str(target_file), str(self.project_root)) and target_file.exists():
                     valid_paths.add(p.replace("\\", "/"))
 
             if filename not in ki_items:

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/sync_agents_md.py

@@ -16,12 +16,16 @@ import ki_utils
 
 
 def resolve_agents_path(agents_path: str = None) -> str:
-    """Finds the AGENTS.md file in the project."""
     if agents_path:
         p = ki_utils.normalize_path(agents_path)
-        if os.path.exists(p):
-            return p
-        return p  # let caller handle not found
+        pr = ki_utils.get_project_root()
+        kr = ki_utils.get_knowledge_root()
+        allowed = [pr] if pr else []
+        if kr and kr not in allowed:
+            allowed.append(kr)
+        if allowed and not any(ki_utils.is_subpath(p, r) for r in allowed):
+            return ""
+        return p
 
     pr = ki_utils.get_project_root()
     kr = ki_utils.get_knowledge_root()

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/server.py

@@ -13,6 +13,7 @@ Usage:
 import sys
 import json
 import os
+import re
 import subprocess
 import importlib.metadata
 from pathlib import Path
@@ -46,7 +47,11 @@ _LOG_DIR = Path.home() / ".ki_base" / "logs"
 def safe_log(msg: str):
     try:
         _LOG_DIR.mkdir(parents=True, exist_ok=True)
-        log_file = _LOG_DIR / f"mcp_{os.getpid()}.log"
+        import datetime
+        today_str = datetime.date.today().isoformat()
+        log_file = _LOG_DIR / f"mcp_{today_str}.log"
+        if len(msg) > 2000:
+            msg = msg[:1997] + "..."
         with open(log_file, "a", encoding="utf-8") as lf:
             lf.write(msg + "\n")
     except Exception:
@@ -114,15 +119,20 @@ def get_adr_list(project_root: str, jail: str) -> str:
 
 # ─── Security ─────────────────────────────────────────────────────────────────
 
-_FORBIDDEN_WRITE_EXT = {".py", ".pyc", ".bat", ".ps1", ".sh", ".exe", ".cmd", ".dll"}
-_FORBIDDEN_WRITE_FILES = {"doc_config.json"}  # can only be modified via dedicated tools
+_FORBIDDEN_WRITE_EXT = {
+    ".py", ".pyc", ".bat", ".ps1", ".sh", ".exe", ".cmd", ".dll",
+    ".js", ".mjs", ".cjs", ".ts", ".vbs", ".wsf", ".bash", ".zsh"
+}
+_FORBIDDEN_WRITE_FILES = {
+    "doc_config.json", "ki_config.json", "config.json", "doc_state.json"
+}  # can only be modified via dedicated tools
 
 NO_WORKSPACE_ERROR = {
     "isError": True,
     "content": [{
         "type": "text",
         "text": (
-            "❌ No active workspace detected.\n\n"
+            "✖ No active workspace detected.\n\n"
             "To fix, call ki_status with explicit path:\n"
             "  ki_status({\"path\": \"/absolute/path/to/project\"})\n\n"
             "Or ensure the MCP client passes workspaceUri in _meta.io.modelcontextprotocol/clientInfo."
@@ -135,7 +145,7 @@ def validate_path(rel_path: str, is_write: bool = False) -> str:
     jail = get_jail_dir()
     if not jail:
         raise PermissionError(
-            "❌ No active workspace detected. "
+            "✖ No active workspace detected. "
             "Call ki_status({\"path\": \"/absolute/path/to/project\"}) to set it."
         )
 
@@ -147,7 +157,7 @@ def validate_path(rel_path: str, is_write: bool = False) -> str:
     else:
         target = os.path.abspath(normalized)
 
-    if not os.path.normcase(target).startswith(os.path.normcase(jail)):
+    if not ki_utils.is_subpath(target, jail):
         raise PermissionError("Access Denied: jail breach detected.")
 
     if is_write:
@@ -155,11 +165,180 @@ def validate_path(rel_path: str, is_write: bool = False) -> str:
         if ext in _FORBIDDEN_WRITE_EXT:
             raise PermissionError(f"Access Denied: modifying {ext} files is forbidden.")
         if os.path.basename(target).lower() in _FORBIDDEN_WRITE_FILES:
-            raise PermissionError(f"Access Denied: use dedicated tools to modify this file.")
+            raise PermissionError("Access Denied: use dedicated tools to modify this file.")
 
     return target
 
 
+def resolve_know_path(rel_path: str, is_write: bool = False, must_exist: bool = False) -> str:
+    """
+    Resolves a relative knowledge/ADR path using smart cascading, security validation,
+    and tolerance for prefixes like 'ADR_'.
+
+    If must_exist is True: raises FileNotFoundError if not found.
+    If must_exist is False and file doesn't exist: returns the target creation path
+    (defaulting flat KI files to <jail>/knowledge/<norm>).
+    """
+    jail = get_jail_dir()
+    if not jail:
+        raise PermissionError(
+            "✖ No active workspace detected. "
+            "Call ki_status({\"path\": \"/absolute/path/to/project\"}) to set it."
+        )
+
+    norm = ki_utils.normalize_path(rel_path, make_absolute=False)
+    if not norm:
+        raise ValueError("rel_path cannot be empty.")
+
+    if not os.path.isabs(norm) and norm.startswith(".."):
+        raise PermissionError(f"Access Denied: path '{rel_path}' escapes sandbox.")
+
+    project_root = get_project_root()
+    base_name = os.path.basename(norm)
+    dir_name = os.path.dirname(norm)
+
+    # Name variants (tolerance for ADR_ / adr_ prefixes)
+    name_variants = [base_name]
+    m_adr = re.match(r"^(?:ADR|adr)[_\-](.*)", base_name)
+    if m_adr:
+        name_variants.append(m_adr.group(1))
+    elif re.match(r"^\d+", base_name):
+        name_variants.append(f"ADR_{base_name}")
+        name_variants.append(f"adr_{base_name}")
+
+    target = None
+
+    # 1. Direct path inside jail
+    try:
+        cand = validate_path(norm)
+        if os.path.exists(cand) and os.path.isfile(cand):
+            target = cand
+    except Exception:
+        target = None
+
+    # 1b. If base_name had ADR_ prefix, try direct path with stripped name in same directory inside jail
+    if not target and m_adr and dir_name:
+        try:
+            cand = validate_path(os.path.join(dir_name, m_adr.group(1)))
+            if os.path.exists(cand) and os.path.isfile(cand):
+                target = cand
+        except Exception:
+            target = None
+
+    # 2. Inside jail/knowledge/ (standard structure: <jail>/knowledge/<file>)
+    if not target and jail:
+        for nv in name_variants:
+            sub = os.path.join(dir_name, nv) if dir_name else nv
+            try:
+                cand = validate_path(os.path.join("knowledge", sub))
+                if os.path.exists(cand) and os.path.isfile(cand):
+                    target = cand
+                    break
+            except Exception:
+                pass
+
+    # 3. If rel_path starts with the knowledge_root folder name itself (e.g. '.ki-base/...' or 'knowledge/...'),
+    # strip prefix and resolve inside jail
+    if not target and jail and project_root:
+        rel_to_proj = os.path.relpath(jail, project_root).replace("\\", "/")
+        if norm.startswith(rel_to_proj + "/"):
+            sub_path = norm[len(rel_to_proj) + 1:]
+            try:
+                cand = validate_path(sub_path)
+                if os.path.exists(cand) and os.path.isfile(cand):
+                    target = cand
+            except Exception:
+                pass
+            if not target:
+                try:
+                    cand = validate_path(os.path.join("knowledge", sub_path))
+                    if os.path.exists(cand) and os.path.isfile(cand):
+                        target = cand
+                except Exception:
+                    pass
+
+    # 4. Decisions directories (ADR resolution)
+    if not target and project_root:
+        candidates = ki_utils.get_decisions_dirs(project_root, jail)
+        for d in candidates:
+            if not os.path.exists(d):
+                continue
+            # Try by name variants
+            for nv in name_variants:
+                cand_p = os.path.abspath(os.path.join(d, nv))
+                if os.path.exists(cand_p) and cand_p.endswith(".md") and os.path.isfile(cand_p):
+                    target = cand_p
+                    break
+            if target:
+                break
+
+            # If still not found, match by ADR ID prefix (e.g. '002' or '2')
+            m_id = re.match(r"^(?:ADR[_\-]?)?(\d+)", base_name, re.IGNORECASE)
+            if m_id:
+                target_id = m_id.group(1)
+                for f in os.listdir(d):
+                    if f.endswith(".md"):
+                        m_f = re.match(r"^(?:ADR[_\-]?)?(\d+)", f, re.IGNORECASE)
+                        if m_f and (m_f.group(1) == target_id or m_f.group(1).lstrip("0") == target_id.lstrip("0")):
+                            target = os.path.abspath(os.path.join(d, f))
+                            break
+            if target:
+                break
+
+        # Also check relative to project root directly if within decisions or jail
+        if not target:
+            cand_p = os.path.abspath(os.path.join(project_root, norm))
+            if os.path.exists(cand_p) and cand_p.endswith(".md") and os.path.isfile(cand_p):
+                valid_prefixes = candidates + ([jail] if jail else [])
+                for vp in valid_prefixes:
+                    if os.path.normcase(cand_p).startswith(os.path.normcase(vp)):
+                        target = cand_p
+                        break
+
+    # 5. Fallback: Search by basename variants in jail and its subfolders
+    if not target and jail and os.path.exists(jail):
+        for root, _, files in os.walk(jail):
+            for nv in name_variants:
+                if nv in files:
+                    cand_p = os.path.abspath(os.path.join(root, nv))
+                    if cand_p.endswith(".md") and os.path.isfile(cand_p):
+                        target = cand_p
+                        break
+            if target:
+                break
+
+    # Security check on resolved existing target
+    if target:
+        valid_roots = [jail]
+        if project_root:
+            valid_roots.extend(ki_utils.get_decisions_dirs(project_root, jail))
+        is_safe = any(ki_utils.is_subpath(target, vr) for vr in valid_roots if vr)
+        if not is_safe:
+            raise PermissionError("Access Denied: jail breach detected.")
+
+        if is_write:
+            ext = os.path.splitext(target)[1].lower()
+            if ext in _FORBIDDEN_WRITE_EXT:
+                raise PermissionError(f"Access Denied: modifying {ext} files is forbidden.")
+            if os.path.basename(target).lower() in _FORBIDDEN_WRITE_FILES:
+                raise PermissionError("Access Denied: use dedicated tools to modify this file.")
+
+        return target
+
+    # Target not found
+    if must_exist:
+        raise FileNotFoundError(f"Knowledge file '{rel_path}' not found.")
+
+    # Target does not exist, but we are resolving path for creation (e.g. write_know_file)
+    # If path is flat (no dir specified) and jail has knowledge folder, default to knowledge/
+    if not dir_name:
+        know_dir = os.path.join(jail, "knowledge")
+        if os.path.exists(know_dir) or base_name.startswith("KI_") or base_name.endswith(".ki.md"):
+            return validate_path(os.path.join("knowledge", base_name), is_write=is_write)
+
+    return validate_path(norm, is_write=is_write)
+
+
 # ─── Script runner ────────────────────────────────────────────────────────────
 
 def run_script(script_name: str, args: List[str] = None) -> dict:
@@ -344,7 +523,7 @@ MCP_TOOLS = [
         "inputSchema": {"type": "object", "properties": {}},
         "annotations": {
             "title": "Generate Dir Index",
-            "readOnlyHint": False,
+            "readOnlyHint": True,
             "destructiveHint": False,
             "idempotentHint": True,
         },
@@ -361,7 +540,7 @@ MCP_TOOLS = [
         },
         "annotations": {
             "title": "Analyze Dependencies",
-            "readOnlyHint": False,
+            "readOnlyHint": True,
             "destructiveHint": False,
             "idempotentHint": True,
         },
@@ -372,7 +551,7 @@ MCP_TOOLS = [
         "inputSchema": {"type": "object", "properties": {}},
         "annotations": {
             "title": "Analyze All Dependencies",
-            "readOnlyHint": False,
+            "readOnlyHint": True,
             "destructiveHint": False,
             "idempotentHint": True,
         },
@@ -864,6 +1043,9 @@ MCP_TOOLS = [
     facade.KI_READ_TOOL,
 ]
 
+# Dynamically bind ki_call and ki_mutate schemas to readOnlyHint annotations
+facade.sync_dispatch_schemas(MCP_TOOLS)
+
 _INSTRUCTIONS_TOOL = next(t for t in MCP_TOOLS if t["name"] == "ki_instructions")
 COMPACT_TOOLS = [
     _INSTRUCTIONS_TOOL,
@@ -1455,82 +1637,12 @@ def tool_read_file(args: dict) -> Any:
     if not rel_path:
         return "Error: 'rel_path' is required."
 
-    project_root = get_project_root()
-    jail = get_jail_dir()
-
-    target = None
-    norm = ki_utils.normalize_path(rel_path, make_absolute=False)
-    base_name = os.path.basename(norm)
-
-    # 1. Try resolving within jail (knowledge root from config, default .ki-base)
-    if jail:
-        # 1a. Direct path inside jail
-        try:
-            cand = validate_path(norm)
-            if os.path.exists(cand) and os.path.isfile(cand):
-                target = cand
-        except Exception:
-            target = None
-
-        # 1b. Try inside jail/knowledge/ (standard structure: <jail>/knowledge/<file>)
-        if not target:
-            try:
-                cand = validate_path(os.path.join("knowledge", norm))
-                if os.path.exists(cand) and os.path.isfile(cand):
-                    target = cand
-            except Exception:
-                target = None
-
-        # 1c. If rel_path starts with the knowledge_root folder name itself (e.g. '.ki-base/...' or 'knowledge/...'),
-        # strip the prefix and resolve inside jail
-        if not target and project_root:
-            rel_to_proj = os.path.relpath(jail, project_root).replace("\\", "/")
-            if norm.startswith(rel_to_proj + "/"):
-                sub_path = norm[len(rel_to_proj) + 1:]
-                try:
-                    cand = validate_path(sub_path)
-                    if os.path.exists(cand) and os.path.isfile(cand):
-                        target = cand
-                except Exception:
-                    pass
-                if not target:
-                    try:
-                        cand = validate_path(os.path.join("knowledge", sub_path))
-                        if os.path.exists(cand) and os.path.isfile(cand):
-                            target = cand
-                    except Exception:
-                        pass
-
-    # 2. Try resolving ADR or path relative to project_root
-    if not target and project_root:
-        candidates = ki_utils.get_decisions_dirs(project_root, jail)
-        # Check by basename in decisions dirs
-        for d in candidates:
-            cand_p = os.path.abspath(os.path.join(d, base_name))
-            if os.path.exists(cand_p) and cand_p.endswith(".md") and os.path.isfile(cand_p):
-                target = cand_p
-                break
-        if not target:
-            # Check relative to project root, ensuring it is within decisions or jail
-            cand_p = os.path.abspath(os.path.join(project_root, norm))
-            if os.path.exists(cand_p) and cand_p.endswith(".md") and os.path.isfile(cand_p):
-                valid_prefixes = candidates + ([jail] if jail else [])
-                for vp in valid_prefixes:
-                    if os.path.normcase(cand_p).startswith(os.path.normcase(vp)):
-                        target = cand_p
-                        break
-
-    # 3. Fallback: Search by basename in jail (knowledge root) and its subfolders
-    if not target and jail and os.path.exists(jail):
-        for root, _, files in os.walk(jail):
-            if base_name in files:
-                cand_p = os.path.abspath(os.path.join(root, base_name))
-                if cand_p.endswith(".md") and os.path.isfile(cand_p):
-                    target = cand_p
-                    break
-
-    if not target or not os.path.exists(target):
+    try:
+        target = resolve_know_path(rel_path, must_exist=True)
+    except FileNotFoundError:
         return f"File not found: '{rel_path}'."
+    except Exception as e:
+        return f"Error: {e}"
 
     try:
         with open(target, "r", encoding="utf-8", errors="replace") as f:
@@ -1584,10 +1696,14 @@ def handle_tool_call(name: str, args: dict) -> Any:
             if doc == "overview":
                 return facade.render_instruction(GLOBAL_INSTRUCTIONS, CURRENT_TOOL_MODE, know_name)
             elif doc == "knowledge-items":
-                return f"Knowledge Items for this project:\n\n{ki_utils.get_ki_list_table()}"
+                ki_table = ki_utils.get_ki_list_table()
+                adr_table = ki_utils.get_adr_table()
+                if adr_table and not adr_table.startswith("No ADRs found"):
+                    return f"Knowledge Items for this project:\n\n{ki_table}\n\nArchitecture Decision Records (ADRs):\n\n{adr_table}"
+                return f"Knowledge Items for this project:\n\n{ki_table}"
             else:
-                wf_path = _WORKFLOWS_DIR / f"{doc}.md"
-                if wf_path.exists():
+                wf_path = (_WORKFLOWS_DIR / f"{doc}.md").resolve()
+                if ki_utils.is_subpath(str(wf_path), str(_WORKFLOWS_DIR)) and wf_path.exists():
                     with open(wf_path, "r", encoding="utf-8") as f:
                         raw = f.read()
                         return facade.render_instruction(raw, CURRENT_TOOL_MODE, know_name)
@@ -1604,15 +1720,19 @@ def handle_tool_call(name: str, args: dict) -> Any:
             from scaffold import init_project
             return init_project(args)
 
-        # ── Registry ──
+        # ─── Registry ───
         if name == "ki_migrate_project":
+            sys.path.insert(0, str(_PACKAGE_DIR / "tools"))
+            import scaffold
             return scaffold.migrate_project(str(get_project_root()))
         if name == "ki_register_project":
             config_path = args.get("config_path", "")
+            workspace = args.get("workspace")
+            inline_config = args.get("inline_config")
             # Accept directory too
             if config_path and os.path.isdir(ki_utils.normalize_path(config_path)):
                 config_path = os.path.join(ki_utils.normalize_path(config_path), "ki_config.json")
-            ok, msg = ki_utils.register_project(config_path)
+            ok, msg = ki_utils.register_project(config_path=config_path, workspace=workspace, inline_config=inline_config)
             return msg
         if name == "ki_list_projects":
             reg = ki_utils.load_registry()
@@ -1628,37 +1748,85 @@ def handle_tool_call(name: str, args: dict) -> Any:
         if name == "ki_prune_registry":
             reg = ki_utils.load_registry()
             before = len(reg["projects"])
-            reg["projects"] = {k: v for k, v in reg["projects"].items()
-                               if os.path.exists(v["config_path"])}
+            surviving = {}
+            for k, v in reg["projects"].items():
+                cfg_p = v.get("config_path")
+                if cfg_p and os.path.exists(cfg_p):
+                    surviving[k] = v
+                elif not cfg_p and os.path.exists(k):
+                    surviving[k] = v
+            reg["projects"] = surviving
             ki_utils.save_registry(reg)
             return f"Pruned {before - len(reg['projects'])} stale project(s)."
 
-        # ── Coverage / Analysis ──
+        # ─── Coverage / Analysis ───
         if name == "audit_coverage":
             return run_script("audit_coverage.py")
 
         if name == "generate_dir_index":
             return run_script("generate_dir_index.py")
         if name == "update_last_verified":
-            import datetime, glob, re as re_mod
+            import datetime
             jail = get_jail_dir()
-            if not jail: return "Error: No project."
+            if not jail:
+                return "Error: No project."
             today = datetime.datetime.now().strftime("%Y-%m-%d")
             count = 0
-            for filepath in glob.glob(os.path.join(jail, "knowledge", "*.md")):
-                with open(filepath, "r", encoding="utf-8") as f:
-                    content = f.read()
-                new_content = re_mod.sub(r'^(last_verified:\s*)"?\d{4}-\d{2}-\d{2}"?', rf'\g<1>"{today}"', content, flags=re_mod.MULTILINE)
-                if new_content != content:
-                    import tempfile
-                    fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(filepath), text=True)
-                    try:
-                        with os.fdopen(fd, "w", encoding="utf-8", newline="") as f:
-                            f.write(new_content)
-                        os.replace(tmp_path, filepath)
-                        count += 1
-                    except Exception:
-                        if os.path.exists(tmp_path): os.remove(tmp_path)
+            know_dir = os.path.join(jail, "knowledge")
+            if os.path.exists(know_dir):
+                for fname in os.listdir(know_dir):
+                    if not ki_utils.is_ki_filename(fname, include_overview=True):
+                        continue
+                    filepath = os.path.join(know_dir, fname)
+                    if not os.path.isfile(filepath):
+                        continue
+                    with open(filepath, "r", encoding="utf-8") as f:
+                        content = f.read()
+
+                    new_content = content
+                    new_content = re.sub(
+                        r'<!--\s*last_verified:\s*"?\d{4}-\d{2}-\d{2}"?\s*-->',
+                        f'<!-- last_verified: {today} -->',
+                        new_content,
+                        flags=re.IGNORECASE
+                    )
+                    new_content = re.sub(
+                        r'^(last_verified:\s*)"?\d{4}-\d{2}-\d{2}"?',
+                        rf'\g<1>"{today}"',
+                        new_content,
+                        flags=re.MULTILINE
+                    )
+                    new_content = re.sub(
+                        r'(\*\*Last verified\*\*:\s*)"?\d{4}-\d{2}-\d{2}"?',
+                        rf'\g<1>{today}',
+                        new_content,
+                        flags=re.IGNORECASE
+                    )
+
+                    if new_content == content:
+                        lines = content.splitlines(keepends=True)
+                        res_lines = []
+                        inserted = False
+                        for line in lines:
+                            res_lines.append(line)
+                            if not inserted and line.startswith("# "):
+                                res_lines.append(f"\n<!-- last_verified: {today} -->\n")
+                                inserted = True
+                        if not inserted:
+                            res_lines.insert(0, f"<!-- last_verified: {today} -->\n\n")
+                        new_content = "".join(res_lines)
+
+                    if new_content != content:
+                        import tempfile
+                        fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(filepath), text=True)
+                        try:
+                            with os.fdopen(fd, "w", encoding="utf-8", newline="") as f:
+                                f.write(new_content)
+                            os.replace(tmp_path, filepath)
+                            count += 1
+                        except Exception:
+                            if os.path.exists(tmp_path):
+                                os.remove(tmp_path)
             return f"Updated last_verified in {count} files."
         if name == "analyze_all_dependencies":
             return run_script("ki_dependency_analyzer.py", ["--all"])
@@ -1730,7 +1898,8 @@ def handle_tool_call(name: str, args: dict) -> Any:
 
         # ─── File Ops ───
         if name == "read_know_file":
-            with open(validate_path(args["rel_path"]), "r", encoding="utf-8") as f:
+            p = resolve_know_path(args["rel_path"], must_exist=True)
+            with open(p, "r", encoding="utf-8") as f:
                 content = f.read()
             offset = 0
             if args.get("offset") is not None:
@@ -1754,7 +1923,7 @@ def handle_tool_call(name: str, args: dict) -> Any:
                 return content[offset:]
             return content
         if name == "write_know_file":
-            p = validate_path(args["rel_path"], is_write=True)
+            p = resolve_know_path(args["rel_path"], is_write=True, must_exist=False)
             os.makedirs(os.path.dirname(p), exist_ok=True)
             import tempfile
             fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(p), text=True)
@@ -1768,7 +1937,7 @@ def handle_tool_call(name: str, args: dict) -> Any:
                 raise e
             return "File written."
         if name == "edit_know_file":
-            p = validate_path(args["rel_path"], is_write=True)
+            p = resolve_know_path(args["rel_path"], is_write=True, must_exist=True)
             with open(p, "r", encoding="utf-8") as f:
                 content = f.read()
             old_text = args["old_text"].replace("\r\n", "\n")
@@ -1904,6 +2073,15 @@ def _write_ide_instructions() -> None:
                 instructions_path.write_text(content, encoding="utf-8")
                 safe_log(f"Wrote instructions.md → {instructions_path}")
 
+                active_tool_names = {t["name"] for t in tools_to_write}
+                for existing_json in target_dir.glob("*.json"):
+                    if existing_json.stem not in active_tool_names:
+                        try:
+                            existing_json.unlink()
+                            safe_log(f"Removed inactive tool schema: {existing_json.name}")
+                        except Exception:
+                            pass
+
                 # Sync tool schema JSON files if target is an IDE mcp tool directory
                 for tool in tools_to_write:
                     try:
@@ -1921,7 +2099,7 @@ def _write_ide_instructions() -> None:
 
 
 def _extract_workspace_from_meta(params: dict) -> Optional[str]:
-    """Извлекает workspace URI из _meta нового протокола (2026-07-28)."""
+    """Извлекает workspace URI из _meta нового протокола (2026-07-28)."""
     meta = params.get("_meta", {})
     client_info = meta.get("io.modelcontextprotocol/clientInfo", {})
     return client_info.get("workspaceUri") or client_info.get("rootUri")
@@ -1964,6 +2142,7 @@ def main():
                     root_uri = roots[0].get("uri")
                     if root_uri:
                         ki_utils.ACTIVE_WORKSPACE_PATH = ki_utils.normalize_path(root_uri)
+                        ki_utils._CACHE.clear()
                         safe_log(f"SET workspace via roots/list: {ki_utils.ACTIVE_WORKSPACE_PATH}")
                 continue
 
@@ -1971,24 +2150,22 @@ def main():
             method = req.get("method")
             params = req.get("params", {})
 
-            # Новый протокол: извлекаем workspace из _meta при каждом запросе
-            if not ki_utils.ACTIVE_WORKSPACE_PATH:
-                _ws = _extract_workspace_from_meta(params)
-                if _ws:
-                    ki_utils.ACTIVE_WORKSPACE_PATH = ki_utils.normalize_path(_ws)
+            # Извлекаем workspace из _meta при каждом запросе
+            _ws = _extract_workspace_from_meta(params)
+            if _ws:
+                norm_ws = ki_utils.normalize_path(_ws)
+                if norm_ws != ki_utils.ACTIVE_WORKSPACE_PATH:
+                    ki_utils.ACTIVE_WORKSPACE_PATH = norm_ws
+                    ki_utils._CACHE.clear()
                     safe_log(f"SET workspace via _meta: {ki_utils.ACTIVE_WORKSPACE_PATH}")
 
             def send(result_data):
                 resp = json.dumps({"jsonrpc": "2.0", "id": rid, "result": result_data})
-                safe_log(f"DEBUG: Before write RESP")
                 safe_log(f"RESP: {resp}")
                 sys.stdout.write(resp + "\n")
-                safe_log(f"DEBUG: Before flush RESP")
                 sys.stdout.flush()
-                safe_log(f"DEBUG: After flush RESP")
 
             if method in ("initialize", "server/discover"):
-                safe_log(f"DEBUG: Inside method {method}")
                 # Extract workspace URI from any location in params
                 root_uri = params.get("rootUri")
                 if not root_uri:
@@ -2012,20 +2189,16 @@ def main():
                             return d
                     root_uri = _find_uri(params)
 
-                safe_log(f"DEBUG: After _find_uri. root_uri={root_uri}")
                 if root_uri:
                     ki_utils.ACTIVE_WORKSPACE_PATH = ki_utils.normalize_path(root_uri)
+                    ki_utils._CACHE.clear()
                     safe_log(f"SET workspace via initialize: {ki_utils.ACTIVE_WORKSPACE_PATH}")
 
-                safe_log(f"DEBUG: Before importlib")
                 try:
-                    server_version = importlib.metadata.version("ki-manager")
-                except importlib.metadata.PackageNotFoundError:
-                    server_version = "2.0.11"
-                except Exception as ex:
-                    safe_log(f"DEBUG: importlib EXCEPTION: {ex}")
-                    server_version = "2.0.11"
-                safe_log(f"DEBUG: After importlib. version={server_version}")
+                    import ki_manager
+                    server_version = getattr(ki_manager, "__version__", importlib.metadata.version("ki-manager"))
+                except Exception:
+                    server_version = "2.3.0"
 
                 know_name = os.path.basename(ki_utils.get_knowledge_root()) or ".ki-base"
                 resp = {
@@ -2037,7 +2210,6 @@ def main():
                 if method == "server/discover":
                     resp["versions"] = ["2026-07-28", "2025-11-25", "2024-11-05"]
                 send(resp)
-                safe_log(f"DEBUG: After send() for {method}")
 
             elif method == "notifications/initialized":
                 # Request roots from client for workspace detection
@@ -2047,17 +2219,18 @@ def main():
                 sys.stdout.flush()
 
             elif method == "tools/list":
+                facade.sync_dispatch_schemas(MCP_TOOLS)
                 tools_list = COMPACT_TOOLS if tool_mode == "compact" else MCP_TOOLS
                 send({"tools": tools_list, "ttlMs": 300000, "cacheScope": "global"})
 
             elif method == "tools/call":
                 tool_name = params["name"]
                 tool_args = params.get("arguments", {})
-                # Fallback: пробуем взять workspace из аргументов инструмента
                 if not ki_utils.ACTIVE_WORKSPACE_PATH:
                     _ws_arg = tool_args.get("path") or tool_args.get("project_path")
                     if _ws_arg:
                         ki_utils.ACTIVE_WORKSPACE_PATH = ki_utils.normalize_path(_ws_arg)
+                        ki_utils._CACHE.clear()
                         safe_log(f"SET workspace via tool args: {ki_utils.ACTIVE_WORKSPACE_PATH}")
                 result = handle_tool_call(tool_name, tool_args)
                 if isinstance(result, dict) and "content" in result:
@@ -2079,10 +2252,15 @@ def main():
                     if not match:
                         content = "No registered project. Run ki_init_project first."
                     else:
-                        content = f"Knowledge Items for this project:\n\n{ki_utils.get_ki_list_table()}"
+                        ki_table = ki_utils.get_ki_list_table()
+                        adr_table = ki_utils.get_adr_table()
+                        if adr_table and not adr_table.startswith("No ADRs found"):
+                            content = f"Knowledge Items for this project:\n\n{ki_table}\n\nArchitecture Decision Records (ADRs):\n\n{adr_table}"
+                        else:
+                            content = f"Knowledge Items for this project:\n\n{ki_table}"
                 else:
-                    wf_path = _WORKFLOWS_DIR / f"{prompt_name}.md"
-                    if wf_path.exists():
+                    wf_path = (_WORKFLOWS_DIR / f"{prompt_name}.md").resolve()
+                    if ki_utils.is_subpath(str(wf_path), str(_WORKFLOWS_DIR)) and 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"
@@ -2142,7 +2320,12 @@ def main():
                     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://knowledge-items.md":
-                    content = f"Knowledge Items for this project:\n\n{ki_utils.get_ki_list_table()}"
+                    ki_table = ki_utils.get_ki_list_table()
+                    adr_table = ki_utils.get_adr_table()
+                    if adr_table and not adr_table.startswith("No ADRs found"):
+                        content = f"Knowledge Items for this project:\n\n{ki_table}\n\nArchitecture Decision Records (ADRs):\n\n{adr_table}"
+                    else:
+                        content = f"Knowledge Items for this project:\n\n{ki_table}"
                 elif uri == "ki://adr-list.md":
                     content = get_adr_list(get_project_root(), jail) if jail else "No active project."
                 elif uri in ("ki://workflows/", "ki://workflows"):
@@ -2157,8 +2340,8 @@ def main():
                     wf_name = uri.replace("ki://workflows/", "")
                     if not wf_name.endswith(".md"):
                         wf_name += ".md"
-                    wf_path = _WORKFLOWS_DIR / wf_name
-                    if wf_path.exists():
+                    wf_path = (_WORKFLOWS_DIR / wf_name).resolve()
+                    if ki_utils.is_subpath(str(wf_path), str(_WORKFLOWS_DIR)) and 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"
@@ -2167,10 +2350,13 @@ def main():
                 # Physical resources in jail
                 elif jail and uri.startswith("ki://"):
                     fname = uri.replace("ki://", "")
-                    fpath = os.path.join(jail, fname)
-                    if os.path.exists(fpath):
-                        with open(fpath, "r", encoding="utf-8") as f:
-                            content = f.read()
+                    try:
+                        fpath = validate_path(fname, is_write=False)
+                        if os.path.exists(fpath) and os.path.isfile(fpath):
+                            with open(fpath, "r", encoding="utf-8") as f:
+                                content = f.read()
+                    except Exception:
+                        content = None
                 
                 if content is not None:
                     send({"contents": [{"uri": uri, "mimeType": "text/plain", "text": content}]})

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/tools/facade.py

@@ -244,6 +244,46 @@ 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"}
+
+
+def sync_dispatch_schemas(all_tools: List[Dict[str, Any]]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Dynamically binds KI_CALL_TOOL and KI_MUTATE_TOOL schemas and descriptions
+    directly to the readOnlyHint annotations of all registered tools."""
+    ro_tools = []
+    mut_tools = []
+
+    for t in all_tools:
+        name = t.get("name")
+        if not name or name in DIRECT_FACADE_TOOLS:
+            continue
+        is_ro = t.get("annotations", {}).get("readOnlyHint", False)
+        if is_ro:
+            ro_tools.append(name)
+        else:
+            mut_tools.append(name)
+
+    ro_tools.sort()
+    mut_tools.sort()
+
+    KI_CALL_TOOL["description"] = (
+        "Execute a read-only ki-manager tool. "
+        f"Available tools: {', '.join(ro_tools)}. "
+        "Use ki_tools(name=...) to check arguments. For mutating operations, use ki_mutate."
+    )
+    KI_CALL_TOOL["inputSchema"]["properties"]["tool"]["enum"] = ro_tools
+
+    KI_MUTATE_TOOL["description"] = (
+        "Execute a state-modifying ki-manager tool. "
+        f"Available tools: {', '.join(mut_tools)}. "
+        "Use ki_tools(name=...) to check arguments."
+    )
+    KI_MUTATE_TOOL["inputSchema"]["properties"]["tool"]["enum"] = mut_tools
+
+    return KI_CALL_TOOL, KI_MUTATE_TOOL
+
+
 # ─── Helper Functions ────────────────────────────────────────────────────────
 
 def format_tools_catalog(all_tools: List[Dict[str, Any]], group_filter: Optional[str] = None) -> str:
@@ -280,7 +320,7 @@ def format_tools_catalog(all_tools: List[Dict[str, Any]], group_filter: Optional
 
 
 def validate_args_against_schema(schema: Dict[str, Any], args: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
-    """Simple schema validator checking required fields and basic types."""
+    """Simple schema validator checking required fields, enum choices, and basic types."""
     properties = schema.get("properties", {})
     required = schema.get("required", [])
 
@@ -307,6 +347,10 @@ def validate_args_against_schema(schema: Dict[str, Any], args: Dict[str, Any]) -
                     return False, f"Parameter '{key}' must be integer, got boolean."
                 if not isinstance(val, expected_type):
                     return False, f"Parameter '{key}' must be of type {expected_type_str}, got {type(val).__name__}."
+            if "enum" in properties[key]:
+                allowed = properties[key]["enum"]
+                if val not in allowed:
+                    return False, f"Parameter '{key}' value '{val}' is not one of {allowed}."
 
     return True, None
 

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/tools/scaffold.py

@@ -42,13 +42,14 @@ KI_CONFIG_TEMPLATE = {
     "knowledge_system": {
         "mcp_server": {
             "name": "ki-manager",
-            "version": "2.0.0"
+            "version": "2.3.0"
         }
     },
     "required_sections": ["Overview", "Key Components", "Related KIs"]
 }
 
 OVERVIEW_KI_TEMPLATE = """\
+<!-- last_verified: {date} -->
 # _OVERVIEW — Project Overview
 
 **Module**: `{project_name}` (entire project)
@@ -126,10 +127,10 @@ def write_text(path: Path, content: str):
         f.write(content)
 
 
-def update_gitignore(project_root: Path):
-    """Append .ki-base/config.json to the project .gitignore if not already present."""
+def update_gitignore(project_root: Path, know_name: str = ".ki-base"):
+    """Append <know_name>/config.json to the project .gitignore if not already present."""
     gitignore = project_root / ".gitignore"
-    line = ".ki-base/config.json"
+    line = f"{know_name}/config.json"
     if gitignore.exists():
         content = gitignore.read_text(encoding="utf-8")
         if line in content:
@@ -221,7 +222,7 @@ def init_project(args: dict) -> str:
         log.append(f"[+] Created {know_name}/knowledge/_OVERVIEW.ki.md")
 
     if cfg_loc != "root":
-        update_gitignore(project_path)
+        update_gitignore(project_path, know_name=know_name)
     
     success, msg = ki_utils.register_project(config_path=str(ki_config_path), workspace=str(project_path))
     if success:
@@ -290,7 +291,7 @@ def migrate_project(project_root: str) -> str:
     overview_path = knowledge_dir / "_OVERVIEW.ki.md"
     if not overview_path.exists():
         try:
-            today = datetime.date.today().isoformat()
+            today = datetime.now().strftime("%Y-%m-%d")
             project_name = root.name
             if doc_config_path.exists():
                 try:

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/workflows/expand-knowledge.md

@@ -139,10 +139,10 @@ Write the file using `write_know_file` or `edit_know_file`:
 Register the new KI in `doc_config.json`:
 <!-- if-compact -->
 // turbo
-`ki_mutate(tool="add_ki_to_config", args={"ki_name": "<filename>.ki.md", "files": ["path/to/tracked/file.py"], "summary": "<Concise summary>"})`
+`ki_mutate(tool="add_ki_to_config", args={"ki_name": "<filename>.ki.md", "description": "<Full description>", "depends_on": ["path/to/tracked/file.py"], "summary": "<Concise summary>"})`
 <!-- else-compact -->
 // turbo
-`add_ki_to_config(ki_name="<filename>.ki.md", files=["path/to/tracked/file.py"], summary="<Concise summary>")`
+`add_ki_to_config(ki_name="<filename>.ki.md", description="<Full description>", depends_on=["path/to/tracked/file.py"], summary="<Concise summary>")`
 <!-- /if-compact -->
 
 ---
@@ -155,7 +155,7 @@ Automatically identify and link related KIs based on code imports:
 <!-- if-compact -->
 `ki_call(tool="analyze_dependencies", args={"ki_name": "<filename>.ki.md", "only_changed": false})`
 <!-- else-compact -->
-`analyze_dependencies(args={"ki_name": "<filename>.ki.md", "only_changed": false})`
+`analyze_dependencies(ki_name="<filename>.ki.md", only_changed=false)`
 <!-- /if-compact -->
 
 ---
@@ -188,7 +188,7 @@ Finalize the expansion by creating a git snapshot of the knowledge state.
 <!-- if-compact -->
 `ki_mutate(tool="git_checkpoint", args={"message": "Expand knowledge base: new KI registration"})`
 <!-- else-compact -->
-`git_checkpoint(args={"message": "Expand knowledge base: new KI registration"})`
+`git_checkpoint(message="Expand knowledge base: new KI registration")`
 <!-- /if-compact -->
 
 ---

{ki_manager-2.3.0.dev3 → ki_manager-2.3.1.dev1}/src/ki_manager/workflows/sync-knowledge.md

@@ -100,7 +100,7 @@ Update inter-KI links ONLY for modified KIs to minimize Git noise.
 <!-- if-compact -->
 `ki_call(tool="analyze_dependencies", args={"only_changed": true})`
 <!-- else-compact -->
-`analyze_dependencies(args={"only_changed": true})`
+`analyze_dependencies(only_changed=true)`
 <!-- /if-compact -->
 
 > [!NOTE]
@@ -114,5 +114,5 @@ Finalize the synchronization by creating a git snapshot of the knowledge state.
 <!-- if-compact -->
 `ki_mutate(tool="git_checkpoint", args={"message": "Sync knowledge system state"})`
 <!-- else-compact -->
-`git_checkpoint(args={"message": "Sync knowledge system state"})`
+`git_checkpoint(message="Sync knowledge system state")`
 <!-- /if-compact -->