@idevelopers/agentgate 0.1.0 → 0.1.1

package/.claude-plugin/marketplace.json

@@ -8,14 +8,14 @@
   "plugins": [
     {
       "name": "agentgate",
-      "description": "Validation gates + token-budget kill switch for autonomous coding agents",
+      "description": "Validation gates and token-budget guardrails for AI coding agents",
       "author": {
         "name": "iDevelopers"
       },
       "category": "development",
       "source": "./",
-      "version": "0.1.0",
-      "homepage": "https://www.npmjs.com/package/@idevelopers/agentgate"
+      "version": "0.1.1",
+      "homepage": "https://github.com/manish-1988/agentgate-installer#readme"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,11 +1,11 @@
 {
   "name": "agentgate",
-  "version": "0.1.0",
-  "description": "Validation gates + token-budget kill switch for autonomous coding agents",
+  "version": "0.1.1",
+  "description": "Validation gates and token-budget guardrails for AI coding agents",
   "author": {
     "name": "iDevelopers",
     "url": "https://github.com/manish-1988"
   },
-  "repository": "https://www.npmjs.com/package/@idevelopers/agentgate",
+  "repository": "https://github.com/manish-1988/agentgate-installer",
   "license": "MIT"
 }

package/README.md

@@ -1,8 +1,11 @@
 # AgentGate
 
-Stop autonomous coding agents from burning tokens and marking broken code as done.
+Stop AI coding agents from burning tokens and marking broken code as done.
 
-AgentGate is an MCP server plus Claude Code and Codex plugin packaging. It wraps agent work in explicit slices, runs real validation gates, blocks done status while gates fail, and adds Pro guardrails for multi-slice plans, token budgets, advanced gates, and analytics.
+AgentGate is a local MCP server plus Claude Code and Codex plugin packaging. It
+wraps agent work in explicit slices, runs real validation gates, blocks done
+status while gates fail, and adds Pro guardrails for multi-slice plans, token
+budgets, advanced gates, bounded retries, and analytics.
 
 ## Install
 
@@ -29,8 +32,38 @@ node dist/index.js
 
 Polar handles paid licenses; npm distributes the runtime package. The public installer repository contains only plugin metadata and points Claude/Codex at `npx -y @idevelopers/agentgate`.
 
+## First Useful Run
+
+AgentGate is most useful when an agent is about to claim a task is finished.
+
+```text
+1. Add agentgate.config.json to the repo.
+2. Define one focused slice with agentgate_define_slice.
+3. Run agentgate_run_gate before accepting "done".
+4. Keep the task open until every returned gate is green.
+```
+
+The free path proves the value locally: one slice, real command output, no
+source upload, and no payment required.
+
+## When Free Becomes Pro
+
+Upgrade when the same workflow needs to run unattended across a full plan:
+
+- multi-slice dependency order
+- bounded retries after gate failures
+- typecheck, build, custom, and Pro-only gates
+- token-budget stop signals
+- validation analytics for team or client handoff
+
+Free tool responses include an `upgrade` block only at relevant moments, such as
+after a passing free gate or when a repo already has Pro-ready slices, budgets,
+or advanced gates configured.
+
 ## Free, Pro, Team
 
+Free is the local AgentGate runtime distributed through public npm. The source repository remains private; the public installer repository only contains plugin metadata that points to `npx -y @idevelopers/agentgate`.
+
 | Capability | Free | Pro | Team |
 | --- | --- | --- | --- |
 | Single-slice run + basic gates | Yes | Yes | Yes |
@@ -40,8 +73,8 @@ Polar handles paid licenses; npm distributes the runtime package. The public ins
 | Run analytics export | No | Yes | Yes |
 | Shared policies and seats | No | No | Yes |
 
-Pro is intended for `$19/mo` or `$190/yr`. Team is intended for `$49/mo` with seats.
-Buy Pro or Team through the live Polar checkout:
+Pro is priced at INR 1,599/month or INR 15,999/year. Team is priced at INR
+4,199/month with seats. Buy Pro or Team through the live Polar checkout:
 
 ```text
 https://buy.polar.sh/polar_cl_VxlhG8lCO6IUcLcveJ51YOXYXMHWdUNorKr0U1bhyqm
@@ -88,6 +121,15 @@ export AGENTGATE_CONFIG=agentgate.config.example.json
 - `agentgate_budget_status`: report token usage, remaining budget, estimated cost, and state.
 - `agentgate_activate_license`: store and verify a Polar license key.
 
+## Public Support
+
+The source repository is private. Public installation metadata, support, and
+issues live at:
+
+```text
+https://github.com/manish-1988/agentgate-installer
+```
+
 ## License Activation
 
 AgentGate ships with the public Polar organization id for production license validation:
@@ -118,9 +160,20 @@ Soft-launch validation was completed on 2026-06-11:
 - Dogfood runs passed against AgentGate, Shipnote, PocketScan, and the mushroom tracker syntax check.
 - The live Polar finance page showed account approval complete, payout account setup complete, and identity verification complete.
 - A production free smoke checkout issued a live Pro license key and AgentGate activated it successfully.
+- A live paid Pro Monthly purchase was validated end-to-end through public npm, then immediately canceled/refunded; the Polar benefit grant was revoked and the refunded license no longer validated.
 
 Current distribution model: private source repository, public npm package, public installer marketplace, and Polar license monetization.
 
+## Production Runbook
+
+For the full operator handoff and reusable blueprint for future Polar + npm paid developer tools, see:
+
+```text
+docs/PRODUCTION_REPLICATION_PLAYBOOK.md
+```
+
+That guide records the private-source/public-npm/public-installer pattern, Polar setup, npm publishing, sandbox and live payment validation, refund/cancel cleanup, and the reusable Codex/Claude Code prompt for building similar apps.
+
 ## Security
 
 AgentGate runs locally and does not send repo contents to an AgentGate server. It does spawn the commands listed in `agentgate.config.json`, using `child_process.spawn` with `shell:false`. Treat the config like a CI file: review it before running, and only run trusted gate commands.

package/codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentgate",
-  "version": "0.1.0",
-  "description": "Validation gates + token-budget kill switch for autonomous coding agents",
+  "version": "0.1.1",
+  "description": "Validation gates and token-budget guardrails for AI coding agents",
   "author": "iDevelopers",
   "license": "MIT",
   "mcpServers": {

package/dist/index.js

@@ -5,7 +5,7 @@ import { registerTools } from "./server.js";
 async function main() {
     const server = new McpServer({
         name: "agentgate",
-        version: "0.1.0",
+        version: "0.1.1",
     });
     registerTools(server);
     const transport = new StdioServerTransport();

package/dist/license/gate.js

@@ -1,6 +1,6 @@
 import { AGENTGATE_CHECKOUT_URL } from "./constants.js";
 export function requirePro(feature, tier) {
     if (tier === "free") {
-        throw new Error(`Pro license required: ${feature}. Buy a license at ${AGENTGATE_CHECKOUT_URL}, then activate it with agentgate_activate_license.`);
+        throw new Error(`AgentGate Pro required for ${feature}. Pro unlocks multi-slice plan execution, typecheck/build/custom gates, token-budget stops, and analytics export. Buy a license at ${AGENTGATE_CHECKOUT_URL}, then activate it with agentgate_activate_license.`);
     }
 }

package/dist/tools/activate_license.js

@@ -17,6 +17,9 @@ export function registerActivateLicenseTool(server) {
             tier: verification.tier,
             validUntil: verification.validUntil,
             checkoutUrl: verification.tier === "free" ? AGENTGATE_CHECKOUT_URL : undefined,
+            nextStep: verification.tier === "free"
+                ? "This key did not unlock Pro or Team. Recheck the key, then buy or open the Polar checkout if needed."
+                : "License active. Run agentgate_run_plan to validate a full multi-slice agent handoff.",
         });
     });
 }

package/dist/tools/budget_status.js

@@ -1,31 +1,38 @@
 import { loadConfig } from "../config/loader.js";
+import { PolarLicenseValidator } from "../license/validator.js";
 import { estimateCostUsd } from "../util/cost.js";
 import { jsonToolResult } from "./response.js";
 import { activeTokenLedger } from "./runtime.js";
+import { agentGateUpgradePrompt } from "./upgrade.js";
 export function registerBudgetStatusTool(server) {
     server.registerTool("agentgate_budget_status", {
         title: "AgentGate Budget Status",
         description: "Report token usage, estimated cost, and budget state.",
     }, async () => {
         const config = await loadConfig(process.cwd());
+        const license = await new PolarLicenseValidator().verify();
         const tokensUsed = activeTokenLedger.used();
         if (!config.budget) {
             return jsonToolResult({
+                tier: license.tier,
                 tokensUsed,
                 maxTokens: null,
                 remaining: null,
                 costUsd: 0,
                 model: null,
                 state: "ok",
+                upgrade: agentGateUpgradePrompt("Add a budget block to show agents their token ceiling before they start drifting.", license.tier),
             });
         }
         return jsonToolResult({
+            tier: license.tier,
             tokensUsed,
             maxTokens: config.budget.maxTokens,
             remaining: activeTokenLedger.remaining(config.budget.maxTokens),
             costUsd: estimateCostUsd(tokensUsed, config.budget.model),
             model: config.budget.model,
             state: activeTokenLedger.check(config.budget),
+            upgrade: agentGateUpgradePrompt(`Budget tracking is configured for ${config.budget.maxTokens.toLocaleString()} tokens.`, license.tier),
         });
     });
 }

package/dist/tools/run_gate.js

@@ -5,6 +5,7 @@ import { Orchestrator } from "../orchestrator/orchestrator.js";
 import { loadRuntimeConfig } from "./config.js";
 import { jsonToolResult } from "./response.js";
 import { activeRunId, activeTokenLedger } from "./runtime.js";
+import { agentGateUpgradePrompt, freePlanSignals } from "./upgrade.js";
 const runGateInputSchema = {
     sliceId: z.string().min(1),
 };
@@ -18,9 +19,17 @@ export function registerRunGateTool(server) {
         const license = await new PolarLicenseValidator().verify();
         const orchestrator = new Orchestrator(config, new GateRunner(), activeTokenLedger, license.tier, activeRunId);
         const result = await orchestrator.runSlice(sliceId);
+        const signals = freePlanSignals(config);
         return jsonToolResult({
+            tier: license.tier,
             passed: result.passed,
             gateResults: result.gateResults,
+            nextStep: result.passed
+                ? "This slice passed. Keep the free path for one-off checks, or use Pro when you want AgentGate to run the whole plan without losing the thread."
+                : "Fix the failed gate output, rerun this slice, and keep done status blocked until the gate is green.",
+            upgrade: agentGateUpgradePrompt(signals.length > 0
+                ? `This repo already has ${signals.join(", ")} ready for Pro orchestration.`
+                : "This free slice passed; Pro turns repeated slice checks into one managed plan run.", license.tier),
         });
     });
 }

package/dist/tools/upgrade.js

@@ -0,0 +1,35 @@
+import { AGENTGATE_CHECKOUT_URL } from "../license/constants.js";
+export function agentGateUpgradePrompt(trigger, tier) {
+    if (tier !== "free") {
+        return undefined;
+    }
+    return {
+        product: "AgentGate Pro",
+        trigger,
+        checkoutUrl: AGENTGATE_CHECKOUT_URL,
+        activationTool: "agentgate_activate_license",
+        value: "Turn a single passing gate into a complete agent handoff: dependency-ordered slices, bounded retries, advanced gates, token-budget stops, and analytics export.",
+        unlocks: [
+            "Run the full multi-slice plan with agentgate_run_plan.",
+            "Use typecheck, build, custom, and explicitly Pro-only gates.",
+            "Stop runaway agent sessions with token-budget guardrails.",
+            "Export validation analytics for client or team handoff.",
+        ],
+    };
+}
+export function freePlanSignals(config) {
+    const signals = [];
+    if (config.slices.length > 1) {
+        signals.push(`${config.slices.length} configured slices`);
+    }
+    if (config.budget) {
+        signals.push(`token budget of ${config.budget.maxTokens.toLocaleString()} tokens`);
+    }
+    if (config.gates.some((gate) => gate.proOnly === true ||
+        gate.type === "typecheck" ||
+        gate.type === "build" ||
+        gate.type === "custom")) {
+        signals.push("advanced validation gates");
+    }
+    return signals;
+}

package/docs/CONVERSION_LAUNCH_KIT.md

@@ -0,0 +1,143 @@
+# AgentGate Conversion Launch Kit
+
+Use this as the public launch and directory-submission source for AgentGate.
+
+## Landing Page Copy
+
+Headline:
+
+```text
+AgentGate
+```
+
+Subhead:
+
+```text
+Validation gates and token-budget guardrails for AI coding agents that want to
+mark broken work as done.
+```
+
+Hero CTA:
+
+```text
+Install free: claude mcp add agentgate -- npx -y @idevelopers/agentgate
+Upgrade: https://buy.polar.sh/polar_cl_VxlhG8lCO6IUcLcveJ51YOXYXMHWdUNorKr0U1bhyqm
+```
+
+Value proof:
+
+```text
+AgentGate wraps agent work in explicit slices, runs real tests and build checks,
+and blocks "done" until gates pass. Free users can validate one slice locally.
+Pro turns the same workflow into a managed multi-slice plan with bounded retries,
+advanced gates, token budgets, and analytics export.
+```
+
+## Demo Script
+
+Use this for screenshots, GIFs, launch videos, and directory descriptions.
+
+```text
+1. Install AgentGate from npm.
+2. Add agentgate.config.json with a test gate and one slice.
+3. Ask the agent to implement a small change.
+4. Run agentgate_run_gate for the slice.
+5. Show a failed gate blocking done status.
+6. Fix the code.
+7. Run agentgate_run_gate again and show a passing slice.
+8. Show the upgrade block explaining that Pro can run the entire multi-slice
+   plan with retries, advanced gates, budgets, and analytics.
+```
+
+Screenshot checklist:
+
+```text
+- npm package page showing install command and checkout link
+- first failing gate output
+- second passing gate output
+- free response upgrade block
+- Polar checkout page with Pro Monthly and Pro Annual
+- license activation success with tier=pro
+```
+
+## Directory Submission
+
+Title:
+
+```text
+AgentGate
+```
+
+Tagline:
+
+```text
+Stop AI coding agents from claiming done before validation passes.
+```
+
+Short description:
+
+```text
+AgentGate is a local MCP server for Codex, Claude Code, and agentic coding
+workflows. It splits work into explicit slices, runs validation gates, tracks
+token budgets, and blocks completion until tests, typecheck, build, or custom
+checks pass.
+```
+
+Category:
+
+```text
+Developer tools, MCP, AI coding, CI, agent guardrails
+```
+
+Pricing:
+
+```text
+Free local single-slice validation. Pro unlocks multi-slice plans, bounded
+retries, advanced gates, token-budget guardrails, and analytics.
+```
+
+## Launch Posts
+
+Short post:
+
+```text
+Launched AgentGate for AI coding agents.
+
+It is a local MCP runtime that makes agents prove work is done: define a slice,
+run gates, block completion until validation passes.
+
+Free: one-slice validation.
+Pro: multi-slice plans, retries, advanced gates, token budgets, analytics.
+
+npm: @idevelopers/agentgate
+```
+
+Founder/dev post:
+
+```text
+I kept seeing coding agents mark work complete after editing files, while tests
+or build checks were still broken.
+
+AgentGate is my answer: a local MCP server that wraps agent work in slices and
+requires real validation before "done".
+
+The free version handles one focused slice. Pro is for longer agent handoffs:
+multi-slice ordering, bounded retries, typecheck/build/custom gates, token
+budgets, and analytics export.
+
+It runs locally, installs from npm, and uses Polar license keys for paid plans.
+```
+
+## Conversion Rule
+
+Do not hard-sell on first install. Show Pro only after value is visible:
+
+```text
+- after a free gate passes
+- after a failed gate prevents a bad done status
+- when config already contains multiple slices
+- when config contains typecheck, build, custom, or Pro-only gates
+- when a token budget is configured
+```
+
+The product should feel like a helpful guardrail first and a paid upgrade second.

package/docs/PRODUCTION_REPLICATION_PLAYBOOK.md

@@ -0,0 +1,659 @@
+# AgentGate Production Replication Playbook
+
+This is the operator handoff for AgentGate and the reusable blueprint for building
+the next 4-5 similar paid developer tools with Codex or Claude Code.
+
+It documents the path we used to move AgentGate from idea to production:
+private source repo, public npm runtime, public installer metadata, Polar
+checkout, live license validation, paid smoke test, refund, and post-launch
+cleanup. Use it as the canonical runbook when researching and shipping the next
+small paid MCP, Claude Code, or Codex app.
+
+Do not paste license keys, npm tokens, card details, OTPs, or private API keys
+into this document. Record only sanitized results and stable public values.
+
+## 1. Final Production State
+
+AgentGate is live as a paid local developer tool.
+
+Current production shape:
+
+- Product: AgentGate, a local MCP server for validation gates and token-budget
+  guardrails around autonomous coding agents.
+- Source repository: private GitHub repo, `manish-1988/agentgate`.
+- Public installer repository: `manish-1988/agentgate-installer`.
+- Public npm package: `@idevelopers/agentgate@0.1.1`.
+- Runtime install path: `npx -y @idevelopers/agentgate`.
+- Plugin install path: public installer repo with Claude Code and Codex metadata.
+- Payment provider: Polar live checkout.
+- Checkout URL: `https://buy.polar.sh/polar_cl_VxlhG8lCO6IUcLcveJ51YOXYXMHWdUNorKr0U1bhyqm`.
+- License model: Polar license keys, validated locally by the npm runtime.
+- Free tier: local runtime with single-slice/basic gates.
+- Pro tier: Polar key unlocks multi-slice plans, token budgets, advanced gates,
+  and analytics.
+- Team tier: future seat-based license key tier.
+
+Production validation completed on 2026-06-11:
+
+- Public npm install worked from a clean environment.
+- MCP server exposed all five public tools.
+- Live Polar checkout created a Pro Monthly paid order.
+- The issued live license key activated as Pro.
+- `agentgate_run_plan` passed the production validation slices.
+- Free installs kept free-core access and blocked Pro features with the live
+  checkout URL.
+- The live test subscription was canceled immediately.
+- The live test order was refunded.
+- The Polar benefit grant was revoked after refund.
+- Direct Polar license validation then returned that the key was no longer
+  active.
+
+Conversion polish completed on 2026-08-29:
+
+- npm package metadata now includes homepage, public installer repository,
+  support/issues URL, funding URL, richer keywords, and packaged docs.
+- Free tool responses include contextual upgrade blocks after useful validation
+  moments instead of hard-selling at install time.
+- Pro-required errors explain the concrete paid value before showing the Polar
+  checkout URL.
+- Public installer copy now clearly distinguishes free local validation from Pro
+  multi-slice orchestration.
+- `docs/CONVERSION_LAUNCH_KIT.md` contains landing copy, demo script, screenshot
+  checklist, directory-submission fields, and launch posts.
+
+## 2. Pattern To Reuse For Future Apps
+
+Use this product architecture for small paid developer tools that run locally:
+
+1. Keep source private.
+2. Publish a minimal public npm runtime.
+3. Publish a public installer repo that contains only plugin metadata, skills,
+   commands, and install instructions.
+4. Use Polar as Merchant of Record for self-serve card payments.
+5. Use Polar license keys for Pro/Team feature gating.
+6. Validate with sandbox first, then one real live purchase.
+7. Refund the live smoke purchase after proving activation and product behavior.
+8. Keep launch docs honest: "public npm runtime", not "open source", unless the
+   source repo is actually public.
+
+This pattern works best for:
+
+- MCP servers.
+- Claude Code plugins.
+- Codex plugins.
+- Local CLI tools.
+- Developer workflow guards.
+- Small automation utilities where users should not send code to your server.
+
+Avoid this pattern when the paid value depends on hosted state, collaborative
+dashboards, or server-side AI compute. Those products need a web app and a
+different billing/enforcement model.
+
+## 3. Repository Layout
+
+Use two repos.
+
+Private source repo:
+
+```text
+apps/<app-name>/
+  package.json
+  src/
+  test/
+  README.md
+  CONTEXT.md
+  agentgate.config.example.json
+  .mcp.json
+  .claude-plugin/
+  codex-plugin/
+  skills/
+  commands/
+  docs/
+```
+
+Public installer repo:
+
+```text
+apps/<app-name>-installer/
+  README.md
+  .mcp.json
+  .claude-plugin/
+  codex-plugin/
+  skills/
+  commands/
+```
+
+Rules:
+
+- Private repo contains source, tests, and production operator docs.
+- Public installer repo contains no proprietary source.
+- Public installer repo points the agent at the public npm package.
+- npm package contains built runtime files, README, manifests, skills, and
+  commands required for install.
+
+## 4. Product And Pricing Setup
+
+For each new app, define these values before coding:
+
+```text
+APP_NAME=AgentGate
+APP_SLUG=agentgate
+NPM_SCOPE=@idevelopers
+NPM_PACKAGE=@idevelopers/agentgate
+BIN_NAME=agentgate
+PRIVATE_REPO=manish-1988/agentgate
+PUBLIC_INSTALLER_REPO=manish-1988/agentgate-installer
+POLAR_ORGANIZATION_ID=<public organization id>
+POLAR_CHECKOUT_URL=<live checkout URL>
+FREE_PROMISE=<what works without payment>
+PRO_PROMISE=<what payment unlocks>
+TEAM_PROMISE=<what seats/policies unlock>
+```
+
+AgentGate pricing used for launch:
+
+- Free: local npm runtime, single-slice/basic gates.
+- Pro Monthly: monthly paid plan.
+- Pro Annual: annual paid plan.
+- Team: future team/seat plan.
+
+The original idea docs suggested USD pricing. The live Polar product used INR
+pricing for the Indian account during production validation. For future apps,
+choose the checkout currency deliberately before launch and make README,
+checkout, and launch copy match.
+
+## 5. Build Implementation Checklist
+
+For a new app, Codex or Claude Code should implement the product in slices.
+
+Minimum technical slices:
+
+1. Package skeleton.
+2. Config schema and loader.
+3. MCP server entrypoint.
+4. Free core tools.
+5. Pro-only tools.
+6. Polar license validator.
+7. Local cache and offline grace.
+8. Plugin manifests.
+9. Skills and slash commands.
+10. README and security notes.
+11. Tests.
+12. Production validation scripts or documented commands.
+
+For AgentGate, the shipped MCP tools are:
+
+```text
+agentgate_define_slice
+agentgate_run_gate
+agentgate_run_plan
+agentgate_budget_status
+agentgate_activate_license
+```
+
+For future apps, keep tool names stable and product-prefixed:
+
+```text
+<appslug>_<verb>_<noun>
+```
+
+Examples:
+
+```text
+pocketscan_scan_file
+pocketscan_export_report
+shipnote_generate_release_note
+shipnote_publish_digest
+```
+
+## 6. Polar Setup Runbook
+
+Do this in Polar live and Polar sandbox.
+
+1. Create or select organization.
+2. Complete finance/account verification.
+3. Confirm payout account is active.
+4. Create the product.
+5. Add recurring prices.
+6. Add License Key benefit.
+7. Set activation limits:
+   - Pro individual: 1 activation.
+   - Team: seat count or activation limit matching seats.
+8. If Polar metadata is available in the product/benefit UI, set:
+   - Pro: `tier=pro`.
+   - Team: `tier=team`.
+9. Copy the public organization id.
+10. Copy the live checkout URL.
+11. Add checkout URL to README, package docs, and Pro-required error message.
+12. Create sandbox equivalent for payment testing.
+
+Notes learned from AgentGate:
+
+- The Polar organization id is not secret when used for customer portal license
+  validation.
+- Never publish Polar server tokens in a local npm package.
+- One-seat Pro keys hit activation limits after first machine activation. This
+  is expected.
+- Cache the activation id locally so the same machine can keep validating
+  without consuming another activation.
+- Refund/cancel behavior can revoke the benefit even if the refund table shows a
+  separate "revoke benefits" field. Always verify the license after refund.
+
+AgentGate production organization id shipped in code:
+
+```text
+534c0711-1ded-497c-aa46-d1a7dfa46d6e
+```
+
+## 7. npm Publishing Runbook
+
+Prepare package:
+
+```sh
+npm install
+npm run build
+npx vitest run
+npm pack --dry-run
+```
+
+Publish:
+
+```sh
+npm publish --access public
+```
+
+Post-publish checks:
+
+```sh
+npm view @idevelopers/agentgate name version bin dist.tarball
+npm pack @idevelopers/agentgate --dry-run
+```
+
+Clean MCP smoke from outside the source repo:
+
+```sh
+tmp_home=$(mktemp -d /tmp/agentgate-home.XXXXXX)
+tmp_cfg=$(mktemp /tmp/empty-npmrc.XXXXXX)
+
+HOME="$tmp_home" NPM_CONFIG_USERCONFIG="$tmp_cfg" \
+  AGENTGATE_CONFIG=/absolute/path/to/agentgate.config.example.json \
+  node ./scripts-or-oneoff/mcp-smoke.mjs
+```
+
+Important source-repo testing note:
+
+- `npx -y @idevelopers/agentgate` works from a clean consumer environment.
+- When testing inside the source repo for the same package, npm/npx can resolve
+  differently and create false negatives.
+- For paid purchase validation from the source repo, use an explicit clean
+  install:
+
+```sh
+tmp_install=$(mktemp -d /tmp/agentgate-public-install.XXXXXX)
+npm install --prefix "$tmp_install" @idevelopers/agentgate@0.1.1
+"$tmp_install/node_modules/.bin/agentgate"
+```
+
+Security cleanup after publish:
+
+- Revoke temporary npm tokens.
+- Clear local npm auth if a temporary publish token was used.
+- Do not commit `.npmrc` with tokens.
+- Confirm package tarball does not include private source files unless intended.
+
+## 8. GitHub Runbook
+
+Private source repo:
+
+1. Initialize git in `apps/<app-name>`.
+2. Commit implementation slices.
+3. Push to GitHub.
+4. Make the repo private if source should remain proprietary.
+5. Keep issues/discussions strategy deliberate. If source is private, support
+   may happen through installer repo, email, or future help desk.
+
+Public installer repo:
+
+1. Create `apps/<app-name>-installer`.
+2. Copy only public install metadata.
+3. Point `.mcp.json` and plugin manifests at public npm runtime.
+4. Write README with install and checkout instructions.
+5. Push public repo.
+6. Add GitHub metadata:
+   - description
+   - homepage
+   - topics
+
+AgentGate correction we made:
+
+- The source repo was accidentally public initially.
+- We corrected the model to private source plus public installer repo.
+- This does not harm npm distribution because users install from npm/Polar, not
+  by cloning the source repo.
+
+## 9. Plugin Packaging Runbook
+
+Ship three install surfaces:
+
+Direct MCP install:
+
+```text
+claude mcp add agentgate -- npx -y @idevelopers/agentgate
+```
+
+Claude Code plugin marketplace install:
+
+```text
+/plugin marketplace add https://github.com/manish-1988/agentgate-installer
+/plugin install agentgate@agentgate-marketplace
+```
+
+Codex plugin metadata:
+
+```text
+codex-plugin/plugin.json
+skills/<workflow>/SKILL.md
+commands/*.md
+```
+
+For future apps, ensure:
+
+- `.mcp.json` points to the public npm package, not local source.
+- Plugin marketplace `source` points at the public installer files.
+- The plugin README explains that source may remain private.
+- Skills teach the agent how to use the tool safely.
+- Slash commands are small wrappers around MCP tool calls.
+
+## 10. License Validation Design
+
+AgentGate validator behavior:
+
+1. `agentgate_activate_license` stores the key in `~/.agentgate/license.json`.
+2. Validator activates the key through Polar if no activation id exists.
+3. Validator caches activation id, tier, and validation timestamp.
+4. Validator calls Polar customer portal validation with:
+   - license key
+   - organization id
+   - activation id
+5. If Polar says granted, AgentGate treats the tier as Pro/Team.
+6. If network fails, AgentGate allows a 72-hour offline grace for cached paid
+   licenses.
+7. If invalid, revoked, expired, or activation limit exceeded, AgentGate falls
+   back to Free.
+
+Future apps should keep the same user experience:
+
+- Paid tool call without license should fail clearly.
+- Error message should include checkout URL.
+- Activation should not require users to edit config files.
+- License cache should live under the app home directory.
+- Network failure should not break paid users immediately.
+- Refunded/revoked keys should stop unlocking Pro.
+
+Never log full license keys.
+
+## 11. Required Validation Matrix
+
+Before launch, run this full matrix.
+
+Local source validation:
+
+```sh
+npm run build
+npx vitest run
+```
+
+Public package validation:
+
+```sh
+npm view <package> name version bin dist.tarball
+npm pack <package> --dry-run
+```
+
+Clean direct MCP validation:
+
+- Start package from a clean temp HOME.
+- Connect with MCP client.
+- Confirm tool list.
+- Run one free tool.
+- Confirm Pro tool blocks without license.
+
+Sandbox payment validation:
+
+- Create sandbox product and checkout.
+- Buy with sandbox card.
+- Capture sandbox license key locally.
+- Activate license.
+- Run paid behavior.
+- Refund sandbox order.
+- Confirm license state after refund if possible.
+
+Live payment validation:
+
+- Buy the real product with a real card.
+- Do not expose card details in docs or chat.
+- Capture issued license key locally only.
+- Activate license.
+- Run paid behavior from public npm package.
+- Run free-vs-Pro contrast test.
+- Cancel subscription.
+- Refund order.
+- Confirm benefit revoked.
+- Confirm direct Polar validation no longer accepts the refunded key.
+
+AgentGate live paid validation results on 2026-06-11:
+
+```text
+Public package: @idevelopers/agentgate@0.1.1
+Live product: AgentGate Pro Monthly
+Subscription after test: canceled
+Order after test: refunded
+Benefit after refund: revoked
+License after refund: no longer active
+Paid plan result before refund: passed
+Free contrast result: free gate passed, Pro gate and Pro plan blocked
+```
+
+## 12. Paid Product Smoke Test Procedure
+
+Use this exact sequence for future apps.
+
+1. Open live checkout.
+2. Purchase the lowest paid recurring tier with a real test buyer identity.
+3. Wait for checkout confirmation.
+4. Copy license key into a local temp file with restricted permissions.
+5. Do not paste the full key into chat or docs.
+6. Install the public npm package into a temp directory.
+7. Run the MCP server from that temp install.
+8. Activate license.
+9. Confirm paid tier in tool output.
+10. Run the main paid tool or paid workflow.
+11. Run a fresh unlicensed temp HOME check.
+12. Confirm unlicensed Pro path blocks.
+13. Return to Polar dashboard.
+14. Cancel the subscription immediately.
+15. Refund the order.
+16. Confirm order status is refunded.
+17. Confirm subscription status is canceled.
+18. Confirm benefit is revoked.
+19. Confirm license no longer validates.
+
+Example sanitized local key handling:
+
+```sh
+umask 077
+pbpaste > /tmp/<app>-paid-license-key
+chmod 600 /tmp/<app>-paid-license-key
+```
+
+Delete the temp key file after validation if you no longer need it:
+
+```sh
+rm -f /tmp/<app>-paid-license-key
+```
+
+## 13. Documentation Update Checklist
+
+Update private source docs:
+
+- `README.md`: install, tiers, checkout, license activation, launch status.
+- `CONTEXT.md`: product truth and monetization model.
+- `docs/PRODUCTION_REPLICATION_PLAYBOOK.md`: production learnings and reusable
+  runbook.
+
+Update public installer docs:
+
+- `README.md`: plugin install, direct MCP install, checkout link.
+- `.mcp.json`: public npm runtime command.
+- `.claude-plugin/marketplace.json`: public npm/homepage links.
+- `codex-plugin/plugin.json`: public npm runtime command.
+
+Update launch assets:
+
+- Avoid "open source" unless source is public.
+- Use "free local runtime" or "public npm runtime".
+- State clearly that source remains private if that is the model.
+- Include checkout URL only after live Polar is approved.
+- Include security note: local tool executes user-configured commands.
+
+## 14. Reusable Codex / Claude Code Handoff Prompt
+
+Use this prompt to start the next app after research is complete.
+
+```text
+You are the dedicated build thread for <APP_NAME>.
+
+Goal:
+Build a production-ready local developer tool distributed as:
+- private source repo
+- public npm runtime package
+- public installer metadata repo
+- Polar-paid Pro/Team license key model
+
+Use the AgentGate production pattern from:
+docs/PRODUCTION_REPLICATION_PLAYBOOK.md
+
+Hard constraints:
+- Keep source private unless explicitly told otherwise.
+- Public repo contains installer metadata only.
+- Runtime installs from public npm.
+- Polar handles paid checkout and license keys.
+- Do not publish server secrets.
+- Do not include npm tokens, Polar tokens, card details, OTPs, or license keys in
+  docs or commits.
+- Free tier must be useful without payment.
+- Pro tier must unlock paid value through license validation.
+- Paid features must fail with a clear checkout URL when unlicensed.
+- Include sandbox and live purchase validation before marketing.
+
+Inputs:
+- APP_NAME=<...>
+- APP_SLUG=<...>
+- NPM_PACKAGE=<...>
+- BIN_NAME=<...>
+- PRIVATE_REPO=<...>
+- PUBLIC_INSTALLER_REPO=<...>
+- POLAR_ORGANIZATION_ID=<...>
+- POLAR_CHECKOUT_URL=<...>
+- FREE_CAPABILITIES=<...>
+- PRO_CAPABILITIES=<...>
+- TEAM_CAPABILITIES=<...>
+
+Build slices:
+1. Skeleton, package, TypeScript config, tests.
+2. Core local functionality.
+3. MCP tools.
+4. Free-vs-Pro gating.
+5. Polar license validator with cache and offline grace.
+6. Plugin manifests, skills, commands.
+7. README and installer repo docs.
+8. Validation scripts and production checklist.
+
+Validation required:
+- npm run build
+- test suite
+- npm pack --dry-run
+- clean public npm install
+- MCP tool list
+- unlicensed free behavior
+- unlicensed Pro block
+- sandbox purchase and activation
+- live purchase and activation
+- live refund/cancel and revoked-license check
+
+Final report must include:
+- what shipped
+- exact repos/packages
+- validation evidence
+- remaining risks
+- launch checklist
+```
+
+## 15. Marketing And Monetization Follow-Through
+
+Technical production is not the same as revenue.
+
+After the paid flow is validated:
+
+1. Keep npm and installer repo live.
+2. Submit to relevant plugin directories.
+3. Post the launch kit.
+4. Send direct outreach to likely users.
+5. Offer Pro keys for feedback.
+6. Track install friction.
+7. Track activation friction.
+8. Improve docs before adding features.
+
+For each future app, write the launch promise before coding:
+
+```text
+This tool saves <buyer> from <pain> by doing <specific local workflow>.
+Free gives <useful narrow outcome>.
+Pro gives <paid outcome worth money>.
+Team gives <collaboration/admin outcome>.
+```
+
+If the paid outcome is vague, do not build yet. Research more.
+
+## 16. Risk Register
+
+Known risks from AgentGate:
+
+- External providers can have edge cases: npm, Polar, banks/cards, user machines,
+  and plugin marketplaces.
+- One-seat activation means a buyer who changes machine may need a reset flow.
+- Refund and benefit revocation should always be verified directly.
+- Public npm package README must not overpromise support or source access.
+- Private source plus public package is valid, but the wording must be precise.
+- Local tools that spawn commands must keep a strong security warning.
+- Marketing copy must avoid fake revenue, fake usage, or inflated claims.
+
+Mitigations:
+
+- Keep one clean install smoke script per app.
+- Keep one license validation smoke script per app.
+- Keep public docs short and exact.
+- Keep private operator docs detailed.
+- Test sandbox and live payments before marketing.
+- Revoke temporary tokens immediately after publishing.
+
+## 17. Definition Of Production-Ready
+
+A future app is production-ready only when all are true:
+
+- Private source repo is clean and pushed.
+- Public installer repo is clean and pushed.
+- npm package is published and installable from a clean machine.
+- MCP tool list loads from the public package.
+- Free flow works without license.
+- Paid flow blocks without license.
+- Sandbox paid license unlocks paid flow.
+- Live paid license unlocks paid flow.
+- Live test purchase is canceled/refunded after validation.
+- Refunded live license no longer unlocks paid flow.
+- README and installer README match reality.
+- Launch kit does not claim open source unless source is public.
+- Temporary npm tokens and local auth are cleaned up.
+
+If any item is missing, the app can be dogfooded, but it is not ready for
+serious marketing.

package/package.json

@@ -1,8 +1,21 @@
 {
   "name": "@idevelopers/agentgate",
-  "version": "0.1.0",
-  "description": "Validation gates and token-budget guardrails for autonomous coding agents.",
+  "version": "0.1.1",
+  "description": "Validation gates, plan checks, and token-budget guardrails for AI coding agents.",
   "type": "module",
+  "author": "iDevelopers <tech@idevelopers.in>",
+  "homepage": "https://github.com/manish-1988/agentgate-installer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manish-1988/agentgate-installer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/manish-1988/agentgate-installer/issues"
+  },
+  "funding": {
+    "type": "polar",
+    "url": "https://buy.polar.sh/polar_cl_VxlhG8lCO6IUcLcveJ51YOXYXMHWdUNorKr0U1bhyqm"
+  },
   "bin": {
     "agentgate": "dist/index.js"
   },
@@ -14,6 +27,7 @@
   "files": [
     "dist",
     "README.md",
+    "docs",
     "agentgate.config.example.json",
     ".mcp.json",
     ".claude-plugin",
@@ -23,10 +37,16 @@
   ],
   "keywords": [
     "mcp",
+    "mcp-server",
     "codex",
     "claude-code",
     "agents",
-    "validation"
+    "ai-agents",
+    "agentic-coding",
+    "validation",
+    "guardrails",
+    "token-budget",
+    "ci"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -40,7 +60,7 @@
   "devDependencies": {
     "@types/node": "^20.19.1",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=20"

package/skills/agentgate-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agentgate-workflow
 description: Use when implementing code under AgentGate validation gates, slice scopes, token budgets, or Pro multi-slice plans.
-version: 0.1.0
+version: 0.1.1
 ---
 
 # AgentGate Workflow