aienvmp 0.1.51 → 0.1.53

package/BUGFIXES.md

@@ -100,6 +100,18 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: snippets and the Codex skill now use the current status, summary, context, intent, and checkpoint flow with agent-specific actor examples.
 - Verification: regression tests cover snippet output for AGENTS.md, Claude, and Gemini, and summary/status tests cover the read order and dependency protocol.
 
+### AI pointer files were only detected as booleans
+
+- Issue: AI and humans could see that an instruction file existed, but not whether it actually contained the aienvmp pointer.
+- Fix: `agentFiles` now records path, existence, pointer marker state, role, and install command; recommended actions suggest installing a pointer without failing local work.
+- Verification: tests cover sync pointer scanning, recommended action output, and dashboard status labels.
+
+### AI consumers had to inspect the full manifest for pointer state
+
+- Issue: `status`, `context`, and `doctor` did not expose a compact pointer summary even after manifest scanning detected it.
+- Fix: `agentPointers` now appears in status/preflight, context JSON, doctor JSON, and summary markdown.
+- Verification: regression tests cover status, context, doctor, schema, and summary outputs.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.53
+
+- Added `agentPointers` to the shared AI preflight/status contract.
+- Added `agentPointers` to `context --json` at the root for quick AI access.
+- Added `agentPointers` to `doctor --json` without making missing pointers a blocking warning.
+- Added agent pointer status to `.aienvmp/summary.md`.
+- Added `agentPointers` to the stable schema contract metadata.
+- Preserved legacy boolean `agentFiles` compatibility in preflight summaries.
+- Added regression tests for status, context, doctor, schema, and summary pointer outputs.
+
+## 0.1.52
+
+- Expanded `manifest.agentFiles` from booleans to lightweight agent instruction metadata.
+- Detected whether AGENTS.md, CLAUDE.md, and GEMINI.md contain the aienvmp pointer marker.
+- Added install commands and roles to agent instruction metadata.
+- Added a low-priority recommended action when no AI instruction pointer is installed.
+- Updated the dashboard Agent Pointers card to distinguish installed pointers, missing pointers, and missing files.
+- Updated README guidance to mention pointer detection and non-blocking doctor recommendations.
+- Added regression tests for pointer scanning, pointer recommendations, dashboard rendering, and sync output.
+
 ## 0.1.51
 
 - Updated Codex/Claude/Gemini pointer snippets to use the current `status -> summary.md -> context` read order.

package/README.md

@@ -72,6 +72,8 @@ npx aienvmp snippet gemini
 ```
 
 Snippets point each AI to `status`, `summary.md`, `context --json`, intent, and checkpoint without taking over the instruction file.
+`sync` records whether those pointers are installed, and `doctor` can recommend installing one without blocking local work.
+`status`, `context --json`, and `doctor --json` expose the same `agentPointers` summary for AI consumers.
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aienvmp",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "AI-first environment maps and lightweight runtime SBOMs for shared development machines.",
   "type": "module",
   "bin": {

package/src/actions.js

@@ -21,6 +21,7 @@ export function recommendedActions(manifest = {}, context = {}) {
 
   actions.push(...securityActions(manifest.security));
   actions.push(...sbomRiskActions(manifest.lightSbom?.riskSummary));
+  actions.push(...agentPointerActions(manifest.agentFiles));
 
   if (hasRuntimePolicyWarning(warnings)) {
     actions.push(action("review-version-policy", "medium", "runtime", "Detected runtime or package manager policy drift. Prefer project-local version files and ask before global changes."));
@@ -74,6 +75,25 @@ function securityActions(security = {}) {
   )];
 }
 
+function agentPointerActions(agentFiles = {}) {
+  const known = Object.entries(agentFiles || {}).filter(([name]) => ["agents", "claude", "gemini"].includes(name));
+  if (!known.length) return [];
+  if (known.some(([, item]) => hasPointer(item))) return [];
+  const first = known.find(([, item]) => item?.installCommand) || known[0];
+  return [action(
+    "install-agent-pointer",
+    "low",
+    "agent-instructions",
+    "Install an aienvmp pointer in an agent instruction file so future AI agents discover the env map before changing runtimes or dependencies.",
+    first?.[1]?.installCommand || "aienvmp snippet codex --write"
+  )];
+}
+
+function hasPointer(item) {
+  if (typeof item === "boolean") return item;
+  return item?.hasAienvmpPointer === true;
+}
+
 function action(id, priority, category, summary, command = "") {
   return { id, priority, category, summary, command };
 }

package/src/commands/context.js

@@ -27,6 +27,7 @@ export async function contextWorkspace(args) {
       status: warnings.length ? "review-required" : "clear",
       preflight,
       coordination: preflight.coordination,
+      agentPointers: preflight.agentPointers,
       sbomRisk: preflight.sbomRisk,
       followUps: preflight.followUps,
       decision,

package/src/commands/doctor.js

@@ -5,6 +5,7 @@ import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.
 import { loadPolicy, policyWarnings } from "../policy.js";
 import { recommendedActions } from "../actions.js";
 import { enforcementAdvice, strictResult } from "../enforcement.js";
+import { agentPointerSummary } from "../preflight.js";
 
 export { strictResult } from "../enforcement.js";
 
@@ -32,6 +33,7 @@ export async function doctorWorkspace(args) {
       exitBehavior,
       trust: manifest.trust || {},
       policy,
+      agentPointers: agentPointerSummary(manifest.agentFiles),
       openIntentCount: intents.length,
       warnings,
       recommendedActions: actions,

package/src/commands/summary.js

@@ -51,6 +51,7 @@ export function renderSummary(status = {}, manifest = {}) {
   const dependencyProtocol = status.dependencyChangeProtocol || {};
   const dependencyCommands = dependencyProtocol.commands || {};
   const dependencyFiles = dependencyFilesFor(status.dependencyReadSet);
+  const agentPointers = status.agentPointers || {};
 
   return [
     "# aienvmp summary",
@@ -86,6 +87,12 @@ export function renderSummary(status = {}, manifest = {}) {
     `- after: ${dependencyCommands.checkpointAfterChange || "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency"}`,
     `- package manager policy: ${dependencyProtocol.packageManagerPolicy || "not-detected"}`,
     "",
+    "## Agent pointers",
+    "",
+    `- installed: ${toList(agentPointers.installed).join(", ") || "none"}`,
+    `- missing: ${toList(agentPointers.missing).join(", ") || "none"}`,
+    `- next: ${agentPointers.next || "Run aienvmp snippet codex --write if AI agents need instruction-file discovery."}`,
+    "",
     "## Artifacts",
     "",
     "- AIENV.md",

package/src/contract.js

@@ -4,7 +4,7 @@ export function preflightContract() {
     version: 1,
     stability: "additive",
     requiredFields: ["schemaVersion", "state", "decision", "quickstart", "commands", "artifacts"],
-    aiEntryFields: ["state", "summary", "nextAgent", "coordination", "agentActivity", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
+    aiEntryFields: ["state", "summary", "nextAgent", "coordination", "agentActivity", "agentPointers", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
     rule: "Consumers should ignore unknown fields and treat missing optional fields as unavailable."
   };
 }
@@ -28,7 +28,7 @@ export function schemaContract() {
       },
       context: {
         command: "aienvmp context --json",
-        rootFields: ["status", "preflight", "coordination", "decision", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
+        rootFields: ["status", "preflight", "coordination", "agentPointers", "decision", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
       },
       handoff: {
         command: "aienvmp handoff --json",

package/src/manifest.js

@@ -205,11 +205,32 @@ async function scanAgentFiles(dir) {
   };
   const out = {};
   for (const [name, rel] of Object.entries(files)) {
-    out[name] = await exists(path.join(dir, rel));
+    const full = path.join(dir, rel);
+    const fileExists = await exists(full);
+    const content = fileExists ? await fs.readFile(full, "utf8") : "";
+    out[name] = {
+      path: rel,
+      exists: fileExists,
+      hasAienvmpPointer: content.includes("<!-- aienvmp:begin -->") && content.includes("<!-- aienvmp:end -->"),
+      installCommand: snippetCommand(name),
+      role: agentRole(name)
+    };
   }
   return out;
 }
 
+function snippetCommand(name) {
+  if (name === "agents") return "aienvmp snippet codex --write";
+  if (["claude", "gemini"].includes(name)) return `aienvmp snippet ${name} --write`;
+  return "";
+}
+
+function agentRole(name) {
+  if (name === "agents") return "codex";
+  if (["claude", "gemini"].includes(name)) return name;
+  return "external";
+}
+
 function compact(obj) {
   return Object.fromEntries(Object.entries(obj).filter(([, value]) => value));
 }

package/src/preflight.js

@@ -17,6 +17,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
   const followUps = pendingFollowUps(timeline);
   const agentActivity = agentActivitySummary(timeline);
   const sbomRisk = manifest.lightSbom?.riskSummary || {};
+  const agentPointers = agentPointerSummary(manifest.agentFiles);
   return {
     schemaVersion: 1,
     contract: preflightContract(),
@@ -58,6 +59,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     nextAgent: nextAgentHint(state, dependencyReadSet, dependencyChangeProtocol),
     coordination,
     agentActivity,
+    agentPointers,
     sbomRisk,
     followUps,
     intentTargets,
@@ -123,6 +125,59 @@ function agentActivitySummary(timeline = []) {
   };
 }
 
+export function agentPointerSummary(agentFiles = {}) {
+  const entries = Object.entries(agentFiles || {}).filter(([name]) => ["agents", "claude", "gemini"].includes(name));
+  const targets = entries.map(([name, item]) => {
+    const normalized = normalizeAgentFile(item);
+    return {
+      name,
+      role: normalized.role || (name === "agents" ? "codex" : name),
+      file: normalized.path || defaultAgentFile(name),
+      exists: normalized.exists,
+      hasPointer: normalized.hasAienvmpPointer,
+      installCommand: normalized.installCommand || defaultInstallCommand(name)
+    };
+  });
+  const installed = targets.filter((item) => item.hasPointer);
+  const missing = targets.filter((item) => !item.hasPointer);
+  return {
+    installedCount: installed.length,
+    missingCount: missing.length,
+    installed: installed.map((item) => item.role),
+    missing: missing.map((item) => item.role),
+    targets,
+    next: missing.length
+      ? `Install a pointer with ${missing[0].installCommand} if this workspace uses that AI.`
+      : "Agent instruction pointers are installed for detected AI instruction files.",
+    mode: "advisory"
+  };
+}
+
+function normalizeAgentFile(item) {
+  if (typeof item === "boolean") {
+    return { exists: item, hasAienvmpPointer: item };
+  }
+  return {
+    path: item?.path || "",
+    exists: item?.exists === true,
+    hasAienvmpPointer: item?.hasAienvmpPointer === true,
+    installCommand: item?.installCommand || "",
+    role: item?.role || ""
+  };
+}
+
+function defaultAgentFile(name) {
+  if (name === "claude") return "CLAUDE.md";
+  if (name === "gemini") return "GEMINI.md";
+  return "AGENTS.md";
+}
+
+function defaultInstallCommand(name) {
+  if (name === "claude") return "aienvmp snippet claude --write";
+  if (name === "gemini") return "aienvmp snippet gemini --write";
+  return "aienvmp snippet codex --write";
+}
+
 function coordinationSummary(intents = []) {
   const byTarget = new Map();
   for (const intent of intents) {

package/src/render.js

@@ -445,7 +445,11 @@ const securityHtml=sec.enabled?\`<table><tr><th>Total</th><td><code>\${esc(secSu
 const change=c=>c.type==='changed'?\`\${c.scope} \${c.key}: \${c.before} -> \${c.after}\`:\`\${c.scope} \${c.key}: \${c.type} \${c.after||c.before}\`;
 const timelineLabel=t=>t.change?change(t.change):(t.summary||t.action||t.type||'recorded change');
 const agentNames={agents:'Codex',claude:'Claude',gemini:'Gemini'};
-const agentCards=Object.entries(agentNames).map(([key,label])=>\`<div class="agent"><strong>\${label}</strong><span>\${manifest.agentFiles?.[key]?'instruction file detected':'not detected'}</span></div>\`).join('');
+const agentInfo=v=>typeof v==='object'&&v? v : {exists:!!v,hasAienvmpPointer:!!v,path:''};
+const agentHasPointer=v=>agentInfo(v).hasAienvmpPointer===true;
+const agentStatus=v=>agentHasPointer(v)?'aienvmp pointer installed':(agentInfo(v).exists?'file detected, pointer missing':'not detected');
+const agentCards=Object.entries(agentNames).map(([key,label])=>\`<div class="agent"><strong>\${label}</strong><span>\${esc(agentStatus(manifest.agentFiles?.[key]))}</span>\${agentInfo(manifest.agentFiles?.[key]).installCommand?\`<span class="path">\${esc(agentInfo(manifest.agentFiles?.[key]).installCommand)}</span>\`:''}</div>\`).join('');
+const agentPointerCount=entries(manifest.agentFiles).filter(([,v])=>agentHasPointer(v)).length;
 const warnHtml=warnings.length?'<div class="warnings">'+warnings.map(w=>\`<div class="warning">\${esc(w.message)}</div>\`).join('')+'</div>':'<div class="okline">No blocking environment warnings detected.</div>';
 const timelineHtml=timeline.length?'<div class="timeline">'+timeline.slice(-8).reverse().map(t=>\`<div class="event"><time>\${esc(t.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(t.actor||'system')}</b> \${esc(timelineLabel(t))}</div></div>\`).join('')+'</div>':'<div class="okline">No previous environment changes recorded.</div>';
 const intentsHtml=intents.length?'<div class="timeline">'+intents.slice(-6).reverse().map(i=>\`<div class="event"><time>\${esc(i.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(i.actor)}</b> plans \${esc(i.action)}</div></div>\`).join('')+'</div>':'<div class="okline">No pending agent intents recorded.</div>';
@@ -561,7 +565,7 @@ document.getElementById('app').innerHTML=\`
     <div style="height:14px"></div>
     \${card('AI Handoff',reviewRequired?'<span class="pill warn">review</span>':'<span class="pill">ready</span>',handoffHtml)}
     <div style="height:14px"></div>
-    \${card('Agent Pointers','<span class="pill">'+entries(manifest.agentFiles).filter(([,v])=>v).length+' detected</span>','<div class="agents">'+agentCards+'</div>')}
+    \${card('Agent Pointers','<span class="pill">'+agentPointerCount+' installed</span>','<div class="agents">'+agentCards+'</div>')}
     <div style="height:14px"></div>
     \${card('Snapshot','',\`<table><tr><th>OS</th><td>\${esc(manifest.os.platform)} \${esc(manifest.os.release)} \${esc(manifest.os.arch)}</td></tr><tr><th>Shell</th><td>\${esc(manifest.os.shell||'unknown')}</td></tr><tr><th>Workspace</th><td><div class="path">\${esc(manifest.workspace.path)}</div></td></tr></table>\`)}
   </aside>