gabbe-kit 1.1.2 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  ## License
2
2
 
3
- This documentation is licensed under the [Creative Commons Attribution 4.0 International License (CC BY SA 4.0)](https://creativecommons.org/licenses/by-sa/4.0/).
3
+ This documentation is licensed under the [Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0)](https://creativecommons.org/licenses/by-sa/4.0/).
4
4
 
5
5
  You are free to:
6
6
 
package/README.md CHANGED
@@ -34,7 +34,11 @@ It contains:
34
34
 
35
35
  ---
36
36
 
37
- *Full documentation: [README_FULL.md](docs/README_FULL.md) · Full quick guide: [QUICK_GUIDE.md](docs/QUICK_GUIDE.md) · Quick commands: [QUICK_COMMANDS.md](docs/QUICK_COMMANDS.md) · CLI reference: [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) · MCP servers: [MCP_CONFIGURATIONS.md](docs/MCP_CONFIGURATIONS.md) · Platform Controls: [PLATFORM_CONTROLS.md](docs/PLATFORM_CONTROLS.md) · Verification Guide: [VERIFICATION_GUIDE.md](docs/VERIFICATION_GUIDE.md) · Roadmap: [ROADMAP.md](docs/ROADMAP.md)*
37
+ *Website: [andreibesleaga.github.io/GABBE](https://andreibesleaga.github.io/GABBE/)*
38
+
39
+ ---
40
+
41
+ *Full documentation: [README_FULL.md](docs/README_FULL.md) · Full quick guide: [QUICK_GUIDE.md](docs/QUICK_GUIDE.md) · Quick commands: [QUICK_COMMANDS.md](docs/QUICK_COMMANDS.md) · CLI reference: [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) · MCP servers: [MCP_CONFIGURATIONS.md](docs/MCP_CONFIGURATIONS.md) · Platform Controls: [PLATFORM_CONTROLS.md](docs/PLATFORM_CONTROLS.md) · Verification Guide: [VERIFICATION_GUIDE.md](docs/VERIFICATION_GUIDE.md) · Architecture: [ARCHITECTURE.md](docs/ARCHITECTURE.md) · Roadmap: [ROADMAP.md](docs/ROADMAP.md)*
38
42
 
39
43
  ---
40
44
 
@@ -57,7 +61,7 @@ It contains:
57
61
  | **Shell bootstrap** | `curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh \| sh` | picks the best available installer |
58
62
  | **Git checkout** | `git clone https://github.com/andreibesleaga/GABBE && cd GABBE && python3 scripts/init.py` | the interactive wizard |
59
63
 
60
- > On npm the package is **`gabbe-kit`** (npm refuses the unscoped `gabbe`); on PyPI it is **`gabbe`**; the npm package is additionally mirrored on GitHub Packages as `@andreibesleaga/gabbe-kit` (npmjs stays canonical). The installed command is `gabbe` either way. After installing, run `gabbe doctor` for an environment + install report. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).
64
+ > On npm the package is **`gabbe-kit`** (npm refuses the unscoped `gabbe`); on PyPI it is **`gabbe`**; the npm package is additionally mirrored on GitHub Packages as `@andreibesleaga/gabbe-kit` (npmjs stays canonical). Both packages install a command named `gabbe`, but not the same one: on npm it is the kit installer (`gabbe init` only), on PyPI it is the CLI. After installing the PyPI CLI, run `gabbe doctor` for an environment + install report. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).
61
65
 
62
66
  **Universal, Python-independent (one command):**
63
67
  ```bash
@@ -121,7 +125,7 @@ Steps after running the wizard:
121
125
  **Manual Setup:**
122
126
  ```bash
123
127
  cp -r GABBE/agents .
124
- chmod +x agents/setup-context.sh && agents/setup-context.sh
128
+ chmod +x agents/scripts/setup-context.sh && agents/scripts/setup-context.sh
125
129
  ```
126
130
 
127
131
  ### Install as a Claude Code plugin
@@ -520,7 +524,7 @@ agents/
520
524
  ├── guides/ # 86 language & domain guides
521
525
  ├── personas/ # 36 specialized agent roles
522
526
  ├── memory/ # Episodic + semantic + project state
523
- └── docs/ # Whitepapers & research
527
+ └── scripts/ # setup-context, validators, state export/import
524
528
  ```
525
529
 
526
530
  ---
@@ -545,34 +549,36 @@ Sits **above** Loki. Decides *how* to execute, not just *what* to execute.
545
549
  | **Episodic Memory** | Recalls past project outcomes to avoid repeated mistakes |
546
550
  | **System 2 Thinking** | Strategic planning before execution |
547
551
 
552
+ These are the agent-mode behaviours of `brain-mode.skill`. The `gabbe brain` CLI is smaller: it reads task counts, picks a prompt gene (epsilon-greedy), makes one LLM call and rewards the gene; routing is `gabbe route`, and it does no episodic recall (see [ADR-0002](docs/adr/0002-brain-active-inference-runtime.md)).
553
+
548
554
  ---
549
555
 
550
556
  ## 🔧 Setup by Project Type
551
557
 
552
558
  ### JavaScript / TypeScript / Node.js
553
559
  ```
554
- Guide: guides/js-ts-nodejs.md
560
+ Guide: guides/languages/js-ts-nodejs.md
555
561
  Stack: Vitest, Zod, Prisma, Playwright, Hono
556
562
  Config in AGENTS.md: test_cmd="npx vitest", lint_cmd="npx eslint ."
557
563
  ```
558
564
 
559
565
  ### Go (Golang)
560
566
  ```
561
- Guide: guides/go-lang.md
567
+ Guide: guides/languages/go-lang.md
562
568
  Stack: Echo/Gin, Ent, Testify, Testcontainers
563
569
  Config in AGENTS.md: test_cmd="go test ./...", lint_cmd="golangci-lint run"
564
570
  ```
565
571
 
566
572
  ### PHP / Laravel
567
573
  ```
568
- Guide: guides/php-laravel.md
574
+ Guide: guides/languages/php-laravel.md
569
575
  Stack: DDD, Actions, Pest PHP, PHPStan L9, Enlightn
570
576
  Config in AGENTS.md: test_cmd="vendor/bin/pest", lint_cmd="vendor/bin/pint"
571
577
  ```
572
578
 
573
579
  ### Python / FastAPI
574
580
  ```
575
- Guide: guides/python-fastapi-ai.md
581
+ Guide: guides/languages/python-fastapi-ai.md
576
582
  Stack: Pydantic, Pytest, Ruff, FastAPI
577
583
  Config in AGENTS.md: test_cmd="pytest", lint_cmd="ruff check ."
578
584
  ```
@@ -617,7 +623,7 @@ the Day-0 phase **S00 (Strategy & Discovery)** and the Day-2 phases **S11–S13
617
623
  | **Industry** | 5+ | `healthcare-fhir`, `telecom-networks`, `industrial-iot`, `global-standards`, `engineering-standards` |
618
624
  | **Loki Modes** | 2+ | `brain-mode`, `loki-mode` |
619
625
 
620
- Full catalog: `agents/skills/00-index.md` *(generated by `init.py`)*
626
+ Full catalog: `agents/skills/00-index.md`
621
627
 
622
628
  ---
623
629
 
@@ -631,12 +637,12 @@ Full catalog: `agents/skills/00-index.md` *(generated by `init.py`)*
631
637
  | **Security** | 5+ | Threat Model, Safety Case, Ethical Impact |
632
638
  | **Product** | 10+ | PRD, Spec, User Story Map, Visual Spec, Green Software |
633
639
  | **Core** | 5+ | Plan, Tasks, Audit Log, Project State, Continuity |
634
- | **Coordination** | 5+ | Agent Profile, Swarm Config, Handshake, Voting Log |
640
+ | **Coordination** | 5+ | Agent Profile, Swarm Config, Handshake, Swarm Architecture |
635
641
  | **Brain** | 5+ | Active Inference Loop, Episodic Memory, OODA Trace |
636
- | **Data** | 5+ | Data Pipeline, Database Schema, OWL Ontology |
642
+ | **Data** | 3 | Data Pipeline, Database Schema, OWL Ontology |
637
643
  | **Industry** | 5+ | FHIR Interop, IoT Telemetry, Telecom API, Global SDLC Audit |
638
644
 
639
- Full catalog: `agents/templates/00-index.md` *(generated by `init.py`)*
645
+ Full catalog: `agents/templates/00-index.md`
640
646
 
641
647
  ---
642
648
 
@@ -686,7 +692,7 @@ Task → Knowledge gap? → research.skill → Execute → Verify
686
692
 
687
693
  | Problem | Fix |
688
694
  |---|---|
689
- | Agent ignores AGENTS.md | Run `setup-context.sh` to create symlinks |
695
+ | Agent ignores AGENTS.md | Run `agents/scripts/setup-context.sh` to create symlinks |
690
696
  | Agent repeats mistakes | Check `CONTINUITY.md` — tell agent to read it |
691
697
  | Tests pass immediately | False positive — test is broken, fix it first |
692
698
  | Uses deprecated APIs | Activate Context-7 MCP |
@@ -744,10 +750,10 @@ Agents are explicitly configured to **Fail-Closed**—they must wait for human a
744
750
 
745
751
  ## 🚀 GABBE CLI (Experimental)
746
752
 
747
- GABBE has also an experimental helper, **Zero-Dependency CLI** (`gabbe`) for a "Hybrid Mode" (Markdown files and a SQLite database) and launching different commands. It is a work-in-progress and you can do without it, only with the rest of the kit.
753
+ GABBE has also an experimental helper, **lightweight CLI** (`gabbe`; three runtime dependencies: `requests`, `PyYAML`, `jsonschema`) for a "Hybrid Mode" (Markdown files and a SQLite database) and launching different commands. It is a work-in-progress and you can do without it, only with the rest of the kit.
748
754
 
749
755
  ### Prerequisites
750
- - Python 3.8+
756
+ - Python 3.9+
751
757
  - **LLM API Key**: For Brain/Route features, set `GABBE_API_KEY` (OpenAI-compatible).
752
758
 
753
759
  **Environment Variables** (full reference in [CLI_REFERENCE.md](docs/CLI_REFERENCE.md)):
@@ -797,7 +803,7 @@ gabbe --help
797
803
  | `gabbe verify`| **Enforcer**: programmable integrity check (files, tests, lint). |
798
804
  | `gabbe status`| **Dashboard**: Visualizes project phase and task progress. |
799
805
  | `gabbe brain` | **Meta-Cognition**: Activates Active Inference loop or Evolutionary Prompt Optimization (Requires API Key). |
800
- | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (Requires API Key). |
806
+ | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (prompts of 100+ characters or with code blocks are rated by the LLM and need `GABBE_API_KEY`; without a key a fallback heuristic is used). |
801
807
  | `gabbe forecast`| **Strategic Forecast**: Projects remaining work cost and tokens based on historical run data. |
802
808
  | `gabbe serve-mcp` | **MCP Gateway**: Zero-dependency JSON-RPC Model Context Protocol server for standalone agents to access tools safely. |
803
809
  | `gabbe runs` | **Run History**: List recent agent runs with status, cost, and timestamps. |
@@ -807,6 +813,9 @@ gabbe --help
807
813
  | `gabbe registry publish` | **Publish Skills**: Export the kit's skills as a publish-ready agentskills.io bundle (manifest + agent-card) for universal registries. |
808
814
  | `gabbe registry add <source>` | **Import Skills**: Draw an external skill/bundle (path, `.tar.gz`, or URL) — validated + security-scanned + landed namespaced for review. |
809
815
  | `gabbe setup` | **Install Wizard**: Run the interactive installer to wire the kit into your coding agents (see also `npx gabbe-kit init`). |
816
+ | `gabbe doctor` | **Autodetect**: OS/arch, runtimes, installed agents + post-install MCP next-steps. |
817
+ | `gabbe eval` | **Skill evals**: deterministic self-check; `--live` scores skill outputs via the model. |
818
+ | `gabbe update` / `gabbe uninstall` | **Reversible install**: additive refresh / manifest-backed removal (`--dry-run`, `--purge`, `--global`, `--dir`). |
810
819
 
811
820
  ### Platform Control Layer
812
821
  The experimental `gabbe` CLI supports a **platform control layer**. It covers budget enforcement, cost and token controls, hard stops, policy rules, the tool gateway, audit tracing, human escalation, and deterministic replay. Detailed documentation is available in [`PLATFORM_CONTROLS.md`](docs/PLATFORM_CONTROLS.md).
package/agents/AGENTS.md CHANGED
@@ -569,7 +569,7 @@ the same operating spine in §5/§13 (preflight → clarify → act → state-pr
569
569
  ---
570
570
 
571
571
  *Last updated: [DATE]*
572
- *GABBE Kit version: 1.1.0*
572
+ *GABBE Kit version: 1.1.3*
573
573
  *This file is maintained by the team and updated when project conventions change.*
574
574
 
575
575
  ---
@@ -184,5 +184,5 @@
184
184
  *Amended by: [team member name]*
185
185
  *Reason for amendment: [brief explanation]*
186
186
 
187
- *GABBE Kit version: 1.1.0*
187
+ *GABBE Kit version: 1.1.3*
188
188
  *This file is maintained by the team and updated when project conventions change.*
@@ -240,7 +240,7 @@ GOOD (EARS — testable):
240
240
  ```json
241
241
  {
242
242
  "mcpServers": {
243
- "context7": { "command": "npx", "args": ["@context7/mcp-server"] },
243
+ "context7": { "command": "npx", "args": ["@upstash/context7-mcp"] },
244
244
  "sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] },
245
245
  "github": {
246
246
  "command": "npx",
@@ -256,6 +256,8 @@ GOOD (EARS — testable):
256
256
  }
257
257
  ```
258
258
 
259
+ > The `server-github` and `server-postgres` packages above are deprecated: npm marks them "no longer supported" (checked 2026-10-30), though they still install. See `docs/MCP_CONFIGURATIONS.md` for current alternatives.
260
+
259
261
  **Key MCP servers for agentic engineering:**
260
262
  - **Context-7**: Up-to-date library docs (prevents hallucinated API usage)
261
263
  - **Sequential Thinking**: Forces structured reasoning before acting
@@ -27,7 +27,7 @@ Financial Operations (FinOps) is the operating model for the cloud, bringing fin
27
27
 
28
28
  ## LLM & Agentic Cost Control (the agent's own spend)
29
29
 
30
- The largest variable cost of an agentic system is LLM tokens. GABBE controls this with four levers, all enforceable through the platform-control layer (`gabbe budget` / `route` / `forecast`).
30
+ The largest variable cost of an agentic system is LLM tokens. GABBE controls this with four levers, all enforceable through the platform-control layer (the `GABBE_MAX_COST_USD` budget, `gabbe route` and `gabbe forecast`).
31
31
 
32
32
  ### 1. Prompt caching — the highest-leverage lever
33
33
  Reusing a stable prompt prefix avoids re-billing it on every call. Sources verified 2026-06-10.
@@ -21,7 +21,7 @@ This guide provides solutions to common issues encountered when initializing, co
21
21
  **Cause:** Windows requires Administrator privileges to create symlinks by default.
22
22
  **Solution:**
23
23
  1. Open PowerShell **as Administrator**.
24
- 2. Run `.\agents\setup-context.ps1`.
24
+ 2. Run `.\agents\scripts\setup-context.ps1`.
25
25
  3. Alternatively, enable Developer Mode in Windows Settings (which allows standard users to create symlinks).
26
26
 
27
27
  ## 2. Agent Configuration Issues
@@ -30,7 +30,7 @@ This guide provides solutions to common issues encountered when initializing, co
30
30
  **Symptoms:** The agent generates code in the wrong framework or ignores layer boundaries.
31
31
  **Cause:** The symlink from `.cursorrules` or `.claude/CLAUDE.md` to `AGENTS.md` is broken, or the file lacks rules.
32
32
  **Solution:**
33
- 1. Re-run `./agents/setup-context.sh`.
33
+ 1. Re-run `./agents/scripts/setup-context.sh`.
34
34
  2. Check `AGENTS.md` to ensure `[PLACEHOLDER]` fields are filled correctly.
35
35
 
36
36
  ### Skills not triggering
@@ -30,7 +30,7 @@ def run_gabbe_command(cmd, env, cwd):
30
30
  process = subprocess.run(cmd, text=True, env=env, cwd=str(cwd), capture_output=True, shell=True)
31
31
  # gabbe verify is expected to fail with exit code 1 due to [PLACEHOLDER] variables inside a freshly initialized setup.
32
32
  # The success state is it finding the placeholders instead of crashing.
33
- if "gabbe verify" in cmd and process.returncode != 0:
33
+ if cmd.endswith(" verify") and process.returncode != 0:
34
34
  if (
35
35
  "Verification FAILED" in process.stdout
36
36
  or "Placeholder" in process.stdout
@@ -10,7 +10,7 @@
10
10
 
11
11
  ### Method 1: This Kit (built-in — no install needed)
12
12
  All 214 skills in this directory are ready to use immediately.
13
- Run `setup-context.sh` to wire them to your AI tool's skill directory.
13
+ Run `agents/scripts/setup-context.sh` to wire them to your AI tool's skill directory.
14
14
 
15
15
  ### Method 2: Skill Marketplaces & Registries
16
16
  ```bash
@@ -35,7 +35,7 @@ namnam install --platform claude-code
35
35
  ### Global vs Workspace Scope
36
36
  ```bash
37
37
  # Workspace scope (this project only):
38
- # .claude/skills/ -> agents/skills/*/*.skill.md (done by setup-context.sh)
38
+ # .claude/skills/ -> agents/skills/*/*.skill.md (done by agents/scripts/setup-context.sh)
39
39
 
40
40
  # Global scope (all projects on this machine):
41
41
  ln -sf /path/to/agents/skills/*/*.skill.md ~/.claude/skills/
@@ -31,3 +31,20 @@ To be used when the user requests generating diagrams onto a physical board, can
31
31
  ## 4. Avoiding Hallucinations
32
32
  * **Spatial Overlap**: Agents must calculate X/Y coordinates carefully to avoid stacking nodes on top of each other. Add an arbitrary offset (e.g., +200px) per new node in a sequence.
33
33
  * **Secret Leakage**: NEVER write API keys, database credentials, or real user data onto shared visual canvases like Miro or Figma. Redact all tokens.
34
+
35
+ ## Security & Guardrails
36
+
37
+ ### 1. Skill Security
38
+
39
+ * **No secrets on canvases**: Boards and design files are shared with everyone who has the link. Never place API keys, credentials, internal hostnames or real user data on them; use labelled placeholders.
40
+ * **Sanitize labels**: Treat user-provided node names as untrusted text. Escape them before writing `.drawio` XML or board items, so a label cannot break the file or inject markup.
41
+
42
+ ### 2. System Integration Security
43
+
44
+ * **Least-privilege MCP tokens**: Give the Miro, Draw.io or Figma MCP server a token scoped to the one board or file it needs, read-only where the task only reads (Figma extraction).
45
+ * **Respect board permissions**: Do not change sharing settings or invite users; ask the human to do it.
46
+
47
+ ### 3. LLM & Agent Guardrails
48
+
49
+ * **Draw only what exists**: Render the verified architecture from the plan or the code. Do not add components (WAF, KMS, queues) that the system does not have.
50
+ * **Human review before sharing**: Present the generated diagram for approval before it is posted to a shared board.
@@ -46,6 +46,23 @@ Build fast, type-safe, maintainable PHP services using the current ecosystem (ve
46
46
  4. **Raise the static-analysis level** (PHPStan/Psalm) and let it fail CI; apply Rector for safe upgrades.
47
47
  5. **Re-profile** and record the before/after numbers.
48
48
 
49
+ ## Security & Guardrails
50
+
51
+ ### 1. Skill Security
52
+
53
+ - **Parameterized queries only**: Use PDO prepared statements or the ORM's bindings; never interpolate user input into SQL, shell commands (`exec`, `shell_exec`) or `unserialize()`.
54
+ - **Dependency hygiene**: Run `composer audit` in CI and keep `roave/security-advisories` installed so a vulnerable package fails the install.
55
+
56
+ ### 2. System Integration Security
57
+
58
+ - **Worker-mode state**: In FrankenPHP worker mode, RoadRunner or Swoole the process outlives the request. Reset per-request state (auth, tenant, static caches) so data cannot leak between users.
59
+ - **Production settings**: Keep `display_errors=Off` and `expose_php=Off`; load secrets from the environment, never from committed files.
60
+
61
+ ### 3. LLM & Agent Guardrails
62
+
63
+ - **Measure before optimizing**: Do not enable JIT, preloading or worker mode without a before/after profile; record both numbers.
64
+ - **Version claims**: Check the PHP and framework versions in `composer.json` before using 8.4/8.5-only syntax.
65
+
49
66
  ## Sources (verified 2026-06-10)
50
67
  - PHP 8.5 / 8.4 features: <https://www.php.net/releases/8.5/en.php> · <https://php.watch/versions>
51
68
  - Laravel 12: <https://laravel.com/docs/12.x/releases>
@@ -653,5 +653,5 @@ the same operating spine in §5/§13 (preflight → clarify → act → state-pr
653
653
  ---
654
654
 
655
655
  *Last updated: [DATE]*
656
- *GABBE Kit version: 1.1.0*
656
+ *GABBE Kit version: 1.1.3*
657
657
  *This file is maintained by the team and updated when project conventions change.*
@@ -8,7 +8,7 @@
8
8
  "_description": "Up-to-date SDK docs \u2014 prevents API hallucination. HIGHLY RECOMMENDED.",
9
9
  "command": "npx",
10
10
  "args": [
11
- "@context7/mcp-server"
11
+ "@upstash/context7-mcp"
12
12
  ],
13
13
  "env": {}
14
14
  },
@@ -23,6 +23,7 @@
23
23
  },
24
24
  "brave-search": {
25
25
  "_description": "Authoritative web research with source filtering.",
26
+ "_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
26
27
  "command": "npx",
27
28
  "args": [
28
29
  "-y",
@@ -45,6 +46,7 @@
45
46
  "_section_version_control": "=== VERSION CONTROL & PROJECT MANAGEMENT ===",
46
47
  "github": {
47
48
  "_description": "PR review, code search, issue management, git history.",
49
+ "_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
48
50
  "command": "npx",
49
51
  "args": [
50
52
  "-y",
@@ -69,6 +71,7 @@
69
71
  "_section_database": "=== DATABASES ===",
70
72
  "postgres-dev": {
71
73
  "_description": "PostgreSQL for development \u2014 READ-WRITE allowed.",
74
+ "_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
72
75
  "_security": "DEVELOPMENT ONLY \u2014 never use read-write in production",
73
76
  "command": "npx",
74
77
  "args": [
@@ -108,6 +111,7 @@
108
111
  },
109
112
  "postgres-prod": {
110
113
  "_description": "PostgreSQL for production \u2014 READ-ONLY. Schema introspection only.",
114
+ "_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
111
115
  "_security": "PRODUCTION \u2014 read-only access enforced by database user permissions",
112
116
  "_enable_only_when_needed": true,
113
117
  "command": "npx",
@@ -148,7 +152,7 @@
148
152
  "command": "npx",
149
153
  "args": [
150
154
  "-y",
151
- "@sentry/mcp"
155
+ "@sentry/mcp-server"
152
156
  ],
153
157
  "env": {
154
158
  "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}",
@@ -192,6 +196,8 @@
192
196
  "_section_infrastructure": "=== CLOUD & INFRASTRUCTURE ===",
193
197
  "terraform": {
194
198
  "_description": "Agentic Infrastructure as Code (IaC) via HashiCorp Terraform.",
199
+ "_note": "No npm package (E404 checked 2026-10-30). HashiCorp ships terraform-mcp-server as a Go binary and Docker image.",
200
+ "_enabled": false,
195
201
  "command": "npx",
196
202
  "args": [
197
203
  "-y",
@@ -205,6 +211,7 @@
205
211
  "docker": {
206
212
  "_enabled": false,
207
213
  "_description": "Docker daemon integration \u2014 manage containers, images, and read local logs.",
214
+ "_note": "No npm package (E404 checked 2026-10-30). Desktop server: use the MCP Toolkit in Docker Desktop.",
208
215
  "command": "npx",
209
216
  "args": [
210
217
  "-y",
@@ -215,6 +222,7 @@
215
222
  "google-cloud": {
216
223
  "_enabled": false,
217
224
  "_description": "Google Cloud Platform access \u2014 manage Firebase, Cloud Run, GKE, BigQuery.",
225
+ "_note": "No npm package (E404 checked 2026-10-30). Use Google Cloud's own MCP documentation instead of npx.",
218
226
  "command": "npx",
219
227
  "args": [
220
228
  "-y",
@@ -241,6 +249,7 @@
241
249
  "vercel": {
242
250
  "_enabled": false,
243
251
  "_description": "Vercel deployments, aliases, and serverless log integration.",
252
+ "_note": "No npm package (E404 checked 2026-10-30). Hosted server: use Vercel's hosted MCP; @vercel/mcp-adapter builds your own.",
244
253
  "command": "npx",
245
254
  "args": [
246
255
  "-y",
@@ -253,6 +262,7 @@
253
262
  "gitlab": {
254
263
  "_enabled": false,
255
264
  "_description": "GitLab alternative to GitHub MCP.",
265
+ "_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
256
266
  "command": "npx",
257
267
  "args": [
258
268
  "-y",
@@ -306,6 +316,7 @@
306
316
  "datadog": {
307
317
  "_enabled": false,
308
318
  "_description": "Monitoring, alerts, observability queries.",
319
+ "_note": "No npm package (E404 checked 2026-10-30). Hosted server: connect to Datadog's hosted MCP.",
309
320
  "command": "npx",
310
321
  "args": [
311
322
  "-y",
@@ -319,6 +330,7 @@
319
330
  "grafana": {
320
331
  "_enabled": false,
321
332
  "_description": "Dashboard search, datasource queries, incident management.",
333
+ "_note": "No npm package (E404 checked 2026-10-30). Grafana ships the Go mcp-grafana server.",
322
334
  "command": "npx",
323
335
  "args": [
324
336
  "-y",
@@ -332,6 +344,7 @@
332
344
  "aws-core": {
333
345
  "_enabled": false,
334
346
  "_description": "AWS core services \u2014 documentation, CDK, Lambda.",
347
+ "_note": "No npm package (E404 checked 2026-10-30). AWS ships awslabs.* servers on PyPI (run with uvx).",
335
348
  "command": "npx",
336
349
  "args": [
337
350
  "-y",
@@ -373,6 +386,7 @@
373
386
  "figma": {
374
387
  "_enabled": false,
375
388
  "_description": "UI/UX semantic understanding, component specs, and design-to-code.",
389
+ "_note": "No npm package (E404 checked 2026-10-30). Desktop server: enable the Dev Mode MCP server in the Figma desktop app.",
376
390
  "command": "npx",
377
391
  "args": [
378
392
  "-y",
@@ -417,6 +431,7 @@
417
431
  "miro": {
418
432
  "_enabled": false,
419
433
  "_description": "Read context from virtual whiteboards and continuously sync architecture PRDs.",
434
+ "_note": "No npm package (E404 checked 2026-10-30). Connect through Miro's own MCP documentation instead of npx.",
420
435
  "command": "npx",
421
436
  "args": [
422
437
  "-y",
@@ -461,6 +476,7 @@
461
476
  "redis": {
462
477
  "_enabled": false,
463
478
  "_description": "Redis interaction and key management.",
479
+ "_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
464
480
  "command": "npx",
465
481
  "args": [
466
482
  "-y",
@@ -520,6 +536,7 @@
520
536
  "confluence": {
521
537
  "_enabled": false,
522
538
  "_description": "Confluence pages and spaces.",
539
+ "_note": "No npm package (E404 checked 2026-10-30). Use a community Atlassian server such as mcp-atlassian.",
523
540
  "command": "npx",
524
541
  "args": [
525
542
  "-y",
@@ -613,6 +630,7 @@
613
630
  "zapier": {
614
631
  "_enabled": false,
615
632
  "_description": "Connect to 6,000+ apps via Zapier.",
633
+ "_note": "No npm package (E404 checked 2026-10-30). Hosted server: connect to your per-user URL at mcp.zapier.com.",
616
634
  "command": "npx",
617
635
  "args": [
618
636
  "-y",
@@ -665,6 +683,7 @@
665
683
  "_enabled": false,
666
684
  "_security": "DEVELOPMENT ONLY \u2014 restrict to project directory. Never enable in production.",
667
685
  "_description": "Execute shell commands for local build, test, and system introspection (internal RAG).",
686
+ "_note": "No npm package (E404 checked 2026-10-30). Do not use; run shell commands through your agent's own tools.",
668
687
  "command": "npx",
669
688
  "args": [
670
689
  "-y",
@@ -12,7 +12,7 @@
12
12
  **Success metric:** [How will we know this feature succeeds? e.g., "Checkout abandonment drops 15%"]
13
13
 
14
14
  **Strategic Context (Step 0 Reference):**
15
- - [BUSINESS_CASE.md](link) or [EMPATHY_MAP.md](link) or [None]
15
+ - [Path to BUSINESS_CASE.md or EMPATHY_MAP.md, or None]
16
16
 
17
17
  ---
18
18
 
package/bin/install.js CHANGED
@@ -423,6 +423,8 @@ Options:
423
423
  gemini, antigravity, opencode, zed, continue, roo, kilo,
424
424
  codex, copilot, vscode.
425
425
  --yes, -y Non-interactive: accept defaults, do not prompt.
426
+ --force Also refresh preserved files such as AGENTS.md and
427
+ CONSTITUTION.md (the old copy is backed up to .gabbe-bak).
426
428
  --wizard Delegate to the full Python wizard (scripts/init.py) if
427
429
  python3 is available (interactive, richer configuration).
428
430
  --help, -h Show this help.
@@ -439,7 +441,15 @@ Examples:
439
441
  `;
440
442
 
441
443
  function parseArgs(argv) {
442
- const opts = { command: null, agents: [], yes: false, wizard: false, help: false, force: false };
444
+ const opts = {
445
+ command: null,
446
+ agents: [],
447
+ yes: false,
448
+ wizard: false,
449
+ help: false,
450
+ force: false,
451
+ unknown: [],
452
+ };
443
453
  for (let i = 0; i < argv.length; i++) {
444
454
  const a = argv[i];
445
455
  if (a === 'init') {
@@ -459,6 +469,10 @@ function parseArgs(argv) {
459
469
  } else if (a.startsWith('-')) {
460
470
  log(red(`Unknown option: ${a}`));
461
471
  opts.help = true;
472
+ } else {
473
+ // An unknown word (e.g. `gabbe doctor`, a command of the PyPI CLI) must
474
+ // not fall through to the default `init` and copy the kit.
475
+ opts.unknown.push(a);
462
476
  }
463
477
  }
464
478
  return opts;
@@ -586,6 +600,15 @@ function runInit(opts) {
586
600
 
587
601
  function main() {
588
602
  const opts = parseArgs(process.argv.slice(2));
603
+ if (opts.unknown.length) {
604
+ process.stderr.write(red(`Unknown command: ${opts.unknown.join(' ')}`) + '\n');
605
+ process.stderr.write(
606
+ 'The npm package only installs the kit; `gabbe doctor` and the other CLI\n' +
607
+ 'commands come from the PyPI package (pipx install gabbe).\n\n'
608
+ );
609
+ process.stderr.write(USAGE);
610
+ return 1;
611
+ }
589
612
  if (opts.help) {
590
613
  process.stdout.write(USAGE);
591
614
  return 0;