thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core-4.0.0.dist-info/METADATA

@@ -0,0 +1,868 @@
+Metadata-Version: 2.4
+Name: thinkstack-core
+Version: 4.0.0
+Summary: ThinkStack — AI reasoning capture, audit trail, and governance for agent-assisted development (core library)
+Author-email: Hemant Joshi <hemant@flotorch.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/hemantcgi/ThinkStack
+Project-URL: Repository, https://github.com/hemantcgi/ThinkStack
+Project-URL: Documentation, https://github.com/hemantcgi/ThinkStack/blob/main/Implementation/README.md
+Keywords: ai,agents,governance,audit,llm,reasoning,thinkstack
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: boto3>=1.34.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Requires-Dist: pdfminer.six>=20221105; extra == "dev"
+Provides-Extra: wrapper
+Requires-Dist: anthropic>=0.40.0; extra == "wrapper"
+Requires-Dist: openai>=1.50.0; extra == "wrapper"
+Requires-Dist: google-generativeai>=0.8.0; extra == "wrapper"
+Requires-Dist: boto3>=1.35.0; extra == "wrapper"
+Requires-Dist: tiktoken>=0.7.0; extra == "wrapper"
+Provides-Extra: proxy
+Requires-Dist: fastapi>=0.115.0; extra == "proxy"
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == "proxy"
+Requires-Dist: httpx>=0.27.0; extra == "proxy"
+Requires-Dist: pydantic>=2.9.0; extra == "proxy"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3.0.0; extra == "embeddings"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: audit
+Requires-Dist: cryptography>=42.0.0; extra == "audit"
+Requires-Dist: reportlab>=4.0.0; extra == "audit"
+Requires-Dist: presidio-analyzer>=2.2.0; extra == "audit"
+Provides-Extra: cloud
+Requires-Dist: fastapi>=0.111.0; extra == "cloud"
+Requires-Dist: uvicorn[standard]>=0.29.0; extra == "cloud"
+Requires-Dist: boto3>=1.34.0; extra == "cloud"
+Requires-Dist: PyJWT>=2.8.0; extra == "cloud"
+Requires-Dist: cryptography>=42.0.0; extra == "cloud"
+Requires-Dist: PyNaCl>=1.5.0; extra == "cloud"
+Requires-Dist: azure-storage-blob>=12.19.0; extra == "cloud"
+Provides-Extra: broadcast
+Requires-Dist: watchdog>=3.0.0; extra == "broadcast"
+Provides-Extra: all
+Requires-Dist: thinkstack-core[audit,cloud,embeddings,mcp,proxy,wrapper]; extra == "all"
+
+# ThinkStack
+
+**Local-first AI agent governance.** ThinkStack gives multi-agent systems a shared on-disk audit trail, coordination vector, privacy controls, and LLM integration layer — all without a remote service.
+
+> **Latest release:** `thinkstack-core` and `thinkstack-cli` **3.0.2** — Local-first AI governance split into a core SDK (`thinkstack-core`) and a CLI (`thinkstack-cli`). Install or upgrade with `pip install -U thinkstack-cli`.
+
+```bash
+pip install -U thinkstack-cli>=3.0.1
+thinkstack init
+thinkstack setup          # connects to Claude Code, Cursor, or Antigravity
+thinkstack debug timeline
+```
+
+---
+
+## What it does
+
+| Concern | ThinkStack feature |
+|---------|-----------------|
+| Reasoning audit trail | Append-only `.GCC/events.log.jsonl` with SHA-256 hash chain |
+| Multi-agent coordination | Coordination vector Θ — shared sensitivity map across agents |
+| Privacy compliance | RDP ε-budget tracking; `[PRIVATE]` span suppression; SIS-TC quarantine |
+| LLM integration | SDK wrappers, HTTP proxy, Claude Code MCP server + hooks |
+| Cloud MCP server | Multi-tenant SSE endpoint; AWS S3, Azure Blob, Cloudflare R2 storage; API key + GitHub OAuth + SSO/JWKS auth |
+| Governance observability | Structured reports, browser dashboard, VS Code extension (Antigravity-compatible) |
+| Alerting | Slack, Jira, PagerDuty outbound webhooks |
+| Metrics | MCS, DHS, ROI — all traceable to citations or explicit design choices |
+
+### Reasoning Plus
+
+Reasoning Plus is ThinkStack’s default augmentation mode: before every LLM call, it gathers smart context from your workspace, asks the model to produce inline `<thinking>` reasoning, and learns from previous calls by re-injecting relevant reasoning into subsequent prompts. The reasoning is captured to `.GCC/` automatically and stripped from the response your tool sees.
+
+```bash
+thinkstack reasoning-plus status          # show current settings
+thinkstack reasoning-plus enable          # turn on per project
+thinkstack reasoning-plus disable         # turn off per project
+thinkstack reasoning-plus config --smart-top-n 3 --smart-max-lines 150 --learning-top-n 3
+```
+
+Set `THINKSTACK_REASONING_PLUS=0` to disable it for a single session. See [REASONING_PLUS.md](REASONING_PLUS.md) for details.
+
+Everything lives in `.GCC/` — a local directory in your project. No database, no network service, no telemetry.
+
+---
+
+## Install
+
+```bash
+pip install thinkstack-cli
+```
+
+**Requirements:** Python 3.10+
+
+One-liner installer (Linux/macOS/WSL):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/hemantcgi/ThinkStack/main/Implementation/scripts/install.sh | bash
+```
+
+This installs `thinkstack-cli` into an isolated virtual environment at `~/.thinkstack-venv` and links `thinkstack` onto PATH. It also supports `pip install` if you prefer to manage your own environment.
+
+For optional extras:
+
+```bash
+pip install thinkstack-cli[wrapper]   # SDK wrappers (Anthropic, OpenAI, Gemini, Bedrock, Ollama)
+pip install thinkstack-cli[proxy]     # HTTP proxy + dashboard API (FastAPI)
+pip install thinkstack-cli[all]       # everything
+```
+
+> PyPI packages are `thinkstack-core` (library/SDK) and `thinkstack-cli` (CLI). The CLI command and import paths remain `thinkstack` / `thinkstack_core`.
+
+---
+
+## Upgrade from an older version
+
+ThinkStack preserves your `.GCC/` store across upgrades. Newer releases add IDE configs, hooks, or governance instructions, so you should re-run `thinkstack setup` after upgrading.
+
+**Upgrade any time:**
+
+```bash
+pip install -U thinkstack-cli>=3.0.1
+cd /path/to/your/project
+thinkstack setup              # or: thinkstack setup --target <ide>
+thinkstack doctor
+```
+
+`thinkstack setup` is idempotent:
+- It rewrites `CLAUDE.md` / `AGENTS.md` with the latest governance instructions.
+- It regenerates IDE-specific config files (`.claude/settings.json`, `.cursor/mcp.json`, `opencode.json`, etc.).
+- It leaves existing `.GCC/` data untouched.
+
+**If you use the cloud MCP server**, re-run the client config installer after upgrade to get the latest bridge and fallback settings:
+
+```bash
+export THINKSTACK_MCP_DOMAIN=thinkstack-mcp.your-domain.com
+thinkstack cloud client-config <ide> --org <org> --repo <repo> --api-key <api-key>
+```
+
+Supported `<ide>` values: `opencode`, `claude`, `cursor`, `vscode`, `stdio`.
+
+---
+
+## Getting Started
+
+ThinkStack takes **5 minutes to set up**. Pick your AI coding tool below.
+
+> **Prerequisites:** Python 3.10+, pip, and the AI tool you plan to use.
+
+---
+
+### Claude Code
+
+Claude Code is the highest-fidelity integration — hooks fire on every file write, MCP tools give Claude native governance commands, and `CLAUDE.md` carries persistent instructions across sessions.
+
+**Step 1 — Install ThinkStack**
+```bash
+pip install thinkstack-cli
+```
+
+**Step 2 — Go to your project and run setup**
+```bash
+cd /path/to/your/project
+thinkstack setup
+```
+
+This single command:
+- Initialises `.GCC/` (the local governance store)
+- Writes `.claude/hooks.json` so hooks fire on every Write, Edit, Bash, and Stop event
+- Adds the ThinkStack MCP server to `.claude/settings.json`
+- Writes governance instructions into `CLAUDE.md`
+
+**Step 3 — Verify**
+```bash
+thinkstack doctor
+```
+
+Expected output: all checks green. If any check fails, the doctor output tells you exactly what to fix.
+
+**Step 4 — Start using Claude Code**
+
+Open Claude Code in your project. On the first task Claude will call `thinkstack_context` to load prior reasoning, and `thinkstack_commit` before any file edit. The `.GCC/` store captures everything automatically.
+
+**What you get:** Full RACP integration — reasoning commits, sensitivity events, coordination vector Θ, divergence detection, HITL conflict resolution.
+
+> **Updating from an older version:** `pip install -U thinkstack-cli>=3.0.1 && thinkstack setup` will rewrite `.claude/hooks.json`, `.claude/settings.json`, and `CLAUDE.md` with the latest versions.
+
+---
+
+### Cursor
+
+Cursor is a VS Code fork with native MCP support. ThinkStack integrates via MCP tools and the VS Code sidebar extension.
+
+**Step 1 — Install ThinkStack**
+```bash
+pip install thinkstack-cli
+```
+
+**Step 2 — Run setup**
+```bash
+cd /path/to/your/project
+thinkstack setup --target cursor
+```
+
+This creates `.cursor/mcp.json` wiring the ThinkStack MCP server into Cursor, initialises `.GCC/`, and writes `CLAUDE.md` with governance instructions.
+
+**Step 3 — Add Cursor rules**
+
+Create `.cursor/rules/thinkstack.mdc`:
+```
+---
+alwaysApply: true
+---
+Before any file edit, call thinkstack_commit with your reasoning and the concepts you are touching.
+Call thinkstack_context at the start of each task to load prior decisions.
+Call thinkstack_sensitivity_add when touching auth, payments, schema, secrets, or PII.
+```
+
+**Step 4 — Install the VS Code extension (optional but recommended)**
+
+In Cursor: `Cmd+Shift+P` → "Extensions: Install from VSIX" → select `extensions/vscode/thinkstack-0.1.0.vsix` from the ThinkStack source directory. This adds a live sidebar panel showing `.GCC/` state, Θ hot zones, and the event feed.
+
+**Step 5 — Verify**
+```bash
+thinkstack doctor
+```
+
+**What you get:** MCP tools, VS Code sidebar, optional HTTP proxy for passive capture of all LLM calls (`thinkstack proxy start`).
+
+> **Updating from an older version:** `pip install -U thinkstack-cli>=3.0.1 && thinkstack setup --target cursor` will regenerate `.cursor/mcp.json` and update `CLAUDE.md`.
+
+---
+
+### Google Antigravity
+
+Google Antigravity is a VS Code fork with a multi-agent orchestration layer. It reads `AGENTS.md` for persistent AI instructions and supports MCP servers.
+
+**Step 1 — Install ThinkStack**
+```bash
+pip install thinkstack-cli
+```
+
+**Step 2 — Run setup**
+```bash
+cd /path/to/your/project
+thinkstack setup --target antigravity
+```
+
+This initialises `.GCC/`, writes the ThinkStack MCP server config for Antigravity, and writes governance instructions into `AGENTS.md`.
+
+**Step 3 — Install the VS Code extension**
+
+In Antigravity: `Cmd+Shift+P` → "Extensions: Install from VSIX" → select `extensions/vscode/thinkstack-0.1.0.vsix`.
+
+**Step 4 — Verify**
+```bash
+thinkstack doctor
+```
+
+**What you get:** Full RACP integration. The multi-agent nature of Antigravity makes Θ accumulation especially valuable — multiple agents share the same reasoning state through `thinkstack_context`.
+
+> **Updating from an older version:** `pip install -U thinkstack-cli>=3.0.1 && thinkstack setup --target antigravity` will regenerate the MCP config and update `AGENTS.md`.
+
+---
+
+### OpenCode
+
+OpenCode connects to ThinkStack through the local stdio ↔ SSE bridge. The bridge talks to the cloud MCP server first, and if the cloud is unreachable or slow it automatically falls back to the local `thinkstack` CLI so your `.GCC/` audit trail is never lost.
+
+**Step 1 — Install ThinkStack**
+```bash
+pip install thinkstack-cli
+```
+
+**Step 2 — Create an API key and install the client config**
+
+Run from the project you want to govern:
+
+```bash
+thinkstack cloud key create --org myorg --repo myrepo
+# Copy the printed API key — it will not be shown again.
+
+export THINKSTACK_MCP_DOMAIN=thinkstack-mcp.your-domain.com
+thinkstack cloud client-config opencode --org myorg --repo myrepo --api-key <api-key>
+```
+
+This creates:
+- `opencode.json` — the OpenCode MCP server config (uses the local bridge)
+- `AGENTS.md` — ThinkStack governance instructions for the model
+
+**Step 3 — Verify**
+```bash
+thinkstack doctor
+```
+
+Open the project in OpenCode. The ThinkStack MCP tools will be listed, and the model will be instructed to call `thinkstack_context` at the start of each task and `thinkstack_commit` before every file edit.
+
+**What you get:** Cloud-hosted MCP server integration with automatic local fallback, automatic reasoning commits via `AGENTS.md` instructions, and a shared Θ state across sessions.
+
+> **Updating from an older version:** `pip install -U thinkstack-cli>=3.0.1 && thinkstack cloud client-config opencode --org <org> --repo <repo> --api-key <api-key>` will regenerate `opencode.json` with the latest bridge and fallback settings. **Restart OpenCode** after updating the config.
+
+---
+
+### VS Code (with GitHub Copilot)
+
+VS Code + Copilot has **partial integration only**. Copilot's API is closed — ThinkStack cannot intercept completions or inject RACP context. What works: the sidebar panel showing `.GCC/` state, and git-commit-level capture via the git hook.
+
+**Step 1 — Install ThinkStack**
+```bash
+pip install thinkstack-cli
+cd /path/to/your/project
+thinkstack init
+thinkstack hooks install
+```
+
+**Step 2 — Install the VS Code extension**
+
+`Cmd+Shift+P` → "Extensions: Install from VSIX" → select `extensions/vscode/thinkstack-0.1.0.vsix`.
+
+The sidebar shows your branch, last commit, Θ hot zones, and the live event feed from `.GCC/`.
+
+**Step 3 — Record reasoning manually**
+
+Since Copilot's internal reasoning cannot be captured automatically, record your own reasoning commits:
+```bash
+thinkstack commit -m "Chose JWT over sessions — stateless service, no session store needed"
+thinkstack sensitivity add --source you --concept auth --confidence 0.9 --disclosure PROTECTED -m "Token expiry logic is security-critical"
+```
+
+**What you get:** Sidebar panel (read-only), git-commit-level event capture, manual reasoning commits. Full capture requires switching to Claude Code, Cursor, Kiro, or Antigravity.
+
+> **Updating from an older version:** `pip install -U thinkstack-cli>=3.0.1 && thinkstack setup` will reinstall the git hook and update the governance instructions.
+
+---
+
+### AWS Kiro
+
+Kiro is Amazon's AI IDE. It uses steering documents and hooks — analogous to `CLAUDE.md` and `hooks.json`. Full ThinkStack integration is available via manual configuration.
+
+**Step 1 — Install ThinkStack**
+```bash
+pip install thinkstack-cli
+cd /path/to/your/project
+thinkstack init
+```
+
+**Step 2 — Add the MCP server**
+
+Create `.kiro/settings/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "thinkstack": {
+      "command": "/absolute/path/to/.venv/bin/thinkstack",
+      "args": ["mcp-server"],
+      "env": {}
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/.venv/bin/thinkstack` with the output of `which thinkstack`.
+
+**Step 3 — Add steering document**
+
+Create `.kiro/steering/thinkstack.md` with `inclusion: always`:
+```markdown
+---
+inclusion: always
+---
+
+# ThinkStack Governance
+
+Before any file edit, call `thinkstack_commit` with your reasoning and the concepts you are touching.
+Call `thinkstack_context` at the start of each task to load prior decisions.
+Call `thinkstack_sensitivity_add` when touching auth, payments, schema, secrets, or PII.
+```
+
+**Step 4 — Add agent hook**
+
+Create `.kiro/hooks/thinkstack-capture.md`:
+```markdown
+---
+name: thinkstack-capture
+trigger: after-file-write
+---
+Run: thinkstack hooks run post-tool-use
+```
+
+**Step 5 — Verify**
+```bash
+thinkstack doctor
+```
+
+**What you get:** Full RACP integration equivalent to Claude Code — MCP tools, steering-document governance, agent action hooks.
+
+> **Updating from an older version:** `pip install -U thinkstack-cli>=3.0.1`, then re-run the manual steps above and refresh your steering document with the latest `AGENTS.md` text.
+
+---
+
+### AWS Bedrock (Python SDK)
+
+ThinkStack integrates at the `boto3` call level with a one-line change.
+
+**Step 1 — Install**
+```bash
+pip install thinkstack-cli[wrapper] boto3
+cd /path/to/your/project
+thinkstack init
+```
+
+**Step 2 — Wrap your Bedrock client**
+```python
+# Before
+import boto3
+client = boto3.client("bedrock-runtime", region_name="us-east-1")
+
+# After — one import change, same API
+from thinkstack_core.wrapper.bedrock import ThinkStackBedrock
+client = ThinkStackBedrock(region_name="us-east-1")
+```
+
+All `invoke_model()` and `converse()` calls are identical. ThinkStack injects the RACP system prefix and captures responses automatically.
+
+**Step 3 — Verify**
+```bash
+thinkstack doctor
+```
+
+> **Updating from an older version:** `pip install -U thinkstack-cli[wrapper]>=3.0.1`.
+
+---
+
+### Azure AI Foundry (Python SDK)
+
+**Step 1 — Install**
+```bash
+pip install thinkstack-cli[wrapper] openai
+cd /path/to/your/project
+thinkstack init
+```
+
+**Step 2 — Wrap your Azure OpenAI client**
+```python
+# Before
+from openai import AzureOpenAI
+
+# After — one import change, all kwargs pass through unchanged
+from thinkstack_core.wrapper.openai import ThinkStackOpenAI as AzureOpenAI
+
+client = AzureOpenAI(
+    azure_endpoint="https://my-resource.openai.azure.com/",
+    api_version="2024-02-01",
+    api_key=os.environ["AZURE_OPENAI_KEY"],
+)
+# All chat.completions.create() calls are identical
+```
+
+**Step 3 — Verify**
+```bash
+thinkstack doctor
+```
+
+> **Updating from an older version:** `pip install -U thinkstack-cli[wrapper]>=3.0.1`.
+
+---
+
+### OpenAI Codex CLI
+
+**Step 1 — Install**
+```bash
+pip install thinkstack-cli
+cd /path/to/your/project
+thinkstack init
+```
+
+**Step 2 — Start the proxy**
+```bash
+thinkstack proxy start   # runs on localhost:8765
+```
+
+**Step 3 — Point Codex at the proxy**
+```bash
+export OPENAI_BASE_URL=http://localhost:8765/v1
+codex "Add error handling to the payment service"
+```
+
+All Codex calls are intercepted by the proxy, which injects the RACP prefix and captures responses into `.GCC/`.
+
+> **Updating from an older version:** `pip install -U thinkstack-cli>=3.0.1`.
+
+---
+
+### Ollama (local models)
+
+**Step 1 — Install Ollama and pull a model**
+```bash
+# Install Ollama from https://ollama.com
+ollama pull llama3.2
+```
+
+**Step 2 — Install ThinkStack**
+```bash
+pip install thinkstack-cli[wrapper]
+cd /path/to/your/project
+thinkstack init
+```
+
+**Step 3 — Wrap your Ollama client**
+```python
+from thinkstack_core.wrapper.ollama import ThinkStackOllama
+
+client = ThinkStackOllama(model="llama3.2")   # any model in `ollama list`
+response = client.chat(messages=[{"role": "user", "content": "Explain this function"}])
+```
+
+**Step 4 — Verify**
+```bash
+thinkstack doctor
+```
+
+No API key required. Fully local — RACP context and captures stay on-device.
+
+> **Updating from an older version:** `pip install -U thinkstack-cli[wrapper]>=3.0.1`.
+
+---
+
+### Cloud MCP server (team-wide shared governance)
+
+For teams that want a single shared reasoning backend across all projects and machines, ThinkStack provides a Cloudflare Worker MCP server. It stores `.GCC/` in Cloudflare R2 and exposes an HTTPS SSE endpoint that every IDE can connect to.
+
+**Deploy once, use everywhere:**
+
+```bash
+cd /path/to/ThinkStack/Implementation/deploy/cloudflare-worker
+cp .env.example .env
+# Fill in R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
+# Optionally set OPENAI_API_KEY for the DRPL openai embedding backend
+source .env
+./setup-mcp-server.sh
+```
+
+The script will:
+
+1. Ensure the R2 bucket exists.
+2. Deploy the Cloudflare Worker.
+3. Create an org/repo-scoped API key.
+4. Install the MCP client config for your IDE.
+5. Run a health check.
+
+For CI/CD, the same script runs non-interactively:
+
+```bash
+./setup-mcp-server.sh --non-interactive \
+  --org myorg \
+  --repo myproject \
+  --ide opencode \
+  --openai-key "$OPENAI_API_KEY"
+```
+
+The repository also includes `.github/workflows/deploy-cloudflare-worker.yml`, which runs on every `v*` tag and deploys the Worker (skipping key creation and client config).
+
+**Live URL:**
+
+```text
+https://thinkstack-mcp.YOUR_ACCOUNT.workers.dev
+```
+
+**Create a per-project API key:**
+
+```bash
+export THINKSTACK_STORAGE=r2
+export R2_ACCOUNT_ID=... R2_BUCKET=... R2_ACCESS_KEY_ID=... R2_SECRET_ACCESS_KEY=...
+thinkstack cloud key create --org myorg --repo myproject
+```
+
+**Wire any IDE in one command:**
+
+```bash
+export THINKSTACK_MCP_DOMAIN=thinkstack-mcp.YOUR_ACCOUNT.workers.dev
+thinkstack cloud client-config <ide> --org myorg --repo myproject --api-key <api-key>
+```
+
+Supported `<ide>` values: `opencode`, `claude`, `cursor`, `vscode`, `stdio`.
+
+**Full walkthrough:** `deploy/cloudflare-worker/README.md` has manual setup details and the full tool list. `IDE_SETUP.md` has step-by-step setup for OpenCode, Claude Code, Cursor, VS Code, Kiro, Antigravity, JetBrains, and generic MCP clients.
+
+> **Updating from an older version:** You do **not** need to redeploy the Cloudflare Worker for client-side changes. Just regenerate the IDE config on each machine after upgrading `thinkstack-cli`:
+> ```bash
+> > pip install -U thinkstack-cli>=3.0.1
+> > export THINKSTACK_MCP_DOMAIN=thinkstack-mcp.YOUR_ACCOUNT.workers.dev
+> > thinkstack cloud client-config <ide> --org <org> --repo <repo> --api-key <api-key>
+> > ```
+
+---
+
+### Platform comparison
+
+| Platform | Setup command | MCP tools | Auto-capture | Sidebar | Notes |
+|---|---|---|---|---|---|
+| Claude Code | `thinkstack setup` | ✅ | ✅ hooks | ✅ | Highest fidelity |
+| Cursor | `thinkstack setup --target cursor` | ✅ | ✅ proxy | ✅ | Near-full |
+| Google Antigravity | `thinkstack setup --target antigravity` | ✅ | ✅ | ✅ | Full |
+| AWS Kiro | Manual (5 steps) | ✅ | ✅ hooks | ✅ | Full — not yet automated |
+| VS Code + Copilot | `thinkstack init` + extension | ❌ | ❌ git only | ✅ | Partial — Copilot API closed |
+| AWS Bedrock | SDK wrapper | — | ✅ SDK | — | Python SDK only |
+| Azure AI Foundry | SDK wrapper or proxy | — | ✅ SDK | — | Python SDK only |
+| OpenAI Codex CLI | HTTP proxy | — | ✅ proxy | — | |
+| Ollama | SDK wrapper | — | ✅ SDK | — | Fully local |
+
+---
+
+## LLM integration
+
+### Option 1 — SDK wrapper (you own the code)
+
+```python
+# One-line change — same API, governance captured automatically
+from thinkstack_core.wrapper.anthropic import ThinkStackAnthropic
+client = ThinkStackAnthropic()   # replaces anthropic.Anthropic()
+
+# OpenAI
+from thinkstack_core.wrapper.openai import ThinkStackOpenAI
+client = ThinkStackOpenAI()
+
+# Local models via Ollama (no API key required)
+from thinkstack_core.wrapper.ollama import ThinkStackOllama
+client = ThinkStackOllama(model="llama3.2")   # any model in `ollama list`
+
+# Google Gemini
+from thinkstack_core.wrapper.gemini import ThinkStackGemini
+client = ThinkStackGemini(model_name="gemini-1.5-pro")
+
+# AWS Bedrock
+from thinkstack_core.wrapper.bedrock import ThinkStackBedrock
+client = ThinkStackBedrock(region_name="us-east-1")
+```
+
+See `OLLAMA_SETUP.md` for the full Ollama guide.
+
+### Option 2 — HTTP proxy (Cursor, JetBrains, closed-source IDEs)
+
+```bash
+thinkstack proxy install   # installs as macOS LaunchAgent or Linux systemd service
+thinkstack proxy start     # runs on localhost:8765
+```
+
+Configure your IDE to use `http://localhost:8765/anthropic` (or `/openai`, `/gemini`). The proxy injects RACP context and captures responses with zero latency penalty.
+
+### Option 3 — MCP server + hooks (Claude Code, Cursor, Kiro, Antigravity)
+
+```bash
+thinkstack setup   # one command: init + hooks + MCP config + CLAUDE.md + AGENTS.md
+```
+
+Claude Code / Cursor / Kiro / Antigravity then call `thinkstack_commit`, `thinkstack_sensitivity_add`, `thinkstack_context`, and `thinkstack_theta_read` as native MCP tools. See `IDE_SETUP.md` for per-IDE instructions.
+
+### Option 4 — OpenAI Codex CLI proxy
+
+```bash
+# Start the Codex-specific proxy on localhost:8766
+python -m thinkstack_core.codex start
+
+# Point Codex CLI at it
+export OPENAI_BASE_URL=http://localhost:8766/v1
+codex "Add error handling to the payment service"
+```
+
+See `CODEX_SETUP.md` for the full guide.
+
+### Option 5 — Org gateway (enterprise, multi-developer)
+
+```bash
+cd deploy/
+cp .env.example .env   # set ANTHROPIC_API_KEY and/or OPENAI_API_KEY
+docker compose up      # gateway on :8080, dashboard on :3000
+```
+
+Developers point their IDE proxy URL to the gateway instead of api.openai.com. The gateway handles central API key management, SSO attribution, governance policy enforcement, and metrics aggregation. See `deploy/README.md` for Helm and Docker Compose instructions.
+
+---
+
+## Cloud Deployment
+
+The ThinkStack cloud MCP server is a multi-tenant SSE endpoint that hosts the full governance toolkit in your own cloud account. Multiple agents and developers connect simultaneously; storage is backed by AWS S3, Azure Blob, or Cloudflare R2.
+
+**AWS ECS Fargate + S3:**
+```bash
+export AWS_REGION=us-east-1 AWS_ACCOUNT_ID=123456789012
+export THINKSTACK_ORG_ID=myorg AWS_S3_BUCKET=thinkstack-myorg
+export VPC_SUBNET_IDS=subnet-xxx VPC_SECURITY_GROUP_IDS=sg-xxx
+./deploy/aws/deploy.sh
+```
+
+**Azure Container Apps + Blob:**
+```bash
+export AZURE_RESOURCE_GROUP=thinkstack-rg AZURE_LOCATION=eastus
+export THINKSTACK_ORG_ID=myorg THINKSTACK_AZURE_CONTAINER=thinkstack
+export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=..."
+./deploy/azure/deploy.sh
+```
+
+See `deploy/README.md` for full instructions, API key setup, GitHub repository connection, and environment variable reference.
+
+---
+
+## Architecture
+
+```
+thinkstack_core/           Pure library — all business logic
+  gcc.py                 GCCRepository: .GCC/ layout, event log, commits, branches
+  sensitivity.py         Sensitivity events + SensitivityStore
+  theta.py               Coordination vector Θ + AggPhi
+  capability.py          OmegaCapability (A1), Lipschitz bound, PST runner
+  invariants.py          I1 (commit-backed), I3 (semantic grounding)
+  variance.py            f_max formula, rolling monitor, VARIANCE_ALERT
+  rep.py                 REP ledger — append-only local transport
+  sis.py                 SIS-TC corpus evaluation + quarantine
+  rdp.py                 RDP ε-budget tracking
+  disclosure.py          [PRIVATE] span suppression
+  prompt_artifact.py     RACP system prompt artifact store
+  deltaf.py              Δf estimation
+  parser/                XML block extractor, thinking tokens, inference
+  wrapper/               SDK drop-in wrappers (Anthropic, OpenAI, Gemini, Bedrock)
+  proxy/                 HTTP reverse proxy (localhost:8765)
+  mcp/                   MCP/JSON-RPC server
+  hooks/                 Claude Code hooks + git commit-msg hook
+  metrics/               MCS, DHS, ROI, calibration, citation registry
+  observability/         Structured reports + enterprise metrics webhook
+  alerts/                Slack, Jira, PagerDuty outbound alerting
+  rep_network/           Multi-node REP ledger sync
+  github/                GitHub App webhook + PR comment builder
+  dashboard_api.py       REST API for browser dashboard
+
+thinkstack_cli/
+  main.py                Thin argparse wrapper over thinkstack_core
+
+extensions/vscode/       VS Code extension (read-only sidebar; installs in Antigravity via .vsix)
+dashboard/               React browser dashboard (Developer/Lead/CISO views)
+tests/                   637 tests across all sprints (S0–S18)
+examples/                end-to-end scenario examples
+```
+
+---
+
+## On-disk layout (`.GCC/`)
+
+```
+.GCC/
+  VERSION                    # format version
+  events.log.jsonl           # append-only audit stream (hash chain)
+  main.md / log.md           # reasoning roadmap + chronological log
+  refs/HEAD                  # current branch
+  refs/branches/<name>       # branch tip commit ID
+  commits/<id>.json          # commit objects
+  sensitivities/events.jsonl # raw sensitivity events
+  theta.json                 # coordination vector Θ
+  capabilities/omega.json    # A1 capability state
+  variance/                  # calibration_report.json, live_state.json
+  rep/rep_ledger.jsonl        # REP transport ledger
+  rep/peers.json             # peer list for multi-node sync
+  sis/                       # SIS-TC corpus, reports, quarantine events
+  rdp/rdp_state.json         # RDP ε-budget
+  concepts/<name>.json       # I3 concept definitions
+  prompts/                   # RACP system prompt artifact
+  deltaf/                    # Δf report
+  calibration.json           # team-specific metric calibration
+  context_bundles/           # MECW-bounded context snapshots
+  NODE_STATE                 # node state machine
+```
+
+---
+
+## Key safety properties
+
+| Property | Mechanism |
+|----------|-----------|
+| Commit-backed decisions (I1) | Merge/unlock blocked unless branch tips exist in commits/ and events log |
+| Semantic grounding (I3) | Operations using concepts_used require matching definitions in concepts/ |
+| Capability gate (A1) | Textual mode requires valid OmegaCapability + passing PST |
+| Variance control (A2) | f_max=0 forces deterministic mode; A1 gate blocks textual_mode |
+| Privacy budget (RDP) | epsilon exhaustion flips read_only=true in rdp_state.json |
+| Proxy trust boundary | Proxy binds to 127.0.0.1 only; API keys pass through, never stored |
+
+---
+
+## Run the tests
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .[dev,proxy]
+pytest tests/         # 637 tests
+```
+
+---
+
+## Configuration reference
+
+| Env var | Purpose |
+|---------|---------|
+| `THINKSTACK_DISABLE=1` | Disable all injection and capture (wrapper/proxy become transparent) |
+| `THINKSTACK_SLACK_WEBHOOK_URL` | Slack alert delivery |
+| `THINKSTACK_JIRA_URL` / `_PROJECT_KEY` / `_API_TOKEN` / `_EMAIL` | Jira issue creation |
+| `THINKSTACK_PAGERDUTY_ROUTING_KEY` | PagerDuty event trigger |
+| `THINKSTACK_ALERT_MIN_SEVERITY` | Minimum severity to alert on (`info`/`warning`/`critical`) |
+| `THINKSTACK_METRICS_WEBHOOK_URL` | Enterprise metrics webhook endpoint |
+| `THINKSTACK_ORG_ID` | Org identifier in metrics payloads |
+| `THINKSTACK_METRICS_API_KEY` | Auth for metrics webhook |
+| `THINKSTACK_GITHUB_WEBHOOK_SECRET` | HMAC secret for GitHub App webhook |
+
+---
+
+## Documentation
+
+| File | Contents |
+|------|----------|
+| `DOCS.md` | Architecture deep-dive, Sprint 4–6 feature reference, conformance matrix |
+| `OBSERVABILITY.md` | Observability pillars, daily-recall pattern, shell audit script template |
+| `CONTRIBUTING.md` | Dev environment, test commands, sprint structure, PR checklist |
+| `THREAT_MODEL.md` | Trust model, hash chain integrity, proxy trust boundary, known limitations |
+| `DESIGN_THOUGHTS.md` | Design decisions Q1–Q14 with full citation validation |
+| `IDE_SETUP.md` | VS Code, Cursor, Kiro, and Antigravity setup instructions |
+| `ANTIGRAVITY_SETUP.md` | Google Antigravity step-by-step onboarding |
+| `CLAUDE_CODE_QUICKSTART.md` | Claude Code step-by-step onboarding |
+| `OLLAMA_SETUP.md` | Local model setup with Ollama (Llama, Mistral, Gemma, Phi, Qwen) |
+| `CODEX_SETUP.md` | OpenAI Codex CLI proxy setup |
+| `AGENTS.md` | Persistent AI instructions for Antigravity/Kiro |
+| `deploy/README.md` | Enterprise org gateway — Docker Compose and Helm deployment |
+| `thinkstack_core/metrics/README.md` | MCS/DHS/ROI formulas and calibration guide |
+| `thinkstack_core/proxy/README.md` | HTTP proxy deployment options |
+| `thinkstack_core/wrapper/README.md` | SDK wrapper quick-start for all providers |
+| `dashboard/README.md` | Browser dashboard setup and API reference |
+
+---
+
+## Metrics credibility
+
+ThinkStack is explicit about what every number is based on:
+
+- **15 min context switch** — Parnin & Rugaber (2011), *Software Quality Journal*. DOI: [10.1007/s11219-010-9104-9](https://doi.org/10.1007/s11219-010-9104-9). Measured for programming tasks only.
+- **Auditor rate** — BLS SOC 13-2011 (2023): $39–40/hr employed staff. External rates ($75–400/hr) not used as defaults.
+- **MCS/DHS weights** — Design choices. No external benchmark. Calibrate with your team's data.
+- **Developer hourly rate** — No default. You must set it: `thinkstack calibrate --set developer_hourly_rate=<value>`
+
+See `thinkstack_core/metrics/credibility.py` for the full citation registry.
+
+---
+
+## License
+
+Apache 2.0