agentlinkops 0.5.0 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Connect an agent to AgentLinkOps and run backlink work with it: the connect skill (views, the three discovery verbs, evidence rules), local ledger and campaign skills, a portable CRM, the source-cited content pipeline, user-managed disavow lists, HTML reports and monitoring-event sync.",
   "author": {
     "name": "AgentLinkOps"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Connect an agent to AgentLinkOps and run backlink work with it: the connect skill (views, the three discovery verbs, evidence rules), local ledger and campaign skills, a portable CRM, the source-cited content pipeline, user-managed disavow lists, HTML reports and monitoring-event sync.",
   "author": {
     "name": "AgentLinkOps"

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agentlinkops": {
+      "type": "http",
+      "url": "https://app.agentlinkops.com/mcp"
+    }
+  }
+}

package/CHANGELOG.md

@@ -3,7 +3,21 @@
 All notable changes to the `agentlinkops` package are recorded here. The version follows the
 plugin manifests in `.claude-plugin/` and `.codex-plugin/`.
 
-## 0.5.0 (unreleased; DP-0036 agent surface)
+## 0.5.1 (2026-09-17)
+
+- The plugin's `.mcp.json` ships in the tarball. 0.5.0 left it out, so a marketplace install
+  got the skills but no MCP server entry; the package build now carries and requires it.
+- Package identity: `author` is AgentLinkOps (https://agentlinkops.com); `repository` and
+  `bugs` point at `sunlover7/agentlinkops-cli`. No personal identity in the registry metadata.
+- `agentlinkops citation run PANEL.json --engine chatgpt:web-own-browser`: measures the
+  consumer UI through the customer's own Camoufox browser instead of an API, with a screenshot
+  of every answer in the evidence. `--engine NAME[:PROVIDER]` overrides the panel's engine list.
+  `playwright-core` is an optional dependency; `doctor` reports the browser stack as a skip,
+  never a failure, when it is absent (API and mock engines need none of it).
+- Repository: CI on every push and a tag-driven release workflow that publishes through npm
+  trusted publishing with provenance.
+
+## 0.5.0 (2026-09-16; DP-0036 agent surface)
 
 - `agentlinkops tools [TOOLSET]`, `agentlinkops describe NAME` and `agentlinkops call NAME`:
   the three discovery verbs, answered offline from the bundled catalog snapshot (`--refresh`

package/README.md

@@ -37,7 +37,8 @@ Four steps, the same ones the docs and the landing page show. Node.js 22.13 or l
 The skill is a short door: the first time your agent uses AgentLinkOps in a session it reads
 the full agent reference, which `agentlinkops skill` prints and
 https://agentlinkops.com/SKILL.md serves. Hosted monitoring is an invitation-only pilot; the
-local commands below need no account.
+local commands below need no account. The package is `agentlinkops` on npm, published by the
+`agentlinkops` account; the source is https://github.com/sunlover7/agentlinkops-cli.
 
 ## Install the CLI on its own
 

package/cli/citation.js

@@ -8,7 +8,7 @@
 // Exit codes follow the link commands: 0 nothing actionable (including
 // insufficient_data — an unknown never fails), 1 a cell classified declined with
 // complete evidence, 2 usage, configuration or budget-abort errors.
-import { resolve } from 'node:path';
+import { resolve, join } from 'node:path';
 
 import { parseArgs } from './args.js';
 import { loadPanel, runEpoch } from '../src/citations/runner.js';
@@ -21,6 +21,21 @@ const USAGE = `agentlinkops citation — AI citation watches in this repository
   agentlinkops citation run PANEL.json [--dir DIR] [--samples N] [--max-usd USD] [--json]
                                             run one fixed-n epoch over a panel; evidence and
                                             tallies land under .agentlinkops/citations/
+  agentlinkops citation run PANEL.json --engine chatgpt:web-own-browser
+                                            measure the consumer UI through Camoufox
+                                            (dedicated account, personal cadence; evidence
+                                            includes a screenshot of every answer)
+  agentlinkops citation report PANEL.json [--out FILE] [--dir DIR]
+                                            render the latest epoch as a self-contained
+                                            HTML report: trends, screenshots inline,
+                                            Wilson intervals, honest classifications
+  agentlinkops citation watch PANEL.json --cadence weekly|daily|hourly|monthly
+                                            register a cron entry that runs the epoch
+                                            and generates the report on schedule
+  agentlinkops citation watch --list         list registered citation watches
+  agentlinkops citation watch --remove NAME  remove a registered watch
+  agentlinkops citation alert PANEL.json     check the latest epoch for declines;
+                                            logs an alert line if any cell declined
   agentlinkops citation help                 this help
 
 Panel (JSON): targets (domain or url, brand, aliases), prompts, engines
@@ -37,6 +52,81 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
   const args = parseArgs(argv);
   const command = args._[0] ?? 'help';
   if (command === 'help' || args.help) { out(USAGE); return 0; }
+  if (command === 'alert') {
+    const panelPath = args._[1];
+    if (!panelPath) { err('citation alert needs a panel file'); return 2; }
+    const { readFile } = await import('node:fs/promises');
+    const dir = resolve(cwd, args.dir ?? '.agentlinkops');
+    let latestEpochId = null;
+    try {
+      const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
+      const rows = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+      if (rows.length > 0) latestEpochId = rows[rows.length - 1].epoch_id;
+    } catch { /* no epochs */ }
+    if (!latestEpochId) { out('no epochs to check'); return 0; }
+    const { shouldAlert } = await import('../src/citations/alert.js');
+    const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
+    const cells = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l)).filter((r) => r.epoch_id === latestEpochId);
+    if (shouldAlert(cells)) {
+      const declined = cells.filter((c) => c.classification === 'declined');
+      err(`ALERT: ${declined.length} cell${declined.length === 1 ? '' : 's'} declined:`);
+      for (const c of declined) err(`  ${c.cell_id}: rate ${c.rate.toFixed(2)} (was ${c.baseline?.rate?.toFixed(2) ?? 'n/a'})`);
+      return 1; // exit 1 = actionable, same convention as link checks
+    }
+    out('no declines detected');
+    return 0;
+  }
+  if (command === 'watch') {
+    const { registerWatch, listWatches, removeWatch } = await import('../src/citations/watch.js');
+    if (args.list) {
+      const watches = await listWatches();
+      if (watches.length === 0) { out('no citation watches registered'); return 0; }
+      for (const w of watches) out(`${w.panel}  ${w.cron}`);
+      return 0;
+    }
+    if (args.remove) {
+      const result = await removeWatch(args.remove);
+      out(`removed watch: ${result.removed}`);
+      return 0;
+    }
+    const panelPath = args._[1];
+    if (!panelPath) { err('citation watch needs a panel file (or --list / --remove)'); return 2; }
+    const cadence = args.cadence ?? 'weekly';
+    try {
+      const result = await registerWatch({ panelPath, cadence });
+      out(`citation watch registered: ${result.panelPath}`);
+      out(`cadence: ${result.cadence} (${result.next})`);
+      out(`cron: ${result.cronSpec}`);
+      return 0;
+    } catch (cause) {
+      err(cause.message);
+      return 2;
+    }
+  }
+  if (command === 'report') {
+    const panelPath = args._[1];
+    if (!panelPath) { err('citation report needs a panel file'); return 2; }
+    const dir = resolve(cwd, args.dir ?? '.agentlinkops');
+    const { generateReport } = await import('../src/citations/report.js');
+    const { readFile, writeFile: wf } = await import('node:fs/promises');
+    // Find the latest epoch for this panel by reading the epochs file
+    let latestEpochId = null;
+    try {
+      const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
+      const rows = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+      if (rows.length > 0) latestEpochId = rows[rows.length - 1].epoch_id;
+    } catch { /* no epochs yet */ }
+    if (!latestEpochId) { err('no epochs found — run an epoch first'); return 2; }
+    const panel = JSON.parse(await readFile(resolve(cwd, panelPath), 'utf8'));
+    const html = await generateReport({ dir, epochId: latestEpochId, panel });
+    const outPath = args.out ? resolve(cwd, args.out) : join(dir, 'citations', `report-${latestEpochId.slice(0, 15)}.html`);
+    const { dirname, join: j } = await import('node:path');
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(dirname(outPath), { recursive: true });
+    await wf(outPath, html, 'utf8');
+    out(`report written: ${outPath} (${Math.round(html.length / 1024)} KB, self-contained)`);
+    return 0;
+  }
   if (command !== 'run') { err(`unknown citation command: ${command}`); err(USAGE); return 2; }
 
   const panelPath = args._[1];
@@ -53,6 +143,15 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
   const dir = resolve(cwd, args.dir ?? '.agentlinkops');
   if (args.samples) panel.samples = Number(args.samples);
   if (args['max-usd']) panel.maxUsd = Number(args['max-usd']);
+  // --engine NAME[:PROVIDER] overrides the panel's engine list. The provider
+  // suffix picks the surface: chatgpt:web-own-browser measures the consumer
+  // UI through Camoufox; chatgpt:api would measure the API. Never averaged.
+  if (args.engine) {
+    const [engineName, providerTag] = String(args.engine).split(':');
+    const via = providerTag === 'web-own-browser' ? 'browser' : 'api';
+    panel.engines = [{ engine: engineName, via }];
+    err(`engine override: ${engineIdentity(panel.engines[0])}`);
+  }
   // Overrides are stated, never silent: a number the panel did not ask for is a
   // configuration decision the operator should see in the receipt.
   if (args.samples || args['max-usd']) {
@@ -63,8 +162,31 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
   for (const spec of panel.engines) {
     const identity = engineIdentity(spec);
     if (engines.has(identity)) continue;
+    if (spec.via === 'browser') {
+      const { createBrowserEngine } = await import('../src/citations/browser/engine.js');
+      engines.set(identity, createBrowserEngine({ engineName: spec.engine, env }));
+      continue;
+    }
     if (spec.engine === 'mock') {
       engines.set(identity, createMockEngine({ fixtures: panel.mockFixtures ?? {} }));
+    } else if (spec.engine === 'google-aio') {
+      // Fixture-first: runs against the recorded response with no credentials.
+      // Activates live the moment DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD exist.
+      const { createGoogleAioEngine } = await import('../src/citations/adapter.js');
+      const creds = env.DATAFORSEO_LOGIN && env.DATAFORSEO_PASSWORD
+        ? { login: env.DATAFORSEO_LOGIN, password: env.DATAFORSEO_PASSWORD }
+        : null;
+      engines.set(identity, createGoogleAioEngine({ credentials: creds }));
+      if (!creds) err(`google-aio: fixture mode (set DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD for live)`);
+    } else if (spec.engine === 'duck') {
+      // Self-hosted Duck2api on the VPS: the whole Claude family plus GPT-5.6
+      // anonymously through duck.ai. Localhost endpoint, no key.
+      const { createOpenAiCompatibleEngine } = await import('../src/citations/adapter.js');
+      engines.set(identity, createOpenAiCompatibleEngine({
+        baseUrl: env.DUCK2API_URL ?? 'http://127.0.0.1:8090/v1',
+        model: spec.model ?? 'claude-haiku-4-5',
+        providerLabel: 'duck-anon',
+      }));
     } else if (spec.engine === 'perplexity') {
       // Presence only, never the value — the same rule doctor applies to tokens.
       if (!env.PERPLEXITY_API_KEY) {
@@ -79,7 +201,7 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
   }
 
   try {
-    const result = await runEpoch(panel, { dir, engines, delayMs: 250 });
+    const result = await runEpoch(panel, { dir, engines, delayMs: 250, err });
     if (args.json) {
       out(JSON.stringify(result, null, 2));
     } else {

package/cli/client.js

@@ -2,7 +2,7 @@ import {restResponseContract} from '../shared/response-contract.js';
 // A small HTTP client for the cloud. Scoped keys only; no human session ever reaches here.
 // DP-0036-T13: the CLI names itself so the usage counters can tell it from other REST callers.
 // The version follows the plugin manifests; bump it with them.
-export const CLI_VERSION = '0.5.0';
+export const CLI_VERSION = '0.5.1';
 export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
 export class CloudError extends Error {
   constructor(code, status, details = null) {

package/cli/doctor.js

@@ -261,6 +261,25 @@ export async function doctorMain(argv = [], { cwd = process.cwd(), out = console
     checks.push({ status: 'skip', name: 'citations', detail: 'no engine credential set; mock citation runs work, live runs need PERPLEXITY_API_KEY' });
   }
 
+  // Browser engines: the Camoufox stack. Each missing piece names its fix; none
+  // of it fails doctor, because API and mock engines do not need it.
+  try {
+    await import('playwright-core');
+    const { execFile } = await import('node:child_process');
+    const camoufoxOk = await new Promise((resolve) => {
+      // `camoufox path` resolves the fetched browser and exits 0; the launcher
+      // has no --version flag and exits nonzero on it.
+      execFile('camoufox', ['path'], { timeout: 8000 }, (error) => resolve(!error));
+    });
+    if (camoufoxOk) {
+      checks.push({ status: 'ok', name: 'browser', detail: 'playwright-core + camoufox present; browser engines available' });
+    } else {
+      checks.push({ status: 'skip', name: 'browser', detail: 'playwright-core ok but camoufox missing', fix: 'python3 -m pip install cloverlabs-camoufox[geoip] && python3 -m camoufox fetch' });
+    }
+  } catch {
+    checks.push({ status: 'skip', name: 'browser', detail: 'browser engines unavailable: playwright-core not installed', fix: 'npm install playwright-core (API and mock engines are unaffected)' });
+  }
+
   out(`agentlinkops doctor — ${config.dir}`);
 
   // Record the probe outcomes beside the cursors they protect — BEFORE rendering, so the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentlinkops",
-  "version": "0.5.0",
-  "description": "A backlink ledger that lives in your repository: local link checks with dated evidence, supplier-export imports and optional sync to the hosted AgentLinkOps service.",
+  "version": "0.6.0",
+  "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",
   "type": "module",
@@ -21,6 +21,7 @@
     "templates",
     "references",
     "scripts",
+    ".mcp.json",
     ".claude-plugin",
     ".codex-plugin",
     "README.md",
@@ -45,15 +46,25 @@
     "mcp",
     "backlinks",
     "seo",
+    "citation-monitoring",
+    "ai-citations",
     "agent",
     "cli",
     "link-monitoring",
+    "citation-watch",
     "ledger",
     "jsonl"
   ],
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "parse5": "8.0.1",
+    "turndown": "^7.2.4",
     "zod": "4.6.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "optionalDependencies": {
+    "playwright-core": "^1.63.0"
   }
-}
+}