aienvmp 0.1.39 → 0.1.41

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.41
+
+- Added preflight contract metadata so AI and CI consumers can rely on stable entry fields while ignoring additive changes.
+- Added `aienvmp schema --json` to print the stable AI-readable output contract without scanning a workspace.
+- Exposed coordination summaries at the root of `context --json` and `handoff --json`, with a human-readable handoff section.
+- Added light SBOM source, confidence, and limitation hints so agents know what the lightweight snapshot does and does not prove.
+- Updated the README with the schema command and light SBOM verification boundary while keeping the quick-start compact.
+- Added an AI Contract dashboard card so humans can review the same stable fields that agents consume.
+
+## 0.1.40
+
+- Added dependency handoff summaries so the next AI receives dependency read-set and protocol guidance directly in `handoff`.
+- Added a compact `nextAgent` hint to status/preflight JSON for safer AI-to-AI continuation.
+- Added target-level open intent coordination summaries so agents can detect dependency conflicts without parsing logs.
+- Shortened the README around the 10-second AI flow, generated outputs, and advisory contract.
+- Updated the dashboard handoff card with next-agent read hints, dependency files, and conflict targets.
+- Printed the next-agent handoff command in the plain `status` output.
+
 ## 0.1.39
 
 - Added a dependency read set to preflight, `AIENV.md`, and the dashboard so agents know which manifests and lockfiles to read before package or security changes.

package/README.md

@@ -6,123 +6,96 @@
 
 **AI Environment Map.**
 
-`aienvmp` is an AI-first environment map for shared coding machines.
+`aienvmp` is a lightweight env map and light SBOM for shared AI coding machines.
 
-It helps Codex, Claude, Gemini, and humans avoid silent Node, Python, package manager, dependency, Docker, and security drift.
+It helps Codex, Claude, Gemini, and humans avoid silent runtime, package manager, dependency, Docker, and security drift.
 
-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
+## 10-Second Use
 
 ```bash
 npx aienvmp sync
 npx aienvmp status
-npx aienvmp context
-npx aienvmp plan
-npx aienvmp handoff
-```
-
-10-second AI flow: `aienvmp status --write` -> `aienvmp context --json` -> intent before environment changes.
-Use `--dir <workspace>` before or after the command when an AI or CI process runs outside the target project.
-
-Optional deeper read-only checks:
-
-```bash
-npx aienvmp sync --deep
-npx aienvmp sync --security
+npx aienvmp context --json
+npx aienvmp schema --json
 ```
 
-## AI Usage
-
-Tell each agent to read `aienvmp context --json` before environment changes.
+Before environment changes:
 
 ```bash
-npx aienvmp context --json
-npx aienvmp intent --actor agent:codex --action "upgrade node" --target node
-npx aienvmp record --actor agent:codex --summary "updated .nvmrc" --target node
+npx aienvmp intent --actor agent:codex --action "change dependency" --target dependency
+npx aienvmp record --actor agent:codex --summary "dependency-change" --target dependency
 npx aienvmp handoff --record --actor agent:codex
 ```
 
-## Output
+Use `--dir <workspace>` when AI or CI runs outside the target project.
+
+## What It Creates
 
 ```text
-AIENV.md
-.aienvmp/manifest.json
-.aienvmp/status.json       # first file for AI: clear/review, next command, strict advice
-.aienvmp/intents.jsonl
-.aienvmp/timeline.jsonl
-.aienvmp/plan.json
-.aienvmp/plan.md             # read-only plan with dependency protocol
-.aienvmp/dashboard.html     # includes dependencies, plan, remediation, and environment cards
+AIENV.md                 # Markdown env map for AI agents
+.aienvmp/status.json     # first AI read: clear/review, next command, nextAgent hint
+.aienvmp/manifest.json   # runtime map + light SBOM
+.aienvmp/intents.jsonl   # planned env changes
+.aienvmp/timeline.jsonl  # append-only change ledger
+.aienvmp/plan.md         # read-only action plan
+.aienvmp/dashboard.html  # human dashboard
 ```
 
-`AIENV.md` includes the 10-second AI flow and recommended intent targets for Markdown-first agents.
+## AI Contract
 
-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.
-It also lists dependency manifests and lockfiles to read before package or security changes.
-Dependency and security changes stay advisory: record dependency intent, refresh with `sync`, then record what changed.
-Dependency records also trigger handoff/coordination warnings for the next agent.
-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.
+- `status`, `context`, `plan`, and `handoff` share one preflight contract.
+- `schema --json` prints the stable AI-readable output contract without scanning.
+- `status.json.nextAgent` tells the next AI what to read and whether to review first.
+- `dependencyReadSet` lists manifests and lockfiles before package or security changes.
+- `coordination.conflictTargets` shows where multiple agents are planning changes.
+- `handoff` carries dependency read-set and protocol guidance for the next AI.
+- Light SBOM includes source/confidence hints; verify security claims with dedicated scanners.
+- Everything is advisory by default; strict failure is opt-in with `doctor --strict`.
 
 ## Agent Files
 
-`aienvmp` does not replace AGENTS.md. It gives AGENTS.md a live environment source of truth.
+`aienvmp` does not replace AGENTS.md, CLAUDE.md, or GEMINI.md. It gives them a live environment source of truth.
 
 ```bash
 npx aienvmp snippet agents
+npx aienvmp snippet claude
+npx aienvmp snippet gemini
 ```
 
-## CI Usage
+## Commands
+
+```bash
+aienvmp sync                    # update env map, status, ledger, dashboard
+aienvmp status --write          # refresh compact AI status
+aienvmp context --json          # AI decision contract
+aienvmp schema --json           # stable output contract for AI/CI consumers
+aienvmp plan --write            # read-only action plan
+aienvmp handoff --record        # next-agent summary
+aienvmp intent                  # record planned env change
+aienvmp record                  # record what changed
+aienvmp doctor --strict security|policy|coordination|all
+```
 
-Use the GitHub Action to write the env map, plan, dashboard, and optional strict checks. See [examples/github-action.yml](examples/github-action.yml).
-CI also writes `.aienvmp/status.json` for a compact AI-readable result.
-The dashboard shows which strict scopes are CI-ready before you enforce them.
+## CI
 
 ```yaml
 - uses: soovwv/aienvmp@main
   with:
     write-status: "true"
     write-plan: "true"
-    strict: "off" # security, policy, coordination, all, or off
+    strict: "off"
 ```
 
-## Commands
-
-```bash
-aienvmp sync              # update env map, light SBOM, status, ledger, dashboard
-aienvmp status --write    # refresh .aienvmp/status.json only
-aienvmp context           # AI preflight brief
-aienvmp context --json    # AI decision contract + actions + compact step summary
-aienvmp plan              # read-only AI action plan using the same decision contract
-aienvmp handoff           # next-agent handoff summary using the same decision contract
-aienvmp intent            # record a planned env change
-aienvmp record            # record what changed
-aienvmp doctor --ci       # strict CI check for all warnings
-aienvmp doctor --strict security  # fail only scoped warnings
-```
+See [examples/github-action.yml](examples/github-action.yml).
 
 ## Principles
 
-- simple by default
-- AI-first
-- lightweight
-- read-only planning, no automatic fixes
-- one advisory engine, optional enforcement with `doctor --ci`
-- scoped enforcement with `doctor --strict security|policy|coordination|all`
-- context and plan expose suggested strict scopes for CI
-- 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
+- simple commands
+- AI-first outputs
+- lightweight, read-only scanning
+- light SBOM from project files
+- advisory locally, strict only when requested
+- humans or CI verify; AI agents observe, plan, record, and hand off
 
 ## Development
 
@@ -132,8 +105,6 @@ npm run smoke
 npm pack --dry-run
 ```
 
-## Links
-
 [Roadmap](ROADMAP.md) / [Security](SECURITY.md) / [Troubleshooting](TROUBLESHOOTING.md) / [Bugfix Log](BUGFIXES.md) / [Contributing](CONTRIBUTING.md)
 
 Apache-2.0

package/package.json

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

package/src/cli.js

@@ -13,6 +13,7 @@ import { snippetWorkspace } from "./commands/snippet.js";
 import { handoffWorkspace } from "./commands/handoff.js";
 import { planWorkspace } from "./commands/plan.js";
 import { statusWorkspace } from "./commands/status.js";
+import { schemaWorkspace } from "./commands/schema.js";
 import { readFileSync } from "node:fs";
 
 const commands = new Map([
@@ -30,7 +31,8 @@ const commands = new Map([
   ["snippet", snippetWorkspace],
   ["handoff", handoffWorkspace],
   ["plan", planWorkspace],
-  ["status", statusWorkspace]
+  ["status", statusWorkspace],
+  ["schema", schemaWorkspace]
 ]);
 
 const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -107,6 +109,7 @@ Usage:
   aienvmp status [--dir .] [--json] [--write] [--quiet]
   aienvmp handoff [--dir .] [--json] [--record --actor agent:id]
   aienvmp plan [--dir .] [--json] [--write]
+  aienvmp schema [--json]
 
 Common:
   aienvmp sync      update AIENV.md, manifest, status, ledger, intents, and dashboard
@@ -114,6 +117,7 @@ Common:
   aienvmp context   print the AI preflight brief
   aienvmp handoff   print the next-agent handoff summary
   aienvmp plan      print a read-only AI environment action plan
+  aienvmp schema    print the stable AI-readable output contract
   aienvmp snippet   print an AGENTS.md pointer snippet
   aienvmp dash      regenerate/open the lightweight dashboard
 

package/src/commands/context.js

@@ -26,6 +26,7 @@ export async function contextWorkspace(args) {
     console.log(JSON.stringify({
       status: warnings.length ? "review-required" : "clear",
       preflight,
+      coordination: preflight.coordination,
       decision,
       enforcement: enforcementAdvice(warnings),
       recommendedActions: actions,
@@ -73,6 +74,9 @@ function lightSbomSummary(lightSbom = {}) {
       guidance: "No lockfile policy detected."
     },
     dependencyChangeHints: (lightSbom.dependencyChangeHints || []).slice(0, 8),
+    source: lightSbom.source || {},
+    confidence: lightSbom.confidence || {},
+    limitations: lightSbom.limitations || [],
     aiUse: lightSbom.aiUse || {}
   };
 }

package/src/commands/handoff.js

@@ -46,11 +46,12 @@ async function recordHandoff(file, handoff, actor) {
 export function buildHandoff(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
   const reviewRequired = warnings.length > 0 || intents.length > 0;
   const actions = recommendedActions(manifest, { warnings, intents });
+  const preflight = buildPreflight(manifest, warnings, intents);
   return {
     status: reviewRequired ? "review-required" : "clear",
     trust: manifest.trust || {},
     schemaVersion: manifest.schemaVersion || 1,
-    preflight: buildPreflight(manifest, warnings, intents),
+    preflight,
     decision: aiDecision(warnings, intents),
     workspace: manifest.workspace,
     safeRuntime: {
@@ -60,6 +61,8 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
     },
     inventory: inventorySummary(manifest.inventory),
     security: securitySummary(manifest.security),
+    dependencyHandoff: dependencyHandoffSummary(preflight),
+    coordination: preflight.coordination,
     policy: {
       node: policy.node || "not set",
       python: policy.python || "not set",
@@ -82,6 +85,20 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
   };
 }
 
+function dependencyHandoffSummary(preflight = {}) {
+  const protocol = preflight.dependencyChangeProtocol || {};
+  return {
+    readSet: (preflight.dependencyReadSet || []).slice(0, 5),
+    protocol: {
+      mode: protocol.mode || "advisory",
+      packageManagerPolicy: protocol.packageManagerPolicy || "not-detected",
+      recordIntent: protocol.commands?.recordIntent || "aienvmp intent --actor agent:id --action planned-change --target dependency",
+      recordAfterChange: protocol.commands?.recordAfterChange || "aienvmp record --actor agent:id --summary dependency-change --target dependency",
+      handoff: protocol.commands?.handoff || "aienvmp handoff --record --actor agent:id"
+    }
+  };
+}
+
 function securitySummary(security = {}) {
   return {
     mode: security.mode || "basic",

package/src/commands/schema.js

@@ -0,0 +1,16 @@
+import { schemaContract } from "../contract.js";
+
+export async function schemaWorkspace(args = {}) {
+  const schema = schemaContract();
+  if (args.json) {
+    console.log(JSON.stringify(schema, null, 2));
+  } else {
+    console.log("aienvmp contract");
+    console.log(`schema: ${schema.name} v${schema.schemaVersion}`);
+    console.log(`status: ${schema.outputs.status.command}`);
+    console.log(`context: ${schema.outputs.context.command}`);
+    console.log(`handoff: ${schema.outputs.handoff.command}`);
+    console.log(`rule: ${schema.compatibility.consumerRule}`);
+  }
+  return schema;
+}

package/src/commands/status.js

@@ -25,6 +25,7 @@ export async function statusWorkspace(args) {
     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(`handoff: ${output.nextAgent.handoffCommand}`);
     console.log(`strict: ${output.enforcement.recommendedCommand}`);
     if (artifact) console.log(`status: ${artifact}`);
   }

package/src/contract.js

@@ -0,0 +1,42 @@
+export function preflightContract() {
+  return {
+    name: "aienvmp-preflight",
+    version: 1,
+    stability: "additive",
+    requiredFields: ["schemaVersion", "state", "decision", "quickstart", "commands", "artifacts"],
+    aiEntryFields: ["state", "summary", "nextAgent", "coordination", "dependencyReadSet", "dependencyChangeProtocol"],
+    rule: "Consumers should ignore unknown fields and treat missing optional fields as unavailable."
+  };
+}
+
+export function schemaContract() {
+  return {
+    schemaVersion: 1,
+    name: "aienvmp-contract",
+    purpose: "Stable AI-readable contract for aienvmp outputs.",
+    outputs: {
+      status: {
+        file: ".aienvmp/status.json",
+        command: "aienvmp status --json",
+        contract: preflightContract()
+      },
+      context: {
+        command: "aienvmp context --json",
+        rootFields: ["status", "preflight", "coordination", "decision", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
+      },
+      handoff: {
+        command: "aienvmp handoff --json",
+        rootFields: ["status", "decision", "preflight", "coordination", "dependencyHandoff", "openIntents", "warnings", "recommendedActions", "recentChanges"]
+      },
+      manifest: {
+        file: ".aienvmp/manifest.json",
+        rootFields: ["schemaVersion", "workspace", "runtimes", "packageManagers", "dependencySnapshot", "lightSbom", "security", "trust"]
+      }
+    },
+    compatibility: {
+      stability: "additive",
+      consumerRule: "Ignore unknown fields. Do not require optional fields unless listed in requiredFields.",
+      localBehavior: "read-only; this command does not scan, install, update, or lock anything."
+    }
+  };
+}

package/src/dependencies.js

@@ -79,6 +79,23 @@ export function buildLightSbom(snapshot = {}, security = {}) {
     schemaVersion: 1,
     mode: "light-sbom",
     note: "AI-ready package and vulnerability summary from read-only project files and optional scanners.",
+    source: {
+      dependencies: "project manifests",
+      lockfiles: "file presence only",
+      vulnerabilities: security.enabled ? "optional scanner summary" : "not scanned",
+      resolver: "not run"
+    },
+    confidence: {
+      directDependencies: "high",
+      lockfileManager: snapshot.lockfiles?.length ? "medium" : "none",
+      transitiveDependencies: "not-resolved",
+      vulnerabilities: security.enabled ? "scanner-provided" : "not-scanned"
+    },
+    limitations: [
+      "Does not install packages.",
+      "Does not resolve full transitive dependency graphs.",
+      "Does not replace CycloneDX, SPDX, Syft, Trivy, npm audit, or pip-audit outputs."
+    ],
     summary: {
       ecosystems: countBy(packages, "ecosystem"),
       managers: countBy(packages, "manager"),
@@ -96,7 +113,8 @@ export function buildLightSbom(snapshot = {}, security = {}) {
     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"
+      dependencySource: "project manifests only; no install or resolver is run",
+      trustRule: "Use lightSbom as a fast AI planning map; verify with dedicated scanners before security claims."
     }
   };
 }

package/src/preflight.js

@@ -1,6 +1,7 @@
 import { recommendedActions } from "./actions.js";
 import { aiDecision } from "./decision.js";
 import { enforcementAdvice } from "./enforcement.js";
+import { preflightContract } from "./contract.js";
 
 export function buildPreflight(manifest = {}, warnings = [], intents = []) {
   const decision = aiDecision(warnings, intents);
@@ -11,8 +12,10 @@ export function buildPreflight(manifest = {}, warnings = [], intents = []) {
   const intentTargets = recommendedIntentTargets(manifest, warnings, intents);
   const dependencyReadSet = dependencyPreflightReadSet(manifest);
   const dependencyChangeProtocol = dependencyProtocol(manifest, dependencyReadSet);
+  const coordination = coordinationSummary(intents);
   return {
     schemaVersion: 1,
+    contract: preflightContract(),
     state,
     summary: state === "clear"
       ? "Project-local work can continue. Record intent before environment changes."
@@ -47,6 +50,8 @@ export function buildPreflight(manifest = {}, warnings = [], intents = []) {
       environmentChanges: decision.canChangeEnvironmentWithoutReview ? "allowed" : "intent-and-review-first"
     },
     quickstart: agentQuickstart(decision.reviewRequired),
+    nextAgent: nextAgentHint(state, dependencyReadSet, dependencyChangeProtocol),
+    coordination,
     intentTargets,
     dependencyReadSet,
     dependencyChangeProtocol,
@@ -72,6 +77,56 @@ export function buildPreflight(manifest = {}, warnings = [], intents = []) {
   };
 }
 
+function coordinationSummary(intents = []) {
+  const byTarget = new Map();
+  for (const intent of intents) {
+    const target = normalizeTarget(intent.target || targetFromText(intent.action) || "environment") || "environment";
+    const item = byTarget.get(target) || { target, count: 0, actors: [], actions: [], conflict: false };
+    item.count += 1;
+    if (intent.actor && !item.actors.includes(intent.actor)) item.actors.push(intent.actor);
+    if (intent.action) item.actions.push(intent.action);
+    byTarget.set(target, item);
+  }
+  const targets = [...byTarget.values()].map((item) => ({
+    target: item.target,
+    count: item.count,
+    actors: item.actors.slice(0, 5),
+    actions: item.actions.slice(-3),
+    conflict: item.count > 1 && item.actors.length > 1
+  }));
+  const conflictTargets = targets.filter((item) => item.conflict).map((item) => item.target);
+  return {
+    openIntentCount: intents.length,
+    targets,
+    conflictTargets,
+    next: conflictTargets.length
+      ? "Review or resolve conflicting intents before environment changes."
+      : intents.length
+        ? "Check open intents before environment changes."
+        : "No open environment intents."
+  };
+}
+
+function nextAgentHint(state, dependencyReadSet = [], dependencyChangeProtocol = {}) {
+  const firstDependency = dependencyReadSet[0];
+  const dependencyFiles = firstDependency
+    ? [firstDependency.manifest, ...(firstDependency.lockfiles || [])].filter(Boolean)
+    : [];
+  return {
+    handoffCommand: dependencyChangeProtocol.commands?.handoff || "aienvmp handoff --record --actor agent:id",
+    readFirst: ".aienvmp/status.json",
+    readNext: "aienvmp context --json",
+    reviewState: state,
+    dependencyFiles,
+    dependencyProtocol: dependencyChangeProtocol.commands?.recordIntent
+      ? "record dependency intent, sync after change, then record dependency-change"
+      : "no dependency protocol detected",
+    rule: state === "clear"
+      ? "Next AI may continue project-local work; record intent before environment changes."
+      : "Next AI should review warnings or open intents before environment changes."
+  };
+}
+
 function dependencyProtocol(manifest = {}, dependencyReadSet = []) {
   const pmPolicy = manifest.lightSbom?.packageManagerPolicy || {};
   return {

package/src/render.js

@@ -199,12 +199,18 @@ export function renderHandoff(handoff) {
     "Open intents:",
     ...(handoff.openIntents.length ? handoff.openIntents.map((i) => `- ${i.actor}: ${i.action}${i.target ? ` (${i.target})` : ""}`) : ["- none"]),
     "",
+    "Coordination:",
+    ...coordinationHandoffLines(handoff.coordination),
+    "",
     "Warnings:",
     ...(handoff.warnings.length ? handoff.warnings.map((w) => `- ${w.message}`) : ["- none"]),
     "",
     "Recommended actions:",
     ...(handoff.recommendedActions?.length ? handoff.recommendedActions.map((item) => `- [${item.priority}] ${item.summary}${item.command ? ` (${item.command})` : ""}`) : ["- none"]),
     "",
+    "Dependency handoff:",
+    ...dependencyHandoffLines(handoff.dependencyHandoff),
+    "",
     "Recent changes:",
     ...(handoff.recentChanges.length ? handoff.recentChanges.map((t) => `- ${formatTimeline(t)}`) : ["- none"]),
     "",
@@ -217,6 +223,30 @@ export function renderHandoff(handoff) {
   return lines.join("\n");
 }
 
+function coordinationHandoffLines(coordination = {}) {
+  const conflicts = coordination.conflictTargets || [];
+  if (conflicts.length) return [`- Conflicts: ${conflicts.join(", ")}`, `- Next: ${coordination.next || "review open intents"}`];
+  return [`- Open intents: ${coordination.openIntentCount || 0}`, `- Next: ${coordination.next || "no open environment intents"}`];
+}
+
+function dependencyHandoffLines(dependencyHandoff = {}) {
+  const readSet = dependencyHandoff.readSet || [];
+  const protocol = dependencyHandoff.protocol || {};
+  const lines = [];
+  if (readSet.length) {
+    for (const item of readSet.slice(0, 3)) {
+      const files = [item.manifest, ...(item.lockfiles || [])].filter(Boolean).join(", ");
+      lines.push(`- Read: ${files || "dependency files"} (${item.ecosystem || "deps"}/${item.manager || "unknown"})`);
+    }
+  } else {
+    lines.push("- Read: no dependency files detected");
+  }
+  lines.push(`- Intent: ${protocol.recordIntent || "aienvmp intent --actor agent:id --action planned-change --target dependency"}`);
+  lines.push(`- After change: ${protocol.recordAfterChange || "aienvmp record --actor agent:id --summary dependency-change --target dependency"}`);
+  lines.push(`- Handoff: ${protocol.handoff || "aienvmp handoff --record --actor agent:id"}`);
+  return lines;
+}
+
 export function renderPlan(plan) {
   const lines = [
     "# AI Environment Plan",
@@ -385,6 +415,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 contract=manifest.preflight?.contract||{};
+const contractHtml=contract.name?\`<table><tr><th>Name</th><td><code>\${esc(contract.name)}</code></td></tr><tr><th>Version</th><td><code>\${esc(contract.version||1)}</code></td></tr><tr><th>Stability</th><td><code>\${esc(contract.stability||'additive')}</code></td></tr><tr><th>AI fields</th><td>\${esc((contract.aiEntryFields||[]).join(', ')||'none')}</td></tr></table><div class="path">\${esc(contract.rule||'Ignore unknown fields.')}</div>\`:'<div class="okline">Run <code>aienvmp status --write</code> to include AI contract metadata.</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 dependencyReadSet=manifest.preflight?.dependencyReadSet||[];
@@ -398,7 +430,12 @@ const trustState=manifest.trust?.state||'observed';
 const nextAction=reviewRequired?'Review before environment changes':'Proceed with project-local work';
 const auditItem=(key,value,hint,klass='')=>\`<div class="audit-item \${klass}"><div class="audit-k">\${key}</div><div class="audit-v">\${value}</div><div class="audit-hint">\${hint}</div></div>\`;
 const driftLabel=warnings.length?'detected':'none';
-const handoffHtml=\`<table><tr><th>Status</th><td>\${reviewRequired?'review-required':'clear'}</td></tr><tr><th>Trust</th><td><code>\${esc(trustState)}</code></td></tr><tr><th>Node</th><td><code>\${esc(manifest.runtimes.node||'not detected')}</code></td></tr><tr><th>Python</th><td><code>\${esc(manifest.runtimes.python||manifest.runtimes.python3||'not detected')}</code></td></tr><tr><th>Docker</th><td>\${manifest.containers?.docker?'available':'not detected'}</td></tr><tr><th>Next</th><td>\${reviewRequired?'Review warnings and open intents':'Continue project-local work'}</td></tr></table>\`;
+const nextAgent=manifest.preflight?.nextAgent||{};
+const coordination=manifest.preflight?.coordination||{};
+const conflictTargets=coordination.conflictTargets||[];
+const handoffFiles=nextAgent.dependencyFiles?.length?nextAgent.dependencyFiles:(dependencyReadSet[0]?[dependencyReadSet[0].manifest,...(dependencyReadSet[0].lockfiles||[])].filter(Boolean):[]);
+const handoffNext=nextAgent.rule||(reviewRequired?'Review warnings and open intents':'Continue project-local work');
+const handoffHtml=\`<table><tr><th>Status</th><td>\${reviewRequired?'review-required':'clear'}</td></tr><tr><th>Trust</th><td><code>\${esc(trustState)}</code></td></tr><tr><th>Read first</th><td><code>\${esc(nextAgent.readFirst||'.aienvmp/status.json')}</code></td></tr><tr><th>Dependency files</th><td>\${handoffFiles.length?'<code>'+esc(handoffFiles.join(', '))+'</code>':'none'}</td></tr><tr><th>Conflicts</th><td>\${conflictTargets.length?'<code>'+esc(conflictTargets.join(', '))+'</code>':'none'}</td></tr><tr><th>Next</th><td>\${esc(handoffNext)}</td></tr></table>\`;
 document.getElementById('app').innerHTML=\`
 <header>
   <div>
@@ -436,6 +473,8 @@ document.getElementById('app').innerHTML=\`
     <div style="height:14px"></div>
     \${card('AI Intent Targets','<span class="pill">'+intentTargets.length+' targets</span>',intentTargetsHtml)}
     <div style="height:14px"></div>
+    \${card('AI Contract','<span class="pill">'+(contract.stability||'additive')+'</span>',contractHtml)}
+    <div style="height:14px"></div>
     \${card('Dependency Read Set','<span class="pill">'+dependencyReadSet.length+' files</span>',dependencyReadSetHtml)}
     <div style="height:14px"></div>
     \${card('Dependency Protocol','<span class="pill">'+(dependencyProtocol.mode||'advisory')+'</span>',dependencyProtocolHtml)}
@@ -543,6 +582,10 @@ function lightSbomLines(lightSbom = {}) {
     `- Transitive or unmatched vulnerable packages: ${summary.transitiveOrUnmatchedVulnerablePackages || 0}`,
     `- Lockfiles: ${(summary.lockfiles || []).map((item) => item.file).join(", ") || "none"}`
   ];
+  if (lightSbom.source || lightSbom.confidence) {
+    lines.push(`- Source: ${lightSbom.source?.dependencies || "project manifests"}; vulnerabilities: ${lightSbom.source?.vulnerabilities || "not scanned"}`);
+    lines.push(`- Confidence: direct ${lightSbom.confidence?.directDependencies || "unknown"}; transitive ${lightSbom.confidence?.transitiveDependencies || "unknown"}`);
+  }
   if (lightSbom.packageManagerPolicy) {
     lines.push(`- Package manager policy: ${lightSbom.packageManagerPolicy.status}`);
     lines.push(`- Package manager guidance: ${lightSbom.packageManagerPolicy.guidance}`);