thumbgate 1.3.0 → 1.4.1

package/README.md

@@ -1,213 +1,329 @@
 # ThumbGate
 
-Make your AI coding agent self-improving. ThumbGate turns thumbs-up and thumbs-down into a learned control plane for autonomous development: pre-action gates, a trained intervention policy, workflow governance, and isolated execution guidance for high-risk runs.
+**Thumbs up or thumbs down — and your AI coding agent never makes the same mistake twice.**
 
 [![CI](https://github.com/IgorGanapolsky/ThumbGate/actions/workflows/ci.yml/badge.svg)](https://github.com/IgorGanapolsky/ThumbGate/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/thumbgate)](https://www.npmjs.com/package/thumbgate)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Start Sprint](https://img.shields.io/badge/Workflow%20Hardening%20Sprint-Start%20Intake%20→-16a34a?style=for-the-badge)](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=badge_cta#workflow-sprint-intake)
 
-**[Workflow Hardening Sprint](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=top_cta#workflow-sprint-intake)** · **[Pro Page](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=pro_page)** · **[Live Dashboard](https://thumbgate-production.up.railway.app/dashboard?utm_source=github&utm_medium=readme&utm_campaign=top_cta)** · **[Setup Guide](https://thumbgate-production.up.railway.app/guide?utm_source=github&utm_medium=readme&utm_campaign=top_cta)**
+**[Workflow Hardening Sprint](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=top_cta#workflow-sprint-intake)** · **[Use in ChatGPT](adapters/chatgpt/INSTALL.md)** · **[Install Claude Desktop Extension](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-desktop.mcpb)** · **[Claude Plugin Guide](docs/CLAUDE_DESKTOP_EXTENSION.md)** · **[Install Codex Plugin](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-codex-plugin.zip)** · **[Live Dashboard](https://thumbgate-production.up.railway.app/dashboard?utm_source=github&utm_medium=readme&utm_campaign=top_cta)** · **[Pro Page](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=pro_page)**
 
-**Popular buyer questions:** **[How to stop repeated AI agent mistakes](https://thumbgate-production.up.railway.app/guides/stop-repeated-ai-agent-mistakes?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Cursor guardrails](https://thumbgate-production.up.railway.app/guides/cursor-agent-guardrails?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Codex CLI guardrails](https://thumbgate-production.up.railway.app/guides/codex-cli-guardrails?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Gemini CLI memory + enforcement](https://thumbgate-production.up.railway.app/guides/gemini-cli-feedback-memory?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)**
+**Popular buyer questions:** **[Stop repeated AI agent mistakes](https://thumbgate-production.up.railway.app/guides/stop-repeated-ai-agent-mistakes?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Cursor guardrails](https://thumbgate-production.up.railway.app/guides/cursor-agent-guardrails?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Codex CLI guardrails](https://thumbgate-production.up.railway.app/guides/codex-cli-guardrails?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Gemini CLI memory + enforcement](https://thumbgate-production.up.railway.app/guides/gemini-cli-feedback-memory?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)**
 
-### Get Started
+**Running Claude Desktop?** **[Download Claude bundle](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-desktop.mcpb)** · **[Install + submission guide](docs/CLAUDE_DESKTOP_EXTENSION.md)** · **[Review packet zip](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-plugin-review.zip)**
 
-**Best first paid motion for teams:** the **Workflow Hardening Sprint**.
+**Running Codex?** **[Download the standalone Codex plugin bundle](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-codex-plugin.zip)** · **[Codex install guide](plugins/codex-profile/INSTALL.md)**
 
-[![Start Workflow Hardening Sprint](https://img.shields.io/badge/>>%20Start%20Intake%20→%20Workflow%20Hardening%20Sprint-16a34a?style=for-the-badge)](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=get_started#workflow-sprint-intake)
+**Running ChatGPT?** Search GPT Store for `ThumbGate` by Igor Ganapolsky. Regular users reply with 👍/👎 or "thumbs up/down" on answers, save the lesson, prevent repeated bad answers, and reinforce the answers that worked. Developers can import the prepared **[GPT Actions OpenAPI spec](adapters/chatgpt/openapi.yaml)** with the **[ChatGPT install guide](adapters/chatgpt/INSTALL.md)**.
 
-One workflow. One owner. One proof review. That is the fastest path to a paid team engagement because it qualifies a real blocker before anyone tries to sell a full rollout.
+**Official directory pending review?** Claude Code users can install today with `/plugin marketplace add IgorGanapolsky/ThumbGate` then `/plugin install thumbgate@thumbgate-marketplace`.
 
-**Self-serve for individual operators:** [ThumbGate Pro](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=pro_page) is the paid lane for the personal local dashboard, DPO export, and review-ready evidence.
+---
 
-Free stays for individual developers. Pro is **$19/mo or $149/yr** for solo operators. Team pricing anchors at **$12/seat/mo with a 3-seat minimum**, but the public Team path remains intake-first through the sprint. [See pricing →](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=pricing_link#pricing)
+## What problem does this solve?
 
-**Paid path for individual operators:** [ThumbGate Pro](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=pro_page) is the buyer-ready page for the personal local dashboard, DPO export, and review-ready evidence. It makes the paid upgrade legible before checkout while the self-hosted path below stays optimized for open source evaluation.
+AI agents repeat mistakes. You fix the same problem in session after session — force-push to main, broken migrations, unauthorized file edits — because the agent has no memory of your feedback.
 
-**Open Source (Self-Hosted):**
-
-```bash
-npx thumbgate init
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    THE PROBLEM                              │
+│                                                             │
+│  Session 1: Agent breaks something. You fix it.             │
+│  Session 2: Agent breaks it again. You fix it again.        │
+│  Session 3: Same thing. Again.                              │
+│                                                             │
+│                    THE SOLUTION                             │
+│                                                             │
+│  Session 1: Agent breaks something. You 👎 it.              │
+│  Session 2: ⛔ Gate blocks the mistake before it happens.   │
+│  Session 3+: Never see it again.                            │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-## Enterprise Story
+ThumbGate is the **control plane** for AI coding agents — turning your feedback into **enforced rules**, not suggestions.
 
-ThumbGate is the control plane for AI coding agents:
+---
 
-- Feedback becomes enforcement, so repeated failures stop at the gate instead of reappearing in review.
-- Workflow Sentinel scores blast radius before execution, so risky PR, release, and publish flows are visible early.
-- High-risk local actions can be routed into Docker Sandboxes, while hosted team automations use a signed isolated sandbox lane.
-- Team rollout stays tied to [Verification Evidence](docs/VERIFICATION_EVIDENCE.md) instead of trust-me operator claims.
+## How It Works in 3 Steps
 
-## Release Confidence
+```
+  STEP 1              STEP 2                 STEP 3
+  ────────            ────────               ────────
 
-Enterprise buyers do not just need a safer runtime. They need legible publishes.
+  You react           ThumbGate learns       The gate holds
 
-- Release-relevant PRs must carry a `.changeset/*.md` entry, so every shipped package version has a customer-readable explanation before publish.
-- [SemVer Policy](docs/SEMVER_POLICY.md) and version-sync checks keep `package.json`, `CHANGELOG.md`, plugin manifests, and installer metadata aligned.
-- CI enforces changeset coverage, version sync, tests, coverage, proof lanes, and operational integrity before merge.
-- Final close-out requires verifying the exact `main` merge commit, with proof anchored in [Verification Evidence](docs/VERIFICATION_EVIDENCE.md).
+  👎 on a bad    ──►  Feedback becomes  ──►  Next time the
+  agent action        a saved lesson         agent tries the
+                      and a block rule       same thing:
+  👍 on a good   ──►  Good pattern gets      ⛔ BLOCKED
+  agent action        reinforced                 (or ✅ allowed)
+```
 
-See [Release Confidence](docs/RELEASE_CONFIDENCE.md) for the full trust chain.
+That's it. No manual rule-writing. No config files to maintain. Your reactions teach the agent what your team actually wants.
+
+---
 
 ## Before / After
 
 ```
-WITHOUT THUMBGATE                    WITH THUMBGATE
+WITHOUT THUMBGATE              │  WITH THUMBGATE
+───────────────────────────────┼───────────────────────────────
+Session 1:                     │  Session 1:
+  Agent force-pushes to main.  │    Agent force-pushes to main.
+  You correct it manually.     │    You 👎 it.
+                               │
+Session 2:                     │  Session 2:
+  Agent force-pushes again.    │    ⛔ Gate blocks force-push.
+  It learned nothing.          │    Agent uses safe push instead.
+                               │
+Session 3:                     │  Session 3+:
+  Same mistake. Again.         │    Permanently fixed.
+  And again.                   │
+```
 
-Session 1:                           Session 1:
-  Agent force-pushes to main.          Agent force-pushes to main.
-  You correct it.                      You 👎 it.
+---
 
-Session 2:                           Session 2:
-  Agent force-pushes again.            ⛔ Gate blocks force-push.
-  It learned nothing.                  Agent uses safe push instead.
+## The Feedback Loop
 
-Session 3:                           Session 3+:
-  Same mistake. Again.                 Permanently fixed.
+```
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+│ Capture  │───►│  Learn   │───►│ Remember │───►│   Rule   │───►│   Gate   │
+│          │    │          │    │          │    │          │    │          │
+│ 👍 / 👎  │    │ Feedback │    │ Stored   │    │ Auto-    │    │ Blocks   │
+│          │    │ becomes  │    │ lessons  │    │ generated│    │ bad      │
+│          │    │ a lesson │    │ & search │    │ from     │    │ actions  │
+│          │    │          │    │          │    │ feedback │    │ live     │
+└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
 ```
 
-## How It Works
+---
 
-```
-  YOU                    THUMBGATE                   YOUR AGENT
-   │                        │                            │
-   │  👎 "broke prod"       │                            │
-   ├───────────────────────►│                            │
-   │                        │  distill + validate        │
-   │                        │  ┌─────────────────┐       │
-   │                        │  │ lesson + rule    │       │
-   │                        │  │ created          │       │
-   │                        │  └─────────────────┘       │
-   │                        │                            │
-   │                        │  PreToolUse hook fires     │
-   │                        │◄───────────────────────────┤ tries same mistake
-   │                        │  ⛔ BLOCKED                │
-   │                        ├───────────────────────────►│ forced to try safe path
-   │                        │                            │
-   │  👍 "good fix"         │                            │
-   ├───────────────────────►│                            │
-   │                        │  reinforced ✅             │
-   │                        │                            │
-```
+## Get Started
 
-## The Loop
+**Best first paid motion for teams:** the **Workflow Hardening Sprint** — qualify one repeated failure before committing to a full rollout. **[Start intake →](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=team_rollout#workflow-sprint-intake)**
 
+**Best first technical motion:** install the CLI-first and let `init` wire hooks for the agent you already use.
+
+**Paid path for individual operators:** [ThumbGate Pro](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=pro_page) is the self-serve side lane for a personal dashboard and export-ready evidence.
+
+---
+
+## Quick Start
+
+```bash
+npx thumbgate init    # detects your agent and wires everything up
+npx thumbgate doctor  # health check
+npx thumbgate lessons # see what's been learned
+npx thumbgate dashboard # open local dashboard
 ```
-┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
-│ Capture  │────►│ Distill  │────►│ Remember │────►│   Rule   │────►│   Gate   │
-│ 👍 / 👎  │     │ history- │     │ SQLite + │     │ auto-gen │     │ PreTool  │
-│          │     │ aware    │     │ FTS5 DB  │     │ from     │     │ Use hook │
-│          │     │          │     │          │     │ failures │     │ enforces │
-└──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘
-```
 
-## Quick Start (Self-Hosted)
+Or wire MCP directly: `claude mcp add thumbgate -- npx --yes --package thumbgate thumbgate serve`
+
+Works with **Claude Code, Cursor, Codex, Gemini CLI, Amp, OpenCode**, and any MCP-compatible agent.
+
+---
 
+## Install for Your Agent
+
+### Claude Code
 ```bash
-npx thumbgate init                                    # auto-detect agent + wire hooks
-npx thumbgate doctor                                  # health check
-npx thumbgate lessons                                 # inspect learned lessons
-npx thumbgate dashboard                               # local dashboard
+npx thumbgate init --agent claude-code
 ```
+Wires hooks automatically. Works immediately.
 
-Or wire MCP directly: `claude mcp add thumbgate -- npx -y thumbgate serve`
+### Cursor
+```bash
+npx thumbgate init --agent cursor
+```
+Installs as a Cursor extension with 4 skills: capture feedback, manage rules, search lessons, recall context.
 
-Works with **Claude Code, Cursor, Codex, Gemini, Amp, OpenCode**, and any MCP-compatible agent.
+### Codex
+```bash
+npx thumbgate init --agent codex
+```
+Bridges to Codex CLI with 6 skills including adversarial review and second-pass analysis.
 
-> **Need shared enforcement, auditability, and rollout proof for a team workflow?** [Start with the Workflow Hardening Sprint →](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=quickstart_cta#workflow-sprint-intake)
->
-> **Need a personal dashboard and DPO export for yourself?** [See ThumbGate Pro →](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=quickstart_cta_pro)
+### Gemini CLI
+```bash
+npx thumbgate init --agent gemini
+```
 
-## Built-in Gates
+### Amp
+```bash
+npx thumbgate init --agent amp
+```
 
+### Any MCP-Compatible Agent
+```bash
+npx thumbgate serve
 ```
-┌─────────────────────────────────────────────────────────┐
-│                   ENFORCEMENT LAYER                      │
-│                                                          │
-│  ⛔ force-push          → blocks git push --force        │
-│  ⛔ protected-branch    → blocks direct push to main     │
-│  ⛔ unresolved-threads  → blocks push with open reviews  │
-│  ⛔ package-lock-reset  → blocks destructive lock edits  │
-│  ⛔ env-file-edit       → blocks .env secret exposure    │
-│                                                          │
-│  + custom gates in config/gates/custom.json              │
-└─────────────────────────────────────────────────────────┘
+Starts the MCP server on stdio. Connect from any MCP-compatible client.
+
+### Claude Desktop
+Add to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "thumbgate": {
+      "command": "npx",
+      "args": ["--yes", "--package", "thumbgate", "thumbgate", "serve"]
+    }
+  }
+}
 ```
+Or [download the packaged extension bundle](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-desktop.mcpb) and install directly.
+
+---
+
+## Use Cases
+
+- **Stop force-push to main** — A gate blocks `git push --force` on protected branches before it runs
+- **Prevent repeated migration failures** — Each mistake becomes a searchable lesson that fires before the next attempt
+- **Block unauthorized file edits** — Control which files agents can touch with path-based rules
+- **Memory across sessions** — The agent remembers your feedback from yesterday without any manual rule-writing
+- **Shared team safety** — One developer's thumbs-down protects the whole team from the same mistake
+- **Auto-improving without feedback** — Self-improvement mode evaluates outcomes and generates rules automatically
+
+---
 
 ## Feedback Sessions
 
+Give the agent more context when a thumbs-down isn't enough:
+
 ```
 👎 thumbs down
   └─► open_feedback_session
-        └─► "you lied about deployment" (append_feedback_context)
-        └─► "tests were actually failing" (append_feedback_context)
+        └─► "you lied about deployment"    (append_feedback_context)
+        └─► "tests were actually failing"  (append_feedback_context)
         └─► finalize_feedback_session
               └─► lesson inferred from full conversation
 ```
 
-History-aware distillation turns vague negative signals into concrete lessons. In the current Claude auto-capture path, ThumbGate can reuse up to 8 prior recorded conversation entries plus the failed tool call, then keep a linked 60-second follow-up session open for later clarification.
+ThumbGate uses up to 8 prior conversation entries to turn vague, history-aware negative signals into specific, actionable lessons. A 60-second follow-up window stays open for additional context via `open_feedback_session` → `append_feedback_context` → `finalize_feedback_session`.
 
 Free and self-hosted users can invoke `search_lessons` directly through MCP, and via the CLI with `npx thumbgate lessons`.
 
-## Pricing
+---
+
+## Built-in Gates
 
 ```
-┌──────────────┬──────────────────────┬──────────────────────────────┐
-│    FREE      │ PRO $19/mo or $149/yr│   TEAM $12/seat/mo (min 3)   │
-├──────────────┼──────────────────────┼──────────────────────────────┤
-│ Unlimited    │ Unlimited feedback │ Shared hosted lesson DB      │
-│ feedback     │ captures + search  │ Org dashboard                │
-│ captures     │ DPO export         │ Gate template library         │
-│ 3 captures   │ Personal dashboard │ Isolated execution guidance   │
-│ 5 lesson     │                    │                              │
-│ searches/day │                    │                              │
-└──────────────┴────────────────────┴──────────────────────────────┘
+┌─────────────────────────────────────────────────────────┐
+│                   ENFORCEMENT LAYER                     │
+│                                                         │
+│  ⛔ force-push          → blocks git push --force       │
+│  ⛔ protected-branch    → blocks direct push to main    │
+│  ⛔ unresolved-threads  → blocks push with open reviews │
+│  ⛔ package-lock-reset  → blocks destructive lock edits │
+│  ⛔ env-file-edit       → blocks .env secret exposure   │
+│                                                         │
+│  + custom gates in config/gates/custom.json             │
+└─────────────────────────────────────────────────────────┘
 ```
 
-Free includes 3 daily feedback captures, 5 daily lesson searches, unlimited recall, and gating. History-aware distillation turns vague feedback into concrete lessons, and feedback sessions (`open_feedback_session` → `append_feedback_context` → `finalize_feedback_session`) keep later clarification linked to one record. The current Claude auto-capture path uses up to 8 prior recorded entries for vague thumbs-down signals; the follow-up session stays open for 60 seconds and resets when more context is appended.
+---
 
-It does not update model weights in frontier LLMs. ThumbGate improves runtime behavior by training a local sidecar intervention policy from feedback, gate audits, and diagnostics, then using that policy to strengthen recall, verification, and enforcement decisions on future runs.
+## Pricing
 
-The fastest commercial path is not a generic self-serve subscription pitch. It is the Workflow Hardening Sprint: qualify one repeated failure in one valuable workflow, prove the control plane on that surface, then expand into Team seats when shared enforcement matters.
+```
+┌──────────────────┬──────────────────────────────┬──────────────────────┐
+│   FREE           │  TEAM  $99/seat/mo (min 3)   │  PRO  $19/mo · $149/yr│
+├──────────────────┼──────────────────────────────┼──────────────────────┤
+│ Local CLI        │ Workflow Hardening Sprint     │ Personal dashboard   │
+│ Enforced gates   │ Shared hosted lesson DB       │ Export feedback data │
+│ 3 captures/day   │ Org-wide dashboard            │ Review-ready exports │
+│ 5 searches/day   │ Approval + audit proof        │                      │
+│ Unlimited recall │ Isolated execution guidance   │                      │
+└──────────────────┴──────────────────────────────┴──────────────────────┘
+```
+
+**[Start Workflow Hardening Sprint](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=top_cta#workflow-sprint-intake)** · **[Live Dashboard](https://thumbgate-production.up.railway.app/dashboard?utm_source=github&utm_medium=readme&utm_campaign=top_cta)** · **[See Pro](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=pro_page)**
 
-**[Start Workflow Hardening Sprint](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=team_rollout#workflow-sprint-intake)** | **[Get Pro](https://thumbgate-production.up.railway.app/checkout/pro?utm_source=github&utm_medium=readme&utm_campaign=thumbgate)** | **[Live Dashboard](https://thumbgate-production.up.railway.app/dashboard?utm_source=github&utm_medium=readme&utm_campaign=thumbgate)**
+**Where to start:**
+- **Teams:** Begin with the Workflow Hardening Sprint — qualify one real repeated failure before committing to a full rollout
+- **Solo operators:** ThumbGate Pro adds a personal dashboard and export-ready evidence
+- **Individuals & open source:** Free CLI tier, self-hosted
+
+---
 
 ## Tech Stack
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│  STORAGE          │  INTELLIGENCE     │  ENFORCEMENT     │
-│                   │                   │                  │
-│  SQLite + FTS5    │  MemAlign dual    │  PreToolUse      │
-│  LanceDB vectors  │    recall         │    hook engine   │
-│  JSONL logs       │  Thompson Sampling│  Gates config    │
-│  ContextFS        │                   │  Hook wiring     │
-├───────────────────┼───────────────────┼──────────────────┤
-│  INTERFACES       │  BILLING          │  EXECUTION       │
-│                   │                   │                  │
-│  MCP stdio        │  Stripe           │  Railway         │
-│  HTTP API         │                   │  Cloudflare      │
-│  CLI              │                   │    Workers       │
-│  Node.js >=18     │                   │  Docker          │
-│                   │                   │    Sandboxes     │
-└───────────────────┴───────────────────┴──────────────────┘
+┌──────────────────────┬──────────────────────┬──────────────────────┐
+│   STORAGE            │   INTELLIGENCE        │   ENFORCEMENT        │
+│                      │                       │                      │
+│ SQLite + FTS5        │ MemAlign dual recall  │ PreToolUse hook      │
+│ LanceDB vectors      │ Thompson Sampling     │ engine               │
+│ JSONL logs           │ (adaptive lesson      │ Gates config         │
+│ File-based context   │  selection)           │ Hook wiring          │
+│                      │                       │                      │
+│                      │                       │                      │
+├──────────────────────┼──────────────────────┼──────────────────────┤
+│   INTERFACES         │   BILLING             │   EXECUTION          │
+│                      │                       │                      │
+│ MCP stdio            │ Stripe                │ Railway              │
+│ HTTP API             │                       │ Cloudflare Workers   │
+│ CLI                  │                       │ Docker Sandboxes     │
+│ Node.js >=18         │                       │                      │
+└──────────────────────┴──────────────────────┴──────────────────────┘
 ```
 
+---
+
+## FAQ
+
+**Is ThumbGate a model fine-tuning tool?**
+No. ThumbGate does not update model weights in frontier LLMs. It captures your feedback, stores lessons, injects context at runtime, and blocks bad actions before they execute.
+
+**How is this different from CLAUDE.md or .cursorrules?**
+Those are suggestions the agent can ignore. ThumbGate gates are enforced — they physically block the action before it runs. They also auto-generate from feedback instead of requiring manual writing.
+
+**Does it work with my agent?**
+Yes. It's MCP-compatible and works with Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, Amp, OpenCode, and any agent that supports MCP or pre-action hooks.
+
+**What's self-improvement mode?**
+ThumbGate can watch for failure signals (test failures, reverted edits, error patterns) and auto-generate prevention rules — no thumbs-down required. Your agent gets smarter every session.
+
+**Is it free?**
+Free tier: **3 daily feedback captures**, **5 daily lesson searches**, unlimited recall, enforced gates. History-aware distillation turns vague feedback into specific lessons. Pro is $19/mo or $149/yr for a personal dashboard and exports. Team rollout starts at $99/seat/mo (3-seat minimum) with shared hosted lesson DB, org dashboard, approval + audit proof, and isolated execution guidance.
+
+---
+
+## Enterprise Story
+
+ThumbGate is the control plane for AI coding agents:
+
+- Feedback becomes enforcement — repeated failures stop at the gate instead of reappearing in review.
+- **Workflow Sentinel** scores blast radius before execution, so risky PR, release, and publish flows are visible early.
+- High-risk local actions route into **Docker Sandboxes**; hosted team automations use a signed isolated sandbox lane.
+- Team rollout stays tied to [Verification Evidence](docs/VERIFICATION_EVIDENCE.md) instead of trust-me operator claims.
+
+## Release Confidence
+
+- Every PR must carry a **Changeset** entry — each shipped version has a customer-readable explanation before publish.
+- Version-sync checks keep `package.json`, `CHANGELOG.md`, plugin manifests, and installer metadata aligned.
+- Final close-out requires verifying the exact `main` merge commit, with proof anchored in [Verification Evidence](docs/VERIFICATION_EVIDENCE.md).
+
+See [Release Confidence](docs/RELEASE_CONFIDENCE.md) for the full trust chain.
+
+---
+
 ## Docs
 
 - [Commercial Truth](docs/COMMERCIAL_TRUTH.md) — pricing, claims, what we don't say
-- [Changeset Strategy](docs/CHANGESET_STRATEGY.md) — how release notes, version bumps, and customer-facing change records are enforced
-- [First Dollar Playbook](docs/FIRST_DOLLAR_PLAYBOOK.md) — the operator loop for turning one painful workflow into the next booked pilot
-- [Release Confidence](docs/RELEASE_CONFIDENCE.md) — how Changesets, SemVer, sync checks, proof lanes, and exact-merge verification make publishes inspectable
+- [Changeset Strategy](docs/CHANGESET_STRATEGY.md) — how release notes and version bumps are enforced
+- [First Dollar Playbook](docs/FIRST_DOLLAR_PLAYBOOK.md) — turning one painful workflow into the next booked pilot
+- [Release Confidence](docs/RELEASE_CONFIDENCE.md) — how changesets, version checks, and proof lanes make publishes inspectable
 - [SemVer Policy](docs/SEMVER_POLICY.md) — stable vs prerelease channel rules
 - [Verification Evidence](docs/VERIFICATION_EVIDENCE.md) — proof artifacts
 - [WORKFLOW.md](WORKFLOW.md) — agent-run contract (scope, hard stops, proof commands)
-- [ready-for-agent issue template](.github/ISSUE_TEMPLATE/ready-for-agent.yml) — intake for agent tasks
+- [Ready-for-agent issue template](.github/ISSUE_TEMPLATE/ready-for-agent.yml) — intake for agent tasks
 
 Pro overlay: [`thumbgate-pro`](https://github.com/IgorGanapolsky/thumbgate-pro) — separate repo/package inheriting from this base.
 
+---
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

package/adapters/README.md

@@ -3,7 +3,7 @@
 - `chatgpt/openapi.yaml`: import into GPT Actions.
 - `gemini/function-declarations.json`: Gemini function-calling definitions.
 - `mcp/server-stdio.js`: underlying local MCP stdio server implementation.
-- `claude/.mcp.json`: example Claude Code MCP config using `npx --yes --package thumbgate@1.3.0 thumbgate serve`.
+- `claude/.mcp.json`: example Claude Code MCP config using `npx --yes --package thumbgate@1.4.0 thumbgate serve`.
 - `codex/config.toml`: example Codex MCP profile section using the same version-pinned portable launcher.
 - `amp/skills/thumbgate-feedback/SKILL.md`: Amp skill template.
 - `opencode/opencode.json`: portable OpenCode MCP profile using the same version-pinned portable launcher.

package/adapters/chatgpt/INSTALL.md

@@ -1,11 +1,64 @@
 # ChatGPT GPT Actions: ThumbGate Install
 
-Import the OpenAPI spec into a Custom GPT in under 5 minutes. No coding required.
+Use the published ThumbGate GPT from GPT Store when it is visible for your account, or import the OpenAPI spec into a Custom GPT in under 5 minutes. Regular users use it by replying with 👍/👎 or "thumbs up/down" on ChatGPT answers so ThumbGate remembers lessons, prevents repeated bad answers, and reinforces the answers that worked.
+
+## GPT Store path
+
+1. Open ChatGPT.
+2. Open **Explore GPTs**.
+3. Search for `ThumbGate`.
+4. Choose the GPT by **Igor Ganapolsky** in the **Programming** category.
+
+Direct store URL status: published by the operator on April 13, 2026, but the public `chatgpt.com/g/...` URL has not been captured in this repo yet. Do not invent a URL; add it here once the share link is available.
+
+## 30-second regular-user flow
+
+1. Ask the ThumbGate GPT any normal question.
+2. If the answer helped, reply with `👍` plus one sentence about what worked.
+3. If the answer missed, reply with `👎` plus one sentence about what to change.
+4. Ask `What do you remember about how I like answers?` to verify the saved lessons.
+
+The user should never need to know what MCP, OpenAPI, Actions, DPO, or prevention rules mean. The GPT should explain the loop as: "Reply 👍 or 👎. I remember the lesson for next time."
+
+## Regular-user prompts
+
+Use these as GPT conversation starters so regular users know how to teach ThumbGate:
+
+1. `👎 this answer was too vague. Next time give me exact steps.`
+2. `👍 this format worked. Remember to answer with short numbered steps.`
+3. `Thumbs down: you assumed I know technical terms. Next time explain it for a beginner first.`
+4. `Remember this lesson: I prefer direct answers with examples before theory.`
+5. `Search my ThumbGate lessons before answering this.`
+
+Use typed chat replies. ChatGPT's native feedback buttons may send feedback to OpenAI, but they should not be described as the ThumbGate capture path unless OpenAI exposes them to GPT Actions.
+
+## Pre-action gate flow
+
+Use this when the user asks whether an AI agent should run a proposed action, command, file edit, deployment, merge, or publish step:
+
+1. The GPT calls `evaluateDecision` (`POST /v1/decisions/evaluate`) before answering.
+2. If the response has `decisionControl.executionMode: "blocked"`, the GPT says the action is blocked and explains the returned reason.
+3. If the response has `decisionControl.executionMode: "checkpoint_required"`, the GPT asks for explicit confirmation before proceeding.
+4. If the response has `decisionControl.executionMode: "auto_execute"`, the GPT can say the action is allowed and summarize why.
+
+Plain thumbs-up/down feedback is the memory loop. The decision endpoint is the gate loop. Do not claim hard blocking unless the decision endpoint, a saved lesson, or a prevention rule was actually applied.
+
+## Best first GPT message
+
+Use this as the first response for regular users:
+
+```text
+Ask me anything. After my answer, reply 👍 if it helped or 👎 plus one sentence if it missed. I will remember the lesson, avoid repeating bad answer patterns, and reuse the formats you like.
+```
 
 ## Prerequisites
 
 - A ChatGPT Plus or Team account (Custom GPTs require a paid plan)
-- ThumbGate API running at a public HTTPS URL (see [Deployment docs](../../docs/deployment.md))
+- ThumbGate API running at `https://thumbgate-production.up.railway.app`
+- Privacy policy URL: `https://thumbgate-production.up.railway.app/privacy`
+- Owner-managed `THUMBGATE_API_KEY` for one-time GPT Builder Actions auth
+
+Regular GPT users should not need an API key, JSON payload, OpenAPI knowledge, or developer setup. They should only see the thumbs-up/down memory loop.
 
 ## Step 1 — Open GPT Builder
 
@@ -19,7 +72,7 @@ Import the OpenAPI spec into a Custom GPT in under 5 minutes. No coding required
 2. Click **Create new action**
 3. Click **Import from URL** — paste your hosted spec URL:
    ```
-   https://<your-railway-domain>/openapi.yaml
+   https://thumbgate-production.up.railway.app/openapi.yaml
    ```
    Or click **Upload file** and select:
    ```
@@ -34,13 +87,15 @@ In the Actions panel:
 2. **Auth type**: Bearer
 3. **API Key**: paste your `THUMBGATE_API_KEY` value
 
+This is an owner setup field. Do not ask regular GPT users to provide an API key.
+
 ## Step 4 — Update the Server URL
 
 In the imported spec, confirm the `servers.url` points to your deployed API:
 
 ```yaml
 servers:
-  - url: https://<your-railway-domain>
+  - url: https://thumbgate-production.up.railway.app
 ```
 
 If you uploaded the file, edit the server URL in the GPT Actions editor.