aienvmp 0.1.0 → 0.1.2

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

@@ -0,0 +1,74 @@
+---
+name: aienvmp
+description: Use before changing runtimes, package managers, Docker settings, global packages, or environment policy in an AI coding workspace. Reads aienvmp context, prevents AI-driven version drift, records intent before environment changes, and records what changed afterward.
+---
+
+# aienvmp
+
+Use `aienvmp` as the shared environment source of truth for this workspace.
+
+The goal is to help multiple AI agents avoid silently installing or using different versions of Node, Python, Docker, package managers, or global tools.
+
+## Preflight
+
+Before environment-impacting work, run:
+
+```bash
+npx aienvmp context
+```
+
+If the output says `review-required`, do not change global runtimes, package managers, Docker settings, or global packages without asking the user.
+
+For machine-readable context, use:
+
+```bash
+npx aienvmp context --json
+```
+
+## Before Environment Changes
+
+Record intent before changing shared environment state:
+
+```bash
+npx aienvmp intent --actor agent:codex --action "<planned change>" --target "<tool-or-runtime>"
+```
+
+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 Docker daemon/context assumptions
+
+## After Environment Changes
+
+Refresh the environment map:
+
+```bash
+npx aienvmp sync
+```
+
+Record what changed:
+
+```bash
+npx aienvmp record --actor agent:codex --summary "<what changed>" --target "<tool-or-runtime>" --evidence "<command or file>"
+```
+
+Resolve the original intent if complete:
+
+```bash
+npx aienvmp resolve --actor agent:codex --id "<intent-id>"
+```
+
+## Safety Rules
+
+- `aienvmp` warnings are non-blocking by default.
+- 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 use warnings as permission to interrupt production or shared workspace operations.
+- Use `npx aienvmp doctor --ci` only in CI or explicit strict-mode automation.
+
+## Normal Coding Work
+
+For ordinary source edits that do not affect runtime versions, package managers, Docker settings, global packages, or environment policy, you do not need to record an intent.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.2
+
+- Added `aienvmp sync` as the simple one-step command for init, scan, `AIENV.md`, manifest, ledger, and dashboard generation.
+- Improved AI preflight context with an explicit next action.
+- Repositioned AGENTS.md integration as an optional snippet instead of default file generation.
+- Added machine-readable sync/context improvements for AI and CI integrations.
+- Simplified README for faster first-time understanding.
+- Kept AGENTS.md, CLAUDE.md, and GEMINI.md integration explicit through `aienvmp snippet`.
+
+## 0.1.1
+
+- Added repo-scoped Codex skill wrapper.
+- Normalized npm package metadata and published the initial npm package.
+
 ## 0.1.0
 
 - Initial AI-first env map prototype.

package/README.md

@@ -4,295 +4,72 @@
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](package.json)
 
-**aienvmp = AI Environment Map**
+**AI Environment Map.**
 
-`aienvmp` is an AI-first environment map and change ledger for shared AI coding workspaces.
+`aienvmp` gives AI agents a shared view of the current dev environment:
 
-It helps multiple AI coding agents read the same runtime state, avoid installing or using conflicting software versions, declare environment-changing intent, record what changed, and keep humans informed through a lightweight dashboard.
+- runtime versions
+- package managers
+- Docker state
+- project version hints
+- planned env changes
+- recent env changes
 
-It is intentionally small: use it beside SBOM scanners, vulnerability scanners, version managers, and CI systems.
+So multiple AI agents do not silently use or install different software versions.
 
-## Why
-
-Shared development machines drift.
-
-One person upgrades Node. Another AI agent installs a global Python tool. A different agent assumes Docker is available. A third agent uses the wrong package manager because it did not see the project lockfile.
-
-After a few sessions, nobody is quite sure which runtime is safe to use.
-
-`aienvmp` is designed to prevent that kind of AI-driven version drift.
-
-It is also designed to stay out of the operator's way. By default, `aienvmp` reports warnings and review-required states instead of taking locks, blocking commands, or changing the machine.
-
-`aienvmp` turns that machine state into:
-
-- `AIENV.md`: an AI-readable environment protocol
-- `.aienvmp/manifest.json`: a lightweight runtime SBOM
-- `.aienvmp/timeline.jsonl`: an append-only environment change ledger
-- `.aienvmp/intents.jsonl`: planned and resolved environment-changing actions
-- `.aienvmp/dashboard.html`: a small human-readable dashboard
-
-## Core Idea
-
-Before an AI changes the environment, it should know the environment.
-
-Before an AI installs or uses a runtime, it should check the shared policy.
-
-The policy is advisory by default. It should guide AI agents and humans, not unexpectedly interrupt production or shared workspace operations.
-
-```bash
-aienvmp context
-aienvmp intent --actor agent:codex --action "install pnpm" --target pnpm
-# make the change
-aienvmp scan
-aienvmp compile
-aienvmp record --actor agent:codex --summary "installed pnpm" --target pnpm --evidence "pnpm --version"
-aienvmp resolve --actor human:you --id int_abc123
-```
-
-## Quickstart
-
-Install with npm:
-
-```bash
-npm install -g aienvmp
-```
-
-Or run without installing:
+## Use
 
 ```bash
-npx aienvmp init
-npx aienvmp scan
+npx aienvmp sync
 npx aienvmp context
-npx aienvmp compile --agents all
-npx aienvmp dash
-```
-
-Run locally from this repository while developing:
-
-```bash
-node bin/aienvmp.js init
-node bin/aienvmp.js scan
-node bin/aienvmp.js context
-node bin/aienvmp.js compile --agents all
-node bin/aienvmp.js dash
 ```
 
-Try the included sample app:
-
-```bash
-node bin/aienvmp.js scan --dir sample-app
-node bin/aienvmp.js context --dir sample-app
-node bin/aienvmp.js dash --dir sample-app
-```
-
-## AI Agent Workflow
-
-1. Read `AIENV.md` or run `aienvmp context`.
-2. Prefer project-local version files such as `.nvmrc`, `.python-version`, `mise.toml`, and `.tool-versions`.
-3. Do not install or switch to a different runtime version when it conflicts with `.aienvmp/policy.yml`.
-4. Ask the user before changing global runtimes, global packages, Docker settings, or package managers.
-5. Record planned environment changes with `aienvmp intent`.
-6. After changes, run `aienvmp scan && aienvmp compile`.
-7. Record what changed with `aienvmp record`.
-8. Resolve the intent with `aienvmp resolve`.
-
-Agent files can be injected automatically:
-
-```bash
-aienvmp compile --agents codex,claude,gemini
-```
-
-Generated agent targets:
-
-- `AGENTS.md`
-- `CLAUDE.md`
-- `GEMINI.md`
-
-## What AI Agents See
-
-`aienvmp context` returns a compact preflight brief:
+## Output
 
 ```text
-# AI Preflight Context
-
-Status: clear
-Node: 24.14.1
-Python: 3.11.0
-Docker: available
-
-Must follow:
-- Ask the user before global runtime, package manager, Docker, or global package changes.
-- Prefer project-local version files and local environments.
-- Before planned env changes, run `aienvmp intent --actor <agent:id> --action <planned-change>`.
-- After env changes, run `aienvmp scan && aienvmp compile`.
-- Then run `aienvmp record --actor <agent:id> --summary <what-changed>`.
-```
-
-For tool integrations:
-
-```bash
-aienvmp context --json
-aienvmp doctor --json
-aienvmp doctor --ci
-```
-
-`doctor --ci` is the explicit strict path. Normal `doctor` output is advisory and exits successfully so it does not disrupt shared operations.
-
-## Commands
-
-| Command | Purpose |
-| --- | --- |
-| `init` | Create `.aienvmp/` |
-| `scan` | Collect runtime/tooling versions and write `.aienvmp/manifest.json` |
-| `context` | Print short AI preflight context |
-| `intent` | Record a planned environment-impacting action |
-| `resolve` | Mark an intent as resolved or cancelled |
-| `record` | Append an agent/human environment change to the ledger |
-| `compile` | Write `AIENV.md` and optionally inject agent files |
-| `diff` | Compare current and previous manifests |
-| `doctor` | Report environment warnings |
-| `dash` | Generate `.aienvmp/dashboard.html` |
-
-Intent IDs are short and prefix-matchable, so `aienvmp resolve --id int_mabc` works when it matches one open intent.
-
-## What It Scans Today
-
-- OS: platform, release, arch, hostname, shell
-- Runtimes: Node.js, Python, Go, Java, Rust
-- Package managers and version managers: npm, pnpm, yarn, uv, pip, pipx, mise, asdf, pyenv, nvm, fnm, volta
-- Containers: Docker and Docker Compose
-- Project hints: `.nvmrc`, `.python-version`, `mise.toml`, `.tool-versions`, lockfiles, `package.json`, `pyproject.toml`, `Dockerfile`
-- Agent integration files: Codex, Claude, Gemini, Cursor, Copilot targets
-
-## Version Drift Prevention
-
-The highest-priority use case is preventing multiple AI agents from installing or using different software versions in the same workspace.
-
-`aienvmp` checks project hints and policy against the currently detected environment.
-
-Example `.aienvmp/policy.yml`:
-
-```yaml
-node: 24
-python: 3.11
-packageManager: npm
-globalInstalls: ask-first
-runtimeChanges: ask-first
-```
-
-If an AI tries to use Node 22 when policy requires Node 24, `aienvmp doctor` and `aienvmp context` should surface that mismatch before work continues.
-
-Example warning:
-
-```text
-.aienvmp/policy.yml requires node 24, but detected 22.11.0.
-```
-
-Normal commands remain non-blocking. Use CI/strict mode only when you explicitly want a warning to fail automation.
-
-## Output Layout
-
-```text
-.aienvmp/
-  manifest.json
-  timeline.jsonl
-  intents.jsonl
-  dashboard.html
 AIENV.md
-AGENTS.md
-CLAUDE.md
-GEMINI.md
+.aienvmp/manifest.json
+.aienvmp/intents.jsonl
+.aienvmp/timeline.jsonl
+.aienvmp/dashboard.html
 ```
 
-## Dashboard
+## For AGENTS.md
 
-The dashboard is a static HTML file. It is derived from the manifest, warnings, intents, and ledger.
+`aienvmp` does not replace AGENTS.md. It gives AGENTS.md a live environment source of truth.
 
 ```bash
-aienvmp dash
-```
-
-Open:
-
-```text
-.aienvmp/dashboard.html
+npx aienvmp snippet agents
 ```
 
-## GitHub Action
-
-Use `aienvmp` in CI without making it disruptive by default:
+## Commands
 
-```yaml
-- uses: soovwv/aienvmp@main
-  with:
-    directory: "."
-    agents: "codex,claude,gemini"
-    strict: "false"
+```bash
+aienvmp sync              # update env map, light SBOM, ledger, dashboard
+aienvmp context           # AI preflight brief
+aienvmp context --json    # machine-readable AI decision context
+aienvmp intent            # record a planned env change
+aienvmp record            # record what changed
+aienvmp doctor --ci       # strict CI check
 ```
 
-Set `strict: "true"` only when you want policy warnings to fail automation.
-
-See [examples/github-action.yml](examples/github-action.yml).
-
-## How This Differs From SBOM Tools
-
-`aienvmp` is not trying to replace full SBOM or security scanners.
-
-Tools like Syft, Trivy, Dependency-Track, and osquery are excellent for component inventory, vulnerability scanning, and system instrumentation.
-
-`aienvmp` focuses on a narrower AI workflow:
-
-- What environment should this AI agent assume?
-- What must it avoid changing globally?
-- What changed recently?
-- Which agent planned or performed the change?
-- What should the next agent read before continuing?
-
-Think of it as an **AI coordination layer over a lightweight runtime SBOM**.
-
-## Why It Is Different
-
-- **AI-first**: the primary consumer is an AI coding agent, not only a human operator.
-- **Version drift prevention**: policy warnings are designed to stop agents from silently using different Node, Python, Docker, or package manager assumptions.
-- **Change intent before change**: agents can declare intent before touching shared environment state.
-- **Append-only ledger**: environment-impacting changes are recorded for the next agent.
-- **Non-blocking operations**: normal warnings do not lock or break the machine; strict mode is opt-in.
-- **Small surface area**: no daemon, no database, no hosted service required.
+## Principles
 
-## Project Links
-
-- [Roadmap](ROADMAP.md)
-- [Security policy](SECURITY.md)
-- [Contributing](CONTRIBUTING.md)
-
-## Status
-
-This is an early prototype.
-
-Good fit today:
-
-- shared development servers
-- AI coding workspaces
-- local projects using Codex, Claude, Gemini, Cursor, or Copilot
-- self-hosted runner experiments
-
-Planned next:
-
-- deeper policy enforcement
-- deeper nvm/fnm/volta/pyenv/mise/asdf scans
-- global npm, pipx, and uv tool inventory
-
-See [ROADMAP.md](ROADMAP.md) for the longer plan.
+- simple by default
+- AI-first
+- lightweight
+- non-blocking unless strict mode is requested
 
 ## Development
 
 ```bash
 node --test
-npm pack --dry-run
 npm run smoke
+npm pack --dry-run
 ```
 
-## License
+## Links
+
+[Roadmap](ROADMAP.md) / [Security](SECURITY.md) / [Contributing](CONTRIBUTING.md)
 
 Apache-2.0

package/action.yml

@@ -7,10 +7,6 @@ inputs:
     description: Workspace directory to scan
     required: false
     default: "."
-  agents:
-    description: Agent files to inject during compile
-    required: false
-    default: ""
   strict:
     description: Fail when doctor reports warnings
     required: false
@@ -19,18 +15,9 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Scan environment
-      shell: bash
-      run: node "$GITHUB_ACTION_PATH/bin/aienvmp.js" scan --dir "${{ inputs.directory }}"
-
-    - name: Compile agent context
+    - name: Sync environment map
       shell: bash
-      run: |
-        if [ -n "${{ inputs.agents }}" ]; then
-          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" compile --dir "${{ inputs.directory }}" --agents "${{ inputs.agents }}"
-        else
-          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" compile --dir "${{ inputs.directory }}"
-        fi
+      run: node "$GITHUB_ACTION_PATH/bin/aienvmp.js" sync --dir "${{ inputs.directory }}" --quiet
 
     - name: Doctor
       shell: bash

package/examples/github-action.yml

@@ -13,5 +13,4 @@ jobs:
       - uses: soovwv/aienvmp@main
         with:
           directory: "."
-          agents: "codex,claude,gemini"
           strict: "false"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aienvmp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI-first environment maps and lightweight runtime SBOMs for shared development machines.",
   "type": "module",
   "bin": {
@@ -24,7 +24,8 @@
     "SECURITY.md",
     "ROADMAP.md",
     "action.yml",
-    "examples"
+    "examples",
+    ".agents"
   ],
   "scripts": {
     "test": "node --test",

package/src/cli.js

@@ -8,6 +8,9 @@ import { contextWorkspace } from "./commands/context.js";
 import { recordWorkspace } from "./commands/record.js";
 import { intentWorkspace } from "./commands/intent.js";
 import { resolveWorkspace } from "./commands/resolve.js";
+import { syncWorkspace } from "./commands/sync.js";
+import { snippetWorkspace } from "./commands/snippet.js";
+import { readFileSync } from "node:fs";
 
 const commands = new Map([
   ["init", initWorkspace],
@@ -19,10 +22,12 @@ const commands = new Map([
   ["context", contextWorkspace],
   ["record", recordWorkspace],
   ["intent", intentWorkspace],
-  ["resolve", resolveWorkspace]
+  ["resolve", resolveWorkspace],
+  ["sync", syncWorkspace],
+  ["snippet", snippetWorkspace]
 ]);
 
-const version = "0.1.0";
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
 export async function main(argv) {
   const [command, ...rest] = argv;
@@ -67,13 +72,23 @@ function printUsage() {
   console.log(`aienvmp - AI-first env map + lightweight runtime SBOM
 
 Usage:
+  aienvmp sync [--dir .] [--json] [--quiet]
+  aienvmp context [--dir .] [--json]
+
+Common:
+  aienvmp sync      update AIENV.md, manifest, ledger, intents, and dashboard
+  aienvmp context   print the AI preflight brief
+  aienvmp snippet   print an AGENTS.md pointer snippet
+  aienvmp dash      regenerate/open the lightweight dashboard
+
+Advanced:
   aienvmp init [--dir .]
   aienvmp scan [--dir .]
-  aienvmp context [--dir .] [--json]
   aienvmp intent [--dir .] --actor agent:codex --action "install pnpm"
   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 compile [--dir .] [--agents all|codex,claude,gemini]
+  aienvmp snippet [agents|claude|gemini] [--write AGENTS.md]
+  aienvmp compile [--dir .]
   aienvmp diff [--dir .]
   aienvmp doctor [--dir .] [--json] [--ci]
   aienvmp dash [--dir .] [--open]

package/src/commands/compile.js

@@ -1,41 +1,25 @@
 import fs from "node:fs/promises";
-import path from "node:path";
 import { diagnose } from "../doctor.js";
-import { readJson, replaceMarkerBlock } from "../fsutil.js";
+import { readJson } from "../fsutil.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { aiEnvPath, intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
-import { markerBegin, markerEnd, renderAgentBlock, renderAIEnv } from "../render.js";
+import { renderAIEnv } from "../render.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
 
-const agentFiles = {
-  codex: "AGENTS.md",
-  claude: "CLAUDE.md",
-  gemini: "GEMINI.md"
-};
-
 export async function compileWorkspace(args) {
   const dir = workspaceDir(args);
   const manifest = await readJson(manifestPath(dir));
-  if (!manifest) throw new Error("missing manifest; run `aienvmp scan` first");
+  if (!manifest) throw new Error("missing manifest; run `aienvmp sync` first");
   const timeline = await readTimeline(timelinePath(dir));
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest), ...policyWarnings(manifest, policy)];
   const rendered = renderAIEnv(manifest, timeline, warnings, intents, policy);
   await fs.writeFile(aiEnvPath(dir), rendered, "utf8");
-  const agents = parseAgents(args.agents);
-  const block = renderAgentBlock(manifest);
-  for (const agent of agents) {
-    const rel = agentFiles[agent];
-    if (!rel) continue;
-    await replaceMarkerBlock(path.join(dir, rel), markerBegin, markerEnd, block);
+  if (!args.quiet) {
+    console.log(`compiled ${aiEnvPath(dir)}`);
   }
-  console.log(`compiled ${aiEnvPath(dir)}`);
-  if (agents.length) console.log(`injected: ${agents.join(", ")}`);
-}
-
-function parseAgents(value) {
-  if (!value) return [];
-  if (value === true || value === "all") return Object.keys(agentFiles);
-  return String(value).split(",").map((v) => v.trim()).filter(Boolean);
+  return {
+    aiEnv: aiEnvPath(dir)
+  };
 }

package/src/commands/context.js

@@ -8,14 +8,17 @@ import { loadPolicy, policyWarnings } from "../policy.js";
 export async function contextWorkspace(args) {
   const dir = workspaceDir(args);
   const manifest = await readJson(manifestPath(dir));
-  if (!manifest) throw new Error("missing manifest; run `aienvmp scan` first");
+  if (!manifest) throw new Error("missing manifest; run `aienvmp sync` first");
   const timeline = await readTimeline(timelinePath(dir));
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest), ...policyWarnings(manifest, policy)];
+  const decision = contextDecision(warnings, intents);
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "review-required" : "clear",
+      decision,
+      guidance: decision,
       workspace: manifest.workspace,
       runtimes: manifest.runtimes,
       packageManagers: manifest.packageManagers,
@@ -31,3 +34,25 @@ export async function contextWorkspace(args) {
   }
   console.log(renderContext(manifest, timeline, warnings, intents, policy));
 }
+
+function contextDecision(warnings, intents) {
+  const reviewRequired = warnings.length > 0 || intents.length > 0;
+  return {
+    canProceed: !reviewRequired,
+    safeForProjectLocalWork: warnings.length === 0,
+    reviewRequired,
+    environmentChangeRequiresIntent: true,
+    globalEnvironmentChangesRequireUserApproval: true,
+    pendingIntentCount: intents.length,
+    mustNotDo: [
+      "do not change global runtimes without user approval",
+      "do not install or remove global package managers without user approval",
+      "do not change Docker daemon/context assumptions without user approval",
+      "do not ignore open intents or review-required warnings"
+    ],
+    recommendedNextActions: warnings.length
+      ? ["review warnings", "ask the user before environment changes", "record intent before changes"]
+      : ["continue with project-local work", "run aienvmp intent before environment changes"],
+    nextCommand: warnings.length ? "review warnings before changing environment" : "continue with project-local work"
+  };
+}

package/src/commands/dash.js

@@ -11,7 +11,7 @@ import { loadPolicy, policyWarnings } from "../policy.js";
 export async function dashWorkspace(args) {
   const dir = workspaceDir(args);
   const manifest = await readJson(manifestPath(dir));
-  if (!manifest) throw new Error("missing manifest; run `aienvmp scan` first");
+  if (!manifest) throw new Error("missing manifest; run `aienvmp sync` first");
   const timeline = await readTimeline(timelinePath(dir));
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
@@ -20,8 +20,9 @@ export async function dashWorkspace(args) {
   const out = dashboardPath(dir);
   await fs.mkdir(path.dirname(out), { recursive: true });
   await fs.writeFile(out, html, "utf8");
-  console.log(`dashboard: ${out}`);
+  if (!args.quiet) console.log(`dashboard: ${out}`);
   if (args.open) openFile(out);
+  return { dashboard: out };
 }
 
 function openFile(file) {

package/src/commands/diff.js

@@ -6,7 +6,7 @@ export async function diffWorkspace(args) {
   const dir = workspaceDir(args);
   const previous = await readJson(previousManifestPath(dir));
   const current = await readJson(manifestPath(dir));
-  if (!current) throw new Error("missing manifest; run `aienvmp scan` first");
+  if (!current) throw new Error("missing manifest; run `aienvmp sync` first");
   const changes = diffManifests(previous, current);
   if (!changes.length) {
     console.log("no environment changes detected");

package/src/commands/doctor.js

@@ -6,7 +6,7 @@ import { loadPolicy, policyWarnings } from "../policy.js";
 export async function doctorWorkspace(args) {
   const dir = workspaceDir(args);
   const manifest = await readJson(manifestPath(dir));
-  if (!manifest) throw new Error("missing manifest; run `aienvmp scan` first");
+  if (!manifest) throw new Error("missing manifest; run `aienvmp sync` first");
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest), ...policyWarnings(manifest, policy)];
   if (args.json) {

package/src/commands/init.js

@@ -15,5 +15,6 @@ export async function initWorkspace(args) {
     "runtimeChanges: ask-first",
     ""
   ].join("\n"), { flag: "wx" }).catch(() => {});
-  console.log(`initialized ${stateDir(dir)}`);
+  if (!args.quiet) console.log(`initialized ${stateDir(dir)}`);
+  return { stateDir: stateDir(dir) };
 }

package/src/commands/scan.js

@@ -22,7 +22,15 @@ export async function scanWorkspace(args) {
       change
     });
   }
-  console.log(`scanned ${dir}`);
-  console.log(`manifest: ${currentPath}`);
-  console.log(`changes: ${changes.length}`);
+  if (!args.quiet) {
+    console.log(`scanned ${dir}`);
+    console.log(`manifest: ${currentPath}`);
+    console.log(`changes: ${changes.length}`);
+  }
+  return {
+    dir,
+    manifest: currentPath,
+    timeline: timelinePath(dir),
+    changes: changes.length
+  };
 }

package/src/commands/snippet.js

@@ -0,0 +1,27 @@
+import path from "node:path";
+import { markerBegin, markerEnd, renderAgentPointer } from "../render.js";
+import { replaceMarkerBlock } from "../fsutil.js";
+import { workspaceDir } from "../paths.js";
+
+const defaultTargets = {
+  agents: "AGENTS.md",
+  codex: "AGENTS.md",
+  claude: "CLAUDE.md",
+  gemini: "GEMINI.md"
+};
+
+export async function snippetWorkspace(args) {
+  const target = String(args._?.[0] || args.agent || "agents").toLowerCase();
+  const block = renderAgentPointer(target);
+
+  if (args.write) {
+    const dir = workspaceDir(args);
+    const rel = args.write === true ? defaultTargets[target] || "AGENTS.md" : String(args.write);
+    await replaceMarkerBlock(path.join(dir, rel), markerBegin, markerEnd, block);
+    if (!args.quiet) console.log(`snippet written: ${rel}`);
+    return { file: rel, target };
+  }
+
+  console.log(block);
+  return { target };
+}

package/src/commands/sync.js

@@ -0,0 +1,34 @@
+import { initWorkspace } from "./init.js";
+import { scanWorkspace } from "./scan.js";
+import { compileWorkspace } from "./compile.js";
+import { dashWorkspace } from "./dash.js";
+
+export async function syncWorkspace(args) {
+  const quiet = args.quiet || args.json;
+  const next = { ...args, quiet };
+
+  const initialized = await initWorkspace(next);
+  const scanned = await scanWorkspace(next);
+  const compiled = await compileWorkspace(next);
+  const dashboard = await dashWorkspace(next);
+
+  const result = {
+    status: "ok",
+    outputs: {
+      aiEnv: compiled.aiEnv,
+      manifest: scanned.manifest,
+      timeline: scanned.timeline,
+      dashboard: dashboard.dashboard
+    },
+    changes: scanned.changes,
+    initialized: initialized.stateDir
+  };
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!quiet) {
+    console.log("sync complete: AIENV.md, manifest, ledger, intents, and dashboard are up to date");
+  }
+
+  return result;
+}

package/src/manifest.js

@@ -7,8 +7,13 @@ import { exists } from "./fsutil.js";
 export async function buildManifest(dir) {
   const now = new Date().toISOString();
   const manifest = {
+    schemaName: "aienvmp.runtime-sbom",
     schemaVersion: 1,
     generatedAt: now,
+    generatedBy: {
+      name: "aienvmp",
+      command: "aienvmp sync"
+    },
     workspace: {
       path: dir,
       name: path.basename(dir)
@@ -24,10 +29,51 @@ export async function buildManifest(dir) {
       preflightCommand: "aienvmp context",
       intentCommand: "aienvmp intent --actor <agent:id> --action <planned-change>",
       recordCommand: "aienvmp record --actor <agent:id> --summary <what-changed>",
-      afterEnvironmentChange: ["aienvmp scan", "aienvmp compile"],
+      afterEnvironmentChange: ["aienvmp sync"],
       globalRuntimeChangeRequiresUserApproval: true,
       globalInstallPolicy: "ask-first",
       projectLocalChanges: "allowed-when-task-requires"
+    },
+    evidence: {
+      runtimes: {
+        node: "node --version",
+        python: "python --version",
+        python3: "python3 --version",
+        go: "go version",
+        java: "java -version",
+        rustc: "rustc --version"
+      },
+      packageManagers: {
+        npm: "npm --version",
+        pnpm: "pnpm --version",
+        yarn: "yarn --version",
+        uv: "uv --version",
+        pip: "pip --version",
+        pipx: "pipx --version",
+        mise: "mise --version",
+        asdf: "asdf --version",
+        pyenv: "pyenv --version",
+        nvm: "nvm --version",
+        fnm: "fnm --version",
+        volta: "volta --version"
+      },
+      containers: {
+        docker: "docker --version",
+        compose: "docker compose version or docker-compose --version"
+      },
+      projectHints: [
+        ".nvmrc",
+        ".python-version",
+        "mise.toml",
+        ".tool-versions",
+        "package.json",
+        "pyproject.toml",
+        "requirements.txt",
+        "Dockerfile",
+        "package-lock.json",
+        "pnpm-lock.yaml",
+        "yarn.lock"
+      ]
     }
   };
   return manifest;

package/src/render.js

@@ -13,7 +13,7 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   lines.push("2. Prefer project-local version files such as `.nvmrc`, `.python-version`, `mise.toml`, and `.tool-versions`.");
   lines.push("3. Ask the user before changing global environment state.");
   lines.push("4. Record planned environment changes with `aienvmp intent --actor <agent:id> --action <planned-change>`.");
-  lines.push("5. After environment changes, run `aienvmp scan && aienvmp compile`.");
+  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("## Current Policy", "");
   lines.push(...policyLines(policy));
@@ -57,31 +57,32 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   return lines.join("\n");
 }
 
-export function renderAgentBlock(manifest) {
-  const node = manifest.runtimes.node || "not detected";
-  const python = manifest.runtimes.python || manifest.runtimes.python3 || "not detected";
-  const docker = manifest.containers.docker ? "available" : "not detected";
-  return `AI environment map is maintained by aienvmp.
+export function renderAgentPointer(target = "agents") {
+  const label = target === "claude" ? "Claude" : target === "gemini" ? "Gemini" : "AI agents";
+  return `## aienvmp Environment Map
 
-Before changing runtimes, package managers, Docker, or global packages:
-1. Read AIENV.md.
-2. Run \`aienvmp context\`.
-3. Ask the user before global environment changes.
-4. Record planned changes with \`aienvmp intent\`.
-5. After changes, run \`aienvmp scan && aienvmp compile\`.
+${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\`.
 
-Default detected tools:
-- Node.js: ${node}
-- Python: ${python}
-- Docker: ${docker}`;
+\`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
 }
 
 export function renderContext(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
+  const status = warnings.length ? "review-required" : "clear";
+  const next = warnings.length ? "Review warnings before changing the environment." : "Continue with project-local work. Record intent before environment changes.";
   return [
     "# AI Preflight Context",
     "",
-    `Status: ${warnings.length ? "review-required" : "clear"}`,
+    `Status: ${status}`,
+    `Next: ${next}`,
     `Workspace: ${manifest.workspace.path}`,
     `Node: ${manifest.runtimes.node || "not detected"}`,
     `Python: ${manifest.runtimes.python || manifest.runtimes.python3 || "not detected"}`,
@@ -95,7 +96,7 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     "- Treat policy mismatches as review-required, not as permission to break ongoing operations.",
     "- Prefer project-local version files and local environments.",
     "- Before planned env changes, run `aienvmp intent --actor <agent:id> --action <planned-change>`.",
-    "- After env changes, run `aienvmp scan && aienvmp compile`.",
+    "- After env changes, run `aienvmp sync`.",
     "- Then run `aienvmp record --actor <agent:id> --summary <what-changed>`.",
     "",
     "Warnings:",
@@ -159,9 +160,8 @@ const entries=o=>Object.entries(o||{});
 const rows=o=>entries(o).map(([k,v])=>\`<tr><th>\${esc(k)}</th><td><code>\${esc(String(v))}</code></td></tr>\`).join('')||'<tr><td colspan="2">None detected</td></tr>';
 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 totalTools=entries(manifest.runtimes).length+entries(manifest.packageManagers).length+entries(manifest.containers).length;
 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]?'connected':'not connected'}</span></div>\`).join('');
+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 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>';
@@ -196,7 +196,7 @@ document.getElementById('app').innerHTML=\`
     <div style="height:14px"></div>
     \${card('Agent Intents','<span class="pill">'+intents.length+' open</span>',intentsHtml)}
     <div style="height:14px"></div>
-    \${card('Agent Integration','<span class="pill">'+totalTools+' tools</span>','<div class="agents">'+agentCards+'</div>')}
+    \${card('Agent Pointers','<span class="pill">'+entries(manifest.agentFiles).filter(([,v])=>v).length+' detected</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>
@@ -236,6 +236,7 @@ function formatTimeline(item) {
 function contextLines(manifest, warnings, intents) {
   return [
     `- Status: ${warnings.length ? "review-required" : "clear"}`,
+    `- Next: ${warnings.length ? "review warnings before environment changes" : "continue with project-local work"}`,
     `- Node: ${manifest.runtimes.node || "not detected"}`,
     `- Python: ${manifest.runtimes.python || manifest.runtimes.python3 || "not detected"}`,
     `- Docker: ${manifest.containers.docker ? "available" : "not detected"}`,