aienvmp 0.1.36 → 0.1.38

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.38
+
+- Added a 10-second AI quickstart flow to the shared preflight contract and status output.
+- Added preflight intent target recommendations so agents can record runtime, package manager, dependency, Docker, or coordination changes consistently.
+- Surfaced AI intent target recommendations in the dashboard so humans can review the same target guidance.
+- Added the same quickstart and intent target guidance to `AIENV.md` so Markdown-first agents receive the current preflight.
+- Aligned AGENTS/Claude/Gemini pointer snippets with the same status-first, target-aware AI flow.
+
+## 0.1.37
+
+- Added `lightSbom` to the manifest as an AI-ready package and vulnerability summary.
+- Linked dependency manifests, ecosystem/group counts, vulnerable direct dependencies, and top risk packages into one compact SBOM view.
+- Surfaced dependency change hints in AI-facing outputs and the dashboard so agents and humans can identify relevant manifests before edits.
+- Added read-only lockfile awareness to dependency snapshots and light SBOM hints.
+- Added package manager policy hints from lockfiles to reduce accidental npm/pnpm/yarn drift.
+
 ## 0.1.36
 
 - Added an explicit enforcement profile to the shared AI preflight contract.

package/README.md

@@ -10,7 +10,7 @@
 
 It helps Codex, Claude, Gemini, and humans avoid silent Node, Python, package manager, dependency, Docker, and security drift.
 
-Core loop: scan once, link runtime/dependency/security context, give AI a shared decision contract with advisory priorities, and hand off safe next steps.
+Core loop: scan once, link runtime/dependency/security context, give AI a shared decision contract with a light SBOM summary, and hand off safe next steps.
 
 ## Quick Start
 
@@ -22,6 +22,8 @@ npx aienvmp plan
 npx aienvmp handoff
 ```
 
+10-second AI flow: `aienvmp status --write` -> `aienvmp context --json` -> intent before environment changes.
+
 Optional deeper read-only checks:
 
 ```bash
@@ -53,9 +55,13 @@ AIENV.md
 .aienvmp/dashboard.html     # includes dependencies, plan, remediation, and environment cards
 ```
 
+`AIENV.md` includes the 10-second AI flow and recommended intent targets for Markdown-first agents.
+
 Trust states are machine-readable: `observed`, `planned`, `changed`, `review`, `verified`, `stale`.
 `status.json` also lists AI read order, artifact paths, and safe commands.
 `status`, `context`, `plan`, and `handoff` share the same AI preflight contract.
+Preflight also recommends the intent target, so agents do not guess between runtime, package manager, dependency, Docker, or coordination changes.
+The dashboard shows the same intent target guidance for human review.
 
 AI agents can observe, plan, and record. Only a human or CI should mark environment facts as verified.
 
@@ -108,6 +114,11 @@ aienvmp doctor --strict security  # fail only scoped warnings
 - dashboard and preflight explain advisory default vs optional strict mode
 - non-blocking unless strict mode is explicitly requested
 - security checks are opt-in and read-only
+- light SBOM is generated from project files and optional scanner summaries
+- dependency change hints point AI agents to the relevant manifest before edits
+- lockfiles are detected read-only and shown before dependency edits
+- package manager policy is inferred from lockfiles to avoid accidental npm/pnpm/yarn drift
+- dashboard mirrors AI-facing SBOM hints so humans can review the same dependency context
 
 ## Development
 

package/package.json

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

package/src/commands/compile.js

@@ -5,6 +5,7 @@ import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { aiEnvPath, intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { renderAIEnv } from "../render.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
+import { buildPreflight } from "../preflight.js";
 
 export async function compileWorkspace(args) {
   const dir = workspaceDir(args);
@@ -14,7 +15,10 @@ export async function compileWorkspace(args) {
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
-  const rendered = renderAIEnv(manifest, timeline, warnings, intents, policy);
+  const rendered = renderAIEnv({
+    ...manifest,
+    preflight: buildPreflight(manifest, warnings, intents)
+  }, timeline, warnings, intents, policy);
   await fs.writeFile(aiEnvPath(dir), rendered, "utf8");
   if (!args.quiet) {
     console.log(`compiled ${aiEnvPath(dir)}`);

package/src/commands/context.js

@@ -38,6 +38,7 @@ export async function contextWorkspace(args) {
       containers: manifest.containers,
       inventory: inventorySummary(manifest.inventory),
       dependencySnapshot: dependencySummary(manifest.dependencySnapshot),
+      lightSbom: lightSbomSummary(manifest.lightSbom),
       security: securitySummary(manifest.security),
       projectHints: manifest.projectHints,
       warnings,
@@ -51,6 +52,31 @@ export async function contextWorkspace(args) {
   console.log(renderContext(manifest, timeline, warnings, intents, policy, actions));
 }
 
+function lightSbomSummary(lightSbom = {}) {
+  return {
+    mode: lightSbom.mode || "light-sbom",
+    summary: lightSbom.summary || {
+      ecosystems: {},
+      managers: {},
+      groups: {},
+      manifests: [],
+      lockfiles: [],
+      packages: 0,
+      vulnerabilities: 0,
+      directVulnerablePackages: 0,
+      transitiveOrUnmatchedVulnerablePackages: 0
+    },
+    topRisk: (lightSbom.topRisk || []).slice(0, 8),
+    packageManagerPolicy: lightSbom.packageManagerPolicy || {
+      status: "no-lockfile",
+      ecosystems: {},
+      guidance: "No lockfile policy detected."
+    },
+    dependencyChangeHints: (lightSbom.dependencyChangeHints || []).slice(0, 8),
+    aiUse: lightSbom.aiUse || {}
+  };
+}
+
 function dependencySummary(snapshot = {}) {
   return {
     mode: snapshot.mode || "snapshot",

package/src/commands/status.js

@@ -23,6 +23,8 @@ export async function statusWorkspace(args) {
   } else if (!args.quiet) {
     console.log(`${output.state}: ${output.summary}`);
     console.log(`next: ${output.nextCommand}`);
+    console.log(`ai: ${output.quickstart.readFirst} -> ${output.quickstart.detailCommand}`);
+    console.log(`intent: ${output.intentTargets[0]?.command || output.commands.recordIntent}`);
     console.log(`strict: ${output.enforcement.recommendedCommand}`);
     if (artifact) console.log(`status: ${artifact}`);
   }

package/src/dependencies.js

@@ -3,20 +3,33 @@ import path from "node:path";
 import { exists, readJson } from "./fsutil.js";
 
 const NODE_GROUPS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+const LOCKFILE_CANDIDATES = [
+  { file: "package-lock.json", ecosystem: "npm", manager: "npm" },
+  { file: "npm-shrinkwrap.json", ecosystem: "npm", manager: "npm" },
+  { file: "pnpm-lock.yaml", ecosystem: "npm", manager: "pnpm" },
+  { file: "yarn.lock", ecosystem: "npm", manager: "yarn" },
+  { file: "bun.lockb", ecosystem: "npm", manager: "bun" },
+  { file: "uv.lock", ecosystem: "python", manager: "uv" },
+  { file: "poetry.lock", ecosystem: "python", manager: "poetry" },
+  { file: "Pipfile.lock", ecosystem: "python", manager: "pipenv" }
+];
 
 export async function scanDependencySnapshot(dir) {
   const node = await scanNodeDependencies(dir);
   const python = await scanPythonDependencies(dir);
   const packages = [...node.packages, ...python.packages];
   const manifests = [...node.manifests, ...python.manifests];
+  const lockfiles = await scanDependencyLockfiles(dir);
   return {
     mode: "snapshot",
     enabled: true,
     note: "Read-only dependency snapshot from project files. It does not install, update, or resolve packages.",
     manifests,
+    lockfiles,
     summary: {
       ecosystems: [...new Set(packages.map((pkg) => pkg.ecosystem))],
       manifests: manifests.length,
+      lockfiles: lockfiles.length,
       packages: packages.length
     },
     packages: packages.slice(0, 80)
@@ -45,6 +58,144 @@ export function linkVulnerableDependencies(security = {}, snapshot = {}) {
   };
 }
 
+export function buildLightSbom(snapshot = {}, security = {}) {
+  const packages = snapshot.packages || [];
+  const vulnerable = security.topPackages || [];
+  const directVulnerable = vulnerable.filter((pkg) => pkg.directDependency === true);
+  const transitiveOrUnmatched = vulnerable.filter((pkg) => pkg.directDependency !== true);
+  const topRisk = vulnerable.slice(0, 8).map((pkg) => ({
+    name: pkg.name,
+    ecosystem: scannerEcosystem(pkg.scanner),
+    severity: pkg.severity || "unknown",
+    directDependency: pkg.directDependency === true,
+    manifest: pkg.dependency?.manifest || "",
+    version: pkg.dependency?.version || pkg.version || "",
+    priority: pkg.remediationPriority?.level || "low",
+    score: pkg.remediationPriority?.score || 0,
+    fixAvailable: pkg.fixAvailable === true || Boolean(pkg.fixVersions?.length),
+    fixVersions: (pkg.fixVersions || []).slice(0, 3)
+  }));
+  return {
+    schemaVersion: 1,
+    mode: "light-sbom",
+    note: "AI-ready package and vulnerability summary from read-only project files and optional scanners.",
+    summary: {
+      ecosystems: countBy(packages, "ecosystem"),
+      managers: countBy(packages, "manager"),
+      groups: countBy(packages, "group"),
+      manifests: snapshot.manifests || [],
+      lockfiles: snapshot.lockfiles || [],
+      packages: packages.length,
+      vulnerabilities: Number(security.summary?.total || 0),
+      directVulnerablePackages: directVulnerable.length,
+      transitiveOrUnmatchedVulnerablePackages: transitiveOrUnmatched.length
+    },
+    topRisk,
+    packageManagerPolicy: packageManagerPolicy(snapshot.lockfiles || []),
+    dependencyChangeHints: dependencyChangeHints(packages, topRisk, snapshot.lockfiles || []),
+    aiUse: {
+      beforeDependencyChanges: "Read lightSbom.summary and lightSbom.topRisk before changing dependencies.",
+      securityMode: security.enabled ? "scanner-summary" : "scanner-off",
+      dependencySource: "project manifests only; no install or resolver is run"
+    }
+  };
+}
+
+function packageManagerPolicy(lockfiles = []) {
+  const byEcosystem = {};
+  for (const lockfile of lockfiles) {
+    const ecosystem = lockfile.ecosystem || "unknown";
+    const managers = byEcosystem[ecosystem]?.managers || new Set();
+    managers.add(lockfile.manager || "unknown");
+    byEcosystem[ecosystem] = {
+      ecosystem,
+      managers,
+      lockfiles: [...(byEcosystem[ecosystem]?.lockfiles || []), lockfile.file]
+    };
+  }
+  const ecosystems = Object.fromEntries(Object.entries(byEcosystem).map(([name, value]) => {
+    const managers = [...value.managers].sort();
+    return [name, {
+      managers,
+      lockfiles: value.lockfiles.sort(),
+      status: managers.length > 1 ? "mixed-lockfiles" : "single-manager",
+      recommendedManager: managers[0] || "not-detected",
+      guidance: managers.length > 1
+        ? "Review with the user before dependency changes; multiple package manager lockfiles are present."
+        : "Use the detected package manager for dependency changes unless the user says otherwise."
+    }];
+  }));
+  return {
+    status: Object.keys(ecosystems).length === 0
+      ? "no-lockfile"
+      : Object.values(ecosystems).some((item) => item.status === "mixed-lockfiles") ? "review-required" : "clear",
+    ecosystems,
+    guidance: Object.keys(ecosystems).length === 0
+      ? "No lockfile detected; avoid creating one with an unexpected package manager without user approval."
+      : "Preserve existing lockfile and package manager choices during dependency changes."
+  };
+}
+
+function dependencyChangeHints(packages = [], topRisk = [], lockfiles = []) {
+  const byManifest = new Map();
+  for (const pkg of packages) {
+    const key = pkg.manifest || "unknown";
+    const entry = byManifest.get(key) || {
+      manifest: key,
+      ecosystem: pkg.ecosystem || "unknown",
+      manager: pkg.manager || "unknown",
+      groups: new Set(),
+      packages: 0,
+      riskPackages: []
+    };
+    entry.groups.add(pkg.group || "unknown");
+    entry.packages += 1;
+    byManifest.set(key, entry);
+  }
+  for (const risk of topRisk) {
+    if (!risk.manifest || !byManifest.has(risk.manifest)) continue;
+    byManifest.get(risk.manifest).riskPackages.push({
+      name: risk.name,
+      severity: risk.severity,
+      priority: risk.priority,
+      fixAvailable: risk.fixAvailable
+    });
+  }
+  return [...byManifest.values()].map((entry) => ({
+    manifest: entry.manifest,
+    ecosystem: entry.ecosystem,
+    manager: entry.manager,
+    groups: [...entry.groups].sort(),
+    packages: entry.packages,
+    riskPackages: entry.riskPackages.slice(0, 5),
+    lockfiles: lockfilesForEntry(entry, lockfiles),
+    beforeChange: [
+      `Read ${entry.manifest} and the active package manager policy before editing dependencies.`,
+      lockfilesForEntry(entry, lockfiles).length
+        ? `Preserve related lockfiles: ${lockfilesForEntry(entry, lockfiles).map((item) => item.file).join(", ")}.`
+        : "No related lockfile was detected; do not create one with a different package manager without approval.",
+      "Record an intent before dependency or lockfile changes when another AI may be working."
+    ],
+    afterChange: [
+      "Run project tests or the narrowest relevant validation.",
+      "Run aienvmp sync.",
+      "Record the dependency change with aienvmp record."
+    ]
+  }));
+}
+
+async function scanDependencyLockfiles(dir) {
+  const found = [];
+  for (const item of LOCKFILE_CANDIDATES) {
+    if (await exists(path.join(dir, item.file))) found.push(item);
+  }
+  return found;
+}
+
+function lockfilesForEntry(entry, lockfiles = []) {
+  return lockfiles.filter((lockfile) => lockfile.ecosystem === entry.ecosystem);
+}
+
 export function remediationPriority(pkg = {}, context = {}) {
   const severityScore = { critical: 90, high: 70, moderate: 45, low: 20, info: 5, unknown: 30 };
   const severity = String(pkg.severity || "unknown").toLowerCase();
@@ -66,6 +217,14 @@ export function remediationPriority(pkg = {}, context = {}) {
   return { level, score, reasons };
 }
 
+function countBy(items = [], key) {
+  return Object.fromEntries(Object.entries(items.reduce((acc, item) => {
+    const value = item[key] || "unknown";
+    acc[value] = (acc[value] || 0) + 1;
+    return acc;
+  }, {})).sort(([a], [b]) => a.localeCompare(b)));
+}
+
 async function scanNodeDependencies(dir) {
   const file = path.join(dir, "package.json");
   if (!(await exists(file))) return { manifests: [], packages: [] };

package/src/manifest.js

@@ -6,12 +6,13 @@ import { exists } from "./fsutil.js";
 import { observedTrust } from "./trust.js";
 import { scanGlobalInventory } from "./inventory.js";
 import { scanSecurity } from "./security.js";
-import { linkVulnerableDependencies, scanDependencySnapshot } from "./dependencies.js";
+import { buildLightSbom, linkVulnerableDependencies, scanDependencySnapshot } from "./dependencies.js";
 
 export async function buildManifest(dir, options = {}) {
   const now = new Date().toISOString();
   const dependencySnapshot = await scanDependencySnapshot(dir);
   const security = linkVulnerableDependencies(await scanSecurity(dir, { security: options.security }), dependencySnapshot);
+  const lightSbom = buildLightSbom(dependencySnapshot, security);
   const manifest = {
     schemaName: "aienvmp.runtime-sbom",
     schemaVersion: 1,
@@ -31,6 +32,7 @@ export async function buildManifest(dir, options = {}) {
     containers: await scanContainers(),
     projectHints: await scanProjectHints(dir),
     dependencySnapshot,
+    lightSbom,
     inventory: await scanGlobalInventory({ deep: options.deep }),
     security,
     agentFiles: await scanAgentFiles(dir),

package/src/preflight.js

@@ -8,6 +8,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = []) {
   const actions = recommendedActions(manifest, { warnings, intents });
   const state = decision.reviewRequired ? "review-required" : "clear";
   const topAction = actions[0] || null;
+  const intentTargets = recommendedIntentTargets(manifest, warnings, intents);
   return {
     schemaVersion: 1,
     state,
@@ -43,6 +44,8 @@ export function buildPreflight(manifest = {}, warnings = [], intents = []) {
       projectLocalWork: decision.canContinueProjectLocalWork ? "allowed" : "review-first",
       environmentChanges: decision.canChangeEnvironmentWithoutReview ? "allowed" : "intent-and-review-first"
     },
+    quickstart: agentQuickstart(decision.reviewRequired),
+    intentTargets,
     artifacts: preflightArtifacts(),
     readOrder: [
       ".aienvmp/status.json",
@@ -58,13 +61,94 @@ export function buildPreflight(manifest = {}, warnings = [], intents = []) {
       context: "aienvmp context --json",
       plan: "aienvmp plan --write",
       handoff: "aienvmp handoff --record --actor agent:id",
-      recordIntent: "aienvmp intent --actor agent:id --action planned-change"
+      recordIntent: intentTargets[0]?.command || "aienvmp intent --actor agent:id --action planned-change"
     },
     topAction,
     nextCommand: topAction?.command || decision.nextCommand
   };
 }
 
+function recommendedIntentTargets(manifest = {}, warnings = [], intents = []) {
+  const targets = [];
+  for (const warning of warnings) {
+    addTarget(targets, targetFromWarning(warning), warning.message || warning.code, warning.code);
+  }
+  for (const intent of intents) {
+    addTarget(targets, intent.target || targetFromText(intent.action), `Open intent from ${intent.actor || "unknown"}.`, "open-intent");
+  }
+  const pmPolicy = manifest.lightSbom?.packageManagerPolicy;
+  if (pmPolicy?.status === "review-required") {
+    addTarget(targets, "package-manager", pmPolicy.guidance, "package-manager-policy");
+  }
+  if (Number(manifest.security?.summary?.total || 0) > 0) {
+    addTarget(targets, "dependency", "Security findings are dependency-related; record dependency intent before remediation.", "security");
+  }
+  if (Number(manifest.dependencySnapshot?.summary?.packages || 0) > 0) {
+    addTarget(targets, "dependency", "Dependency manifests detected; use this target before package changes.", "dependency-snapshot");
+  }
+  if (!targets.length) {
+    addTarget(targets, "environment", "Default target when the change affects runtime, dependency, container, or global tool state.", "default");
+  }
+  return targets.slice(0, 5).map((item) => ({
+    ...item,
+    command: `aienvmp intent --actor agent:id --action planned-change --target ${item.target}`
+  }));
+}
+
+function addTarget(targets, target, reason, source) {
+  const normalized = normalizeTarget(target);
+  if (!normalized) return;
+  const existing = targets.find((item) => item.target === normalized);
+  if (existing) {
+    if (source && !existing.sources.includes(source)) existing.sources.push(source);
+    return;
+  }
+  targets.push({ target: normalized, reason: reason || "Environment change target.", sources: source ? [source] : [] });
+}
+
+function targetFromWarning(warning = {}) {
+  if (warning.target) return warning.target;
+  const code = warning.code || "";
+  if (code.includes("node")) return "node";
+  if (code.includes("python")) return "python";
+  if (code.includes("docker")) return "docker";
+  if (code.includes("lockfile") || code.includes("package-manager")) return "package-manager";
+  if (code.includes("security")) return "dependency";
+  if (code.includes("intent") || code.includes("handoff")) return "coordination";
+  return targetFromText(`${warning.message || ""} ${code}`);
+}
+
+function targetFromText(text = "") {
+  const normalized = String(text).toLowerCase();
+  for (const target of ["node", "python", "docker", "package-manager", "dependency", "npm", "pnpm", "yarn", "uv", "pip", "pipx"]) {
+    if (normalized.includes(target)) return target;
+  }
+  if (normalized.includes("package manager") || normalized.includes("lockfile")) return "package-manager";
+  if (normalized.includes("vulnerab") || normalized.includes("package")) return "dependency";
+  return "";
+}
+
+function normalizeTarget(target = "") {
+  const normalized = String(target).trim().toLowerCase();
+  if (["npm", "pnpm", "yarn"].includes(normalized)) return "package-manager";
+  if (["pip", "pipx", "uv"].includes(normalized)) return "python";
+  return normalized;
+}
+
+function agentQuickstart(reviewRequired) {
+  return {
+    label: "10-second AI flow",
+    readFirst: "aienvmp status --write",
+    detailCommand: "aienvmp context --json",
+    beforeEnvironmentChange: "aienvmp intent --actor agent:id --action planned-change --target <runtime|package-manager|docker|dependency>",
+    afterEnvironmentChange: "aienvmp sync && aienvmp record --actor agent:id --summary what-changed",
+    handoff: "aienvmp handoff --record --actor agent:id",
+    rule: reviewRequired
+      ? "Review warnings or open intents before environment changes; project-local work may continue."
+      : "Continue project-local work; record intent before environment changes."
+  };
+}
+
 export function preflightArtifacts() {
   return {
     status: ".aienvmp/status.json",

package/src/render.js

@@ -16,6 +16,7 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   lines.push("5. After environment changes, run `aienvmp sync`.");
   lines.push("6. Record what changed with `aienvmp record --actor agent:id --summary what-changed`.");
   lines.push("7. At handoff, run `aienvmp handoff --record --actor agent:id`.", "");
+  lines.push(...preflightLines(manifest.preflight), "");
   lines.push("## Current Policy", "");
   lines.push(...policyLines(policy));
   lines.push("- Enforcement: non-blocking by default; warnings require review but do not lock the machine.");
@@ -33,6 +34,8 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   lines.push(...inventoryLines(manifest.inventory), "");
   lines.push("## Dependency Snapshot", "");
   lines.push(...dependencyLines(manifest.dependencySnapshot), "");
+  lines.push("## Light SBOM", "");
+  lines.push(...lightSbomLines(manifest.lightSbom), "");
   lines.push("## Security Summary", "");
   lines.push(...securityLines(manifest.security), "");
   lines.push("## Project Requirements And Hints", "");
@@ -67,6 +70,31 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   return lines.join("\n");
 }
 
+function preflightLines(preflight = {}) {
+  const quickstart = preflight.quickstart;
+  const targets = preflight.intentTargets || [];
+  const lines = ["## 10-Second AI Flow", ""];
+  if (quickstart) {
+    lines.push(`- Read first: \`${quickstart.readFirst}\``);
+    lines.push(`- Detail: \`${quickstart.detailCommand}\``);
+    lines.push(`- Before env change: \`${quickstart.beforeEnvironmentChange}\``);
+    lines.push(`- After env change: \`${quickstart.afterEnvironmentChange}\``);
+    lines.push(`- Handoff: \`${quickstart.handoff}\``);
+    lines.push(`- Rule: ${quickstart.rule}`);
+  } else {
+    lines.push("- Run `aienvmp status --write`, then `aienvmp context --json` before environment changes.");
+  }
+  lines.push("", "## Recommended Intent Targets", "");
+  if (targets.length) {
+    for (const target of targets.slice(0, 5)) {
+      lines.push(`- ${target.target}: \`${target.command}\` - ${target.reason}`);
+    }
+  } else {
+    lines.push("- environment: `aienvmp intent --actor agent:id --action planned-change --target environment`");
+  }
+  return lines;
+}
+
 export function renderAgentPointer(target = "agents") {
   const label = target === "claude" ? "Claude" : target === "gemini" ? "Gemini" : "AI agents";
   return `## aienvmp Environment Map
@@ -75,12 +103,12 @@ ${label} should use \`aienvmp\` as the workspace environment source of truth.
 
 Before changing runtimes, package managers, Docker settings, global packages, or environment policy:
 
-1. Run \`aienvmp context\`.
-2. Read \`AIENV.md\`.
-3. If the context says \`review-required\`, ask the user before changing the environment.
-4. Record planned environment changes with \`aienvmp intent\`.
-5. After environment changes, run \`aienvmp sync\`.
-6. Record what changed with \`aienvmp record\`.
+1. Run \`aienvmp status --write\`.
+2. Run \`aienvmp context --json\` for details.
+3. Read \`AIENV.md\`.
+4. If status or context says \`review-required\`, ask the user before changing the environment.
+5. Record planned environment changes with the recommended target, for example \`aienvmp intent --actor agent:id --action planned-change --target dependency\`.
+6. After environment changes, run \`aienvmp sync\` and \`aienvmp record --actor agent:id --summary what-changed\`.
 7. At handoff, run \`aienvmp handoff --record --actor agent:id\`.
 
 \`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
@@ -284,6 +312,14 @@ const deps=manifest.dependencySnapshot||{};
 const depSummary=deps.summary||{ecosystems:[],manifests:0,packages:0};
 const depPackages=deps.packages||[];
 const depHtml=depPackages.length?'<table><tr><th>Packages</th><td><code>'+esc(depSummary.packages||0)+'</code></td></tr><tr><th>Ecosystems</th><td><code>'+esc((depSummary.ecosystems||[]).join(', ')||'none')+'</code></td></tr><tr><th>Manifests</th><td><code>'+esc((deps.manifests||[]).join(', ')||'none')+'</code></td></tr></table><div class="timeline">'+depPackages.slice(0,8).map(p=>\`<div class="event"><time>\${esc(p.ecosystem)}</time><div><b>\${esc(p.name)}</b> <code>\${esc(p.version)}</code><div class="path">\${esc(p.manifest)} / \${esc(p.group)}</div></div></div>\`).join('')+'</div>':'<div class="okline">No project dependency manifests detected.</div>';
+const lightSbom=manifest.lightSbom||{};
+const lightSbomSummary=lightSbom.summary||{};
+const pmPolicy=lightSbom.packageManagerPolicy||{};
+const topRisk=lightSbom.topRisk||[];
+const dependencyHints=lightSbom.dependencyChangeHints||[];
+const dependencyHintsHtml=dependencyHints.length?'<div class="timeline">'+dependencyHints.slice(0,5).map(h=>\`<div class="event"><time>\${esc(h.ecosystem||'deps')}</time><div><b>\${esc(h.manifest)}</b> <code>\${esc(h.manager||'unknown')}</code> \${esc(h.packages||0)} packages\${h.riskPackages?.length?\`<div class="path">risk: \${esc(h.riskPackages.map(p=>p.name).join(', '))}</div>\`:''}<div class="path">\${esc((h.groups||[]).join(', ')||'no groups')}\${h.lockfiles?.length?\` / lockfiles: \${esc(h.lockfiles.map(l=>l.file).join(', '))}\`:''}</div></div></div>\`).join('')+'</div>':'<div class="okline">No dependency change hints available.</div>';
+const pmPolicyHtml='<table><tr><th>Status</th><td><code>'+esc(pmPolicy.status||'no-lockfile')+'</code></td></tr><tr><th>Guidance</th><td>'+esc(pmPolicy.guidance||'No lockfile policy detected.')+'</td></tr></table>';
+const lightSbomHtml=\`<table><tr><th>Packages</th><td><code>\${esc(lightSbomSummary.packages||0)}</code></td></tr><tr><th>Vulnerabilities</th><td><code>\${esc(lightSbomSummary.vulnerabilities||0)}</code></td></tr><tr><th>Direct vulnerable</th><td><code>\${esc(lightSbomSummary.directVulnerablePackages||0)}</code></td></tr><tr><th>Manifests</th><td><code>\${esc((lightSbomSummary.manifests||[]).join(', ')||'none')}</code></td></tr><tr><th>Lockfiles</th><td><code>\${esc((lightSbomSummary.lockfiles||[]).map(l=>l.file).join(', ')||'none')}</code></td></tr></table><h3 style="margin-top:12px">Package manager policy</h3>\${pmPolicyHtml}\${topRisk.length?'<div class="timeline">'+topRisk.slice(0,5).map(p=>\`<div class="event"><time>\${esc(p.priority)}</time><div><b>\${esc(p.name)}</b> \${esc(p.severity)} \${p.directDependency?'<code>direct</code>':'<code>transitive</code>'}<div class="path">\${esc(p.manifest||p.ecosystem)} \${esc(p.version||'')}</div></div></div>\`).join('')+'</div>':'<div class="okline">No high-risk package summary in the current light SBOM.</div>'}<h3 style="margin-top:12px">Dependency change hints</h3>\${dependencyHintsHtml}\`;
 const sec=manifest.security||{};
 const secSummary=sec.summary||{total:0,critical:0,high:0,moderate:0,low:0,info:0};
 const secPackages=sec.topPackages||[];
@@ -316,6 +352,8 @@ const ciReadinessHtml=ciReadiness.length?'<table>'+ciReadiness.map(s=>\`<tr><th>
 const enforcementProfile=manifest.preflight?.enforcementProfile||{};
 const strictCommands=enforcementProfile.strictCommands||[];
 const enforcementHtml=\`<table><tr><th>Default</th><td><code>\${esc(enforcementProfile.defaultMode||'advisory')}</code></td></tr><tr><th>Local</th><td>\${esc(enforcementProfile.localOperation||'non-blocking')}</td></tr><tr><th>Strict</th><td>\${esc(enforcementProfile.strictUse||'CI or explicit checks only')}</td></tr><tr><th>Recommended</th><td><code>\${esc(enforcementProfile.recommendedStrictCommand||'aienvmp doctor --strict all')}</code></td></tr></table><div class="timeline">\${strictCommands.slice(0,4).map(cmd=>\`<div class="event"><time>CI</time><div><code>\${esc(cmd)}</code></div></div>\`).join('')}</div><div class="path">\${esc(enforcementProfile.reason||'Warnings stay advisory unless strict mode is requested.')}</div>\`;
+const intentTargets=manifest.preflight?.intentTargets||[];
+const intentTargetsHtml=intentTargets.length?'<div class="timeline">'+intentTargets.slice(0,5).map(t=>\`<div class="event"><time>\${esc(t.target)}</time><div><b>\${esc(t.target)}</b> \${esc(t.reason||'Record this target before environment changes.')}\${t.command?\`<div class="path">\${esc(t.command)}</div>\`:''}</div></div>\`).join('')+'</div>':'<div class="okline">No specific target recommendation. Use <code>aienvmp intent --actor agent:id --action planned-change</code>.</div>';
 const card=(title,badge,body)=>\`<section class="card"><div class="card-head"><h2>\${title}</h2>\${badge||''}</div>\${body}</section>\`;
 const reviewRequired=warnings.length>0||intents.length>0;
 const recentChanges=timeline.slice(-8).length;
@@ -353,11 +391,14 @@ document.getElementById('app').innerHTML=\`
     \${card('Project Hints',\`<span class="pill">\${entries(manifest.projectHints).length} hints</span>\`,\`<table>\${rows(manifest.projectHints)}</table>\`)}
     \${card('Global Inventory',manifest.inventory?.enabled?'<span class="pill">deep</span>':'<span class="pill off">basic</span>',inventoryHtml)}
     \${card('Dependency Snapshot','<span class="pill">'+(depSummary.packages||0)+' packages</span>',depHtml)}
+    \${card('Light SBOM','<span class="pill">'+(lightSbomSummary.packages||0)+' packages</span>',lightSbomHtml)}
     \${card('Security Summary',sec.enabled?'<span class="pill warn">security</span>':'<span class="pill off">basic</span>',securityHtml)}
   </div>
   <aside>
     \${card('Recommended Actions','<span class="pill">'+actions.length+' actions</span>',actionsHtml)}
     <div style="height:14px"></div>
+    \${card('AI Intent Targets','<span class="pill">'+intentTargets.length+' targets</span>',intentTargetsHtml)}
+    <div style="height:14px"></div>
     \${card('AI Plan Artifacts',plan.markdown||plan.json?'<span class="pill">written</span>':'<span class="pill off">not written</span>',planHtml)}
     <div style="height:14px"></div>
     \${card('Remediation Steps',remediation.length?'<span class="pill warn">'+remediation.length+' items</span>':'<span class="pill off">none</span>',remediationHtml)}
@@ -451,6 +492,39 @@ function dependencyLines(snapshot = {}) {
   return lines;
 }
 
+function lightSbomLines(lightSbom = {}) {
+  const summary = lightSbom.summary || {};
+  const lines = [
+    `- Mode: ${lightSbom.mode || "light-sbom"}`,
+    `- Packages: ${summary.packages || 0}`,
+    `- Vulnerabilities: ${summary.vulnerabilities || 0}`,
+    `- Direct vulnerable packages: ${summary.directVulnerablePackages || 0}`,
+    `- Transitive or unmatched vulnerable packages: ${summary.transitiveOrUnmatchedVulnerablePackages || 0}`,
+    `- Lockfiles: ${(summary.lockfiles || []).map((item) => item.file).join(", ") || "none"}`
+  ];
+  if (lightSbom.packageManagerPolicy) {
+    lines.push(`- Package manager policy: ${lightSbom.packageManagerPolicy.status}`);
+    lines.push(`- Package manager guidance: ${lightSbom.packageManagerPolicy.guidance}`);
+  }
+  const risks = lightSbom.topRisk || [];
+  if (risks.length) {
+    lines.push("- Top risk:");
+    for (const item of risks.slice(0, 8)) {
+      lines.push(`  - ${item.name}: ${item.severity}; ${item.priority}/${item.score}; ${item.directDependency ? "direct" : "transitive-or-unmatched"}${item.version ? `; ${item.version}` : ""}`);
+    }
+  }
+  const hints = lightSbom.dependencyChangeHints || [];
+  if (hints.length) {
+    lines.push("- Dependency change hints:");
+    for (const hint of hints.slice(0, 6)) {
+      const risk = hint.riskPackages?.length ? `; risk: ${hint.riskPackages.map((pkg) => pkg.name).join(", ")}` : "";
+      const lockfiles = hint.lockfiles?.length ? `; lockfiles: ${hint.lockfiles.map((item) => item.file).join(", ")}` : "";
+      lines.push(`  - ${hint.manifest}: ${hint.ecosystem}/${hint.manager}; ${hint.packages} packages${risk}${lockfiles}`);
+    }
+  }
+  return lines;
+}
+
 function securityLines(security = {}) {
   if (!security.enabled) return ["- Mode: basic", "- Security scan is disabled. Run `aienvmp sync --security` when vulnerability context is needed."];
   const summary = security.summary || {};