agentlinkops 0.6.1 → 0.6.3

package/cli/lifecycle.js

@@ -0,0 +1,40 @@
+import {legacyCostPatch} from '../shared/lifecycle-money.js';
+import {readFile,stat} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {loadConfig,ConfigError} from './config.js';
+import {cloudConnection} from './connection.js';
+import {createClient} from './client.js';
+import * as C from '../shared/lifecycle-contract.js';
+export const LIFECYCLE_CLI_HELP=`agentlinkops lifecycle get WATCH_ID
+agentlinkops lifecycle update WATCH_ID --revision N --deal PATCH.json [--decimal-cost]
+agentlinkops lifecycle clear WATCH_ID --revision N
+agentlinkops lifecycle renew [--limit 100]
+agentlinkops lifecycle report [--from YYYY-MM-DD] [--to YYYY-MM-DD]
+Uses the connected project. Deal costs are integer currency minor units. Null clears a field; costMinor and currency must be set or cleared together. Clear removes deal metadata, not the watch. Renew retains due events without sending a message. --decimal-cost reads cost_amount as an exact decimal string and cost_currency using the supported currency scale. sync --lifecycle pulls a deal mirror without editing the ledger.`;
+const fail=message=>{throw new ConfigError(message);};
+const integer=(value,name)=>{if(typeof value!=='string'||!/^\d+$/.test(value)||!Number.isSafeInteger(Number(value)))fail(`${name} requires a nonnegative integer`);return Number(value);};
+export async function lifecycleMain(args,{cwd=process.cwd(),env=process.env,out=console.log,fetchImpl=globalThis.fetch}={}){
+ if(args.help){out(LIFECYCLE_CLI_HELP);return 0;}
+ const action=args._?.[1],allowed={get:[],update:['revision','deal','decimal-cost'],clear:['revision'],renew:['limit'],report:['from','to']}[action];
+ if(!allowed||args.tag?.length||Object.keys(args).some(key=>!['_','tag',...allowed].includes(key)))fail(LIFECYCLE_CLI_HELP);
+ const record=['get','update','clear'].includes(action);
+ if(args._.length!==(record?3:2)||record&&(typeof args._[2]!=='string'||!args._[2]))fail(LIFECYCLE_CLI_HELP);
+ const config=await loadConfig({cwd}),connection=cloudConnection(config,env);if(!connection.projectId)fail('Connect this repository to a project first');
+ const input={projectId:connection.projectId};let name,schema,output;
+ if(record)input.watchId=args._[2];
+ if(action==='get'){name='get_link_lifecycle';schema=C.lifecycleGetInput;output=C.lifecycleOutput;}
+ if(action==='update'||action==='clear'){
+  name='update_link_lifecycle';schema=C.lifecycleUpdateInput;output=C.lifecycleOutput;input.revision=integer(args.revision,'--revision');
+  if(action==='clear')input.deal=C.emptyDeal();else{
+   if(typeof args.deal!=='string')fail('--deal requires a JSON patch file');const path=resolve(cwd,args.deal),info=await stat(path);if(!info.isFile()||info.size>16384)fail('Deal patch must be a JSON file of at most 16 KiB');
+   try{input.deal=JSON.parse(await readFile(path,'utf8'));}catch{fail('Deal patch must contain valid JSON');}
+   if(args['decimal-cost']){try{input.deal=legacyCostPatch(input.deal);}catch(e){fail(e.message);}}
+   const patch=C.lifecyclePatch.safeParse(input.deal);if(!patch.success)fail('Invalid deal patch fields');
+   if(('costMinor' in input.deal)!==('currency' in input.deal))fail('Set or clear costMinor and currency together');
+  }
+ }
+ if(action==='renew'){name='record_lifecycle_renewals';schema=C.lifecycleRenewInput;output=C.lifecycleRenewOutput;if(args.limit!==undefined)input.limit=integer(args.limit,'--limit');}
+ if(action==='report'){name='get_lifecycle_report';schema=C.lifecycleReportInput;output=C.lifecycleReportOutput;for(const key of ['from','to'])if(args[key]!==undefined)input[key]=args[key];}
+ const parsed=schema.safeParse(input);if(!parsed.success)fail('Invalid lifecycle dates, fields or bounds');
+ const result=await createClient({...connection,fetchImpl}).callCommand(name,parsed.data),checked=output.safeParse(result);if(!checked.success)fail('Invalid lifecycle service response');out(JSON.stringify(checked.data,null,2));return 0;
+}

package/cli/main.js

@@ -1,4 +1,7 @@
+import {lifecycleMain} from './lifecycle.js';
+import {admissionMain} from './admission.js';
 import { commandsMain } from './commands.js';
+import { disavowMain } from './disavow.js';
 import { agentMain } from './agent-setup.js';
 import { setupPlanMain } from './setup-plan.js';
 import {parseArgs as parseArguments} from './args.js';
@@ -19,7 +22,7 @@ import { readImport, parseMap } from './import.js';
 import { freezeDataset, renderReport, datasetDigest } from './report.js';
 import { createClient, CloudError } from './client.js';
 import { cloudConnection, connectMain, keySetup } from './connection.js';
-import { syncPlan, pushExpectations, pullEvents, cloudObservationRows, watchIndex, pullTargetEvents } from './sync.js';
+import { syncPlan, pushExpectations, pullLifecycleMirrors, pullEvents, cloudObservationRows, watchIndex, pullTargetEvents } from './sync.js';
 import { SUPPLIER_NAMES } from './adapters/suppliers.js';
 import { fleetSummary, renderFleet } from './fleet.js';
 import { platformAggregate, classifyObservation, renderPlatforms, attachToCandidates, PLATFORM_CLASSES } from './platforms.js';
@@ -30,14 +33,17 @@ import { attachReceiptPerformance } from './receipt-performance.js';
 import { contextPaths, loadContextConfig, readGscRows } from '../src/context/gsc.js';
 import { readGa4Rows } from '../src/context/ga4.js';
 import { mixMain } from './mix.js';
+import { locateOccurrences } from '../src/locator.js';
+import { mirrorEvidenceReference, parseEvidenceReference, describeEvidenceReference } from '../src/evidence-reference.js';
 import { doctorMain } from './doctor.js';
 import { gscLinksMain } from './gsc-browser.js';
 import { skillMain, NUDGE } from './skill.js';
+import { indexMain, readIndexReceipts, locateIndexReceipt } from './index-observations.js';
 import { citationMain } from './citation.js';
 
 const USAGE = `agentlinkops — a backlink ledger that lives in your repository
 
-  agentlinkops skill [--url]            print the agent reference; read it in full once per session
+  agentlinkops skill [--url|--list [--json]|NAME]  read the agent reference or a named skill
                                             before the first AgentLinkOps call
   agentlinkops init                   create .agentlinkops/ here
   agentlinkops migrate                rename an existing .linktrail/ to .agentlinkops/ (receipt; never merges)
@@ -45,6 +51,12 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
                 [--mode local|hosted|external]  read-only setup plan; no account required
   agentlinkops add --source URL --target URL [--intent wanted|expected] [--scope …]
                 [--anchor TEXT] [--rel a,b] [--ref TEXT] [--tag t --tag t] [--note TEXT]
+  agentlinkops index pull --watch-id ID [--limit N] [--before ID]
+  agentlinkops lifecycle get|update|clear|renew|report
+  agentlinkops admission list|add|update|remove|evaluate|reevaluate|receipt --project ID
+  agentlinkops disavow list|history|propose|import|export|approve|reject|delete
+  agentlinkops index import FILE | export [--out FILE] | csv URLS.csv [--out FILE]
+  agentlinkops index check-csv URLS.csv --connection-id ID --request-id ID --out FILE
   agentlinkops import FILE --target DOMAIN [--from SUPPLIER] [--map source=COL,target=COL]
                 [--exact-url] [--no-subdomains] [--generated-at ISO] [--json]
   agentlinkops adopt CRM.sqlite [--scope exact|domain] [--write]
@@ -61,7 +73,7 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops citation run PANEL.json [--dir DIR] [--samples N] [--max-usd USD] [--json]
                                             one fixed-n AI-citation epoch; evidence under
                                             .agentlinkops/citations/; live engines need
-                                            PERPLEXITY_API_KEY, the mock engine costs nothing
+                                            engine-specific setup; the mock engine makes no paid calls
   agentlinkops receive --body FILE --headers FILE   signed notification; authenticated pull
   agentlinkops connect --workspace ID --project-id ID [--origin URL] [--selection FILE]
   agentlinkops tools [TOOLSET] [--json] [--refresh]   cloud commands by toolset (offline snapshot;
@@ -74,7 +86,9 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
                                             detected agent client (Claude Code, Codex, Cursor,
                                             Gemini CLI, Hermes); stores no credential
   agentlinkops agent status                 what is installed where
-  agentlinkops sync [--push-only] [--pull-only] [--dry-run] [--include-wanted]
+  agentlinkops agent remove [--scope project|user] [--apply] [--json]
+  agentlinkops agent recover [--scope project|user] [--apply] [--json]
+  agentlinkops sync [--push-only] [--pull-only] [--dry-run] [--include-wanted] [--lifecycle]
                                             AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY
   agentlinkops check [--filter TEXT] [--all] [--json] [--fail-on-unknown]
   agentlinkops doctor                       verify ledger, verifier, cloud reachability, token
@@ -86,7 +100,12 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops status [--json]
   agentlinkops diff [--json]
   agentlinkops report [--out FILE] [--title T] [--brand B] [--as-of ISO]
-                [--include-notes] [--include-retired] [--digest-only]
+                [--include-notes] [--include-retired] [--digest-only] [--json]
+                                            HTML by default; --json writes the same frozen
+                                            dataset as JSON (the machine receipt)
+  agentlinkops locate (--entry ID [--at ISO] | --ref REFERENCE)
+                                            resolve one observation to its occurrences and
+                                            evidence reference, from the local mirror only
   agentlinkops fmt
   agentlinkops compact [--apply]
 
@@ -112,7 +131,7 @@ function reportProblems(problems, what, out) {
   if (problems.length > 20) out(`  … and ${problems.length - 20} more`);
 }
 
-export async function main(argv = process.argv.slice(2), { cwd = process.cwd(), out = console.log, err = console.error } = {}) {
+export async function main(argv = process.argv.slice(2), { cwd = process.cwd(), out = console.log, err = console.error, env = process.env, fetchImpl = globalThis.fetch } = {}) {
   if (argv[0] === 'gsc-links') return await gscLinksMain(argv, { cwd, out });
   // Citation watches keep their own files under .agentlinkops/citations/ and never
   // touch the link ledger, so they dispatch before its requirement like context does.
@@ -126,8 +145,12 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
 
   let syncLock = null;
   try {
+    if (command === 'lifecycle') return await lifecycleMain(args,{cwd,env,fetchImpl,out});
+    if (command === 'admission') { const config=await loadConfig({cwd}); return await admissionMain(argv.slice(1),{client:createClient({...cloudConnection(config,env),fetchImpl}),out,err}); }
+    if (command === 'disavow') return await disavowMain(args,{cwd,env,fetchImpl,out});
+    if (command === 'index') return await indexMain(args,{cwd,env,fetchImpl,out});
     if (command === 'setup') return await setupPlanMain(argv, { cwd, out });
-    if (command === 'tools' || command === 'describe' || command === 'call') return await commandsMain(argv, { cwd, out, err });
+    if (command === 'tools' || command === 'describe' || command === 'call') return await commandsMain(argv, { cwd, out, err, env, fetchImpl });
     if (command === 'skill') return await skillMain(argv, { out });
     if (command === 'agent') return await agentMain(argv, { cwd, out, err });
     if (command === 'connect') {
@@ -369,8 +392,26 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
         title: args.title === true ? 'Backlink report' : (args.title ?? 'Backlink report'),
         includeNotes: args['include-notes'] === true,
         includeRetired: args['include-retired'] === true,
+        indexObservations: await readIndexReceipts(config.paths.indexObservations),
       });
       if (args['digest-only']) { out(datasetDigest(dataset)); return 0; }
+      // `--json` selects the machine receipt: the SAME frozen dataset, not a second serializer,
+      // so an agent's JSON and a client's HTML cannot disagree about what was observed.
+      if (args.json) {
+        const json = JSON.stringify(dataset, null, 2);
+        if (args.out && args.out !== true) {
+          await mkdir(dirname(String(args.out)), { recursive: true });
+          await writeFile(String(args.out), json, 'utf8');
+          out(`${dataset.totals.entries} link(s), digest ${datasetDigest(dataset)}`);
+          out(`wrote ${args.out}`);
+        } else { out(json); }
+        // On the JSON stdout path the notices go to stderr: a consumer piping the machine
+        // receipt must receive exactly one parseable document, nothing after it.
+        const note = args.out && args.out !== true ? out : err;
+        if (!asOf) note('NOT reproducible: no --as-of, so the prepared date is today and tomorrow differs.');
+        if (dataset.include_notes) note('Private notes are IN this document.');
+        return 0;
+      }
       const html = renderReport(dataset, { brand: args.brand === true ? null : (args.brand ?? null) });
       if (args.out && args.out !== true) {
         await mkdir(dirname(String(args.out)), { recursive: true });
@@ -385,6 +426,55 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       return 0;
     }
 
+    if (command === 'locate') {
+      // The resolution side of the evidence reference (DP-0004-T21): a reference printed in an
+      // export must resolve to the observation it names, from the repository alone, with no
+      // account and no network. Hosted references name the workspace's own rows and resolve
+      // through the API; sending a reader there from an offline command would be a silent
+      // dependency on live session state, so it is refused with the command that works.
+      const ref = args.ref === true ? null : (args.ref ?? null);
+      const entryId = args.entry === true ? null : (args.entry ?? null);
+      const at = args.at === true ? null : (args.at ?? null);
+      let row = null;
+      if (ref) {
+        const parsed = parseEvidenceReference(String(ref));
+        if (!parsed) { err(`not an AgentLinkOps evidence reference: ${ref}`); return 2; }
+        if (parsed.subject === 'index') {
+          if(parsed.storage==='hosted'){err(describeEvidenceReference(ref).resolves[0]);return 2;}
+          out(JSON.stringify(locateIndexReceipt(await readIndexReceipts(config.paths.indexObservations),parsed.receiptId),null,2));return 0;
+        }
+        if (parsed.storage === 'hosted') {
+          err('hosted references resolve through the workspace API, not the local mirror:');
+          err(`  agentlinkops call locate_link --set observationId=${parsed.observationId}`);
+          return 2;
+        }
+        row = observations.rows.find(candidate => candidate.id === parsed.entryId
+          && String(candidate.checked_at) === parsed.checkedAt
+          && (candidate.source === 'cloud' ? 'cloud' : 'local') === parsed.origin) ?? null;
+        if (!row) { err(`no observation in this mirror matches ${ref}`); return 2; }
+      } else if (entryId) {
+        if (at && !Number.isFinite(Date.parse(String(at)))) { err(`--at is not a valid timestamp: ${at}`); return 2; }
+        const candidates = observations.rows.filter(candidate => candidate.id === String(entryId));
+        // `--at` is exact or it is an error: silently falling back to the latest observation
+        // would show a reader a different check while appearing to resolve the one they named.
+        row = at ? candidates.find(candidate => String(candidate.checked_at) === String(at)) ?? null
+          // Latest by checked_at, matching latestByEntry's rule, so `locate` and `report` never
+          // disagree about which observation a row's receipt describes.
+          : candidates.reduce((best, candidate) => (!best || String(candidate.checked_at) >= String(best.checked_at) ? candidate : best), null);
+        if (!row) { err(at ? `no observation of ${entryId} at ${at}` : `no observation of ${entryId} in this mirror`); return 2; }
+      } else { err('agentlinkops locate (--entry ID [--at ISO] | --ref REFERENCE)'); return 2; }
+      const entry = ledger.entries.find(candidate => candidate.id === row.id) ?? null;
+      const reference = mirrorEvidenceReference({ entryId: row.id, checkedAt: row.checked_at, origin: row.source === 'cloud' ? 'cloud' : 'local' });
+      out(JSON.stringify({
+        // The T05 locate view: positions, live-page handoff, evidence metadata, notes.
+        ...locateOccurrences({ ...row, id: row.cloud_observation_id ?? null }),
+        ledger_entry: entry ? { id: entry.id, source: entry.source, target: entry.target, scope: entry.scope } : null,
+        evidence_reference: reference,
+        reference_resolution: describeEvidenceReference(reference),
+      }, null, 2));
+      return 0;
+    }
+
     if (command === 'fmt') {
       reportProblems(ledger.problems, 'ledger line(s)', out);
       if (ledger.problems.length) return 2;
@@ -438,6 +528,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       }
       const state = await readState(config.paths.state);
       if (args['pull-only'] && args['push-only']) throw new ConfigError('Choose --pull-only or --push-only.');
+      if(args.lifecycle&&args['push-only'])throw new ConfigError('--lifecycle requires a pull; omit --push-only.');
       const selection = { includeWanted: args['include-wanted'] === true, ledgerIds: config.cloud?.ledgerIds ?? null };
       if (args['dry-run']) { out(JSON.stringify({ network: false, rows: args['pull-only'] ? [] : syncPlan(ledger.entries, state, selection) }, null, 2)); return 0; }
       const connection = cloudConnection(config);
@@ -467,6 +558,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
         // expiry on one cannot move the other.
         const targets = await pullTargetEvents(client, next);
         const index = await watchIndex(client, next);
+        if(args.lifecycle)next.lifecycle=await pullLifecycleMirrors(client,next,{projectId:connection.projectId,index,ledgerIds:selection.ledgerIds??ledger.entries.map(entry=>entry.id)});
         const { fresh, duplicates } = await persistPulledHistory(config, pulled.events, targets.events, index);
         next.cursors = { ...(next.cursors ?? {}), events: pulled.cursor, target_events: targets.cursor };
         next.gaps = [...(next.gaps ?? []), ...pulled.gaps, ...targets.gaps];

package/cli/report.js

@@ -12,10 +12,19 @@
 //
 // Self-contained: no external stylesheet, font, script or image. That makes it openable offline
 // forever, printable to PDF from any browser, and incapable of telling anyone it was opened.
+//
+// v2 makes the document a RECEIPT (DP-0004-T20): every row carries the observation behind it —
+// when it was observed, the content hash of what was captured, who checked, and a stable
+// evidence reference that resolves to the observation itself. One dataset feeds both exports:
+// this HTML view for a human client, and `report --json` for an agent, so the two can never
+// disagree about what was observed.
+import {indexRowsForUrl} from './index-observations.js';
+import {reconcileIndexObservations} from '../src/index-observation.js';
 import { createHash } from 'node:crypto';
 import { latestByEntry } from './mirror.js';
+import { mirrorEvidenceReference } from '../src/evidence-reference.js';
 
-export const REPORT_VERSION = 1;
+export const REPORT_VERSION = 2;
 
 /** HTML-escape. Every value below is publisher or customer content and none of it is trusted. */
 export const escape = value => String(value ?? '')
@@ -33,12 +42,14 @@ const STATE_LABEL = Object.freeze({
  * Selection happens here and nowhere else, so a caller can hold this object, assert it, and know
  * the rendered document is a pure function of it.
  */
-export function freezeDataset(entries, observations, { asOf, title = 'Backlink report', includeNotes = false, includeRetired = false } = {}) {
+export function freezeDataset(entries, observations, { asOf, title = 'Backlink report', includeNotes = false, includeRetired = false, indexObservations = [] } = {}) {
   const latest = latestByEntry(observations);
   const rows = entries
     .filter(entry => includeRetired || entry.intent !== 'retired')
     .map(entry => {
       const row = latest.get(entry.id) ?? null;
+      const indexRows=indexRowsForUrl(indexObservations,entry.source);
+      const origin = row?.source === 'cloud' ? 'cloud' : (row?.source ?? null);
       return {
         id: entry.id, intent: entry.intent, source: entry.source, target: entry.target, scope: entry.scope,
         expected_anchor: entry.expect?.anchor ?? null,
@@ -49,8 +60,34 @@ export function freezeDataset(entries, observations, { asOf, title = 'Backlink r
         checked_by: row?.source ?? null,
         anchor: row?.result?.occurrences?.[0]?.anchor ?? null,
         rel: row?.result?.occurrences?.[0]?.rel ?? [],
+        // The receipt block: what was observed, when, by which check, and how to point at the
+        // observation itself. Null on a never-checked row — an absent receipt is a fact here,
+        // not a missing field.
+        evidence: row ? {
+          observed_at: row.checked_at ?? null,
+          // The content hash of the captured document, present whenever the check recorded one.
+          // This is the field anchoring (DP-0042-T07) will make independently verifiable; it is
+          // in the export now so a document made today can be verified the day anchoring lands.
+          content_hash: row.result?.evidence?.sha256 ?? null,
+          // The hosted snapshot key, when this observation was synced from the workspace.
+          // Local checks never store publisher bytes anywhere, so null there means exactly that.
+          snapshot_key: row.evidence_key ?? null,
+          // Who ran the check: a local CLI run or the hosted scheduler. Two origins at the same
+          // instant are two observations, and a receipt that blurred them would blur method.
+          origin,
+          checker_version: row.checker_version ?? row.result?.evidence?.checkerVersion ?? null,
+          // Named, not implied: a static observation is not a claim about what a reader sees.
+          method: row.result?.evidence?.rendered === true || row.result?.evidence?.method === 'browser_html'
+            ? 'rendered' : row.result?.evidence?.rendered === false || row.result?.evidence?.method === 'http_html'
+              ? 'static_html' : null,
+          // The hosted observation id when the mirror row carries one (cloud-synced rows).
+          hosted_observation_id: row.cloud_observation_id ?? null,
+          // The stable reference that resolves to this observation from the repository mirror.
+          locator: mirrorEvidenceReference({ entryId: entry.id, checkedAt: row.checked_at ?? undefined, origin: origin ?? undefined }),
+        } : null,
         // Opt-in, because a note can hold commercial context — what a placement cost, what a
         // publisher said — and a report is the document most likely to be forwarded.
+        ...(indexRows.length?{index_observations:indexRows,index_reconciliation:reconcileIndexObservations(indexRows)}:{}),
         note: includeNotes ? (entry.note ?? null) : null,
         ref: includeNotes ? (entry.ref ?? null) : null,
       };
@@ -94,6 +131,8 @@ td.url{word-break:break-all;max-width:340px}
 .present{background:#eef7ee;border-color:#b6d7b6}
 .absent{background:#fdeeee;border-color:#e2b6b6}
 .unknown,.unchecked,.source_unavailable{background:#f6f6f6}
+code.hash{font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+.ref{font:11px/1.4 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;word-break:break-all}
 .note{color:#555;font-size:12px}
 footer{margin-top:28px;padding-top:12px;border-top:1px solid #eee;color:#555;font-size:12px}
 .caveat{margin:18px 0;padding:10px 14px;border-left:3px solid #ddd;color:#444;font-size:13px}
@@ -110,14 +149,36 @@ export function renderReport(dataset, { brand = null } = {}) {
   const digest = createHash('sha256').update(JSON.stringify(dataset)).digest('hex');
   const card = (label, value) => `<div class="card"><b>${escape(value)}</b><span>${escape(label)}</span></div>`;
   const coverage = dataset.coverage;
+  // The receipt column. "hash not recorded" is stated rather than papered over: a local check
+  // that never completed a fetch has no hash, and a cloud-synced row may carry its snapshot key
+  // without a hash in an older event. Neither is a claim about the link.
+  const evidenceCell = row => {
+    if (!row.evidence) return '<span class="note">no observation</span>';
+    const hash = row.evidence.content_hash ? `<code class="hash">${escape(row.evidence.content_hash.slice(0, 12))}</code>` : '<span class="note">hash not recorded</span>';
+    const origin = row.evidence.origin === 'cloud' ? 'hosted check' : row.evidence.origin === 'local' ? 'local check' : 'unknown origin';
+    const checker = row.evidence.checker_version ? ` &middot; checker ${escape(row.evidence.checker_version)}` : '';
+    const method=row.evidence.method==='rendered'?'browser-rendered HTML':row.evidence.method==='static_html'?'static HTML':'method not recorded';
+    return `${hash}<div class="note">${escape(origin)}${checker}</div><div class="note">${method}</div>`;
+  };
+  const hasIndex=dataset.rows.some(row=>row.index_observations?.length);
   const rows = dataset.rows.map(row => `<tr>
       <td class="url"><a href="${escape(row.source)}">${escape(row.source)}</a></td>
       <td class="url">${escape(row.target)}</td>
       <td><span class="state ${escape(row.state)}">${escape(STATE_LABEL[row.state] ?? row.state)}</span></td>
       <td>${row.anchor ? escape(row.anchor) : '<span class="note">&mdash;</span>'}${(row.rel ?? []).length ? `<div class="note">rel: ${escape(row.rel.join(' '))}</div>` : ''}</td>
       <td>${row.checked_at ? escape(row.checked_at.slice(0, 10)) : '<span class="note">never</span>'}</td>
+      <td>${evidenceCell(row)}</td>
+      ${hasIndex?`<td>${(row.index_observations??[]).map(o=>`${escape(o.tier)} · ${escape(o.reason)}<div>${escape(o.checked_at)} · ${escape(o.backend)}</div><div class="ref">${escape(o.locator)}</div>`).join('<hr>')||'Not checked'}</td>`:''}
       ${dataset.include_notes ? `<td class="note">${escape(row.ref ?? '')}${row.note ? `<div>${escape(row.note)}</div>` : ''}</td>` : ''}
     </tr>`).join('\n');
+  // Every row's full reference, printable: the table above stays readable while the document a
+  // client forwards still carries the complete handle for each observation behind it.
+  const receiptRows = dataset.rows.filter(row => row.evidence?.locator).map(row => `<tr>
+      <td>${escape(row.id)}</td>
+      <td>${escape(row.evidence.observed_at ?? 'unknown')}</td>
+      <td>${row.evidence.content_hash ? `<code class="hash">${escape(row.evidence.content_hash)}</code>` : '<span class="note">not recorded</span>'}</td>
+      <td class="ref">${escape(row.evidence.locator)}</td>
+    </tr>`).join('\n');
 
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
@@ -137,17 +198,29 @@ last observed, between ${escape(coverage.observed_from ?? 'n/a')} and ${escape(c
 The date at the top is when this document was prepared and does not make any observation newer
 than it is. ${coverage.never_checked ? `${coverage.never_checked} of ${dataset.totals.entries} links have never been checked and are listed as such.` : ''}</p>
 <p class="caveat"><strong>What a result means.</strong> &ldquo;Present&rdquo; means the link was in
-the HTML the publisher served. &ldquo;Could not check&rdquo; is not the same as
+the observed HTML. &ldquo;Could not check&rdquo; is not the same as
 &ldquo;not found&rdquo;: it means the page could not be read, and no conclusion was drawn.
-JavaScript execution and visual visibility were not checked.</p>
+Each receipt identifies the check method when it was recorded. A snapshot alone does not prove the link was visible on screen.</p>
 <table><thead><tr>
-<th>Source page</th><th>Target</th><th>Result</th><th>Anchor</th><th>Observed</th>${dataset.include_notes ? '<th>Notes</th>' : ''}
+<th>Source page</th><th>Target</th><th>Result</th><th>Anchor</th><th>Observed</th><th>Evidence</th>${hasIndex?'<th>Index evidence</th>':''}${dataset.include_notes ? '<th>Notes</th>' : ''}
 </tr></thead><tbody>
 ${rows}
 </tbody></table>
+${receiptRows ? `<h2>Evidence references</h2>
+<p class="caveat"><strong>What a reference is.</strong> Each row above was concluded from one
+saved observation. Its reference names that observation — which ledger entry, when it was
+checked, and whether the check ran locally or on the hosted service — and resolves to the
+recorded result from the repository that produced this document, with no account required. The
+content hash, where recorded, is the hash of the document that was captured at that moment;
+two captures of a changed page produce different hashes, which is what makes "the same
+evidence" checkable rather than claimed.</p>
+<table><thead><tr><th>Link</th><th>Observed at</th><th>Content hash</th><th>Reference</th></tr></thead><tbody>
+${receiptRows}
+</tbody></table>` : ''}
 <footer>
 AgentLinkOps report v${dataset.v}. Dataset digest <code>${escape(digest)}</code> &mdash; the same
-ledger and observations always produce this digest.
+ledger and observations always produce this digest. The same dataset exports as JSON
+(<code>agentlinkops report --json</code>) and carries the same digest.
 ${dataset.include_notes ? 'Private notes are included in this document.' : 'Private notes and references are excluded.'}
 </footer>
 </body></html>

package/cli/skill.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -11,7 +11,7 @@ import { fileURLToPath } from 'node:url';
 // steps); a machine reader of `tools --json` or of stderr error objects never sees it.
 export const REFERENCE_URL = 'https://agentlinkops.com/SKILL.md';
 export const NUDGE = `Run \`agentlinkops skill\` and read it in full before the first AgentLinkOps call in a session (also at ${REFERENCE_URL}).`;
-const USAGE = 'skill [--url]';
+const USAGE = 'skill [--url | --list [--json] | NAME]';
 
 export async function readReference({ from = fileURLToPath(import.meta.url), packDir = null } = {}) {
   // The pack beside the CLI (the published package), then this repository's generated copy,
@@ -29,10 +29,47 @@ export async function readReference({ from = fileURLToPath(import.meta.url), pac
   throw new Error(`No agent reference found beside this CLI; read ${REFERENCE_URL}.`);
 }
 
+export async function readSkillSet({ from = fileURLToPath(import.meta.url), packDir = null } = {}) {
+  const base = dirname(from);
+  const packs = packDir ? [packDir] : [join(base, '..', 'skills'), join(base, '..', 'toolkit', 'plugin', 'agentlinkops', 'skills'), join(base, '..', 'dist', 'plugin', 'agentlinkops', 'skills')];
+  for (const pack of packs) {
+    const entries = await readdir(pack, { withFileTypes: true }).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+    const skills = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !/^agentlinkops-[a-z0-9-]+$/.test(entry.name)) continue;
+      const text = await readFile(join(pack, entry.name, 'SKILL.md'), 'utf8').catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+      if (!text) continue;
+      const frontmatter = text.match(/^---\n([\s\S]*?)\n---/u)?.[1] ?? '';
+      const description = frontmatter.match(/^description:\s*(.+)$/mu)?.[1] ?? '';
+      skills.push({ name: entry.name, description, text, source: join(pack, entry.name, 'SKILL.md') });
+    }
+    if (!skills.length) continue;
+    let version = 'unversioned';
+    for (const file of [join(pack, '..', '.claude-plugin', 'plugin.json'), join(pack, '..', 'package.json')]) {
+      const manifest = await readFile(file, 'utf8').catch(() => null);
+      if (manifest) { version = JSON.parse(manifest).version ?? version; break; }
+    }
+    return { version, skills: skills.sort((a, b) => a.name.localeCompare(b.name)) };
+  }
+  throw new Error('No shipped skill set found beside this CLI');
+}
+
 export async function skillMain(argv, { out = console.log, from, packDir = null } = {}) {
   const rest = argv.slice(1);
-  if (rest.some(a => !['--url'].includes(a))) { out(USAGE); return 2; }
-  if (rest.includes('--url')) { out(REFERENCE_URL); return 0; }
+  if (rest.length === 1 && rest[0] === '--url') { out(REFERENCE_URL); return 0; }
+  if (rest[0] === '--list' && rest.every(flag => ['--list', '--json'].includes(flag))) {
+    const { version, skills } = await readSkillSet({ from, packDir });
+    const listing = { version, skills: skills.map(({ name, description }) => ({ name, description })) };
+    out(rest.includes('--json') ? JSON.stringify(listing) : `AgentLinkOps skills ${version}\n` + listing.skills.map(skill => `${skill.name} — ${skill.description}`).join('\n'));
+    return 0;
+  }
+  if (rest.length === 1 && /^agentlinkops-[a-z0-9-]+$/.test(rest[0])) {
+    const { skills } = await readSkillSet({ from, packDir });
+    const selected = skills.find(skill => skill.name === rest[0]);
+    if (!selected) { out('Unknown shipped skill; run agentlinkops skill --list'); return 2; }
+    out(`<!-- Installed skill source: ${selected.source} -->\n${selected.text.trimEnd()}`); return 0;
+  }
+  if (rest.length) { out(USAGE); return 2; }
   const { text } = await readReference({ from, packDir });
   out(text.replace(/^<!--[^\n]*-->\n/u, '').trimEnd());
   return 0;

package/cli/sync.js

@@ -1,3 +1,4 @@
+import {lifecycleOutput} from '../shared/lifecycle-contract.js';
 import {observationFromSnapshot,eventSnapshot} from '../shared/observation-event.js';
 // `agentlinkops sync`: expectations up, events and evidence references down.
 //
@@ -151,7 +152,11 @@ export function cloudObservationRows(events, watchToLedger) {
     if (!ledgerId) continue;
     const observation = event.data?.after;
     if (!observation?.checked_at) continue;
-    rows.push({...observationRow(ledgerId, observationFromSnapshot(observation), { source: 'cloud', evidenceKey: event.data?.evidence_key ?? null }), projection_version: 1});
+    rows.push({...observationRow(ledgerId, observationFromSnapshot(observation), { source: 'cloud', evidenceKey: event.data?.evidence_key ?? null }),
+      // The hosted observation's own id, carried so a receipt export can name the workspace row
+      // (agentlinkops:evidence/1/link/hosted/<id>) alongside the mirror reference that resolves
+      // offline. Absent on snapshot-derived rows, which reconstruct state without observation ids.
+      cloud_observation_id: event.data?.observation_id ?? null, projection_version: 1});
   }
   return rows;
 }
@@ -177,3 +182,20 @@ export async function watchIndex(client, state) {
   }
   throw new CloudError('WATCH_INDEX_LIMIT', 502);
 }
+
+
+// Optional read-only deal mirror. One failure leaves the previous mirror untouched.
+// The caller saves it only after every selected watch has been read and scoped.
+export async function pullLifecycleMirrors(client,state,{projectId,index=null,ledgerIds=null,now=()=>new Date().toISOString()}={}){
+ const candidates=index?[...index].map(([watchId,ledgerId])=>[ledgerId,watchId]):Object.entries(state.watches??{});
+ const selected=ledgerIds===null?null:new Set(ledgerIds),mapping=candidates.filter(([id])=>!selected||selected.has(id));
+ if(new Set(mapping.map(([id])=>id)).size!==mapping.length)throw new CloudError('LIFECYCLE_MAPPING_CONFLICT',0);
+ if(mapping.length>1000)throw new CloudError('LIFECYCLE_MIRROR_LIMIT',0);
+ const rows={};
+ for(const [ledgerId,watchId] of mapping){
+  const value=lifecycleOutput.parse(await client.callCommand('get_link_lifecycle',{projectId,watchId}));
+  if(value.projectId!==projectId||value.watchId!==watchId)throw new CloudError('LIFECYCLE_MIRROR_SCOPE',0);
+  rows[ledgerId]={...value,observedAt:now()};
+ }
+ return {projectId,rows};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "A backlink and AI citation ledger that lives in your repository: local link and citation checks with dated evidence, supplier-export imports and optional sync to the hosted AgentLinkOps service.",
   "author": "AgentLinkOps (https://agentlinkops.com)",
   "license": "Apache-2.0",
@@ -59,6 +59,7 @@
     "@modelcontextprotocol/server": "2.0.0",
     "parse5": "8.0.1",
     "turndown": "^7.2.4",
+    "undici": "7.29.0",
     "zod": "4.6.0"
   },
   "devDependencies": {
@@ -67,4 +68,4 @@
   "optionalDependencies": {
     "playwright-core": "^1.63.0"
   }
-}
+}

package/references/citation-panels.md

@@ -0,0 +1,26 @@
+# Citation panels
+
+A panel records the questions, target sites, engines and sample budget for a citation check. Start with questions your audience has actually asked. Keep each question's source and collection date in your own research notes. Search Console queries, support conversations and public discussion threads can help when you already have access; the panel builder does not fetch or validate them.
+
+Create an editable draft without calling a provider:
+
+```sh
+agentlinkops citation panel --domain example.com --brand Example --topic "backlink monitoring" --out panel.json
+```
+
+This command defaults to the mock engine. Its suggested questions are writing prompts, not measured search demand. Replace them with the questions you chose. Repeat `--prompt "Your question"` to supply your own questions directly. The command refuses to overwrite an existing output file.
+
+Use `--competitors competitors.json` to add domains to check beside your own. The file is an array of objects with `domain`, `brand` and optional `aliases` fields. Each target gets separate results for each question. A target missing from one answer is only missing from that sample; it does not establish absence from the engine.
+
+Choose a live engine explicitly after checking access and budget. For an existing browser setup, use `--engine chatgpt:web-own-browser` or `--engine grok:web-own-browser`. `--engine google-aio` requires your configured supplier access. This workflow does not create accounts or buy services.
+
+Set `--locale en-GB --country GB` for a British locale draft. The mock engine supports locale fixtures. The Google AIO supplier path supports US and GB location requests; other engine paths refuse non-default locale requests in this version. Legacy default browser observations do not prove US proxy egress. Reports disclose the requested context and its basis; they do not treat it as verified user geography.
+
+After reviewing the draft, run the [local CLI workflow](cli.md) and inspect the retained evidence:
+
+```sh
+agentlinkops citation run panel.json --max-usd 1
+agentlinkops citation report panel.json --last 2 --out report.html
+```
+
+Keep brand mentions separate from links. Retained answer text can mention a brand and cite it in the same observation. Unknown or failed answers remain unknown. Reports keep engine, question, target and non-default locale identities separate; they do not produce an engine-wide share-of-voice score.

package/references/discovery-handoff.md

@@ -0,0 +1,32 @@
+# From research to a checked shortlist
+
+Keep research notes beside the user's project. The graph release, source retrieval date and qualification explain why a page is on the shortlist. They do not establish a live backlink.
+
+Use `agentlinkops skill --list` to see the installed set and `agentlinkops skill agentlinkops-discovery` to read the research workflow. `agentlinkops skill` still prints the connection and evidence reference.
+
+Create a CSV with exact source and target pages:
+
+```csv
+source_url,target_url
+https://publisher.example.org/resources,https://example.com/guide
+```
+
+Preview normalization before writing:
+
+```sh
+agentlinkops import shortlist.csv --target example.com --from csv --map source=source_url,target=target_url
+```
+
+The preview is not a live check or a watch. Inspect accepted and rejected rows. For a selected opportunity that has not been earned, initialize a local ledger when needed and add it as wanted:
+
+```sh
+agentlinkops init
+agentlinkops add --source https://publisher.example.org/resources --target https://example.com/guide --intent wanted --note "Research candidate; link not yet earned"
+agentlinkops check --all --json
+```
+
+The local check includes wanted entries; `--all` rechecks the selected rows even if their cadence is not yet due. Keep observed absence separate from unknown access failures. Once the user has an earned placement, record the exact source/target pair as expected and retain the observation date and evidence.
+
+For an already connected workspace, `agentlinkops tools monitoring` and `agentlinkops describe monitor_link` expose the current hosted contract. Inspect project IDs and usage first. Enroll selected source/target pairs only when recurring monitoring is within the user's request; record the returned watch IDs. A successful import or local check alone does not create a recurring hosted job.
+
+The [campaign skill](../skills/agentlinkops-campaigns/SKILL.md) handles subsequent campaign judgment. The [CRM reference](cli.md) covers optional records when the user needs contacts and activities beside the ledger. Outreach stays in the user's chosen tool and requires their instruction.