@maind-dev/mcp-bridge 0.89.0 → 0.91.0

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/README.md CHANGED
@@ -240,13 +240,19 @@ path and a 2,000-character preview.
240
240
  (`declined_hooks` in the bridge config) and not nagged about;
241
241
  `install --hooks-only` asks again.
242
242
 
243
- ## Codex: conventions via AGENTS.md
243
+ ## AGENTS.md readers: conventions via AGENTS.md
244
244
 
245
245
  Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
246
246
  reach the model as an instruction (0/76), while the maind block in `AGENTS.md`
247
247
  does (74/76). For Codex, `AGENTS.md` is therefore the always-on channel for
248
248
  your project conventions — and the bridge keeps that block current instead of
249
- appending it once and leaving it to age.
249
+ appending it once and leaving it to age. Since **0.91.0** it does so for every
250
+ client that reads `AGENTS.md` per the vendor's own documentation (checked
251
+ 2026-10-04): **Cursor** ("supports AGENTS.md in the project root and
252
+ subdirectories") and **VS Code Copilot** (`chat.useAgentsMdFile`, on by
253
+ default). For both the channel is documented, not yet measured here — we claim
254
+ nothing until it is. Windsurf sessions get the same refresh; whether Windsurf
255
+ (now Devin Desktop) reads `AGENTS.md` is not established here.
250
256
 
251
257
  - **What.** A managed block between `<!-- maind:conventions v1 begin -->` and
252
258
  `<!-- maind:conventions v1 end -->`, placed inside the `## maind MCP
@@ -257,33 +263,42 @@ appending it once and leaving it to age.
257
263
  (`~/.maind/guard/briefing-cache.json`). Capped at 6 000 characters at a line
258
264
  boundary; what does not fit is named: `… (N more via get_conventions)`.
259
265
  - **When.** `install` fills the block as soon as the pairing yields
260
- conventions (own report row `preamble:AGENTS.md#conventions`; `skipped (no
261
- conventions yet)` otherwise; `--dry-run` reads the cache only and reports
262
- `would insert`). Every Codex session start refreshes it: after the MCP
263
- handshake, off the hot path, at most once per 12 hours per project. The
264
- session is recognised as Codex via `MAIND_CLIENT_FAMILY=codex` (the installer
265
- writes it into `~/.codex/config.toml`) or detected from the client's
266
- `initialize` frame. The file is rewritten only when the conventions changed —
267
- a committed `AGENTS.md` does not churn for a date — and Codex has already
268
- loaded `AGENTS.md` when the bridge starts, so a refresh reaches the *next*
269
- session. A refresh prints one stderr line: `maind: AGENTS.md conventions
270
- block refreshed (<n> conventions)`.
266
+ conventions — if the run sets up at least one client the refresh serves
267
+ (Codex, Cursor, Windsurf, Copilot; own report row
268
+ `preamble:AGENTS.md#conventions`, `skipped (no selected client uses
269
+ the AGENTS.md block …)` otherwise; `skipped (no conventions yet)` without conventions;
270
+ `--dry-run` reads the cache only and reports `would insert`). Every session
271
+ start of such a client refreshes it: after the MCP handshake, off the hot
272
+ path, at most once per 12 hours per project. The client is recognised via
273
+ `MAIND_CLIENT_FAMILY` (the installer writes it into each client's config) or
274
+ detected from the client's `initialize` frame. The file is rewritten only
275
+ when the conventions changed — a committed `AGENTS.md` does not churn for a
276
+ date — and the client has usually loaded `AGENTS.md` when the bridge starts,
277
+ so a refresh reaches the *next* session. A refresh prints one stderr line:
278
+ `maind: AGENTS.md conventions block refreshed (<n> conventions)`.
271
279
  - **Only where the bridge installed it, only inside the repository.** The
272
- block goes into the closest `AGENTS.md` between the session's working
280
+ block goes into the closest `AGENTS.md` between the bridge's working
273
281
  directory and the root of its git repository (`git rev-parse
274
282
  --show-toplevel`) that exists *and* carries the `## maind MCP integration`
275
- header. The bridge never walks above the repository root — Codex reads
283
+ header. The bridge never walks above the repository root — the readers take
276
284
  `AGENTS.md` from the repository root down to the working directory, so a
277
285
  parent repository's file above a nested checkout is not this session's file
278
286
  — never creates `AGENTS.md`, and never touches a file without the header.
279
- Outside a git repository nothing is written. `MAIND_DEBUG=1` prints one line
280
- when the repository has no such file. `CLAUDE.md`, `.cursorrules`,
281
- `.windsurfrules` and `copilot-instructions.md` stay as they are — Claude Code
282
- has the hook, and the readers of the others are not measured.
287
+ Outside a git repository nothing is written. Where the bridge runs is the
288
+ MCP client's choice; when its working directory leads to no repository or
289
+ to no such `AGENTS.md`, the bridge asks the client for its workspace folders
290
+ over MCP `roots/list` (only a client that declared the `roots` capability,
291
+ only after its `notifications/initialized`, within 8 seconds) and tries each
292
+ of them (at most 8). The answer never leaves the bridge. `MAIND_DEBUG=1`
293
+ prints one line per skip with its reason. `CLAUDE.md`, `.cursorrules`,
294
+ `.windsurfrules` and `copilot-instructions.md` stay as they are. Claude Code
295
+ is not on the list: it reads `AGENTS.md` only when a repository has no
296
+ `CLAUDE.md` (v2.1.277+), and its channel is the SessionStart hook.
283
297
  - **Opt-out.** `MAIND_NO_AGENTS_MD_REFRESH=1` in the bridge's environment (the
284
- `env` table of the `maind` entry in `~/.codex/config.toml`). To get rid of
285
- the block, set the opt-out and delete the two marker lines with everything
286
- between them; without the opt-out the next refresh re-inserts it.
298
+ `env` of the `maind` entry in the client's MCP config, e.g. the `env` table
299
+ in `~/.codex/config.toml`). To get rid of the block, set the opt-out and
300
+ delete the two marker lines with everything between them; without the
301
+ opt-out the next refresh re-inserts it.
287
302
  - **Measure, don't assume.** `maind sessions scan-conventions --client codex`
288
303
  counts the Codex rollouts in which `=== Project Conventions` arrived as an
289
304
  instruction.
@@ -297,7 +312,7 @@ appending it once and leaving it to age.
297
312
  | `%APPDATA%\maind\device-id` (Windows) | Same, on Windows |
298
313
  | `device-id`-sibling file `api-key` | API key returned by approve flow (mode 0600) |
299
314
  | `~/.maind/state.json` | Hook subcommand state: tracked sessions, queued Tier-3 metrics, synced thresholds (mode 0600) |
300
- | `~/.maind/guard/agents-md-refresh.json` | When the Codex `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
315
+ | `~/.maind/guard/agents-md-refresh.json` | When the `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
301
316
  | `~/.maind/guard/briefing-cache.json` | The last session briefing + conventions, for the session-start hook and the `AGENTS.md` block (12 h; mode 0600) |
302
317
  | `~/.maind/context/<session>/` | Once-per-session markers of the context hooks: one empty file per delivered item, named by a hash; swept after 7 days |
303
318