agentlinkops 0.5.0

package/src/verifier/readiness.js

@@ -0,0 +1,90 @@
+import { parse, defaultTreeAdapter } from 'parse5';
+
+const INERT = new Set(['script', 'style', 'template', 'noscript']);
+const CHROME = new Set(['nav', 'header', 'footer', 'aside', 'head']);
+const ROOT_IDS = new Set(['root', 'app', '__next', '__nuxt']);
+const attr = (node, name) => node.attrs?.find((item) => item.name === name)?.value;
+const hidden = (node) => attr(node, 'hidden') !== undefined
+  || (node.tagName === 'dialog' && attr(node, 'open') === undefined)
+  || /(?:^|;)\s*(?:display\s*:\s*none|visibility\s*:\s*(?:hidden|collapse))\s*(?:!important\s*)?(?:;|$)/iu.test(attr(node, 'style') ?? '');
+
+/** Static evidence only: this does not claim computed CSS visibility or browser readiness. */
+export function assessReadiness({ html, parsed, targetUrl }) {
+  if (typeof html !== 'string') throw new TypeError('HTML must be a string');
+  const bounded = () => ({ requiresRender: true, reason: 'readiness_limit_exceeded', possibleLoginWall: false });
+  if (html.length > 2 * 1024 * 1024) return bounded();
+  let elements = 0;
+  const started = performance.now();
+  let document;
+  try {
+    document = parse(html, { treeAdapter: {
+      ...defaultTreeAdapter,
+      createElement(...args) {
+        if (++elements > 25_000 || args[2].length > 256 || performance.now() - started > 500) {
+          throw new RangeError('readiness_limit_exceeded');
+        }
+        return defaultTreeAdapter.createElement(...args);
+      },
+    } });
+  } catch (error) {
+    if (error instanceof RangeError && error.message === 'readiness_limit_exceeded') return bounded();
+    throw error;
+  }
+  let hasScript = false;
+  let targetInScript = false;
+  let hasVisiblePassword = false;
+  let contentText = '';
+  let articleText = '';
+  let emptyAppRoot = false;
+  let emptyProfileRoot = false;
+  const roots = [];
+  const stack = [{ node: document, chrome: false, form: false, article: false, root: null }];
+  while (stack.length) {
+    const state = stack.pop();
+    const { node } = state;
+    if (hidden(node)) continue;
+    if (node.tagName === 'script') {
+      hasScript = true;
+      // Script data is a rendering hint, never a link occurrence. Keep this exact and narrow.
+      if (targetUrl && node.childNodes?.some((child) => child.nodeName === '#text'
+        && child.value.replace(/\\\//gu, '/').includes(targetUrl))) targetInScript = true;
+    }
+    if (INERT.has(node.tagName)) continue;
+    const chrome = state.chrome || CHROME.has(node.tagName);
+    const form = state.form || node.tagName === 'form';
+    const article = state.article || node.tagName === 'article';
+    let root = state.root;
+    const id = (attr(node, 'id') ?? '').toLowerCase();
+    if (ROOT_IDS.has(id) || ['profile', 'profile-root', 'profile-container'].includes(id)) {
+      root = { app: ROOT_IDS.has(id), content: false, parent: root };
+      roots.push(root);
+    }
+    if (node.tagName === 'input' && (attr(node, 'type') ?? '').toLowerCase() === 'password') hasVisiblePassword = true;
+    if (!chrome && node.nodeName === '#text' && node.value.trim()) {
+      for (let ancestor = root; ancestor && !ancestor.content; ancestor = ancestor.parent) ancestor.content = true;
+      if (!form) {
+        contentText += node.value.slice(0, 256 - contentText.length);
+        if (article) articleText += node.value.slice(0, 256 - articleText.length);
+      }
+    }
+    if (!chrome && ['img', 'video', 'audio', 'iframe', 'canvas', 'input', 'textarea'].includes(node.tagName)) {
+      for (let ancestor = root; ancestor && !ancestor.content; ancestor = ancestor.parent) ancestor.content = true;
+    }
+    for (const child of node.childNodes ?? []) stack.push({ node: child, chrome, form, article, root });
+  }
+  for (const root of roots) {
+    if (!root.content && root.app) emptyAppRoot = true;
+    if (!root.content && !root.app) emptyProfileRoot = true;
+  }
+  const substantiveContent = contentText.replace(/\s+/gu, ' ').trim().length >= 80
+    || articleText.replace(/\s+/gu, ' ').trim().length >= 40;
+  const possibleLoginWall = hasVisiblePassword && !substantiveContent;
+  let reason = null;
+  if (hasScript && !substantiveContent) {
+    if (emptyAppRoot) reason = 'empty_application_root';
+    else if (emptyProfileRoot && targetInScript) reason = 'profile_target_in_script_only';
+    else if (!(parsed?.links?.length) && !contentText.trim()) reason = 'empty_script_shell';
+  }
+  return { requiresRender: reason !== null, reason, possibleLoginWall,
+    hasVisiblePassword, targetInScript, emptyAppRoot, emptyProfileRoot };
+}

package/src/verifier/render-evidence.js

@@ -0,0 +1,57 @@
+import { validatePublicUrl } from './url.js';
+import { retryAfterSeconds } from './fetch.js';
+
+const text = (value, max = 256) => typeof value === 'string' && value.length <= max && !/[\x00-\x1f\x7f]/u.test(value);
+const url = value => text(value, 2048) && validatePublicUrl(value).valid;
+
+// Native transport metadata is checked separately from the DOM parser. A provider's
+// ready flag cannot turn a challenge, failed session or partial document into proof.
+export function nativeRenderEvidence(doc, version) {
+  const invalid = reason => ({ reason });
+  if (version !== 1 || doc.rendererVersion !== 'cf-native-1'
+    || !text(doc.contentType) || !text(doc.cfMitigated)
+    || typeof doc.challenge !== 'boolean' || typeof doc.visibleLogin !== 'boolean'
+    || typeof doc.browserClosed !== 'boolean'
+    || !text(doc.browserVersion) || !doc.browserVersion || !text(doc.userAgent, 512) || !doc.userAgent
+    || !Number.isInteger(doc.requestCount) || doc.requestCount < 1 || doc.requestCount > 150
+    || !Number.isFinite(doc.durationMs) || doc.durationMs < 0 || doc.durationMs > 20_000
+    || !(doc.terminationReason === null || text(doc.terminationReason, 80))
+    || !Array.isArray(doc.robotsHistory) || !doc.robotsHistory.length || doc.robotsHistory.length > 150) return invalid('invalid_native_render_evidence');
+  if (doc.browserClosed !== true) return invalid('render_close_unconfirmed');
+  if (doc.terminationReason) return invalid('render_acquisition_incomplete');
+  if (doc.cfMitigated.toLowerCase() === 'challenge' || doc.challenge) return invalid('render_access_challenge');
+  if (doc.cfMitigated) return invalid('render_access_mitigated');
+  if (doc.visibleLogin) return invalid('render_login_wall');
+  if (!/^(?:text\/html|application\/xhtml\+xml)(?:\s*;|\s*$)/iu.test(doc.contentType)) return invalid('render_not_html');
+  const robotsHistory = [];
+  for (const row of doc.robotsHistory) {
+    if (!row || !url(row.sourceUrl) || !url(row.robotsUrl) || row.allowed !== true
+      || row.productToken !== 'LinktrailBot' || !text(row.reason, 80)
+      || !Number.isInteger(row.httpStatus) || row.httpStatus < 100 || row.httpStatus > 599
+      || (row.crawlDelaySeconds !== null && (!Number.isFinite(row.crawlDelaySeconds) || row.crawlDelaySeconds < 0))) return invalid('invalid_render_robots_evidence');
+    robotsHistory.push({ sourceUrl: row.sourceUrl, robotsUrl: row.robotsUrl, allowed: true,
+      productToken: 'LinktrailBot', reason: row.reason, httpStatus: row.httpStatus,
+      crawlDelaySeconds: row.crawlDelaySeconds });
+  }
+  // Each main-document hop must have a recorded authorization, including the final URL.
+  const authorized = new Set(robotsHistory.map(row => row.sourceUrl));
+  if (!authorized.has(doc.finalUrl) || doc.redirects.some(hop => !authorized.has(hop.from) || !authorized.has(hop.to))) return invalid('invalid_render_robots_evidence');
+  const evidence = { rendererVersion: doc.rendererVersion, contentType: doc.contentType,
+    cfMitigated: doc.cfMitigated, challenge: false, visibleLogin: false, browserClosed: true,
+    browserVersion: doc.browserVersion, userAgent: doc.userAgent, requestCount: doc.requestCount,
+    durationMs: doc.durationMs, terminationReason: null, robotsHistory };
+  for (const key of ['blockedMutationRequests','blockedEssentialRequests']) {
+    if (doc[key] === undefined) continue;
+    if (!Number.isInteger(doc[key]) || doc[key] < 0 || doc[key] > 150) return invalid('invalid_native_render_evidence');
+    evidence[key] = doc[key];
+  }
+  if (doc.sessionId !== undefined) {
+    if (!text(doc.sessionId, 128)) return invalid('invalid_native_render_evidence');
+    evidence.sessionId = doc.sessionId;
+  }
+  if (doc.retryAfter !== undefined) {
+    if (!text(doc.retryAfter,128)) return invalid('invalid_native_render_evidence');
+    evidence.retryAfterSeconds = retryAfterSeconds(doc.retryAfter);
+  }
+  return { evidence };
+}

package/src/verifier/robots.js

@@ -0,0 +1,85 @@
+// RFC 9309 matching, with conservative treatment of unavailable/access-blocked files
+// performed by the fetcher. Unknown extension directives are not access grants.
+function normalizedOctets(value) {
+  return value.replace(/%([0-9a-f]{2})/giu, (_, hex) => {
+    const char = String.fromCharCode(Number.parseInt(hex, 16));
+    return /[a-z0-9._~-]/iu.test(char) ? char : `%${hex.toUpperCase()}`;
+  }).replace(/[^\x00-\x7f]/gu, (char) => encodeURIComponent(char));
+}
+
+// Linear-space wildcard matcher; avoids regex backtracking on origin-controlled patterns.
+function matches(pattern, path, budget) {
+  let anchored = pattern.endsWith('$');
+  if (anchored) pattern = pattern.slice(0, -1);
+  else pattern += '*';
+  let pi = 0;
+  let si = 0;
+  let star = -1;
+  let retry = 0;
+  while (si < path.length) {
+    if (--budget.remaining < 0) return null;
+    if (pattern[pi] === '*') { star = pi++; retry = si; }
+    else if (pattern[pi] === path[si]) { pi++; si++; }
+    else if (star !== -1) { pi = star + 1; si = ++retry; }
+    else return false;
+  }
+  while (pattern[pi] === '*') pi++;
+  return pi === pattern.length;
+}
+
+export function robotsDecision(text, url, productToken = 'LinktrailBot') {
+  const groups = [];
+  let group = null;
+  let hasDirectives = false;
+  let ruleCount = 0;
+  for (const original of text.replace(/^\uFEFF/u, '').split(/\r?\n/u)) {
+    const line = original.split('#', 1)[0].trim();
+    const colon = line.indexOf(':');
+    if (colon < 0) continue;
+    const key = line.slice(0, colon).trim().toLowerCase();
+    const value = line.slice(colon + 1).trim();
+    if (key === 'user-agent') {
+      if (!group || hasDirectives) {
+        group = { agents: [], rules: [], crawlDelays: [] };
+        groups.push(group);
+        hasDirectives = false;
+      }
+      if (value) group.agents.push(value.toLowerCase());
+    } else if (group && ['allow', 'disallow', 'crawl-delay'].includes(key)) {
+      hasDirectives = true;
+      if (key === 'crawl-delay') {
+        const delay = Number(value);
+        if (value && Number.isFinite(delay) && delay >= 0) group.crawlDelays.push(delay);
+      } else if (value.startsWith('/')) {
+        if (++ruleCount > 5000 || value.length > 8192) return { allowed: null, reason: 'robots_too_complex' };
+        group.rules.push({ allow: key === 'allow', path: normalizedOctets(value) });
+      }
+    }
+  }
+  const token = productToken.toLowerCase();
+  // PREFIX, not substring. RFC 9309 and Google's implementation both match a robots `User-agent`
+  // value against the beginning of the crawler's product token — which is why `googlebot` selects
+  // the group for `Googlebot-News`. Substring matching additionally selected a group written for
+  // `bot` or `trail`, and since the common case is `Disallow: /`, that refused fetches we were
+  // allowed to make and reported them as the publisher's choice.
+  //
+  // A short prefix like `link` still matches, and that is the spec working as designed rather than
+  // a defect: it is the reason crawler names are chosen to be distinctive.
+  const specific = groups.filter((item) => item.agents.some((agent) => agent !== '*' && token.startsWith(agent)));
+  const applicable = specific.length ? specific : groups.filter((item) => item.agents.includes('*'));
+  const path = normalizedOctets(`${new URL(url).pathname}${new URL(url).search}`);
+  const matching = [];
+  const budget = { remaining: 2_000_000 };
+  for (const rule of applicable.flatMap((item) => item.rules)) {
+    const matched = matches(rule.path, path, budget);
+    if (matched === null) return { allowed: null, reason: 'robots_too_complex' };
+    if (matched) matching.push(rule);
+  }
+  matching.sort((a, b) => b.path.replace(/[\*$]/gu, '').length - a.path.replace(/[\*$]/gu, '').length || Number(b.allow) - Number(a.allow));
+  return {
+    allowed: matching.length ? matching[0].allow : true,
+    reason: matching.length && !matching[0].allow ? 'robots_disallowed' : 'robots_allowed',
+    matchedRule: matching[0]?.path ?? null,
+    crawlDelaySeconds: Math.max(0, ...applicable.flatMap((item) => item.crawlDelays)),
+  };
+}

package/src/verifier/transition.js

@@ -0,0 +1,129 @@
+const CONFIRMATION_MS = 30 * 60 * 1000;
+
+const timeOf = (value) => {
+  if (value === null || value === undefined || value === '') return null;
+  const time = new Date(value).getTime();
+  return Number.isFinite(time) ? time : null;
+};
+
+function summary(observation) {
+  if (!observation) return null;
+  const { evidence } = observation;
+  const all = observation.occurrences ?? [];
+  // State/event snapshots are small references to full observations in D1/R2.
+  // linkSignature covers ALL occurrences, preserving change detection beyond excerpts.
+  return {
+    state: observation.state,
+    reason: observation.reason,
+    sourceUrl: observation.sourceUrl,
+    finalUrl: observation.finalUrl,
+    targetUrl: observation.targetUrl,
+    targetScope: observation.targetScope,
+    httpStatus: observation.httpStatus,
+    checkedAt: observation.checkedAt,
+    linkSignature: observation.linkSignature,
+    occurrenceCount: observation.occurrenceCount ?? all.length,
+    occurrencesTruncated: observation.occurrencesTruncated === true || all.length > 10,
+    occurrences: all.slice(0, 10).map(({ href, targetUrl, anchor, rel, context, locator }) => ({
+      href: href?.slice(0, 512), targetUrl: targetUrl?.slice(0, 512), anchor: anchor?.slice(0, 256),
+      rel, context: context?.slice(0, 320), locator,
+    })),
+    directives: observation.directives ? { noindex: observation.directives.noindex, nofollow: observation.directives.nofollow, indexingStatus: observation.directives.indexingStatus } : undefined,
+    evidence: evidence ? {
+      complete: evidence.complete, method: evidence.method, checkerVersion: evidence.checkerVersion,
+      sha256: evidence.sha256, bytes: evidence.bytes, fetchedAt: evidence.fetchedAt,
+    } : undefined,
+  };
+}
+
+function fingerprint(observation) {
+  if (observation?.linkSignature) return observation.linkSignature;
+  return JSON.stringify({
+    source: observation?.finalUrl,
+    occurrences: observation?.occurrences?.map(({ targetUrl, anchor, rel }) => ({ targetUrl, anchor, rel: [...(rel ?? [])].sort() })),
+    noindex: observation?.directives?.noindex,
+    nofollow: observation?.directives?.nofollow,
+  });
+}
+
+/** Pure state reducer. Persist its result atomically with the observation + outbox. */
+export function transitionState(previous, observation, now = Date.now()) {
+  const prior = previous ?? {};
+  const checkedMs = timeOf(observation.checkedAt) ?? timeOf(typeof now === 'function' ? now() : now);
+  if (checkedMs === null) throw new TypeError('A valid observation timestamp is required');
+  const checkedAt = new Date(checkedMs).toISOString();
+  const latestMs = prior.latestAttempt ? timeOf(prior.latestAttempt.checkedAt) : null;
+  const base = {
+    state: prior.state ?? 'unknown',
+    latestAttempt: prior.latestAttempt ?? null,
+    lastSuccessfulObservation: prior.lastSuccessfulObservation ?? null,
+    firstAbsentAt: prior.firstAbsentAt ?? null,
+    absentCount: prior.absentCount ?? 0,
+    firstUnavailableAt: prior.firstUnavailableAt ?? null,
+    unavailableCount: prior.unavailableCount ?? 0,
+    sourceUnavailableConfirmed: prior.sourceUnavailableConfirmed ?? false,
+    wasEverPresent: prior.wasEverPresent ?? prior.lastSuccessfulObservation?.state === 'present',
+    nextCheckAt: null,
+    retryNotBefore: prior.retryNotBefore ?? null,
+    uncertain: prior.uncertain ?? true,
+    event: null,
+    ignored: false,
+  };
+  if (latestMs !== null && checkedMs <= latestMs) return { ...base, nextCheckAt: prior.nextCheckAt ?? null, ignored: true };
+  base.latestAttempt = summary({ ...observation, checkedAt });
+  if (observation.state === 'unknown' || observation.evidence?.complete !== true) {
+    base.uncertain = true;
+    // A scheduler decides retry/backoff after an unknown; no past due timestamp loop. The one
+    // thing carried is a floor the publisher stated in a Retry-After — "not before", never "then",
+    // so the scheduler takes the later of this and the watch's own cadence.
+    if (Number.isFinite(observation.retryAfterSeconds)) {
+      base.retryNotBefore = new Date(checkedMs + observation.retryAfterSeconds * 1000).toISOString();
+    }
+    return base;
+  }
+  if (!['present', 'absent', 'source_unavailable'].includes(observation.state)) throw new TypeError('Invalid observation state');
+  base.lastSuccessfulObservation = base.latestAttempt;
+  base.uncertain = false;
+  if (observation.state === 'present') {
+    base.state = 'present';
+    base.wasEverPresent = true;
+    base.firstAbsentAt = null;
+    base.absentCount = 0;
+    base.firstUnavailableAt = null;
+    base.unavailableCount = 0;
+    base.sourceUnavailableConfirmed = false;
+    let type;
+    if (!prior.wasEverPresent && prior.lastSuccessfulObservation?.state !== 'present') type = 'placement_acquired';
+    else if (prior.state === 'confirmed_missing' || prior.sourceUnavailableConfirmed) type = 'placement_recovered';
+    else if (prior.lastSuccessfulObservation?.state === 'present' && fingerprint(prior.lastSuccessfulObservation) !== fingerprint(observation)) type = 'placement_changed';
+    if (type) base.event = { type, before: summary(prior.lastSuccessfulObservation), after: base.latestAttempt };
+    return base;
+  }
+  if (observation.state === 'absent') {
+    const first = timeOf(base.firstAbsentAt);
+    base.firstAbsentAt = first === null ? checkedAt : base.firstAbsentAt;
+    base.absentCount = first === null ? 1 : base.absentCount + 1;
+    base.firstUnavailableAt = null;
+    base.unavailableCount = 0;
+    base.sourceUnavailableConfirmed = false;
+    const confirmed = first !== null && checkedMs - first >= CONFIRMATION_MS && base.absentCount >= 2;
+    base.state = confirmed ? 'confirmed_missing' : 'suspected_missing';
+    if (!confirmed) base.nextCheckAt = new Date((first ?? checkedMs) + CONFIRMATION_MS).toISOString();
+    if (confirmed && prior.state !== 'confirmed_missing' && base.wasEverPresent) {
+      base.event = { type: 'placement_lost', before: summary(prior.lastSuccessfulObservation), after: base.latestAttempt };
+    }
+    return base;
+  }
+  const first = timeOf(base.firstUnavailableAt);
+  base.firstUnavailableAt = first === null ? checkedAt : base.firstUnavailableAt;
+  base.unavailableCount = first === null ? 1 : base.unavailableCount + 1;
+  base.firstAbsentAt = null;
+  base.absentCount = 0;
+  base.state = 'source_unavailable';
+  base.sourceUnavailableConfirmed = first !== null && checkedMs - first >= CONFIRMATION_MS && base.unavailableCount >= 2;
+  if (!base.sourceUnavailableConfirmed) base.nextCheckAt = new Date((first ?? checkedMs) + CONFIRMATION_MS).toISOString();
+  if (base.sourceUnavailableConfirmed && !prior.sourceUnavailableConfirmed) {
+    base.event = { type: 'source_unavailable', before: summary(prior.lastSuccessfulObservation), after: base.latestAttempt };
+  }
+  return base;
+}

package/src/verifier/url.js

@@ -0,0 +1,56 @@
+const RESERVED_SUFFIXES = [
+  'localhost', 'local', 'internal', 'intranet', 'lan', 'home', 'home.arpa',
+  'test', 'invalid', 'example', 'onion', 'alt', 'arpa',
+];
+
+/** Lexical screening only. A public-only fetch transport MUST also prevent DNS rebinding. */
+export function validatePublicUrl(input) {
+  if (typeof input !== 'string' || input.length > 8192 || /[\u0000-\u0020\u007f\\]/u.test(input)) {
+    return { valid: false, reason: 'invalid_url' };
+  }
+  let url;
+  try { url = new URL(input); } catch { return { valid: false, reason: 'invalid_url' }; }
+  if (!['http:', 'https:'].includes(url.protocol)) return { valid: false, reason: 'unsupported_protocol' };
+  if (url.username || url.password) return { valid: false, reason: 'url_credentials' };
+  if (url.port) return { valid: false, reason: 'unsupported_port' };
+  // URL canonicalization expands hexadecimal, octal and integer IPv4 spellings.
+  // No literal IPs are a supported publisher target, even globally routable ones.
+  const hostname = url.hostname.toLowerCase().replace(/\.$/, '');
+  if (hostname.startsWith('[') || /^\d+\.\d+\.\d+\.\d+$/.test(hostname)) {
+    return { valid: false, reason: 'ip_literal_not_supported' };
+  }
+  if (hostname.length > 253 || !hostname.includes('.') || hostname.split('.').some(
+    (label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label),
+  )) return { valid: false, reason: 'non_public_hostname' };
+  if (RESERVED_SUFFIXES.some((suffix) => hostname === suffix || hostname.endsWith(`.${suffix}`))) {
+    return { valid: false, reason: 'non_public_hostname' };
+  }
+  url.hostname = hostname;
+  url.hash = '';
+  return { valid: true, url: url.href, hostname };
+}
+
+export function matchesTarget(candidate, target, scope) {
+  const found = new URL(candidate);
+  const wanted = new URL(target);
+  found.hostname = found.hostname.toLowerCase().replace(/\.$/, '');
+  wanted.hostname = wanted.hostname.toLowerCase().replace(/\.$/, '');
+  switch (scope) {
+    case 'domain':
+      return found.hostname === wanted.hostname || found.hostname.endsWith(`.${wanted.hostname}`);
+    case 'subdomain':
+      return found.hostname === wanted.hostname;
+    case 'path': {
+      const prefix = wanted.pathname.endsWith('/') ? wanted.pathname : `${wanted.pathname}/`;
+      return found.origin === wanted.origin
+        && (found.pathname === wanted.pathname || found.pathname.startsWith(prefix))
+        && (!wanted.search || found.search === wanted.search);
+    }
+    case 'exact':
+      found.hash = '';
+      wanted.hash = '';
+      return found.href === wanted.href;
+    default:
+      return false;
+  }
+}

package/templates/SITE.template.md

@@ -0,0 +1,59 @@
+# SITE.md — fill-in template
+
+Copy this file to `.claude/SITE.md` in the site's repository and fill in every section. The
+content skills in this package resolve their rules from it: remove a section only if it truly
+does not apply, and say so in its place — an empty section reads as "no rules", which is a
+different statement than "not applicable here". Placeholder text in brackets is not a value;
+nothing ships with brackets left in.
+
+Nothing in this file is sent anywhere. It is the customer's own judgment about their own site,
+kept in their own repository.
+
+## Site identity
+
+- **Public site:** [https://example.com/] — [static export / SSR / plain HTML; where content lives in the repo]
+- **What the business sells:** [one sentence, in the reader's words]
+- **Niche:** [the niche, stated narrowly enough that "relevant publisher" is decidable]
+- **Page types:** [hub / comparison / review / explainer / tool — the real URL patterns, e.g. /compare/x-vs-y/]
+
+## Voice
+
+[2-4 sentences a new writer can hold every page to. Name the reader and what they are checking.
+Evidence beats enthusiasm, or whatever is true for this site. If a fuller voice reference exists
+in the repo, link it here and keep this section as the summary. Read by: source-cited-content-builder
+(drafting), source-cited-humanizer (the pass), pre-publish-review (Pass B).]
+
+## Terminology table
+
+One term per concept. Enforced by pre-publish-review; used by the humanizer pass.
+
+| Use | Don't use | Notes |
+| --- | --- | --- |
+| [preferred term] | [term to avoid] | [why, or a claims-policy pointer] |
+| [preferred term] | [term to avoid] | |
+
+## Claims policy
+
+[What may be claimed, with what evidence, and what may never be claimed. For health-adjacent,
+legal or financial niches this section is load-bearing: state the categories that are CRITICAL
+findings if asserted without evidence (medical, dosage, legal, financial outcomes), the disclosure
+rules (e.g. affiliate disclosure placement), and who signs off on edge cases. Read by:
+source-cited-content-builder (guardrails) and pre-publish-review (claims-policy findings).]
+
+## Niche primary sources
+
+[The sources this niche's facts must come from, ranked. Government, standards bodies, utilities,
+manufacturers, recognized industry publications — then the niche's own credible primary sources.
+Name any source class that must NEVER be cited (e.g. vendor marketing claims for health-adjacent
+facts). Read by: source-cited-content-builder, step 2 — this list is what "your niche's preferred
+primary sources (SITE.md)" resolves to.]
+
+## Content roots
+
+[The directories or URL prefixes where publishable content lives, for the orphan check and the
+internal-link pass. Example: content pages under /guides/ built from content/ in the repo. Read
+by: internal-linking-optimizer (scan scope, orphan grep) and pre-publish-review (Pass A linking).]
+
+- Content directories: [paths in the repository]
+- Published URL patterns: [patterns, e.g. /guides/<slug>/]
+- Sitemap: [path or URL, if one exists]

package/templates/campaigns.v1.json

@@ -0,0 +1,65 @@
+{
+  "schema_version": 1,
+  "campaigns": {
+    "guest_post": {
+      "version": 1,
+      "goal": "Contribute an original article useful to a relevant publisher's audience.",
+      "inputs": ["product audience", "author expertise", "proposed topic", "linkable target"],
+      "qualify": ["Publisher covers this audience", "Recent editorial activity", "Published contribution route or explicit editor interest", "Proposed topic adds material the site lacks"],
+      "evidence": ["Relevant recent article URL", "Contribution-policy URL and observed date", "Editor or submission form source"],
+      "reject": ["Required payment hidden from campaign owner", "Irrelevant audience", "Mass-produced guest-post inventory without editorial review"],
+      "agent_work": ["Read contribution terms", "Develop a differentiated outline", "Use the existing email tool when outreach is authorized"],
+      "success": "Published article contains an accurate, contextually useful attribution to the target asset."
+    },
+    "resource_addition": {
+      "version": 1,
+      "goal": "Help a resource-page editor add a genuinely useful missing resource.",
+      "inputs": ["target resource", "reader problem solved", "topic and geography", "resource-page examples"],
+      "qualify": ["Page curates outside resources", "Our asset fills an observable gap", "Page's audience matches the asset", "Publisher has a working submission route"],
+      "evidence": ["Candidate source page", "Relevant section and current neighboring resources", "Specific missing information our asset supplies"],
+      "reject": ["The target duplicates an existing resource without improvement", "Resource is mainly a sales page with little independent utility"],
+      "agent_work": ["Read the page in context", "Explain the precise addition", "Record editor response using external message IDs"],
+      "success": "The editor adds the resource to a relevant section, then an independent check verifies the placement."
+    },
+    "broken_link": {
+      "version": 1,
+      "goal": "Offer an accurate replacement for a demonstrably unavailable cited resource.",
+      "inputs": ["source page", "dead destination", "replacement asset", "original citation purpose"],
+      "qualify": ["Repeated checks establish unavailability rather than blocking", "Replacement answers the original citation's purpose", "Replacement claims have evidence"],
+      "evidence": ["Original anchor and surrounding context", "Check status and time", "Archived original when available", "Replacement comparison"],
+      "reject": ["A single timeout or bot challenge treated as dead", "Replacement meaning differs from original", "Historical source unavailable but replacement accuracy unverified"],
+      "agent_work": ["Investigate ambiguous browser results", "Compare original context and replacement", "Explain the broken resource factually"],
+      "success": "The editor repairs the citation using a suitable destination and monitoring confirms the result."
+    },
+    "competitor": {
+      "version": 1,
+      "goal": "Find relevant publisher opportunities from observed competitor placements.",
+      "inputs": ["named competitors", "our audience and differentiator", "desired asset", "known source coverage"],
+      "qualify": ["Placement is editorially relevant", "Our offering independently merits inclusion", "Source remains active", "There is a real route to contribute or request correction"],
+      "evidence": ["Observed source page and destination", "Provider or owned-index provenance and retrieval time", "Fresh source verification", "Editorial inclusion criteria"],
+      "reject": ["Competitor link is assumed to guarantee our eligibility", "Affiliate or sponsorship terms concealed", "Provider disappearance treated as confirmed link loss"],
+      "agent_work": ["Classify the actual campaign mechanism", "Propose a specific contribution", "Preserve discovery coverage limitations"],
+      "success": "A qualified, evidence-backed opportunity becomes an earned, independently verified placement."
+    },
+    "reclamation": {
+      "version": 1,
+      "goal": "Repair a previously earned link or request useful attribution for an existing mention.",
+      "inputs": ["prior placement or mention", "correct destination", "current observation", "prior publisher relationship if known"],
+      "qualify": ["Prior link or relevant mention has evidence", "Change is confirmed rather than an inaccessible page", "Correct destination helps the reader"],
+      "evidence": ["Earlier and current observations", "Source URL and surrounding context", "Correct canonical destination"],
+      "reject": ["Unknown fetch outcome described as intentional removal", "Unrelated namesake mention", "Attribution request presented as a legal demand without a basis"],
+      "agent_work": ["Inspect ambiguous changes", "Check whether our own destination changed", "Use the prior thread when available"],
+      "success": "The placement is repaired or useful attribution is added, with the outcome recorded locally."
+    },
+    "custom": {
+      "version": 1,
+      "goal": "Define a campaign around the user's actual product, assets and audience.",
+      "inputs": ["user objective", "publisher incentive", "target asset", "qualification criteria", "budget and outreach constraints"],
+      "qualify": ["State why a publisher and its reader benefit", "Define observable acceptance and rejection criteria", "Specify what evidence is required"],
+      "evidence": ["Campaign-specific source URLs", "Observed dates", "Known uncertainties"],
+      "reject": ["Invented contact details or publisher policies", "Unsupported authority or ranking guarantees"],
+      "agent_work": ["Write a product-specific goal and rubric in campaign notes", "Adapt available research, browser and email tools", "Track outcomes using the common CRM entities"],
+      "success": "Campaign-specific acceptance criteria are met and supported by verifiable evidence."
+    }
+  }
+}