@maximalabs/dev-mcp-suite 0.0.0-stage → 3.6.1

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.
Files changed (68) hide show
  1. package/.env.example +69 -0
  2. package/CHANGELOG.md +281 -0
  3. package/CODEX_DEV_MCP_GUIDE.md +297 -0
  4. package/LICENSE +21 -0
  5. package/README.md +193 -2
  6. package/armada/package.json +14 -0
  7. package/armada/server.js +329 -0
  8. package/backfill-sessions-v2.mjs +288 -0
  9. package/bin/_meta.mjs +73 -0
  10. package/bin/armada-mcp.mjs +12 -0
  11. package/bin/checkpoint.mjs +9 -0
  12. package/bin/context-pack.mjs +9 -0
  13. package/bin/devjournal.mjs +9 -0
  14. package/bin/init.mjs +25 -0
  15. package/bin/project-memory.mjs +10 -0
  16. package/bin/provider-smoke.mjs +278 -0
  17. package/bin/prune.mjs +158 -0
  18. package/bin/stats.mjs +101 -0
  19. package/bin/ui.mjs +5 -0
  20. package/checkpoint/package.json +14 -0
  21. package/checkpoint/server.js +318 -0
  22. package/context-pack/package.json +14 -0
  23. package/context-pack/server.js +747 -0
  24. package/devjournal/compress.js +75 -0
  25. package/devjournal/env.js +3 -0
  26. package/devjournal/package.json +14 -0
  27. package/devjournal/provider-chain.js +109 -0
  28. package/devjournal/rerank.js +120 -0
  29. package/devjournal/server.js +415 -0
  30. package/docs/ROADMAP.md +77 -0
  31. package/docs/clients/antigravity.md +52 -0
  32. package/docs/clients/claude-code.md +46 -0
  33. package/docs/clients/codex.md +39 -0
  34. package/docs/clients/generic-mcp.md +45 -0
  35. package/docs/clients/hermes.md +48 -0
  36. package/docs/configuration.md +123 -0
  37. package/docs/privacy.md +39 -0
  38. package/docs/providers.md +13 -0
  39. package/docs/superpowers/plans/2026-06-15-hardening-v1-2-implementation.md +60 -0
  40. package/docs/superpowers/plans/2026-06-15-provider-chain-v1-1-implementation.md +65 -0
  41. package/docs/superpowers/plans/2026-06-15-provider-client-agnostic-config.md +41 -0
  42. package/docs/superpowers/plans/2026-06-15-trust-release-implementation.md +62 -0
  43. package/docs/superpowers/plans/2026-06-18-v1-5-0-knowledge-graph.md +792 -0
  44. package/docs/superpowers/specs/2026-06-15-provider-chain-v1-1-design.md +89 -0
  45. package/docs/superpowers/specs/2026-06-15-trust-release-design.md +164 -0
  46. package/docs/superpowers/specs/2026-06-18-dev-mcp-suite-v1-5-0-knowledge-graph-design.md +386 -0
  47. package/docs/superpowers/specs/2026-07-22-v2-0-0-peak-intelligence.md +50 -0
  48. package/docs/superpowers/specs/2026-07-22-v3-0-0-god-tier.md +32 -0
  49. package/lib/init-wizard.js +120 -0
  50. package/lib/provider-smoke.js +234 -0
  51. package/lib/prune.js +114 -0
  52. package/lib/stats.js +269 -0
  53. package/lib/ui-server.js +151 -0
  54. package/lib/update-check.js +125 -0
  55. package/package.json +71 -4
  56. package/project-memory/auto-indexer.js +152 -0
  57. package/project-memory/dedup.js +49 -0
  58. package/project-memory/embedding.js +174 -0
  59. package/project-memory/env.js +3 -0
  60. package/project-memory/global-index.js +46 -0
  61. package/project-memory/graph.js +93 -0
  62. package/project-memory/local-embed.js +92 -0
  63. package/project-memory/package.json +14 -0
  64. package/project-memory/provider-chain.js +109 -0
  65. package/project-memory/rerank.js +120 -0
  66. package/project-memory/server.js +931 -0
  67. package/project-memory/swarm.js +56 -0
  68. package/run-tests.mjs +54 -0
@@ -0,0 +1,48 @@
1
+ # Hermes Agent Setup
2
+
3
+ `@maximalabs/dev-mcp-suite` is fully compatible with **Hermes Agent** via the standard Model Context Protocol (MCP) stdio interface.
4
+
5
+ ## Quick Installation
6
+
7
+ Ensure the package is installed globally or accessible via `npx`:
8
+
9
+ ```bash
10
+ npm install -g @maximalabs/dev-mcp-suite
11
+ ```
12
+
13
+ ## Hermes Configuration (`~/.hermes/config.yaml`)
14
+
15
+ Add the suite servers to your Hermes `mcp_servers` configuration block in `~/.hermes/config.yaml`:
16
+
17
+ ```yaml
18
+ mcp_servers:
19
+ project-memory:
20
+ command: project-memory-mcp
21
+ args: []
22
+ env:
23
+ MEMORY_VAULT_DIR: "~/.local/share/dev-mcp-suite/memories/vault"
24
+ MCP_LOCAL_EMBED: "true" # Enables zero-dependency local offline vector search
25
+
26
+ devjournal:
27
+ command: devjournal-mcp
28
+ args: []
29
+ env:
30
+ JOURNAL_DIR: "~/.local/share/dev-mcp-suite/memories/journal"
31
+
32
+ checkpoint:
33
+ command: checkpoint-mcp
34
+ args: []
35
+ env:
36
+ CHECKPOINT_DIR: "~/.local/share/dev-mcp-suite/memories/checkpoints"
37
+
38
+ context-pack:
39
+ command: context-pack-mcp
40
+ args: []
41
+ ```
42
+
43
+ ## Features Available to Hermes
44
+
45
+ - **`memory_save` / `memory_recall`**: Persistent cross-session memory with optional local offline 384-d term-frequency hashing vector search (`MCP_LOCAL_EMBED=true`).
46
+ - **`journal_log` / `journal_resume` / `journal_handoff`**: Session log & handoff recovery.
47
+ - **`checkpoint_create` / `checkpoint_diff`**: File checkpoints independent of git.
48
+ - **`pack_overview` / `pack_tree` / `pack_audit`**: Codebase orientation & security risk auditing.
@@ -0,0 +1,123 @@
1
+ # Configuration
2
+
3
+ Dev MCP Suite is MCP-client agnostic. The servers run locally over stdio and work in any client that can launch MCP servers: Codex CLI, Claude Code, Cursor, Cline, Gemini-compatible launchers, Hermes, and generic MCP hosts.
4
+
5
+ ## Storage
6
+
7
+ All storage is local and file-based.
8
+
9
+ | Env var | Used by | Default |
10
+ |---|---|---|
11
+ | `MEMORY_VAULT_DIR` | `project-memory` | `~/.codex/memories/vault` |
12
+ | `JOURNAL_DIR` | `devjournal` | `~/.codex/memories/journal` |
13
+ | `CHECKPOINT_DIR` | `checkpoint` | `~/.codex/memories/checkpoints` |
14
+
15
+ Use a different base path if your MCP client is not Codex, for example `~/.local/share/dev-mcp-suite/...`.
16
+
17
+ ## Optional model features
18
+
19
+ `context-pack` and `checkpoint` never need a model. `project-memory` and `devjournal` work offline by keyword search and can optionally use an OpenAI-compatible API for better recall.
20
+
21
+ No remote calls are made unless you configure a model endpoint. For strict local-only behavior even when model env vars are present, set `MCP_DETERMINISTIC_FALLBACK=true`.
22
+
23
+ | Env var | Purpose |
24
+ |---|---|
25
+ | `MCP_LLM_BASE_URL` | Base URL for an OpenAI-compatible API, e.g. `http://localhost:11434/v1` or `http://localhost:20128` |
26
+ | `MCP_LLM_API_KEY` | API key for that endpoint; leave blank for local servers that do not require auth |
27
+ | `MCP_RERANK_MODEL` | Chat model for LLM reranking, e.g. `llama3.1:8b`, `kr/claude-haiku-4.5`, `gpt-4o-mini` |
28
+ | `MCP_RERANK_BASE_URL` | Optional rerank-specific base URL; falls back to `MCP_LLM_BASE_URL` |
29
+ | `MCP_RERANK_API_KEY` | Optional rerank-specific API key; falls back to `MCP_LLM_API_KEY` |
30
+ | `RERANK_ENABLED` | Set `0` to disable reranking |
31
+ | `RERANK_TIMEOUT_MS` | Rerank request timeout; default `30000` |
32
+ | `MCP_EMBED_MODEL` | Embedding model for semantic recall, e.g. `nomic-embed-text`, `text-embedding-3-small`, `bm/baai/bge-m3` |
33
+ | `MCP_EMBED_BASE_URL` | Optional embedding-specific base URL; falls back to `MCP_LLM_BASE_URL` |
34
+ | `MCP_EMBED_API_KEY` | Optional embedding-specific API key; falls back to `MCP_LLM_API_KEY` |
35
+ | `EMBED_TIMEOUT_MS` | Embedding request timeout; default `15000` |
36
+ | `MCP_DETERMINISTIC_FALLBACK` | Hard no-network fallback when true; accepts `true`, `1`, `yes`, `on` |
37
+
38
+ Recall mode order:
39
+
40
+ 1. `deterministic` if `MCP_DETERMINISTIC_FALLBACK=true`.
41
+ 2. `semantic` if embeddings are configured and available.
42
+ 3. `rerank` if a chat model is configured and enabled.
43
+ 4. `keyword` offline fallback, always available.
44
+
45
+ Failures degrade gracefully. If your embedding endpoint returns `503`, recall falls back to rerank/keyword instead of failing the tool call.
46
+
47
+ ## Provider strategy
48
+
49
+ The suite is provider-neutral. A practical remote setup is:
50
+
51
+ 1. **Groq** for fast rerank/chat when model quality is sufficient.
52
+ 2. **Cerebras** as a second fast provider for outages or model fit.
53
+ 3. **OpenRouter** as broad fallback for many OpenAI-compatible models.
54
+
55
+ In `v1.1`, chat/rerank can use built-in numbered fallback slots. Configure only primary if you want one provider, or add more numbered chain entries.
56
+
57
+ ```bash
58
+ MCP_PROVIDER_PRIMARY=groq
59
+ MCP_PROVIDER_PRIMARY_BASE_URL=https://api.groq.com/openai/v1
60
+ MCP_PROVIDER_PRIMARY_API_KEY=<groq-key>
61
+ MCP_PROVIDER_PRIMARY_MODEL=llama-3.3-70b-versatile
62
+
63
+ MCP_PROVIDER_CHAIN2=cerebras
64
+ MCP_PROVIDER_CHAIN2_BASE_URL=https://api.cerebras.ai/v1
65
+ MCP_PROVIDER_CHAIN2_API_KEY=<cerebras-key>
66
+ MCP_PROVIDER_CHAIN2_MODEL=llama-3.3-70b
67
+
68
+ MCP_PROVIDER_CHAIN3=openrouter
69
+ MCP_PROVIDER_CHAIN3_BASE_URL=https://openrouter.ai/api/v1
70
+ MCP_PROVIDER_CHAIN3_API_KEY=<openrouter-key>
71
+ MCP_PROVIDER_CHAIN3_MODEL=openai/gpt-4o-mini
72
+ ```
73
+
74
+ You can add `MCP_PROVIDER_CHAIN4_*`, `MCP_PROVIDER_CHAIN5_*`, and so on. The provider name is only a label; any OpenAI-compatible endpoint works when `BASE_URL`, `API_KEY`, and `MODEL` are set.
75
+
76
+ On a `429`, `5xx`, timeout, or network error, a provider is put on a short cooldown and the next slot is tried. Tune the window with `MCP_PROVIDER_COOLDOWN_MS` (default `60000`).
77
+
78
+ ## Diagnostics
79
+
80
+ Each server bin supports inspection flags that never start the server:
81
+
82
+ ```bash
83
+ project-memory-mcp --version
84
+ project-memory-mcp --doctor # storage + model/provider config, API keys redacted
85
+ project-memory-mcp --help
86
+ ```
87
+
88
+ `--doctor` reports configured providers and storage paths and shows API keys only as `set (<n> chars)` or `not set`, never the raw value.
89
+
90
+ Example OpenRouter-style config:
91
+
92
+ ```bash
93
+ MCP_LLM_BASE_URL=https://openrouter.ai/api/v1
94
+ MCP_LLM_API_KEY=<your-key>
95
+ MCP_RERANK_MODEL=openai/gpt-4o-mini
96
+ ```
97
+
98
+ Example local-only deterministic config:
99
+
100
+ ```bash
101
+ MCP_DETERMINISTIC_FALLBACK=true
102
+ ```
103
+
104
+ See [privacy and data flow](privacy.md) before using remote providers with sensitive projects.
105
+
106
+ ## Legacy aliases
107
+
108
+ These older names still work for backward compatibility:
109
+
110
+ | Legacy | Preferred |
111
+ |---|---|
112
+ | `LLM_BASE_URL` | `MCP_LLM_BASE_URL` |
113
+ | `LLM_API_KEY` | `MCP_LLM_API_KEY` |
114
+ | `NINEROUTER_URL` | `MCP_LLM_BASE_URL` |
115
+ | `NINEROUTER_KEY` | `MCP_LLM_API_KEY` |
116
+ | `EMBED_MODEL` | `MCP_EMBED_MODEL` |
117
+ | `RERANK_MODEL` | `MCP_RERANK_MODEL` |
118
+ | `EMBED_URL` | `MCP_EMBED_BASE_URL` |
119
+ | `EMBED_KEY` | `MCP_EMBED_API_KEY` |
120
+ | `RERANK_URL` | `MCP_RERANK_BASE_URL` |
121
+ | `RERANK_KEY` | `MCP_RERANK_API_KEY` |
122
+
123
+ Prefer the `MCP_*` names for new installs.
@@ -0,0 +1,39 @@
1
+ # Privacy and Data Flow
2
+
3
+ Dev MCP Suite is local-first. It has no hosted backend, no built-in telemetry, and no account system owned by this project.
4
+
5
+ ## What is stored locally
6
+
7
+ | Server | Local data |
8
+ |---|---|
9
+ | `project-memory` | Markdown notes, keyword index, optional embedding vectors if you run `memory_reindex` with embeddings configured |
10
+ | `devjournal` | Session logs, handoff files, timeline entries |
11
+ | `checkpoint` | Text-file snapshots for rollback |
12
+ | `context-pack` | No persistent project data by default |
13
+
14
+ Default storage paths are under `~/.codex/memories/...`; you can override them with `MEMORY_VAULT_DIR`, `JOURNAL_DIR`, and `CHECKPOINT_DIR`.
15
+
16
+ ## What can leave your machine
17
+
18
+ Nothing leaves your machine by default. `project-memory` and `devjournal` use offline keyword scoring unless you configure an external OpenAI-compatible model endpoint.
19
+
20
+ If you set model environment variables such as `MCP_LLM_BASE_URL`, `MCP_EMBED_BASE_URL`, `MCP_RERANK_BASE_URL`, or numbered provider slots like `MCP_PROVIDER_PRIMARY_BASE_URL`, the related query text and candidate snippets may be sent to that endpoint for embeddings or reranking. The endpoint can be local (Ollama, LM Studio, vLLM, LiteLLM) or remote (Groq, Cerebras, OpenRouter, 9Router, OpenAI-compatible gateways).
21
+
22
+ ## Hard no-network mode
23
+
24
+ Set this when you want deterministic local-only recall even if model keys are present:
25
+
26
+ ```bash
27
+ MCP_DETERMINISTIC_FALLBACK=true
28
+ ```
29
+
30
+ Accepted true values: `true`, `1`, `yes`, `on` (case-insensitive). In this mode:
31
+
32
+ - Embeddings are disabled.
33
+ - LLM reranking is disabled.
34
+ - `memory_reindex` skips embedding generation.
35
+ - Results are labeled `[deterministic]`.
36
+
37
+ ## Recommended provider posture
38
+
39
+ For remote providers, use least-privilege API keys and configure them per MCP client environment. Do not commit API keys to this repository or project repos. Prefer local models for sensitive work; use remote providers only for projects where sending snippets to that provider is acceptable.
@@ -0,0 +1,13 @@
1
+ # Provider smoke matrix
2
+
3
+ _Generated 2026-06-17T01:58:41.412Z_
4
+
5
+ | Provider | Kind | Status | Latency | HTTP | Sample / dim | Error |
6
+ |---|---|---|---|---|---|---|
7
+ | groq | chat | ✓ | 430ms | 200 | `OK` | |
8
+ | cerebras | chat | ✓ | 554ms | 200 | — | |
9
+ | openai | chat | ✗ | 158ms | 401 | — | {"error":{"message":"unauthorized client detected, contact support for assistance at https://discord.com/invite/V6kaP6Rg44"},"message":"UNAUTHENTICATED","success":false,"type":"unauthorized_client_err |
10
+ | openai | embed | ✗ | 147ms | 401 | — | {"error":{"message":"unauthorized client detected, contact support for assistance at https://discord.com/invite/V6kaP6Rg44"},"message":"UNAUTHENTICATED","success":false,"type":"unauthorized_client_err |
11
+ | anthropic | chat | ✓ | 5.83s | 200 | — | |
12
+ | cloudflare | chat | ✗ | 907ms | 400 | — | {"errors":[{"message":"AiError: Bad input: Error: oneOf at '/' not met, 0 matches: required properties at '/' are 'text', required properties at '/' are 'requests' (f3f58c5f-7207-461a-96e1-d809e15ede3 |
13
+ | cloudflare | embed | ✓ | 194ms | 200 | dim=768 | |
@@ -0,0 +1,60 @@
1
+ # Hardening v1.2 Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+ **Goal:** Add CLI UX (help/version/doctor), secret redaction, provider validation, per-provider timeout + 429/5xx cooldown, and a packaged-tarball CI smoke test, without breaking existing behavior.
6
+
7
+ **Architecture:** Add a shared bin meta-handler that intercepts `--help/--version/--doctor` before starting the stdio server. Add redaction + provider diagnostics + cooldown helpers in the provider layer. Wire rerank chat calls through cooldown-aware provider iteration. Extend CI with a tarball install smoke job.
8
+
9
+ **Tech Stack:** Node.js ESM, existing MCP SDK servers, built-in `http`/`https`, offline test harness, GitHub Actions.
10
+
11
+ ---
12
+
13
+ ### Task 1: Bin CLI Meta (help/version/doctor)
14
+
15
+ **Files:**
16
+ - Create: `bin/_meta.mjs`
17
+ - Modify: `bin/project-memory.mjs`, `bin/devjournal.mjs`, `bin/checkpoint.mjs`, `bin/context-pack.mjs`
18
+
19
+ - [ ] Add `handleCliMeta({ bin, title, serverDir })` that handles `-h/--help`, `-v/--version`, `--doctor` then exits; returns false otherwise.
20
+ - [ ] Read version from root `package.json`.
21
+ - [ ] `--doctor` prints storage + model/provider config with API keys redacted (never raw values).
22
+ - [ ] Each bin calls meta first, then imports its server only when not handled.
23
+
24
+ ### Task 2: Redaction + Provider Diagnostics + Cooldown
25
+
26
+ **Files:**
27
+ - Modify: `project-memory/provider-chain.js`, `devjournal/provider-chain.js`
28
+
29
+ - [ ] Add `redactKey(value)` returning `set (<n> chars)` / `not set`, never the value.
30
+ - [ ] Add `providerChainDiagnostics()` listing active providers (redacted) and incomplete-slot issues.
31
+ - [ ] Add pure cooldown helpers `recordOutcome(key, ok, now)` and `isCoolingDown(key, now)` using `MCP_PROVIDER_COOLDOWN_MS` (default 60000).
32
+
33
+ ### Task 3: Cooldown-Aware Rerank
34
+
35
+ **Files:**
36
+ - Modify: `project-memory/rerank.js`, `devjournal/rerank.js`
37
+
38
+ - [ ] Make provider chat return status so 429/5xx/network failures are retryable.
39
+ - [ ] Skip providers currently cooling down; record outcomes.
40
+ - [ ] Stop after first success; fall back to keyword if all fail. Never log keys/bodies.
41
+
42
+ ### Task 4: Tests
43
+
44
+ **Files:**
45
+ - Modify: `project-memory/test.mjs`, `devjournal/test.mjs`
46
+
47
+ - [ ] Test `providerChainDiagnostics()` flags an incomplete slot and redacts keys.
48
+ - [ ] Test cooldown helpers: failure starts cooldown, expiry clears it, success clears it.
49
+ - [ ] Test bin `--version` prints package version and `--doctor` output excludes raw key value.
50
+
51
+ ### Task 5: CI Tarball Smoke + Verify
52
+
53
+ **Files:**
54
+ - Modify: `.github/workflows/ci.yml`
55
+ - Modify: `CHANGELOG.md`, `package.json`, `docs/configuration.md`, `.env.example`
56
+
57
+ - [ ] Add CI job: `npm pack`, install tarball in temp dir, run each bin `--version`.
58
+ - [ ] Document `--doctor` and `MCP_PROVIDER_COOLDOWN_MS`.
59
+ - [ ] Bump version to 1.2.0 and add changelog entry.
60
+ - [ ] Run `npm test` and `npm pack --dry-run`; expect all pass.
@@ -0,0 +1,65 @@
1
+ # Provider Chain v1.1 Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+ **Goal:** Add optional numbered OpenAI-compatible provider fallback for rerank/chat calls while preserving deterministic no-network mode and legacy env compatibility.
6
+
7
+ **Architecture:** Add focused provider-chain helpers to `project-memory` and `devjournal`, then route existing rerank chat calls through those helpers. Provider slots are built from `MCP_PROVIDER_PRIMARY_*`, `MCP_PROVIDER_CHAIN2_*`, `MCP_PROVIDER_CHAIN3_*`, etc.; if absent, existing `MCP_RERANK_*`/`MCP_LLM_*`/legacy config is used.
8
+
9
+ **Tech Stack:** Node.js ESM, existing MCP SDK servers, built-in `http`/`https`, existing offline test harness.
10
+
11
+ ---
12
+
13
+ ### Task 1: Provider Chain Helpers
14
+
15
+ **Files:**
16
+ - Create: `project-memory/provider-chain.js`
17
+ - Create: `devjournal/provider-chain.js`
18
+ - Test: `project-memory/test.mjs`
19
+ - Test: `devjournal/test.mjs`
20
+
21
+ - [ ] Create a `providerEnv(slotPrefix)` helper that reads `NAME`, `BASE_URL`, `API_KEY`, and `MODEL` from a prefix such as `MCP_PROVIDER_PRIMARY`.
22
+ - [ ] Create `providerChainConfig()` returning `{ providers, enabled, deterministic }`.
23
+ - [ ] Include `MCP_PROVIDER_PRIMARY` first when complete.
24
+ - [ ] Include every complete numbered slot matching `MCP_PROVIDER_CHAIN<N>` in numeric order for `N >= 2`.
25
+ - [ ] Fall back to one legacy provider from existing rerank/LLM envs when no numbered slots exist.
26
+ - [ ] Return disabled config if deterministic mode is on.
27
+ - [ ] Add tests for primary-only, primary+chain2+chain3 ordering, arbitrary chain4, incomplete slot skip, deterministic disable, and legacy fallback.
28
+
29
+ ### Task 2: Rerank Uses Provider Chain
30
+
31
+ **Files:**
32
+ - Modify: `project-memory/rerank.js`
33
+ - Modify: `devjournal/rerank.js`
34
+ - Test: existing `npm test`
35
+
36
+ - [ ] Replace single `BASE`/`KEY`/`MODEL` request selection with `providerChainConfig()`.
37
+ - [ ] Try providers in order for each chat request.
38
+ - [ ] Return first valid OpenAI-compatible response.
39
+ - [ ] On non-200, timeout, network error, invalid JSON, or SSE parse failure, try the next provider.
40
+ - [ ] Keep returning `null` if every provider fails so keyword fallback still works.
41
+ - [ ] Never log API keys or response bodies.
42
+
43
+ ### Task 3: Docs and Examples
44
+
45
+ **Files:**
46
+ - Modify: `docs/configuration.md`
47
+ - Modify: `docs/privacy.md`
48
+ - Modify: `.env.example`
49
+ - Modify: `CHANGELOG.md`
50
+ - Modify: `README.md` if needed
51
+
52
+ - [ ] Document numbered provider slots.
53
+ - [ ] Document Groq/Cerebras/OpenRouter as recommended examples, not required providers.
54
+ - [ ] Clarify users can use any OpenAI-compatible base URL, token, and model ID.
55
+ - [ ] Clarify deterministic mode overrides provider chain.
56
+ - [ ] Add changelog entry for v1.1 unreleased.
57
+
58
+ ### Task 4: Verification
59
+
60
+ **Files:**
61
+ - No source changes.
62
+
63
+ - [ ] Run `npm test` and expect 33+ tests all pass.
64
+ - [ ] Run `npm pack --dry-run` and confirm runtime provider-chain helpers are included.
65
+ - [ ] Run secret scan on changed/staged files and confirm no real secrets.
@@ -0,0 +1,41 @@
1
+ # Provider- and Client-Agnostic Config Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+ **Goal:** Make the MCP suite configurable for any OpenAI-compatible gateway and document usage beyond Codex.
6
+
7
+ **Architecture:** Keep backward compatibility with existing `NINEROUTER_*` env vars while introducing neutral `MCP_*` env names. Documentation separates generic install, provider config, and client-specific config examples.
8
+
9
+ **Tech Stack:** Node.js MCP servers, OpenAI-compatible HTTP APIs for embeddings/rerank, Markdown docs.
10
+
11
+ ---
12
+
13
+ ### Task 1: Neutral Provider Env Aliases
14
+
15
+ **Files:**
16
+ - Modify: `project-memory/embedding.js`
17
+ - Modify: `project-memory/rerank.js`
18
+ - Modify: `devjournal/rerank.js`
19
+ - Test: existing `npm test`
20
+
21
+ - [ ] Add `MCP_EMBED_BASE_URL`, `MCP_EMBED_API_KEY`, `MCP_EMBED_MODEL` with fallback to existing `NINEROUTER_URL`, `NINEROUTER_KEY`, `EMBED_MODEL`.
22
+ - [ ] Add `MCP_LLM_BASE_URL`, `MCP_LLM_API_KEY`, `MCP_RERANK_MODEL` with fallback to existing `NINEROUTER_URL`, `NINEROUTER_KEY`, `RERANK_MODEL`.
23
+ - [ ] Keep default disabled behavior when no key/url/model is configured.
24
+ - [ ] Run `npm test` and expect all tests pass.
25
+
26
+ ### Task 2: Client-Agnostic Docs
27
+
28
+ **Files:**
29
+ - Create: `docs/configuration.md`
30
+ - Create: `docs/clients/codex.md`
31
+ - Create: `docs/clients/claude-code.md`
32
+ - Create: `docs/clients/generic-mcp.md`
33
+ - Modify: `.env.example`
34
+ - Modify: `README.md`
35
+
36
+ - [ ] Document neutral env names and legacy aliases.
37
+ - [ ] Provide Codex TOML config using npm bin commands.
38
+ - [ ] Provide Claude Code MCP JSON config using npm bin commands.
39
+ - [ ] Provide generic MCP JSON config.
40
+ - [ ] Update README to call the suite “Dev MCP Suite” while preserving package name.
41
+ - [ ] Run tests again after docs changes.
@@ -0,0 +1,62 @@
1
+ # Trust Release Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+ **Goal:** Implement the approved v1.0.1 trust release: privacy docs, deterministic no-network mode, provider recommendation docs, tests, and publish readiness checks.
6
+
7
+ **Architecture:** Add a tiny shared environment parser for deterministic mode in each server area that needs it, then gate embedding/rerank call paths before any network request is attempted. Documentation explains data flow and optional provider setup without enabling remote calls by default.
8
+
9
+ **Tech Stack:** Node.js MCP servers, Markdown docs, existing offline MCP test harness.
10
+
11
+ ---
12
+
13
+ ### Task 1: Deterministic Mode Code
14
+
15
+ **Files:**
16
+ - Modify: `project-memory/server.js`
17
+ - Modify: `project-memory/embedding.js`
18
+ - Modify: `project-memory/rerank.js`
19
+ - Modify: `devjournal/server.js`
20
+ - Modify: `devjournal/rerank.js`
21
+
22
+ - [ ] Add `deterministicEnabled()` helper that accepts `true`, `1`, `yes`, `on` case-insensitive.
23
+ - [ ] In project-memory, skip embedding and rerank when deterministic is enabled.
24
+ - [ ] In project-memory, label recall results `[deterministic]` when deterministic is enabled.
25
+ - [ ] In project-memory, make reindex report deterministic/no-network instead of attempting embeddings.
26
+ - [ ] In devjournal, skip rerank and label search `[deterministic]` when deterministic is enabled.
27
+
28
+ ### Task 2: Deterministic Tests
29
+
30
+ **Files:**
31
+ - Modify: `project-memory/test.mjs`
32
+ - Modify: `devjournal/test.mjs`
33
+
34
+ - [ ] Add project-memory test proving deterministic mode labels recall `[deterministic]`.
35
+ - [ ] Add project-memory test proving reindex reports deterministic/no-network.
36
+ - [ ] Add devjournal test proving deterministic mode labels search `[deterministic]`.
37
+ - [ ] Add env parsing test for `true`, `1`, `yes`, `on`.
38
+
39
+ ### Task 3: Trust Docs
40
+
41
+ **Files:**
42
+ - Create: `docs/privacy.md`
43
+ - Modify: `docs/configuration.md`
44
+ - Modify: `README.md`
45
+ - Modify: `.env.example`
46
+ - Modify: `CHANGELOG.md`
47
+ - Modify: `package.json`
48
+
49
+ - [ ] Add privacy/data-flow doc.
50
+ - [ ] Add deterministic env docs.
51
+ - [ ] Add Groq/Cerebras/OpenRouter docs-only provider strategy.
52
+ - [ ] Include `docs/privacy.md` in npm package files.
53
+ - [ ] Update changelog with trust-release items.
54
+
55
+ ### Task 4: Verification
56
+
57
+ **Files:**
58
+ - No code files.
59
+
60
+ - [ ] Run `npm test` and expect all tests pass.
61
+ - [ ] Run `npm pack --dry-run` and confirm public docs included, internal plans/specs excluded.
62
+ - [ ] Run secret scan and confirm no real secrets.