@outerlayer/cli 0.1.0

package/dist/emit-finding-cmd-6K7ERPKG.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { FindingBatchSchema, resolveRepoIdentity, detectActiveSession, launchRefusalForSession } from './chunk-DEDV5V4U.js';
+import './chunk-YRYMNBGQ.js';
+import { launchedItemForSession, parseTrackerNumber, trackerNumberError } from './chunk-RCQXYLMO.js';
+import { readLatestProvenanceForSession } from './chunk-ZJSNLVCE.js';
+import './chunk-A6NNKRJU.js';
+import './chunk-IWIUYLDR.js';
+import './chunk-YMTXR7PJ.js';
+import './chunk-ECSYRPCC.js';
+import { readCloudConfig } from './chunk-TFUIDMOB.js';
+import { homeFromEnv } from './chunk-VNVZDWO3.js';
+import './chunk-Z5GEFMRW.js';
+import { readFileSync } from 'fs';
+
+createRequire(import.meta.url);
+var GREEN = "\x1B[32m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
+var EmitFindingError = class extends Error {
+};
+function parseItemFlag(raw) {
+  if (raw === void 0) return void 0;
+  const number = parseTrackerNumber(raw);
+  if (number === void 0) {
+    throw new EmitFindingError(trackerNumberError("--item", raw));
+  }
+  return { number };
+}
+function parseIntFlag(raw, flag, opts) {
+  if (raw === void 0) return void 0;
+  if (!/^-?\d+$/.test(raw)) {
+    throw new EmitFindingError(`invalid ${flag} "${raw}" \u2014 expected a whole number`);
+  }
+  const n = Number(raw);
+  if (!Number.isSafeInteger(n) || n < opts.min) {
+    throw new EmitFindingError(`invalid ${flag} "${raw}" \u2014 expected a whole number >= ${opts.min}`);
+  }
+  return n;
+}
+async function readAllStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+function recordFromFlags(opts) {
+  const line = parseIntFlag(opts.line, "--line", { min: 1 });
+  const ruleLine = parseIntFlag(opts.ruleLine, "--rule-line", { min: 1 });
+  const turnIndex = parseIntFlag(opts.turn, "--turn", { min: 0 });
+  const round = parseIntFlag(opts.round, "--round", { min: 0 });
+  return {
+    id: opts.id,
+    subject: opts.subject,
+    title: opts.title,
+    file: opts.file,
+    line: line ?? null,
+    severity: opts.severity ?? null,
+    kind: opts.kind,
+    verdict: opts.verdict,
+    fixed: opts.fixed ?? false,
+    rule: opts.rulePath !== void 0 ? {
+      path: opts.rulePath,
+      line: ruleLine ?? null,
+      quote: opts.ruleQuote ?? "",
+      relation: opts.ruleRelation
+    } : null,
+    source: opts.source,
+    where: {
+      label: opts.where,
+      ...opts.traceId !== void 0 ? { traceId: opts.traceId } : {},
+      ...turnIndex !== void 0 ? { turnIndex } : {},
+      ...round !== void 0 ? { round } : {}
+    }
+  };
+}
+function firstIssueMessage(result) {
+  const issue = result.error.issues[0];
+  return issue ? `${issue.path.join(".")}: ${issue.message}` : "malformed";
+}
+function detectUploadSessionId(opts) {
+  const identity = resolveRepoIdentity(opts.cwd);
+  return detectActiveSession({
+    env: opts.env,
+    home: opts.home,
+    cwds: identity.repoRoot !== void 0 ? [identity.repoRoot, opts.cwd] : [opts.cwd],
+    nowMs: opts.now().getTime()
+  });
+}
+function resolveUploadTarget(opts) {
+  const item = parseItemFlag(opts.item);
+  const sessionId = opts.sessionId;
+  if (sessionId !== void 0) {
+    const refusal = launchRefusalForSession(sessionId, opts.home);
+    if (refusal !== void 0) throw new EmitFindingError(refusal);
+  }
+  if (item !== void 0) {
+    return sessionId !== void 0 ? { item, sessionId } : { item };
+  }
+  if (sessionId === void 0) {
+    throw new EmitFindingError(
+      "nothing to attach this to \u2014 no work item. Pass --item <number>, or run inside a recorded session launched with OUTERLAYER_WORK \u2014 its own launch record names the item automatically."
+    );
+  }
+  const launchedNumber = launchedItemForSession(sessionId, opts.home);
+  if (launchedNumber === void 0) {
+    throw new EmitFindingError(
+      "nothing to attach this to \u2014 no work item. Pass --item <number>; this recorded session's own launch record names no item either."
+    );
+  }
+  return { item: { number: launchedNumber }, sessionId };
+}
+async function upload(batch, target, opts) {
+  const fileConfig = readCloudConfig(opts.home);
+  const url = opts.url ?? opts.env.OUTERLAYER_URL ?? fileConfig.url;
+  const apiKey = opts.apiKey ?? opts.env.OUTERLAYER_API_KEY ?? fileConfig.apiKey;
+  const appId = opts.appId ?? opts.env.OUTERLAYER_APP_ID ?? fileConfig.appId;
+  if (!url || !apiKey || !appId) {
+    const missing = [!url && "--url", !apiKey && "--api-key", !appId && "--app-id"].filter(Boolean).join(", ");
+    throw new EmitFindingError(
+      `missing ${missing}. Run \`outerlayer login --url <your gateway>\` and paste the key at the prompt, or set OUTERLAYER_URL / OUTERLAYER_API_KEY / OUTERLAYER_APP_ID. Mint a key in the dashboard: Settings \u2192 API keys.`
+    );
+  }
+  const request = {
+    ...batch,
+    item: target.item,
+    ...target.sessionId !== void 0 ? { sessionId: target.sessionId } : {}
+  };
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const endpoint = new URL("/v1/findings", url).toString();
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${apiKey}`,
+        "x-outerlayer-app-id": appId
+      },
+      body: JSON.stringify(request)
+    });
+  } catch (err) {
+    throw new EmitFindingError(`network error reaching ${endpoint}: ${String(err)}`);
+  }
+  if (response.status === 401) {
+    throw new EmitFindingError(
+      "not authorized \u2014 the API key is unknown, expired, or bound to a different app. Mint a fresh key: dashboard \u2192 Settings \u2192 API keys."
+    );
+  }
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = (await response.text()).replace(/\s+/g, " ").trim().slice(0, 160);
+    } catch {
+    }
+    throw new EmitFindingError(`emit failed (${response.status})${detail ? `: ${detail}` : ""}`);
+  }
+  let data = {};
+  try {
+    data = (await response.json()).data ?? {};
+  } catch {
+  }
+  const count = typeof data.count === "number" ? data.count : batch.findings.length;
+  const output = opts.json ? JSON.stringify(data) : `${GREEN}\u2713${RESET} recorded ${count} ${count === 1 ? "finding" : "findings"} ${DIM}\xB7${RESET} item #${target.item.number}`;
+  if (!opts.quiet) process.stdout.write(output + "\n");
+  return { data, output, exitCode: 0 };
+}
+async function runEmitFinding(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const home = opts.home ?? homeFromEnv();
+  const env = opts.env ?? process.env;
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  const sessionId = detectUploadSessionId({ cwd, home, env, now });
+  const contextSourceSha = opts.contextSourceSha ?? (sessionId !== void 0 ? readLatestProvenanceForSession(sessionId, home)?.sha ?? void 0 : void 0);
+  const rawBatch = {
+    schemaVersion: 1,
+    ...opts.headSha !== void 0 ? { headSha: opts.headSha } : {},
+    ...contextSourceSha !== void 0 ? { contextSourceSha } : {},
+    findings: [recordFromFlags(opts)]
+  };
+  const parsed = FindingBatchSchema.safeParse(rawBatch);
+  if (!parsed.success) {
+    throw new EmitFindingError(`invalid finding \u2014 ${firstIssueMessage(parsed)}`);
+  }
+  const target = resolveUploadTarget({ item: opts.item, sessionId, home });
+  return upload(parsed.data, target, {
+    json: opts.json,
+    url: opts.url,
+    apiKey: opts.apiKey,
+    appId: opts.appId,
+    quiet: opts.quiet,
+    home,
+    env,
+    fetchImpl: opts.fetchImpl
+  });
+}
+async function runEmitFindings(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const home = opts.home ?? homeFromEnv();
+  const env = opts.env ?? process.env;
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  let text;
+  if (opts.file === "-") {
+    text = await (opts.readStdin ?? readAllStdin)();
+  } else {
+    try {
+      text = readFileSync(opts.file, "utf8");
+    } catch (err) {
+      throw new EmitFindingError(`cannot read "${opts.file}": ${String(err)}`);
+    }
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    throw new EmitFindingError(`"${opts.file}" is not valid JSON: ${String(err)}`);
+  }
+  const parsed = FindingBatchSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new EmitFindingError(`invalid finding batch \u2014 ${firstIssueMessage(parsed)}`);
+  }
+  const sessionId = detectUploadSessionId({ cwd, home, env, now });
+  const target = resolveUploadTarget({ item: opts.item, sessionId, home });
+  return upload(parsed.data, target, {
+    json: opts.json,
+    url: opts.url,
+    apiKey: opts.apiKey,
+    appId: opts.appId,
+    quiet: opts.quiet,
+    home,
+    env,
+    fetchImpl: opts.fetchImpl
+  });
+}
+
+export { EmitFindingError, runEmitFinding, runEmitFindings };

package/dist/emit-result-cmd-NDFHMJX7.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { EmittedNameSchema, ARTIFACT_REVIEW_CHECK_NAME, EMITTED_RESULT_MAX_LINK_LENGTH, EMITTED_RESULTS, EMITTED_RESULT_MAX_BODY_LENGTH, resolveRepoIdentity, detectActiveSession, launchRefusalForSession, detectCi } from './chunk-DEDV5V4U.js';
+import './chunk-YRYMNBGQ.js';
+import { parseTrackerNumber, trackerNumberError } from './chunk-RCQXYLMO.js';
+import './chunk-ZJSNLVCE.js';
+import './chunk-A6NNKRJU.js';
+import './chunk-IWIUYLDR.js';
+import './chunk-YMTXR7PJ.js';
+import './chunk-ECSYRPCC.js';
+import { readCloudConfig } from './chunk-TFUIDMOB.js';
+import { homeFromEnv } from './chunk-VNVZDWO3.js';
+import './chunk-Z5GEFMRW.js';
+import { randomUUID } from 'crypto';
+import { readFileSync } from 'fs';
+
+createRequire(import.meta.url);
+var GREEN = "\x1B[32m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
+var EmitResultError = class extends Error {
+};
+function parseItemFlag(raw) {
+  if (raw === void 0) return void 0;
+  const number = parseTrackerNumber(raw);
+  if (number === void 0) {
+    throw new EmitResultError(trackerNumberError("--item", raw));
+  }
+  return { number };
+}
+async function readAllStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readBodyFile(path, readStdin) {
+  if (path === "-") return (readStdin ?? readAllStdin)();
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    throw new EmitResultError(`cannot read --body-file "${path}": ${String(err)}`);
+  }
+}
+async function runEmitResult(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const home = opts.home ?? homeFromEnv();
+  const env = opts.env ?? process.env;
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  if (!EmittedNameSchema.safeParse(opts.name).success) {
+    throw new EmitResultError(
+      `invalid name "${opts.name}" \u2014 an emit name is 1-64 characters: a lowercase letter followed by lowercase letters, digits, ".", "_" or "-" (e.g. smoke.pass)`
+    );
+  }
+  const isArtifactReview = opts.name === ARTIFACT_REVIEW_CHECK_NAME;
+  const artifactId = opts.artifact === "" ? void 0 : opts.artifact;
+  if (isArtifactReview) {
+    if (artifactId === void 0) {
+      throw new EmitResultError(
+        `--artifact <id> is required for ${ARTIFACT_REVIEW_CHECK_NAME} \u2014 it names which artifact this verdict is on`
+      );
+    }
+  } else if (artifactId !== void 0) {
+    throw new EmitResultError(`--artifact is only accepted with ${ARTIFACT_REVIEW_CHECK_NAME}`);
+  }
+  const link = opts.link === "" ? void 0 : opts.link;
+  if (isArtifactReview && link !== void 0) {
+    throw new EmitResultError(
+      `--link is refused for ${ARTIFACT_REVIEW_CHECK_NAME} \u2014 an artifact verdict is a judgment on evidence already on file, never a run to point at; pass --body / --body-file instead`
+    );
+  }
+  if (link !== void 0) {
+    if (!link.startsWith("http://") && !link.startsWith("https://")) {
+      throw new EmitResultError(`invalid --link "${link}" \u2014 expected an http:// or https:// URL`);
+    }
+    if (/\s/.test(link)) {
+      throw new EmitResultError(`invalid --link \u2014 URLs cannot contain whitespace; percent-encode it`);
+    }
+    if (link.length > EMITTED_RESULT_MAX_LINK_LENGTH) {
+      throw new EmitResultError(
+        `link is ${link.length} characters \u2014 the cap is ${EMITTED_RESULT_MAX_LINK_LENGTH}`
+      );
+    }
+  }
+  let result = "pass";
+  if (opts.result !== void 0) {
+    if (!EMITTED_RESULTS.includes(opts.result)) {
+      throw new EmitResultError(`invalid --result "${opts.result}" \u2014 expected "pass" or "fail"`);
+    }
+    result = opts.result;
+  }
+  if (opts.body !== void 0 && opts.bodyFile !== void 0) {
+    throw new EmitResultError(
+      `--body and --body-file both name the sentence \u2014 pass one, not both`
+    );
+  }
+  let body;
+  if (opts.body !== void 0) {
+    body = opts.body;
+  } else if (opts.bodyFile !== void 0) {
+    body = await readBodyFile(opts.bodyFile, opts.readStdin);
+  } else if (isArtifactReview && result === "fail") {
+    body = await (opts.readStdin ?? readAllStdin)();
+  }
+  if (body !== void 0) {
+    body = body.trim();
+    if (body === "") {
+      throw new EmitResultError(
+        `the sentence is empty \u2014 --body and --body-file need something to say`
+      );
+    }
+    if (body.length > EMITTED_RESULT_MAX_BODY_LENGTH) {
+      throw new EmitResultError(
+        `the sentence is ${body.length} characters \u2014 the cap is ${EMITTED_RESULT_MAX_BODY_LENGTH}`
+      );
+    }
+  }
+  if (isArtifactReview) {
+    if (result === "fail" && body === void 0) {
+      throw new EmitResultError(
+        `a failing artifact verdict needs a sentence \u2014 pass --body or --body-file with one sentence saying what is wrong`
+      );
+    }
+  } else if (result === "fail" && link === void 0 && body === void 0) {
+    throw new EmitResultError(
+      `a failing check needs something to act on \u2014 pass --link with the run URL, or --body / --body-file with one sentence saying what is wrong`
+    );
+  }
+  const item = parseItemFlag(opts.item);
+  const identity = resolveRepoIdentity(cwd);
+  const sessionId = detectActiveSession({
+    env,
+    home,
+    cwds: identity.repoRoot !== void 0 ? [identity.repoRoot, cwd] : [cwd],
+    nowMs: now().getTime()
+  });
+  if (isArtifactReview && sessionId !== void 0) {
+    throw new EmitResultError(
+      "an artifact verdict is a person's act \u2014 record it with a person's API key, outside a recorded session."
+    );
+  }
+  if (!isArtifactReview) {
+    if (item === void 0 && sessionId === void 0) {
+      throw new EmitResultError(
+        "nothing to attach this to \u2014 no work item. Pass --item <number>; a recorded session alone does not name one, and a session with no --item is always refused as self-judgment."
+      );
+    }
+    if (sessionId !== void 0) {
+      const refusal = launchRefusalForSession(sessionId, home);
+      if (refusal !== void 0) throw new EmitResultError(refusal);
+    }
+    if (item === void 0 && sessionId !== void 0) {
+      throw new EmitResultError(
+        "a session records a check only on a work item it was not launched for, named with --item \u2014 the item this session was launched for needs a machine key (an API key run outside the recorded session) or CI."
+      );
+    }
+  }
+  const fileConfig = readCloudConfig(home);
+  const url = opts.url ?? env.OUTERLAYER_URL ?? fileConfig.url;
+  const apiKey = opts.apiKey ?? env.OUTERLAYER_API_KEY ?? fileConfig.apiKey;
+  const appId = opts.appId ?? env.OUTERLAYER_APP_ID ?? fileConfig.appId;
+  if (!url || !apiKey || !appId) {
+    const missing = [!url && "--url", !apiKey && "--api-key", !appId && "--app-id"].filter(Boolean).join(", ");
+    throw new EmitResultError(
+      `missing ${missing}. Run \`outerlayer login --url <your gateway>\` and paste the key at the prompt, or set OUTERLAYER_URL / OUTERLAYER_API_KEY / OUTERLAYER_APP_ID. Mint a key in the dashboard: Settings \u2192 API keys.`
+    );
+  }
+  const ci = detectCi(env);
+  const request = {
+    schemaVersion: 1,
+    emit: {
+      clientEmitId: randomUUID(),
+      name: opts.name,
+      result,
+      ...link !== void 0 ? { link } : {},
+      ...body !== void 0 ? { body } : {},
+      emittedAt: now().toISOString(),
+      ...ci ? { ci: true } : {},
+      ...sessionId !== void 0 ? { sessionId } : {},
+      ...item !== void 0 ? { item } : {},
+      ...isArtifactReview ? { artifactId } : {}
+    }
+  };
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const endpoint = new URL("/v1/emitted-results", url).toString();
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${apiKey}`,
+        "x-outerlayer-app-id": appId
+      },
+      body: JSON.stringify(request)
+    });
+  } catch (err) {
+    throw new EmitResultError(`network error reaching ${endpoint}: ${String(err)}`);
+  }
+  if (response.status === 401) {
+    throw new EmitResultError(
+      "not authorized \u2014 the API key is unknown, expired, or bound to a different app. Mint a fresh key: dashboard \u2192 Settings \u2192 API keys."
+    );
+  }
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = (await response.text()).replace(/\s+/g, " ").trim().slice(0, 160);
+    } catch {
+    }
+    throw new EmitResultError(`emit failed (${response.status})${detail ? `: ${detail}` : ""}`);
+  }
+  let data = {};
+  try {
+    data = (await response.json()).data ?? {};
+  } catch {
+  }
+  const anchorLabel = isArtifactReview ? `artifact ${artifactId}` : `item #${item.number}`;
+  const recordedId = typeof data.id === "string" ? data.id : "";
+  const idSuffix = recordedId ? ` ${DIM}\xB7${RESET} ${recordedId}` : "";
+  const output = opts.json ? JSON.stringify(data) : `${GREEN}\u2713${RESET} emitted ${opts.name} (${result}) ${DIM}\xB7${RESET} ${anchorLabel}${idSuffix}`;
+  if (!opts.quiet) process.stdout.write(output + "\n");
+  return { data, output, exitCode: 0 };
+}
+
+export { EmitResultError, runEmitResult };

package/dist/hook-fast-CBW4ZETX.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+export { AUTO_SYNC_DEBOUNCE_MS, WORK_ADD_RETRIES, contextPossiblyGoverned, handleWorkLaunch, hookFiredMarkerPath, maybeAutoSync, runHookFast, spoolDir } from './chunk-A6NNKRJU.js';
+import './chunk-IWIUYLDR.js';
+import './chunk-VNVZDWO3.js';
+import './chunk-Z5GEFMRW.js';
+
+createRequire(import.meta.url);

package/dist/hook-wrap-fast-36WGE6EX.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+export { hookExecSpoolPath, hookWrapStdio, installAbortForwarding, makeTailCollector, parseHookWrapArgs, runHookWrapFast, spoolDir } from './chunk-YMTXR7PJ.js';
+import './chunk-ECSYRPCC.js';
+import './chunk-VNVZDWO3.js';
+import './chunk-Z5GEFMRW.js';
+
+createRequire(import.meta.url);

package/dist/import-capture-cmd-EUMBGIV3.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import './chunk-Z5GEFMRW.js';
+import { statSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+createRequire(import.meta.url);
+var GREEN = "\x1B[32m";
+var DIM = "\x1B[2m";
+var YELLOW = "\x1B[33m";
+var RESET = "\x1B[0m";
+var ImportCaptureError = class extends Error {
+};
+var SKILL_PATH = ".outerlayer/skills/emitting-evidence/SKILL.md";
+var SNIPPET_PATH = ".outerlayer/skills/emitting-evidence/references/agents-snippet.md";
+var AGENTS_MD_PATH = ".outerlayer/AGENTS.md";
+var AGENTS_MD_MARKER = "<!-- outerlayer:capture-pack -->";
+var SKILL_CONTENT = `---
+name: emitting-evidence
+description: >
+  Emit artifacts \u2014 screenshots, recordings, reports, logs \u2014 as proof that a
+  change works, bound to the pull request via \`outerlayer emit artifact\`.
+  Use when finishing work a spec criterion or tracked requirement covers,
+  when asked to "provide evidence", "attach a screenshot", or "prove it
+  works", and in CI steps that produce verifiable output.
+---
+
+An artifact is an exhibit: evidence *of* a specific change, anchored to the
+pull request and rendered in its evidence comment. Emit the few exhibits the
+spec asks for \u2014 a reviewer should see the change working, not a gallery.
+
+## When to capture
+
+Capture AFTER the state exists, never before: run the app, the test, or the
+flow first, and shoot the working result. A screenshot of code is not
+evidence; a screenshot of the rendered page is. If the state takes setup
+(seed data, a logged-in user), finish the setup, verify by eye, then capture.
+
+## Per-kind mechanics
+
+Kind is inferred from the file's media type \u2014 name files honestly. Every
+artifact shares one upload cap of 8 MiB, whatever its kind:
+
+- **screenshot** (\`.png\`, \`.jpg\`) \u2014 one focused window or region showing the
+  proven state. Crop noise; keep enough chrome (URL bar, test summary line)
+  to show it is real.
+- **video** (\`.webm\`, \`.mp4\`) \u2014 a short recording of the flow, start to
+  outcome. Video is the kind most likely to hit the 8 MiB cap: trim dead
+  time, prefer webm.
+- **report** (\`.html\`, \`.pdf\`) \u2014 generated reports: coverage, benchmark,
+  audit output. Emit the file the tool produced, unedited.
+- **log** (\`.txt\`, \`.log\`) \u2014 command output proving a run happened: test
+  runs, migrations, gate output. Pipe to a file and emit that file.
+
+Anything else uploads as plain \`file\` \u2014 it is never guessed into a stronger
+kind, so a \`.mov\` will NOT count where a video is required; convert first.
+
+## Captions
+
+One sentence, present tense, saying what the exhibit shows and what that
+proves: "Signup blocked for a disallowed domain \u2014 the 403 page renders."
+Never put secrets, tokens, or personal data in the caption \u2014 or the pixels.
+
+## Binding with --for
+
+When a criterion is the reason you captured, bind it:
+
+    outerlayer emit artifact shot.png --caption "\u2026" --for LOGIN-01
+
+The id comes from your team's own spec or tracker \u2014 wherever criteria for
+this change are written down. The PR comment's Evidence section shows the
+id next to the artifact, and the dashboard's Floor lists it against the
+work item \u2014 but deciding whether a given criterion still needs proof, and
+of what kind, is your team's own check to write, typically a custom
+validator recorded with \`outerlayer emit\`.
+
+## The noise rule
+
+Satisfy the declared proofs; don't document everything. One exhibit per
+criterion is the norm. An unrequested artifact is worth emitting only when
+it would change how a reviewer reads the diff. When in doubt, leave it out \u2014
+evidence works because there is little of it.
+
+## Mechanics
+
+Inside a recorded session, just run the command \u2014 the artifact spools
+locally and uploads with the next \`outerlayer sync\`, bound to this session
+and turn. In CI, run it after the step that produced the file (repo and PR
+come from the CI environment). From a plain machine it anchors through the
+git checkout, or pass \`--pr <n>\` explicitly. If there is nothing to attach
+to, the command refuses \u2014 emit from the work, not from nowhere.
+`;
+var AGENTS_SNIPPET_CONTENT = `${AGENTS_MD_MARKER}
+## Emitting evidence
+
+When you finish work a spec criterion or tracked requirement covers,
+capture the working state and emit it:
+
+    outerlayer emit artifact <file> --caption "what it shows" [--for <criterion-id>] [--pr <n>]
+
+Rules: capture AFTER the state exists (run it, then shoot it); kind comes
+from the file type (png/jpg screenshot, webm/mp4 video, html/pdf report,
+txt/log log \u2014 anything else is a plain file); every artifact caps at 8
+MiB, and video is the kind most likely to hit it; captions are one
+present-tense sentence with no secrets; bind an artifact to the id of the
+requirement it proves \u2014 \`--for <id>\`, from the team's own spec or
+tracker \u2014 and pick the kind that shows the state best; the platform
+records the kind and the id and shows them next to the artifact; satisfy
+what's asked for and stop \u2014 don't document everything. Inside a recorded
+session the artifact uploads on the next \`outerlayer sync\`; in CI it
+anchors via the CI environment; otherwise the git checkout or \`--pr\`
+anchors it, and with nothing to attach to the command refuses.
+`;
+function writeOutFile(repoRoot, relPath, content) {
+  const abs = join(repoRoot, relPath);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+}
+function runImportCapture(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  let cwdStat;
+  try {
+    cwdStat = statSync(cwd);
+  } catch {
+    throw new ImportCaptureError(`no such directory: ${cwd}`);
+  }
+  if (!cwdStat.isDirectory()) throw new ImportCaptureError(`not a directory: ${cwd}`);
+  const skillAbs = join(cwd, SKILL_PATH);
+  if (existsSync(skillAbs) && readFileSync(skillAbs, "utf8") !== SKILL_CONTENT) {
+    throw new ImportCaptureError(
+      `refusing to import \u2014 ${SKILL_PATH} already exists with local edits (never overwritten; remove it first to reinstall)`
+    );
+  }
+  const files = [];
+  for (const [relPath, content] of [
+    [SKILL_PATH, SKILL_CONTENT],
+    [SNIPPET_PATH, AGENTS_SNIPPET_CONTENT]
+  ]) {
+    if (existsSync(join(cwd, relPath))) continue;
+    writeOutFile(cwd, relPath, content);
+    files.push(relPath);
+  }
+  let appendedAgentsMd = false;
+  const agentsMdAbs = join(cwd, AGENTS_MD_PATH);
+  if (existsSync(agentsMdAbs)) {
+    const existing = readFileSync(agentsMdAbs, "utf8");
+    if (!existing.includes(AGENTS_MD_MARKER)) {
+      writeFileSync(agentsMdAbs, existing + "\n" + AGENTS_SNIPPET_CONTENT);
+      appendedAgentsMd = true;
+    }
+  }
+  let output;
+  if (opts.json) {
+    output = JSON.stringify({ files, appendedAgentsMd });
+  } else {
+    const lines = files.map((f) => `${GREEN}\u2713${RESET} wrote ${f}`);
+    if (appendedAgentsMd) lines.push(`${GREEN}\u2713${RESET} appended the evidence snippet to ${AGENTS_MD_PATH}`);
+    if (files.length === 0 && !appendedAgentsMd) {
+      lines.push(`${DIM}capture pack already installed \u2014 nothing to write${RESET}`);
+    }
+    lines.push(`Run ${YELLOW}\`outerlayer emit\`${RESET} to compile the pack into your agent's native files.`);
+    output = lines.join("\n");
+  }
+  if (!opts.quiet) {
+    process.stdout.write(output + "\n");
+    if (!opts.json && !appendedAgentsMd && !existsSync(agentsMdAbs)) {
+      process.stdout.write(
+        `${DIM}  no ${AGENTS_MD_PATH} to append to \u2014 paste ${SNIPPET_PATH} into your instructions file if your harness reads no skills${RESET}
+`
+      );
+    }
+  }
+  return { files, appendedAgentsMd, output };
+}
+
+export { ImportCaptureError, runImportCapture };