open-memex 0.6.0-alpha.4 → 0.6.0-alpha.5

package/AGENTS.md

@@ -66,6 +66,10 @@ previews keyword capture without writing, `open-memex doctor` runs health checks
 (`--yes` skips, scripts never prompt); `open-memex config set <key> <value>` edits settings after install.
 `npm install -g` prints a pointer to `open-memex init` via a postinstall script
 (print-only — postinstall must never prompt, it runs in CI/Docker; D50).
+Note: npm swallows lifecycle-script stdout (background run unless
+`--foreground-scripts`), so the postinstall pointer is best-effort only —
+every CLI entry point also prints a one-line stderr nudge until init has run
+or been declined (F28; stderr keeps the MCP stdio protocol intact).
 Bare `open-memex` on a machine where init never completed offers to run it on a
 TTY (usage as before when non-interactive); init/uninstall maintain a
 `.init.json` first-run marker at the data root so the offer is asked once (D50);

package/dist/cli.js

@@ -526,6 +526,20 @@ async function main() {
         console.log(`open-memex ${pkg.version}`);
         return;
     }
+    // F28: npm runs lifecycle scripts in the background and swallows their
+    // stdout (unless --foreground-scripts), so the D50 postinstall pointer
+    // never reaches the user. Every CLI entry point therefore carries a
+    // one-line nudge on stderr until init has run or been declined — stderr
+    // keeps the MCP stdio protocol (stdout) intact, and the .init.json marker
+    // makes it once-ever. `init`/`uninstall` are excluded (already there /
+    // nothing to wire).
+    if (cmd !== "init" && cmd !== "uninstall") {
+        const { isFirstRun } = await import("./first-run.js");
+        if (isFirstRun()) {
+            console.error("open-memex: first run? `open-memex init` wires it into your editors " +
+                "(auto-detects VS Code, Cursor, opencode).");
+        }
+    }
     // Per-command help: `open-memex <command> --help`. Checked before loadConfig()
     // so it works even when the environment is broken.
     if (rest.includes("--help") || rest.includes("-h")) {

package/docs/V2-DESIGN.md

@@ -554,7 +554,9 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   (D52): rewrite both agent-facing prompts (MCP handshake + init template) so
   agents execute them correctly. Push-not-poll outbox (D53): the checkpoint
   mechanism is retired — the server reports the outbox draft count at session
-  start and appends it to mutating tool results when non-zero.
+  start and appends it to mutating tool results when non-zero. Install→init
+  reminder fix (F28): one-line stderr nudge on every CLI entry point until
+  init runs (npm swallows postinstall stdout).
 - **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
   sharing needs, fine-grained ACL, audit/compliance mandates · optional API-backed exporters/providers
   for enterprise knowledge systems.
@@ -1057,6 +1059,20 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   `memory_submit` drains the outbox, so its own note is naturally silent.
   Approved 2026-10-01.*
 
+- **F28** — install→init reminder was invisible (0.6.0-alpha.5). The D50
+  postinstall pointer never reaches the user: npm runs lifecycle scripts in
+  the background and swallows their stdout unless `--foreground-scripts` is
+  passed (reproduced on npm 10.9.4 — the script ran with code 0, its output
+  never displayed). The install-time channel is therefore best-effort only.
+  Fix: every CLI entry point now prints a one-line nudge on stderr until init
+  has run or been declined (`open-memex init` wires editors), gated by the
+  existing `.init.json` first-run marker — stderr keeps the MCP stdio protocol
+  (stdout) intact, so even `open-memex mcp` spawned by an editor carries it
+  safely. `init`/`uninstall` are excluded. The bare-`open-memex` interactive
+  offer on a TTY (D50) is unchanged. *Rationale: the reminder must live in a
+  channel the project controls — the CLI — not in npm script output.
+  Reported 2026-10-01.*
+
 ## Open Questions
 
 _All resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull)._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.6.0-alpha.4",
+  "version": "0.6.0-alpha.5",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",

package/src/cli.ts

@@ -588,6 +588,23 @@ async function main() {
     return;
   }
 
+  // F28: npm runs lifecycle scripts in the background and swallows their
+  // stdout (unless --foreground-scripts), so the D50 postinstall pointer
+  // never reaches the user. Every CLI entry point therefore carries a
+  // one-line nudge on stderr until init has run or been declined — stderr
+  // keeps the MCP stdio protocol (stdout) intact, and the .init.json marker
+  // makes it once-ever. `init`/`uninstall` are excluded (already there /
+  // nothing to wire).
+  if (cmd !== "init" && cmd !== "uninstall") {
+    const { isFirstRun } = await import("./first-run.ts");
+    if (isFirstRun()) {
+      console.error(
+        "open-memex: first run? `open-memex init` wires it into your editors " +
+          "(auto-detects VS Code, Cursor, opencode).",
+      );
+    }
+  }
+
   // Per-command help: `open-memex <command> --help`. Checked before loadConfig()
   // so it works even when the environment is broken.
   if (rest.includes("--help") || rest.includes("-h")) {