Public log

venira-mcp

venira-mcp — a standalone Model Context Protocol (MCP) server that gives coding agents (OpenCode, Claude Desktop, any MCP client) workspace-scoped tools in default/expert modes: file read/write/edit/delete, batch reads, line-range reads, content search, r

npm · fingerprint f19a613cab395d51c25735da · repository · RSS

38tools
9recorded versions
14dtracked
changed 1d ago

What changed

Changed 2026-11-18 15:42 UTC

18 descriptions rewritten, 10 schema or annotation changes with the description left byte-identical.

--- pinned/apply_patch
+++ observed/apply_patch
  {
    "_meta": {
      "venira": {
-   "description": "Apply a unified diff (git apply compatible) to one or more files, all-or-nothing. Every file is validated in memory before anything is written; a failing hunk rolls every file back from an automatic checkpoint, like edit_batch. dry_run=1 validates and reports without writing.\nUse when: a change arrives as a diff (git diff, a patch file, another tool's output) and must land completely or not at all — files created, modified, deleted or renamed.\nAvoid when: you have no diff (edit_file/edit_batch) or only need a new file (write_file). Not for directories or symbolic links.\nOutput: dry_run: files[] {action, relative_path, hunks, bytes} plus added/modified/deleted/renamed counts; nothing is written. success: same list plus sha256_after per file. Failure: nothing is changed; data carries rollback_succeeded and, for a mismatching hunk, nearest_context lines for the file and hunk that failed.",
+   "description": "Apply a unified diff (git apply compatible) to one or more files, all-or-nothing. Every file is validated in memory before anything is written; a failing hunk rolls every file back from an automatic checkpoint, like edit_batch. dry_run=true validates and reports without writing.\nUse when: a change arrives as a diff (git diff, a patch file, another tool's output) and must land completely or not at all — files created, modified, deleted or renamed.\nAvoid when: you have no diff (edit_file/edit_batch) or only need a new file (write_file). Not for directories or symbolic links.\nOutput: dry_run: files[] {action, relative_path, hunks, bytes} plus added/modified/deleted/renamed counts; nothing is written. success: same list plus sha256_after per file. Failure: nothing is changed; data carries rollback_succeeded and, for a mismatching hunk, nearest_context lines for the file and hunk that failed.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 validates the patch against the current files and reports what would change, writing nothing (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true validates the patch against the current files and reports what would change, writing nothing (default false).",
+         "type": "boolean"
        },
        "expected_sha256": {
          "additionalProperties": {
--- pinned/change_impact
+++ observed/change_impact
  {
    "_meta": {
      "venira": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 includes test files (default) and counts them in tests_affected.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true includes test files (default) and counts them in tests_affected.",
+         "type": "boolean"
        },
        "max_nodes": {
          "description": "Max affected files (default 300).",
--- pinned/copy_path
+++ observed/copy_path
  {
    "_meta": {
      "venira": {
-   "description": "Copy a file, or a directory with recursive=1, inside the workspace. overwrite=1 replaces an existing file; symbolic links and protected files inside a directory are skipped.\nUse when: you duplicate a file or folder, for example to start from a template.\nAvoid when: you move or rename (move_path).\nOutput: from, to, kind, overwritten, entries, bytes, skipped_symlinks/skipped_protected when any. Missing source gives not_found, an existing target without overwrite gives conflict.",
+   "description": "Copy a file, or a directory with recursive=true, inside the workspace. overwrite=true replaces an existing file; symbolic links and protected files inside a directory are skipped.\nUse when: you duplicate a file or folder, for example to start from a template.\nAvoid when: you move or rename (move_path).\nOutput: from, to, kind, overwritten, entries, bytes, skipped_symlinks/skipped_protected when any. Missing source gives not_found, an existing target without overwrite gives conflict.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 creates missing parent directories of `to` (default 1).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true creates missing parent directories of `to` (default true).",
+         "type": "boolean"
        },
        "from": {
          "description": "Existing workspace path to copy.",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 replaces an existing target file (default 0). A directory is never replaced.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true replaces an existing target file (default false). A directory is never replaced.",
+         "type": "boolean"
        },
        "reason": {
          "description": "Optional why (max 400 chars), audit-logged.",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 is required to copy a directory (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true is required to copy a directory (default false).",
+         "type": "boolean"
        },
        "to": {
          "description": "New workspace path: the final name, not a parent directory.",
--- pinned/create
+++ observed/create
  {
    "_meta": {
      "venira": {
-   "description": "Create a directory; missing parents are created unless create_dirs=0.\nUse when: you need an empty directory. For a file use write_file, which also creates parent folders.\nAvoid when: you edit existing content (edit_file).\nOutput: directory_created {relative_path, created, parents_created}.",
+   "description": "Create a directory; missing parents are created unless create_dirs=false.\nUse when: you need an empty directory. For a file use write_file, which also creates parent folders.\nAvoid when: you edit existing content (edit_file).\nOutput: directory_created {relative_path, created, parents_created}.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 creates missing parent directories (default 1); 0 fails when a parent is missing.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true (default) creates missing parent directories; false fails when a parent is missing.",
+         "type": "boolean"
        },
        "reason": {
          "description": "Optional why (max 400 chars), audit-logged.",
--- pinned/delete_path
+++ observed/delete_path
  {
    "_meta": {
      "venira": {
-   "description": "Delete a file or directory (recursive=1 is required for directories). Not undoable.\nUse when: you remove files or folders. Take a snapshot first when they are not in git.\nAvoid when: the target is uncertain (check with get_file_info or list_files).\nOutput: entries_deleted, bytes_deleted. Missing path gives not_found.",
+   "description": "Delete a file or directory (recursive=true is required for directories). Not undoable.\nUse when: you remove files or folders. Take a snapshot first when they are not in git.\nAvoid when: the target is uncertain (check with get_file_info or list_files).\nOutput: entries_deleted, bytes_deleted. Missing path gives not_found.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 = delete a directory recursively (required for directories); snapshot it first.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true = delete a directory recursively (required for directories); snapshot it first.",
+         "type": "boolean"
        },
        "relative_path": {
          "description": "Exact workspace path to delete.",
--- pinned/dependency_graph
+++ observed/dependency_graph
  {
    "_meta": {
      "venira": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 aggregates npm/pip/node package nodes in external[]. Default 0.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true aggregates npm/pip/node package nodes in external[]. Default false.",
+         "type": "boolean"
        },
        "include_tests": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 includes test files/edges (default); 0 hides them.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true includes test files/edges (default); false hides them.",
+         "type": "boolean"
        },
        "kind": {
          "description": "files (imports), symbols (references/extends), or both (default files).",
--- pinned/edit_batch
+++ observed/edit_batch
  {
    "_meta": {
      "venira": {
-                     "anyOf": [
-                       {
-                         "type": "boolean"
-                       },
-                       {
-                         "maximum": 1,
-                         "minimum": 0,
-                         "type": "integer"
-                       }
-                     ],
-                     "description": "1 replaces every match; 0 (default) requires exactly one match.",
-                     "maximum": 1,
-                     "minimum": 0,
-                     "type": "integer"
+                     "description": "true replaces every match; false (default) requires exactly one match.",
+                     "type": "boolean"
                    }
                  },
                  "required": [
-               "anyOf": [
-                 {
-                   "type": "boolean"
-                 },
-                 {
-                   "maximum": 1,
-                   "minimum": 0,
-                   "type": "integer"
-                 }
-               ],
-               "description": "1 replaces every match; 0 (default) requires exactly one match.",
-               "maximum": 1,
-               "minimum": 0,
-               "type": "integer"
+               "description": "true replaces every match; false (default) requires exactly one match.",
+               "type": "boolean"
              }
            },
            "required": [
--- pinned/edit_file
+++ observed/edit_file
  {
    "_meta": {
      "venira": {
-       "use_when": "you make a targeted change. old_text must match exactly once unless replace_all=1. Pass expected_sha256 (read_file's sha256 or your last sha256_after) to refuse stale content and get a verified re-read."
+       "use_when": "you make a targeted change. old_text must match exactly once unless replace_all=true. Pass expected_sha256 (read_file's sha256 or your last sha256_after) to refuse stale content and get a verified re-read."
      }
    },
    "annotations": {
-   "description": "Replace exact text: old_text to new_text, or edits[] for several replacements in one file (edits[] wins).\nUse when: you make a targeted change. old_text must match exactly once unless replace_all=1. Pass expected_sha256 (read_file's sha256 or your last sha256_after) to refuse stale content and get a verified re-read.\nAvoid when: you rewrite the whole file (write_file) or change several files at once (edit_batch).\nOutput: replacements, sha256_before, sha256_after, verified (when expected_sha256 is given). Failures leave the file unchanged: old_text_not_found (data.mismatch locates the first difference, data.context shows the nearby lines) and old_text_ambiguous (lists each match with context).",
+   "description": "Replace exact text: old_text to new_text, or edits[] for several replacements in one file (edits[] wins).\nUse when: you make a targeted change. old_text must match exactly once unless replace_all=true. Pass expected_sha256 (read_file's sha256 or your last sha256_after) to refuse stale content and get a verified re-read.\nAvoid when: you rewrite the whole file (write_file) or change several files at once (edit_batch).\nOutput: replacements, sha256_before, sha256_after, verified (when expected_sha256 is given). Failures leave the file unchanged: old_text_not_found (data.mismatch locates the first difference, data.context shows the nearby lines) and old_text_ambiguous (lists each match with context).",
    "execution": {
      "taskSupport": "forbidden"
    },
-               "anyOf": [
-                 {
-                   "type": "boolean"
-                 },
-                 {
-                   "maximum": 1,
-                   "minimum": 0,
-                   "type": "integer"
-                 }
-               ],
-               "description": "1 replaces every match; 0 (default) requires exactly one match.",
-               "maximum": 1,
-               "minimum": 0,
-               "type": "integer"
+               "description": "true replaces every match; false (default) requires exactly one match.",
+               "type": "boolean"
              }
            },
            "required": [
-         "description": "Exact text to replace. Must match exactly once unless replace_all=1. Ignored when edits[] is given.",
+         "description": "Exact text to replace. Must match exactly once unless replace_all=true. Ignored when edits[] is given.",
          "minLength": 1,
          "type": "string"
        },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 replaces every match; 0 (default) requires exactly one match.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true replaces every match; false (default) requires exactly one match.",
+         "type": "boolean"
        }
      },
      "required": [
--- pinned/get_file_info
+++ observed/get_file_info
  {
    "_meta": {
      "venira": {
-       "output_kind": "kind, size_bytes, modified_unix_seconds, exists when missing_ok=1. Missing path gives not_found (or ok with exists:false and missing_ok=1).",
+       "output_kind": "kind, size_bytes, modified_unix_seconds, exists when missing_ok=true. Missing path gives not_found (or ok with exists:false and missing_ok=true).",
        "speed_profile": "very fast; cache validated by mtime+size.",
-       "use_when": "you need to know whether a path exists or how big it is. Use missing_ok=1 to probe existence without failing the call or the batch."
+       "use_when": "you need to know whether a path exists or how big it is. Use missing_ok=true to probe existence without failing the call or the batch."
      }
    },
    "annotations": {
-   "description": "Return kind, size and modification time of a path. `missing_ok=1` answers ok with `data.exists:false` for a missing path instead of `not_found` (works inside read_batch items too).\nUse when: you need to know whether a path exists or how big it is. Use missing_ok=1 to probe existence without failing the call or the batch.\nAvoid when: you need the content (read_file).\nOutput: kind, size_bytes, modified_unix_seconds, exists when missing_ok=1. Missing path gives not_found (or ok with exists:false and missing_ok=1).",
+   "description": "Return kind, size and modification time of a path. `missing_ok=true` answers ok with `data.exists:false` for a missing path instead of `not_found` (works inside read_batch items too).\nUse when: you need to know whether a path exists or how big it is. Use missing_ok=true to probe existence without failing the call or the batch.\nAvoid when: you need the content (read_file).\nOutput: kind, size_bytes, modified_unix_seconds, exists when missing_ok=true. Missing path gives not_found (or ok with exists:false and missing_ok=true).",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 = answer ok with exists:false for a missing path instead of not_found (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true = answer ok with exists:false for a missing path instead of not_found (default false).",
+         "type": "boolean"
        },
        "relative_path": {
          "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
--- pinned/git_branch
+++ observed/git_branch
  {
    "_meta": {
      "venira": {
-         "description": "list: local branches (add include_remote=1 for origin); current: just the checked-out branch; create/switch/delete: local branch.",
+         "description": "list: local branches (add include_remote=true for origin); current: just the checked-out branch; create/switch/delete: local branch.",
          "enum": [
            "list",
            "current",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 allows deleting an unmerged branch (git branch -D); 0 uses -d.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true allows deleting an unmerged branch (git branch -D); false uses -d.",
+         "type": "boolean"
        },
        "from": {
          "description": "Optional start ref for action=create (default: HEAD).",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 includes remote-tracking branches in action=list.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true includes remote-tracking branches in action=list.",
+         "type": "boolean"
        },
        "name": {
          "description": "Branch name (required for create/switch/delete).",
--- pinned/git_commit
+++ observed/git_commit
  {
    "_meta": {
      "venira": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 allows an empty commit (git commit --allow-empty).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true allows an empty commit (git commit --allow-empty).",
+         "type": "boolean"
        },
        "amend": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 amends HEAD instead of creating a new commit.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true amends HEAD instead of creating a new commit.",
+         "type": "boolean"
        },
        "message": {
          "description": "Commit message (first line is the subject).",
--- pinned/git_diff
+++ observed/git_diff
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you need a raw unified blob (use include_patch=1 or diff_files) or a PR diff (provider tools).",
+       "avoid_when": "you need a raw unified blob (use include_patch=true or diff_files) or a PR diff (provider tools).",
        "batch_safe": true,
-       "output_kind": "files[] {old_path|null, new_path|null, action (added|modified|deleted|renamed), binary, hunks[] {old_start, old_lines, new_start, new_lines, section}}, counts{}, patch_bytes, patch/patch_truncated when include_patch=1.",
+       "output_kind": "files[] {old_path|null, new_path|null, action (added|modified|deleted|renamed), binary, hunks[] {old_start, old_lines, new_start, new_lines, section}}, counts{}, patch_bytes, patch/patch_truncated when include_patch=true.",
        "speed_profile": "scales with the diff; hunk metadata is parsed, patch text is opt-in.",
        "use_when": "you need per-file hunk info for review/preview or a test, not free text."
      }
-   "description": "Parsed git diff (staged or worktree): files + hunks (old_start/lines, new_start/lines, section). Patch text is opt-in via include_patch=1.\nUse when: you need per-file hunk info for review/preview or a test, not free text.\nAvoid when: you need a raw unified blob (use include_patch=1 or diff_files) or a PR diff (provider tools).\nOutput: files[] {old_path|null, new_path|null, action (added|modified|deleted|renamed), binary, hunks[] {old_start, old_lines, new_start, new_lines, section}}, counts{}, patch_bytes, patch/patch_truncated when include_patch=1.",
+   "description": "Parsed git diff (staged or worktree): files + hunks (old_start/lines, new_start/lines, section). Patch text is opt-in via include_patch=true.\nUse when: you need per-file hunk info for review/preview or a test, not free text.\nAvoid when: you need a raw unified blob (use include_patch=true or diff_files) or a PR diff (provider tools).\nOutput: files[] {old_path|null, new_path|null, action (added|modified|deleted|renamed), binary, hunks[] {old_start, old_lines, new_start, new_lines, section}}, counts{}, patch_bytes, patch/patch_truncated when include_patch=true.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 includes the unified diff text (truncated to max_bytes).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true includes the unified diff text (truncated to max_bytes).",
+         "type": "boolean"
        },
        "max_bytes": {
-         "description": "Patch text budget when include_patch=1 (default 65536).",
+         "description": "Patch text budget when include_patch=true (default 65536).",
          "maximum": 1048576,
          "minimum": 1024,
          "type": "integer"
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 compares the index to HEAD (git diff --cached); 0 compares worktree to HEAD/index.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true compares the index to HEAD (git diff --cached); false compares worktree to HEAD/index.",
+         "type": "boolean"
        }
      },
      "type": "object"
--- pinned/git_log
+++ observed/git_log
  {
    "_meta": {
      "venira": {
-   "description": "Local commit log, or per-line blame when blame=1 with path. Filters: ref, author, grep, paths.\nUse when: you need recent commits or who last touched lines (blame).\nAvoid when: you need tags/remote refs only (git branch --all) or a remote CI’s log (ci_logs).\nOutput: mode=log: commits[] {sha, short_sha, author, email, authored_at, committer, subject, body}, count. mode=blame: entries[] {line, commit, author, authored_at, summary}, lines.",
+   "description": "Local commit log, or per-line blame when blame=true with path. Filters: ref, author, grep, paths.\nUse when: you need recent commits or who last touched lines (blame).\nAvoid when: you need tags/remote refs only (git branch --all) or a remote CI’s log (ci_logs).\nOutput: mode=log: commits[] {sha, short_sha, author, email, authored_at, committer, subject, body}, count. mode=blame: entries[] {line, commit, author, authored_at, summary}, lines.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 switches to blame mode for path (optionally ref).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true switches to blame mode for path (optionally ref).",
+         "type": "boolean"
        },
        "grep": {
          "description": "Filter commit messages by substring.",
-         "description": "Required when blame=1: the file to blame.",
+         "description": "Required when blame=true: the file to blame.",
          "maxLength": 4096,
          "minLength": 1,
          "type": "string"
--- pinned/git_stash
+++ observed/git_stash
  {
    "_meta": {
      "venira": {
-   "description": "Stash push/list/apply/pop/drop/show. Push stashes staged+unstaged tracked changes (add include_untracked=1 for untracked files).\nUse when: you need to pause work to switch branches or commit selectively.\nAvoid when: you need to stash and keep a copy (stash keeps one; use apply over pop) or drop permanently (prefer apply, then commit).\nOutput: push: pushed, message, selector, output. list: entries[] {selector, sha, subject}, count. apply/pop/drop: applied/dropped. show: files[], count.",
+   "description": "Stash push/list/apply/pop/drop/show. Push stashes staged+unstaged tracked changes (add include_untracked=true for untracked files).\nUse when: you need to pause work to switch branches or commit selectively.\nAvoid when: you need to stash and keep a copy (stash keeps one; use apply over pop) or drop permanently (prefer apply, then commit).\nOutput: push: pushed, message, selector, output. list: entries[] {selector, sha, subject}, count. apply/pop/drop: applied/dropped. show: files[], count.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 includes untracked files when pushing.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true includes untracked files when pushing.",
+         "type": "boolean"
        },
        "message": {
          "description": "Optional message for action=push.",
--- pinned/github_connect
+++ observed/github_connect
  {
    "_meta": {
      "venira": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
          "description": "action=start: 1 explicitly authorizes replacing an existing GitHub credential; 0 does not.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "type": "boolean"
        }
      },
      "required": [
--- pinned/health
+++ observed/health
  {
    "_meta": {
      "venira": {
-       "speed_profile": "fast (~a few ms + 1 audit DB query); set include_audit=0 to skip the DB query.",
-       "use_when": "you debug slowness or errors, or want the security warnings before risky work. include_audit=0 skips the audit query."
+       "speed_profile": "fast (~a few ms + 1 audit DB query); set include_audit=false to skip the DB query.",
+       "use_when": "you debug slowness or errors, or want the security warnings before risky work. include_audit=false skips the audit query."
      }
    },
    "annotations": {
-   "description": "Server diagnostics: version, workspace, security posture and warnings, caches, queue, running shells, latency, snapshot store, audit status.\nUse when: you debug slowness or errors, or want the security warnings before risky work. include_audit=0 skips the audit query.\nAvoid when: normal file work.\nOutput: One key per report section (see sections); with sections set, also sections_requested and sections_unknown.",
+   "description": "Server diagnostics: version, workspace, security posture and warnings, caches, queue, running shells, latency, snapshot store, audit status.\nUse when: you debug slowness or errors, or want the security warnings before risky work. include_audit=false skips the audit query.\nAvoid when: normal file work.\nOutput: One key per report section (see sections); with sections set, also sections_requested and sections_unknown.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 includes the audit-log summary in the result (default 1); 0 skips the audit DB query.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true includes the audit-log summary in the result (default true); false skips the audit DB query.",
+         "type": "boolean"
        },
        "sections": {
          "description": "Report sections to return: notice, server, corehost, capability, queue, caches, shells, approvals, warnings, posture, snapshots, secrets, network, metrics, cache, trace, shell, environment, audit. caches/shells are live state; cache/shell are configuration. Omit for everything; use it when the full payload does not fit the response.",
--- pinned/list_files
+++ observed/list_files
  {
    "_meta": {
      "venira": {
-   "description": "List files and directories (depth 1-3, limit up to 200). include_ignored=1 also lists ignored folders.\nUse when: you need the directory tree or want to confirm a path exists.\nAvoid when: you know the file (read_file) or want what changed lately (recent_files).\nOutput: entries[] {relative_path, kind, size_bytes}, truncated.",
+   "description": "List files and directories (depth 1-3, limit up to 200). include_ignored=true also lists ignored folders.\nUse when: you need the directory tree or want to confirm a path exists.\nAvoid when: you know the file (read_file) or want what changed lately (recent_files).\nOutput: entries[] {relative_path, kind, size_bytes}, truncated.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 also lists ignored folders (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true also lists ignored folders (default false).",
+         "type": "boolean"
        },
        "limit": {
          "description": "Max entries (default 200, max 200).",
--- pinned/move_path
+++ observed/move_path
  {
    "_meta": {
      "venira": {
-   "description": "Move or rename a file or directory inside the workspace. overwrite=1 replaces an existing file, never a directory; create_dirs (default 1) makes missing parents of `to`.\nUse when: you rename or relocate files or folders. Not undoable: take a snapshot first when they are not in git.\nAvoid when: you duplicate (copy_path) or remove (delete_path).\nOutput: from, to, kind, overwritten, entries, bytes. Missing source gives not_found, an existing target without overwrite gives conflict.",
+   "description": "Move or rename a file or directory inside the workspace. overwrite=true replaces an existing file, never a directory; create_dirs (default true) makes missing parents of `to`.\nUse when: you rename or relocate files or folders. Not undoable: take a snapshot first when they are not in git.\nAvoid when: you duplicate (copy_path) or remove (delete_path).\nOutput: from, to, kind, overwritten, entries, bytes. Missing source gives not_found, an existing target without overwrite gives conflict.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 creates missing parent directories of `to` (default 1).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true creates missing parent directories of `to` (default true).",
+         "type": "boolean"
        },
        "from": {
          "description": "Existing workspace path to move or rename.",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 replaces an existing target file (default 0). A directory is never replaced.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true replaces an existing target file (default false). A directory is never replaced.",
+         "type": "boolean"
        },
        "reason": {
          "description": "Optional why (max 400 chars), audit-logged.",
--- pinned/outline_symbol
+++ observed/outline_symbol
  {
    "_meta": {
      "venira": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 includes class/interface symbols (default 1).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true includes class/interface symbols (default true).",
+         "type": "boolean"
        },
        "include_functions": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 includes function symbols (default 1).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true includes function symbols (default true).",
+         "type": "boolean"
        },
        "language": {
          "description": "Optional language hint (e.g. 'ts', 'py'); the parser auto-detects from the file extension when omitted. The hint is advisory.",
--- pinned/read_audit
+++ observed/read_audit
  {
    "_meta": {
      "venira": {
-       "output_kind": "rows[] {session_id, operation, outcome, reason_code, reason, args_hash, command, request_id, started_at_ms, completed_at_ms, elapsed_ms, args_summary, result_summary, result_bytes}, count, truncated, chain_ok (verify=1). Output mode full adds redacted args and result per row; bulk text is kept as its length only. Timestamps are epoch milliseconds (since_unix filters in seconds). args_hash identifies the call, command is the redacted command line.",
+       "output_kind": "rows[] {session_id, operation, outcome, reason_code, reason, args_hash, command, request_id, started_at_ms, completed_at_ms, elapsed_ms, args_summary, result_summary, result_bytes}, count, truncated, chain_ok (verify=true). Output mode full adds redacted args and result per row; bulk text is kept as its length only. Timestamps are epoch milliseconds (since_unix filters in seconds). args_hash identifies the call, command is the redacted command line.",
        "speed_profile": "fast; one bounded SQLite read (readonly, WAL-safe).",
        "use_when": "you review what ran and how it ended, or look one job up by request_id."
      }
-   "description": "Read recent audit-log rows, newest first: what each job was asked and returned. Filter by session_id, operation, outcome, request_id, since_unix (seconds); verify=1 checks the hash chain.\nUse when: you review what ran and how it ended, or look one job up by request_id.\nAvoid when: you want live metrics (health).\nOutput: rows[] {session_id, operation, outcome, reason_code, reason, args_hash, command, request_id, started_at_ms, completed_at_ms, elapsed_ms, args_summary, result_summary, result_bytes}, count, truncated, chain_ok (verify=1). Output mode full adds redacted args and result per row; bulk text is kept as its length only. Timestamps are epoch milliseconds (since_unix filters in seconds). args_hash identifies the call, command is the redacted command line.",
+   "description": "Read recent audit-log rows, newest first: what each job was asked and returned. Filter by session_id, operation, outcome, request_id, since_unix (seconds); verify=true checks the hash chain.\nUse when: you review what ran and how it ended, or look one job up by request_id.\nAvoid when: you want live metrics (health).\nOutput: rows[] {session_id, operation, outcome, reason_code, reason, args_hash, command, request_id, started_at_ms, completed_at_ms, elapsed_ms, args_summary, result_summary, result_bytes}, count, truncated, chain_ok (verify=true). Output mode full adds redacted args and result per row; bulk text is kept as its length only. Timestamps are epoch milliseconds (since_unix filters in seconds). args_hash identifies the call, command is the redacted command line.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 verifies the audit hash chain and returns chain_ok; 0 disables verification.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true verifies the audit hash chain and returns chain_ok; false disables verification.",
+         "type": "boolean"
        }
      },
      "type": "object"
--- pinned/read_batch
+++ observed/read_batch
  {
    "_meta": {
      "venira": {
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 also lists ignored folders (default 0).",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true also lists ignored folders (default false).",
+                       "type": "boolean"
                      },
                      "limit": {
                        "description": "Max entries (default 200, max 200).",
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 prefixes lines (default 0).",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true prefixes lines (default false).",
+                       "type": "boolean"
                      },
                      "max_bytes": {
                        "description": "Max bytes returned (default 1 MiB).",
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 = answer ok with exists:false for a missing path instead of not_found (default 0).",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true = answer ok with exists:false for a missing path instead of not_found (default false).",
+                       "type": "boolean"
                      },
                      "relative_path": {
                        "description": "Required (optional here so one bad item fails only itself).",
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 = case-sensitive (default 0).",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true = case-sensitive (default false).",
+                       "type": "boolean"
                      },
                      "context_lines": {
                        "description": "Context lines per hit (default 0).",
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 = counts only (default 0).",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true = counts only (default false).",
+                       "type": "boolean"
                      },
                      "exclude_glob": {
                        "description": "rg glob exclusion (same dialect as glob).",
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 tags hits with source (default 0).",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true tags hits with source (default false).",
+                       "type": "boolean"
                      },
                      "include_hidden": {
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 includes dotfiles (default); 0 skips them.",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true includes dotfiles (default); false skips them.",
+                       "type": "boolean"
                      },
                      "kind": {
                        "description": "Required: name substring | content | declaration lines.",
-                       "description": "Max hits (ignored when count_only=1).",
+                       "description": "Max hits (ignored when count_only=true).",
                        "maximum": 200,
                        "minimum": 1,
                        "type": "integer"
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 = regex query (default 0).",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true = regex query (default false).",
+                       "type": "boolean"
                      },
                      "relative_path": {
                        "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
-                       "anyOf": [
-                         {
-                           "type": "boolean"
-                         },
-                         {
-                           "maximum": 1,
-                           "minimum": 0,
-                           "type": "integer"
-                         }
-                       ],
-                       "description": "1 = whole-word only (default 0).",
-                       "maximum": 1,
-                       "minimum": 0,
-                       "type": "integer"
+                       "description": "true = whole-word only (default false).",
+                       "type": "boolean"
                      }
                    },
                    "type": "object"
--- pinned/read_file
+++ observed/read_file
  {
    "_meta": {
      "venira": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 prefixes each line with its line number (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true prefixes each line with its line number (default false).",
+         "type": "boolean"
        },
        "max_bytes": {
          "description": "Max bytes returned (default and max 1 MiB).",
--- pinned/recent_files
+++ observed/recent_files
  {
    "_meta": {
      "venira": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 also lists ignored folders (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true also lists ignored folders (default false).",
+         "type": "boolean"
        },
        "limit": {
          "description": "Max entries (default 20, max 100).",
--- pinned/search
+++ observed/search
  {
    "_meta": {
      "venira": {
-   "description": "Search by kind: file_name, directory_name, literal_content (regex=1 for regex) or definition (symbol declarations). `queries` instead ranks matching lines by several weighted patterns (must/weight).\nUse when: you must locate code, strings or symbols before reading. Keep relative_path narrow: a scan stops at 50000 files.\nAvoid when: you know the path (read_file), want a file's structure (outline_symbol), a symbol's usages (symbol_references) or an executable on PATH (shell_run: `where <name>`).\nOutput: hits[] {relative_path, line_number, snippet}, complete, total_match_lines, files_matched. With queries: hits also carry score/matched, plus total_files/total_hits. No match is ok with empty hits.",
+   "description": "Search by kind: file_name, directory_name, literal_content (regex=true for regex) or definition (symbol declarations). `queries` instead ranks matching lines by several weighted patterns (must/weight).\nUse when: you must locate code, strings or symbols before reading. Keep relative_path narrow: a scan stops at 50000 files.\nAvoid when: you know the path (read_file), want a file's structure (outline_symbol), a symbol's usages (symbol_references) or an executable on PATH (shell_run: `where <name>`).\nOutput: hits[] {relative_path, line_number, snippet}, complete, total_match_lines, files_matched. With queries: hits also carry score/matched, plus total_files/total_hits. No match is ok with empty hits.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 makes literal_content/definition matching case-sensitive (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true makes literal_content/definition matching case-sensitive (default false).",
+         "type": "boolean"
        },
        "context_lines": {
          "description": "Context lines around each hit (default 0).",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 returns only match counts; limit is then ignored. 0 (default) returns hits.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true returns only match counts; limit is then ignored. false (default) returns hits.",
+         "type": "boolean"
        },
        "exclude_glob": {
          "description": "rg glob exclusion (same dialect as glob).",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 = tag hits with source/confidence; literal_content only.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true = tag hits with source/confidence; literal_content only.",
+         "type": "boolean"
        },
        "include_hidden": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 = include hidden files (default); 0 = skip dotfiles. Secrets always excluded.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true = include hidden files (default); false = skip dotfiles. Secrets always excluded.",
+         "type": "boolean"
        },
        "kind": {
-         "description": "name substring | content (substring, or regex when regex=1) | declaration lines. Required unless `queries`/`files_hint` is set.",
+         "description": "name substring | content (substring, or regex when regex=true) | declaration lines. Required unless `queries`/`files_hint` is set.",
          "enum": [
            "file_name",
            "directory_name",
-         "description": "Max hits returned (default and max 200; ignored when count_only=1).",
+         "description": "Max hits returned (default and max 200; ignored when count_only=true).",
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
-               "anyOf": [
-                 {
-                   "type": "boolean"
-                 },
-                 {
-                   "maximum": 1,
-                   "minimum": 0,
-                   "type": "integer"
-                 }
-               ],
-               "description": "1 = only lines containing this pattern count as hits (default 0).",
-               "maximum": 1,
-               "minimum": 0,
-               "type": "integer"
+               "description": "true = only lines containing this pattern count as hits (default false).",
+               "type": "boolean"
              },
              "pattern": {
                "description": "Case-insensitive substring matched against each line.",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 treats query as a regular expression for literal_content/definition (default 0 = plain substring).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true treats query as a regular expression for literal_content/definition (default false = plain substring).",
+         "type": "boolean"
        },
        "relative_path": {
          "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 = whole-word match only (rg -w / JS word boundaries) for literal_content and definition.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true = whole-word match only (rg -w / JS word boundaries) for literal_content and definition.",
+         "type": "boolean"
        }
      },
      "type": "object"
--- pinned/secret
+++ observed/secret
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the value is plain config (use .env or the config file). reveal=1 prints plaintext and needs VENIRA_SHELL_MODE=permissive or off.",
+       "avoid_when": "the value is plain config (use .env or the config file). reveal=true prints plaintext and needs VENIRA_SHELL_MODE=permissive or off.",
        "batch_safe": false,
        "output_kind": "set: name, length, expires_at, days_left. get and list: metadata only.",
        "speed_profile": "fast; encrypted AES-256-GCM store, atomic writes, values decrypted only when injected. Expiry/use fields are metadata only.",
-   "description": "Store and inspect tokens without exposing them (AES-256-GCM at rest). action: set | get (metadata only) | list | delete. Inject into commands with shell_run secret_env=[NAME]; the GitHub tools read GITHUB_TOKEN on their own.\nUse when: you save a non-GitHub token, check expiry or rotation, or remove one. Prefer value_env over value so the secret never appears in chat.\nAvoid when: the value is plain config (use .env or the config file). reveal=1 prints plaintext and needs VENIRA_SHELL_MODE=permissive or off.\nOutput: set: name, length, expires_at, days_left. get and list: metadata only.",
+   "description": "Store and inspect tokens without exposing them (AES-256-GCM at rest). action: set | get (metadata only) | list | delete. Inject into commands with shell_run secret_env=[NAME]; the GitHub tools read GITHUB_TOKEN on their own.\nUse when: you save a non-GitHub token, check expiry or rotation, or remove one. Prefer value_env over value so the secret never appears in chat.\nAvoid when: the value is plain config (use .env or the config file). reveal=true prints plaintext and needs VENIRA_SHELL_MODE=permissive or off.\nOutput: set: name, length, expires_at, days_left. get and list: metadata only.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "set stores a secret; get returns metadata only (plaintext needs reveal=1); list shows all stored secrets; delete removes one.",
+         "description": "set stores a secret; get returns metadata only (plaintext needs reveal=true); list shows all stored secrets; delete removes one.",
          "enum": [
            "get",
            "set",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
          "description": "action=get: 1 prints plaintext; needs VENIRA_SHELL_MODE=permissive or off; prefer secret_env injection.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "type": "boolean"
        },
        "value": {
          "description": "Secret value for action=set. Prefer value_env so it never appears in the transcript.",
--- pinned/shell_run
+++ observed/shell_run
  {
    "_meta": {
      "venira": {
-       "output_kind": "run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=0) or stdout_tail/stderr_tail. ok=true only means the call ran; status (completed|failed|running|cancelled) and command_status describe the command. shell_path/shell_kind name the binary that ran it (on Windows bash may be the WSL launcher). approval_required: ask the user to approve, then retry once with approval_id. repeated_failure: the identical invocation already failed; read data.previous.stderr_tail, then change the command or pass retry_failed=1.",
-       "speed_profile": "background=1 returns in ~5 ms, run time is up to the command; background=0 blocks for the whole run (bounded by timeout_s, default 10 min).",
-       "use_when": "you build, test, run git or install packages. background=0 for short commands you need now."
+       "output_kind": "run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=false) or stdout_tail/stderr_tail. ok=true only means the call ran; status (completed|failed|running|cancelled) and command_status describe the command. shell_path/shell_kind name the binary that ran it (on Windows bash may be the WSL launcher). approval_required: ask the user to approve, then retry once with approval_id. repeated_failure: the identical invocation already failed; read data.previous.stderr_tail, then change the command or pass retry_failed=true.",
+       "speed_profile": "background=true returns in ~5 ms, run time is up to the command; background=false blocks for the whole run (bounded by timeout_s, default 10 min).",
+       "use_when": "you build, test, run git or install packages. background=false for short commands you need now."
      }
    },
    "annotations": {
-   "description": "Run a shell command in the workspace (shell, relative_cwd, timeout_s). Default is background: returns run_id, poll shell_status. background=0 blocks until exit and returns stdout/stderr.\nUse when: you build, test, run git or install packages. background=0 for short commands you need now.\nAvoid when: you read or edit files (file tools) or run a tiny JS calculation (execute_js).\nOutput: run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=0) or stdout_tail/stderr_tail. ok=true only means the call ran; status (completed|failed|running|cancelled) and command_status describe the command. shell_path/shell_kind name the binary that ran it (on Windows bash may be the WSL launcher). approval_required: ask the user to approve, then retry once with approval_id. repeated_failure: the identical invocation already failed; read data.previous.stderr_tail, then change the command or pass retry_failed=1.",
+   "description": "Run a shell command in the workspace (shell, relative_cwd, timeout_s). Default is background: returns run_id, poll shell_status. background=false blocks until exit and returns stdout/stderr.\nUse when: you build, test, run git or install packages. background=false for short commands you need now.\nAvoid when: you read or edit files (file tools) or run a tiny JS calculation (execute_js).\nOutput: run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=false) or stdout_tail/stderr_tail. ok=true only means the call ran; status (completed|failed|running|cancelled) and command_status describe the command. shell_path/shell_kind name the binary that ran it (on Windows bash may be the WSL launcher). approval_required: ask the user to approve, then retry once with approval_id. repeated_failure: the identical invocation already failed; read data.previous.stderr_tail, then change the command or pass retry_failed=true.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "1 = background (default): return immediately with run_id. 0 = foreground: block until the command exits, then return the final stdout/stderr in this call.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true = background (default): return immediately with run_id. false = foreground: block until the command exits, then return the final stdout/stderr in this call.",
+         "type": "boolean"
        },
        "command": {
          "description": "Command line to run.",
-         "description": "1 = evaluate policy only; nothing runs, no approval is created (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true = evaluate policy only; nothing runs, no approval is created (default false).",
+         "type": "boolean"
        },
        "override": {
          "description": "Named exception; only works when the operator enabled this exact name in VENIRA_SHELL_OVERRIDES.",
-         "description": "1 = rerun an identical invocation that already failed (default 0: refused with repeated_failure and the previous stderr tail).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true = rerun an identical invocation that already failed (default false: refused with repeated_failure and the previous stderr tail).",
+         "type": "boolean"
        },
        "secret_env": {
          "description": "Stored secret names (secret) injected as env vars, e.g. [\"GITHUB_TOKEN\"]. Values never appear in the command, audit log or output.",
--- pinned/snapshot
+++ observed/snapshot
  {
    "_meta": {
      "venira": {
-       "use_when": "before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=1, then restore with verify=1."
+       "use_when": "before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=true, then restore with verify=true."
      }
    },
    "annotations": {
-   "description": "Checkpoint and roll back workspace files. action: create (label, paths) | list | restore (id) | delete (id) | mirror (copy to VENIRA_SNAPSHOT_MIRROR_DIR).\nUse when: before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=1, then restore with verify=1.\nAvoid when: tiny single-file edits or states git already holds.\nOutput: create: id, file_count, total_bytes, truncated, skipped[]. restore: restored[], deleted_count, skipped[].",
+   "description": "Checkpoint and roll back workspace files. action: create (label, paths) | list | restore (id) | delete (id) | mirror (copy to VENIRA_SNAPSHOT_MIRROR_DIR).\nUse when: before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=true, then restore with verify=true.\nAvoid when: tiny single-file edits or states git already holds.\nOutput: create: id, file_count, total_bytes, truncated, skipped[]. restore: restored[], deleted_count, skipped[].",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "restore only: 1 also deletes files in captured dirs that are not in the checkpoint (max 500). Default 0; use only when intended.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "restore only: true also deletes files in captured dirs that are not in the checkpoint (max 500). Default false; use only when intended.",
+         "type": "boolean"
        },
        "dry_run": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "restore only: 1 previews path/size changes without writing.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "restore only: true previews path/size changes without writing.",
+         "type": "boolean"
        },
        "exclude": {
          "description": "Extra directory/file names to skip.",
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 skips standard generated/cache directories (default); 0 disables those exclusions.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true (default) skips standard generated/cache directories; false disables those exclusions.",
+         "type": "boolean"
        },
        "verify": {
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "restore: 1 verifies each blob before writing (default). mirror: 1 re-hashes blobs already at the mirror and re-copies bad ones (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "restore: true (default) verifies each blob before writing. mirror: true re-hashes blobs already at the mirror and re-copies bad ones (default false).",
+         "type": "boolean"
        }
      },
      "type": "object"
--- pinned/write_file
+++ observed/write_file
  {
    "_meta": {
      "venira": {
-   "description": "Write a file. mode=create (fails if it exists), overwrite, or append. create_dirs=1 creates parent folders.\nUse when: you create a file, replace one entirely, or append. expected_sha256 refuses the write if the file changed since you read it.\nAvoid when: you change a few lines (edit_file). overwrite is immediate and not undoable: snapshot first when the file is not in git.\nOutput: action (created|overwritten|appended), bytes_written, sha256_after. mode=create on an existing path gives conflict.",
+   "description": "Write a file. mode=create (fails if it exists), overwrite, or append. create_dirs=true creates parent folders.\nUse when: you create a file, replace one entirely, or append. expected_sha256 refuses the write if the file changed since you read it.\nAvoid when: you change a few lines (edit_file). overwrite is immediate and not undoable: snapshot first when the file is not in git.\nOutput: action (created|overwritten|appended), bytes_written, sha256_after. mode=create on an existing path gives conflict.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "anyOf": [
-           {
-             "type": "boolean"
-           },
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           }
-         ],
-         "description": "1 creates missing parent directories (default 0).",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
+         "description": "true creates missing parent directories (default false).",
+         "type": "boolean"
        },
        "expected_sha256": {
          "description": "Hex SHA-256 of the file's current full content. The write is refused if the file on disk differs. Use sha256_after from your last write/edit of this file; read_file's sha256 only matches when the whole file was returned.",

Changed 2026-11-15 13:54 UTC

4 descriptions rewritten, 1 schema or annotation change with the description left byte-identical, 1 tool added.

--- pinned/change_impact
+++ observed/change_impact
  {
    "_meta": {
      "venira": {
-       "output_kind": "affected[] {id, distance, path, confidence}, summary {affected_files, affected_symbols, tests_affected}, unresolved[] (the seeds that did not resolve: symbol, reason, next_step), stats.unresolved_imports.",
+       "output_kind": "affected[] {id, distance, path, confidence}, summary {affected_files, affected_symbols, tests_affected}, unresolved[] (the seeds that did not resolve: symbol, reason, next_step), stats {unresolved_imports, min_confidence, filtered_possible}. By default only exact/likely edges are traversed; pass min_confidence=\"possible\" to follow name-matching guesses.",
        "speed_profile": "medium; reuses the dependency index (5 s cache, invalidated on writes), BFS bounded by depth. No network.",
        "use_when": "you are about to rename or change something and need which files to read and which tests to run."
      }
-   "description": "List the files and symbols affected by changing given files or symbols (direction: dependents, dependencies or both). At least one of files/symbols; a symbol seed takes {name, relative_path} (file is an alias).\nUse when: you are about to rename or change something and need which files to read and which tests to run.\nAvoid when: you want the whole graph (dependency_graph).\nOutput: affected[] {id, distance, path, confidence}, summary {affected_files, affected_symbols, tests_affected}, unresolved[] (the seeds that did not resolve: symbol, reason, next_step), stats.unresolved_imports.",
+   "description": "List the files and symbols affected by changing given files or symbols (direction: dependents, dependencies or both). At least one of files/symbols; a symbol seed takes {name, relative_path} (file is an alias).\nUse when: you are about to rename or change something and need which files to read and which tests to run.\nAvoid when: you want the whole graph (dependency_graph).\nOutput: affected[] {id, distance, path, confidence}, summary {affected_files, affected_symbols, tests_affected}, unresolved[] (the seeds that did not resolve: symbol, reason, next_step), stats {unresolved_imports, min_confidence, filtered_possible}. By default only exact/likely edges are traversed; pass min_confidence=\"possible\" to follow name-matching guesses.",
    "execution": {
      "taskSupport": "forbidden"
    },
+       "min_confidence": {
+         "description": "Only traverse edges at or above this confidence (default \"likely\"). \"exact\" = import/declared-in-one-file ties; \"likely\" = unique name match; \"possible\" = name matched several declarations (noisy at distance >= 2). Skipped edges are counted in stats.filtered_possible.",
+         "enum": [
+           "exact",
+           "likely",
+           "possible"
+         ],
+         "type": "string"
+       },
        "symbols": {
          "description": "Symbols you plan to rename/change; pass a name, or {name, relative_path} (or {name, file}) when the name is ambiguous. At least one of files/symbols is required.",
          "items": {
--- pinned/get_file_info
+++ observed/get_file_info
  {
    "_meta": {
      "venira": {
-       "output_kind": "kind, size_bytes, modified_unix_seconds. Missing path gives not_found.",
+       "output_kind": "kind, size_bytes, modified_unix_seconds, exists when missing_ok=1. Missing path gives not_found (or ok with exists:false and missing_ok=1).",
        "speed_profile": "very fast; cache validated by mtime+size.",
-       "use_when": "you need to know whether a path exists or how big it is."
+       "use_when": "you need to know whether a path exists or how big it is. Use missing_ok=1 to probe existence without failing the call or the batch."
      }
    },
    "annotations": {
-   "description": "Return kind, size and modification time of a path.\nUse when: you need to know whether a path exists or how big it is.\nAvoid when: you need the content (read_file).\nOutput: kind, size_bytes, modified_unix_seconds. Missing path gives not_found.",
+   "description": "Return kind, size and modification time of a path. `missing_ok=1` answers ok with `data.exists:false` for a missing path instead of `not_found` (works inside read_batch items too).\nUse when: you need to know whether a path exists or how big it is. Use missing_ok=1 to probe existence without failing the call or the batch.\nAvoid when: you need the content (read_file).\nOutput: kind, size_bytes, modified_unix_seconds, exists when missing_ok=1. Missing path gives not_found (or ok with exists:false and missing_ok=1).",
    "execution": {
      "taskSupport": "forbidden"
    },
+       "missing_ok": {
+         "anyOf": [
+           {
+             "type": "boolean"
+           },
+           {
+             "maximum": 1,
+             "minimum": 0,
+             "type": "integer"
+           }
+         ],
+         "description": "1 = answer ok with exists:false for a missing path instead of not_found (default 0).",
+         "maximum": 1,
+         "minimum": 0,
+         "type": "integer"
+       },
        "relative_path": {
          "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"

+ tool added: memory

--- pinned/read_batch
+++ observed/read_batch
  {
    "_meta": {
      "venira": {
+                     "missing_ok": {
+                       "anyOf": [
+                         {
+                           "type": "boolean"
+                         },
+                         {
+                           "maximum": 1,
+                           "minimum": 0,
+                           "type": "integer"
+                         }
+                       ],
+                       "description": "1 = answer ok with exists:false for a missing path instead of not_found (default 0).",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
                      "relative_path": {
                        "description": "Required (optional here so one bad item fails only itself).",
                        "type": "string"
--- pinned/switch_workspace
+++ observed/switch_workspace
  {
    "_meta": {
      "venira": {
-       "avoid_when": "one-shot tasks in the spawn directory, or when VENIRA_DYNAMIC_WORKSPACE=0 (the call is refused).",
+       "avoid_when": "one-shot tasks in the spawn directory, or under strict/balanced without VENIRA_WORKSPACE_ROOTS (the call is refused).",
        "batch_safe": false,
        "output_kind": "workspace_root (the new root), allowed_roots. All subsequent path guards and caches operate on the new root.",
        "speed_profile": "instant; runtime re-root of every path the tools resolve.",
-   "description": "Re-root the workspace to another directory at runtime (on by default; any existing directory unless VENIRA_WORKSPACE_ROOTS is set, then only inside it; VENIRA_DYNAMIC_WORKSPACE=0 opts out).\nUse when: the client spawned the server once (e.g. Claude Desktop) and the user changed to a different project folder; switch instead of restarting the client.\nAvoid when: one-shot tasks in the spawn directory, or when VENIRA_DYNAMIC_WORKSPACE=0 (the call is refused).\nOutput: workspace_root (the new root), allowed_roots. All subsequent path guards and caches operate on the new root.",
+   "description": "Re-root the workspace to another directory at runtime. Follows VENIRA_SECURITY_PROFILE: trusted/off (or VENIRA_UNRESTRICTED=1) switch anywhere existing; strict/balanced only inside VENIRA_WORKSPACE_ROOTS (unset = spawn only).\nUse when: the client spawned the server once (e.g. Claude Desktop) and the user changed to a different project folder; switch instead of restarting the client.\nAvoid when: one-shot tasks in the spawn directory, or under strict/balanced without VENIRA_WORKSPACE_ROOTS (the call is refused).\nOutput: workspace_root (the new root), allowed_roots. All subsequent path guards and caches operate on the new root.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Absolute path of the directory to make the workspace. Enabled by default; when VENIRA_WORKSPACE_ROOTS is set the target must be inside it, otherwise any existing directory may be chosen; VENIRA_DYNAMIC_WORKSPACE=0 opts out.",
+         "description": "Absolute path of the directory to make the workspace. Follows VENIRA_SECURITY_PROFILE: trusted/off switch to any existing directory; strict/balanced only inside VENIRA_WORKSPACE_ROOTS (unset = locked to the spawn workspace).",
          "minLength": 1,
          "type": "string"
        }
--- pinned/trace_status
+++ observed/trace_status
  {
    "_meta": {
      "venira": {
-   "description": "Show recent traced tool calls and the trace configuration (needs VENIRA_TRACE=1).\nUse when: you want to see what ran recently without opening the log file.\nAvoid when: tracing is off (the buffer is empty).\nOutput: enabled, file, buffered, recent[] (newest first, timestamp_ms is epoch milliseconds).",
+   "description": "Show recent traced tool calls (tracing is always on).\nUse when: you want to see what ran recently without opening the log file.\nAvoid when: tracing is off (the buffer is empty).\nOutput: enabled, file, buffered, recent[] (newest first, timestamp_ms is epoch milliseconds).",
    "execution": {
      "taskSupport": "forbidden"
    },

Changed 2026-11-14 13:25 UTC

37 tools added, 32 tools removed.

+ tool added: apply_patch

+ tool added: cache_clear

+ tool added: change_impact

+ tool added: copy_path

+ tool added: create

+ tool added: delete_path

+ tool added: dependency_graph

+ tool added: diff_files

+ tool added: edit_batch

+ tool added: edit_file

+ tool added: get_file_info

+ tool added: git_branch

+ tool added: git_commit

+ tool added: git_diff

+ tool added: git_log

+ tool added: git_stash

+ tool added: git_status

+ tool added: github_connect

+ tool added: health

+ tool added: list_files

+ tool added: move_path

+ tool added: outline_symbol

+ tool added: read_audit

+ tool added: read_batch

+ tool added: read_file

+ tool added: recent_files

+ tool added: search

+ tool added: secret

+ tool added: shell_cancel

+ tool added: shell_cancel_session

+ tool added: shell_run

+ tool added: shell_status

+ tool added: snapshot

+ tool added: switch_workspace

+ tool added: symbol_references

+ tool added: trace_status

+ tool added: write_file

tool removed: project_cache_clear

tool removed: project_change_impact

tool removed: project_create

tool removed: project_delete_path

tool removed: project_dependency_graph

tool removed: project_detect_harnesses

tool removed: project_diff_files

tool removed: project_edit_batch

tool removed: project_edit_file

tool removed: project_explain_error

tool removed: project_get_file_info

tool removed: project_github_connect

tool removed: project_health

tool removed: project_install_self

tool removed: project_list_files

tool removed: project_outline_symbol

tool removed: project_plan_read_batch

tool removed: project_read_audit

tool removed: project_read_batch

tool removed: project_read_file

tool removed: project_recent_files

tool removed: project_search

tool removed: project_secret

tool removed: project_selective_search

tool removed: project_shell_cancel

tool removed: project_shell_cancel_session

tool removed: project_shell_run

tool removed: project_shell_status

tool removed: project_snapshot

tool removed: project_symbol_references

tool removed: project_trace_status

tool removed: project_write_file

Changed 2026-11-10 14:49 UTC

32 descriptions rewritten.

--- pinned/project_cache_clear
+++ observed/project_cache_clear
  {
    "_meta": {
      "venira": {
-       "avoid_when": "normal flow (cache invalidates on write/edit/delete).",
+       "avoid_when": "normal flow: writes already invalidate caches.",
        "batch_safe": false,
-       "output_kind": "cache_clear: type, cleared per-cache entry counts.",
+       "output_kind": "cleared entry counts per cache.",
        "speed_profile": "instant; clears LRU/TTL maps only (no backend call).",
-       "use_when": "force-fresh reads after external tooling mutated files, or the cache stats show high hit/miss pressure."
+       "use_when": "reads look stale because a tool changed files outside Venira."
      }
    },
    "annotations": {
-   "description": "Clear in-process read/search/list/recent/search/shell/graph caches. Use after a toolchain generates files outside normal write flow, or to force fresh reads.\nUse when: force-fresh reads after external tooling mutated files, or the cache stats show high hit/miss pressure.\nAvoid when: normal flow (cache invalidates on write/edit/delete).\nSpeed: instant; clears LRU/TTL maps only (no backend call).\nOutput: cache_clear: type, cleared per-cache entry counts.\nBatch-safe: no",
+   "description": "Clear in-process caches (all, read, info, list, search, recent, negative, graph, shell).\nUse when: reads look stale because a tool changed files outside Venira.\nAvoid when: normal flow: writes already invalidate caches.\nOutput: cleared entry counts per cache.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Which cache to clear.",
+         "description": "Cache to clear (default all). negative = cached not_found paths; graph = import graph.",
          "enum": [
            "all",
            "shell",
--- pinned/project_change_impact
+++ observed/project_change_impact
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you need the whole graph (project_dependency_graph) or exact textual usages in one file (project_symbol_references).",
+       "avoid_when": "you want the whole graph (project_dependency_graph).",
        "batch_safe": true,
-       "output_kind": "change_impact: seed {files, symbols}, affected[] {id, distance, path, reason, confidence, symbols?}, unresolved[], summary {affected_files, affected_symbols, max_distance, tests_affected}, truncated; format=mermaid returns data.graph.",
+       "output_kind": "affected[] {id, distance, path, confidence}, summary {affected_files, affected_symbols, tests_affected}, unresolved[].",
        "speed_profile": "medium; reuses the dependency index (5 s cache, invalidated on writes), BFS bounded by depth. No network.",
-       "use_when": "before renaming/changing a function or file, to list the dependents you should read/test (direction=dependents), or the dependencies a module relies on."
+       "use_when": "you are about to rename or change something and need which files to read and which tests to run."
      }
    },
    "annotations": {
-   "description": "Answer \"if I change these files/symbols, what depends on them?\" with a bounded reverse (or forward) closure: affected files, distance, path, reason and confidence, plus affected symbols and a separate test count.\nUse when: before renaming/changing a function or file, to list the dependents you should read/test (direction=dependents), or the dependencies a module relies on.\nAvoid when: you need the whole graph (project_dependency_graph) or exact textual usages in one file (project_symbol_references).\nSpeed: medium; reuses the dependency index (5 s cache, invalidated on writes), BFS bounded by depth. No network.\nOutput: change_impact: seed {files, symbols}, affected[] {id, distance, path, reason, confidence, symbols?}, unresolved[], summary {affected_files, affected_symbols, max_distance, tests_affected}, truncated; format=mermaid returns data.graph.\nBatch-safe: yes",
+   "description": "List the files and symbols affected by changing given files or symbols (direction: dependents, dependencies or both). At least one of files/symbols; a symbol seed takes {name, relative_path} (file is an alias).\nUse when: you are about to rename or change something and need which files to read and which tests to run.\nAvoid when: you want the whole graph (project_dependency_graph).\nOutput: affected[] {id, distance, path, confidence}, summary {affected_files, affected_symbols, tests_affected}, unresolved[].",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "BFS hop cap (default 5).",
+         "description": "Max hops from the seeds (default 5).",
          "maximum": 10,
          "minimum": 1,
          "type": "integer"
-         "description": "Workspace paths you plan to edit.",
+         "description": "Workspace paths you plan to edit. At least one of files/symbols is required.",
          "items": {
            "maxLength": 500,
            "type": "string"
-         "description": "Symbols you plan to rename/change; pass a name, or {name, file} when the name is ambiguous.",
+         "description": "Symbols you plan to rename/change; pass a name, or {name, relative_path} (or {name, file}) when the name is ambiguous. At least one of files/symbols is required.",
          "items": {
            "anyOf": [
              {
+                   "description": "Alias of relative_path (relative_path wins when both are given).",
                    "maxLength": 500,
                    "type": "string"
                  },
+                   "description": "Symbol name.",
                    "maxLength": 200,
                    "type": "string"
                  },
+                   "description": "File the symbol is declared in; preferred over file.",
                    "maxLength": 500,
                    "type": "string"
                  }
--- pinned/project_create
+++ observed/project_create
  {
    "_meta": {
      "venira": {
-       "avoid_when": "editing an existing file (project_edit_file/project_write_file); never use mode=overwrite unless a pre-write project_snapshot covers the existing contents.",
+       "avoid_when": "you write file content (project_write_file) or edit existing content (project_edit_file).",
        "batch_safe": false,
-       "output_kind": "directory_created or file_written (data kind depends on the op).",
-       "speed_profile": "fast; triggers cache invalidation on write / new directory.",
-       "use_when": "create a directory or new file; if replacing an existing file, first create a scoped project_snapshot, confirm it captured the target, and keep its id."
+       "output_kind": "directory_created {relative_path, created, parents_created}.",
+       "speed_profile": "fast; triggers cache invalidation for the new directory.",
+       "use_when": "you need an empty directory. For a file use project_write_file, which also creates parent folders."
      }
    },
    "annotations": {
-   "description": "Create a directory OR a file in ONE call. For an existing file, mode=overwrite replaces its contents: create and verify a scoped project_snapshot first.\nUse when: create a directory or new file; if replacing an existing file, first create a scoped project_snapshot, confirm it captured the target, and keep its id.\nAvoid when: editing an existing file (project_edit_file/project_write_file); never use mode=overwrite unless a pre-write project_snapshot covers the existing contents.\nSpeed: fast; triggers cache invalidation on write / new directory.\nOutput: directory_created or file_written (data kind depends on the op).\nBatch-safe: no",
+   "description": "Create a directory; missing parents are created unless create_dirs=0.\nUse when: you need an empty directory. For a file use project_write_file, which also creates parent folders.\nAvoid when: you write file content (project_write_file) or edit existing content (project_edit_file).\nOutput: directory_created {relative_path, created, parents_created}.",
    "execution": {
      "taskSupport": "forbidden"
    },
+     "additionalProperties": {},
      "properties": {
-       "content": {
-         "type": "string"
-       },
        "create_dirs": {
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 creates missing parent directories (default 1); 0 fails when a parent is missing.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-       "expected_sha256": {
-         "type": "string"
-       },
-       "kind": {
-         "enum": [
-           "file",
-           "directory"
-         ],
-         "type": "string"
-       },
-       "mode": {
-         "description": "overwrite replaces existing contents; create and verify a scoped project_snapshot first. create fails if the path exists; append adds to the end.",
-         "enum": [
-           "create",
-           "overwrite",
-           "append"
-         ],
-         "type": "string"
-       },
        "reason": {
-         "description": "Why this change is made (e.g. \"sua loi null pointer o dong 45\"). Recorded in the audit trail so later sessions know the intent. Single line, max 400 chars, secrets are redacted.",
+         "description": "Optional why (max 400 chars), audit-logged. Required only on project_ci_control.",
          "maxLength": 400,
          "type": "string"
        },
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        }
      },
-       "relative_path",
-       "kind"
+       "relative_path"
      ],
      "type": "object"
    },
-   "title": "Create file or directory"
+   "title": "Create directory"
  }
--- pinned/project_delete_path
+++ observed/project_delete_path
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the target is ambiguous or a pre-delete snapshot is missing, truncated, or skipped the target. This op is not undoable; capture and verify a checkpoint first.",
+       "avoid_when": "the target is uncertain (check with project_get_file_info or project_list_files).",
        "batch_safe": false,
-       "output_kind": "path_deleted: entries_deleted, bytes_deleted.",
+       "output_kind": "entries_deleted, bytes_deleted. Missing path gives not_found.",
        "speed_profile": "fast; clears the read/list/search cache.",
-       "use_when": "only after creating a scoped project_snapshot for the exact target, confirming file_count/truncated/skipped cover the intended files, and keeping its id for recovery."
+       "use_when": "you remove files or folders. Take a project_snapshot first when they are not in git."
      }
    },
    "annotations": {
-   "description": "Delete a file or directory (directories require recursive=1). Create and verify a scoped snapshot before using this irreversible tool; do not delete if the checkpoint is incomplete.\nUse when: only after creating a scoped project_snapshot for the exact target, confirming file_count/truncated/skipped cover the intended files, and keeping its id for recovery.\nAvoid when: the target is ambiguous or a pre-delete snapshot is missing, truncated, or skipped the target. This op is not undoable; capture and verify a checkpoint first.\nSpeed: fast; clears the read/list/search cache.\nOutput: path_deleted: entries_deleted, bytes_deleted.\nBatch-safe: no",
+   "description": "Delete a file or directory (recursive=1 is required for directories). Not undoable.\nUse when: you remove files or folders. Take a project_snapshot first when they are not in git.\nAvoid when: the target is uncertain (check with project_get_file_info or project_list_files).\nOutput: entries_deleted, bytes_deleted. Missing path gives not_found.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Why this change is made (e.g. \"sua loi null pointer o dong 45\"). Recorded in the audit trail so later sessions know the intent. Single line, max 400 chars, secrets are redacted.",
+         "description": "Optional why (max 400 chars), audit-logged. Required only on project_ci_control.",
          "maxLength": 400,
          "type": "string"
        },
--- pinned/project_dependency_graph
+++ observed/project_dependency_graph
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you only need usages of one symbol in one file (project_symbol_references) or a text search (project_search).",
+       "avoid_when": "you need usages of one symbol (project_symbol_references) or the impact of an edit (project_change_impact).",
        "batch_safe": true,
-       "output_kind": "dependency_graph: nodes[] {id, type, language, loc}, edges[] {from, to, type (import|extends|implements|references), confidence, line, via}, external[] {id, used_by}, unresolved[], stats, truncated; format=dot|mermaid returns data.graph.",
+       "output_kind": "nodes[], edges[] {from, to, type, confidence}, external[], unresolved[], stats, truncated. dot and mermaid return data.graph.",
        "speed_profile": "medium; bounded walk (<=5000 files / 64 MB), parser-lite line scan, 5 s index cache invalidated on writes. No network.",
-       "use_when": "you need the import graph, a module map to render, or the files/symbols a change can reach before refactoring."
+       "use_when": "you want module structure or what a subtree depends on. Narrow with relative_path, depth, languages."
      }
    },
    "annotations": {
-   "description": "Build a deterministic file/symbol dependency graph for TypeScript/JavaScript, Python, Rust, Go, Java and Kotlin (module declarations, pub mod, use crate::/super::, extern crate, go.mod module resolution, import (...) blocks, relative imports, require(), dynamic import(), extends/implements, cross-file symbol references). Renders as JSON, DOT or Mermaid.\nUse when: you need the import graph, a module map to render, or the files/symbols a change can reach before refactoring.\nAvoid when: you only need usages of one symbol in one file (project_symbol_references) or a text search (project_search).\nSpeed: medium; bounded walk (<=5000 files / 64 MB), parser-lite line scan, 5 s index cache invalidated on writes. No network.\nOutput: dependency_graph: nodes[] {id, type, language, loc}, edges[] {from, to, type (import|extends|implements|references), confidence, line, via}, external[] {id, used_by}, unresolved[], stats, truncated; format=dot|mermaid returns data.graph.\nBatch-safe: yes",
+   "description": "Build the import and reference graph for TypeScript/JavaScript, Python, Rust, Go, Java and Kotlin. format: json, dot or mermaid.\nUse when: you want module structure or what a subtree depends on. Narrow with relative_path, depth, languages.\nAvoid when: you need usages of one symbol (project_symbol_references) or the impact of an edit (project_change_impact).\nOutput: nodes[], edges[] {from, to, type, confidence}, external[], unresolved[], stats, truncated. dot and mermaid return data.graph.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Max edges (default 2000).",
+         "description": "Max edges kept; more sets truncated (default 2000).",
          "maximum": 5000,
          "minimum": 1,
          "type": "integer"
--- pinned/project_detect_harnesses
+++ observed/project_detect_harnesses
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you already know the config path (skip straight to project_install_self).",
+       "avoid_when": "you already know the config path.",
        "batch_safe": true,
-       "output_kind": "harness_detect: detected[] (found harnesses), harnesses[] {harness, detected, config_path, format, note}.",
+       "output_kind": "harnesses[] {harness, detected, config_path, format, note}.",
        "speed_profile": "fast; filesystem checks, no writes.",
-       "use_when": "before installing venira, to know which client configs exist and can be updated."
+       "use_when": "before project_install_self, to see which configs exist."
      }
    },
    "annotations": {
-   "description": "Detect which MCP-client harnesses (OpenCode/Claude/Cursor/Codex/Kimi/DeepSeek/Antigravity) have a config on this machine.\nUse when: before installing venira, to know which client configs exist and can be updated.\nAvoid when: you already know the config path (skip straight to project_install_self).\nSpeed: fast; filesystem checks, no writes.\nOutput: harness_detect: detected[] (found harnesses), harnesses[] {harness, detected, config_path, format, note}.\nBatch-safe: yes",
+   "description": "Find MCP client configs on this machine (OpenCode, Claude Desktop, Cursor, Codex, Kimi, DeepSeek, Antigravity).\nUse when: before project_install_self, to see which configs exist.\nAvoid when: you already know the config path.\nOutput: harnesses[] {harness, detected, config_path, format, note}.",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_diff_files
+++ observed/project_diff_files
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the two files are in different languages or one is binary; large binaries are not supported.",
+       "avoid_when": "binary files, or git history (run git with project_shell_run).",
        "batch_safe": true,
-       "output_kind": "diff_files: lines_added, lines_removed, unified_diff, truncated.",
+       "output_kind": "lines_added, lines_removed, unified_diff, truncated.",
        "speed_profile": "medium; LCS-based diff over the two full texts, bounded by max_lines.",
-       "use_when": "comparing two versions of a file, or reviewing changes before/after an edit."
+       "use_when": "you compare two versions of a file, such as a backup and the current one."
      }
    },
    "annotations": {
-   "description": "Unified (git-style) diff between two workspace files. Reports lines_added/lines_removed and the full hunk text.\nUse when: comparing two versions of a file, or reviewing changes before/after an edit.\nAvoid when: the two files are in different languages or one is binary; large binaries are not supported.\nSpeed: medium; LCS-based diff over the two full texts, bounded by max_lines.\nOutput: diff_files: lines_added, lines_removed, unified_diff, truncated.\nBatch-safe: yes",
+   "description": "Unified diff between two workspace files.\nUse when: you compare two versions of a file, such as a backup and the current one.\nAvoid when: binary files, or git history (run git with project_shell_run).\nOutput: lines_added, lines_removed, unified_diff, truncated.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Unchanged context lines around each hunk (default 3, max 50).",
          "maximum": 50,
          "minimum": 0,
          "type": "integer"
+         "description": "Max diff lines returned (default 500, max 10000).",
          "maximum": 10000,
          "minimum": 10,
          "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        },
        "relative_path_b": {
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        }
      },
--- pinned/project_edit_batch
+++ observed/project_edit_batch
  {
    "_meta": {
      "venira": {
-       "avoid_when": "a single edit (project_edit_file) or a whole-file rewrite (project_write_file).",
+       "avoid_when": "you make one edit (project_edit_file).",
        "batch_safe": false,
-       "output_kind": "batch: responses[] {ok, response|error}, atomic metadata with executed/skipped indexes and rollback status.",
+       "output_kind": "success: per-edit {relative_path, replacements, sha256_after}. Failure: ok=false, error batch_failed, data {executed, skipped, rollback_succeeded, snapshot_id}.",
        "speed_profile": "depends on item count; each runs edit_file and clears caches.",
-       "use_when": "before editing existing files in a multi-edit batch, create a scoped project_snapshot when it spans multiple files/sections or needs rollback after later checks. Batch rollback covers an in-batch failure only; it does not undo a successful batch after tests fail."
+       "use_when": "a change spans several files or sections and must land completely or not at all."
      }
    },
    "annotations": {
-   "description": "Apply multiple edit_file operations atomically in one call; aborts after the first failure and restores the pre-batch snapshot when possible.\nUse when: before editing existing files in a multi-edit batch, create a scoped project_snapshot when it spans multiple files/sections or needs rollback after later checks. Batch rollback covers an in-batch failure only; it does not undo a successful batch after tests fail.\nAvoid when: a single edit (project_edit_file) or a whole-file rewrite (project_write_file).\nSpeed: depends on item count; each runs edit_file and clears caches.\nOutput: batch: responses[] {ok, response|error}, atomic metadata with executed/skipped indexes and rollback status.\nBatch-safe: no",
+   "description": "Apply edits across one or more files all-or-nothing. Each item takes edit_file arguments (relative_path, old_text, new_text, ...). The first failure rolls back every touched file from an automatic snapshot and skips the rest.\nUse when: a change spans several files or sections and must land completely or not at all.\nAvoid when: you make one edit (project_edit_file).\nOutput: success: per-edit {relative_path, replacements, sha256_after}. Failure: ok=false, error batch_failed, data {executed, skipped, rollback_succeeded, snapshot_id}.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Array of edit_file arguments. For existing files across multiple edits, create a scoped project_snapshot first if later validation may require full rollback; automatic rollback only handles in-batch failures.",
+         "description": "edit_file argument objects (typed like project_edit_file). Unknown fields are rejected with a did-you-mean hint and nothing is applied. Snapshot first when later checks may need a full rollback; automatic rollback covers in-batch failures only.",
          "items": {
            "additionalProperties": {},
-           "propertyNames": {
-             "type": "string"
+           "properties": {
+             "edits": {
+               "description": "Several replacements in this file; wins over old_text/new_text.",
+               "items": {
+                 "properties": {
+                   "new_text": {
+                     "description": "Replacement text.",
+                     "type": "string"
+                   },
+                   "old_text": {
+                     "description": "Exact text to replace.",
+                     "minLength": 1,
+                     "type": "string"
+                   },
+                   "replace_all": {
+                     "description": "1 replaces every match; 0 (default) requires exactly one match.",
+                     "maximum": 1,
+                     "minimum": 0,
+                     "type": "integer"
+                   }
+                 },
+                 "required": [
+                   "old_text",
+                   "new_text",
+                   "replace_all"
+                 ],
+                 "type": "object"
+               },
+               "maxItems": 64,
+               "type": "array"
+             },
+             "expected_sha256": {
+               "description": "Hex SHA-256 of the current full content; edit refused if it differs; when given, the result also reports verified.",
+               "type": "string"
+             },
+             "new_text": {
+               "description": "Replacement text (see project_edit_file).",
+               "type": "string"
+             },
+             "old_text": {
+               "description": "Exact text to replace (see project_edit_file).",
+               "minLength": 1,
+               "type": "string"
+             },
+             "reason": {
+               "description": "Optional why (max 400 chars), audit-logged. Required only on project_ci_control.",
+               "maxLength": 400,
+               "type": "string"
+             },
+             "relative_path": {
+               "description": "File to edit (required per item).",
+               "type": "string"
+             },
+             "replace_all": {
+               "description": "1 replaces every match; 0 (default) requires exactly one match.",
+               "maximum": 1,
+               "minimum": 0,
+               "type": "integer"
+             }
            },
+           "required": [
+             "relative_path"
+           ],
            "type": "object"
          },
          "maxItems": 64,
+         "description": "Max serialized bytes per edit item (default 1 MiB).",
          "maximum": 1048576,
          "minimum": 256,
          "type": "integer"
--- pinned/project_edit_file
+++ observed/project_edit_file
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the whole file must change (project_write_file), or you have not read the file to know old_text.",
+       "avoid_when": "you rewrite the whole file (project_write_file) or change several files at once (project_edit_batch).",
        "batch_safe": false,
-       "output_kind": "file_written: replacements, sha256_before/after, verified (with guard=sha256).",
+       "output_kind": "replacements, sha256_before, sha256_after, verified (when expected_sha256 is given). Failures: old_text_not_found, old_text_ambiguous (returns each match with line context).",
        "speed_profile": "fast; clears the read/list/search cache for the affected path.",
-       "use_when": "change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify. Before editing 2+ files or 2+ sections, create a scoped project_snapshot and confirm coverage."
+       "use_when": "you make a targeted change. old_text must match exactly once; replace_all=1 replaces every match. pass expected_sha256 to refuse stale content and get a verified re-read."
      }
    },
    "annotations": {
-   "description": "Edit a file by exact text replacement: one old_text/new_text pair, or edits[] for multiple sections. Supports TOCTOU guard mode (guard=sha256) for atomic read-edit-verify cycle.\nUse when: change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify. Before editing 2+ files or 2+ sections, create a scoped project_snapshot and confirm coverage.\nAvoid when: the whole file must change (project_write_file), or you have not read the file to know old_text.\nSpeed: fast; clears the read/list/search cache for the affected path.\nOutput: file_written: replacements, sha256_before/after, verified (with guard=sha256).\nBatch-safe: no",
+   "description": "Replace exact text: old_text to new_text, or edits[] for several replacements in one file (edits[] wins).\nUse when: you make a targeted change. old_text must match exactly once; replace_all=1 replaces every match. pass expected_sha256 to refuse stale content and get a verified re-read.\nAvoid when: you rewrite the whole file (project_write_file) or change several files at once (project_edit_batch).\nOutput: replacements, sha256_before, sha256_after, verified (when expected_sha256 is given). Failures: old_text_not_found, old_text_ambiguous (returns each match with line context).",
    "execution": {
      "taskSupport": "forbidden"
    },
+     "additionalProperties": {},
      "properties": {
-       "case_insensitive": {
-         "description": "P2: Case-insensitive fuzzy matching; 1=on, 0=off.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
-       },
        "edits": {
-         "description": "Multiple section replacements in this file. Create a scoped project_snapshot first when applying 2+ edits or when the change is hard to recreate.",
+         "description": "Multiple section replacements in this file; takes precedence over old_text/new_text. Create a scoped project_snapshot first when applying 2+ edits or when the change is hard to recreate.",
          "items": {
            "properties": {
              "new_text": {
+               "description": "Replacement text.",
                "type": "string"
              },
              "old_text": {
+               "description": "Exact text to replace.",
                "minLength": 1,
                "type": "string"
              },
-               "description": "Numeric flag: 1=enabled, 0=disabled.",
+               "description": "1 replaces every match; 0 (default) requires exactly one match.",
                "maximum": 1,
                "minimum": 0,
                "type": "integer"
-             "new_text"
+             "new_text",
+             "replace_all"
            ],
            "type": "object"
          },
-         "type": "string"
-       },
-       "fuzzy_distance": {
-         "description": "P2: Max Levenshtein distance for fuzzy matching (default 3).",
-         "maximum": 10,
-         "minimum": 0,
-         "type": "integer"
-       },
-       "guard": {
-         "description": "TOCTOU guard: 'sha256' reads fresh content, verifies expected_sha256, applies edits, writes, then re-reads to verify content+sha256 match. Provides atomic read-edit-verify cycle.",
-         "enum": [
-           "sha256"
-         ],
+         "description": "Hex SHA-256 of the file's current full content. The edit is refused if the file on disk differs. Use sha256_after from your last write/edit of this file; read_file's sha256 only matches when the whole file was returned. When given, the result is re-read after the write and reports verified.",
          "type": "string"
        },
-       "ignore_indentation": {
-         "description": "P2: Ignore leading whitespace differences in fuzzy matching; 1=on, 0=off.",
-         "maximum": 1,
-         "minimum": 0,
-         "type": "integer"
-       },
        "new_text": {
+         "description": "Replacement text (paired with old_text; ignored when edits[] is given).",
          "type": "string"
        },
        "old_text": {
+         "description": "Exact text to replace. Must match exactly once unless replace_all=1. Ignored when edits[] is given.",
          "minLength": 1,
          "type": "string"
        },
-       "old_text_fuzzy": {
-         "description": "P2: Fuzzy-match fallback for old_text (used when exact match fails and VENIRA_EDIT_FUZZY=1).",
-         "type": "string"
-       },
        "reason": {
-         "description": "Why this change is made (e.g. \"sua loi null pointer o dong 45\"). Recorded in the audit trail so later sessions know the intent. Single line, max 400 chars, secrets are redacted.",
+         "description": "Optional why (max 400 chars), audit-logged. Required only on project_ci_control.",
          "maxLength": 400,
          "type": "string"
        },
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        },
        "replace_all": {
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 replaces every match; 0 (default) requires exactly one match.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
--- pinned/project_explain_error
+++ observed/project_explain_error
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you already know the cause and only need the file contents (use project_read_file, which also accepts ranges).",
+       "avoid_when": "you already know the cause.",
        "batch_safe": true,
-       "output_kind": "explain_error: matched, summary, error_line, language, diagnoses[] {rule_id, title, likely_cause, suggested_fix[], retry_hint?, next_actions[]}, next_actions[].",
+       "output_kind": "matched, summary, diagnoses[] {title, likely_cause, suggested_fix[], next_actions[]}.",
        "speed_profile": "pure local rules, < 1 ms; no network and no model call.",
-       "use_when": "a command, test, build or provider call failed and you want the fastest route to the fix (feed it the stderr tail or the CI log tail)."
+       "use_when": "a command, build or provider call failed and the cause is unclear. Pass error_text or log_tail."
      }
    },
    "annotations": {
-   "description": "Diagnose a failure from its error text / log tail: known signatures (errno, TypeScript, Python, git, npm, GitHub, venira codes) → likely cause + ready-to-send next tool calls. Rule-based, offline, instant.\nUse when: a command, test, build or provider call failed and you want the fastest route to the fix (feed it the stderr tail or the CI log tail).\nAvoid when: you already know the cause and only need the file contents (use project_read_file, which also accepts ranges).\nSpeed: pure local rules, < 1 ms; no network and no model call.\nOutput: explain_error: matched, summary, error_line, language, diagnoses[] {rule_id, title, likely_cause, suggested_fix[], retry_hint?, next_actions[]}, next_actions[].\nBatch-safe: yes",
+   "description": "Match an error or log tail against known failure signatures (TypeScript, Python, git, npm, GitHub, Venira codes) and return the likely cause, fixes and ready next_actions. Offline rules, no model call.\nUse when: a command, build or provider call failed and the cause is unclear. Pass error_text or log_tail.\nAvoid when: you already know the cause.\nOutput: matched, summary, diagnoses[] {title, likely_cause, suggested_fix[], next_actions[]}.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Tail of the failing output (e.g. project_ci_logs / project_shell_status text).",
+         "description": "Tail of the failing output (e.g. project_ci_logs / project_shell_status text). One of error_text/log_tail is required.",
          "maxLength": 32768,
          "type": "string"
        }
--- pinned/project_get_file_info
+++ observed/project_get_file_info
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you need the file's contents (project_read_file).",
+       "avoid_when": "you need the content (project_read_file).",
        "batch_safe": true,
-       "output_kind": "file_info: relative_path, kind, size_bytes, modified_unix_seconds.",
+       "output_kind": "kind, size_bytes, modified_unix_seconds. Missing path gives not_found.",
        "speed_profile": "very fast; cache validated by mtime+size.",
-       "use_when": "you only need size/mtime/kind, or want to check that a path exists."
+       "use_when": "you need to know whether a path exists or how big it is."
      }
    },
    "annotations": {
-   "description": "File/directory metadata (kind, size, modification time).\nUse when: you only need size/mtime/kind, or want to check that a path exists.\nAvoid when: you need the file's contents (project_read_file).\nSpeed: very fast; cache validated by mtime+size.\nOutput: file_info: relative_path, kind, size_bytes, modified_unix_seconds.\nBatch-safe: yes",
+   "description": "Return kind, size and modification time of a path.\nUse when: you need to know whether a path exists or how big it is.\nAvoid when: you need the content (project_read_file).\nOutput: kind, size_bytes, modified_unix_seconds. Missing path gives not_found.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        }
      },
--- pinned/project_github_connect
+++ observed/project_github_connect
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the user only needs GitHub public read access or has already configured a token.",
+       "avoid_when": "you only need public read access, or a token is already configured.",
        "batch_safe": false,
-       "output_kind": "github_connect: start returns verification_uri, user_code, pending_id and expiry; poll returns pending, denied, expired or connected (never a token).",
+       "output_kind": "start: verification_uri, user_code, pending_id, expiry. poll: pending | denied | expired | connected.",
        "speed_profile": "start returns a short-lived verification code; poll only at the interval GitHub specifies.",
-       "use_when": "the user wants to connect or replace the local GitHub credential without pasting a token into chat."
+       "use_when": "the user wants to connect or replace the GitHub credential without pasting a token."
      }
    },
    "annotations": {
-   "description": "Connect GitHub through its Device Flow. The user authorizes at github.com; access and refresh tokens are saved in the encrypted local vault and are never returned.\nUse when: the user wants to connect or replace the local GitHub credential without pasting a token into chat.\nAvoid when: the user only needs GitHub public read access or has already configured a token.\nSpeed: start returns a short-lived verification code; poll only at the interval GitHub specifies.\nOutput: github_connect: start returns verification_uri, user_code, pending_id and expiry; poll returns pending, denied, expired or connected (never a token).\nBatch-safe: no",
+   "description": "Connect GitHub with Device Flow. action=start returns verification_uri and user_code: show them to the user, then action=poll with pending_id after they authorize. Tokens go to the encrypted vault and are never returned.\nUse when: the user wants to connect or replace the GitHub credential without pasting a token.\nAvoid when: you only need public read access, or a token is already configured.\nOutput: start: verification_uri, user_code, pending_id, expiry. poll: pending | denied | expired | connected.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "start: begin the device flow (returns verification_uri + user_code). poll: check with pending_id whether the user authorized.",
          "enum": [
            "start",
            "poll"
--- pinned/project_health
+++ observed/project_health
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you just need to read/write files normally.",
+       "avoid_when": "normal file work.",
        "batch_safe": false,
-       "output_kind": "health: notice, server, corehost, capability, queue, caches, shells, metrics, audit.",
+       "output_kind": "server, corehost, queue, caches, shells, posture {level, findings}, snapshots, metrics.",
        "speed_profile": "fast (~a few ms + 1 audit DB query); set include_audit=0 to skip the DB query.",
-       "use_when": "debugging slowness/errors, checking the backend/DB/audit before reporting, or inspecting this session's cache/metrics."
+       "use_when": "you debug slowness or errors, or want the security warnings before risky work. include_audit=0 skips the audit query."
      }
    },
    "annotations": {
-   "description": "Server diagnostics: corehost/data dir/audit DB, capability, queue depth, cache hit-rate, running shells, p50/p95 metrics, plus a security-limit notice (guard rail, not sandbox).\nUse when: debugging slowness/errors, checking the backend/DB/audit before reporting, or inspecting this session's cache/metrics.\nAvoid when: you just need to read/write files normally.\nSpeed: fast (~a few ms + 1 audit DB query); set include_audit=0 to skip the DB query.\nOutput: health: notice, server, corehost, capability, queue, caches, shells, metrics, audit.\nBatch-safe: no",
+   "description": "Server diagnostics: version, workspace, security posture and warnings, caches, queue, running shells, latency, snapshot store, audit status.\nUse when: you debug slowness or errors, or want the security warnings before risky work. include_audit=0 skips the audit query.\nAvoid when: normal file work.\nOutput: server, corehost, queue, caches, shells, posture {level, findings}, snapshots, metrics.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 includes the audit-log summary in the result (default 1); 0 skips the audit DB query.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
--- pinned/project_install_self
+++ observed/project_install_self
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the config path is unknown (run project_detect_harnesses first), or the user wants a dry-run (set dry_run=1).",
+       "avoid_when": "the config path is unknown (project_detect_harnesses first).",
        "batch_safe": false,
-       "output_kind": "install_self: {harness, config_path, status (installed|already_present|config_missing|error), needs_restart, error?}.",
+       "output_kind": "harness, config_path, status (installed|already_present|config_missing|error), needs_restart.",
        "speed_profile": "fast; one atomic write per config. Always backs up the original to <file>.venira-bak.",
-       "use_when": "a user asks to 'install venira into <client>' — add the MCP server block to that client's config file."
+       "use_when": "the user asks to install Venira into a client."
      }
    },
    "annotations": {
-   "description": "Add the venira MCP entry to a target client's config (OpenCode/Claude/Cursor/Codex/Kimi/DeepSeek/Antigravity). Atomic + backup.\nUse when: a user asks to 'install venira into <client>' — add the MCP server block to that client's config file.\nAvoid when: the config path is unknown (run project_detect_harnesses first), or the user wants a dry-run (set dry_run=1).\nSpeed: fast; one atomic write per config. Always backs up the original to <file>.venira-bak.\nOutput: install_self: {harness, config_path, status (installed|already_present|config_missing|error), needs_restart, error?}.\nBatch-safe: no",
+   "description": "Add the Venira MCP server entry to a client's config. Atomic write with a backup at <file>.venira-bak. dry_run=1 previews.\nUse when: the user asks to install Venira into a client.\nAvoid when: the config path is unknown (project_detect_harnesses first).\nOutput: harness, config_path, status (installed|already_present|config_missing|error), needs_restart.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Which client's config to update (see project_detect_harnesses).",
          "enum": [
            "opencode",
            "claude_desktop",
--- pinned/project_list_files
+++ observed/project_list_files
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you only need one file's metadata (project_get_file_info) or one file's contents (project_read_file).",
+       "avoid_when": "you know the file (project_read_file) or want what changed lately (project_recent_files).",
        "batch_safe": true,
-       "output_kind": "file_list: entries, truncated, hint.",
+       "output_kind": "entries[] {relative_path, kind, size_bytes}, truncated.",
        "speed_profile": "fast; TTL cache 1.5s, auto-wiped on write/edit/delete.",
-       "use_when": "you need to see the directory tree, check a path, or list files before reading."
+       "use_when": "you need the directory tree or want to confirm a path exists."
      }
    },
    "annotations": {
-   "description": "List files/directories in the workspace. depth 1..3 shows the tree in a single call.\nUse when: you need to see the directory tree, check a path, or list files before reading.\nAvoid when: you only need one file's metadata (project_get_file_info) or one file's contents (project_read_file).\nSpeed: fast; TTL cache 1.5s, auto-wiped on write/edit/delete.\nOutput: file_list: entries, truncated, hint.\nBatch-safe: yes",
+   "description": "List files and directories (depth 1-3, limit up to 200). include_ignored=1 also lists ignored folders.\nUse when: you need the directory tree or want to confirm a path exists.\nAvoid when: you know the file (project_read_file) or want what changed lately (project_recent_files).\nOutput: entries[] {relative_path, kind, size_bytes}, truncated.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Tree depth (default 1, max 3).",
          "maximum": 3,
          "minimum": 1,
          "type": "integer"
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 also lists ignored folders (default 0).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "Max entries (default 200, max 200).",
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        }
      },
--- pinned/project_outline_symbol
+++ observed/project_outline_symbol
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you need every usage of a symbol (project_symbol_references) or a text-only diff (project_diff_files).",
+       "avoid_when": "you need usages (project_symbol_references), a text search (project_search) or the text itself (project_read_file).",
        "batch_safe": true,
-       "output_kind": "outline_symbol: total_symbols, symbols[] {name, kind, line, signature}.",
+       "output_kind": "total_symbols, symbols[] {name, kind, line, signature}.",
        "speed_profile": "fast; single-file regex scan, no external indexer.",
-       "use_when": "you need to see the structure / top-level symbols of a file before reading or refactoring it."
+       "use_when": "you want a file's structure before reading or refactoring it."
      }
    },
    "annotations": {
-   "description": "Parse a source file and return its symbol outline (functions, classes, types, interfaces) with line numbers.\nUse when: you need to see the structure / top-level symbols of a file before reading or refactoring it.\nAvoid when: you need every usage of a symbol (project_symbol_references) or a text-only diff (project_diff_files).\nSpeed: fast; single-file regex scan, no external indexer.\nOutput: outline_symbol: total_symbols, symbols[] {name, kind, line, signature}.\nBatch-safe: yes",
+   "description": "List a source file's top-level symbols (functions, classes, types, interfaces) with line numbers.\nUse when: you want a file's structure before reading or refactoring it.\nAvoid when: you need usages (project_symbol_references), a text search (project_search) or the text itself (project_read_file).\nOutput: total_symbols, symbols[] {name, kind, line, signature}.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 includes class/interface symbols (default 1).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 includes function symbols (default 1).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "Optional language hint (e.g. 'ts', 'py'); the parser auto-detects from the file extension when omitted. The hint is advisory.",
          "type": "string"
        },
        "max_symbols": {
+         "description": "Max symbols returned (default 200, max 500).",
          "maximum": 500,
          "minimum": 1,
          "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        }
      },
--- pinned/project_plan_read_batch
+++ observed/project_plan_read_batch
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you already know the exact files (call project_read_batch directly), or the task is a one-line lookup (project_search).",
+       "avoid_when": "you know the files (project_read_batch) or only need one string or name (project_search).",
        "batch_safe": true,
-       "output_kind": "plan_read_batch: task, keywords[], searched, candidates[] {relative_path, reason, hits}, steps[] {tool, arguments, why}, estimated_ms, notes.",
+       "output_kind": "keywords[], candidates[] {relative_path, reason, hits}, steps[] {tool, arguments, why}.",
        "speed_profile": "1-3 bounded content searches (~20 ms each) + local ranking; no file contents are returned.",
-       "use_when": "starting a task in an unfamiliar area and you do not know which files matter yet (one call instead of guess-read-repeat)."
+       "use_when": "you start in an unfamiliar area: run steps[0] instead of guessing files."
      }
    },
    "annotations": {
-   "description": "Plan a read: extract keywords from the task, run bounded content + file-name searches (+recent files), rank candidate source files by hits, path/name match and prose weight (build output, DB/log artifacts excluded), and return a ready project_read_batch call with a calibrated estimate. Deterministic planner, no model call.\nUse when: starting a task in an unfamiliar area and you do not know which files matter yet (one call instead of guess-read-repeat).\nAvoid when: you already know the exact files (call project_read_batch directly), or the task is a one-line lookup (project_search).\nSpeed: 1-3 bounded content searches (~20 ms each) + local ranking; no file contents are returned.\nOutput: plan_read_batch: task, keywords[], searched, candidates[] {relative_path, reason, hits}, steps[] {tool, arguments, why}, estimated_ms, notes.\nBatch-safe: yes",
+   "description": "Turn a task description into ranked candidate files and a ready-to-run project_read_batch call (keyword search plus recent files; deterministic, returns no file contents).\nUse when: you start in an unfamiliar area: run steps[0] instead of guessing files.\nAvoid when: you know the files (project_read_batch) or only need one string or name (project_search).\nOutput: keywords[], candidates[] {relative_path, reason, hits}, steps[] {tool, arguments, why}.",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_read_audit
+++ observed/project_read_audit
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you only need the live cache/metric report (project_health include_audit=1) — that one is faster.",
+       "avoid_when": "you want live metrics (project_health).",
        "batch_safe": true,
-       "output_kind": "audit_read: rows[] (newest first), count, truncated, db_path.",
+       "output_kind": "rows[], count, truncated, chain_ok (verify=1).",
        "speed_profile": "fast; one bounded SQLite read (readonly, WAL-safe).",
-       "use_when": "you need to inspect what operations were recorded (audit trail) — e.g. compliance or debugging a prior action."
+       "use_when": "you review what was done and why (the reason field), in this or an earlier session."
      }
    },
    "annotations": {
-   "description": "Read recent rows from the SQLite audit log (WAL). Filter by session/operation/outcome; bounded by limit.\nUse when: you need to inspect what operations were recorded (audit trail) — e.g. compliance or debugging a prior action.\nAvoid when: you only need the live cache/metric report (project_health include_audit=1) — that one is faster.\nSpeed: fast; one bounded SQLite read (readonly, WAL-safe).\nOutput: audit_read: rows[] (newest first), count, truncated, db_path.\nBatch-safe: yes",
+   "description": "Read recent audit-log rows, newest first. Filter by session_id, operation, outcome, since_unix; verify=1 checks the hash chain.\nUse when: you review what was done and why (the reason field), in this or an earlier session.\nAvoid when: you want live metrics (project_health).\nOutput: rows[], count, truncated, chain_ok (verify=1).",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Max rows, newest first (default 50, max 200).",
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
+         "description": "Only rows for this operation (e.g. edit_file, shell_run).",
          "type": "string"
        },
        "outcome": {
+         "description": "Only rows with this outcome.",
          "enum": [
            "success",
            "failure",
+         "description": "Only rows from this session.",
          "type": "string"
        },
        "since_unix": {
+         "description": "Only rows at or after this Unix timestamp (seconds).",
          "maximum": 9007199254740991,
          "minimum": 0,
          "type": "integer"
--- pinned/project_read_batch
+++ observed/project_read_batch
  {
    "_meta": {
      "venira": {
-       "avoid_when": "there is only a single op; or you need a mutating op (use the corresponding tool).",
+       "avoid_when": "a single read (project_read_file) or any edit (project_edit_batch).",
        "batch_safe": true,
-       "output_kind": "read_batch: responses[] (each item is an ok/error envelope).",
+       "output_kind": "responses[] each {ok, response | error}, total_bytes_returned.",
        "speed_profile": "fastest for read-heavy work; sequential + cached, with a response budget.",
-       "use_when": "you need to read 2+ files/ops in the same step (reading context, scanning several files)."
+       "use_when": "you need 2+ reads or mixed read steps. Items run in order and one failing item does not stop the rest."
      }
    },
    "annotations": {
-   "description": "Run up to 8 READ-ONLY ops (list_files, read_file, get_file_info, search) in one call; read/info use the cache so repeats are very fast. Each item takes the same arguments as the standalone tool, including numeric 0/1 flags (e.g. search regex, case_sensitive, hybrid).\nUse when: you need to read 2+ files/ops in the same step (reading context, scanning several files).\nAvoid when: there is only a single op; or you need a mutating op (use the corresponding tool).\nSpeed: fastest for read-heavy work; sequential + cached, with a response budget.\nOutput: read_batch: responses[] (each item is an ok/error envelope).\nBatch-safe: yes",
+   "description": "Run up to 8 read-only ops in one call. operation is the short name (list_files|read_file|get_file_info|search) mapping to project_list_files|project_read_file|project_get_file_info|project_search; arguments hold exactly that tool's parameters.\nUse when: you need 2+ reads or mixed read steps. Items run in order and one failing item does not stop the rest.\nAvoid when: a single read (project_read_file) or any edit (project_edit_batch).\nOutput: responses[] each {ok, response | error}, total_bytes_returned.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Max serialized bytes per item (default 1 MiB).",
          "maximum": 2097152,
          "minimum": 1024,
          "type": "integer"
+         "description": "1-8 read items; one failing item does not stop the rest.",
          "items": {
-           "properties": {
-             "arguments": {
-               "additionalProperties": {},
-               "propertyNames": {
-                 "type": "string"
+           "anyOf": [
+             {
+               "properties": {
+                 "arguments": {
+                   "additionalProperties": {},
+                   "description": "Same as project_list_files.",
+                   "properties": {
+                     "depth": {
+                       "description": "Tree depth (default 1, max 3).",
+                       "maximum": 3,
+                       "minimum": 1,
+                       "type": "integer"
+                     },
+                     "include_ignored": {
+                       "description": "1 also lists ignored folders (default 0).",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
+                     "limit": {
+                       "description": "Max entries (default 200, max 200).",
+                       "maximum": 200,
+                       "minimum": 1,
+                       "type": "integer"
+                     },
+                     "relative_path": {
+                       "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
+                       "type": "string"
+                     }
+                   },
+                   "type": "object"
+                 },
+                 "operation": {
+                   "const": "list_files",
+                   "description": "Short op name for project_list_files.",
+                   "type": "string"
+                 }
                },
+               "required": [
+                 "operation",
+                 "arguments"
+               ],
                "type": "object"
              },
-             "operation": {
-               "enum": [
-                 "list_files",
-                 "read_file",
-                 "get_file_info",
-                 "search"
+             {
+               "properties": {
+                 "arguments": {
+                   "additionalProperties": {},
+                   "description": "Same as project_read_file.",
+                   "properties": {
+                     "end_line": {
+                       "description": "Last line (1-based).",
+                       "maximum": 9007199254740991,
+                       "minimum": 1,
+                       "type": "integer"
+                     },
+                     "line_numbers": {
+                       "description": "1 prefixes lines (default 0).",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
+                     "max_bytes": {
+                       "description": "Max bytes returned (default 1 MiB).",
+                       "maximum": 1048576,
+                       "minimum": 1,
+                       "type": "integer"
+                     },
+                     "ranges": {
+                       "description": "Disjoint ranges (max 16).",
+                       "items": {
+                         "properties": {
+                           "end_line": {
+                             "description": "Last line (1-based).",
+                             "maximum": 9007199254740991,
+                             "minimum": 1,
+                             "type": "integer"
+                           },
+                           "max_bytes": {
+                             "description": "Max bytes for this range.",
+                             "maximum": 9007199254740991,
+                             "minimum": 1,
+                             "type": "integer"
+                           },
+                           "start_line": {
+                             "description": "First line (1-based).",
+                             "maximum": 9007199254740991,
+                             "minimum": 1,
+                             "type": "integer"
+                           }
+                         },
+                         "required": [
+                           "start_line"
+                         ],
+                         "type": "object"
+                       },
+                       "maxItems": 16,
+                       "minItems": 1,
+                       "type": "array"
+                     },
+                     "relative_path": {
+                       "description": "Required (optional here so one bad item fails only itself).",
+                       "type": "string"
+                     },
+                     "start_line": {
+                       "description": "First line (1-based).",
+                       "maximum": 9007199254740991,
+                       "minimum": 1,
+                       "type": "integer"
+                     }
+                   },
+                   "type": "object"
+                 },
+                 "operation": {
+                   "const": "read_file",
+                   "description": "Short op name for project_read_file.",
+                   "type": "string"
+                 }
+               },
+               "required": [
+                 "operation",
+                 "arguments"
                ],
-               "type": "string"
+               "type": "object"
+             },
+             {
+               "properties": {
+                 "arguments": {
+                   "additionalProperties": {},
+                   "description": "Same as project_get_file_info.",
+                   "properties": {
+                     "relative_path": {
+                       "description": "Required (optional here so one bad item fails only itself).",
+                       "type": "string"
+                     }
+                   },
+                   "type": "object"
+                 },
+                 "operation": {
+                   "const": "get_file_info",
+                   "description": "Short op name for project_get_file_info.",
+                   "type": "string"
+                 }
+               },
+               "required": [
+                 "operation",
+                 "arguments"
+               ],
+               "type": "object"
+             },
+             {
+               "properties": {
+                 "arguments": {
+                   "additionalProperties": {},
+                   "description": "Same as project_search.",
+                   "properties": {
+                     "case_sensitive": {
+                       "description": "1 = case-sensitive (default 0).",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
+                     "context_lines": {
+                       "description": "Context lines per hit (default 0).",
+                       "maximum": 20,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
+                     "count_only": {
+                       "description": "1 = counts only (default 0).",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
+                     "exclude_glob": {
+                       "description": "rg glob exclusion (same dialect as glob).",
+                       "type": "string"
+                     },
+                     "glob": {
+                       "description": "rg glob filter ('*.ts' = any depth).",
+                       "type": "string"
+                     },
+                     "hybrid": {
+                       "description": "1 tags hits with source (default 0).",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
+                     "include_hidden": {
+                       "description": "1 includes dotfiles (default); 0 skips them.",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
+                     "kind": {
+                       "description": "Required: name substring | content | declaration lines.",
+                       "enum": [
+                         "file_name",
+                         "directory_name",
+                         "literal_content",
+                         "definition"
+                       ],
+                       "type": "string"
+                     },
+                     "limit": {
+                       "description": "Max hits (ignored when count_only=1).",
+                       "maximum": 200,
+                       "minimum": 1,
+                       "type": "integer"
+                     },
+                     "query": {
+                       "description": "Required; see kind.",
+                       "type": "string"
+                     },
+                     "regex": {
+                       "description": "1 = regex query (default 0).",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     },
+                     "relative_path": {
+                       "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
+                       "type": "string"
+                     },
+                     "whole_word": {
+                       "description": "1 = whole-word only (default 0).",
+                       "maximum": 1,
+                       "minimum": 0,
+                       "type": "integer"
+                     }
+                   },
+                   "type": "object"
+                 },
+                 "operation": {
+                   "const": "search",
+                   "description": "Short op name for project_search.",
+                   "type": "string"
+                 }
+               },
+               "required": [
+                 "operation",
+                 "arguments"
+               ],
+               "type": "object"
              }
-           },
-           "required": [
-             "operation",
-             "arguments"
-           ],
-           "type": "object"
+           ]
          },
          "maxItems": 8,
          "minItems": 1,
--- pinned/project_read_file
+++ observed/project_read_file
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you need to read 2+ files (project_read_batch) or only need metadata (project_get_file_info).",
+       "avoid_when": "you need 2+ files (project_read_batch) or only size/mtime (project_get_file_info).",
        "batch_safe": true,
-       "output_kind": "file_read: text, first_line, last_line, total_bytes, next_start_line.",
+       "output_kind": "text, first_line, last_line, total_bytes, truncated, next_start_line (when truncated). Missing path gives not_found.",
        "speed_profile": "very fast on repeat; cache validated by mtime+size.",
-       "use_when": "you need the contents of one file, or one line range of a large file."
+       "use_when": "you need one file's content. When truncated, call again with start_line=next_start_line."
      }
    },
    "annotations": {
-   "description": "Read a text file, optionally by line range (1-based). The result carries next_start_line when truncated.\nUse when: you need the contents of one file, or one line range of a large file.\nAvoid when: you need to read 2+ files (project_read_batch) or only need metadata (project_get_file_info).\nSpeed: very fast on repeat; cache validated by mtime+size.\nOutput: file_read: text, first_line, last_line, total_bytes, next_start_line.\nBatch-safe: yes",
+   "description": "Read a text file, whole or by line range (start_line/end_line, 1-based; ranges[] for several disjoint ranges of one file).\nUse when: you need one file's content. When truncated, call again with start_line=next_start_line.\nAvoid when: you need 2+ files (project_read_batch) or only size/mtime (project_get_file_info).\nOutput: text, first_line, last_line, total_bytes, truncated, next_start_line (when truncated). Missing path gives not_found.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Last line (1-based, inclusive).",
          "maximum": 9007199254740991,
-         "minimum": 0,
+         "minimum": 1,
          "type": "integer"
        },
        "line_numbers": {
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 prefixes each line with its line number (default 0).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "Max text bytes returned (default 1,048,576 = 1 MiB, max 1 MiB).",
          "maximum": 1048576,
          "minimum": 1,
          "type": "integer"
+               "description": "Last line (1-based, inclusive).",
                "maximum": 9007199254740991,
                "minimum": 1,
                "type": "integer"
+               "description": "Max text bytes for this range (default: the top-level max_bytes).",
                "maximum": 9007199254740991,
                "minimum": 1,
                "type": "integer"
+               "description": "First line (1-based).",
                "maximum": 9007199254740991,
                "minimum": 1,
                "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        },
        "start_line": {
+         "description": "First line (1-based). Together with end_line it selects one line range. When truncated, read again with start_line=next_start_line.",
          "maximum": 9007199254740991,
-         "minimum": 0,
+         "minimum": 1,
          "type": "integer"
        }
      },
--- pinned/project_recent_files
+++ observed/project_recent_files
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you need the full list / by name (project_list_files) or content search (project_search).",
+       "avoid_when": "you need the full tree (project_list_files) or a content search (project_search).",
        "batch_safe": false,
-       "output_kind": "recent_files: entries[] sorted by mtime desc, scanned_files, truncated.",
+       "output_kind": "entries[] {relative_path, size_bytes, modified_ago_seconds}, session_edits, truncated.",
        "speed_profile": "medium (filesystem walk); TTL cache 2s, bounded to 4000 files / 300 directories.",
-       "use_when": "starting or resuming a task, checking what the user or a command just changed (after shell/build/format/git), re-orienting after context loss, or picking the next files to feed into project_read_batch. Prefer it over listing a whole tree."
+       "use_when": "you start or resume a task, or finished a build, format or git step and want to see what changed. Feed the top paths into project_read_batch."
      }
    },
    "annotations": {
-   "description": "List files modified most recently in the workspace, newest first, plus session_edits (files you already wrote this session). Cheap orientation call: use it at the start of a task, when resuming, before editing a file the user may have changed, and after shell/build/git steps to see what really changed (bounded filesystem scan, skips node_modules/target/.git).\nUse when: starting or resuming a task, checking what the user or a command just changed (after shell/build/format/git), re-orienting after context loss, or picking the next files to feed into project_read_batch. Prefer it over listing a whole tree.\nAvoid when: you need the full list / by name (project_list_files) or content search (project_search).\nSpeed: medium (filesystem walk); TTL cache 2s, bounded to 4000 files / 300 directories.\nOutput: recent_files: entries[] sorted by mtime desc, scanned_files, truncated.\nBatch-safe: no",
+   "description": "List recently modified files, newest first, plus session_edits (files you wrote in this session).\nUse when: you start or resume a task, or finished a build, format or git step and want to see what changed. Feed the top paths into project_read_batch.\nAvoid when: you need the full tree (project_list_files) or a content search (project_search).\nOutput: entries[] {relative_path, size_bytes, modified_ago_seconds}, session_edits, truncated.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Directory recursion cap (default 2, max 6).",
          "maximum": 6,
          "minimum": 1,
          "type": "integer"
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 also lists ignored folders (default 0).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "Max entries (default 20, max 100).",
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        }
      },
--- pinned/project_search
+++ observed/project_search
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you already know the exact path to read.",
+       "avoid_when": "you know the path (project_read_file), want one file's structure (project_outline_symbol), a symbol's usages (project_symbol_references) or files ranked by several keywords (project_selective_search).",
        "batch_safe": true,
-       "output_kind": "search: hits (source+confidence when hybrid:1), complete, diagnostics, hint.",
+       "output_kind": "hits[] {relative_path, line_number, snippet}, complete, total_match_lines, files_matched. No match is ok with empty hits.",
        "speed_profile": "medium (file scan); TTL cache 3s for the same query.",
-       "use_when": "you need to find code/strings/symbols before reading; use kind=literal_content or definition."
+       "use_when": "you must locate code, strings or symbols before reading. hybrid=1 tags each hit with source and confidence."
      }
    },
    "annotations": {
-   "description": "Search by file name, directory name, content (literal or regex=1), or symbol declaration lines (definition).\nUse when: you need to find code/strings/symbols before reading; use kind=literal_content or definition.\nAvoid when: you already know the exact path to read.\nSpeed: medium (file scan); TTL cache 3s for the same query.\nOutput: search: hits (source+confidence when hybrid:1), complete, diagnostics, hint.\nBatch-safe: yes",
+   "description": "Search by kind: file_name, directory_name, literal_content (regex=1 for regex) or definition (symbol declaration lines).\nUse when: you must locate code, strings or symbols before reading. hybrid=1 tags each hit with source and confidence.\nAvoid when: you know the path (project_read_file), want one file's structure (project_outline_symbol), a symbol's usages (project_symbol_references) or files ranked by several keywords (project_selective_search).\nOutput: hits[] {relative_path, line_number, snippet}, complete, total_match_lines, files_matched. No match is ok with empty hits.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 makes literal_content/definition matching case-sensitive (default 0).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "Context lines around each hit (default 0).",
          "maximum": 20,
          "minimum": 0,
          "type": "integer"
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 returns only match counts; limit is then ignored. 0 (default) returns hits.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "rg glob exclusion (same dialect as glob).",
          "type": "string"
        },
        "glob": {
+         "description": "rg glob filter ('*.ts' = any depth, 'tools/*.ts' = that dir).",
          "type": "string"
        },
        "hybrid": {
-         "description": "1 = tag each hit with source (symbol_index|symbol_reference|content) and confidence (exact_match|text_match); a scoped identifier query with 0 hits widens once to the workspace (scope_widened:true). literal_content only.",
+         "description": "1 = tag hits with source/confidence; literal_content only.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "1 = include hidden files (default); 0 = skip dotfiles (rg-style). Secrets (.env*, credentials, keys) are always excluded either way.",
+         "description": "1 = include hidden files (default); 0 = skip dotfiles. Secrets always excluded.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "name substring | content (substring, or regex when regex=1) | declaration lines.",
          "enum": [
            "file_name",
            "directory_name",
+         "description": "Max hits returned (default and max 200; ignored when count_only=1).",
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
+         "description": "What to find (meaning depends on kind).",
          "type": "string"
        },
        "regex": {
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 treats query as a regular expression for literal_content/definition (default 0 = plain substring).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        },
        "whole_word": {
--- pinned/project_secret
+++ observed/project_secret
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the value is a normal, non-secret config (put it in .env or the config file); or you need the plaintext printed (only with reveal=1 + VENIRA_SECRET_ALLOW_REVEAL=1).",
+       "avoid_when": "the value is plain config (use .env or the config file). reveal=1 prints plaintext and needs VENIRA_SECRET_ALLOW_REVEAL=1.",
        "batch_safe": false,
-       "output_kind": "secret_set: name, length, sha256_12, updated_at, expires_at, days_left, created, rotated; secret_get/list: metadata only (expires_at, expired, days_left, last_used_at, use_count, rotated_at); secret_delete: deleted.",
+       "output_kind": "set: name, length, expires_at, days_left. get and list: metadata only.",
        "speed_profile": "fast; encrypted AES-256-GCM store, atomic writes, values decrypted only when injected. Expiry/use fields are metadata only.",
-       "use_when": "storing a non-GitHub token (action=set), checking whether one exists or is due for rotation (action=get / action=list), removing one (action=delete). Then use secret_env on project_shell_run or the built-in GitHub tools."
+       "use_when": "you save a non-GitHub token, check expiry or rotation, or remove one. Prefer value_env over value so the secret never appears in chat."
      }
    },
    "annotations": {
-   "description": "Manage API tokens/credentials without leaking them: values are encrypted at rest and never returned by default. Inject them into commands with project_shell_run secret_env=[\"NAME\"] instead of pasting them into a command line. Rotation metadata (expiry, last use, use count) is tracked by default and expired secrets are refused.\nUse when: storing a non-GitHub token (action=set), checking whether one exists or is due for rotation (action=get / action=list), removing one (action=delete). Then use secret_env on project_shell_run or the built-in GitHub tools.\nAvoid when: the value is a normal, non-secret config (put it in .env or the config file); or you need the plaintext printed (only with reveal=1 + VENIRA_SECRET_ALLOW_REVEAL=1).\nSpeed: fast; encrypted AES-256-GCM store, atomic writes, values decrypted only when injected. Expiry/use fields are metadata only.\nOutput: secret_set: name, length, sha256_12, updated_at, expires_at, days_left, created, rotated; secret_get/list: metadata only (expires_at, expired, days_left, last_used_at, use_count, rotated_at); secret_delete: deleted.\nBatch-safe: no",
+   "description": "Store and inspect tokens without exposing them (AES-256-GCM at rest). action: set | get (metadata only) | list | delete. Inject into commands with project_shell_run secret_env=[NAME]; the GitHub tools read GITHUB_TOKEN on their own.\nUse when: you save a non-GitHub token, check expiry or rotation, or remove one. Prefer value_env over value so the secret never appears in chat.\nAvoid when: the value is plain config (use .env or the config file). reveal=1 prints plaintext and needs VENIRA_SECRET_ALLOW_REVEAL=1.\nOutput: set: name, length, expires_at, days_left. get and list: metadata only.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "set stores a secret; get returns metadata only (plaintext needs reveal=1); list shows all stored secrets; delete removes one.",
          "enum": [
            "get",
            "set",
-         "description": "Why this change is made (e.g. \"sua loi null pointer o dong 45\"). Recorded in the audit trail so later sessions know the intent. Single line, max 400 chars, secrets are redacted.",
+         "description": "Optional why (max 400 chars), audit-logged. Required only on project_ci_control.",
          "maxLength": 400,
          "type": "string"
        },
--- pinned/project_selective_search
+++ observed/project_selective_search
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you need a single exact literal (project_search) or to inspect one file's content (project_read_file).",
+       "avoid_when": "you search for one literal (project_search) or do not know where to start (project_plan_read_batch).",
        "batch_safe": true,
-       "output_kind": "selective_search: hits[] {relative_path, line_number, text, score, matched}, total_files, total_hits, truncated.",
+       "output_kind": "hits[] {relative_path, line_number, text, score, matched}, total_files, total_hits.",
        "speed_profile": "medium; reads a bounded set of files (files_hint or a shallow listing) and scores each line.",
-       "use_when": "you need to rank many files by how well they match several keywords at once (e.g. locating the right module among candidates)."
+       "use_when": "you must find the right module among candidates using several keywords."
      }
    },
    "annotations": {
-   "description": "Smart multi-query search: combine several patterns with AND/OR/NOT + fuzzy scoring. Bounded to a file set you pass in.\nUse when: you need to rank many files by how well they match several keywords at once (e.g. locating the right module among candidates).\nAvoid when: you need a single exact literal (project_search) or to inspect one file's content (project_read_file).\nSpeed: medium; reads a bounded set of files (files_hint or a shallow listing) and scores each line.\nOutput: selective_search: hits[] {relative_path, line_number, text, score, matched}, total_files, total_hits, truncated.\nBatch-safe: yes",
+   "description": "Rank files by how well they match several patterns (must, weight, fuzzy score) within files_hint or a shallow listing.\nUse when: you must find the right module among candidates using several keywords.\nAvoid when: you search for one literal (project_search) or do not know where to start (project_plan_read_batch).\nOutput: hits[] {relative_path, line_number, text, score, matched}, total_files, total_hits.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Workspace paths to search instead of a shallow listing (first 20 are used).",
          "items": {
            "type": "string"
          },
+         "description": "Max hits returned (default 100, max 500).",
          "maximum": 500,
          "minimum": 1,
          "type": "integer"
+         "description": "One or more patterns. Files are scored by how many patterns they match (must patterns are required).",
          "items": {
            "properties": {
              "must": {
-               "description": "Numeric flag: 1=enabled, 0=disabled.",
+               "description": "1 excludes files that do not contain this pattern (default 0).",
                "maximum": 1,
                "minimum": 0,
                "type": "integer"
+               "description": "Case-insensitive substring matched against each line.",
                "type": "string"
              },
              "weight": {
+               "description": "Score multiplier for hits on this pattern (default 1; higher wins).",
                "maximum": 9007199254740991,
                "minimum": -9007199254740991,
                "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Directory to list when files_hint is omitted (default: workspace root, depth 2, first 40 files).",
          "type": "string"
        }
      },
--- pinned/project_shell_cancel
+++ observed/project_shell_cancel
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the command already finished (check with project_shell_status).",
+       "avoid_when": "the run already finished (project_shell_status).",
        "batch_safe": false,
-       "output_kind": "cancellation: accepted, cleanup_complete.",
+       "output_kind": "accepted, cleanup_complete.",
        "speed_profile": "fast; kills the whole process tree so grandchildren do not keep running.",
-       "use_when": "the command is running too long or its result is no longer needed."
+       "use_when": "a command hangs or its result is no longer needed."
      }
    },
    "annotations": {
-   "description": "Cancel a running shell command by run_id.\nUse when: the command is running too long or its result is no longer needed.\nAvoid when: the command already finished (check with project_shell_status).\nSpeed: fast; kills the whole process tree so grandchildren do not keep running.\nOutput: cancellation: accepted, cleanup_complete.\nBatch-safe: no",
+   "description": "Kill a running command and its child processes. Needs run_id and kill_key from project_shell_run.\nUse when: a command hangs or its result is no longer needed.\nAvoid when: the run already finished (project_shell_status).\nOutput: accepted, cleanup_complete.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Kill key from project_shell_run; proves this caller started the run.",
          "type": "string"
        },
        "run_id": {
+         "description": "Run id from project_shell_run.",
          "type": "string"
        }
      },
--- pinned/project_shell_cancel_session
+++ observed/project_shell_cancel_session
  {
    "_meta": {
      "venira": {
-       "avoid_when": "only one run needs cancelling (project_shell_cancel by run_id). Destructive: running commands are killed.",
+       "avoid_when": "only one run must stop (project_shell_cancel).",
        "batch_safe": false,
-       "output_kind": "shell_cancel_session: cancelled_run_ids[], count.",
+       "output_kind": "cancelled_run_ids[], count.",
        "speed_profile": "fast; iterates the in-process shell run table and kills each tree.",
-       "use_when": "a session is ending or a stuck session has many running commands and they must all be stopped."
+       "use_when": "you tear down a stuck session with several running commands."
      }
    },
    "annotations": {
-   "description": "Cancel ALL shell runs tracked in this session (kills every process tree). Use to cleanly tear down a session.\nUse when: a session is ending or a stuck session has many running commands and they must all be stopped.\nAvoid when: only one run needs cancelling (project_shell_cancel by run_id). Destructive: running commands are killed.\nSpeed: fast; iterates the in-process shell run table and kills each tree.\nOutput: shell_cancel_session: cancelled_run_ids[], count.\nBatch-safe: no",
+   "description": "Kill every shell run started in this session.\nUse when: you tear down a stuck session with several running commands.\nAvoid when: only one run must stop (project_shell_cancel).\nOutput: cancelled_run_ids[], count.",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_shell_run
+++ observed/project_shell_run
  {
    "_meta": {
      "venira": {
-       "avoid_when": "a command that may never finish: use the async default plus project_shell_status/project_shell_cancel.",
+       "avoid_when": "you read or edit files (file tools) or run a tiny JS calculation (project_execute_js).",
        "batch_safe": false,
-       "output_kind": "shell_run: run_id/shell_id, running, exit_code, background/foreground, stdout_tail/stderr_tail, timed_out, policy; background=0 also returns bounded stdout/stderr. approval_required: rule, reason, approval_id, retry_with.",
+       "output_kind": "run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=0) or stdout_tail/stderr_tail. ok=true only means it ran: read command_status/exit_code. approval_required: ask the user to approve, then retry once with approval_id.",
        "speed_profile": "background=1 returns in ~5 ms, run time is up to the command; background=0 blocks for the whole run (bounded by timeout_ms, default 10 min).",
-       "use_when": "build/test/lint/long-running commands. For hard-to-reverse workspace file changes, checkpoint first. Default (background=1) returns run_id immediately so it never blocks other tools; set background=0 when you need the final output in this call — it blocks until the command exits, and you must not start other work while waiting. After approval_required, ask the user to approve the approval_id in an interactive terminal, then retry."
+       "use_when": "you build, test, run git or install packages. Use background=0 for short commands whose output you need now."
      }
    },
    "annotations": {
-   "description": "Run a shell command (cwd defaults to /home/runner/work/mcp-pin/mcp-pin). Asynchronous by default: returns run_id immediately, so poll project_shell_status for the output. Pass background=0 (or false) for a foreground run: the call blocks until the command exits and returns the final stdout/stderr. For commands that overwrite/delete existing workspace source files, create and verify a scoped project_snapshot first; prefer project file tools for targeted edits. Commands pass a policy gate: risky ones return an approval_required error with a pending approval_id; catastrophic ones are denied outright. Named overrides require operator allowlisting and a per-call reason.\nUse when: build/test/lint/long-running commands. For hard-to-reverse workspace file changes, checkpoint first. Default (background=1) returns run_id immediately so it never blocks other tools; set background=0 when you need the final output in this call — it blocks until the command exits, and you must not start other work while waiting. After approval_required, ask the user to approve the approval_id in an interactive terminal, then retry.\nAvoid when: a command that may never finish: use the async default plus project_shell_status/project_shell_cancel.\nSpeed: background=1 returns in ~5 ms, run time is up to the command; background=0 blocks for the whole run (bounded by timeout_ms, default 10 min).\nOutput: shell_run: run_id/shell_id, running, exit_code, background/foreground, stdout_tail/stderr_tail, timed_out, policy; background=0 also returns bounded stdout/stderr. approval_required: rule, reason, approval_id, retry_with.\nBatch-safe: no",
+   "description": "Run a shell command in the workspace (shell: powershell|cmd|bash, relative_cwd, timeout_ms). Default is background: returns run_id, poll project_shell_status. background=0 blocks until exit and returns stdout/stderr.\nUse when: you build, test, run git or install packages. Use background=0 for short commands whose output you need now.\nAvoid when: you read or edit files (file tools) or run a tiny JS calculation (project_execute_js).\nOutput: run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=0) or stdout_tail/stderr_tail. ok=true only means it ran: read command_status/exit_code. approval_required: ask the user to approve, then retry once with approval_id.",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Approval ID from the approval_required envelope, granted by a human running `data.approval.approve_command` or using client elicitation. Retry once after they confirm.",
-         "type": "string"
-       },
-       "approval_scope": {
-         "description": "Ignored: scope (once/session) is chosen by the human at approval time (`--approve <id> --session`), never by the model.",
-         "enum": [
-           "once",
-           "session"
-         ],
-         "type": "string"
-       },
-       "approval_token": {
-         "description": "REMOVED in v1.15: passing it returns an error. Use approval_id instead.",
+         "description": "Id from approval_required, granted by a human (`data.approval.approve_command` or client elicitation). Retry once.",
          "type": "string"
        },
        "approval_wait_ms": {
-         "description": "If the command needs approval, wait up to this many ms (max 45000) for the human to grant it and run in the same call. On timeout you get the normal approval_required response.",
+         "description": "If approval is needed, wait up to this many ms (max 45000) for the human, then run in the same call.",
          "maximum": 45000,
          "minimum": 0,
          "type": "integer"
-         "anyOf": [
-           {
-             "maximum": 1,
-             "minimum": 0,
-             "type": "integer"
-           },
-           {
-             "type": "boolean"
-           },
-           {
-             "maxLength": 20,
-             "type": "string"
-           }
-         ],
-         "description": "1/true = background (default): return immediately with run_id. 0/false = foreground: block until the command exits, then return the final stdout/stderr in this call."
+         "description": "1 = background (default): return immediately with run_id. 0 = foreground: block until the command exits, then return the final stdout/stderr in this call.",
+         "maximum": 1,
+         "minimum": 0,
+         "type": "integer"
        },
        "command": {
-         "description": "Command line to execute. If it overwrites or deletes existing workspace source files, create and verify a scoped project_snapshot first; use project_write_file/project_edit_file/project_delete_path for targeted file operations.",
+         "description": "Command line to run.",
          "type": "string"
        },
        "dry_run": {
-         "description": "1 = evaluate policy only: returns tier, rule and whether approval would be needed. Nothing runs and no approval is created.",
+         "description": "1 = evaluate policy only; nothing runs, no approval is created (default 0).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "Required with override; explain the specific intent in one line. Redacted and recorded in the SQLite audit trail.",
+         "description": "Required with override: one-line intent (audit-logged).",
          "maxLength": 400,
          "minLength": 1,
          "type": "string"
+         "description": "Default: VENIRA_DEFAULT_SHELL, else the host default. pwsh = PowerShell 7+, powershell = 5.1.",
          "enum": [
            "powershell",
+           "pwsh",
            "cmd",
            "bash"
          ],
-         "description": "Kill the whole process tree after this many milliseconds. Unset or 0 uses the default 10-minute timeout; capped by VENIRA_SHELL_MAX_TIMEOUT_MS.",
+         "description": "Kill the process tree after this many ms (0/unset = 10 min; capped by VENIRA_SHELL_MAX_TIMEOUT_MS).",
          "maximum": 9007199254740991,
          "minimum": 0,
          "type": "integer"
--- pinned/project_shell_status
+++ observed/project_shell_status
  {
    "_meta": {
      "venira": {
-       "avoid_when": "no run_id available yet.",
+       "avoid_when": "you have no run_id yet.",
        "batch_safe": false,
-       "output_kind": "shell_run: running, exit_code, stdout_tail/stderr_tail.",
+       "output_kind": "running, exit_code, stdout_tail, stderr_tail. Unknown run_id gives not_found (run ids only live for this session).",
        "speed_profile": "fast; not queued so it never blocks other tools.",
-       "use_when": "after project_shell_run; poll until running=false."
+       "use_when": "after a background project_shell_run: poll until running=false, then read exit_code."
      }
    },
    "annotations": {
-   "description": "Check status + output of a running command. wait_seconds (0..30) is an observation window, not a timeout.\nUse when: after project_shell_run; poll until running=false.\nAvoid when: no run_id available yet.\nSpeed: fast; not queued so it never blocks other tools.\nOutput: shell_run: running, exit_code, stdout_tail/stderr_tail.\nBatch-safe: no",
+   "description": "Return the state and output tail of a shell run. wait_seconds (0-30) waits up to that long for it to finish.\nUse when: after a background project_shell_run: poll until running=false, then read exit_code.\nAvoid when: you have no run_id yet.\nOutput: running, exit_code, stdout_tail, stderr_tail. Unknown run_id gives not_found (run ids only live for this session).",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Run id from project_shell_run.",
          "type": "string"
        },
        "wait_seconds": {
+         "description": "Wait up to this many seconds for the run to finish (default 0, max 30). Observation window only, not a timeout.",
          "maximum": 30,
          "minimum": 0,
          "type": "integer"
--- pinned/project_snapshot
+++ observed/project_snapshot
  {
    "_meta": {
      "venira": {
-       "avoid_when": "a tiny, easily recreated single-file edit, generated build output, or a commit already provides the needed recovery point; do not restore over newer user changes without inspecting them.",
+       "avoid_when": "tiny single-file edits or states git already holds.",
        "batch_safe": false,
-       "output_kind": "snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed; snapshot_mirror: status, copied_blobs, copied_indexes, bytes, failed[] (needs VENIRA_SNAPSHOT_MIRROR_DIR); snapshot_create adds mirror{} when configured.",
+       "output_kind": "create: id, file_count, total_bytes, truncated, skipped[]. restore: restored[], deleted_count, skipped[].",
        "speed_profile": "create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, SHA-256 verified by default; dry_run previews path/size only, not same-size content changes.",
-       "use_when": "before multi-file, cross-file, refactor/rename or hard-to-reverse edits: create with a descriptive label, scope paths to the affected area, retain the exact returned id, and confirm required files were captured. For rollback, run restore dry_run=1 to preview path/size changes (same-size content differences are not detected); inspect files with newer user edits, then restore the exact id with verify=1 and delete_extra=0. Example: checkpoint → edit 3 files → tests fail → inspect scope → restore."
+       "use_when": "before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=1, then restore with verify=1."
      }
    },
    "annotations": {
-   "description": "Checkpoint/rollback for the workspace: create a labeled, scoped snapshot before multi-file or hard-to-reverse edits; keep its returned id. For rollback, preview with restore dry_run=1 (size-based preview only; it cannot detect same-size content changes), inspect newer user edits, then restore that exact id with verify=1 and delete_extra=0. Content-addressed and deduplicated.\nUse when: before multi-file, cross-file, refactor/rename or hard-to-reverse edits: create with a descriptive label, scope paths to the affected area, retain the exact returned id, and confirm required files were captured. For rollback, run restore dry_run=1 to preview path/size changes (same-size content differences are not detected); inspect files with newer user edits, then restore the exact id with verify=1 and delete_extra=0. Example: checkpoint → edit 3 files → tests fail → inspect scope → restore.\nAvoid when: a tiny, easily recreated single-file edit, generated build output, or a commit already provides the needed recovery point; do not restore over newer user changes without inspecting them.\nSpeed: create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, SHA-256 verified by default; dry_run previews path/size only, not same-size content changes.\nOutput: snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed; snapshot_mirror: status, copied_blobs, copied_indexes, bytes, failed[] (needs VENIRA_SNAPSHOT_MIRROR_DIR); snapshot_create adds mirror{} when configured.\nBatch-safe: no",
+   "description": "Checkpoint and roll back workspace files. action: create (label, paths) | list | restore (id) | delete (id) | mirror (copy to VENIRA_SNAPSHOT_MIRROR_DIR).\nUse when: before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=1, then restore with verify=1.\nAvoid when: tiny single-file edits or states git already holds.\nOutput: create: id, file_count, total_bytes, truncated, skipped[]. restore: restored[], deleted_count, skipped[].",
    "execution": {
      "taskSupport": "forbidden"
    },
+     "additionalProperties": {},
      "properties": {
        "action": {
          "default": "create",
+         "description": "create (default) captures paths; list; restore rolls back an id; delete removes an id; mirror copies the store to VENIRA_SNAPSHOT_MIRROR_DIR.",
          "enum": [
            "create",
            "list",
-         "description": "restore only: 1 also deletes files inside captured dirs not in the checkpoint (capped at 500); default/0 keeps them. Use 1 only when deletion is explicitly intended.",
+         "description": "restore only: 1 also deletes files in captured dirs that are not in the checkpoint (max 500). Default 0; use only when intended.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "restore only: 1 previews path/size changes without writing (same-size content changes are not detected); inspect current user edits before applying.",
+         "description": "restore only: 1 previews path/size changes without writing.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "Max files captured (default 20000, max 20000).",
          "maximum": 20000,
          "minimum": 1,
          "type": "integer"
+         "description": "Max total bytes captured (default and max 512 MiB).",
          "maximum": 536870912,
          "minimum": 1,
          "type": "integer"
-         "description": "Capture affected paths (default ['.'] only when scope is unclear); restore accepts a subset to filter files.",
+         "description": "Workspace-relative paths to capture (default ['.'] = whole workspace; scope narrowly). For restore: subset to restore.",
          "items": {
            "type": "string"
          },
-         "description": "Why this change is made (e.g. \"sua loi null pointer o dong 45\"). Recorded in the audit trail so later sessions know the intent. Single line, max 400 chars, secrets are redacted.",
+         "description": "Optional why (max 400 chars), audit-logged. Required only on project_ci_control.",
          "maxLength": 400,
          "type": "string"
        },
-       "scope": {
-         "description": "Deprecated alias for paths; supplied scope is honored and missing paths return not_found.",
-         "items": {
-           "type": "string"
-         },
-         "maxItems": 64,
-         "type": "array"
-       },
        "verify": {
-         "description": "restore: 1 verifies each blob before writing (default); 0 disables verification. mirror: 1 re-hashes every blob already at the mirror and re-copies bad ones (default 0 trusts existing files).",
+         "description": "restore: 1 verifies each blob before writing (default). mirror: 1 re-hashes blobs already at the mirror and re-copies bad ones (default 0).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
--- pinned/project_symbol_references
+++ observed/project_symbol_references
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you only need its declaration (project_outline_symbol) or an arbitrary string (project_search).",
+       "avoid_when": "you only need its declaration (project_outline_symbol) or arbitrary text (project_search).",
        "batch_safe": true,
-       "output_kind": "symbol_references: count, references[] {relative_path, line_number, context}.",
+       "output_kind": "count, references[] {relative_path, line_number, context}.",
        "speed_profile": "fast for scope=file; medium for scope=workspace (single search call).",
-       "use_when": "you need to know where a symbol is used before renaming/refactoring it."
+       "use_when": "you check where a symbol is used before renaming or changing it."
      }
    },
    "annotations": {
-   "description": "Find every occurrence of a named symbol. scope=file (fast, single file) or scope=workspace (uses content search).\nUse when: you need to know where a symbol is used before renaming/refactoring it.\nAvoid when: you only need its declaration (project_outline_symbol) or an arbitrary string (project_search).\nSpeed: fast for scope=file; medium for scope=workspace (single search call).\nOutput: symbol_references: count, references[] {relative_path, line_number, context}.\nBatch-safe: yes",
+   "description": "Find occurrences of a symbol name. scope=file needs relative_path (one file); scope=workspace (default) searches all files. limit caps the workspace scan, max_references caps the returned list.\nUse when: you check where a symbol is used before renaming or changing it.\nAvoid when: you only need its declaration (project_outline_symbol) or arbitrary text (project_search).\nOutput: count, references[] {relative_path, line_number, context}.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "scope=workspace only: max search hits to scan (default 50). Ignored for scope=file.",
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
+         "description": "Max references returned (default 100, max 500). Applies in both scopes.",
          "maximum": 500,
          "minimum": 1,
          "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Required when scope=file; with scope=workspace it narrows the search to this subtree.",
          "type": "string"
        },
        "scope": {
+         "description": "workspace = search all files (default); file = search one file. scope=file requires relative_path.",
          "enum": [
            "file",
            "workspace"
+         "description": "Symbol name to find (matched as a whole word).",
          "type": "string"
        }
      },
--- pinned/project_trace_status
+++ observed/project_trace_status
  {
    "_meta": {
      "venira": {
-       "avoid_when": "tracing is disabled (returns an empty buffer) or you need the full on-disk log (read VENIRA_TRACE_FILE instead).",
+       "avoid_when": "tracing is off (the buffer is empty).",
        "batch_safe": true,
-       "output_kind": "trace_status: enabled, file, buffered, recent[] (newest last).",
+       "output_kind": "enabled, file, buffered, recent[] (newest last).",
        "speed_profile": "instant; in-memory buffer only, no I/O.",
-       "use_when": "VENIRA_TRACE=1 and you want to see what ran recently without reading the log file."
+       "use_when": "you want to see what ran recently without opening the log file."
      }
    },
    "annotations": {
-   "description": "Show the most recent traced tool calls from the in-memory buffer (last N) plus the trace configuration.\nUse when: VENIRA_TRACE=1 and you want to see what ran recently without reading the log file.\nAvoid when: tracing is disabled (returns an empty buffer) or you need the full on-disk log (read VENIRA_TRACE_FILE instead).\nSpeed: instant; in-memory buffer only, no I/O.\nOutput: trace_status: enabled, file, buffered, recent[] (newest last).\nBatch-safe: yes",
+   "description": "Show recent traced tool calls and the trace configuration (needs VENIRA_TRACE=1).\nUse when: you want to see what ran recently without opening the log file.\nAvoid when: tracing is off (the buffer is empty).\nOutput: enabled, file, buffered, recent[] (newest last).",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_write_file
+++ observed/project_write_file
  {
    "_meta": {
      "venira": {
-       "avoid_when": "only a small section needs to change (project_edit_file), or an existing file would be overwritten without a verified pre-write project_snapshot.",
+       "avoid_when": "you change a few lines (project_edit_file). overwrite is immediate and not undoable: project_snapshot first when the file is not in git.",
        "batch_safe": false,
-       "output_kind": "file_written: action, bytes_written, sha256_after.",
+       "output_kind": "action (created|overwritten|appended), bytes_written, sha256_after. mode=create on an existing path gives conflict.",
        "speed_profile": "fast; clears the read/list/search cache for the affected path.",
-       "use_when": "create a new file or append content; before mode=overwrite on an existing file, create a scoped project_snapshot, confirm it captured the target, and keep the returned id."
+       "use_when": "you create a file, replace one entirely, or append. expected_sha256 refuses the write if the file changed since you read it."
      }
    },
    "annotations": {
-   "description": "Write a file. mode=create errors if it exists; overwrite replaces existing contents; append concatenates. Create and verify a scoped project_snapshot before overwriting existing file contents.\nUse when: create a new file or append content; before mode=overwrite on an existing file, create a scoped project_snapshot, confirm it captured the target, and keep the returned id.\nAvoid when: only a small section needs to change (project_edit_file), or an existing file would be overwritten without a verified pre-write project_snapshot.\nSpeed: fast; clears the read/list/search cache for the affected path.\nOutput: file_written: action, bytes_written, sha256_after.\nBatch-safe: no",
+   "description": "Write a file. mode=create (fails if it exists), overwrite, or append. create_dirs=1 creates parent folders.\nUse when: you create a file, replace one entirely, or append. expected_sha256 refuses the write if the file changed since you read it.\nAvoid when: you change a few lines (project_edit_file). overwrite is immediate and not undoable: project_snapshot first when the file is not in git.\nOutput: action (created|overwritten|appended), bytes_written, sha256_after. mode=create on an existing path gives conflict.",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Full file content to write.",
          "type": "string"
        },
        "create_dirs": {
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 creates missing parent directories (default 0).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
+         "description": "Hex SHA-256 of the file's current full content. The write is refused if the file on disk differs. Use sha256_after from your last write/edit of this file; read_file's sha256 only matches when the whole file was returned.",
          "type": "string"
        },
        "mode": {
-         "description": "overwrite replaces existing contents; create and verify a scoped project_snapshot first. create fails if the path exists; append adds to the end.",
+         "description": "Default overwrite: replaces existing contents; create and verify a scoped project_snapshot first. create fails if the path exists; append adds to the end.",
          "enum": [
            "create",
            "overwrite",
-         "description": "Why this change is made (e.g. \"sua loi null pointer o dong 45\"). Recorded in the audit trail so later sessions know the intent. Single line, max 400 chars, secrets are redacted.",
+         "description": "Optional why (max 400 chars), audit-logged. Required only on project_ci_control.",
          "maxLength": 400,
          "type": "string"
        },
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Workspace-relative ('.' = root); absolute/.. outside it rejected.",
          "type": "string"
        }
      },

Changed 2026-11-09 16:00 UTC

1 description rewritten.

--- pinned/project_snapshot
+++ observed/project_snapshot
  {
    "_meta": {
      "venira": {
-       "output_kind": "snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed.",
+       "output_kind": "snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed; snapshot_mirror: status, copied_blobs, copied_indexes, bytes, failed[] (needs VENIRA_SNAPSHOT_MIRROR_DIR); snapshot_create adds mirror{} when configured.",
        "speed_profile": "create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, SHA-256 verified by default; dry_run previews path/size only, not same-size content changes.",
        "use_when": "before multi-file, cross-file, refactor/rename or hard-to-reverse edits: create with a descriptive label, scope paths to the affected area, retain the exact returned id, and confirm required files were captured. For rollback, run restore dry_run=1 to preview path/size changes (same-size content differences are not detected); inspect files with newer user edits, then restore the exact id with verify=1 and delete_extra=0. Example: checkpoint → edit 3 files → tests fail → inspect scope → restore."
      }
-   "description": "Checkpoint/rollback for the workspace: create a labeled, scoped snapshot before multi-file or hard-to-reverse edits; keep its returned id. For rollback, preview with restore dry_run=1 (size-based preview only; it cannot detect same-size content changes), inspect newer user edits, then restore that exact id with verify=1 and delete_extra=0. Content-addressed and deduplicated.\nUse when: before multi-file, cross-file, refactor/rename or hard-to-reverse edits: create with a descriptive label, scope paths to the affected area, retain the exact returned id, and confirm required files were captured. For rollback, run restore dry_run=1 to preview path/size changes (same-size content differences are not detected); inspect files with newer user edits, then restore the exact id with verify=1 and delete_extra=0. Example: checkpoint → edit 3 files → tests fail → inspect scope → restore.\nAvoid when: a tiny, easily recreated single-file edit, generated build output, or a commit already provides the needed recovery point; do not restore over newer user changes without inspecting them.\nSpeed: create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, SHA-256 verified by default; dry_run previews path/size only, not same-size content changes.\nOutput: snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed.\nBatch-safe: no",
+   "description": "Checkpoint/rollback for the workspace: create a labeled, scoped snapshot before multi-file or hard-to-reverse edits; keep its returned id. For rollback, preview with restore dry_run=1 (size-based preview only; it cannot detect same-size content changes), inspect newer user edits, then restore that exact id with verify=1 and delete_extra=0. Content-addressed and deduplicated.\nUse when: before multi-file, cross-file, refactor/rename or hard-to-reverse edits: create with a descriptive label, scope paths to the affected area, retain the exact returned id, and confirm required files were captured. For rollback, run restore dry_run=1 to preview path/size changes (same-size content differences are not detected); inspect files with newer user edits, then restore the exact id with verify=1 and delete_extra=0. Example: checkpoint → edit 3 files → tests fail → inspect scope → restore.\nAvoid when: a tiny, easily recreated single-file edit, generated build output, or a commit already provides the needed recovery point; do not restore over newer user changes without inspecting them.\nSpeed: create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, SHA-256 verified by default; dry_run previews path/size only, not same-size content changes.\nOutput: snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed; snapshot_mirror: status, copied_blobs, copied_indexes, bytes, failed[] (needs VENIRA_SNAPSHOT_MIRROR_DIR); snapshot_create adds mirror{} when configured.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
-           "delete"
+           "delete",
+           "mirror"
          ],
          "type": "string"
        },
-         "description": "restore only: 1 verifies each blob before writing (default); 0 disables verification.",
+         "description": "restore: 1 verifies each blob before writing (default); 0 disables verification. mirror: 1 re-hashes every blob already at the mirror and re-copies bad ones (default 0 trusts existing files).",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"

Changed 2026-11-08 13:15 UTC

1 schema or annotation change with the description left byte-identical.

--- pinned/project_snapshot
+++ observed/project_snapshot
  {
    "_meta": {
      "venira": {
+       "scope": {
+         "description": "Deprecated alias for paths; supplied scope is honored and missing paths return not_found.",
+         "items": {
+           "type": "string"
+         },
+         "maxItems": 64,
+         "type": "array"
+       },
        "verify": {
          "description": "restore only: 1 verifies each blob before writing (default); 0 disables verification.",
          "maximum": 1,

Changed 2026-11-07 12:57 UTC

12 descriptions rewritten.

--- pinned/project_create
+++ observed/project_create
  {
    "_meta": {
      "venira": {
-       "avoid_when": "modifying an existing file (project_edit_file); overwriting a file whose contents must be preserved (project_write_file mode=overwrite still works).",
+       "avoid_when": "editing an existing file (project_edit_file/project_write_file); never use mode=overwrite unless a pre-write project_snapshot covers the existing contents.",
        "batch_safe": false,
        "output_kind": "directory_created or file_written (data kind depends on the op).",
        "speed_profile": "fast; triggers cache invalidation on write / new directory.",
-       "use_when": "create a directory (kind=directory) or a new file (kind=file, content+mode); kept in sync with the Venira native app tool."
+       "use_when": "create a directory or new file; if replacing an existing file, first create a scoped project_snapshot, confirm it captured the target, and keep its id."
      }
    },
    "annotations": {
-   "description": "Create a directory OR a file in ONE call (merges project_create_directory + project_write_file for the new-file case).\nUse when: create a directory (kind=directory) or a new file (kind=file, content+mode); kept in sync with the Venira native app tool.\nAvoid when: modifying an existing file (project_edit_file); overwriting a file whose contents must be preserved (project_write_file mode=overwrite still works).\nSpeed: fast; triggers cache invalidation on write / new directory.\nOutput: directory_created or file_written (data kind depends on the op).\nBatch-safe: no",
+   "description": "Create a directory OR a file in ONE call. For an existing file, mode=overwrite replaces its contents: create and verify a scoped project_snapshot first.\nUse when: create a directory or new file; if replacing an existing file, first create a scoped project_snapshot, confirm it captured the target, and keep its id.\nAvoid when: editing an existing file (project_edit_file/project_write_file); never use mode=overwrite unless a pre-write project_snapshot covers the existing contents.\nSpeed: fast; triggers cache invalidation on write / new directory.\nOutput: directory_created or file_written (data kind depends on the op).\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "overwrite replaces existing contents; create and verify a scoped project_snapshot first. create fails if the path exists; append adds to the end.",
          "enum": [
            "create",
            "overwrite",
--- pinned/project_delete_path
+++ observed/project_delete_path
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you only need to change the content (write/edit). This op is not undoable.",
+       "avoid_when": "the target is ambiguous or a pre-delete snapshot is missing, truncated, or skipped the target. This op is not undoable; capture and verify a checkpoint first.",
        "batch_safe": false,
        "output_kind": "path_deleted: entries_deleted, bytes_deleted.",
        "speed_profile": "fast; clears the read/list/search cache.",
-       "use_when": "a file/directory must be deleted entirely; the path is confirmed."
+       "use_when": "only after creating a scoped project_snapshot for the exact target, confirming file_count/truncated/skipped cover the intended files, and keeping its id for recovery."
      }
    },
    "annotations": {
-   "description": "Delete a file or directory (directories require recursive=1).\nUse when: a file/directory must be deleted entirely; the path is confirmed.\nAvoid when: you only need to change the content (write/edit). This op is not undoable.\nSpeed: fast; clears the read/list/search cache.\nOutput: path_deleted: entries_deleted, bytes_deleted.\nBatch-safe: no",
+   "description": "Delete a file or directory (directories require recursive=1). Create and verify a scoped snapshot before using this irreversible tool; do not delete if the checkpoint is incomplete.\nUse when: only after creating a scoped project_snapshot for the exact target, confirming file_count/truncated/skipped cover the intended files, and keeping its id for recovery.\nAvoid when: the target is ambiguous or a pre-delete snapshot is missing, truncated, or skipped the target. This op is not undoable; capture and verify a checkpoint first.\nSpeed: fast; clears the read/list/search cache.\nOutput: path_deleted: entries_deleted, bytes_deleted.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "For recursive directory deletion, set 1 only after confirming the target and creating a scoped project_snapshot; required for directory deletion.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "Path inside the workspace (relative, or absolute inside the workspace)",
+         "description": "Exact workspace path to delete. Create a scoped project_snapshot first and confirm this target is captured; do not delete if it is skipped or the checkpoint is truncated.",
          "type": "string"
        }
      },
--- pinned/project_edit_batch
+++ observed/project_edit_batch
  {
    "_meta": {
      "venira": {
-       "use_when": "you have 2+ independent edits across one or more files. Consider project_snapshot action=create first so you can rollback the whole batch in one call if something goes wrong."
+       "use_when": "before editing existing files in a multi-edit batch, create a scoped project_snapshot when it spans multiple files/sections or needs rollback after later checks. Batch rollback covers an in-batch failure only; it does not undo a successful batch after tests fail."
      }
    },
    "annotations": {
-   "description": "Apply multiple edit_file operations atomically in one call; aborts after the first failure and restores the pre-batch snapshot when possible.\nUse when: you have 2+ independent edits across one or more files. Consider project_snapshot action=create first so you can rollback the whole batch in one call if something goes wrong.\nAvoid when: a single edit (project_edit_file) or a whole-file rewrite (project_write_file).\nSpeed: depends on item count; each runs edit_file and clears caches.\nOutput: batch: responses[] {ok, response|error}, atomic metadata with executed/skipped indexes and rollback status.\nBatch-safe: no",
+   "description": "Apply multiple edit_file operations atomically in one call; aborts after the first failure and restores the pre-batch snapshot when possible.\nUse when: before editing existing files in a multi-edit batch, create a scoped project_snapshot when it spans multiple files/sections or needs rollback after later checks. Batch rollback covers an in-batch failure only; it does not undo a successful batch after tests fail.\nAvoid when: a single edit (project_edit_file) or a whole-file rewrite (project_write_file).\nSpeed: depends on item count; each runs edit_file and clears caches.\nOutput: batch: responses[] {ok, response|error}, atomic metadata with executed/skipped indexes and rollback status.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Array of edit_file argument objects. The batch aborts on the first failure and rolls back earlier writes when possible.",
+         "description": "Array of edit_file arguments. For existing files across multiple edits, create a scoped project_snapshot first if later validation may require full rollback; automatic rollback only handles in-batch failures.",
          "items": {
            "additionalProperties": {},
            "propertyNames": {
--- pinned/project_edit_file
+++ observed/project_edit_file
  {
    "_meta": {
      "venira": {
-       "use_when": "change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify cycle (replaces safe_edit). If editing 2+ files or 2+ sections, create a project_snapshot first so you can rollback in one call."
+       "use_when": "change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify. Before editing 2+ files or 2+ sections, create a scoped project_snapshot and confirm coverage."
      }
    },
    "annotations": {
-   "description": "Edit a file by exact text replacement: one old_text/new_text pair, or edits[] for multiple sections. Supports TOCTOU guard mode (guard=sha256) for atomic read-edit-verify cycle.\nUse when: change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify cycle (replaces safe_edit). If editing 2+ files or 2+ sections, create a project_snapshot first so you can rollback in one call.\nAvoid when: the whole file must change (project_write_file), or you have not read the file to know old_text.\nSpeed: fast; clears the read/list/search cache for the affected path.\nOutput: file_written: replacements, sha256_before/after, verified (with guard=sha256).\nBatch-safe: no",
+   "description": "Edit a file by exact text replacement: one old_text/new_text pair, or edits[] for multiple sections. Supports TOCTOU guard mode (guard=sha256) for atomic read-edit-verify cycle.\nUse when: change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify. Before editing 2+ files or 2+ sections, create a scoped project_snapshot and confirm coverage.\nAvoid when: the whole file must change (project_write_file), or you have not read the file to know old_text.\nSpeed: fast; clears the read/list/search cache for the affected path.\nOutput: file_written: replacements, sha256_before/after, verified (with guard=sha256).\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "Multiple section replacements in this file. Create a scoped project_snapshot first when applying 2+ edits or when the change is hard to recreate.",
          "items": {
            "properties": {
              "new_text": {
--- pinned/project_explain_error
+++ observed/project_explain_error
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you already know the cause and only need the file contents (use project_read_file / project_read_ranges).",
+       "avoid_when": "you already know the cause and only need the file contents (use project_read_file, which also accepts ranges).",
        "batch_safe": true,
        "output_kind": "explain_error: matched, summary, error_line, language, diagnoses[] {rule_id, title, likely_cause, suggested_fix[], retry_hint?, next_actions[]}, next_actions[].",
        "speed_profile": "pure local rules, < 1 ms; no network and no model call.",
-   "description": "Diagnose a failure from its error text / log tail: known signatures (errno, TypeScript, Python, git, npm, GitHub, venira codes) → likely cause + ready-to-send next tool calls. Rule-based, offline, instant.\nUse when: a command, test, build or provider call failed and you want the fastest route to the fix (feed it the stderr tail or the CI log tail).\nAvoid when: you already know the cause and only need the file contents (use project_read_file / project_read_ranges).\nSpeed: pure local rules, < 1 ms; no network and no model call.\nOutput: explain_error: matched, summary, error_line, language, diagnoses[] {rule_id, title, likely_cause, suggested_fix[], retry_hint?, next_actions[]}, next_actions[].\nBatch-safe: yes",
+   "description": "Diagnose a failure from its error text / log tail: known signatures (errno, TypeScript, Python, git, npm, GitHub, venira codes) → likely cause + ready-to-send next tool calls. Rule-based, offline, instant.\nUse when: a command, test, build or provider call failed and you want the fastest route to the fix (feed it the stderr tail or the CI log tail).\nAvoid when: you already know the cause and only need the file contents (use project_read_file, which also accepts ranges).\nSpeed: pure local rules, < 1 ms; no network and no model call.\nOutput: explain_error: matched, summary, error_line, language, diagnoses[] {rule_id, title, likely_cause, suggested_fix[], retry_hint?, next_actions[]}, next_actions[].\nBatch-safe: yes",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_health
+++ observed/project_health
  {
    "_meta": {
      "venira": {
-       "output_kind": "health: server, corehost, capability, queue, caches, shells, metrics, audit.",
+       "output_kind": "health: notice, server, corehost, capability, queue, caches, shells, metrics, audit.",
        "speed_profile": "fast (~a few ms + 1 audit DB query); set include_audit=0 to skip the DB query.",
        "use_when": "debugging slowness/errors, checking the backend/DB/audit before reporting, or inspecting this session's cache/metrics."
      }
-   "description": "Server diagnostics: corehost/data dir/audit DB, capability, queue depth, cache hit-rate, running shells, p50/p95 metrics.\nUse when: debugging slowness/errors, checking the backend/DB/audit before reporting, or inspecting this session's cache/metrics.\nAvoid when: you just need to read/write files normally.\nSpeed: fast (~a few ms + 1 audit DB query); set include_audit=0 to skip the DB query.\nOutput: health: server, corehost, capability, queue, caches, shells, metrics, audit.\nBatch-safe: no",
+   "description": "Server diagnostics: corehost/data dir/audit DB, capability, queue depth, cache hit-rate, running shells, p50/p95 metrics, plus a security-limit notice (guard rail, not sandbox).\nUse when: debugging slowness/errors, checking the backend/DB/audit before reporting, or inspecting this session's cache/metrics.\nAvoid when: you just need to read/write files normally.\nSpeed: fast (~a few ms + 1 audit DB query); set include_audit=0 to skip the DB query.\nOutput: health: notice, server, corehost, capability, queue, caches, shells, metrics, audit.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_read_batch
+++ observed/project_read_batch
  {
    "_meta": {
      "venira": {
-   "description": "Run up to 8 READ-ONLY ops (list_files, read_file, get_file_info, search) in one call; read/info use the cache so repeats are very fast.\nUse when: you need to read 2+ files/ops in the same step (reading context, scanning several files).\nAvoid when: there is only a single op; or you need a mutating op (use the corresponding tool).\nSpeed: fastest for read-heavy work; sequential + cached, with a response budget.\nOutput: read_batch: responses[] (each item is an ok/error envelope).\nBatch-safe: yes",
+   "description": "Run up to 8 READ-ONLY ops (list_files, read_file, get_file_info, search) in one call; read/info use the cache so repeats are very fast. Each item takes the same arguments as the standalone tool, including numeric 0/1 flags (e.g. search regex, case_sensitive, hybrid).\nUse when: you need to read 2+ files/ops in the same step (reading context, scanning several files).\nAvoid when: there is only a single op; or you need a mutating op (use the corresponding tool).\nSpeed: fastest for read-heavy work; sequential + cached, with a response budget.\nOutput: read_batch: responses[] (each item is an ok/error envelope).\nBatch-safe: yes",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_recent_files
+++ observed/project_recent_files
  {
    "_meta": {
      "venira": {
-       "use_when": "you need to know which files just changed, or to pick the next file to read in this session."
+       "use_when": "starting or resuming a task, checking what the user or a command just changed (after shell/build/format/git), re-orienting after context loss, or picking the next files to feed into project_read_batch. Prefer it over listing a whole tree."
      }
    },
    "annotations": {
-   "description": "List files modified most recently in the workspace (bounded filesystem scan, skips node_modules/target/.git).\nUse when: you need to know which files just changed, or to pick the next file to read in this session.\nAvoid when: you need the full list / by name (project_list_files) or content search (project_search).\nSpeed: medium (filesystem walk); TTL cache 2s, bounded to 4000 files / 300 directories.\nOutput: recent_files: entries[] sorted by mtime desc, scanned_files, truncated.\nBatch-safe: no",
+   "description": "List files modified most recently in the workspace, newest first, plus session_edits (files you already wrote this session). Cheap orientation call: use it at the start of a task, when resuming, before editing a file the user may have changed, and after shell/build/git steps to see what really changed (bounded filesystem scan, skips node_modules/target/.git).\nUse when: starting or resuming a task, checking what the user or a command just changed (after shell/build/format/git), re-orienting after context loss, or picking the next files to feed into project_read_batch. Prefer it over listing a whole tree.\nAvoid when: you need the full list / by name (project_list_files) or content search (project_search).\nSpeed: medium (filesystem walk); TTL cache 2s, bounded to 4000 files / 300 directories.\nOutput: recent_files: entries[] sorted by mtime desc, scanned_files, truncated.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_shell_run
+++ observed/project_shell_run
  {
    "_meta": {
      "venira": {
-       "use_when": "build/test/lint/long-running commands. Default (background=1) returns run_id immediately so it never blocks other tools; set background=0 when you need the final output in this call — it blocks until the command exits, and you must not start other work while waiting. After approval_required, ask the user to approve the approval_id in an interactive terminal, then retry."
+       "use_when": "build/test/lint/long-running commands. For hard-to-reverse workspace file changes, checkpoint first. Default (background=1) returns run_id immediately so it never blocks other tools; set background=0 when you need the final output in this call — it blocks until the command exits, and you must not start other work while waiting. After approval_required, ask the user to approve the approval_id in an interactive terminal, then retry."
      }
    },
    "annotations": {
-   "description": "Run a shell command (cwd defaults to /home/runner/work/mcp-pin/mcp-pin). Asynchronous by default: returns run_id immediately, so poll project_shell_status for the output. Pass background=0 (or false) for a foreground run: the call blocks until the command exits and returns the final stdout/stderr. Commands pass a policy gate: risky ones return an approval_required error with a pending approval_id; catastrophic ones are denied outright. Named overrides require operator allowlisting and a per-call reason.\nUse when: build/test/lint/long-running commands. Default (background=1) returns run_id immediately so it never blocks other tools; set background=0 when you need the final output in this call — it blocks until the command exits, and you must not start other work while waiting. After approval_required, ask the user to approve the approval_id in an interactive terminal, then retry.\nAvoid when: a command that may never finish: use the async default plus project_shell_status/project_shell_cancel.\nSpeed: background=1 returns in ~5 ms, run time is up to the command; background=0 blocks for the whole run (bounded by timeout_ms, default 10 min).\nOutput: shell_run: run_id/shell_id, running, exit_code, background/foreground, stdout_tail/stderr_tail, timed_out, policy; background=0 also returns bounded stdout/stderr. approval_required: rule, reason, approval_id, retry_with.\nBatch-safe: no",
+   "description": "Run a shell command (cwd defaults to /home/runner/work/mcp-pin/mcp-pin). Asynchronous by default: returns run_id immediately, so poll project_shell_status for the output. Pass background=0 (or false) for a foreground run: the call blocks until the command exits and returns the final stdout/stderr. For commands that overwrite/delete existing workspace source files, create and verify a scoped project_snapshot first; prefer project file tools for targeted edits. Commands pass a policy gate: risky ones return an approval_required error with a pending approval_id; catastrophic ones are denied outright. Named overrides require operator allowlisting and a per-call reason.\nUse when: build/test/lint/long-running commands. For hard-to-reverse workspace file changes, checkpoint first. Default (background=1) returns run_id immediately so it never blocks other tools; set background=0 when you need the final output in this call — it blocks until the command exits, and you must not start other work while waiting. After approval_required, ask the user to approve the approval_id in an interactive terminal, then retry.\nAvoid when: a command that may never finish: use the async default plus project_shell_status/project_shell_cancel.\nSpeed: background=1 returns in ~5 ms, run time is up to the command; background=0 blocks for the whole run (bounded by timeout_ms, default 10 min).\nOutput: shell_run: run_id/shell_id, running, exit_code, background/foreground, stdout_tail/stderr_tail, timed_out, policy; background=0 also returns bounded stdout/stderr. approval_required: rule, reason, approval_id, retry_with.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Approval ID from npx venira-mcp --approve <id>. Use this instead of approval_token when auto-approval is disabled.",
+         "description": "Approval ID from the approval_required envelope, granted by a human running `data.approval.approve_command` or using client elicitation. Retry once after they confirm.",
          "type": "string"
        },
        "approval_scope": {
-         "description": "Legacy token-only compatibility. With approval_id, scope is chosen by the human at approval time (`--approve <id> --session`) and this field is ignored.",
+         "description": "Ignored: scope (once/session) is chosen by the human at approval time (`--approve <id> --session`), never by the model.",
          "enum": [
            "once",
            "session"
-         "description": "Single-use token from a previous approval_required envelope. Never invent or reuse one.",
+         "description": "REMOVED in v1.15: passing it returns an error. Use approval_id instead.",
          "type": "string"
        },
+       "approval_wait_ms": {
+         "description": "If the command needs approval, wait up to this many ms (max 45000) for the human to grant it and run in the same call. On timeout you get the normal approval_required response.",
+         "maximum": 45000,
+         "minimum": 0,
+         "type": "integer"
+       },
        "background": {
          "anyOf": [
            {
-         "description": "Command line to execute.",
+         "description": "Command line to execute. If it overwrites or deletes existing workspace source files, create and verify a scoped project_snapshot first; use project_write_file/project_edit_file/project_delete_path for targeted file operations.",
          "type": "string"
        },
+       "dry_run": {
+         "description": "1 = evaluate policy only: returns tier, rule and whether approval would be needed. Nothing runs and no approval is created.",
+         "maximum": 1,
+         "minimum": 0,
+         "type": "integer"
+       },
        "override": {
          "description": "Named exception; only works when the operator enabled this exact name in VENIRA_SHELL_OVERRIDES.",
          "enum": [
--- pinned/project_snapshot
+++ observed/project_snapshot
  {
    "_meta": {
      "venira": {
-       "avoid_when": "only one file changed and can be re-edited, or you already committed everything and don't need a safety net.",
+       "avoid_when": "a tiny, easily recreated single-file edit, generated build output, or a commit already provides the needed recovery point; do not restore over newer user changes without inspecting them.",
        "batch_safe": false,
        "output_kind": "snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed.",
-       "speed_profile": "create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, sha256-verified by default.",
-       "use_when": "before a multi-file refactor/rename: action=create (paths defaults to ['.']) then action=restore id=<id> if the change goes wrong. Example: create snapshot → edit 3 files → tests fail → restore snapshot in one call instead of re-editing each file manually."
+       "speed_profile": "create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, SHA-256 verified by default; dry_run previews path/size only, not same-size content changes.",
+       "use_when": "before multi-file, cross-file, refactor/rename or hard-to-reverse edits: create with a descriptive label, scope paths to the affected area, retain the exact returned id, and confirm required files were captured. For rollback, run restore dry_run=1 to preview path/size changes (same-size content differences are not detected); inspect files with newer user edits, then restore the exact id with verify=1 and delete_extra=0. Example: checkpoint → edit 3 files → tests fail → inspect scope → restore."
      }
    },
    "annotations": {
-   "description": "Checkpoint/rollback for the workspace: snapshot the current bytes before a large edit chain, then restore in one call. Content-addressed and deduplicated (only changed files cost new space).\nUse when: before a multi-file refactor/rename: action=create (paths defaults to ['.']) then action=restore id=<id> if the change goes wrong. Example: create snapshot → edit 3 files → tests fail → restore snapshot in one call instead of re-editing each file manually.\nAvoid when: only one file changed and can be re-edited, or you already committed everything and don't need a safety net.\nSpeed: create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, sha256-verified by default.\nOutput: snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed.\nBatch-safe: no",
+   "description": "Checkpoint/rollback for the workspace: create a labeled, scoped snapshot before multi-file or hard-to-reverse edits; keep its returned id. For rollback, preview with restore dry_run=1 (size-based preview only; it cannot detect same-size content changes), inspect newer user edits, then restore that exact id with verify=1 and delete_extra=0. Content-addressed and deduplicated.\nUse when: before multi-file, cross-file, refactor/rename or hard-to-reverse edits: create with a descriptive label, scope paths to the affected area, retain the exact returned id, and confirm required files were captured. For rollback, run restore dry_run=1 to preview path/size changes (same-size content differences are not detected); inspect files with newer user edits, then restore the exact id with verify=1 and delete_extra=0. Example: checkpoint → edit 3 files → tests fail → inspect scope → restore.\nAvoid when: a tiny, easily recreated single-file edit, generated build output, or a commit already provides the needed recovery point; do not restore over newer user changes without inspecting them.\nSpeed: create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, SHA-256 verified by default; dry_run previews path/size only, not same-size content changes.\nOutput: snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "restore only: 1 also deletes files inside captured dirs not in the checkpoint (capped at 500); 0 keeps them.",
+         "description": "restore only: 1 also deletes files inside captured dirs not in the checkpoint (capped at 500); default/0 keeps them. Use 1 only when deletion is explicitly intended.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "restore only: 1 reports changes without writing; 0 writes the restore.",
+         "description": "restore only: 1 previews path/size changes without writing (same-size content changes are not detected); inspect current user edits before applying.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "Paths to capture (default ['.']); restore accepts a subset to filter files.",
+         "description": "Capture affected paths (default ['.'] only when scope is unclear); restore accepts a subset to filter files.",
          "items": {
            "type": "string"
          },
--- pinned/project_symbol_references
+++ observed/project_symbol_references
  {
    "_meta": {
      "venira": {
-       "avoid_when": "you only need its declaration (project_file_symbols) or an arbitrary string (project_search).",
+       "avoid_when": "you only need its declaration (project_outline_symbol) or an arbitrary string (project_search).",
        "batch_safe": true,
        "output_kind": "symbol_references: count, references[] {relative_path, line_number, context}.",
        "speed_profile": "fast for scope=file; medium for scope=workspace (single search call).",
-   "description": "Find every occurrence of a named symbol. scope=file (fast, single file) or scope=workspace (uses content search).\nUse when: you need to know where a symbol is used before renaming/refactoring it.\nAvoid when: you only need its declaration (project_file_symbols) or an arbitrary string (project_search).\nSpeed: fast for scope=file; medium for scope=workspace (single search call).\nOutput: symbol_references: count, references[] {relative_path, line_number, context}.\nBatch-safe: yes",
+   "description": "Find every occurrence of a named symbol. scope=file (fast, single file) or scope=workspace (uses content search).\nUse when: you need to know where a symbol is used before renaming/refactoring it.\nAvoid when: you only need its declaration (project_outline_symbol) or an arbitrary string (project_search).\nSpeed: fast for scope=file; medium for scope=workspace (single search call).\nOutput: symbol_references: count, references[] {relative_path, line_number, context}.\nBatch-safe: yes",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_write_file
+++ observed/project_write_file
  {
    "_meta": {
      "venira": {
-       "avoid_when": "only a small section needs to change (project_edit_file) to leave the rest intact.",
+       "avoid_when": "only a small section needs to change (project_edit_file), or an existing file would be overwritten without a verified pre-write project_snapshot.",
        "batch_safe": false,
        "output_kind": "file_written: action, bytes_written, sha256_after.",
        "speed_profile": "fast; clears the read/list/search cache for the affected path.",
-       "use_when": "create a new file or replace/append a file's contents."
+       "use_when": "create a new file or append content; before mode=overwrite on an existing file, create a scoped project_snapshot, confirm it captured the target, and keep the returned id."
      }
    },
    "annotations": {
-   "description": "Write a file. mode=create errors if it exists; overwrite replaces; append concatenates to the end.\nUse when: create a new file or replace/append a file's contents.\nAvoid when: only a small section needs to change (project_edit_file) to leave the rest intact.\nSpeed: fast; clears the read/list/search cache for the affected path.\nOutput: file_written: action, bytes_written, sha256_after.\nBatch-safe: no",
+   "description": "Write a file. mode=create errors if it exists; overwrite replaces existing contents; append concatenates. Create and verify a scoped project_snapshot before overwriting existing file contents.\nUse when: create a new file or append content; before mode=overwrite on an existing file, create a scoped project_snapshot, confirm it captured the target, and keep the returned id.\nAvoid when: only a small section needs to change (project_edit_file), or an existing file would be overwritten without a verified pre-write project_snapshot.\nSpeed: fast; clears the read/list/search cache for the affected path.\nOutput: file_written: action, bytes_written, sha256_after.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
+         "description": "overwrite replaces existing contents; create and verify a scoped project_snapshot first. create fails if the path exists; append adds to the end.",
          "enum": [
            "create",
            "overwrite",

Changed 2026-11-06 14:18 UTC

5 descriptions rewritten, 1 schema or annotation change with the description left byte-identical, 14 tools removed.

--- pinned/project_dependency_graph
+++ observed/project_dependency_graph
  {
    "_meta": {
      "venira": {
-   "description": "Build a deterministic file/symbol dependency graph for TypeScript/JavaScript and Python (relative imports, require(), dynamic import(), extends/implements, cross-file symbol references). Renders as JSON, DOT or Mermaid.\nUse when: you need the import graph, a module map to render, or the files/symbols a change can reach before refactoring.\nAvoid when: you only need usages of one symbol in one file (project_symbol_references) or a text search (project_search).\nSpeed: medium; bounded walk (<=5000 files / 64 MB), parser-lite line scan, 5 s index cache invalidated on writes. No network.\nOutput: dependency_graph: nodes[] {id, type, language, loc}, edges[] {from, to, type (import|extends|implements|references), confidence, line, via}, external[] {id, used_by}, unresolved[], stats, truncated; format=dot|mermaid returns data.graph.\nBatch-safe: yes",
+   "description": "Build a deterministic file/symbol dependency graph for TypeScript/JavaScript, Python, Rust, Go, Java and Kotlin (module declarations, pub mod, use crate::/super::, extern crate, go.mod module resolution, import (...) blocks, relative imports, require(), dynamic import(), extends/implements, cross-file symbol references). Renders as JSON, DOT or Mermaid.\nUse when: you need the import graph, a module map to render, or the files/symbols a change can reach before refactoring.\nAvoid when: you only need usages of one symbol in one file (project_symbol_references) or a text search (project_search).\nSpeed: medium; bounded walk (<=5000 files / 64 MB), parser-lite line scan, 5 s index cache invalidated on writes. No network.\nOutput: dependency_graph: nodes[] {id, type, language, loc}, edges[] {from, to, type (import|extends|implements|references), confidence, line, via}, external[] {id, used_by}, unresolved[], stats, truncated; format=dot|mermaid returns data.graph.\nBatch-safe: yes",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "description": "Language filter, e.g. [\"ts\",\"py\"] (default: all supported).",
+         "description": "Language filter, e.g. [\"ts\",\"py\",\"rs\",\"go\",\"java\",\"kotlin\"] (default: all supported).",
          "items": {
            "maxLength": 20,
            "type": "string"
--- pinned/project_edit_batch
+++ observed/project_edit_batch
  {
    "_meta": {
      "venira": {
-       "use_when": "you have 2+ independent edits across one or more files."
+       "use_when": "you have 2+ independent edits across one or more files. Consider project_snapshot action=create first so you can rollback the whole batch in one call if something goes wrong."
      }
    },
    "annotations": {
-   "description": "Apply multiple edit_file operations atomically in one call; aborts after the first failure and restores the pre-batch snapshot when possible.\nUse when: you have 2+ independent edits across one or more files.\nAvoid when: a single edit (project_edit_file) or a whole-file rewrite (project_write_file).\nSpeed: depends on item count; each runs edit_file and clears caches.\nOutput: batch: responses[] {ok, response|error}, atomic metadata with executed/skipped indexes and rollback status.\nBatch-safe: no",
+   "description": "Apply multiple edit_file operations atomically in one call; aborts after the first failure and restores the pre-batch snapshot when possible.\nUse when: you have 2+ independent edits across one or more files. Consider project_snapshot action=create first so you can rollback the whole batch in one call if something goes wrong.\nAvoid when: a single edit (project_edit_file) or a whole-file rewrite (project_write_file).\nSpeed: depends on item count; each runs edit_file and clears caches.\nOutput: batch: responses[] {ok, response|error}, atomic metadata with executed/skipped indexes and rollback status.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
--- pinned/project_edit_file
+++ observed/project_edit_file
  {
    "_meta": {
      "venira": {
-       "output_kind": "file_written: replacements, sha256_before/after.",
+       "output_kind": "file_written: replacements, sha256_before/after, verified (with guard=sha256).",
        "speed_profile": "fast; clears the read/list/search cache for the affected path.",
-       "use_when": "change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites."
+       "use_when": "change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify cycle (replaces safe_edit). If editing 2+ files or 2+ sections, create a project_snapshot first so you can rollback in one call."
      }
    },
    "annotations": {
-   "description": "Edit a file by exact text replacement: one old_text/new_text pair, or edits[] for multiple sections.\nUse when: change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites.\nAvoid when: the whole file must change (project_write_file), or you have not read the file to know old_text.\nSpeed: fast; clears the read/list/search cache for the affected path.\nOutput: file_written: replacements, sha256_before/after.\nBatch-safe: no",
+   "description": "Edit a file by exact text replacement: one old_text/new_text pair, or edits[] for multiple sections. Supports TOCTOU guard mode (guard=sha256) for atomic read-edit-verify cycle.\nUse when: change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify cycle (replaces safe_edit). If editing 2+ files or 2+ sections, create a project_snapshot first so you can rollback in one call.\nAvoid when: the whole file must change (project_write_file), or you have not read the file to know old_text.\nSpeed: fast; clears the read/list/search cache for the affected path.\nOutput: file_written: replacements, sha256_before/after, verified (with guard=sha256).\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
+       "guard": {
+         "description": "TOCTOU guard: 'sha256' reads fresh content, verifies expected_sha256, applies edits, writes, then re-reads to verify content+sha256 match. Provides atomic read-edit-verify cycle.",
+         "enum": [
+           "sha256"
+         ],
+         "type": "string"
+       },
        "ignore_indentation": {
          "description": "P2: Ignore leading whitespace differences in fuzzy matching; 1=on, 0=off.",
          "maximum": 1,
--- pinned/project_read_file
+++ observed/project_read_file
  {
    "_meta": {
      "venira": {
+       "ranges": {
+         "description": "Multiple disjoint ranges of the SAME file (max 16). Use instead of multiple read_file calls.",
+         "items": {
+           "properties": {
+             "end_line": {
+               "maximum": 9007199254740991,
+               "minimum": 1,
+               "type": "integer"
+             },
+             "max_bytes": {
+               "maximum": 9007199254740991,
+               "minimum": 1,
+               "type": "integer"
+             },
+             "start_line": {
+               "maximum": 9007199254740991,
+               "minimum": 1,
+               "type": "integer"
+             }
+           },
+           "required": [
+             "start_line"
+           ],
+           "type": "object"
+         },
+         "maxItems": 16,
+         "minItems": 1,
+         "type": "array"
+       },
        "relative_path": {
          "description": "Path inside the workspace (relative, or absolute inside the workspace)",
          "type": "string"
--- pinned/project_search
+++ observed/project_search
  {
    "_meta": {
      "venira": {
-       "output_kind": "search: hits, complete, diagnostics, hint.",
+       "output_kind": "search: hits (source+confidence when hybrid:1), complete, diagnostics, hint.",
        "speed_profile": "medium (file scan); TTL cache 3s for the same query.",
        "use_when": "you need to find code/strings/symbols before reading; use kind=literal_content or definition."
      }
-   "description": "Search by file name, directory name, content (literal or regex=1), or symbol declaration lines (definition).\nUse when: you need to find code/strings/symbols before reading; use kind=literal_content or definition.\nAvoid when: you already know the exact path to read.\nSpeed: medium (file scan); TTL cache 3s for the same query.\nOutput: search: hits, complete, diagnostics, hint.\nBatch-safe: yes",
+   "description": "Search by file name, directory name, content (literal or regex=1), or symbol declaration lines (definition).\nUse when: you need to find code/strings/symbols before reading; use kind=literal_content or definition.\nAvoid when: you already know the exact path to read.\nSpeed: medium (file scan); TTL cache 3s for the same query.\nOutput: search: hits (source+confidence when hybrid:1), complete, diagnostics, hint.\nBatch-safe: yes",
    "execution": {
      "taskSupport": "forbidden"
    },
+       "hybrid": {
+         "description": "1 = tag each hit with source (symbol_index|symbol_reference|content) and confidence (exact_match|text_match); a scoped identifier query with 0 hits widens once to the workspace (scope_widened:true). literal_content only.",
+         "maximum": 1,
+         "minimum": 0,
+         "type": "integer"
+       },
        "include_hidden": {
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 = include hidden files (default); 0 = skip dotfiles (rg-style). Secrets (.env*, credentials, keys) are always excluded either way.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
-         "description": "Numeric flag: 1=enabled, 0=disabled.",
+         "description": "1 = whole-word match only (rg -w / JS word boundaries) for literal_content and definition.",
          "maximum": 1,
          "minimum": 0,
          "type": "integer"
--- pinned/project_snapshot
+++ observed/project_snapshot
  {
    "_meta": {
      "venira": {
-       "avoid_when": "the repo is clean in git (git is cheaper), or only one file changed and can be re-edited.",
+       "avoid_when": "only one file changed and can be re-edited, or you already committed everything and don't need a safety net.",
        "batch_safe": false,
        "output_kind": "snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed.",
        "speed_profile": "create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, sha256-verified by default.",
-       "use_when": "before a multi-file refactor/rename: action=create (paths defaults to ['.']) then action=restore with the returned id if the change goes wrong."
+       "use_when": "before a multi-file refactor/rename: action=create (paths defaults to ['.']) then action=restore id=<id> if the change goes wrong. Example: create snapshot → edit 3 files → tests fail → restore snapshot in one call instead of re-editing each file manually."
      }
    },
    "annotations": {
-   "description": "Checkpoint/rollback for the workspace: snapshot the current bytes before a large edit chain, then restore in one call. Content-addressed and deduplicated (only changed files cost new space).\nUse when: before a multi-file refactor/rename: action=create (paths defaults to ['.']) then action=restore with the returned id if the change goes wrong.\nAvoid when: the repo is clean in git (git is cheaper), or only one file changed and can be re-edited.\nSpeed: create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, sha256-verified by default.\nOutput: snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed.\nBatch-safe: no",
+   "description": "Checkpoint/rollback for the workspace: snapshot the current bytes before a large edit chain, then restore in one call. Content-addressed and deduplicated (only changed files cost new space).\nUse when: before a multi-file refactor/rename: action=create (paths defaults to ['.']) then action=restore id=<id> if the change goes wrong. Example: create snapshot → edit 3 files → tests fail → restore snapshot in one call instead of re-editing each file manually.\nAvoid when: only one file changed and can be re-edited, or you already committed everything and don't need a safety net.\nSpeed: create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, sha256-verified by default.\nOutput: snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed.\nBatch-safe: no",
    "execution": {
      "taskSupport": "forbidden"
    },
-         "maximum": 4000,
+         "maximum": 20000,
          "minimum": 1,
          "type": "integer"
        },

tool removed: project_ci_logs

tool removed: project_ci_status

tool removed: project_ci_trigger

tool removed: project_ci_wait

tool removed: project_create_directory

tool removed: project_file_symbols

tool removed: project_pr_close

tool removed: project_pr_comment

tool removed: project_pr_create

tool removed: project_pr_list

tool removed: project_pr_merge

tool removed: project_pr_reopen

tool removed: project_read_ranges

tool removed: project_safe_edit

Current tools

Show all 38 tool fingerprints
apply_patch
b0b3e605a77bcf75
cache_clear
28a16382d7d1dc7e
change_impact
af13152243b2ddfd
copy_path
13c7b9f76e0be13e
create
b217972dc9e7c5fe
delete_path
083edf7262472b1c
dependency_graph
85c42617351995c3
diff_files
cbb33cf97cca4f20
edit_batch
2afb58de30c61902
edit_file
d469024475825174
get_file_info
4237153e135585f2
git_branch
63d27a6560da6aa9
git_commit
1b986a9d04a1eff3
git_diff
80c8a2cf648223a5
git_log
7c5efc08b8c14514
git_stash
463b6151f7df47f3
git_status
621bd2bc63ac77c2
github_connect
695f6481d2d8f481
health
77aadf424c3eb71a
list_files
aaea75aaac4b508a
memory
93075e2f89738e63
move_path
96dc534c359970d8
outline_symbol
52dd1e9f5a3b065c
read_audit
f6a6b50b83263882
read_batch
bb5b7e80a108a44a
read_file
70a844968fb7e62e
recent_files
e4c26dfcfdb9a1f4
search
ce2d9c85213ebca9
secret
082f5ad017d26c99
shell_cancel
0fa6355946fee289
shell_cancel_session
aa3faf8274ef6555
shell_run
a71d381416e3da74
shell_status
b8cdbe62b4fa1940
snapshot
0c6a9d7729295031
switch_workspace
91e7081aeca33338
symbol_references
bae5417ae6c3d316
trace_status
cdb8d1ba70dec1ee
write_file
a0e4cb3c480eff7f

Watch this server yourself

If you run this server, put the proxy in front of it. It pins these exact fingerprints on first connect and stops the session if they move.

npx -y mcp-pin@0.2.4 -- <your venira-mcp command>

Or subscribe to this page's RSS feed to be told when it changes.

Badge

mcp-pin status badge for venira-mcp

The badge states one fact about time and nothing else. It never claims a server is safe.

[![mcp-pin](https://mcp-pin.gautamkhosla.com/badge/55e4b222fc060625.svg)](https://mcp-pin.gautamkhosla.com/servers/55e4b222fc060625.html)