@agent-pattern-labs/leads-rig 0.1.3

package/bin/lead-harness.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'child_process';
+import { createRequire } from 'module';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+const PROJECT_DIR = process.env.PUBLIC_LEADS_PROJECT || process.env.LEAD_HARNESS_PROJECT || process.cwd();
+const require = createRequire(import.meta.url);
+
+const commands = {
+  crawl: 'scripts/crawl.mjs',
+  pipeline: 'scripts/pipeline.mjs',
+  validate: 'scripts/validate-leads.mjs',
+  manifest: 'scripts/manifest.mjs',
+  ingest: 'scripts/ingest.mjs',
+  batch: 'scripts/batch-orchestrator.mjs',
+  verify: 'verify-pipeline.mjs',
+  sync: 'bin/sync.mjs',
+};
+
+const helperAliases = {
+  'trace:list': ['@razroo/iso-trace', 'list'],
+  'trace:stats': ['@razroo/iso-trace', 'stats'],
+  'trace:show': ['@razroo/iso-trace', 'show'],
+  'guard:audit': ['@razroo/iso-guard', 'audit'],
+  'guard:explain': ['@razroo/iso-guard', 'explain'],
+  'ledger:status': ['@razroo/iso-ledger', 'status'],
+  'ledger:rebuild': ['@razroo/iso-ledger', 'rebuild'],
+  'ledger:verify': ['@razroo/iso-ledger', 'verify'],
+  'capabilities:list': ['@razroo/iso-capabilities', 'list'],
+  'capabilities:explain': ['@razroo/iso-capabilities', 'explain'],
+  'capabilities:check': ['@razroo/iso-capabilities', 'check'],
+  'context:list': ['@razroo/iso-context', 'list'],
+  'context:explain': ['@razroo/iso-context', 'explain'],
+  'context:plan': ['@razroo/iso-context', 'plan'],
+  'context:check': ['@razroo/iso-context', 'check'],
+  'context:render': ['@razroo/iso-context', 'render'],
+  'cache:key': ['@razroo/iso-cache', 'key'],
+  'cache:has': ['@razroo/iso-cache', 'has'],
+  'cache:get': ['@razroo/iso-cache', 'get'],
+  'cache:put': ['@razroo/iso-cache', 'put'],
+  'cache:status': ['@razroo/iso-cache', 'status'],
+  'cache:list': ['@razroo/iso-cache', 'list'],
+  'cache:verify': ['@razroo/iso-cache', 'verify'],
+  'cache:prune': ['@razroo/iso-cache', 'prune'],
+  'index:build': ['@razroo/iso-index', 'build'],
+  'index:status': ['@razroo/iso-index', 'status'],
+  'index:query': ['@razroo/iso-index', 'query'],
+  'index:has': ['@razroo/iso-index', 'has'],
+  'index:verify': ['@razroo/iso-index', 'verify'],
+  'facts:build': ['@razroo/iso-facts', 'build'],
+  'facts:status': ['@razroo/iso-facts', 'status'],
+  'facts:query': ['@razroo/iso-facts', 'query'],
+  'facts:has': ['@razroo/iso-facts', 'has'],
+  'facts:verify': ['@razroo/iso-facts', 'verify'],
+  'score:compute': ['@razroo/iso-score', 'compute'],
+  'score:verify': ['@razroo/iso-score', 'verify'],
+  'score:check': ['@razroo/iso-score', 'check'],
+  'score:gate': ['@razroo/iso-score', 'gate'],
+  'score:compare': ['@razroo/iso-score', 'compare'],
+  'score:explain': ['@razroo/iso-score', 'explain'],
+  'canon:normalize': ['@razroo/iso-canon', 'normalize'],
+  'canon:key': ['@razroo/iso-canon', 'key'],
+  'canon:compare': ['@razroo/iso-canon', 'compare'],
+  'canon:explain': ['@razroo/iso-canon', 'explain'],
+  'preflight:plan': ['@razroo/iso-preflight', 'plan'],
+  'preflight:check': ['@razroo/iso-preflight', 'check'],
+  'preflight:explain': ['@razroo/iso-preflight', 'explain'],
+  'postflight:status': ['@razroo/iso-postflight', 'status'],
+  'postflight:check': ['@razroo/iso-postflight', 'check'],
+  'postflight:explain': ['@razroo/iso-postflight', 'explain'],
+  'timeline:status': ['@razroo/iso-timeline', 'status'],
+  'timeline:build': ['@razroo/iso-timeline', 'build'],
+  'timeline:plan': ['@razroo/iso-timeline', 'plan'],
+  'timeline:due': ['@razroo/iso-timeline', 'due'],
+  'timeline:check': ['@razroo/iso-timeline', 'check'],
+  'timeline:verify': ['@razroo/iso-timeline', 'verify'],
+  'prioritize:status': ['@razroo/iso-prioritize', 'status'],
+  'prioritize:items': ['@razroo/iso-prioritize', 'items'],
+  'prioritize:build': ['@razroo/iso-prioritize', 'build'],
+  'prioritize:rank': ['@razroo/iso-prioritize', 'rank'],
+  'prioritize:select': ['@razroo/iso-prioritize', 'select'],
+  'prioritize:check': ['@razroo/iso-prioritize', 'check'],
+  'prioritize:verify': ['@razroo/iso-prioritize', 'verify'],
+  'lineage:status': ['@razroo/iso-lineage', 'status'],
+  'lineage:record': ['@razroo/iso-lineage', 'record'],
+  'lineage:check': ['@razroo/iso-lineage', 'check'],
+  'lineage:stale': ['@razroo/iso-lineage', 'stale'],
+  'lineage:verify': ['@razroo/iso-lineage', 'verify'],
+  'redact:scan': ['@razroo/iso-redact', 'scan'],
+  'redact:verify': ['@razroo/iso-redact', 'verify'],
+  'redact:apply': ['@razroo/iso-redact', 'apply'],
+  'migrate:plan': ['@razroo/iso-migrate', 'plan'],
+  'migrate:apply': ['@razroo/iso-migrate', 'apply'],
+  'migrate:check': ['@razroo/iso-migrate', 'check'],
+};
+
+const [, , cmd, ...rest] = process.argv;
+
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  printHelp();
+  process.exit(cmd ? 0 : 1);
+}
+
+if (commands[cmd]) {
+  runScript(commands[cmd], rest);
+}
+
+if (helperAliases[cmd]) {
+  const [pkgName, subcommand] = helperAliases[cmd];
+  runIsoCli(pkgName, [subcommand, ...defaultIsoArgs(pkgName, subcommand, rest), ...rest]);
+}
+
+console.error(`Unknown command: ${cmd}\n`);
+printHelp();
+process.exit(1);
+
+function runScript(relScript, args) {
+  const scriptPath = join(PKG_ROOT, relScript);
+  if (!existsSync(scriptPath)) {
+    console.error(`public-leads: script not found: ${relScript}`);
+    process.exit(1);
+  }
+
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: {
+      ...process.env,
+      PUBLIC_LEADS_PROJECT: PROJECT_DIR,
+      PUBLIC_LEADS_ROOT: PKG_ROOT,
+      LEAD_HARNESS_PROJECT: PROJECT_DIR,
+      LEAD_HARNESS_ROOT: PKG_ROOT,
+    },
+  });
+  process.exit(result.status ?? 1);
+}
+
+function runIsoCli(pkgName, args) {
+  const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
+  const pkg = JSON.parse(require('fs').readFileSync(pkgJsonPath, 'utf8'));
+  const binRel = typeof pkg.bin === 'string'
+    ? pkg.bin
+    : Object.values(pkg.bin || {})[0];
+  if (!binRel) {
+    console.error(`public-leads: ${pkgName} does not expose a CLI bin`);
+    process.exit(1);
+  }
+  const cliPath = join(dirname(pkgJsonPath), binRel);
+  const result = spawnSync(process.execPath, [cliPath, ...args], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+  process.exit(result.status ?? 1);
+}
+
+function defaultIsoArgs(pkgName, subcommand, args) {
+  const defaults = [];
+  if (pkgName === '@razroo/iso-trace') {
+    if (!hasFlag(args, '--cwd')) defaults.push('--cwd', PROJECT_DIR);
+    if ((subcommand === 'list' || subcommand === 'stats') && !hasFlag(args, '--since')) {
+      defaults.push('--since', '7d');
+    }
+  }
+  return defaults;
+}
+
+function hasFlag(args, flag) {
+  return args.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+}
+
+function printHelp() {
+  console.log(`public-leads — CLI for the @agent-pattern-labs/leads-rig package
+
+Usage:
+  public-leads <command> [args...]
+
+Core commands:
+  crawl         Crawl public company pages and write a lead artifact
+  pipeline      Crawl, validate, manifest, and optionally ingest leads
+  validate      Validate lead artifacts against the local contract
+  manifest      Build/update data/lead-manifest.json from lead artifacts
+  ingest        Submit a validated payload to the configured ingest API
+  verify        Run the full harness verification gate
+  sync          Re-run consumer-project symlink sync
+
+Helper command families:
+  trace:*, guard:*, ledger:*, capabilities:*, context:*, cache:*, index:*,
+  facts:*, score:*, canon:*, preflight:*, postflight:*, timeline:*,
+  prioritize:*, lineage:*,
+  redact:*, migrate:*
+
+Legacy alias:
+  lead-harness <command> ...
+`);
+}

package/bin/sync.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  symlinkSync,
+  writeFileSync,
+} from 'fs';
+import { dirname, join, resolve, relative } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+const PROJECT_DIR = process.env.INIT_CWD || process.env.PUBLIC_LEADS_PROJECT || process.env.LEAD_HARNESS_PROJECT || process.cwd();
+
+const pkgJsonPath = join(PROJECT_DIR, 'package.json');
+if (existsSync(pkgJsonPath)) {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+    if (new Set(['@agent-pattern-labs/leads-rig', '@agent-pattern-labs/public-leads-harness', 'public-leads-harness', 'leads-agentic-harness']).has(pkg.name) && PROJECT_DIR === PKG_ROOT) {
+      console.log('public-leads sync: skipping (running inside harness repo).');
+      process.exit(0);
+    }
+  } catch {
+    // Ignore malformed consumer package files; symlink sync can still run.
+  }
+}
+
+if (PROJECT_DIR === PKG_ROOT) {
+  console.log('public-leads sync: skipping (PROJECT_DIR == PKG_ROOT).');
+  process.exit(0);
+}
+
+const links = [
+  { src: '.cursor/mcp.json', dst: '.cursor/mcp.json' },
+  { src: '.cursor/rules/main.mdc', dst: '.cursor/rules/main.mdc' },
+  { src: '.cursor/rules/agent-general-free.mdc', dst: '.cursor/rules/agent-general-free.mdc' },
+  { src: '.cursor/rules/agent-general-paid.mdc', dst: '.cursor/rules/agent-general-paid.mdc' },
+  { src: '.cursor/rules/agent-glm-minimal.mdc', dst: '.cursor/rules/agent-glm-minimal.mdc' },
+  { src: '.cursor/iso-route.md', dst: '.cursor/iso-route.md' },
+  { src: '.mcp.json', dst: '.mcp.json' },
+  { src: '.claude/agents', dst: '.claude/agents' },
+  { src: '.claude/settings.json', dst: '.claude/settings.json' },
+  { src: '.claude/iso-route.resolved.json', dst: '.claude/iso-route.resolved.json' },
+  { src: '.codex/config.toml', dst: '.codex/config.toml' },
+  { src: '.opencode/instructions.md', dst: '.opencode/instructions.md' },
+  { src: '.opencode/skills/public-leads.md', dst: '.opencode/skills/public-leads.md' },
+  { src: '.opencode/skills/lead-harness.md', dst: '.opencode/skills/lead-harness.md' },
+  { src: '.opencode/agents', dst: '.opencode/agents' },
+  { src: '.pi/skills', dst: '.pi/skills' },
+  { src: '.pi/prompts', dst: '.pi/prompts' },
+  { src: 'models.yaml', dst: 'models.yaml' },
+  { src: 'modes', dst: 'modes' },
+  { src: 'templates', dst: 'templates' },
+  { src: 'batch/batch-prompt.md', dst: 'batch/batch-prompt.md' },
+  { src: 'batch/batch-runner.sh', dst: 'batch/batch-runner.sh' },
+  { src: 'batch/README.md', dst: 'batch/README.md' },
+  { src: 'AGENTS.md', dst: 'AGENTS.harness.md' },
+  { src: 'CLAUDE.md', dst: 'CLAUDE.harness.md' },
+];
+
+let created = 0;
+let skipped = 0;
+let warned = 0;
+
+for (const { src, dst } of links) {
+  const absSrc = join(PKG_ROOT, src);
+  const absDst = join(PROJECT_DIR, dst);
+
+  if (!existsSync(absSrc)) {
+    console.warn(`  skip: ${src} not found in harness`);
+    skipped++;
+    continue;
+  }
+
+  const parent = dirname(absDst);
+  if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+
+  let stat = null;
+  try {
+    stat = lstatSync(absDst);
+  } catch {
+    // absent is expected
+  }
+
+  if (stat) {
+    if (stat.isSymbolicLink()) {
+      const current = readlinkSync(absDst);
+      const expected = relative(dirname(absDst), absSrc);
+      if (current === expected || resolve(dirname(absDst), current) === absSrc) {
+        skipped++;
+        continue;
+      }
+      console.warn(`  warn: ${dst} points elsewhere (${current}) -- leaving alone`);
+      warned++;
+      continue;
+    }
+    console.warn(`  warn: ${dst} already exists as a real file/dir -- leaving alone`);
+    warned++;
+    continue;
+  }
+
+  const relSrc = relative(dirname(absDst), absSrc);
+  const type = lstatSync(absSrc).isDirectory() ? 'dir' : 'file';
+  try {
+    symlinkSync(relSrc, absDst, type);
+    console.log(`  linked: ${dst} -> ${relSrc}`);
+    created++;
+  } catch (error) {
+    console.error(`  error: failed to symlink ${dst}: ${error.message}`);
+    warned++;
+  }
+}
+
+try {
+  if (ensureOpencodeInstructionRef()) created++;
+} catch (error) {
+  console.warn(`  warn: failed to patch opencode.json instructions: ${error.message}`);
+  warned++;
+}
+
+console.log(`\npublic-leads sync: ${created} created, ${skipped} skipped, ${warned} warnings (project: ${PROJECT_DIR})`);
+
+function ensureOpencodeInstructionRef() {
+  const configPath = join(PROJECT_DIR, 'opencode.json');
+  if (!existsSync(configPath)) return false;
+
+  const raw = readFileSync(configPath, 'utf8');
+  const config = JSON.parse(raw);
+  const current = Array.isArray(config.instructions)
+    ? config.instructions.slice()
+    : config.instructions
+      ? [config.instructions]
+      : [];
+
+  const required = '.opencode/instructions.md';
+  if (current.includes(required)) return false;
+
+  const next = current.slice();
+  const anchor = next.indexOf('AGENTS.harness.md');
+  if (anchor === -1) next.unshift(required);
+  else next.splice(anchor + 1, 0, required);
+  config.instructions = [...new Set(next)];
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  console.log(`  updated: opencode.json instructions += ${required}`);
+  return true;
+}

package/config/profile.example.yml

@@ -0,0 +1,34 @@
+# Lead ingest settings for the reference client.
+# Prefer environment variables for secrets in shared terminals.
+
+api:
+  # Cold Agent Leads local API default. Set target_project to a local
+  # cold-agent-leads checkout to read ADMIN_API_TOKEN/ADMIN_EMAILS from .env.
+  base_url: "http://localhost:8080"
+  ingest_path: "/api/lead-ingests"
+  target_project: ""
+  operator_email: "admin@example.com"
+  operator_email_header: "X-Admin-Email"
+  auth_header: "Authorization"
+  auth_scheme: "Bearer"
+  auth_token_env: "ADMIN_API_TOKEN"
+
+crawl:
+  max_pages: 10
+  max_domains_per_batch: 50
+  concurrency: 2
+  user_agent: "PublicLeadsBot/0.1 (+https://example.com/public-leads)"
+
+lead_policy:
+  min_confidence: 30
+  allowed_email_types:
+    - person
+    - role
+    - contact_path
+  required_fields:
+    - domain
+    - sourceUrl
+    - evidence
+    - emailType
+    - verificationStatus
+    - confidence

package/docs/ARCHITECTURE.md

@@ -0,0 +1,85 @@
+# Architecture
+
+`@agent-pattern-labs/leads-rig` follows a package-oriented harness pattern.
+
+## Package Architecture
+
+The harness repo is the npm package. Consumer projects install it, keep private data locally, and receive shared harness files through symlinks created by `bin/sync.mjs`.
+
+```text
+consumer-project/
+├── package.json                    # depends on @agent-pattern-labs/leads-rig
+├── opencode.json                   # thin local config
+├── config/profile.yml              # local API settings and secret env names
+├── data/domains.tsv                # local target domains
+├── data/lead-manifest.json         # generated, local
+├── batch/batch-input.tsv           # local batch queue
+├── batch/batch-state.tsv           # generated state
+├── batch/lead-results-*.json       # generated lead artifacts
+├── AGENTS.md                       # local overrides
+├── AGENTS.harness.md               # symlink to package AGENTS.md
+├── CLAUDE.harness.md               # symlink to package CLAUDE.md
+├── modes/                          # symlink to package modes
+├── templates/                      # symlink to package templates
+└── node_modules/@agent-pattern-labs/leads-rig/
+```
+
+## Source Of Truth
+
+`iso/` is the source for multi-harness agent configuration. `npm run build:config` runs:
+
+```bash
+iso-route build models.yaml --out .
+iso-harness build
+```
+
+This generates:
+
+- `AGENTS.md` / `CLAUDE.md`
+- `.opencode/agents/*`
+- `.opencode/skills/public-leads.md`
+- `.codex/config.toml`
+- `.cursor/rules/*`
+- `.pi/skills/*`
+- `.pi/prompts/*`
+- `.mcp.json`
+
+Generated harness config is tracked for Git/source installs and refreshed at package time through `prepack`.
+
+## Runtime Flow
+
+```text
+domain input
+  -> mode routing (/public-leads pipeline|crawl|batch)
+  -> deterministic bounded public crawler or bounded crawl workers
+  -> lead JSON artifacts
+  -> public-leads validate
+  -> public-leads manifest
+  -> public-leads ingest
+  -> configured lead store or review API
+```
+
+## Deterministic Helpers
+
+| Helper | Purpose |
+|---|---|
+| `scripts/crawl.mjs` | Crawls bounded public company pages and writes lead artifacts |
+| `scripts/pipeline.mjs` | Runs crawl, validation, manifest update, and optional ingest |
+| `scripts/validate-leads.mjs` | Normalizes and validates JSON/JSONL lead artifacts |
+| `scripts/manifest.mjs` | Records validated batches in `data/lead-manifest.json` |
+| `scripts/ingest.mjs` | Posts to the configured ingest endpoint |
+| `scripts/batch-orchestrator.mjs` | Durable batch runner using `@razroo/iso-orchestrator` |
+| `verify-pipeline.mjs` | Repo/consumer health gate |
+
+The package also carries the `@razroo/iso-*` helper ecosystem for trace, guard, ledger, cache, canon, context, preflight, postflight, prioritize, lineage, redact, migrate, score, and timeline commands.
+
+## Data Contract
+
+`templates/lead-schema.json` defines the portable lead artifact and ingest payload:
+
+- lead records
+- crawl results
+- page visits
+- ingest requests
+
+The validator intentionally accepts the same defaults the local runtime normalizes, but it fails missing source evidence, invalid URL fields, invalid `emailType`, invalid `verificationStatus`, invalid confidence, and person/role leads without email.

package/docs/CONSTRUCTION.md

@@ -0,0 +1,40 @@
+# Construction
+
+`@agent-pattern-labs/leads-rig` follows the reusable agentic harness pattern used by Agent Pattern Labs: a published harness package owns shared behavior, while consumer projects own private inputs, generated artifacts, and local overrides.
+
+## Construction Map
+
+| Pattern Area | This Harness |
+|---|---|
+| Package entry points | `bin/lead-harness.mjs`, `bin/create-leads-harness.mjs`, `bin/sync.mjs` |
+| Source of truth | `iso/` instructions, subagents, commands, MCP declarations, and model routing |
+| Runtime surfaces | `AGENTS.md`, `CLAUDE.md`, `.codex/`, `.claude/`, `.cursor/`, `.opencode/`, `.pi/`, `.mcp.json` |
+| Workflow modes | `modes/_shared.md` plus `modes/{setup,crawl,pipeline,batch,ingest,review}.md` |
+| Executable policy | `templates/lead-schema.json`, `templates/states.yml`, and `templates/*.json` helper policy files |
+| Deterministic helpers | `scripts/crawl.mjs`, `scripts/pipeline.mjs`, `scripts/validate-leads.mjs`, `scripts/manifest.mjs`, `scripts/ingest.mjs`, `scripts/batch-orchestrator.mjs` |
+| Consumer scaffold | `create-public-leads-harness <dir>` writes local config, input, output, and ignore files |
+| Consumer sync | `public-leads sync` symlinks shared harness files from the installed package |
+| Batch orchestration | `batch/batch-runner.sh` delegates to `@razroo/iso-orchestrator` with bounded parallelism |
+| Verification gates | `npm run verify`, `npm run smoke:iso`, sample validate/manifest/ingest, `npm pack` |
+
+## Maintainer Rules
+
+- Treat `iso/` as the source for shared agent instructions and generated runtime config.
+- Keep private data in consumer projects under `config/`, `data/`, `batch/`, `reports/`, and `output/`.
+- Add domain behavior through `modes/`, not by bloating always-loaded instructions.
+- Prefer deterministic helpers in `scripts/` or `lib/` over prose-only workflow rules.
+- Keep subagent roles narrow: procedural crawl work, quality reasoning, and small JSON transforms stay separate.
+- Regenerate runtime config with `npm run build:config` after changing `iso/` or `models.yaml`.
+- Run `npm run verify`, `npm run smoke:iso`, and package/install smoke tests before release.
+
+## Release Checklist
+
+1. Verify `config/profile.yml`, lead artifacts, reports, logs, and output files are gitignored.
+2. Run `npm run build:config` and inspect generated config diffs.
+3. Run `npm run verify` and `npm run smoke:iso`.
+4. Run `npx public-leads validate --input examples/sample-leads.json`.
+5. Run dry-run manifest and ingest checks against the sample artifact.
+6. Run `npm audit`.
+7. Run `npm pack` and confirm generated runtime surfaces are included.
+8. Scaffold a clean consumer project and test install-time sync from the packed package or source tree.
+9. Publish through GitHub Actions with `gh workflow run publish.yml --ref main`, or create a published release with `gh release create v0.1.3 --title v0.1.3 --generate-notes`.

package/docs/README.md

@@ -0,0 +1,5 @@
+# Documentation
+
+- [Architecture](ARCHITECTURE.md)
+- [Construction](CONSTRUCTION.md)
+- [Setup](SETUP.md)

package/docs/SETUP.md

@@ -0,0 +1,89 @@
+# Setup
+
+## Harness Development
+
+```bash
+npm install
+npm run verify
+npm run smoke:iso
+```
+
+Build generated harness config locally:
+
+```bash
+npm run build:config
+```
+
+The generated config files are ignored in git. They are created for local smoke testing and during package packing.
+
+## Consumer Project
+
+```bash
+npx -p @agent-pattern-labs/leads-rig create-public-leads-harness my-lead-project
+cd my-lead-project
+npm install
+```
+
+Then edit:
+
+- `config/profile.yml`
+- `data/domains.tsv`
+
+Use environment variables for secrets:
+
+```bash
+export ADMIN_API_TOKEN=...
+```
+
+## Validate A Payload
+
+```bash
+npx public-leads validate --input examples/sample-leads.json
+```
+
+## Crawl Domains
+
+```bash
+npx public-leads crawl --input data/domains.tsv --out data/lead-results.json
+npx public-leads pipeline --input data/domains.tsv --out data/lead-results.json
+```
+
+## Dry-Run Ingest
+
+```bash
+npx public-leads ingest --input examples/sample-leads.json --dry-run --out output/sample-ingest.json
+```
+
+## Live Ingest
+
+```bash
+npx public-leads pipeline --input data/domains.tsv --ingest --target-project /path/to/cold-agent-leads
+npx public-leads ingest --input data/lead-results.json --target-project /path/to/cold-agent-leads
+```
+
+Required request settings come from flags, environment, or `config/profile.yml`:
+
+- `api.base_url`
+- `api.ingest_path`
+- `api.target_project`
+- `api.operator_email`
+- `api.operator_email_header`
+- `api.auth_header`
+- `api.auth_scheme`
+- `api.auth_token_env`
+
+## Batch
+
+Create `batch/batch-input.tsv`:
+
+```text
+id	domain	company	notes
+1	example.com	Example	Seed target
+```
+
+Run:
+
+```bash
+batch/batch-runner.sh --dry-run
+batch/batch-runner.sh --parallel 2
+```

package/examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+`sample-leads.json` is a fictional artifact that matches the local lead-ingest
+payload shape. Use it for local validation smoke tests:
+
+```bash
+npx public-leads validate --input examples/sample-leads.json
+npx public-leads ingest --input examples/sample-leads.json --dry-run --out output/sample-ingest.json
+```

package/examples/sample-leads.json

@@ -0,0 +1,57 @@
+{
+  "jobId": "sample-agentic-harness-job",
+  "domains": ["example.com"],
+  "leads": [
+    {
+      "company": "Example",
+      "domain": "example.com",
+      "websiteUrl": "https://example.com/",
+      "contactName": "Jane Founder",
+      "title": "Founder",
+      "email": "jane@example.com",
+      "emailType": "person",
+      "sourceUrl": "https://example.com/about",
+      "sourceLabel": "About",
+      "evidence": "Jane Founder is listed on the public About page with jane@example.com.",
+      "extractionMethod": "agentic_harness_public_page",
+      "verificationStatus": "unverified",
+      "confidence": 82,
+      "warnings": [],
+      "foundAt": "2026-05-15T00:00:00.000Z"
+    },
+    {
+      "company": "Example",
+      "domain": "example.com",
+      "websiteUrl": "https://example.com/",
+      "title": "Contact form",
+      "email": "",
+      "emailType": "contact_path",
+      "sourceUrl": "https://example.com/contact",
+      "sourceLabel": "Contact",
+      "evidence": "The public contact page contains a general inquiry form.",
+      "extractionMethod": "agentic_harness_contact_form",
+      "verificationStatus": "not_applicable",
+      "confidence": 35,
+      "warnings": [],
+      "foundAt": "2026-05-15T00:00:00.000Z"
+    }
+  ],
+  "results": [
+    {
+      "domain": "example.com",
+      "websiteUrl": "https://example.com/",
+      "leads": [],
+      "pages": [
+        {
+          "url": "https://example.com/about",
+          "title": "About Example",
+          "statusCode": 200,
+          "emailsFound": 1
+        }
+      ],
+      "warnings": [],
+      "completedAt": "2026-05-15T00:00:00.000Z"
+    }
+  ],
+  "errors": []
+}