@pieai/pro-gov 0.3.3 → 0.3.4

package/dist/cli.js

@@ -30,6 +30,7 @@ function isValidProfile(profile) {
 function listFiles(dir) {
   const files = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (isPlatformMetadata(entry.name)) continue;
     const absolutePath = join(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...listFiles(absolutePath));
@@ -42,27 +43,1194 @@ function listFiles(dir) {
 function toUnixPath(path) {
   return path.replaceAll("\\", "/");
 }
+function isPlatformMetadata(name) {
+  return name === ".DS_Store" || name === "Thumbs.db" || name.startsWith("._");
+}
+
+// src/commands/assets.ts
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname5 } from "node:path";
+
+// src/asset-bundles/bundles.ts
+import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+function loadAgentAssetBundles(agentAssetsDir) {
+  const bundlesDir = join2(agentAssetsDir, "bundles");
+  if (!existsSync2(bundlesDir)) return [];
+  return readdirSync2(bundlesDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => {
+    const bundlePath = join2(bundlesDir, entry.name);
+    return JSON.parse(readFileSync(bundlePath, "utf8"));
+  }).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+// src/asset-npx/maintenance.ts
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync as existsSync3, mkdirSync, mkdtempSync, readdirSync as readdirSync3, readFileSync as readFileSync2, statSync } from "node:fs";
+import { join as join3, relative as relative2 } from "node:path";
+import { tmpdir } from "node:os";
+function createNpxSkillsMaintenancePlan(options) {
+  assertNativeNpxRoot(options.npxRoot);
+  if (options.operation === "add" && !options.source) {
+    throw new Error("npx skills add requires a source.");
+  }
+  const before = snapshotFiles(options.npxRoot);
+  const tempRoot = mkdtempSync(join3(tmpdir(), "pro-gov-npx-skills-"));
+  cpSync(options.npxRoot, tempRoot, { recursive: true, dereference: false });
+  const command2 = buildNpxCommand(options);
+  const runner = options.runner ?? defaultRunner;
+  const result = runner({ command: command2, cwd: tempRoot });
+  if (result.status !== 0) {
+    throw new Error(`npx skills ${options.operation} failed with exit code ${result.status}`);
+  }
+  if (options.operation === "update") {
+    assertNoReportedPartialUpdateFailure(result.stdout, result.stderr);
+  }
+  const after = snapshotFiles(tempRoot);
+  const changes = diffSnapshots(before, after);
+  return {
+    schemaVersion: 1,
+    operation: options.operation,
+    npxRoot: options.npxRoot,
+    tempRoot,
+    command: command2,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.status ?? 0,
+    changes,
+    summary: summarizeChanges(changes),
+    appliedToRealRoot: false
+  };
+}
+function assertNoReportedPartialUpdateFailure(stdout, stderr) {
+  const output = `${stdout}
+${stderr}`.replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, "");
+  const failure = output.match(/Failed to update\s+\d+\s+skill\(s\)/i);
+  if (failure) {
+    throw new Error(`npx skills update reported a partial failure: ${failure[0]}`);
+  }
+}
+function assertNativeNpxRoot(npxRoot) {
+  if (!existsSync3(join3(npxRoot, "skills-lock.json"))) {
+    throw new Error(`npx skills root is missing skills-lock.json: ${npxRoot}`);
+  }
+  if (!existsSync3(join3(npxRoot, ".agents/skills"))) {
+    throw new Error(`npx skills root is missing .agents/skills: ${npxRoot}`);
+  }
+}
+function buildNpxCommand(options) {
+  if (options.operation === "add") {
+    const command3 = ["npx", "--yes", "skills", "add", options.source ?? ""];
+    if (options.skill) command3.push("--skill", options.skill);
+    return command3;
+  }
+  const command2 = ["npx", "--yes", "skills", "update", "-p", "-y"];
+  if (options.skill) command2.push(options.skill);
+  return command2;
+}
+function defaultRunner({ command: command2, cwd }) {
+  const result = spawnSync(command2[0] ?? "npx", command2.slice(1), { cwd, encoding: "utf8" });
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr
+  };
+}
+function snapshotFiles(root) {
+  const snapshot = /* @__PURE__ */ new Map();
+  for (const filePath of listFiles2(root)) {
+    const relativePath = toUnixPath2(relative2(root, filePath));
+    snapshot.set(relativePath, hashFile(filePath));
+  }
+  return snapshot;
+}
+function listFiles2(root) {
+  const files = [];
+  collectFiles(root, root, files);
+  return files.sort();
+}
+function collectFiles(root, current, files) {
+  mkdirSync(root, { recursive: true });
+  for (const entry of readdirSync3(current, { withFileTypes: true })) {
+    const entryPath = join3(current, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(root, entryPath, files);
+    } else if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+}
+function hashFile(path) {
+  const hash = createHash("sha256");
+  const stats = statSync(path);
+  hash.update(String(stats.size));
+  hash.update("\0");
+  hash.update(readFileSync2(path));
+  return hash.digest("hex");
+}
+function diffSnapshots(before, after) {
+  const changes = [];
+  for (const [path, hash] of after) {
+    if (!before.has(path)) {
+      changes.push({ type: "added", path });
+    } else if (before.get(path) !== hash) {
+      changes.push({ type: "modified", path });
+    }
+  }
+  for (const path of before.keys()) {
+    if (!after.has(path)) changes.push({ type: "deleted", path });
+  }
+  return changes.sort((a, b) => a.path.localeCompare(b.path) || a.type.localeCompare(b.type));
+}
+function summarizeChanges(changes) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const change of changes) counts.set(change.type, (counts.get(change.type) ?? 0) + 1);
+  return `added=${counts.get("added") ?? 0} modified=${counts.get("modified") ?? 0} deleted=${counts.get("deleted") ?? 0}`;
+}
+function toUnixPath2(path) {
+  return path.replaceAll("\\", "/");
+}
+
+// src/asset-registry/loader.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync3, statSync as statSync2 } from "node:fs";
+import { dirname as dirname2, join as join5, relative as relative3 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/asset-registry/registry.ts
+import { existsSync as existsSync4, lstatSync } from "node:fs";
+import { isAbsolute, join as join4, posix } from "node:path";
+var supportedFamilies = /* @__PURE__ */ new Set([
+  "pie-skills",
+  "dokobot",
+  "npx-skills",
+  "pie-rules",
+  "pie-commands"
+]);
+var supportedKinds = /* @__PURE__ */ new Set(["skill", "rule", "command"]);
+var supportedVisibilities = /* @__PURE__ */ new Set([
+  "public",
+  "private",
+  "third-party"
+]);
+var supportedSourceKinds = /* @__PURE__ */ new Set(["local", "local-pack", "npx"]);
+var supportedHosts = /* @__PURE__ */ new Set([
+  "codex",
+  "claude-code",
+  "gemini-cli",
+  "antigravity"
+]);
+function validateAssetRegistry(registry, options = {}) {
+  const issues = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const asset of registry.assets) {
+    if (seenIds.has(asset.id)) {
+      issues.push({
+        type: "duplicate-id",
+        id: asset.id,
+        message: `Duplicate asset id: ${asset.id}`
+      });
+    }
+    seenIds.add(asset.id);
+    if (!supportedFamilies.has(asset.family)) {
+      issues.push({
+        type: "unsupported-enum",
+        id: asset.id,
+        message: `Unsupported asset family: ${asset.family}`
+      });
+    }
+    if (!supportedKinds.has(asset.kind)) {
+      issues.push({
+        type: "unsupported-enum",
+        id: asset.id,
+        message: `Unsupported asset kind: ${asset.kind}`
+      });
+    }
+    if (!supportedVisibilities.has(asset.visibility)) {
+      issues.push({
+        type: "unsupported-enum",
+        id: asset.id,
+        message: `Unsupported asset visibility: ${asset.visibility}`
+      });
+    }
+    if (!supportedSourceKinds.has(asset.sourceKind)) {
+      issues.push({
+        type: "unsupported-enum",
+        id: asset.id,
+        message: `Unsupported asset source kind: ${asset.sourceKind}`
+      });
+    }
+    for (const host of asset.hosts) {
+      if (!supportedHosts.has(host)) {
+        issues.push({
+          type: "unsupported-host",
+          id: asset.id,
+          message: `Unsupported asset host: ${host}`
+        });
+      }
+    }
+    if (!isSafeRegistrySourcePath(asset.sourcePath)) {
+      issues.push({
+        type: "unsafe-source-path",
+        id: asset.id,
+        path: asset.sourcePath,
+        message: `Asset source path escapes agent-assets: ${asset.sourcePath}`
+      });
+    }
+    if (asset.visibility !== "public" && asset.publishable) {
+      issues.push({
+        type: "non-public-publishable",
+        id: asset.id,
+        message: `Only public assets may be publishable: ${asset.id}`
+      });
+    }
+    if (options.agentAssetsDir && isSafeRegistrySourcePath(asset.sourcePath)) {
+      const sourceAbsolutePath = join4(options.agentAssetsDir, normalizeRegistrySourcePath(asset.sourcePath));
+      if (!existsSync4(sourceAbsolutePath)) {
+        issues.push({
+          type: "missing-source-path",
+          id: asset.id,
+          path: asset.sourcePath,
+          message: `Asset source path does not exist: ${asset.sourcePath}`
+        });
+      } else if (asset.kind === "skill" && !existsSync4(join4(sourceAbsolutePath, "SKILL.md"))) {
+        issues.push({
+          type: "missing-skill-file",
+          id: asset.id,
+          path: asset.sourcePath,
+          message: `Skill asset is missing SKILL.md: ${asset.sourcePath}`
+        });
+      }
+    }
+  }
+  if (options.agentAssetsDir) {
+    const npxCompatibilityLayer = join4(options.agentAssetsDir, "skills/npx-skills/skills");
+    if (pathExistsEvenIfDanglingSymlink(npxCompatibilityLayer)) {
+      issues.push({
+        type: "internal-npx-compatibility-layer",
+        id: "npx-skills",
+        path: "skills/npx-skills/skills",
+        message: "Do not create an internal npx compatibility symlink layer."
+      });
+    }
+  }
+  return issues;
+}
+function isSafeRegistrySourcePath(sourcePath) {
+  if (!sourcePath || isAbsolute(sourcePath) || sourcePath.startsWith("/")) return false;
+  const normalized = normalizeRegistrySourcePath(sourcePath);
+  if (normalized === "." || normalized.startsWith("../") || normalized === "..") return false;
+  return !normalized.split("/").includes("..");
+}
+function normalizeRegistrySourcePath(sourcePath) {
+  return posix.normalize(sourcePath.replaceAll("\\", "/"));
+}
+function pathExistsEvenIfDanglingSymlink(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/asset-registry/loader.ts
+function loadAgentAssetRegistry(options = {}) {
+  const agentAssetsDir = options.agentAssetsDir ?? findDefaultAgentAssetsDir();
+  const registryPath = join5(agentAssetsDir, "registry.json");
+  if (!existsSync5(registryPath)) {
+    return {
+      registry: { schemaVersion: 1, assets: [] },
+      agentAssetsDir,
+      registryPath,
+      issues: []
+    };
+  }
+  const registry = JSON.parse(readFileSync3(registryPath, "utf8"));
+  return {
+    registry,
+    agentAssetsDir,
+    registryPath,
+    issues: validateAssetRegistry(registry, { agentAssetsDir })
+  };
+}
+function createAgentAssetLockEntries(registry, agentAssetsDir, assetIds) {
+  const wantedIds = assetIds ? new Set(assetIds) : void 0;
+  return registry.assets.filter((asset) => !wantedIds || wantedIds.has(asset.id)).map((asset) => ({
+    id: asset.id,
+    sourcePath: asset.sourcePath,
+    contentHash: hashAgentAssetContent(asset, agentAssetsDir)
+  })).sort((a, b) => a.id.localeCompare(b.id));
+}
+function hashAgentAssetContent(asset, agentAssetsDir) {
+  const sourceAbsolutePath = join5(agentAssetsDir, asset.sourcePath);
+  const hash = createHash2("sha256");
+  for (const filePath of listFiles3(sourceAbsolutePath)) {
+    const relativePath = toUnixPath3(relative3(sourceAbsolutePath, filePath));
+    hash.update(relativePath);
+    hash.update("\0");
+    hash.update(readFileSync3(filePath));
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+function findDefaultAgentAssetsDir() {
+  const packageRoot2 = findPackageRoot(dirname2(fileURLToPath2(import.meta.url)));
+  const repoRoot = join5(packageRoot2, "..", "..");
+  const candidates = [join5(packageRoot2, "assets/agent-assets"), join5(repoRoot, "agent-assets")];
+  return candidates.find((candidate) => existsSync5(join5(candidate, "registry.json"))) ?? candidates[0];
+}
+function findPackageRoot(startDir) {
+  let current = startDir;
+  while (current !== dirname2(current)) {
+    const packageJsonPath = join5(current, "package.json");
+    if (existsSync5(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse(readFileSync3(packageJsonPath, "utf8"));
+        if (packageJson.name === "@pieai/pro-gov") return current;
+      } catch {
+      }
+    }
+    current = dirname2(current);
+  }
+  return startDir;
+}
+function listFiles3(absolutePath) {
+  const stats = statSync2(absolutePath);
+  if (stats.isFile()) return [absolutePath];
+  const files = [];
+  for (const entry of readdirSync4(absolutePath, { withFileTypes: true })) {
+    const entryPath = join5(absolutePath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listFiles3(entryPath));
+    } else if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+  return files.sort();
+}
+function toUnixPath3(path) {
+  return path.replaceAll("\\", "/");
+}
+
+// src/asset-targets/apply.ts
+import { existsSync as existsSync6, lstatSync as lstatSync2, mkdirSync as mkdirSync2, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname as dirname3, join as join6, resolve } from "node:path";
+function applyAssetInstallPlan(plan) {
+  const appliedActions = [];
+  for (const action of plan.actions) {
+    applyAction(plan.targetDir, action);
+    appliedActions.push(action.type);
+  }
+  return { appliedActions };
+}
+function applyAction(targetDir, action) {
+  const targetAbsolutePath = join6(targetDir, action.targetPath);
+  if (action.type === "create-dir") {
+    mkdirSync2(targetAbsolutePath, { recursive: true });
+    return;
+  }
+  if (action.type === "write-file") {
+    mkdirSync2(dirname3(targetAbsolutePath), { recursive: true });
+    writeFileSync(targetAbsolutePath, action.content);
+    return;
+  }
+  mkdirSync2(dirname3(targetAbsolutePath), { recursive: true });
+  const sourceAbsolutePath = resolve(action.sourcePath);
+  if (action.type === "symlink") {
+    if (pathExistsEvenIfDanglingSymlink2(targetAbsolutePath)) {
+      throw new Error(`Refusing to overwrite unmanaged target: ${action.targetPath}`);
+    }
+    symlinkSync(sourceAbsolutePath, targetAbsolutePath);
+    return;
+  }
+  if (!pathExistsEvenIfDanglingSymlink2(targetAbsolutePath)) {
+    symlinkSync(sourceAbsolutePath, targetAbsolutePath);
+    return;
+  }
+  const stats = lstatSync2(targetAbsolutePath);
+  if (!stats.isSymbolicLink()) {
+    throw new Error(`Refusing to overwrite unmanaged target: ${action.targetPath}`);
+  }
+  unlinkSync(targetAbsolutePath);
+  symlinkSync(sourceAbsolutePath, targetAbsolutePath);
+}
+function pathExistsEvenIfDanglingSymlink2(path) {
+  try {
+    lstatSync2(path);
+    return true;
+  } catch {
+    return existsSync6(path);
+  }
+}
+
+// src/asset-targets/check.ts
+import { existsSync as existsSync7, lstatSync as lstatSync3, readFileSync as readFileSync4 } from "node:fs";
+import { join as join7 } from "node:path";
+function checkInstalledAssets(options) {
+  const lockfilePath = join7(options.targetDir, ".pro-gov/assets.lock.json");
+  if (!existsSync7(lockfilePath)) {
+    return {
+      targetDir: options.targetDir,
+      issues: [
+        {
+          type: "missing-lock",
+          message: "Missing .pro-gov/assets.lock.json"
+        }
+      ]
+    };
+  }
+  const registryById = new Map(options.registry.assets.map((asset) => [asset.id, asset]));
+  const lockfile = JSON.parse(readFileSync4(lockfilePath, "utf8"));
+  const issues = [];
+  for (const entry of lockfile.assets ?? []) {
+    const asset = registryById.get(entry.id);
+    const targetAbsolutePath = join7(options.targetDir, entry.targetPath);
+    const sourceAbsolutePath = join7(options.agentAssetsDir, entry.sourcePath);
+    if (!asset) {
+      issues.push({
+        type: "unknown-asset",
+        id: entry.id,
+        targetPath: entry.targetPath,
+        message: `Lockfile references unknown asset: ${entry.id}`
+      });
+      continue;
+    }
+    const hostFolderIssue = checkHostFolder(lockfile.host, asset.kind, entry.targetPath, entry.id);
+    if (hostFolderIssue) {
+      issues.push(hostFolderIssue);
+    }
+    if (!pathExistsEvenIfDanglingSymlink3(targetAbsolutePath)) {
+      issues.push({
+        type: "missing-target",
+        id: entry.id,
+        targetPath: entry.targetPath,
+        message: `Managed target is missing: ${entry.targetPath}`
+      });
+      continue;
+    }
+    const targetStats = lstatSync3(targetAbsolutePath);
+    if (!targetStats.isSymbolicLink()) {
+      issues.push({
+        type: "unmanaged-conflict",
+        id: entry.id,
+        targetPath: entry.targetPath,
+        message: `Managed target is not a symlink: ${entry.targetPath}`
+      });
+      continue;
+    }
+    if (!existsSync7(targetAbsolutePath)) {
+      issues.push({
+        type: "dangling-symlink",
+        id: entry.id,
+        targetPath: entry.targetPath,
+        message: `Managed symlink is dangling: ${entry.targetPath}`
+      });
+      continue;
+    }
+    if (!existsSync7(sourceAbsolutePath)) {
+      issues.push({
+        type: "missing-source",
+        id: entry.id,
+        targetPath: entry.targetPath,
+        message: `Managed asset source is missing: ${entry.sourcePath}`
+      });
+      continue;
+    }
+    const currentHash = hashAgentAssetContent(asset, options.agentAssetsDir);
+    if (currentHash !== entry.contentHash) {
+      issues.push({
+        type: "hash-drift",
+        id: entry.id,
+        targetPath: entry.targetPath,
+        message: `Managed asset hash drifted: ${entry.id}`
+      });
+    }
+  }
+  return { targetDir: options.targetDir, issues };
+}
+function checkHostFolder(host, kind, targetPath, id) {
+  if (kind !== "skill") return void 0;
+  const expectedPrefix = expectedSkillTargetPrefix(host);
+  if (!expectedPrefix) {
+    return {
+      type: "unsupported-host-folder",
+      id,
+      targetPath,
+      message: `Lockfile host is unsupported for managed skill target: ${host ?? "missing"}`
+    };
+  }
+  if (!targetPath.startsWith(expectedPrefix)) {
+    return {
+      type: "unsupported-host-folder",
+      id,
+      targetPath,
+      message: `Managed skill target ${targetPath} does not match host ${host}; expected ${expectedPrefix}`
+    };
+  }
+  return void 0;
+}
+function expectedSkillTargetPrefix(host) {
+  if (host === "claude-code") return ".claude/skills/";
+  if (host === "codex" || host === "gemini-cli" || host === "antigravity") {
+    return ".agents/skills/";
+  }
+  return void 0;
+}
+function pathExistsEvenIfDanglingSymlink3(path) {
+  try {
+    lstatSync3(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/asset-targets/install-plan.ts
+import { existsSync as existsSync8, lstatSync as lstatSync4, readFileSync as readFileSync5 } from "node:fs";
+import { basename, dirname as dirname4, join as join8 } from "node:path";
+function createAssetInstallPlan(options) {
+  const assetsById = new Map(options.registry.assets.map((asset) => [asset.id, asset]));
+  const bundlesById = new Map(options.bundles.map((bundle) => [bundle.id, bundle]));
+  const assetIds = resolveBundleAssetIds(options.bundleIds, bundlesById);
+  const assets = assetIds.map((assetId) => {
+    const asset = assetsById.get(assetId);
+    if (!asset) throw new Error(`Unknown asset id in bundle: ${assetId}`);
+    if (asset.kind === "skill" && !asset.hosts.includes(options.host)) {
+      throw new Error(`Asset ${assetId} does not support host ${options.host}`);
+    }
+    return asset;
+  });
+  const lockEntries = createAgentAssetLockEntries(options.registry, options.agentAssetsDir, assetIds);
+  const managedTargets = readManagedTargets(options.targetDir);
+  const assetActions = assets.map(
+    (asset) => createAssetAction(asset, options.agentAssetsDir, options.targetDir, options.host, managedTargets)
+  );
+  const manifest = {
+    schemaVersion: 1,
+    host: options.host,
+    bundleIds: [...options.bundleIds],
+    assetIds
+  };
+  const lockfile = {
+    schemaVersion: 1,
+    host: options.host,
+    bundleIds: [...options.bundleIds],
+    assets: lockEntries.map((entry) => {
+      const action = assetActions.find((candidate) => "assetId" in candidate && candidate.assetId === entry.id);
+      return {
+        ...entry,
+        targetPath: action && "targetPath" in action ? action.targetPath : ""
+      };
+    })
+  };
+  const writeActions = [
+    {
+      type: "write-file",
+      targetPath: ".pro-gov/assets.json",
+      content: `${JSON.stringify(manifest, null, 2)}
+`
+    },
+    {
+      type: "write-file",
+      targetPath: ".pro-gov/assets.lock.json",
+      content: `${JSON.stringify(lockfile, null, 2)}
+`
+    }
+  ];
+  return {
+    schemaVersion: 1,
+    dryRun: true,
+    targetDir: options.targetDir,
+    host: options.host,
+    bundleIds: [...options.bundleIds],
+    assetIds,
+    actions: [...createDirectoryActions([...assetActions, ...writeActions]), ...assetActions, ...writeActions]
+  };
+}
+function resolveBundleAssetIds(bundleIds, bundlesById) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const bundleId of bundleIds) {
+    const bundle = bundlesById.get(bundleId);
+    if (!bundle) throw new Error(`Unknown bundle id: ${bundleId}`);
+    for (const assetId of bundle.assets) {
+      ids.add(assetId);
+    }
+  }
+  return [...ids].sort();
+}
+function createAssetAction(asset, agentAssetsDir, targetDir, host, managedTargets) {
+  const sourcePath = join8(agentAssetsDir, asset.sourcePath);
+  const targetPath = resolveHostTargetPath(asset, host);
+  const targetAbsolutePath = join8(targetDir, targetPath);
+  const targetExists = pathExistsEvenIfDanglingSymlink4(targetAbsolutePath);
+  if (targetExists) {
+    const stats = lstatSync4(targetAbsolutePath);
+    if (stats.isSymbolicLink() && managedTargets.has(targetPath)) {
+      return {
+        type: "update-symlink",
+        assetId: asset.id,
+        sourcePath,
+        targetPath
+      };
+    }
+    throw new Error(`Refusing to overwrite unmanaged target: ${targetPath}`);
+  }
+  return {
+    type: "symlink",
+    assetId: asset.id,
+    sourcePath,
+    targetPath
+  };
+}
+function resolveHostTargetPath(asset, host) {
+  if (asset.kind === "skill") {
+    if (host === "claude-code") {
+      return `.claude/skills/${basename(asset.sourcePath)}`;
+    }
+    return `.agents/skills/${basename(asset.sourcePath)}`;
+  }
+  if (asset.kind === "rule") {
+    return `.pro-gov/agent-assets/rules/${basename(asset.sourcePath)}`;
+  }
+  return `.pro-gov/agent-assets/commands/${basename(asset.sourcePath)}`;
+}
+function createDirectoryActions(actions) {
+  const directories = /* @__PURE__ */ new Set();
+  for (const action of actions) {
+    if (action.type === "create-dir") continue;
+    const directory = dirname4(action.targetPath);
+    if (directory !== ".") directories.add(directory);
+  }
+  return [...directories].sort().map((targetPath) => ({ type: "create-dir", targetPath }));
+}
+function readManagedTargets(targetDir) {
+  const lockfilePath = join8(targetDir, ".pro-gov/assets.lock.json");
+  if (!existsSync8(lockfilePath)) return /* @__PURE__ */ new Set();
+  try {
+    const lockfile = JSON.parse(readFileSync5(lockfilePath, "utf8"));
+    return new Set((lockfile.assets ?? []).map((asset) => asset.targetPath).filter(Boolean));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function pathExistsEvenIfDanglingSymlink4(path) {
+  try {
+    lstatSync4(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/asset-targets/recommend.ts
+import { existsSync as existsSync9, readdirSync as readdirSync5, readFileSync as readFileSync6 } from "node:fs";
+import { join as join9 } from "node:path";
+var frontendPackages = /* @__PURE__ */ new Set([
+  "@vitejs/plugin-react",
+  "astro",
+  "next",
+  "nuxt",
+  "react",
+  "svelte",
+  "tailwindcss",
+  "vite",
+  "vue"
+]);
+var agentEntryCandidates = ["AGENTS.md", "CLAUDE.md", ".gemini/settings.json", "GEMINI.md"];
+function discoverTargetSignals(targetDir) {
+  const packageJson = readJson(join9(targetDir, "package.json"));
+  const dependencyNames = packageJson ? Object.keys({ ...packageJson.dependencies, ...packageJson.devDependencies }) : [];
+  const frontendSignals = dependencyNames.filter((name) => frontendPackages.has(name)).sort();
+  const hasAgentEntry = agentEntryCandidates.some((file) => existsSync9(join9(targetDir, file)));
+  const researchSignals = [
+    existsSync9(join9(targetDir, "docs/research")) ? "docs/research" : "",
+    existsSync9(join9(targetDir, "research")) ? "research" : "",
+    hasBookChildDirectory(targetDir, "research") ? "books/*/research" : "",
+    textFileIncludes(join9(targetDir, "README.md"), ["research", "\u8C03\u7814"]) ? "README research" : ""
+  ].filter(Boolean);
+  const writingSignals = [
+    existsSync9(join9(targetDir, "chapters")) ? "chapters" : "",
+    existsSync9(join9(targetDir, "src/chapters")) ? "src/chapters" : "",
+    hasBookChildDirectory(targetDir, "chapters") ? "books/*/chapters" : "",
+    textFileIncludes(join9(targetDir, "AGENTS.md"), ["writing mode", "novel chapter", "book content"]) ? "AGENTS writing" : ""
+  ].filter(Boolean);
+  return {
+    targetDir,
+    hasPackageJson: Boolean(packageJson),
+    hasAgentEntry,
+    frontendSignals,
+    researchSignals,
+    writingSignals
+  };
+}
+function recommendBundlesForTarget(targetDir) {
+  const signals = discoverTargetSignals(targetDir);
+  const recommendations = [
+    {
+      bundleId: "base-governance",
+      confidence: signals.hasAgentEntry || signals.hasPackageJson ? "high" : "medium",
+      reasons: [
+        signals.hasAgentEntry ? "agent entry file present" : "",
+        signals.hasPackageJson ? "package.json present" : "",
+        !signals.hasAgentEntry && !signals.hasPackageJson ? "default project governance baseline" : ""
+      ].filter(Boolean)
+    }
+  ];
+  if (signals.frontendSignals.length > 0) {
+    recommendations.push({
+      bundleId: "frontend-app",
+      confidence: "high",
+      reasons: signals.frontendSignals.map((signal) => `frontend dependency: ${signal}`)
+    });
+  }
+  if (signals.researchSignals.length > 0) {
+    recommendations.push({
+      bundleId: "research-docs",
+      confidence: "high",
+      reasons: signals.researchSignals
+    });
+  }
+  if (signals.writingSignals.length > 0) {
+    recommendations.push({
+      bundleId: "novel-writing",
+      confidence: "high",
+      reasons: signals.writingSignals
+    });
+  }
+  return recommendations;
+}
+function readJson(path) {
+  if (!existsSync9(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync6(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function textFileIncludes(path, needles) {
+  if (!existsSync9(path)) return false;
+  const contents = readFileSync6(path, "utf8").toLowerCase();
+  return needles.some((needle) => contents.includes(needle.toLowerCase()));
+}
+function hasBookChildDirectory(targetDir, childName) {
+  const booksDir = join9(targetDir, "books");
+  if (!existsSync9(booksDir)) return false;
+  try {
+    return readdirSync5(booksDir, { withFileTypes: true }).some(
+      (entry) => entry.isDirectory() && existsSync9(join9(booksDir, entry.name, childName))
+    );
+  } catch {
+    return false;
+  }
+}
 
 // src/commands/assets.ts
 function runAssets(args) {
-  const [subcommand2] = args;
-  if (subcommand2 !== "list") {
-    console.error("Usage: pro-gov assets list");
+  const [subcommand2, ...rest] = args;
+  if (subcommand2 === "list") {
+    return runAssetsList(rest);
+  }
+  if (subcommand2 === "recommend") {
+    return runAssetsRecommend(rest);
+  }
+  if (subcommand2 === "discover") {
+    return runAssetsDiscover(rest);
+  }
+  if (subcommand2 === "plan") {
+    return runAssetsPlan(rest);
+  }
+  if (subcommand2 === "apply") {
+    return runAssetsApply(rest);
+  }
+  if (subcommand2 === "check") {
+    return runAssetsCheck(rest);
+  }
+  if (subcommand2 === "npx") {
+    return runAssetsNpx(rest);
+  }
+  printUsage();
+  return 1;
+}
+function runAssetsNpx(args) {
+  const [operation, ...rest] = args;
+  if (!operation || operation === "--help" || operation === "-h" || rest.includes("--help")) {
+    printNpxUsage();
+    return 0;
+  }
+  if (operation !== "add" && operation !== "update") {
+    printNpxUsage();
+    return 1;
+  }
+  const options = parseNpxOptions(operation, rest);
+  if (!options.ok) {
+    console.error(options.error);
+    printNpxUsage();
+    return 1;
+  }
+  try {
+    const loaded = loadAgentAssetRegistry();
+    const plan = createNpxSkillsMaintenancePlan({
+      operation,
+      npxRoot: options.value.npxRoot ?? `${loaded.agentAssetsDir}/skills/npx-skills`,
+      source: options.value.source,
+      skill: options.value.skill
+    });
+    console.log(JSON.stringify(plan, null, 2));
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}
+function runAssetsApply(args) {
+  const options = parseApplyOptions(args);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage();
+    return 1;
+  }
+  try {
+    const plan = JSON.parse(readFileSync7(options.value.planPath, "utf8"));
+    const result = applyAssetInstallPlan(plan);
+    console.log(`applied-actions: ${result.appliedActions.length}`);
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}
+function runAssetsCheck(args) {
+  const options = parseTargetJsonOptions(args);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage();
+    return 1;
+  }
+  const loaded = loadAgentAssetRegistry();
+  const result = checkInstalledAssets({
+    targetDir: options.value.targetDir,
+    agentAssetsDir: loaded.agentAssetsDir,
+    registry: loaded.registry
+  });
+  if (options.value.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.issues.length === 0) {
+    console.log("assets check passed");
+  } else {
+    for (const issue of result.issues) {
+      console.log(`${issue.type}: ${issue.message}`);
+    }
+  }
+  return result.issues.length === 0 ? 0 : 1;
+}
+function runAssetsList(args) {
+  const options = parseListOptions(args);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage();
     return 1;
   }
+  if (options.value.registryMode) {
+    return listRegistryAssets(options.value);
+  }
   for (const asset of listAssets()) {
     console.log(asset.path);
   }
   return 0;
 }
+function runAssetsRecommend(args) {
+  const options = parseTargetJsonOptions(args);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage();
+    return 1;
+  }
+  const recommendations = recommendBundlesForTarget(options.value.targetDir);
+  if (options.value.json) {
+    console.log(JSON.stringify({ targetDir: options.value.targetDir, recommendations }, null, 2));
+  } else {
+    for (const recommendation of recommendations) {
+      console.log(
+        `${recommendation.bundleId}	${recommendation.confidence}	${recommendation.reasons.join("; ")}`
+      );
+    }
+  }
+  return 0;
+}
+function runAssetsDiscover(args) {
+  const options = parseTargetJsonOptions(args);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage();
+    return 1;
+  }
+  const signals = discoverTargetSignals(options.value.targetDir);
+  if (options.value.json) {
+    console.log(JSON.stringify(signals, null, 2));
+  } else {
+    console.log(`target: ${signals.targetDir}`);
+    console.log(`package-json: ${signals.hasPackageJson ? "yes" : "no"}`);
+    console.log(`agent-entry: ${signals.hasAgentEntry ? "yes" : "no"}`);
+    console.log(`frontend: ${signals.frontendSignals.join(", ") || "none"}`);
+    console.log(`research: ${signals.researchSignals.join(", ") || "none"}`);
+    console.log(`writing: ${signals.writingSignals.join(", ") || "none"}`);
+  }
+  return 0;
+}
+function runAssetsPlan(args) {
+  const options = parsePlanOptions(args);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage();
+    return 1;
+  }
+  const loaded = loadAgentAssetRegistry();
+  if (loaded.issues.length > 0) {
+    for (const issue of loaded.issues) {
+      console.error(`${issue.type}: ${issue.message}`);
+    }
+    return 1;
+  }
+  try {
+    const plan = createAssetInstallPlan({
+      targetDir: options.value.targetDir,
+      agentAssetsDir: loaded.agentAssetsDir,
+      registry: loaded.registry,
+      bundles: loadAgentAssetBundles(loaded.agentAssetsDir),
+      bundleIds: options.value.bundleIds,
+      host: options.value.host
+    });
+    if (options.value.json) {
+      console.log(JSON.stringify(plan, null, 2));
+    } else {
+      console.log(`target: ${plan.targetDir}`);
+      console.log(`host: ${plan.host}`);
+      console.log(`bundles: ${plan.bundleIds.join(", ")}`);
+      console.log(`assets: ${plan.assetIds.length}`);
+      console.log(`actions: ${plan.actions.length}`);
+      console.log("dry-run: true");
+    }
+    if (options.value.outPath) {
+      mkdirSync3(dirname5(options.value.outPath), { recursive: true });
+      writeFileSync2(options.value.outPath, `${JSON.stringify(plan, null, 2)}
+`);
+      if (!options.value.json) {
+        console.log(`plan: ${options.value.outPath}`);
+      }
+    }
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}
+function parseListOptions(args) {
+  const options = {
+    json: false,
+    registryMode: false,
+    visibility: "all"
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      options.json = true;
+      options.registryMode = true;
+    } else if (arg === "--visibility") {
+      const visibility = args[index + 1];
+      if (!isVisibilityFilter(visibility)) {
+        return { ok: false, error: "Expected --visibility public|private|third-party|all" };
+      }
+      options.visibility = visibility;
+      options.registryMode = true;
+      index += 1;
+    } else if (arg === "--registry") {
+      options.registryMode = true;
+    } else {
+      return { ok: false, error: `Unknown assets list option: ${arg}` };
+    }
+  }
+  return { ok: true, value: options };
+}
+function parseTargetJsonOptions(args) {
+  const options = {
+    targetDir: process.cwd(),
+    json: false
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--target") {
+      const targetDir = args[index + 1];
+      if (!targetDir) return { ok: false, error: "Expected --target <path>" };
+      options.targetDir = targetDir;
+      index += 1;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else {
+      return { ok: false, error: `Unknown assets target option: ${arg}` };
+    }
+  }
+  return { ok: true, value: options };
+}
+function parsePlanOptions(args) {
+  const options = {
+    targetDir: process.cwd(),
+    json: false,
+    bundleIds: [],
+    host: "codex"
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--target") {
+      const targetDir = args[index + 1];
+      if (!targetDir) return { ok: false, error: "Expected --target <path>" };
+      options.targetDir = targetDir;
+      index += 1;
+    } else if (arg === "--bundle") {
+      const bundleId = args[index + 1];
+      if (!bundleId) return { ok: false, error: "Expected --bundle <bundle-id>" };
+      options.bundleIds.push(bundleId);
+      index += 1;
+    } else if (arg === "--host") {
+      const host = args[index + 1];
+      if (!isHost(host)) {
+        return {
+          ok: false,
+          error: "Expected --host codex|claude-code|gemini-cli|antigravity"
+        };
+      }
+      options.host = host;
+      index += 1;
+    } else if (arg === "--out") {
+      const outPath = args[index + 1];
+      if (!outPath) return { ok: false, error: "Expected --out <path>" };
+      options.outPath = outPath;
+      index += 1;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else {
+      return { ok: false, error: `Unknown assets plan option: ${arg}` };
+    }
+  }
+  if (options.bundleIds.length === 0) {
+    return { ok: false, error: "Expected at least one --bundle <bundle-id>" };
+  }
+  return { ok: true, value: options };
+}
+function parseApplyOptions(args) {
+  let planPath = "";
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--plan") {
+      const value = args[index + 1];
+      if (!value) return { ok: false, error: "Expected --plan <path>" };
+      planPath = value;
+      index += 1;
+    } else {
+      return { ok: false, error: `Unknown assets apply option: ${arg}` };
+    }
+  }
+  if (!planPath) return { ok: false, error: "Expected --plan <path>" };
+  return { ok: true, value: { planPath } };
+}
+function parseNpxOptions(operation, args) {
+  const options = {};
+  const positional = [];
+  let hasPlan = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--plan") {
+      hasPlan = true;
+    } else if (arg === "--root") {
+      const npxRoot = args[index + 1];
+      if (!npxRoot) return { ok: false, error: "Expected --root <path>" };
+      options.npxRoot = npxRoot;
+      index += 1;
+    } else if (arg === "--skill") {
+      const skill = args[index + 1];
+      if (!skill) return { ok: false, error: "Expected --skill <name>" };
+      options.skill = skill;
+      index += 1;
+    } else if (arg.startsWith("-")) {
+      return { ok: false, error: `Unknown assets npx option: ${arg}` };
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (!hasPlan) return { ok: false, error: "Expected --plan. Direct npx writes are not supported." };
+  if (operation === "add") {
+    const [source] = positional;
+    if (!source) return { ok: false, error: "Expected pro-gov assets npx add <source> --plan" };
+    options.source = source;
+  } else if (positional.length > 0) {
+    return { ok: false, error: `Unexpected assets npx update argument: ${positional[0]}` };
+  }
+  return { ok: true, value: options };
+}
+function listRegistryAssets(options) {
+  const loaded = loadAgentAssetRegistry();
+  if (loaded.issues.length > 0) {
+    for (const issue of loaded.issues) {
+      console.error(`${issue.type}: ${issue.message}`);
+    }
+    return 1;
+  }
+  const assets = filterAssetsByVisibility(loaded.registry.assets, options.visibility);
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          count: assets.length,
+          registryPath: loaded.registryPath,
+          assets
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    for (const asset of assets) {
+      console.log(asset.id);
+    }
+  }
+  return 0;
+}
+function filterAssetsByVisibility(assets, visibility) {
+  if (visibility === "all") return [...assets];
+  return assets.filter((asset) => asset.visibility === visibility);
+}
+function isVisibilityFilter(value) {
+  return value === "public" || value === "private" || value === "third-party" || value === "all";
+}
+function isHost(value) {
+  return value === "codex" || value === "claude-code" || value === "gemini-cli" || value === "antigravity";
+}
+function printUsage() {
+  console.error("Usage:");
+  console.error("  pro-gov assets list [--registry] [--json] [--visibility public|private|third-party|all]");
+  console.error("  pro-gov assets discover [--target <path>] [--json]");
+  console.error("  pro-gov assets recommend [--target <path>] [--json]");
+  console.error("  pro-gov assets plan --bundle <bundle-id> [--bundle <bundle-id>] [--target <path>] [--host codex|claude-code|gemini-cli|antigravity] [--out <path>] [--json]");
+  console.error("  pro-gov assets apply --plan <path>");
+  console.error("  pro-gov assets check [--target <path>] [--json]");
+  console.error("  pro-gov assets npx add <source> [--skill <name>] --plan [--root <path>]");
+  console.error("  pro-gov assets npx update [--skill <name>] --plan [--root <path>]");
+}
+function printNpxUsage() {
+  console.log("Usage: pro-gov assets npx add <source> [--skill <name>] --plan [--root <path>]");
+  console.log("Usage: pro-gov assets npx update [--skill <name>] --plan [--root <path>]");
+  console.log("");
+  console.log("Runs npx skills only in a temporary copy and prints a reviewable plan.");
+}
 
 // src/commands/doctor.ts
-import { spawnSync } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync10 } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname as dirname2, join as join2 } from "node:path";
+import { dirname as dirname6, join as join10 } from "node:path";
 var REQUIRED_ASSETS = [
   "starter/AGENTS.template.md",
+  "starter/.gemini/settings.json",
   "starter/docs/governance/ssot-v0.9.md",
   "starter/docs/governance/agents-routing/engineering-runtime-v0.9.md",
   "starter/docs/governance/agents-routing/doc-only-v0.9.md",
@@ -86,7 +1254,7 @@ function runDoctor(_args) {
   return missing.length > 0 ? 1 : 0;
 }
 function checkDocGov() {
-  const fromPath = spawnSync("doc-gov", ["--help"], {
+  const fromPath = spawnSync2("doc-gov", ["--help"], {
     encoding: "utf8",
     stdio: "ignore"
   });
@@ -97,7 +1265,7 @@ function checkDocGov() {
   if (!dependencyCli) {
     return "doc-gov: not found; install @pieai/doc-gov beside @pieai/pro-gov for validation.";
   }
-  const fromDependency = spawnSync(process.execPath, [dependencyCli, "--help"], {
+  const fromDependency = spawnSync2(process.execPath, [dependencyCli, "--help"], {
     encoding: "utf8",
     stdio: "ignore"
   });
@@ -110,8 +1278,8 @@ function resolveDocGovDependencyCli() {
   try {
     const require2 = createRequire(import.meta.url);
     const packageJsonPath = require2.resolve("@pieai/doc-gov/package.json");
-    const cliPath = join2(dirname2(packageJsonPath), "dist/cli.js");
-    return existsSync2(cliPath) ? cliPath : null;
+    const cliPath = join10(dirname6(packageJsonPath), "dist/cli.js");
+    return existsSync10(cliPath) ? cliPath : null;
   } catch {
     return null;
   }
@@ -176,9 +1344,256 @@ function readFlag(args, flag) {
   return value;
 }
 
+// src/commands/lens.ts
+import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname7 } from "node:path";
+
+// src/lens/report.ts
+function formatProjectLensInspection(report) {
+  return [
+    `target: ${report.targetDir}`,
+    `ai-entry-files: ${formatList(report.aiEntryFiles)}`,
+    `ai-config-files: ${formatList(report.aiConfigFiles)}`,
+    `package-scripts: ${formatList(report.packageJson?.scripts ?? [])}`,
+    `dependencies: ${formatList(report.packageJson?.dependencies ?? [])}`,
+    `dev-dependencies: ${formatList(report.packageJson?.devDependencies ?? [])}`,
+    `docs-directory: ${report.docs.hasDocsDirectory ? "yes" : "no"}`,
+    `markdown-files: ${report.docs.markdownFileCount}`,
+    `governance-files: ${formatList(report.docs.governanceFiles)}`,
+    `git: ${report.git.available ? "available" : "unavailable"}`,
+    `git-branch: ${report.git.branch ?? "unknown"}`,
+    `git-head: ${report.git.head ?? "unknown"}`,
+    `large-files: ${report.largeFiles.length}`
+  ].join("\n");
+}
+function renderProjectLensMarkdownReport(report) {
+  return `${[
+    "# Project Lens Evidence Report",
+    "",
+    `- Target: \`${report.targetDir}\``,
+    `- Generated: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    "- Scope: local read-only evidence for AI-assisted project review",
+    "",
+    "## AI Entry Files",
+    "",
+    bulletList(report.aiEntryFiles),
+    "",
+    "## AI Config Adapters",
+    "",
+    bulletList(report.aiConfigFiles),
+    "",
+    "## Package",
+    "",
+    `- Scripts: ${formatList(report.packageJson?.scripts ?? [])}`,
+    `- Dependencies: ${formatList(report.packageJson?.dependencies ?? [])}`,
+    `- Dev dependencies: ${formatList(report.packageJson?.devDependencies ?? [])}`,
+    "",
+    "## Docs",
+    "",
+    `- Docs directory: ${report.docs.hasDocsDirectory ? "yes" : "no"}`,
+    `- Markdown files: ${report.docs.markdownFileCount}`,
+    `- Governance files: ${formatList(report.docs.governanceFiles)}`,
+    "",
+    "## Git",
+    "",
+    `- Available: ${report.git.available ? "yes" : "no"}`,
+    `- Branch: ${report.git.branch ?? "unknown"}`,
+    `- Head: ${report.git.head ?? "unknown"}`,
+    "",
+    "## Large Files",
+    "",
+    report.largeFiles.length === 0 ? "- none" : report.largeFiles.map((file) => `- \`${file.path}\` (${file.bytes} bytes)`).join("\n"),
+    "",
+    "## Review Notes",
+    "",
+    "- This report is evidence only; it does not replace human or AI judgement.",
+    "- Use the ProjectLens skills for interpretation, tradeoff analysis, and recommendations."
+  ].join("\n")}
+`;
+}
+function formatList(values) {
+  return values.length === 0 ? "none" : values.join(", ");
+}
+function bulletList(values) {
+  if (values.length === 0) return "- none";
+  return values.map((value) => `- \`${value}\``).join("\n");
+}
+
+// src/lens/scan.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { existsSync as existsSync11, readdirSync as readdirSync6, readFileSync as readFileSync8, statSync as statSync3 } from "node:fs";
+import { join as join11, relative as relative4 } from "node:path";
+var ignoredDirectories = /* @__PURE__ */ new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  "dist",
+  "node_modules",
+  "coverage"
+]);
+function scanProjectLensTarget(targetDir, options = {}) {
+  const largeFileBytes = options.largeFileBytes ?? 5e4;
+  const files = listProjectFiles(targetDir);
+  const markdownFiles = files.filter((file) => file.endsWith(".md"));
+  const packageJson = readPackageJson(targetDir);
+  return {
+    targetDir,
+    aiEntryFiles: ["AGENTS.md", "CLAUDE.md", "GEMINI.md"].filter(
+      (file) => existsSync11(join11(targetDir, file))
+    ),
+    aiConfigFiles: [".gemini/settings.json"].filter((file) => existsSync11(join11(targetDir, file))),
+    packageJson,
+    docs: {
+      hasDocsDirectory: existsSync11(join11(targetDir, "docs")),
+      markdownFileCount: markdownFiles.length,
+      governanceFiles: markdownFiles.filter((file) => file.startsWith("docs/governance/") || file.startsWith("docs/policy/")).sort()
+    },
+    git: readGitState(targetDir),
+    largeFiles: files.map((file) => ({ path: file, bytes: statSync3(join11(targetDir, file)).size })).filter((file) => file.bytes >= largeFileBytes).sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path)).slice(0, 25)
+  };
+}
+function readPackageJson(targetDir) {
+  const packageJsonPath = join11(targetDir, "package.json");
+  if (!existsSync11(packageJsonPath)) return void 0;
+  try {
+    const packageJson = JSON.parse(readFileSync8(packageJsonPath, "utf8"));
+    return {
+      scripts: Object.keys(packageJson.scripts ?? {}).sort(),
+      dependencies: Object.keys(packageJson.dependencies ?? {}).sort(),
+      devDependencies: Object.keys(packageJson.devDependencies ?? {}).sort()
+    };
+  } catch {
+    return void 0;
+  }
+}
+function readGitState(targetDir) {
+  const branch = runGit(targetDir, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (!branch.ok) return { available: false };
+  const head = runGit(targetDir, ["log", "-1", "--format=%H %s"]);
+  const status = runGit(targetDir, ["status", "-sb"]);
+  return {
+    available: true,
+    branch: branch.stdout,
+    head: head.ok ? head.stdout : void 0,
+    statusShort: status.ok ? status.stdout : void 0
+  };
+}
+function runGit(targetDir, args) {
+  const result = spawnSync3("git", ["-C", targetDir, ...args], {
+    encoding: "utf8"
+  });
+  if (result.status !== 0) return { ok: false };
+  return { ok: true, stdout: result.stdout.trim() };
+}
+function listProjectFiles(targetDir) {
+  const files = [];
+  collectFiles2(targetDir, targetDir, files);
+  return files.sort();
+}
+function collectFiles2(rootDir, currentDir, files) {
+  if (!existsSync11(currentDir)) return;
+  for (const entry of readdirSync6(currentDir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (ignoredDirectories.has(entry.name)) continue;
+      collectFiles2(rootDir, join11(currentDir, entry.name), files);
+    } else if (entry.isFile()) {
+      files.push(toUnixPath4(relative4(rootDir, join11(currentDir, entry.name))));
+    }
+  }
+}
+function toUnixPath4(path) {
+  return path.replaceAll("\\", "/");
+}
+
+// src/commands/lens.ts
+function runLens(args) {
+  const [subcommand2, ...rest] = args;
+  if (subcommand2 === "scan" || subcommand2 === "inspect") {
+    return runLensInspect(rest, subcommand2);
+  }
+  if (subcommand2 === "report") {
+    return runLensReport(rest);
+  }
+  printUsage2();
+  return 1;
+}
+function runLensInspect(args, subcommand2) {
+  const options = parseLensOptions(args, subcommand2);
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage2();
+    return 1;
+  }
+  const report = scanProjectLensTarget(options.value.targetDir);
+  if (options.value.json || options.value.format === "json") {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatProjectLensInspection(report));
+  }
+  return 0;
+}
+function runLensReport(args) {
+  const options = parseLensOptions(args, "report");
+  if (!options.ok) {
+    console.error(options.error);
+    printUsage2();
+    return 1;
+  }
+  if (!options.value.outPath) {
+    console.error("Expected --out <path>");
+    printUsage2();
+    return 1;
+  }
+  const report = scanProjectLensTarget(options.value.targetDir);
+  const markdown = renderProjectLensMarkdownReport(report);
+  mkdirSync4(dirname7(options.value.outPath), { recursive: true });
+  writeFileSync3(options.value.outPath, markdown);
+  console.log(`report: ${options.value.outPath}`);
+  return 0;
+}
+function parseLensOptions(args, subcommand2) {
+  const options = {
+    targetDir: process.cwd(),
+    json: false,
+    format: "text"
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--target") {
+      const targetDir = args[index + 1];
+      if (!targetDir) return { ok: false, error: "Expected --target <path>" };
+      options.targetDir = targetDir;
+      index += 1;
+    } else if (arg === "--json") {
+      options.json = true;
+      options.format = "json";
+    } else if (arg === "--format") {
+      const format = args[index + 1];
+      if (format !== "text" && format !== "json") {
+        return { ok: false, error: "Expected --format text|json" };
+      }
+      options.format = format;
+      index += 1;
+    } else if (arg === "--out") {
+      const outPath = args[index + 1];
+      if (!outPath) return { ok: false, error: "Expected --out <path>" };
+      options.outPath = outPath;
+      index += 1;
+    } else {
+      return { ok: false, error: `Unknown lens ${subcommand2} option: ${arg}` };
+    }
+  }
+  return { ok: true, value: options };
+}
+function printUsage2() {
+  console.error("Usage: pro-gov lens scan [--target <path>] [--json]");
+  console.error("Usage: pro-gov lens inspect [--target <path>] [--format text|json]");
+  console.error("Usage: pro-gov lens report --target <path> --out <path>");
+}
+
 // src/commands/sync.ts
-import { existsSync as existsSync3, readFileSync } from "node:fs";
-import { join as join3 } from "node:path";
+import { existsSync as existsSync12, readFileSync as readFileSync9 } from "node:fs";
+import { join as join12 } from "node:path";
 function runSync(args) {
   if (!args.includes("--check")) {
     console.error("pro-gov sync requires --check in this first read-only release.");
@@ -187,14 +1602,14 @@ function runSync(args) {
   let differences = 0;
   console.log("pro-gov sync check");
   for (const file of planStarterFiles()) {
-    const targetPath = join3(process.cwd(), file.targetPath);
-    if (!existsSync3(targetPath)) {
+    const targetPath = join12(process.cwd(), file.targetPath);
+    if (!existsSync12(targetPath)) {
       console.log(`missing: ${file.targetPath}`);
       differences += 1;
       continue;
     }
-    const source = readFileSync(file.absoluteSourcePath, "utf8");
-    const target = readFileSync(targetPath, "utf8");
+    const source = readFileSync9(file.absoluteSourcePath, "utf8");
+    const target = readFileSync9(targetPath, "utf8");
     if (source !== target) {
       console.log(`different: ${file.targetPath}`);
       differences += 1;
@@ -210,7 +1625,16 @@ function runSync(args) {
 
 // src/cli.ts
 var COMMANDS = [
-  "assets list",
+  "assets list [--json] [--visibility public|private|third-party|all]",
+  "assets discover [--target <path>] [--json]",
+  "assets recommend [--target <path>] [--json]",
+  "assets plan --bundle <bundle-id> [--target <path>] [--json]",
+  "assets apply --plan <path>",
+  "assets check [--target <path>] [--json]",
+  "assets npx add|update ... --plan",
+  "lens scan [--target <path>] [--json]",
+  "lens inspect [--target <path>] [--format text|json]",
+  "lens report --target <path> --out <path>",
   "init --profile <engineering-runtime|doc-only> --dry-run",
   "sync --check",
   "doctor"
@@ -219,8 +1643,10 @@ var [command, subcommand] = process.argv.slice(2);
 if (!command || command === "--help" || command === "-h") {
   printHelp();
   process.exitCode = command ? 0 : 1;
-} else if (command === "assets" && subcommand === "list") {
+} else if (command === "assets") {
   process.exitCode = runAssets(process.argv.slice(3));
+} else if (command === "lens") {
+  process.exitCode = runLens(process.argv.slice(3));
 } else if (command === "init") {
   process.exitCode = runInit(process.argv.slice(3));
 } else if (command === "sync") {