aienvmp 0.1.49 → 0.1.51

package/.agents/skills/aienvmp/SKILL.md

@@ -11,20 +11,26 @@ The goal is to help multiple AI agents avoid silently installing or using differ
 
 ## Preflight
 
-Before environment-impacting work, run:
+Before environment-impacting work, run the light preflight first:
 
 ```bash
-npx aienvmp context
+npx aienvmp status --write
 ```
 
-If the output says `review-required`, do not change global runtimes, package managers, Docker settings, or global packages without asking the user.
+Then read the short handoff:
 
-For machine-readable context, use:
+```bash
+cat .aienvmp/summary.md
+```
+
+For deeper machine-readable context, use:
 
 ```bash
 npx aienvmp context --json
 ```
 
+If the output says `review-required`, do not change global runtimes, package managers, Docker settings, dependencies, lockfiles, or global packages without asking the user.
+
 ## Before Environment Changes
 
 Record intent before changing shared environment state:
@@ -38,26 +44,25 @@ Use this for changes such as:
 - installing or upgrading Node, Python, Docker, package managers, or global CLIs
 - changing `.nvmrc`, `.python-version`, `mise.toml`, `.tool-versions`, or `.aienvmp/policy.yml`
 - switching package managers
+- changing dependencies or lockfiles
 - changing Docker daemon/context assumptions
 
 ## After Environment Changes
 
-Refresh the environment map:
+Use the one-command checkpoint after an accepted environment change:
 
 ```bash
-npx aienvmp sync
+npx aienvmp checkpoint --actor agent:codex --summary "<what changed>" --target "<tool-or-runtime>"
 ```
 
-Record what changed:
+This records the change, refreshes the env map, writes status/summary/SBOM artifacts, and records a handoff.
 
-```bash
-npx aienvmp record --actor agent:codex --summary "<what changed>" --target "<tool-or-runtime>" --evidence "<command or file>"
-```
-
-Resolve the original intent if complete:
+If checkpoint is not available, use the explicit fallback:
 
 ```bash
-npx aienvmp resolve --actor agent:codex --id "<intent-id>"
+npx aienvmp sync
+npx aienvmp record --actor agent:codex --summary "<what changed>" --target "<tool-or-runtime>" --evidence "<command or file>"
+npx aienvmp handoff --record --actor agent:codex
 ```
 
 ## Safety Rules
@@ -66,6 +71,7 @@ npx aienvmp resolve --actor agent:codex --id "<intent-id>"
 - Treat policy mismatches as review-required.
 - Do not install, upgrade, downgrade, or remove global software unless the user explicitly asks.
 - Prefer project-local version files and local environments.
+- Do not switch package managers or rewrite lockfiles only to satisfy a tool preference.
 - Do not use warnings as permission to interrupt production or shared workspace operations.
 - Use `npx aienvmp doctor --ci` only in CI or explicit strict-mode automation.
 

package/BUGFIXES.md

@@ -82,6 +82,24 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: the Action now has `write-sbom` and the example uploads both native and CycloneDX-lite SBOM artifacts.
 - Verification: Action tests cover input metadata, SBOM write commands, and example artifact paths.
 
+### CI and AI review still needed a short handoff view
+
+- Issue: `status.json` was AI-friendly, but GitHub Actions and quick human review still required opening JSON artifacts or the dashboard.
+- Fix: `aienvmp summary` now writes `.aienvmp/summary.md`, `sync` creates it by default, and the GitHub Action appends it to `GITHUB_STEP_SUMMARY`.
+- Verification: tests cover summary rendering, sync artifact creation, schema metadata, Action wiring, and example upload paths.
+
+### Windows-created JSON files could be missed
+
+- Issue: UTF-8 BOM JSON files created by some Windows tools could fail JSON parsing and make dependency snapshots look empty.
+- Fix: `readJson` now strips a leading UTF-8 BOM before parsing.
+- Verification: regression tests cover BOM JSON parsing and Windows smoke testing confirmed dependency counts in `summary.md`.
+
+### Agent instructions lagged behind the current protocol
+
+- Issue: packaged skill and pointer snippets still emphasized older context/record flows and did not direct agents to `summary.md`.
+- 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.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.51
+
+- Updated Codex/Claude/Gemini pointer snippets to use the current `status -> summary.md -> context` read order.
+- Added agent-specific actor examples for Codex, Claude, and Gemini snippet output.
+- Added dependency and lockfile changes to the snippet environment-change scope.
+- Updated the packaged Codex skill to prefer `status --write`, `summary.md`, and `checkpoint`.
+- Added `.aienvmp/summary.md` to the shared preflight read order and next-agent hint.
+- Added a Dependency changes section to `summary.md` with read files, intent command, checkpoint command, and package-manager policy.
+- Updated README agent-file guidance and added regression coverage for the AI snippet and summary protocol.
+
+## 0.1.50
+
+- Added `aienvmp summary` for a compact Markdown AI/CI handoff view.
+- Added `.aienvmp/summary.md` writing through the default `sync` flow.
+- Added `summary` to preflight artifacts and the stable output contract.
+- Added a GitHub Action `write-summary` input.
+- Appended `.aienvmp/summary.md` to GitHub Step Summary when the Action runs in GitHub Actions.
+- Updated the GitHub Action example and README to include the summary artifact.
+- Fixed UTF-8 BOM JSON parsing so Windows-created `package.json` files are scanned correctly.
+- Added regression tests for summary rendering, sync output, schema metadata, Action Step Summary wiring, and BOM JSON parsing.
+
 ## 0.1.49
 
 - Added a `write-sbom` GitHub Action input for explicit SBOM artifact generation.

package/README.md

@@ -34,6 +34,7 @@ Warnings are advisory by default. Use `doctor --strict <scope>` only when you wa
 ```text
 AIENV.md                 # Markdown env map for AI agents
 .aienvmp/status.json     # first AI read: clear/review, next command, nextAgent hint
+.aienvmp/summary.md      # compact AI/CI summary
 .aienvmp/manifest.json   # runtime map + light SBOM
 .aienvmp/sbom.json       # standalone AI-readable light SBOM
 .aienvmp/sbom.cdx.json   # CycloneDX-lite export from project manifests
@@ -47,6 +48,7 @@ AIENV.md                 # Markdown env map for AI agents
 
 - `status`, `context`, `plan`, and `handoff` share one preflight contract.
 - `schema --json` prints the stable AI-readable output contract without scanning.
+- `summary.md` is the short CI/AI handoff view.
 - `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.
 - `sbomRisk` gives AI a compact light-SBOM risk level, signals, and next command.
@@ -63,16 +65,20 @@ AIENV.md                 # Markdown env map for AI agents
 `aienvmp` does not replace AGENTS.md, CLAUDE.md, or GEMINI.md. It gives them a live environment source of truth.
 
 ```bash
+npx aienvmp snippet codex
 npx aienvmp snippet agents
 npx aienvmp snippet claude
 npx aienvmp snippet gemini
 ```
 
+Snippets point each AI to `status`, `summary.md`, `context --json`, intent, and checkpoint without taking over the instruction file.
+
 ## Commands
 
 ```bash
-aienvmp sync                    # update env map, status, ledger, dashboard
+aienvmp sync                    # update env map, status, summary, SBOM, dashboard
 aienvmp status --write          # refresh compact AI status
+aienvmp summary --write         # refresh compact Markdown summary
 aienvmp context --json          # AI decision contract
 aienvmp sbom --json             # standalone light SBOM
 aienvmp sbom --format cyclonedx-lite --json
@@ -87,7 +93,7 @@ aienvmp doctor --strict security|policy|coordination|all
 
 ## CI
 
-The GitHub Action writes status, schema, doctor, plan, SBOM, and dashboard artifacts. `strict: "off"` reports warnings without failing the job.
+The GitHub Action writes status, summary, schema, doctor, plan, SBOM, and dashboard artifacts. `strict: "off"` reports warnings without failing the job.
 
 ```yaml
 - uses: soovwv/aienvmp@main
@@ -95,6 +101,7 @@ The GitHub Action writes status, schema, doctor, plan, SBOM, and dashboard artif
     write-status: "true"
     write-plan: "true"
     write-sbom: "true"
+    write-summary: "true"
     strict: "off"
 ```
 

package/action.yml

@@ -31,6 +31,10 @@ inputs:
     description: Write standalone light SBOM and CycloneDX-lite artifacts
     required: false
     default: "true"
+  write-summary:
+    description: Write compact Markdown summary and append it to GitHub Step Summary
+    required: false
+    default: "true"
 
 runs:
   using: composite
@@ -77,6 +81,16 @@ runs:
           node "$GITHUB_ACTION_PATH/bin/aienvmp.js" sbom --dir "${{ inputs.directory }}" --format cyclonedx-lite --write --quiet
         fi
 
+    - name: Write AI summary
+      shell: bash
+      run: |
+        if [ "${{ inputs.write-summary }}" = "true" ]; then
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" summary --dir "${{ inputs.directory }}" --write --quiet
+          if [ -n "$GITHUB_STEP_SUMMARY" ]; then
+            cat "${{ inputs.directory }}/.aienvmp/summary.md" >> "$GITHUB_STEP_SUMMARY"
+          fi
+        fi
+
     - name: Doctor
       shell: bash
       run: |

package/examples/github-action.yml

@@ -17,6 +17,7 @@ jobs:
           write-schema: "true"
           write-doctor-json: "true"
           write-sbom: "true"
+          write-summary: "true"
           strict: "off" # security, policy, coordination, all, or off
 
       - uses: actions/upload-artifact@v4
@@ -27,6 +28,7 @@ jobs:
             AIENV.md
             .aienvmp/manifest.json
             .aienvmp/status.json
+            .aienvmp/summary.md
             .aienvmp/sbom.json
             .aienvmp/sbom.cdx.json
             .aienvmp/schema.json

package/package.json

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

package/src/cli.js

@@ -16,6 +16,7 @@ import { statusWorkspace } from "./commands/status.js";
 import { schemaWorkspace } from "./commands/schema.js";
 import { checkpointWorkspace } from "./commands/checkpoint.js";
 import { sbomWorkspace } from "./commands/sbom.js";
+import { summaryWorkspace } from "./commands/summary.js";
 import { readFileSync } from "node:fs";
 
 const commands = new Map([
@@ -36,7 +37,8 @@ const commands = new Map([
   ["status", statusWorkspace],
   ["schema", schemaWorkspace],
   ["checkpoint", checkpointWorkspace],
-  ["sbom", sbomWorkspace]
+  ["sbom", sbomWorkspace],
+  ["summary", summaryWorkspace]
 ]);
 
 const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -115,16 +117,18 @@ Usage:
   aienvmp checkpoint [--dir .] --actor agent:id --summary "what changed" [--target dependency] [--json]
   aienvmp plan [--dir .] [--json] [--write]
   aienvmp sbom [--dir .] [--json] [--write]
+  aienvmp summary [--dir .] [--write]
   aienvmp schema [--json]
 
 Common:
-  aienvmp sync      update AIENV.md, manifest, status, ledger, intents, and dashboard
+  aienvmp sync      update AIENV.md, manifest, status, summary, SBOM, ledger, intents, and dashboard
   aienvmp status    print one simple environment decision; --write saves .aienvmp/status.json
   aienvmp context   print the AI preflight brief
   aienvmp handoff   print the next-agent handoff summary
   aienvmp checkpoint record, sync, status, and handoff after an env change
   aienvmp plan      print a read-only AI environment action plan
   aienvmp sbom      print/write standalone light SBOM artifact
+  aienvmp summary   print/write a compact Markdown summary for AI and CI
   aienvmp schema    print the stable AI-readable output contract
   aienvmp snippet   print an AGENTS.md pointer snippet
   aienvmp dash      regenerate/open the lightweight dashboard
@@ -136,11 +140,12 @@ Advanced:
   aienvmp resolve [--dir .] --actor human:you --id <intent-id> [--status resolved|cancelled]
   aienvmp record [--dir .] --actor agent:codex --summary "updated .nvmrc" [--target node] [--before 20] [--after 24]
   aienvmp checkpoint [--dir .] --actor agent:codex --summary "updated dependency" [--target dependency]
-  aienvmp snippet [agents|claude|gemini] [--write AGENTS.md]
+  aienvmp snippet [agents|codex|claude|gemini] [--write AGENTS.md]
   aienvmp compile [--dir .]
   aienvmp diff [--dir .]
   aienvmp doctor [--dir .] [--json] [--ci] [--strict security|policy|coordination|all]
   aienvmp sbom [--dir .] [--json] [--write]
+  aienvmp summary [--dir .] [--write]
   aienvmp dash [--dir .] [--open]
 `);
 }

package/src/commands/summary.js

@@ -0,0 +1,118 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readJson } from "../fsutil.js";
+import { manifestPath, statusJsonPath, summaryMdPath, workspaceDir } from "../paths.js";
+import { statusWorkspace } from "./status.js";
+
+export async function summaryWorkspace(args) {
+  const dir = workspaceDir(args);
+  let status = await readJson(statusJsonPath(dir));
+  if (!status) {
+    status = await statusWorkspace({ ...args, dir, json: false, write: true, quiet: true });
+  }
+  const manifest = await readJson(manifestPath(dir), {});
+  const markdown = renderSummary(status, manifest);
+  const artifact = args.write ? await writeSummaryArtifact(dir, markdown) : "";
+  const output = { artifact, summary: markdown, state: status.state || "unknown", sbomRisk: status.sbomRisk || {}, nextCommand: status.nextCommand || "" };
+
+  if (args.json) {
+    console.log(JSON.stringify(output, null, 2));
+  } else if (!args.quiet) {
+    console.log(markdown.trimEnd());
+    if (artifact) console.log(`\nsummary: ${artifact}`);
+  }
+
+  return output;
+}
+
+export async function writeSummaryArtifact(dir, markdown) {
+  const out = summaryMdPath(dir);
+  await fs.mkdir(path.dirname(out), { recursive: true });
+  await fs.writeFile(out, `${markdown.trimEnd()}\n`, "utf8");
+  return out;
+}
+
+export function renderSummary(status = {}, manifest = {}) {
+  const counts = status.counts || {};
+  const sbomRisk = status.sbomRisk || manifest.lightSbom?.riskSummary || {};
+  const coordination = status.coordination || {};
+  const activity = status.agentActivity || {};
+  const workspace = manifest.workspace?.root || manifest.workspace?.name || ".";
+  const next = status.nextCommand || status.decision?.nextCommand || "aienvmp status";
+  const readFirst = status.nextAgent?.readFirst || ".aienvmp/status.json";
+  const detail = status.quickstart?.detailCommand || "aienvmp context --json";
+  const strict = status.enforcement?.recommendedCommand || "aienvmp doctor --strict all";
+  const riskLevel = sbomRisk.level || "unknown";
+  const riskScore = valueOrZero(sbomRisk.score);
+  const scanner = sbomRisk.scanner || manifest.lightSbom?.source?.scanner || "not run";
+  const riskSignals = toList(sbomRisk.signals).slice(0, 3);
+  const conflictTargets = toList(coordination.conflictTargets);
+  const multiActorTargets = toList(activity.multiActorTargets);
+  const dependencyProtocol = status.dependencyChangeProtocol || {};
+  const dependencyCommands = dependencyProtocol.commands || {};
+  const dependencyFiles = dependencyFilesFor(status.dependencyReadSet);
+
+  return [
+    "# aienvmp summary",
+    "",
+    `- state: ${status.state || "unknown"}`,
+    `- workspace: ${workspace}`,
+    `- warnings: ${valueOrZero(counts.warnings)} / open intents: ${valueOrZero(counts.openIntents)}`,
+    `- runtimes: ${valueOrZero(counts.runtimes)} / dependencies: ${valueOrZero(counts.dependencies)} / vulnerabilities: ${valueOrZero(counts.vulnerabilities)}`,
+    `- light SBOM risk: ${riskLevel} (${riskScore}) / scanner: ${scanner}`,
+    `- next: ${next}`,
+    `- AI read first: ${readFirst}, then ${detail}`,
+    `- mode: advisory by default; strict is opt-in with ${strict}`,
+    "",
+    "## AI handoff",
+    "",
+    `- environment changes: ${status.agentUse?.environmentChanges || "intent-and-review-first"}`,
+    `- coordination: ${coordination.next || "No open environment intents."}`,
+    `- recent agent activity: ${activity.next || "No environment records need coordination."}`,
+    `- conflict targets: ${conflictTargets.length ? conflictTargets.join(", ") : "none"}`,
+    `- multi-actor targets: ${multiActorTargets.length ? multiActorTargets.join(", ") : "none"}`,
+    "",
+    "## SBOM",
+    "",
+    `- source: ${manifest.lightSbom?.source?.dependencies || "project manifests"}`,
+    `- confidence: transitive ${manifest.lightSbom?.confidence?.transitiveDependencies || "not-resolved"}`,
+    `- signals: ${riskSignals.length ? riskSignals.join("; ") : "none"}`,
+    `- verify: ${sbomRisk.next || "Use a dedicated scanner for security decisions."}`,
+    "",
+    "## Dependency changes",
+    "",
+    `- read files: ${dependencyFiles.length ? dependencyFiles.join(", ") : "none detected"}`,
+    `- before: ${dependencyCommands.recordIntent || "aienvmp intent --actor agent:id --action planned-change --target dependency"}`,
+    `- after: ${dependencyCommands.checkpointAfterChange || "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency"}`,
+    `- package manager policy: ${dependencyProtocol.packageManagerPolicy || "not-detected"}`,
+    "",
+    "## Artifacts",
+    "",
+    "- AIENV.md",
+    "- .aienvmp/status.json",
+    "- .aienvmp/manifest.json",
+    "- .aienvmp/sbom.json",
+    "- .aienvmp/sbom.cdx.json",
+    "- .aienvmp/dashboard.html"
+  ].join("\n");
+}
+
+function valueOrZero(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}
+
+function toList(value) {
+  return Array.isArray(value) ? value.filter(Boolean) : [];
+}
+
+function dependencyFilesFor(readSet = []) {
+  const files = [];
+  for (const item of toList(readSet).slice(0, 3)) {
+    if (item.manifest) files.push(item.manifest);
+    for (const lockfile of toList(item.lockfiles).slice(0, 3)) {
+      const file = typeof lockfile === "string" ? lockfile : lockfile?.file;
+      if (file && !files.includes(file)) files.push(file);
+    }
+  }
+  return files.slice(0, 8);
+}

package/src/commands/sync.js

@@ -4,6 +4,7 @@ import { compileWorkspace } from "./compile.js";
 import { dashWorkspace } from "./dash.js";
 import { statusWorkspace } from "./status.js";
 import { sbomWorkspace } from "./sbom.js";
+import { summaryWorkspace } from "./summary.js";
 
 export async function syncWorkspace(args) {
   const quiet = args.quiet || args.json;
@@ -16,6 +17,7 @@ export async function syncWorkspace(args) {
   const status = await statusWorkspace({ ...next, json: false, write: true, quiet: true });
   const sbom = await sbomWorkspace({ ...next, json: false, write: true, quiet: true });
   const cyclonedx = await sbomWorkspace({ ...next, json: false, write: true, quiet: true, format: "cyclonedx-lite" });
+  const summary = await summaryWorkspace({ ...next, json: false, write: true, quiet: true });
 
   const result = {
     status: "ok",
@@ -26,6 +28,7 @@ export async function syncWorkspace(args) {
       status: status.artifact,
       sbom: sbom.artifact,
       cyclonedx: cyclonedx.artifact,
+      summary: summary.artifact,
       dashboard: dashboard.dashboard
     },
     changes: scanned.changes,
@@ -35,7 +38,7 @@ export async function syncWorkspace(args) {
   if (args.json) {
     console.log(JSON.stringify(result, null, 2));
   } else if (!quiet) {
-    console.log("sync complete: AIENV.md, manifest, status, ledger, intents, and dashboard are up to date");
+    console.log("sync complete: AIENV.md, manifest, status, SBOM, summary, ledger, intents, and dashboard are up to date");
   }
 
   return result;

package/src/contract.js

@@ -20,6 +20,12 @@ export function schemaContract() {
         command: "aienvmp status --json",
         contract: preflightContract()
       },
+      summary: {
+        file: ".aienvmp/summary.md",
+        command: "aienvmp summary --write",
+        format: "markdown",
+        purpose: "Compact AI and CI step summary for quick review."
+      },
       context: {
         command: "aienvmp context --json",
         rootFields: ["status", "preflight", "coordination", "decision", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]

package/src/fsutil.js

@@ -12,12 +12,16 @@ export async function exists(file) {
 
 export async function readJson(file, fallback = null) {
   try {
-    return JSON.parse(await fs.readFile(file, "utf8"));
+    return JSON.parse(stripBom(await fs.readFile(file, "utf8")));
   } catch {
     return fallback;
   }
 }
 
+export function stripBom(value) {
+  return String(value).replace(/^\uFEFF/, "");
+}
+
 export async function writeJson(file, data) {
   await fs.mkdir(path.dirname(file), { recursive: true });
   await fs.writeFile(file, `${JSON.stringify(data, null, 2)}\n`, "utf8");

package/src/paths.js

@@ -48,6 +48,10 @@ export function planMdPath(dir) {
   return path.join(stateDir(dir), "plan.md");
 }
 
+export function summaryMdPath(dir) {
+  return path.join(stateDir(dir), "summary.md");
+}
+
 export function aiEnvPath(dir) {
   return path.join(dir, "AIENV.md");
 }

package/src/preflight.js

@@ -66,6 +66,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     artifacts: preflightArtifacts(),
     readOrder: [
       ".aienvmp/status.json",
+      ".aienvmp/summary.md",
       "AIENV.md",
       ".aienvmp/manifest.json",
       ".aienvmp/plan.json",
@@ -195,6 +196,7 @@ function nextAgentHint(state, dependencyReadSet = [], dependencyChangeProtocol =
   return {
     handoffCommand: dependencyChangeProtocol.commands?.handoff || "aienvmp handoff --record --actor agent:id",
     readFirst: ".aienvmp/status.json",
+    readSummary: ".aienvmp/summary.md",
     readNext: "aienvmp context --json",
     reviewState: state,
     dependencyFiles,
@@ -351,6 +353,7 @@ function agentQuickstart(reviewRequired) {
 export function preflightArtifacts() {
   return {
     status: ".aienvmp/status.json",
+    summary: ".aienvmp/summary.md",
     envMap: "AIENV.md",
     manifest: ".aienvmp/manifest.json",
     sbom: ".aienvmp/sbom.json",

package/src/render.js

@@ -114,18 +114,30 @@ function preflightLines(preflight = {}) {
 
 export function renderAgentPointer(target = "agents") {
   const label = target === "claude" ? "Claude" : target === "gemini" ? "Gemini" : "AI agents";
+  const actor = target === "claude"
+    ? "agent:claude"
+    : target === "gemini"
+      ? "agent:gemini"
+      : target === "codex"
+        ? "agent:codex"
+        : "agent:id";
   return `## aienvmp Environment Map
 
 ${label} should use \`aienvmp\` as the workspace environment source of truth.
 
-Before changing runtimes, package managers, Docker settings, global packages, or environment policy:
+Fast read order:
 
 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 checkpoint --actor agent:id --summary what-changed --target environment\`.
+2. Read \`.aienvmp/summary.md\` for the short handoff.
+3. Run \`aienvmp context --json\` for details.
+4. Read \`AIENV.md\` when Markdown context is easier.
+
+Before changing runtimes, package managers, Docker settings, global packages, dependencies, lockfiles, or environment policy:
+
+1. If status or context says \`review-required\`, ask the user before changing the environment.
+2. Record planned environment changes with the recommended target, for example \`aienvmp intent --actor ${actor} --action planned-change --target dependency\`.
+3. Prefer project-local version files and local environments.
+4. After accepted environment changes, run \`aienvmp checkpoint --actor ${actor} --summary what-changed --target environment\`.
 
 \`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
 }