@usecoil/skill-claude 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# Coil Claude Code Skill
+
+Installable Claude Code skill package for Coil agent workflows. It verifies the
+installed CLI and installs the compatible public `@usecoil/cli` package when
+`coil` is not already available:
+
+```bash
+npx --yes @usecoil/skill-claude@0.1.0 --base-url https://www.usecoil.com
+coil config set-base-url https://www.usecoil.com --profile prod
+printf '%s' "$COIL_API_KEY" | coil auth login --profile prod --key -
+coil --profile prod agent-context --json
+```
+
+The installer copies the `coil-api` skill and its references into
+`~/.claude/skills/coil-api`. It does not modify global or project `CLAUDE.md`
+files.
+
+Supply `COIL_API_KEY` through a secret manager or hidden prompt. The installer
+does not accept, print, or persist authentication secrets. Do not configure
+`COIL_ORG_ID`; Coil API keys are organization-scoped.
+
+This package is proprietary (`UNLICENSED`). It installs a Claude Code skill,
+not an MCP server or general Claude.ai integration.

package/bin/commands.mjs

@@ -0,0 +1,5 @@
+import crossSpawn from 'cross-spawn';
+
+export function spawnSyncPortable(command, args, options = {}) {
+  return crossSpawn.sync(command, args, options);
+}

package/bin/install.mjs

@@ -0,0 +1,699 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import {
+  cpSync,
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { gunzipSync } from 'node:zlib';
+import { spawnSyncPortable } from './commands.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageMetadata = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+const SUPPORTED_CLI_RANGE = packageMetadata.coilCompatibility?.cli;
+const PUBLIC_CLI_VERSION = packageMetadata.coilCompatibility?.preferredVersion;
+const supportedCliMatch = /^(\d+)\.(\d+)\.x$/.exec(SUPPORTED_CLI_RANGE ?? '');
+const runtimeMetadata = packageMetadata.coilRuntime;
+
+if (!runtimeMetadata
+  || !['codex', 'claude', 'hermes'].includes(runtimeMetadata.name)
+  || typeof runtimeMetadata.displayName !== 'string'
+  || !/^--[a-z]+-dir$/.test(runtimeMetadata.directoryOption ?? '')
+  || typeof runtimeMetadata.defaultDirectory !== 'string'
+  || typeof runtimeMetadata.skillDirectory !== 'string') {
+  console.error('Error: the skill package does not declare a valid runtime install contract.');
+  process.exit(1);
+}
+
+if (!supportedCliMatch) {
+  console.error('Error: the skill package does not declare a valid Coil CLI compatibility range.');
+  process.exit(1);
+}
+
+const isolatedNpmConfigDir = mkdtempSync(join(tmpdir(), 'coil-npm-config-'));
+const isolatedNpmUserConfig = join(isolatedNpmConfigDir, 'user.npmrc');
+const isolatedNpmGlobalConfig = join(isolatedNpmConfigDir, 'global.npmrc');
+writeFileSync(isolatedNpmUserConfig, '');
+writeFileSync(isolatedNpmGlobalConfig, '');
+const cleanupDirs = [isolatedNpmConfigDir];
+process.on('exit', () => {
+  for (const path of cleanupDirs) rmSync(path, { recursive: true, force: true });
+});
+
+const SUPPORTED_CLI_VERSION = new RegExp(
+  `^v?${supportedCliMatch[1]}\\.${supportedCliMatch[2]}\\.\\d+(?:-[0-9A-Za-z.-]+)?$`,
+);
+if (!SUPPORTED_CLI_VERSION.test(PUBLIC_CLI_VERSION ?? '')) {
+  console.error('Error: the skill package must declare a preferred compatible Coil CLI version.');
+  process.exit(1);
+}
+const PUBLIC_CLI_SPEC = `@usecoil/cli@${PUBLIC_CLI_VERSION}`;
+const defaultNpmPrefix = process.env.npm_config_prefix || process.env.NPM_CONFIG_PREFIX || join(homedir(), '.local');
+const runtimeDefaultDir = join(homedir(), runtimeMetadata.defaultDirectory);
+
+function globalBinDir() {
+  return process.platform === 'win32' ? defaultNpmPrefix : join(defaultNpmPrefix, 'bin');
+}
+
+if (Number.parseInt(process.versions.node.split('.')[0], 10) < 20) {
+  console.error('Error: Coil setup requires Node.js 20 or newer.');
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--profile' && argv[i + 1]) args.profile = argv[++i];
+    else if (arg === '--base-url' && argv[i + 1]) args.baseUrl = argv[++i];
+    else if (arg === runtimeMetadata.directoryOption && argv[i + 1]) args.runtimeDir = argv[++i];
+    else if (arg === '--cli-package' && argv[i + 1]) args.cliPackage = argv[++i];
+    else if (arg === '--cli-sha256' && argv[i + 1]) args.cliSha256 = argv[++i];
+    else if (arg === '--help' || arg === '-h') args.help = true;
+    else {
+      console.error(`Unknown option: ${arg}`);
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+function printUsage() {
+  console.log(`
+Usage: npx ${packageMetadata.name} [options]
+
+Options:
+  --profile <name>          Suggested Coil auth profile name. Defaults to "coil".
+  --base-url <url>          Coil API base URL to include in installed setup guidance.
+                            Defaults to COIL_BASE_URL when present.
+  ${runtimeMetadata.directoryOption} <path>${' '.repeat(Math.max(1, 25 - runtimeMetadata.directoryOption.length))}${runtimeMetadata.displayName} config directory. Defaults to ~/${runtimeMetadata.defaultDirectory}.
+  --cli-package <spec>      Use an exact @usecoil/cli 0.1.x version or local .tgz instead
+                            of the public npm package when coil is absent.
+  --cli-sha256 <hex>        Required with a local --cli-package tarball; verify SHA-256 first.
+  --help                    Show this help message.
+
+Default install:
+  - Verifies a compatible Coil CLI (0.1.x), installing ${PUBLIC_CLI_SPEC} when absent
+  - Atomically installs the coil-api skill and API references
+${runtimeMetadata.guidanceFile
+    ? `  - Writes general Coil guidance to ~/${runtimeMetadata.defaultDirectory}/${runtimeMetadata.guidanceFile}`
+    : `  - Leaves global ${runtimeMetadata.displayName} instruction files unchanged`}
+
+Authentication is normally done with:
+  coil auth login
+  ${agentAuthCommand('<name>')}
+  coil --profile <name> agent-context --json
+
+The installer never accepts, prints, or persists authentication secrets.
+`);
+}
+
+function stripFrontmatter(markdown) {
+  return markdown.replace(/^---[\s\S]*?---\n*/, '');
+}
+
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function agentAuthCommand(profile) {
+  return process.platform === 'win32'
+    ? `$env:COIL_API_KEY | coil auth login --profile ${shellQuote(profile)} --key -`
+    : `printf '%s' "$COIL_API_KEY" | coil auth login --profile ${shellQuote(profile)} --key -`;
+}
+
+function upsertSection(existing, heading, body) {
+  const section = `${heading}\n\n${body.trim()}\n`;
+  if (!existing) return section;
+
+  const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`${escapedHeading}[\\s\\S]*?(?=\\n# |$)`);
+  if (pattern.test(existing)) {
+    return existing.replace(pattern, section.trimEnd()) + (existing.endsWith('\n') ? '' : '\n');
+  }
+  return `${existing.trimEnd()}\n\n${section}`;
+}
+
+function validateBaseUrl(value) {
+  if (!value) return undefined;
+  if (/[\u0000-\u001f\u007f]/.test(value)) throw new Error('--base-url cannot contain control characters.');
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error('--base-url must be an absolute HTTP(S) URL.');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname) {
+    throw new Error('--base-url must be an absolute HTTP(S) URL.');
+  }
+  if (parsed.username || parsed.password) throw new Error('--base-url cannot contain credentials.');
+  if (parsed.search || parsed.hash) {
+    throw new Error('--base-url cannot contain a query string or fragment.');
+  }
+  const localHosts = new Set(['localhost', '127.0.0.1', '::1']);
+  if (parsed.protocol === 'http:' && !localHosts.has(parsed.hostname) && !parsed.hostname.endsWith('.localhost')) {
+    throw new Error('--base-url must use HTTPS unless it targets loopback.');
+  }
+  return value.replace(/\/$/, '');
+}
+
+function validateCliPackage(value) {
+  const exactPackagePattern = new RegExp(
+    `^@usecoil/cli@${supportedCliMatch[1]}\\.${supportedCliMatch[2]}\\.\\d+(?:-[0-9A-Za-z.-]+)?$`,
+  );
+  if (exactPackagePattern.test(value)) return value;
+  const candidate = resolve(value.replace(/^file:/, ''));
+  if (candidate.endsWith('.tgz') && existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  throw new Error('--cli-package must be an exact @usecoil/cli 0.1.x version or an existing local .tgz file.');
+}
+
+function validateCliSha256(value) {
+  if (!/^[a-f0-9]{64}$/i.test(value)) {
+    throw new Error('--cli-sha256 must be a 64-character hexadecimal SHA-256 digest.');
+  }
+  return value.toLowerCase();
+}
+
+function isLocalCliPackage(value) {
+  return value.endsWith('.tgz') && existsSync(value) && statSync(value).isFile();
+}
+
+function spawnPortable(command, args, options = {}) {
+  return spawnSyncPortable(command, args, options);
+}
+
+function snapshotLocalCliPackage(path, expectedSha256) {
+  const packageBytes = readFileSync(path);
+  const actualSha256 = createHash('sha256').update(packageBytes).digest('hex');
+  if (actualSha256 !== expectedSha256) {
+    throw new Error(`--cli-package SHA-256 mismatch; expected ${expectedSha256}, received ${actualSha256}.`);
+  }
+  validateLocalCliPackageMetadata(packageBytes);
+  const snapshotDir = mkdtempSync(join(tmpdir(), 'coil-cli-package-'));
+  cleanupDirs.push(snapshotDir);
+  chmodSync(snapshotDir, 0o700);
+  const snapshotPath = join(snapshotDir, 'usecoil-cli.tgz');
+  writeFileSync(snapshotPath, packageBytes, { flag: 'wx', mode: 0o600 });
+  return snapshotPath;
+}
+
+function readTarEntry(archive, targetName) {
+  for (let offset = 0; offset + 512 <= archive.length; ) {
+    const header = archive.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+    const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
+    const sizeText = header.subarray(124, 136).toString('ascii').replace(/\0.*$/, '').trim();
+    const size = sizeText ? Number.parseInt(sizeText, 8) : 0;
+    if (!Number.isSafeInteger(size) || size < 0) throw new Error('local CLI package contains an invalid tar entry size.');
+    const contentStart = offset + 512;
+    if (name === targetName) return archive.subarray(contentStart, contentStart + size).toString('utf8');
+    offset = contentStart + Math.ceil(size / 512) * 512;
+  }
+  return null;
+}
+
+function validateLocalCliPackageMetadata(packageBytes) {
+  let metadata;
+  try {
+    const packageJson = readTarEntry(gunzipSync(packageBytes), 'package/package.json');
+    if (!packageJson) throw new Error('package/package.json is missing.');
+    metadata = JSON.parse(packageJson);
+  } catch (error) {
+    throw new Error(`--cli-package is not a readable npm package: ${error.message}`);
+  }
+
+  const expectedBin = metadata.bin?.coil === 'dist/coil.js' || metadata.bin?.coil === './dist/coil.js';
+  const expectedExports = JSON.stringify(metadata.exports) === JSON.stringify({ './package.json': './package.json' });
+  const valid = metadata.name === '@usecoil/cli'
+    && SUPPORTED_CLI_VERSION.test(String(metadata.version ?? ''))
+    && metadata.license === 'UNLICENSED'
+    && metadata.engines?.node === '>=20'
+    && expectedBin
+    && expectedExports
+    && metadata.publishConfig?.access === 'public'
+    && !metadata.main
+    && !metadata.dependencies
+    && !metadata.devDependencies;
+  if (!valid) {
+    throw new Error('--cli-package metadata must be the reviewed @usecoil/cli public executable package.');
+  }
+}
+
+function checkCli() {
+  const pathExecutable = resolveCoilOnPath();
+  const packageCheck = pathExecutable
+    ? verifyInstalledCliPackage(packagePathForExecutable(pathExecutable))
+    : verifyInstalledCliPackage();
+  if (!packageCheck.ok) {
+    return {
+      ok: false,
+      present: Boolean(pathExecutable || globalCliPackagePath()),
+      version: null,
+      reason: pathExecutable
+        ? 'A coil executable is present on PATH but is not owned by the reviewed global @usecoil/cli package.'
+        : packageCheck.reason,
+    };
+  }
+  const probeHome = mkdtempSync(join(tmpdir(), 'coil-cli-probe-'));
+  const probeEnvironment = sanitizedCliEnvironment(probeHome);
+  const result = spawnPortable(process.execPath, [packageCheck.entrypoint, '--version'], {
+    encoding: 'utf8',
+    env: probeEnvironment,
+  });
+  rmSync(probeHome, { recursive: true, force: true });
+  if (result.error?.code === 'ENOENT') return { ok: false, present: false, version: null, reason: null };
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      present: true,
+      version: null,
+      reason: 'A coil executable is present but failed its version check.',
+    };
+  }
+  const version = result.stdout.trim();
+  if (!SUPPORTED_CLI_VERSION.test(version)) return { ok: false, present: true, version, reason: null };
+
+  const discoveryHome = mkdtempSync(join(tmpdir(), 'coil-cli-discovery-'));
+  try {
+    const contextResult = spawnPortable(process.execPath, [packageCheck.entrypoint, '--json', 'agent-context'], {
+      encoding: 'utf8',
+      env: sanitizedCliEnvironment(discoveryHome),
+    });
+    const context = JSON.parse(contextResult.stdout);
+    const activationCommands = context.commands?.activation?.commands;
+    const activationStatus = Array.isArray(activationCommands)
+      && activationCommands.some((command) => command?.name === 'activation status');
+    const starterRun = Array.isArray(activationCommands)
+      && activationCommands.find((command) => command?.name === 'recipes run --starter-run');
+    const starterParams = Array.isArray(starterRun?.params) ? starterRun.params : [];
+    const hasSpendGate = starterParams.some((param) => (
+      param?.name === '--confirm-provider-spend' && param?.type === 'boolean' && param?.required === true
+    ));
+    const fetchCount = starterParams.find((param) => param?.name === '--fetch-count');
+    const hasStarterCap = fetchCount?.type === 'number'
+      && fetchCount?.required === true
+      && fetchCount?.minimum === 1
+      && fetchCount?.maximum === 25;
+    const compatible = contextResult.status === 0
+      && context.cli?.name === 'coil'
+      && context.cli?.version === version.replace(/^v/, '')
+      && activationStatus
+      && hasSpendGate
+      && hasStarterCap
+      && Array.isArray(context.commands?.recipes?.commands)
+      && context.commands.recipes.commands.some((command) => command?.name === 'recipes run');
+    return {
+      ok: Boolean(compatible),
+      present: true,
+      version,
+      reason: compatible ? null : 'The executable does not expose the required Coil runtime-discovery contract.',
+    };
+  } catch {
+    return {
+      ok: false,
+      present: true,
+      version,
+      reason: 'The executable does not return valid Coil runtime-discovery JSON.',
+    };
+  } finally {
+    rmSync(discoveryHome, { recursive: true, force: true });
+  }
+}
+
+function rollbackCliInstall() {
+  const rollback = spawnPortable('npm', [
+    'uninstall',
+    '--global',
+    '--ignore-scripts',
+    '--no-audit',
+    '--no-fund',
+    '@usecoil/cli',
+  ], { encoding: 'utf8', env: sanitizedNpmEnvironment() });
+  return !rollback.error && rollback.status === 0;
+}
+
+function globalCliPackagePath() {
+  const rootResult = spawnPortable('npm', ['root', '--global'], { encoding: 'utf8', env: sanitizedNpmEnvironment() });
+  if (rootResult.error || rootResult.status !== 0) return null;
+  const packagePath = join(rootResult.stdout.trim(), '@usecoil', 'cli', 'package.json');
+  return existsSync(packagePath) ? packagePath : null;
+}
+
+function resolveCoilOnPath() {
+  const pathEntries = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+  const names = process.platform === 'win32'
+    ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').map((ext) => `coil${ext.toLowerCase()}`)
+    : ['coil'];
+  for (const pathEntry of pathEntries) {
+    for (const name of names) {
+      const candidate = resolve(pathEntry, name);
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        // Continue searching PATH.
+      }
+    }
+  }
+  return null;
+}
+
+function packagePathForExecutable(executable) {
+  if (process.platform === 'win32') {
+    return join(dirname(executable), 'node_modules', '@usecoil', 'cli', 'package.json');
+  }
+  try {
+    const entrypoint = realpathSync(executable);
+    return join(dirname(dirname(entrypoint)), 'package.json');
+  } catch {
+    return null;
+  }
+}
+
+function verifyInstalledCliPackage(packagePath = globalCliPackagePath()) {
+  if (!packagePath) return { ok: false, reason: 'Could not locate the global npm package root after installation.' };
+  try {
+    const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
+    const expectedBin = metadata.bin?.coil === 'dist/coil.js' || metadata.bin?.coil === './dist/coil.js';
+    const expectedExports = JSON.stringify(metadata.exports) === JSON.stringify({ './package.json': './package.json' });
+    const valid = metadata.name === '@usecoil/cli'
+      && SUPPORTED_CLI_VERSION.test(String(metadata.version ?? ''))
+      && metadata.license === 'UNLICENSED'
+      && metadata.engines?.node === '>=20'
+      && expectedBin
+      && expectedExports
+      && !metadata.main
+      && !metadata.dependencies
+      && !metadata.devDependencies;
+    const entrypoint = join(dirname(packagePath), 'dist', 'coil.js');
+    const entrypointIsFile = existsSync(entrypoint) && statSync(entrypoint).isFile();
+    return valid && entrypointIsFile
+      ? { ok: true, reason: null, entrypoint }
+      : { ok: false, reason: 'The installed package metadata does not match the reviewed Coil CLI contract.' };
+  } catch {
+    return { ok: false, reason: 'The installed Coil CLI package metadata could not be read.' };
+  }
+}
+
+function sanitizedNpmEnvironment() {
+  const allowed = new Set([
+    'appdata',
+    'comspec',
+    'home',
+    'homedrive',
+    'homepath',
+    'lang',
+    'lc_all',
+    'lc_ctype',
+    'localappdata',
+    'path',
+    'pathext',
+    'systemroot',
+    'temp',
+    'tmp',
+    'tmpdir',
+    'userprofile',
+  ]);
+  const environment = Object.fromEntries(Object.entries(process.env).filter(([key]) => {
+    const normalized = key.toLowerCase();
+    return allowed.has(normalized) || normalized === 'npm_config_prefix' || normalized === 'npm_config_cache';
+  }).concat([
+    ['npm_config_prefix', defaultNpmPrefix],
+    ['npm_config_userconfig', isolatedNpmUserConfig],
+    ['npm_config_globalconfig', isolatedNpmGlobalConfig],
+  ]));
+
+  for (const key of [
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
+    'http_proxy', 'https_proxy', 'no_proxy',
+    'npm_config_proxy', 'npm_config_https_proxy', 'npm_config_noproxy', 'npm_config_registry',
+  ]) {
+    const value = process.env[key];
+    if (!value) continue;
+    if (key.toLowerCase().includes('proxy') || key === 'npm_config_registry') {
+      try {
+        const parsed = new URL(value);
+        if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) continue;
+      } catch {
+        const normalized = key.toLowerCase();
+        if (normalized !== 'no_proxy' && normalized !== 'npm_config_noproxy') continue;
+      }
+    }
+    environment[key] = value;
+  }
+  for (const key of ['npm_config_cafile', 'NODE_EXTRA_CA_CERTS']) {
+    if (process.env[key]) environment[key] = process.env[key];
+  }
+  return environment;
+}
+
+function sanitizedCliEnvironment(isolatedHome) {
+  const environment = sanitizedNpmEnvironment();
+  environment.HOME = isolatedHome;
+  environment.USERPROFILE = isolatedHome;
+  environment.COIL_API_KEY = '';
+  environment.COIL_PROFILE = '';
+  environment.COIL_BASE_URL = 'http://127.0.0.1:9';
+  environment.PATH = [globalBinDir(), environment.PATH].filter(Boolean).join(process.platform === 'win32' ? ';' : ':');
+  return environment;
+}
+
+function maybeInjectFailure(step) {
+  if (process.env.NODE_ENV === 'test' && process.env.COIL_SKILL_INSTALL_TEST_FAIL_AFTER === step) {
+    throw new Error(`Injected installer failure after ${step}`);
+  }
+}
+
+function lstatIfPresent(path) {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+const args = parseArgs(process.argv);
+args.profile ??= 'coil';
+args.baseUrl ??= process.env.COIL_BASE_URL;
+args.runtimeDir ??= runtimeDefaultDir;
+
+if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(args.profile)) {
+  console.error('Error: --profile must be 1-64 letters, numbers, dots, underscores, or hyphens.');
+  process.exit(1);
+}
+
+try {
+  args.baseUrl = validateBaseUrl(args.baseUrl);
+  if (args.cliPackage) {
+    args.cliPackage = validateCliPackage(args.cliPackage);
+    if (isLocalCliPackage(args.cliPackage)) {
+      if (!args.cliSha256) throw new Error('--cli-sha256 is required when --cli-package points to a local .tgz file.');
+      args.cliSha256 = validateCliSha256(args.cliSha256);
+      args.cliPackage = snapshotLocalCliPackage(args.cliPackage, args.cliSha256);
+    } else if (args.cliSha256) {
+      throw new Error('--cli-sha256 is only valid with a local --cli-package .tgz file.');
+    }
+  } else if (args.cliSha256) {
+    throw new Error('--cli-sha256 requires --cli-package.');
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}
+
+if (args.help) {
+  printUsage();
+  process.exit(0);
+}
+
+let cli = checkCli();
+let installedCli = false;
+if (!cli.ok && cli.present) {
+  const found = cli.version ? ` ${cli.version}` : '';
+  const detail = cli.reason ?? `Found${found}; supported versions are ${SUPPORTED_CLI_RANGE}.`;
+  console.error(`Error: ${detail} Refusing to replace an existing executable automatically.`);
+  process.exit(1);
+}
+
+if (!cli.ok) {
+  if (globalCliPackagePath()) {
+    console.error('Error: @usecoil/cli is already installed globally but its coil executable is unavailable; refusing to replace the existing package automatically.');
+    process.exit(1);
+  }
+  const installSpec = args.cliPackage ?? PUBLIC_CLI_SPEC;
+  const install = spawnPortable('npm', [
+    'install',
+    '--global',
+    '--ignore-scripts',
+    '--no-audit',
+    '--no-fund',
+    installSpec,
+  ], { encoding: 'utf8', env: sanitizedNpmEnvironment() });
+  if (install.error || install.status !== 0) {
+    const source = args.cliPackage ? 'the reviewed Coil CLI package' : `public npm package ${PUBLIC_CLI_SPEC}`;
+    console.error(`Error: ${source} could not be installed.`);
+    process.exit(1);
+  }
+  installedCli = true;
+  const packageCheck = verifyInstalledCliPackage();
+  if (!packageCheck.ok) {
+    const rollbackFailed = !rollbackCliInstall();
+    console.error(`Error: ${packageCheck.reason}`);
+    if (rollbackFailed) console.error('Warning: automatic rollback of the newly installed Coil CLI failed; remove @usecoil/cli manually.');
+    process.exit(1);
+  }
+  cli = checkCli();
+}
+
+if (!cli.ok) {
+  const rollbackFailed = installedCli && !rollbackCliInstall();
+  const detail = cli.reason ?? (cli.version ? `Found ${cli.version}; supported versions are ${SUPPORTED_CLI_RANGE}.` : 'No coil executable was found.');
+  console.error(`Error: ${detail} Install @usecoil/cli ${PUBLIC_CLI_SPEC} from the public npm registry, or rerun with --cli-package <path-to-reviewed-tarball>.`);
+  if (rollbackFailed) console.error('Warning: automatic rollback of the newly installed Coil CLI failed; remove @usecoil/cli manually.');
+  process.exit(1);
+}
+
+const runtimeDir = args.runtimeDir;
+const skillSource = join(__dirname, '..', 'skill');
+const skillDest = join(runtimeDir, ...runtimeMetadata.skillDirectory.split('/'));
+const referencesDest = runtimeMetadata.referencesDirectory
+  ? join(runtimeDir, ...runtimeMetadata.referencesDirectory.split('/'))
+  : null;
+const guidanceDest = runtimeMetadata.guidanceFile ? join(runtimeDir, runtimeMetadata.guidanceFile) : null;
+
+let stagingRoot;
+try {
+  mkdirSync(runtimeDir, { recursive: true });
+  stagingRoot = mkdtempSync(join(runtimeDir, '.coil-install-'));
+} catch (error) {
+  const rollbackFailed = installedCli && !rollbackCliInstall();
+  console.error(`Error: Coil skill installation could not create its staging directory: ${error.message}`);
+  if (rollbackFailed) console.error('Warning: automatic rollback of the newly installed Coil CLI failed; remove @usecoil/cli manually.');
+  process.exit(1);
+}
+const stagedRoot = join(stagingRoot, 'new');
+const backupRoot = join(stagingRoot, 'backup');
+const stagedSkill = join(stagedRoot, 'coil-api');
+const stagedReferences = referencesDest ? join(stagedRoot, 'coil-references') : null;
+const stagedGuidance = guidanceDest ? join(stagedRoot, runtimeMetadata.guidanceFile) : null;
+
+try {
+  mkdirSync(stagedRoot, { recursive: true });
+  mkdirSync(backupRoot, { recursive: true });
+  cpSync(skillSource, stagedSkill, { recursive: true });
+  if (stagedReferences) {
+    mkdirSync(stagedReferences, { recursive: true });
+    for (const file of ['api-endpoints.md', 'api-fields.md']) {
+      cpSync(join(skillSource, 'references', file), join(stagedReferences, file));
+    }
+  }
+
+  if (stagedGuidance) {
+    const skillBody = stripFrontmatter(readFileSync(join(skillSource, 'SKILL.md'), 'utf-8'));
+    const guidanceBody = `${skillBody}
+
+## Local Install Notes
+
+- Human auth: \`coil auth login\`
+- Agent auth: \`${agentAuthCommand(args.profile)}\`
+- API base URL: \`${args.baseUrl
+  ? `coil config set-base-url ${shellQuote(args.baseUrl)} --profile ${shellQuote(args.profile)}`
+  : `coil config set-base-url https://www.usecoil.com --profile ${shellQuote(args.profile)}`}\`
+- First discovery command: \`coil --profile ${shellQuote(args.profile)} agent-context --json\`
+- Compatible CLI: \`${SUPPORTED_CLI_RANGE}\`
+- Env fallback: \`COIL_API_KEY\` and \`COIL_BASE_URL\`
+- Do not set \`COIL_ORG_ID\`; Coil API keys are organization-scoped.
+`;
+    let existingGuidance = '';
+    let guidanceMode = 0o600;
+    if (existsSync(guidanceDest)) {
+      const guidanceStat = lstatSync(guidanceDest);
+      if (guidanceStat.isSymbolicLink() || !guidanceStat.isFile()) {
+        throw new Error(`${runtimeMetadata.guidanceFile} must be a regular file, not a symlink or special file.`);
+      }
+      existingGuidance = readFileSync(guidanceDest, 'utf8');
+      guidanceMode = guidanceStat.mode & 0o777;
+    }
+    writeFileSync(stagedGuidance, upsertSection(existingGuidance, '# Coil Integration', guidanceBody), { mode: guidanceMode });
+    chmodSync(stagedGuidance, guidanceMode);
+  }
+} catch (error) {
+  rmSync(stagingRoot, { recursive: true, force: true });
+  const rollbackFailed = installedCli && !rollbackCliInstall();
+  console.error(`Error: Coil skill installation could not be staged: ${error.message}`);
+  if (rollbackFailed) console.error('Warning: automatic rollback of the newly installed Coil CLI failed; remove @usecoil/cli manually.');
+  process.exit(1);
+}
+
+const targets = [
+  { name: 'skill', staged: stagedSkill, target: skillDest, backup: join(backupRoot, 'coil-api') },
+  ...(stagedReferences ? [{ name: 'references', staged: stagedReferences, target: referencesDest, backup: join(backupRoot, 'coil-references') }] : []),
+  ...(stagedGuidance ? [{ name: 'guidance', staged: stagedGuidance, target: guidanceDest, backup: join(backupRoot, runtimeMetadata.guidanceFile) }] : []),
+];
+const applied = [];
+
+try {
+  for (const item of targets) {
+    mkdirSync(dirname(item.target), { recursive: true });
+    const previousStat = lstatIfPresent(item.target);
+    if (previousStat?.isSymbolicLink()
+      || (item.name === 'guidance' ? previousStat && !previousStat.isFile() : previousStat && !previousStat.isDirectory())) {
+      throw new Error(`${item.target} must be a regular ${item.name === 'guidance' ? 'file' : 'directory'}, not a symlink or special file.`);
+    }
+    const hadPrevious = Boolean(previousStat);
+    if (hadPrevious) renameSync(item.target, item.backup);
+    try {
+      renameSync(item.staged, item.target);
+    } catch (error) {
+      if (hadPrevious && existsSync(item.backup)) renameSync(item.backup, item.target);
+      throw error;
+    }
+    applied.push({ ...item, hadPrevious });
+    maybeInjectFailure(item.name);
+  }
+  rmSync(stagingRoot, { recursive: true, force: true });
+} catch (error) {
+  for (const item of applied.reverse()) {
+    rmSync(item.target, { recursive: true, force: true });
+    if (item.hadPrevious && existsSync(item.backup)) renameSync(item.backup, item.target);
+  }
+  rmSync(stagingRoot, { recursive: true, force: true });
+  const rollbackFailed = installedCli && !rollbackCliInstall();
+  console.error(`Error: Coil skill installation rolled back: ${error.message}`);
+  if (rollbackFailed) console.error('Warning: automatic rollback of the newly installed Coil CLI failed; remove @usecoil/cli manually.');
+  process.exit(1);
+}
+
+console.log(`Verified Coil CLI ${cli.version} (${SUPPORTED_CLI_RANGE}).`);
+if (installedCli && !(process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').includes(globalBinDir())) {
+  const guidance = process.platform === 'win32'
+    ? `Add ${globalBinDir()} to PATH before running coil in a new terminal.`
+    : `Run: export PATH=${shellQuote(`${globalBinDir()}:$PATH`)}`;
+  console.log(guidance);
+}
+console.log(`Installed Coil skill to ${skillDest}`);
+if (referencesDest) console.log(`Installed Coil API references to ${referencesDest}`);
+if (guidanceDest) console.log(`Wrote Coil guidance to ${guidanceDest}`);
+console.log('Human auth: coil auth login');
+console.log(`Agent auth: ${agentAuthCommand(args.profile)}`);
+
+if (args.baseUrl) {
+  console.log(`Required base URL setup: coil config set-base-url ${shellQuote(args.baseUrl)} --profile ${shellQuote(args.profile)}`);
+} else {
+  console.log(`Required public-service setup: coil config set-base-url https://www.usecoil.com --profile ${shellQuote(args.profile)}`);
+}
+
+console.log(`Done. After base URL setup and authentication, run coil --profile ${shellQuote(args.profile)} agent-context --json.`);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@usecoil/skill-claude",
+  "version": "0.1.0",
+  "description": "Claude Code skill package for Coil agent workflows",
+  "type": "module",
+  "bin": {
+    "coil-skill-claude": "./bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "README.md"
+  ],
+  "keywords": [
+    "coil",
+    "claude-code",
+    "agents",
+    "lead-generation"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antons-agents/coil.git",
+    "directory": "packages/skill-claude"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "coilCompatibility": {
+    "cli": "0.1.x",
+    "preferredVersion": "0.1.0"
+  },
+  "coilRuntime": {
+    "name": "claude",
+    "displayName": "Claude Code",
+    "directoryOption": "--claude-dir",
+    "defaultDirectory": ".claude",
+    "skillDirectory": "skills/coil-api",
+    "referencesDirectory": null,
+    "guidanceFile": null
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "cross-spawn": "7.0.6"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: coil-api
+description: Use Coil's CLI and API for agent-operated outbound recipes, durable runs, lead management, automations, provider integrations, feedback, and runtime discovery. Use when an agent needs to install, authenticate, discover, or operate Coil through the same organization state humans use in the dashboard.
+---
+
+# Coil API
+
+Coil is an agent-operated outbound platform. Recipes are reusable workflows and runs are durable executions; prospect and Sales Navigator scrapes remain backing source/result records and compatibility commands.
+
+The project principle is human-agent parity: when a feature exists in the UI, agents should have an API route, CLI command, and skill-level discoverability path for the same capability.
+
+## First Command
+
+Install the supported CLI if `coil` is not already available, then ask it what
+it can do:
+
+```bash
+if ! command -v coil >/dev/null 2>&1; then
+  npm install --global @usecoil/cli@0.1.0
+fi
+coil --version
+```
+
+Start every new Coil runtime by asking the CLI what it can do:
+
+```bash
+coil agent-context --json
+```
+
+For named environments:
+
+```bash
+coil --profile prod agent-context --json
+```
+
+`agent-context` returns the selected profile, API base URL, auth mode, actor context, global flags, command manifests, output version information, and current caveats.
+
+## Authentication
+
+Prefer profile-based CLI auth:
+
+```bash
+printf '%s' "$COIL_API_KEY" | coil auth login --profile prod --key -
+coil auth use prod
+coil --profile prod auth status --json
+```
+
+On PowerShell:
+
+```powershell
+$env:COIL_API_KEY | coil auth login --profile prod --key -
+coil auth use prod
+coil --profile prod auth status --json
+```
+
+Coil API keys are first-party organization API keys. They start with `ak_` and are already scoped to an organization.
+
+Do not configure `COIL_ORG_ID`. Coil does not need it for CLI/API calls.
+
+Environment fallback is supported when a profile is not available:
+
+```bash
+export COIL_API_KEY="ak_..."
+export COIL_BASE_URL="https://your-coil-host.example.com"
+coil scrapes list --json
+```
+
+The CLI's built-in base URL is for local development. For the public service,
+explicitly run `coil config set-base-url https://www.usecoil.com --profile prod`
+before authenticating. Use `COIL_BASE_URL` only as an environment fallback when
+you cannot persist a profile.
+
+## Runtime setup
+
+This skill is portable across Codex, Claude Code, Hermes Agent, and OpenClaw.
+The runtime-specific installer or registry handles placement; Coil operations
+always use the same public JSON CLI:
+
+```bash
+npm install --global @usecoil/cli@0.1.0
+coil config set-base-url https://www.usecoil.com --profile prod
+printf '%s' "$COIL_API_KEY" | coil auth login --profile prod --key -
+coil --profile prod agent-context --json
+```
+
+On PowerShell, use `$env:COIL_API_KEY | coil auth login --profile prod --key -`
+for the authentication step.
+
+Supply `COIL_API_KEY` through the runtime secret manager and never place it in
+command arguments. OpenClaw may provide it through the `coil-api` skill entry;
+other runtimes may use their own secret manager. Do not add `COIL_ORG_ID`.
+
+## CLI JSON Rules
+
+- Use `--json` for machine-readable output.
+- Use `--output-version 2` for standard list envelopes where supported.
+- Version 2 list output shape is `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`.
+- Diagnostics and errors go to stderr.
+- Global flags: `--profile`, `--base-url`, `--json`, `--output-version`.
+
+## Common Workflows
+
+### Orient
+
+```bash
+coil --profile prod agent-context --json
+coil --profile prod config show --json
+coil --profile prod auth status --json
+```
+
+### Guided activation
+
+Use the server-derived activation state before starting a new workspace flow. Provider-backed runs require a healthy saved connection and explicit spend confirmation.
+
+```bash
+coil --profile prod activation status --json
+coil --profile prod marketplace templates --json
+coil --profile prod marketplace install coil.prospect-search --json
+coil --profile prod recipes run <starter-recipe-id> --starter-run --confirm-provider-spend --new-scrape-name "Starter prospects" --titles "Founder" --locations "Singapore" --sizes "1-10" --fetch-count 25 --input '{"fetch_count":25}' --json
+```
+
+The starter flow is capped at 25 leads. A queued or running response is not success; inspect or wait for the durable recipe run before claiming usable leads.
+
+### Provider connections
+
+Credential mutation and testing require a human organization admin. Keep secrets on stdin and never place them in arguments, logs, issue bodies, or recipe inputs.
+
+```bash
+printf '%s' "$APIFY_API_TOKEN" | coil --profile prod integrations set apify --json
+coil --profile prod integrations status apify --json
+coil --profile prod integrations test apify --json
+coil --profile prod integrations rotate --json
+coil --profile prod integrations rotate --apply --json
+coil --profile prod integrations disconnect apify --json
+```
+
+### Recipes and durable runs
+
+```bash
+coil --profile prod recipes list --status published --json
+coil --profile prod recipes view <recipe-id> --json
+coil --profile prod recipes validate <recipe-id> --json
+coil --profile prod recipes run <recipe-id> --confirm-provider-spend --new-scrape-name "Q2 prospects" --input '{"fetch_count":100}' --json
+coil --profile prod recipe-runs view <run-id> --json
+coil --profile prod recipe-runs wait <run-id> --timeout 300 --interval 2 --json
+coil --profile prod recipe-runs cancel <run-id> --json
+coil --profile prod recipe-runs retry <run-id> --json
+```
+
+Publication and ambiguous-effect reconciliation require a human organization admin. Retry/cancel behavior follows the durable run state returned by the API.
+
+### Scrapes
+
+```bash
+coil --profile prod scrapes list --json --output-version 2
+coil --profile prod scrapes get <scrape-id> --json
+coil --profile prod scrapes create --type prospect --name "Q2 prospects" --titles "VP Sales,Head of Growth" --locations "United States" --sizes "11-50,51-200" --confirm-provider-spend --json
+printf '%s' "$LINKEDIN_COOKIE" | coil --profile prod scrapes create --type sales-nav --name "Sales Nav export" --url "https://www.linkedin.com/sales/search/people?..." --user-agent "Mozilla/5.0 ..." --cookie-stdin --confirm-provider-spend --json
+```
+
+### Leads
+
+```bash
+coil --profile prod leads list --limit 50 --json --output-version 2
+# Add a scrape ID after `list` to scope the result to one run.
+coil --profile prod leads get <lead-id> --json
+coil --profile prod leads export <scrape-id> --output leads.csv
+coil --profile prod leads export <scrape-id> --view <view-id> --output saved-view.csv
+coil --profile prod leads export <scrape-id> --ids <lead-id-1>,<lead-id-2> --output selected.csv
+coil --profile prod --json leads export <scrape-id> --output leads.csv
+coil --profile prod leads emails <scrape-id>
+```
+
+### Automations
+
+API-key agents can create draft automations. Human org admins publish drafts after validation.
+
+```bash
+coil --profile prod automations create --name "Enrich leads" --webhook-url "https://hooks.example.com/enrich" --input-fields email,company_name --scope global --json
+coil --profile prod automations list --status draft --json --output-version 2
+coil --profile prod automations view <automation-id> --json
+coil --profile prod automations validate <automation-id> --json
+coil --profile prod automations results list --automation <automation-id> --json --output-version 2
+coil --profile prod automations results links add <result-id> --kind webhook_evidence --url "https://logs.example.com/run/1" --label "n8n execution" --json
+```
+
+Publishing, deletion, and egress policy management require a human org admin session:
+
+```bash
+coil automations publish <automation-id> --json
+coil automations policy get --json
+coil automations policy set --domains hooks.example.com --fields email,company_name --json
+```
+
+### SmartLead
+
+```bash
+coil --profile prod integrations status smartlead --json
+coil --profile prod smartlead campaigns --json
+coil --profile prod smartlead sequences --campaign <campaign-id> --json
+coil --profile prod smartlead send <scrape-id> --campaign <campaign-id> --filter '[{"column":"email","operator":"is_not_empty","value":""}]' --json
+```
+
+### Feedback
+
+Use feedback when a Coil task exposes product friction or a platform bug. Do not include secrets.
+
+```bash
+coil feedback "SmartLead send failed for selected leads" --type bug --json
+coil feedback draft --type feature "Add export link metadata" --json
+coil feedback drafts --json --output-version 2
+coil feedback resend <feedback-id> --json
+```
+
+## API Reference
+
+Use the local reference files when you need raw HTTP details:
+
+- `references/api-endpoints.md`
+- `references/api-fields.md`
+
+Prefer the CLI for routine operations because it handles auth, profiles, output normalization, and local retry behavior.

package/skill/references/api-endpoints.md

@@ -0,0 +1,139 @@
+# Coil API Endpoints
+
+Base URL comes from the selected CLI profile or `COIL_BASE_URL`.
+
+All authenticated requests use:
+
+```http
+Authorization: Bearer <session-token-or-ak-key>
+Content-Type: application/json
+```
+
+Coil organization API keys (`ak_...`) are accepted by agent-compatible routes.
+
+## Auth and Context
+
+| Method | Path | Notes |
+| --- | --- | --- |
+| GET | `/api/auth/status` | Returns authenticated actor, org, role, token type, and auth mode. |
+| GET | `/api/auth/api-keys` | Lists Coil organization API keys for human org admins. |
+| DELETE | `/api/auth/api-keys/{id}` | Revokes a Coil organization API key for human org admins. |
+| POST | `/api/auth/verify-key` | Verifies a Coil organization API key without exposing it. |
+
+CLI discovery wrapper:
+
+```bash
+coil agent-context --json
+```
+
+## Activation, Marketplace, and Recipes
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| GET | `/api/activation` | `coil activation status --json` |
+| GET | `/api/marketplace/templates` | `coil marketplace templates --json` |
+| POST | `/api/marketplace/templates/{id}/install` | `coil marketplace install <template-id> --json` |
+| GET | `/api/recipes` | `coil recipes list --json` |
+| GET | `/api/recipes/{id}` | `coil recipes view <recipe-id> --json` |
+| POST | `/api/recipes/{id}/validate` | `coil recipes validate <recipe-id> --json` |
+| POST | `/api/recipes/{id}/publish` | `coil recipes publish <recipe-id> --json` |
+| POST | `/api/recipes/{id}/run` | `coil recipes run <recipe-id> --confirm-provider-spend ... --json` |
+| GET | `/api/recipe-runs/{id}` | `coil recipe-runs view <run-id> --json` |
+| POST | `/api/recipe-runs/{id}/cancel` | `coil recipe-runs cancel <run-id> --json` |
+| POST | `/api/recipe-runs/{id}/retry` | `coil recipe-runs retry <run-id> --json` |
+
+Provider-backed admission requires explicit spend confirmation. A `202` queued response is durable admission, not terminal success. Recipe publication and ambiguous-effect reconciliation require a human organization admin.
+
+## Scrapes
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| GET | `/api/scrapes?limit=100` | `coil scrapes list --json` |
+| POST | `/api/scrapes` | `coil scrapes create ... --json` |
+| GET | `/api/scrapes/{id}` | `coil scrapes get <id> --json` |
+| PATCH | `/api/scrapes/{id}` | `coil scrapes rename <id> --name ...` |
+| DELETE | `/api/scrapes/{id}` | `coil scrapes delete <id> --force` |
+| POST | `/api/scrapes/{id}/recount` | `coil scrapes recount <id> --json` |
+| GET | `/api/scrapes/{id}/leads` | `coil leads list <scrape-id> --json` |
+| GET | `/api/leads` | `coil leads list --json` |
+
+Machine callers can create scrapes. Admin-gated destructive routes require a human org admin session.
+
+## Leads
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| GET | `/api/scrapes/{scrapeId}/leads?limit=50&offset=0` | `coil leads list <scrape-id> --json` |
+| GET | `/api/leads?limit=50&offset=0` | `coil leads list --json` |
+| GET | `/api/leads/{id}` | `coil leads get <id> --json` |
+| PATCH | `/api/leads/{id}` | `coil leads update <id> --fields '{...}' --json` |
+| DELETE | `/api/leads/{id}` | `coil leads delete <id> --force --json` |
+| PATCH | `/api/leads/bulk` | `coil leads bulk-update --ids ... --fields '{...}' --json` |
+| POST | `/api/export/csv` | `coil leads export <scrape-id> [--filter/--view/--ids] [--output]` |
+| GET | `/api/leads/emails?scrapeId={id}` | `coil leads emails <scrape-id>` |
+
+## Automations
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| GET | `/api/automations?status=published` | `coil automations list --json` |
+| POST | `/api/automations` | `coil automations create ... --json` |
+| GET | `/api/automations/{id}` | `coil automations view <id> --json` |
+| PATCH | `/api/automations/{id}` | `coil automations update <id> ... --json` |
+| DELETE | `/api/automations/{id}` | `coil automations delete <id> --force --json` |
+| POST | `/api/automations/{id}/validate` | `coil automations validate <id> --json` |
+| POST | `/api/automations/{id}/publish` | `coil automations publish <id> --json` |
+| POST | `/api/automations/{id}/run` | `coil automations run <id> --scrape <scrape-id> --json` |
+| GET | `/api/automations/{id}/results` | `coil automations results list --automation <id> --json` |
+| GET | `/api/automations/results` | `coil automations results list --json` |
+| GET | `/api/automations/results/{resultId}` | `coil automations results view <result-id> --json` |
+| GET | `/api/automations/results/{resultId}/links` | `coil automations results links list <result-id> --json` |
+| POST | `/api/automations/results/{resultId}/links` | `coil automations results links add <result-id> --kind webhook_evidence --url https://... --json` |
+| DELETE | `/api/automations/results/{resultId}/links/{linkId}` | `coil automations results links delete <result-id> <link-id> --json` |
+| GET | `/api/automations/policy` | `coil automations policy get --json` |
+| PUT | `/api/automations/policy` | `coil automations policy set --domains ... --fields ... --json` |
+
+API-key callers create draft automations. Publishing, deletion, and policy changes require a human org admin session. Automation result links are deliberately narrow traceability records for delivery evidence; they are not a generic metadata surface.
+
+## Settings, Preferences, Members
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| GET | `/api/settings` | `coil settings get --json` |
+| PATCH | `/api/settings` | `coil settings set <key> <value> --json` |
+| GET | `/api/preferences/columns?scrapeId={id}` | `coil preferences get --scrape <id> --json` |
+| PUT | `/api/preferences/columns` | `coil preferences set --scrape <id> ... --json` |
+| GET | `/api/members` | `coil members list --json` |
+
+## Integrations and SmartLead
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| GET | `/api/integrations` | `coil integrations list --json` |
+| GET | `/api/integrations/{provider}` | `coil integrations status <provider> --json` |
+| PUT | `/api/integrations/{provider}` | `printf '%s' "$PROVIDER_API_KEY" \| coil integrations set <provider> --json` |
+| DELETE | `/api/integrations/{provider}` | `coil integrations disconnect <provider> --json` |
+| POST | `/api/integrations/{provider}/test` | `coil integrations test <provider> --json` |
+| POST | `/api/integrations/rotate` | `coil integrations rotate [--apply] --json` |
+| GET | `/api/integrations/smartlead/campaigns` | `coil smartlead campaigns --json` |
+| GET | `/api/integrations/smartlead/campaigns/sequences?campaignId={id}` | `coil smartlead sequences --campaign <id> --json` |
+| POST | `/api/integrations/smartlead/send` | `coil smartlead send <scrape-id> --campaign <id> --json` |
+
+## Feedback
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| POST | `/api/feedback` | `coil feedback "..." --json` |
+
+The CLI also supports local feedback drafts and resend commands for retryable failures.
+
+## Activity and Usage
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| GET | `/api/activity` | `coil activity list --json` |
+| GET | `/api/usage?view=summary` | `coil usage summary --json` |
+| GET | `/api/usage?view=events` | `coil usage events --json` |
+| GET | `/api/usage?view=limits` | `coil usage limits --json` |
+
+Activity cursors are opaque. Usage endpoints require an organization admin, so machine API keys are intentionally rejected by the shared role gate.

package/skill/references/api-fields.md

@@ -0,0 +1,202 @@
+# Coil API Fields
+
+Responses use snake_case. Request bodies generally accept the field names shown by the CLI and API route schemas.
+
+## Auth Context
+
+`GET /api/auth/status` returns:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `authenticated` | boolean | Whether the bearer token is valid. |
+| `userId` | string/null | Human Clerk user ID when present. |
+| `orgId` | string/null | Clerk organization ID. |
+| `orgRole` | `org:admin`/`org:member`/null | Role for human sessions; API keys map to member behavior. |
+| `tokenType` | string/null | Usually `session_token` or `api_key`. |
+| `actor` | object | `{ type, id, name }` where type is `human` or `machine`. |
+
+## CLI Output Envelope
+
+Use `--json --output-version 2` on list commands when possible:
+
+```json
+{
+  "resource": "scrapes",
+  "items": [],
+  "total": 0,
+  "limit": 25,
+  "offset": 0,
+  "nextOffset": null,
+  "truncated": false,
+  "hint": null
+}
+```
+
+## Scrape
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | string | UUID. |
+| `org_id` | string | Tenant isolation key. |
+| `name` | string | Human-visible scrape name. |
+| `status` | string | `pending`, `running`, `completed`, `failed`, or legacy/null values. |
+| `job_titles` | string[] | Prospect scrape filter. |
+| `locations` | string[] | Prospect scrape filter. |
+| `company_sizes` | string[] | Prospect scrape filter. |
+| `industries_include` | string[]/null | Prospect filter. |
+| `industries_exclude` | string[]/null | Prospect filter. |
+| `search_url` | string/null | Sales Navigator source URL in create payloads. |
+| `fetch_count` | number | Requested prospect count. |
+| `prospect_count` | number | Current stored lead count. |
+| `smartlead_campaign_id` | string/null | Optional auto-send campaign. |
+| `created_by_user_id` | string/null | Human creator when known. |
+| `created_at` | ISO string | Creation timestamp. |
+
+Create payloads:
+
+```json
+{
+  "type": "prospect",
+  "name": "Q2 prospects",
+  "job_titles": ["VP Sales"],
+  "locations": ["United States"],
+  "company_sizes": ["11-50"],
+  "fetch_count": 100,
+  "confirm_provider_spend": true
+}
+```
+
+```json
+{
+  "type": "sales-nav",
+  "name": "Sales Nav export",
+  "search_url": "https://www.linkedin.com/sales/search/people?...",
+  "user_agent": "Mozilla/5.0 ...",
+  "linkedin_cookie": "li_at=...",
+  "confirm_provider_spend": true
+}
+```
+
+`confirm_provider_spend` is required for provider-backed acquisition. Sales Navigator credentials are resolved server-side for execution and must not be stored in recipe inputs or copied into logs.
+
+## Lead
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | string | UUID. |
+| `org_id` | string | Tenant isolation key. |
+| `scrape_id` | string | Parent scrape. |
+| `full_name` | string/null | Lead name. |
+| `first_name` | string/null | First name. |
+| `last_name` | string/null | Last name. |
+| `email` | string/null | Email when known. |
+| `linkedin` | string/null | LinkedIn profile URL. |
+| `job_title` | string/null | Role/title. |
+| `company_name` | string/null | Company. |
+| `company_domain` | string/null | Company domain. |
+| `location` | string/null | Lead location. |
+| `is_bad_fit` | boolean/null | Qualification marker. |
+| `added_to_smartlead` | boolean/null | SmartLead send marker. |
+| `smartlead_campaign` | string/null | Campaign name. |
+| `date_scraped` | string/null | Scrape date. |
+
+Filter conditions use:
+
+```json
+{
+  "column": "email",
+  "operator": "is_not_empty",
+  "value": ""
+}
+```
+
+Supported operators include equality, contains, empty/not-empty, booleans, and date comparisons. Use `coil agent-context --json` for the current command manifest.
+
+## Automation
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | string | UUID. |
+| `org_id` | string | Tenant isolation key. |
+| `name` | string | Automation name. |
+| `webhook_url` | string | HTTPS webhook URL. |
+| `input_fields` | string[] | Lead fields sent to the webhook. |
+| `scope` | `global`/`scrape` | Whether automation applies globally or to one scrape. |
+| `scrape_id` | string/null | Required for scrape-scoped automation. |
+| `status` | `draft`/`published`/`disabled` | API-key agents create drafts. |
+| `created_by_actor_type` | `human`/`machine` | Actor attribution. |
+| `created_by_actor_id` | string | User ID or API key ID. |
+| `created_by_actor_name` | string/null | API key display name when available. |
+| `published_by_user_id` | string/null | Human admin publisher. |
+| `published_at` | ISO string/null | Publication timestamp. |
+
+Create payload:
+
+```json
+{
+  "name": "Enrich leads",
+  "webhook_url": "https://hooks.example.com/enrich",
+  "input_fields": ["email", "company_name"],
+  "scope": "global",
+  "scrape_id": null
+}
+```
+
+## Automation Result
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | string | UUID. |
+| `automation_id` | string | Parent automation. |
+| `lead_id` | string | Processed lead. |
+| `status` | `pending`/`running`/`success`/`error` | Delivery state. |
+| `result` | string/null | Webhook response or summary. |
+| `error_message` | string/null | Failure detail. |
+| `created_at` | ISO string | Creation timestamp. |
+| `updated_at` | ISO string | Last status update. |
+
+## Automation Result Link
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | string | UUID. |
+| `automation_result_id` | string | Parent automation result. |
+| `kind` | `webhook_evidence`/`smartlead_campaign`/`delivery_evidence` | Accepted evidence class. |
+| `label` | string/null | Short label or delivery ID, max 120 characters. |
+| `url` | string | HTTPS URL, max 2048 characters. `smartlead_campaign` URLs must use a `smartlead.ai` host. |
+| `created_at` | ISO string | Creation timestamp. |
+
+Create payload:
+
+```json
+{
+  "kind": "webhook_evidence",
+  "label": "n8n execution",
+  "url": "https://logs.example.com/run/1"
+}
+```
+
+## Automation Policy
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `domains` | string[] | Exact or wildcard allowed webhook hosts. |
+| `fields` | string[] | Allowed lead fields for automation payloads. |
+
+Only human org admins can update policy.
+
+## Settings
+
+Settings are stored in org-scoped JSON. Common keys:
+
+| Key | Type | Notes |
+| --- | --- | --- |
+| `has_smartlead_key` | boolean | Read-only redacted presence marker. |
+| `smartlead_api_key` | string | Legacy setting. New writes are rejected; configure SmartLead with `printf '%s' "$SMARTLEAD_API_KEY" \| coil integrations set smartlead` or `PUT /api/integrations/smartlead`. |
+| `default_columns` | string[] | Optional lead table defaults. |
+
+## Agent Caveats
+
+- API-key agents currently behave as org members, not org admins.
+- Admin-gated actions include destructive scrape/automation operations, automation policy management, and automation publishing.
+- Prefer `coil feedback` for platform friction discovered while operating Coil.