List the files and subdirectories at a given path in the canonical-vault repository (kushkillerjsixx66/canonical-vault).

Args:

• path (string): Directory path relative to repo root (default: "" for root)

• ref (string): Branch, tag, or commit SHA (default: 'main')

• response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "path": string, "ref": string, "entries": [{ "name": string, "path": string, "type": "file"|"dir", "size": number }] }

Examples:

• Use when: "What's in the governance directory?" -> path="governance"

• Use when: "Show me the top-level structure of the vault" -> path=""

• Don't use when: You need the actual contents of a file (use vault_get_file instead)

Error Handling:

• Returns "Error: ... not found" if the path doesn't exist on that ref

• Returns a rate limit message if GitHub's API limit is exceeded (set GITHUB_TOKEN to raise it)

Fetch the decoded text content of a single file from the canonical-vault repository (kushkillerjsixx66/canonical-vault).

Args:

• path (string): File path relative to repo root, e.g. 'governance/CONSTITUTION.md'

• ref (string): Branch, tag, or commit SHA (default: 'main')

Returns: The raw file text, prefixed with a small header (path, ref, sha, size). Binary or oversized files (> 500000 bytes) return an error instead of garbled content.

Examples:

• Use when: "Read me the current Constitution" -> path="governance/CONSTITUTION.md"

• Use when: "What does vara.py look like right now?" -> path="vara.py"

• Don't use when: You just want to know if a file exists or how big it is (use vault_list_directory instead)

Error Handling:

• Returns "Error: ... not found" if the path doesn't exist on that ref

• Returns an error for directories (use vault_list_directory instead) or binary files

Get the commit lineage (history) affecting a file or directory in canonical-vault — i.e. every commit that touched that path, most recent first.

Args:

• path (string): File or directory path to trace (default: "" for whole-repo history)

• ref (string): Branch, tag, or commit SHA to start from (default: 'main')

• limit (number): Max commits to return, 1-100 (default: 20)

• offset (number): Commits to skip for pagination (default: 0)

• response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "path": string, "count": number, "commits": [{ "sha": string, "message": string, "author": string, "date": string, "url": string }], "has_more": boolean }

Examples:

• Use when: "How has VARA_SPEC_1.0 evolved?" -> path="system-specs/VARA_SPEC_1.0.md"

• Use when: "What's the recent commit lineage for the whole vault?" -> path=""

• Don't use when: You need the full diff of one specific commit (use vault_get_commit instead)

Error Handling:

• Returns "Error: ... not found" if the path or ref doesn't exist

Get full detail for a single commit in canonical-vault: message, author, stats, and the list of files it changed (with per-file diff stats).

Args:

• sha (string): Full or abbreviated commit SHA (get one from vault_get_file_history)

• response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "sha": string, "message": string, "author": string, "date": string, "stats": {...}, "files": [{ "filename": string, "status": string, "additions": number, "deletions": number }] }

Examples:

• Use when: "What exactly changed in commit a1b2c3d?" -> sha="a1b2c3d"

• Don't use when: You just want the commit list for a path (use vault_get_file_history instead)

Error Handling:

• Returns "Error: ... not found" if the SHA doesn't exist in this repo

Search file names and contents across the canonical-vault repository (kushkillerjsixx66/canonical-vault) using GitHub code search.

Args:

• query (string): Search terms. Supports GitHub code search qualifiers like 'path:governance' or 'extension:md'

• limit (number): Max results, 1-50 (default: 20)

• offset (number): Results to skip for pagination (default: 0)

• response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "total": number, "count": number, "results": [{ "path": string, "url": string }], "has_more": boolean }

Examples:

• Use when: "Where is Coherence defined?" -> query="Coherence path:governance"

• Use when: "Find every mention of vara.py" -> query="vara.py"

• Don't use when: You already know the exact path (use vault_get_file instead)

Error Handling:

• Returns "No files found matching ''" if the search returns empty

• GitHub code search only indexes the default branch and repos under ~size limits; very new commits may lag briefly