Merge pull request #509 from manojmallick/feat/budget-ledger-508

feat(tracking,mcp): sigmap budget — session spend ledger + get_budget (F1, v8.23)

Author: manojmallick

README.md

@@ -222,7 +222,7 @@ Use SigMap with open-source tools and fully self-hosted setups:
 | **JetBrains** | [Marketplace](https://plugins.jetbrains.com/plugin/31109-sigmap--ai-context-engine/) | [github.com/manojmallick/sigmap-jetbrains](https://github.com/manojmallick/sigmap-jetbrains) | IntelliJ IDEA, WebStorm, PyCharm, GoLand — tool window + actions |
 | **Neovim** | lazy.nvim / packer / vim-plug | [github.com/manojmallick/sigmap.nvim](https://github.com/manojmallick/sigmap.nvim) | `:SigMap`, `:SigMapQuery` float window, statusline widget |
 
-**MCP server** — 20 on-demand tools for Claude Code and Cursor:
+**MCP server** — 21 on-demand tools for Claude Code and Cursor:
 
 ```bash
 sigmap --mcp
@@ -269,7 +269,7 @@ SigMap treats coding agents as **consumers, not competitors**: it hands them a d
 
 | Agent | One-time setup | How it consumes SigMap |
 |---|---|---|
-| **Claude Code** | `sigmap mcp install claude` | 20 MCP tools (`search_signatures`, `get_lines`, `get_diff_context`, `squeeze_output`…) |
+| **Claude Code** | `sigmap mcp install claude` | 21 MCP tools (`search_signatures`, `get_lines`, `get_diff_context`, `squeeze_output`…) |
 | **Cursor** | `sigmap mcp install cursor` | MCP tools, plus the `cursor` adapter writes `.cursorrules` |
 | **Cline** | `sigmap mcp install cursor` | Reads `.cursorrules`; same MCP server |
 | **Continue** | `sigmap mcp install vscode` | MCP tools inside the Continue extension |

docs-vp/guide/mcp.md

@@ -1,6 +1,6 @@
 ---
 title: MCP server setup
-description: Set up the SigMap MCP server for Claude Code, Cursor, and Windsurf. On-demand codebase access with 20 tools over stdio. Zero npm install.
+description: Set up the SigMap MCP server for Claude Code, Cursor, and Windsurf. On-demand codebase access with 21 tools over stdio. Zero npm install.
 head:
   - - meta
     - property: og:title
@@ -22,7 +22,7 @@ head:
 
 Give Claude Code, Cursor, and Windsurf on-demand access to your codebase signatures. Zero npm install.
 
-The SigMap MCP server exposes 20 tools over the stdio Model Context Protocol. Your AI agent calls only what it needs — keeping token costs low.
+The SigMap MCP server exposes 21 tools over the stdio Model Context Protocol. Your AI agent calls only what it needs — keeping token costs low.
 
 > **Setup time: under 2 minutes.** Use `sigmap --setup` for automatic configuration.
 
@@ -99,7 +99,7 @@ Stack both MCP servers for the two-layer context strategy — SigMap for always-
 ## 11 available tools
 
 ::: tip New in v6.3.0 — native tool registration
-Claude Code and Codex now receive the full tool list at MCP startup without a discovery round-trip. The server declares all 20 tools in the `initialize` response, so your AI sees them immediately. No config change needed — upgrade via `npm install -g sigmap@latest`.
+Claude Code and Codex now receive the full tool list at MCP startup without a discovery round-trip. The server declares all 21 tools in the `initialize` response, so your AI sees them immediately. No config change needed — upgrade via `npm install -g sigmap@latest`.
 :::
 
 All tools are available on-demand — your AI agent calls only what it needs.

docs-vp/public/llms-full.txt

@@ -26,7 +26,7 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 | Task-success proxy (modeled) | — | 64.8% |
 | Prompts per task | 2.84 | 1.53 (46.1% fewer) |
 | Supported languages | — | 33 |
-| MCP tools | — | 20 |
+| MCP tools | — | 21 |
 | npm runtime dependencies | — | 0 |
 
 ---
@@ -125,6 +125,8 @@ sigmap evidence "<query>" --markdown     Emit the Markdown handoff rendering to
 sigmap evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked files / token budget / write rendered output
 sigmap memory                            List cross-session stores (.context/) — entries, size, age
 sigmap memory --clear <store>            Clear one store: session|notes|weights|evidence|all (--json supported)
+sigmap budget                            Session spend ledger — estimated SigMap-emitted tokens, budget, context age (--json)
+sigmap budget --budget <tokens>          One-off budget override (config: sessionBudgetTokens, contextTtlDays)
 sigmap note "<text>"                     Append a note to the cross-session decision log
 sigmap note                              List recent notes (also: note --list <N>)
 sigmap status                            Show repo state — branch, dirty files, index freshness, notes
@@ -138,7 +140,7 @@ sigmap --version                         Show version
 
 ---
 
-## MCP server — 20 tools
+## MCP server — 21 tools
 
 Start with `sigmap --mcp` (stdio JSON-RPC). Configure once:
 
@@ -306,6 +308,14 @@ Compress noisy tool, command, or agent output before it enters context — a sta
 Input:  { content: string }
 ```
 
+### get_budget
+
+Session spend ledger — estimated tokens SigMap has emitted this session (chars/4 estimates from the local gain log), optional budget remaining, and context freshness. Scope honesty: counts only SigMap output, NOT the whole chat's spend. Check this mid-session and degrade gracefully when near budget: prefer terse encoding, squeeze large outputs, summarize-then-drop context. Local-only; no LLM, no network.
+
+```
+Input:  { session?: string, budgetTokens?: number }
+```
+
 ---
 
 ## Configuration (gen-context.config.json)
@@ -334,6 +344,8 @@ watchDebounce = 300
 routing = false
 format = default
 tracking = false
+sessionBudgetTokens = null
+contextTtlDays = null
 mcp = {"autoRegister":true}
 depMap = true
 versionPins = true

docs-vp/public/llms.txt

@@ -29,7 +29,7 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - Token reduction: 96.8% average across benchmark repos
 - Task-success proxy: 64.8% (modeled from retrieval tiers, not measured LLM sessions)
 - Prompts per task: 1.53 vs 2.84 baseline (46.1% fewer, modeled)
-- Languages: 33 supported · MCP tools: 20
+- Languages: 33 supported · MCP tools: 21
 - Dependencies: zero npm runtime dependencies · fully offline
 
 ## Quick start