agentlinkops 0.6.13 → 0.6.16

package/README.md

@@ -1,5 +1,9 @@
 # agentlinkops
 
+<!-- generated:customer-catalog begin -->
+Pack version 0.6.16. 156 commands in 13 toolsets.
+<!-- generated:customer-catalog end -->
+
 A backlink ledger that lives in your repository. `agentlinkops check` fetches a source page,
 looks for the link you declared and records an observation with the HTTP status, redirect
 chain, robots posture and a SHA-256 of the fetched bytes. Page HTML never enters the repository.
@@ -30,7 +34,8 @@ the installed version's help before selecting guidance.
    `https://app.agentlinkops.com/mcp` as a remote HTTP MCP server in your client.
    On a version whose help supports selection, use `agentlinkops agent setup --skill ID`
    or `--recipe ID` for optional guidance; repeat either flag for several choices.
-   Choose `--all-skills` only for the complete pack. Customer instructions and records
+   Choose `--all-skills` only for this product pack's skills. Separate optional packs
+   require `--pack DIR`. Customer instructions and records
    remain the customer's choice.
 
    Preview `agentlinkops agent remove --recipe ID` or `--skill ID` before adding
@@ -58,8 +63,8 @@ the installed version's help before selecting guidance.
 
 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. The package is `agentlinkops` on npm, published by the
+https://agentlinkops.com/SKILL.md serves. Hosted monitoring is a private pilot, and access opens
+in stages; the 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
@@ -168,46 +173,16 @@ agentlinkops sync --dry-run
 agentlinkops sync
 ```
 
-Hosted access is an invitation-only pilot. The hosted checks, evidence store and MCP server are a
-separate service and are not part of this package.
-
-## Citation watches
-
-An AI citation is a placement: a reference to your asset on a surface you do not control,
-re-decided by the model on every ask. So the CLI watches it the way it watches a link — a prompt
-panel, run against engine APIs on cadence, with dated evidence and honest statistics. A citation
-is never reported as "removed": each epoch states the citation rate with a Wilson interval and
-its sample size, classified against the previous epoch as declined, grown or
-not_distinguishable, or `insufficient_data` when n is too thin to interpret.
+Hosted access opens in stages: anyone can create an account at https://app.agentlinkops.com/sign-up,
+and an account outside the pilot is told it is waiting for access. The hosted checks, evidence store
+and MCP server are a separate service and are not part of this package.
 
-```sh
-agentlinkops citation panel --domain example.com --brand Example --out panel.json
-agentlinkops citation run panel.json --max-usd 1.00
-```
+## Citation commands
 
-New panels use the free mock engine. A live engine requires its own configuration and credentials;
-missing credentials never select mock results. The JSON panel contains `targets`, `prompts`,
-`engines`, optional `samples` and `maxUsd`. Answer snapshots live in
-`.agentlinkops/citations/evidence/`; observation and epoch ledgers live at the `.agentlinkops/` root.
-The runner reserves estimated cost before each call and retry. A reported supplier
-overrun stops later calls; estimates do not enforce a provider invoice cap. A budget
-abort leaves a partial-epoch receipt and exit code 2. A cell
-that declined with complete evidence exits 1, like an expected link observed absent.
-
-Browser measurement requires `AGENTLINKOPS_PROXY_URL` and refuses direct fallback.
-For an explicitly authorized direct diagnostic, set `AGENTLINKOPS_BROWSER_EGRESS=direct-diagnostic`
-and leave the proxy unset. The standard URL proxy provides no actual usage meter;
-its cost remains an estimate. Browser login and live account acceptance are separate.
-
-Browser epochs retain supplied usage and cleanup receipts in
-`.agentlinkops/citations/egress/<epochId>.jsonl`. Unknown meter values stay null. A missing
-final record means the journal is incomplete; it does not establish complete costs or cleanup.
-Journals stop at 10,000 records or 8 MiB, and a failed write stops further samples.
-
-Frozen inventories and evidence uploads check files against their retained observation hashes.
-Historical hashes verify the recorded answer fields and screenshot filename; they do not prove
-when an answer was captured or authenticate old screenshot pixels. Hosted uploads retain a
-separate hash of the exact uploaded file bytes.
+The local `agentlinkops citation` commands stay in this package for existing panels.
+AI citation measurement is not part of the AgentLinkOps offer, and the hosted service does
+not list citation commands for customers. `agentlinkops citation help` describes the local
+commands.
 
 ## Environment variables
 
@@ -228,13 +203,24 @@ ledger directory are still accepted with a one-line notice on stderr until 2026-
 ## Agent plugin
 
 The package doubles as a plugin: `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`
-point at `skills/`, which holds the connect, CRM, campaign and asset skills plus the
-content-pipeline skills, with templates in `templates/` and contracts in `references/`.
-`agentlinkops agent setup` installs the same skills for any detected client, and the discovery
-index at `https://agentlinkops.com/.well-known/agent-skills/index.json` serves them to
-`npx skills add` (the content pipeline sits behind `https://agentlinkops.com/content`). Node.js
-runs the ledger CLI; Python 3.10 or later runs the optional CRM helper and the watermark
-scanner.
+point at five product skills in `skills/`: connect, discovery, campaigns, CRM and assets.
+`agentlinkops agent setup` keeps the connection-only default; `--skill` and `--recipe`
+add explicit selections. `--all-skills` selects this pack's five skills. Upgrades retain
+older optional selections and customer edits until explicit removal.
+
+The separate optional content pack contains builder, humanizer, text cleanup,
+internal-linking and pre-publish guidance. Its source-rights and portable-dependency
+qualification remain unresolved; the product build preserves its
+older published index and archives without qualifying them. When a separately qualified
+pack is available, `--pack DIR` selects its local skills directory. An optional pack alone
+does not configure AgentLinkOps MCP. The existing product discovery index and content
+index paths remain unchanged.
+
+Each standalone product archive includes its required references and Python resources.
+Its dependency receipt declares the separately installed CLI, selected recipes and
+customer tools. Node.js runs the CLI; Python 3.10 or later runs the optional CRM helper.
+Inspect the installed version and help before using a local feature. Refreshing the
+hosted command catalog does not install a newer CLI.
 
 ## What it does not do
 

package/cli/adapters/suppliers.js

@@ -69,7 +69,7 @@ export const SUPPLIERS = Object.freeze({
   },
   google_search_console: {
     label: 'Google Search Console linking pages export',
-    source: alias('Linking page', 'Linking Page', 'Source page'),
+    source: alias('Linking page', 'Linking Page', 'Source page', 'Links', 'Source URL'),
     target: alias('Target page', 'Target Page', 'Linked page'),
     last_seen: alias('Last crawled', 'Last crawled date'),
     // GSC's headline exports are COUNTS PER SITE, not placements. Importing one would mean

package/cli/agent-setup.js

@@ -17,13 +17,15 @@ import { parseArgs } from "./args.js";
 import { ConfigError } from "./config.js";
 import { AGENT_CLIENTS, clientById } from "../shared/agent-clients.js";
 import { NUDGE } from "./skill.js";
+import { STORED_KEY } from "./key-store.js";
 
 // DP-0036-T09: `agentlinkops agent setup` (Stripe's `stripe agent setup` shape). It detects the
 // agent clients on this machine, installs the skill pack at each client's path with digest
 // verification, and writes the MCP entry for the view that client should use, from the one
-// client table in shared/agent-clients.js. It stores no credential: OAuth happens in the
-// client. It is idempotent, never overwrites a file it did not write, and prints exactly what
-// changed. `agent status` reports what is installed without touching anything.
+// client table in shared/agent-clients.js. It stores no credential itself: OAuth happens in the
+// client, and on a terminal the caller may offer to connect the CLI too (connectCli), which saves
+// a pasted key outside the repository. It is idempotent, never overwrites a file it did not write,
+// and prints exactly what changed. `agent status` reports what is installed without touching anything.
 const USAGE =
   "agent setup [--client ID ...] [--scope project|user] [--origin URL] [--pack DIR] [--skill ID ...] [--recipe ID ...] [--all-skills] [--dry-run] [--json] | agent status [--json] | agent remove [--skill ID ...] [--recipe ID ...] [--scope project|user] [--apply] [--json] | agent recover [--scope project|user] [--apply] [--json]";
 export const DEFAULT_ORIGIN = "https://app.agentlinkops.com";
@@ -31,6 +33,7 @@ export const SERVER_NAME = "agentlinkops";
 const RECEIPT = ".agentlinkops/agent-setup.json";
 const SHARED = Symbol("package siblings");
 const SELECTION = Symbol("selected payloads");
+const ARTIFACT = Symbol("pack artifact contract");
 const CORE_SKILL = "agentlinkops-connect";
 const selectionIds = (value, flag) => {
   const ids = value === undefined ? [] : [].concat(value);
@@ -187,6 +190,38 @@ export async function readPack(dir) {
       "Skill package exceeds the 10000-file/32MiB install bound.",
     );
   Object.defineProperty(skills, SHARED, { value: siblings });
+  await safePath(join(dir, "..", "PACK-ARTIFACT.json"));
+  await safePath(join(dir, "..", "PACKS.json"));
+  const artifactBytes = await bytesAt(join(dir, "..", "PACK-ARTIFACT.json"));
+  const contractBytes = await bytesAt(join(dir, "..", "PACKS.json"));
+  if (artifactBytes || contractBytes) {
+    let artifact, contract;
+    try {
+      contract = JSON.parse(contractBytes);
+      // The maintained source tree has PACKS but no generated artifact receipt.
+      // Its explicit default still uses additive product selection; missing
+      // generated metadata must not restore the old prune-everything mode.
+      artifact = artifactBytes ? JSON.parse(artifactBytes) : {
+        schemaVersion:1,pack:contract.defaultPack,skills:contract.packs?.[contract.defaultPack]?.skills,
+        defaultCliSkills:contract.packs?.[contract.defaultPack]?.defaultCliSkills,
+        mcp:contract.packs?.[contract.defaultPack]?.mcp,contractSha256:sha256(JSON.stringify(contract)),
+        selectionSource:'maintained manifest; no generated artifact qualification',
+      };
+    } catch { throw new ConfigError("The selected pack metadata is unavailable or invalid."); }
+    const selected = contract?.packs?.[artifact?.pack];
+    if (!artifact || artifact.schemaVersion !== 1 || contract?.schemaVersion !== 1 || !["product", "content"].includes(artifact.pack)
+        || !selected || selected.sourcePolicy !== (artifact.pack === "product" ? "maintained-product-source" : "reviewed-portable-source")
+        || artifact.contractSha256 !== sha256(JSON.stringify(contract))
+        || !Array.isArray(artifact.skills) || !Array.isArray(artifact.defaultCliSkills)
+        || !isDeepStrictEqual(artifact.skills, selected.skills) || !isDeepStrictEqual([...artifact.skills].sort(), Object.keys(skills).sort())
+        || !isDeepStrictEqual(artifact.defaultCliSkills, selected.defaultCliSkills) || artifact.mcp !== selected.mcp
+        || artifact.mcp !== (artifact.pack === "product")
+        || !isDeepStrictEqual(artifact.defaultCliSkills, artifact.pack === "product" ? [CORE_SKILL] : [])
+        || artifact.defaultCliSkills.some(id => !Object.hasOwn(skills,id))
+        || artifact.skills.some(id => contract.dependencies?.[id]?.unresolved?.length))
+      throw new ConfigError("The selected pack metadata disagrees with its files or source hold.");
+    Object.defineProperty(skills, ARTIFACT, {value:artifact});
+  }
   return skills;
 }
 
@@ -195,12 +230,20 @@ export async function readPack(dir) {
 export function selectPack(pack, { skills = [], recipes = [], all = false } = {}) {
   if (all && (skills.length || recipes.length))
     throw new ConfigError("Choose --all-skills or named --skill/--recipe selections.");
-  if (!Object.hasOwn(pack, CORE_SKILL) || !pack[CORE_SKILL]["SKILL.md"]?.bytes.length)
+  const artifact = pack[ARTIFACT], connects = artifact?.mcp !== false;
+  if (connects && (!Object.hasOwn(pack, CORE_SKILL) || !pack[CORE_SKILL]["SKILL.md"]?.bytes.length))
     throw new ConfigError("The core connection skill is missing from the package.");
-  if (!pack[CORE_SKILL]["references/agentlinkops.md"]?.bytes.length)
+  if (connects && !pack[CORE_SKILL]["references/agentlinkops.md"]?.bytes.length)
     throw new ConfigError("The core connection reference is missing from the package.");
-  if (all) return { pack, selection: { mode: "all", skills: Object.keys(pack), recipes: [] } };
-  const selected = new Set([CORE_SKILL, ...skills]);
+  if (all) {
+    // A new product-only artifact must not prune optional payloads installed by
+    // an older mixed bundle. Legacy packs retain their existing explicit mode.
+    if (artifact) Object.defineProperty(pack, SELECTION, {value:true});
+    return { pack, selection: { mode: "all", skills: Object.keys(pack), recipes: [] } };
+  }
+  const selected = new Set([...(artifact?.defaultCliSkills ?? [CORE_SKILL]), ...skills]);
+  if (!connects && (!selected.size || recipes.length))
+    throw new ConfigError("Select optional pack skills with --skill ID or --all-skills; product recipes are a separate selection.");
   const siblings = pack[SHARED] ?? {};
   let catalog = null;
   if (recipes.length) {
@@ -239,6 +282,7 @@ export function selectPack(pack, { skills = [], recipes = [], all = false } = {}
   }
   Object.defineProperty(result, SHARED, { value: support });
   Object.defineProperty(result, SELECTION, { value: true });
+  if (artifact) Object.defineProperty(result, ARTIFACT, {value:artifact});
   return { pack: result, selection: { mode: "selected", skills: [...selected], recipes: chosenRecipes } };
 }
 
@@ -900,6 +944,7 @@ export async function agentMain(
     packDir = null,
     now = () => new Date().toISOString(),
     afterOperation,
+    connectCli = null,
   } = {},
 ) {
   const args = parseArgs(argv, ["client", "skill", "recipe"]);
@@ -1109,9 +1154,9 @@ export async function agentMain(
       scope,
       receipt,
     });
-    for (const path of skills.desired) desired.add(path);
-    for (const path of skills.roots) selectedRoots.add(path);
-    const mcp = await planMcp(client, { cwd, home, origin, scope });
+    const mcp = pack[ARTIFACT]?.mcp === false
+      ? {action:"not selected",file:null,url:null}
+      : await planMcp(client, { cwd, home, origin, scope });
     const entry = {
       id: client.id,
       name: client.name,
@@ -1130,6 +1175,19 @@ export async function agentMain(
         ...(mcp.snippet ? { snippet: mcp.snippet } : {}),
       },
     };
+    // Autodetection is a convenience, not one shared permission boundary. Leave a
+    // conflicting client's files and receipt ownership alone while installing
+    // independent clients. An explicit multi-client selection remains atomic.
+    if (!only && (skills.conflicts.length || mcp.action === "conflict")) {
+      entry.skipped = true;
+      if (mcp.action === "write") entry.mcp.action = "not applied";
+      if (mcp.action === "conflict") report.next.push(`${client.name}: ${mcp.note}`);
+      for (const c of skills.conflicts) report.next.push(`${client.name}: ${c.target} ${c.note}`);
+      report.clients.push(entry);
+      continue;
+    }
+    for (const path of skills.desired) desired.add(path);
+    for (const path of skills.roots) selectedRoots.add(path);
     for (const item of skills.install) {
       operations.set(item.target, {
         path: item.target,
@@ -1191,9 +1249,11 @@ export async function agentMain(
   const conflicts = report.clients.some(
     (c) => c.skills.conflicts.length || c.mcp.action === "conflict",
   );
+  const readyClients = report.clients.filter(c => !c.skipped);
+  const blocked = conflicts && (Boolean(only) || readyClients.length === 0);
   if (
     !report.dryRun &&
-    !conflicts &&
+    !blocked &&
     (operations.size || ownershipChanged || !receipt)
   ) {
     const oldReceipt = await bytesAt(paths.receipt),
@@ -1203,7 +1263,7 @@ export async function agentMain(
             installedAt: now(),
             origin,
             scope,
-            clients: report.clients.map((c) => c.id),
+            clients: readyClients.map((c) => c.id),
             lastSetupSelection: selection,
             files: ownedFiles,
             mcp: ownedMcp,
@@ -1225,7 +1285,7 @@ export async function agentMain(
     for (const c of report.clients)
       if (c.mcp.action === "planned") c.mcp.action = "written";
   }
-  if (conflicts) {
+  if (blocked) {
     report.pruned = [];
     report.next.push(
       "Conflicts prevented all installation writes. Resolve them and retry.",
@@ -1235,14 +1295,38 @@ export async function agentMain(
       if (c.mcp.action === "planned") c.mcp.action = "not applied";
     }
   }
-  report.next.push(
-    "For a chosen hosted task, sign in through the client's MCP OAuth flow. Local supplied-link checks require no AgentLinkOps account; no credential was stored by this command.",
+  if (conflicts && !blocked) report.next.push(
+    report.dryRun
+      ? "Conflicting clients would be skipped; other clients can be installed."
+      : "Conflicting clients were skipped; other clients were installed. Retry a skipped client with --client ID after resolving its conflicts.",
+  );
+  const connects = pack[ARTIFACT]?.mcp !== false;
+  if (!blocked && connects) {
+    // The plain next step: where the sign-in happens, then where to approve it.
+    for (const c of readyClients)
+      report.next.push(c.id === "claude-code"
+        ? `Claude Code: open it${scope === "project" ? " in this folder" : ""}, run /mcp, select ${SERVER_NAME} and choose Authenticate.`
+        : `${c.name}: sign in when it first connects to ${SERVER_NAME}; the client opens the sign-in page.`);
+    report.next.push(`Then approve the agent's request on the Agent page: ${origin}/#/access`);
+  }
+  const offerCli = connects && !json && !report.dryRun && !blocked && typeof connectCli === "function";
+  if (connects) report.next.push(
+    `For a chosen hosted task, sign in through the client's MCP OAuth flow. Local supplied-link checks require no AgentLinkOps account; ${offerCli
+      ? "this command stores a credential only if you paste a CLI key below."
+      : "no credential was stored by this command."}`,
   );
+  const cliReady = connects && (["AGENTLINKOPS_API_KEY", "AGENTLINKOPS_TOKEN", "LINKTRAIL_API_KEY", "LINKTRAIL_TOKEN"].some((name) => env[name]) ||
+    !!env[STORED_KEY]?.(origin));
+  if (connects && !cliReady && !offerCli)
+    report.next.push(`To use the agentlinkops CLI too, run \`npx -y agentlinkops connect\` in a terminal and paste an API key from ${origin}/#/access.`);
   if (report.retainedExisting.length)
     report.next.push("Earlier payloads outside this selection were retained. Preview agent remove --skill ID or --recipe ID to remove them explicitly.");
-  report.next.push("Optional skills and recipes: agent setup --skill ID or --recipe ID; --all-skills installs the complete pack.");
-  report.next.push(NUDGE);
+  report.next.push(connects
+    ? "Select available product skills or recipes with --skill ID or --recipe ID. --all-skills installs this pack's skills; separate optional packs require --pack DIR."
+    : "This optional selection does not configure AgentLinkOps MCP. Use --pack DIR and --skill ID or --all-skills to select its available skills.");
+  if (connects) report.next.push(NUDGE);
   out(json ? JSON.stringify(report, null, 2) : renderSetup(report));
+  if (offerCli) await connectCli(origin);
   return report.clients.some(
     (c) => c.skills.conflicts.length || c.mcp.action === "conflict",
   )