dotmd-cli 0.75.0 → 0.76.1

package/bin/dotmd.mjs

@@ -1594,6 +1594,18 @@ async function main() {
     throw err;
   }
   _resolvedConfig = config;
+  // The one place that reaches an OpenCode session running without the
+  // integration — whatever verb it reaches for first. stderr, so `--json`
+  // consumers are untouched, and once per session so it informs rather than
+  // nags. `install`/`doctor`/`update` are skipped: they report this themselves,
+  // and telling `dotmd install opencode` to run `dotmd install opencode` is
+  // noise.
+  if (!['install', 'doctor', 'update', 'hud', 'guard'].includes(command)) {
+    const { degradedIdentityNotice } = await import('../src/host-integration.mjs');
+    const notice = degradedIdentityNotice(config?.repoRoot, { version: pkg.version });
+    if (notice) process.stderr.write(`${notice}\n`);
+  }
+
   const suppressSideEffects = effectiveDryRun || command === 'hud' || passiveMachineContext;
   Object.defineProperty(config, '_execution', {
     value: { dryRun, passive: command === 'hud' || passiveMachineContext, suppressSideEffects, gitStaleness },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.75.0",
+  "version": "0.76.1",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/host-integration.mjs

@@ -16,6 +16,7 @@
 // reports that the integration is missing and names the command; it never
 // installs. Passive commands touch nothing.
 
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -166,6 +167,59 @@ export function describeSessionIdentity(opts = {}) {
   };
 }
 
+// --- Telling the session it is running degraded -----------------------------
+//
+// Every other surface here has to be sought out: `doctor`, `install`, the npm
+// postinstall line. But the degraded mode is SILENT — with the OPENCODE_PID
+// fallback in place, `use`/`set`/`baton` all work, they just share one identity
+// across every session in the OpenCode process. Nobody goes looking for a
+// diagnostic about a thing that appears to work, so this comes to them.
+//
+// Warning, not error. Failing closed would undo the fallback that unblocked
+// OpenCode in the first place, and punish a setup that is working.
+//
+// Once per session per repo, via a marker under the gitignored .dotmd/. Silent
+// under DOTMD_NO_HINTS=1, the switch the repeat-failure hints already use.
+const NOTICE_DIR = 'notices';
+
+function noticeMarkerPath(repoRoot, key) {
+  const digest = createHash('sha256').update(key).digest('hex').slice(0, 32);
+  return path.join(path.resolve(repoRoot), '.dotmd', NOTICE_DIR, `${digest}`);
+}
+
+// Returns the notice text the first time it applies in a session, then null.
+// `record: false` answers without consuming the once-per-session budget.
+export function degradedIdentityNotice(repoRoot, opts = {}) {
+  const { env = process.env, homedir = os.homedir(), version, record = true } = opts;
+  if (env.DOTMD_NO_HINTS === '1') return null;
+  // Cheap env check first: a user on any other host pays nothing for this.
+  if (!env.OPENCODE && !env.OPENCODE_PID) return null;
+
+  const identity = describeSessionIdentity({ env, homedir, version });
+  if (identity.scope === 'session') return null;
+
+  const installed = opencodeStatus({ env, homedir, version }).exists;
+  const lines = installed
+    ? ['[dotmd] This OpenCode session started before the dotmd integration loaded, so its plan',
+      '        ownership is still process-scoped. Restart OpenCode to pick it up.']
+    : ['[dotmd] OpenCode detected, dotmd integration not installed — plan ownership is scoped to',
+      '        the OpenCode process, so another session in it can release plans this one claimed,',
+      '        and no session-start briefing runs. Fix once: dotmd install opencode'];
+
+  if (!record) return lines.join('\n');
+  if (!repoRoot) return lines.join('\n');
+  const marker = noticeMarkerPath(repoRoot, `opencode:${identity.id}:${installed ? 'restart' : 'install'}`);
+  if (existsSync(marker)) return null;
+  try {
+    mkdirSync(path.dirname(marker), { recursive: true });
+    writeFileSync(marker, '', 'utf8');
+  } catch {
+    // Unwritable .dotmd: say it once anyway rather than stay silent about a
+    // real ownership weakness. Worst case it repeats.
+  }
+  return lines.join('\n');
+}
+
 // --- Claude Code -----------------------------------------------------------
 //
 // Claude Code has a real plugin registry, so dotmd drives `claude plugin`

package/src/new.mjs

@@ -101,7 +101,16 @@ const BUILTIN_TEMPLATES = {
       'related_plans:',
       'related_docs:',
     ].join('\n'),
-    body: (t, ctx) => `
+    body: (t, ctx) => {
+      // Same full-body shortcut the plan templates use, and for the same
+      // reason: a body that already authors `## Section` headings is a complete
+      // document, not section-content for one slot. Nesting it under `## Overview`
+      // produced a second `# Title` under the scaffold's, a placeholder summary
+      // line above the author's own opening, and the skeleton's trailing
+      // sections after a document that had already ended.
+      const authored = fullBodyShortcut(t, ctx?.bodyInput);
+      if (authored !== null) return authored;
+      return `
 # ${t}
 
 > One-line summary of what this doc covers.
@@ -116,7 +125,8 @@ ${ctx?.bodyInput?.trim() ?? ''}
 
 ## Related Documentation
 
-`,
+`;
+    },
   },
   plan: {
     description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',