agentlinkops 0.5.0

package/cli/connection.js

@@ -0,0 +1,90 @@
+import { readFile, writeFile, rename, unlink, open } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { loadConfig, ConfigError } from './config.js';
+import { createClient } from './client.js';
+import { readLedger } from './ledger.js';
+import { resolveEnv } from './env.js';
+
+export const SYNC_SCOPES = ['projects:read', 'watches:read', 'watches:write', 'events:read', 'exports:create'];
+
+// Both TOKEN and API_KEY have shipped in customer installations, under both the AGENTLINKOPS_
+// and the LINKTRAIL_ prefix (env.js owns that alias rule). Reject ambiguous identities: a
+// TOKEN that disagrees with an API_KEY fails the same way a new name that disagrees with its
+// old spelling does.
+export function cloudConnection(config, env = process.env) {
+  const { values, sources } = resolveEnv(env);
+  if (values.TOKEN && values.API_KEY && values.TOKEN !== values.API_KEY)
+    throw new ConfigError(`${sources.TOKEN} and ${sources.API_KEY} disagree; select one credential.`);
+  if (values.API_URL && config.cloud?.origin && new URL(values.API_URL).origin !== new URL(config.cloud.origin).origin)
+    throw new ConfigError(`${sources.API_URL} disagrees with the saved cloud origin.`);
+  if (new Set([config.cloud?.workspaceId, config.cloud?.workspace_id].filter(Boolean)).size > 1 || new Set([config.project?.id, config.cloud?.projectId, config.cloud?.project_id].filter(Boolean)).size > 1)
+    throw new ConfigError('Saved cloud identity fields disagree.');
+  return { origin: values.API_URL || config.cloud?.origin,
+    token: values.TOKEN || values.API_KEY || config.cloud?.token,
+    tokenSource: values.TOKEN ? sources.TOKEN : values.API_KEY ? sources.API_KEY : null,
+    workspaceId: config.cloud?.workspaceId || config.cloud?.workspace_id, projectId: config.project?.id || config.cloud?.projectId || config.cloud?.project_id };
+}
+
+export function keySetup(origin) {
+  return `Open ${origin}/app, select the workspace, then Agent access > Create API key. Select the project and scopes ${SYNC_SCOPES.join(', ')}. Supply the key through AGENTLINKOPS_TOKEN (AGENTLINKOPS_API_KEY also works; the LINKTRAIL_ spellings remain accepted during the pilot compatibility window), then rerun connect. MCP OAuth credentials remain in the MCP client.`;
+}
+
+// Verify an existing project before saving only non-secret connection metadata.
+export async function connectMain(args, { cwd, env = process.env, out = console.log, fetchImpl = globalThis.fetch } = {}) {
+  const config = await loadConfig({ cwd });
+  const connection = cloudConnection(config, env);
+  const origin = args.origin || connection.origin || 'https://app.agentlinkops.com';
+  const workspaceId = args.workspace || connection.workspaceId;
+  const projectId = args['project-id'] || connection.projectId;
+  let parsed;
+  try { parsed = new URL(origin); } catch { throw new ConfigError('connect --origin requires an HTTPS origin.'); }
+  if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.search || parsed.hash || parsed.pathname !== '/')
+    throw new ConfigError('connect --origin requires an HTTPS origin without a path.');
+  if (!connection.token) { out(keySetup(parsed.origin)); return 2; }
+  if (!/^lt_[0-9a-f]{64}$/.test(connection.token)) throw new ConfigError('Supply a complete API key through AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY.');
+  if (typeof workspaceId !== 'string' || !workspaceId || typeof projectId !== 'string' || !projectId)
+    throw new ConfigError('connect requires --workspace ID and --project-id ID from the existing cloud project.');
+  if (config.cloud?.origin && new URL(config.cloud.origin).origin !== parsed.origin || connection.workspaceId && connection.workspaceId !== workspaceId || connection.projectId && connection.projectId !== projectId)
+    throw new ConfigError('This ledger is connected elsewhere; use a separate ledger to preserve its cursors and mapping.');
+  let ledgerIds;
+  if (args.selection !== undefined) {
+    if (typeof args.selection !== 'string') throw new ConfigError('--selection requires a JSON file of ledger IDs or mapping entries.');
+    const selection = JSON.parse(await readFile(resolve(cwd || process.cwd(), args.selection), 'utf8'));
+    ledgerIds = Array.isArray(selection) ? selection : selection.entries?.map(entry => entry.local_id);
+    const ledger = await readLedger(config.paths.ledger);
+    if (ledger.missing || ledger.problems.length || !Array.isArray(ledgerIds) || ledgerIds.some(id => typeof id !== 'string' || !ledger.entries.some(entry => entry.id === id)))
+      throw new ConfigError('Selection must name existing ledger IDs in a valid ledger.');
+    ledgerIds = [...new Set(ledgerIds)];
+  }
+  const client = createClient({ origin: parsed.origin, token: connection.token, workspaceId, fetchImpl });
+  const account = await client.getWorkspace();
+  if (account.workspace?.id !== workspaceId) throw new ConfigError('Cloud workspace does not match the selected workspace.');
+  const missing = SYNC_SCOPES.filter(scope => !account.access?.scopes?.includes(scope));
+  if (missing.length) throw new ConfigError(`Key lacks sync scopes: ${missing.join(', ')}.`);
+  const project = await client.getProject(projectId);
+  if (project.id !== projectId || project.workspace_id !== workspaceId) throw new ConfigError('Cloud project does not match the selected workspace.');
+  const lockPath = join(config.dir, 'sync.lock');
+  const lock = await open(lockPath, 'wx');
+  const file = join(config.dir, 'config.json'), temporary = join(config.dir, `.connect-${crypto.randomUUID()}.tmp`);
+  try {
+    const before = await readFile(file, 'utf8');
+    const saved = JSON.parse(before);
+    const savedIdentity = cloudConnection(saved, {});
+    if (savedIdentity.workspaceId && savedIdentity.workspaceId !== workspaceId || savedIdentity.projectId && savedIdentity.projectId !== projectId)
+      throw new ConfigError('This ledger is connected to another workspace or project; use a separate ledger to preserve its cursors and mapping.');
+    if (saved.cloud?.origin && new URL(saved.cloud.origin).origin !== parsed.origin)
+      throw new ConfigError('This ledger is connected to another origin; use a separate ledger to preserve its cursors and mapping.');
+    saved.cloud = { ...saved.cloud, origin: parsed.origin, workspaceId };
+    if (ledgerIds !== undefined) saved.cloud.ledgerIds = ledgerIds;
+    delete saved.cloud.token;
+    saved.project = { ...saved.project, id: projectId };
+    await writeFile(temporary, JSON.stringify(saved, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    if (await readFile(file, 'utf8') !== before) throw new ConfigError('Connection configuration changed; retry.');
+    await rename(temporary, file);
+  } finally {
+    await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
+    await lock.close(); await unlink(lockPath);
+  }
+  out(`Verified workspace ${workspaceId}, project ${projectId}. Saved connection metadata; keep the key in the environment. Run agentlinkops sync --dry-run to review uploads, or agentlinkops sync --pull-only to retrieve history.`);
+  return 0;
+}

package/cli/context-mcp.js

@@ -0,0 +1,193 @@
+import { loadConfig, DEFAULTS, LEGACY_DIR } from './config.js';
+import { readEnv } from './env.js';
+import {
+    contextPaths, loadContextConfig, readManual, buildManualContext, readContextState, readGscRows,
+    pageContext, selectFocusPages, refreshContext, importHandoff, createGoogleClient,
+    recentWindows, windowFromRange,
+  } from '../src/context/gsc.js';
+import { buildSiteProfile, validateProfileCitations, readSiteFacts } from '../src/context/site-profile.js';
+// Repository-local MCP over stdio. Host root is chosen at startup, never by tool arguments.
+import { readFile, realpath } from 'node:fs/promises';
+import { resolve, relative, dirname, join, isAbsolute, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod';
+import { registerContextTools } from '../src/context-tool-registry.js';
+
+// Injecting path semantics lets the boundary be verified on Windows as well as POSIX.
+export function isWithinContextRoot(root, file, paths = { relative, isAbsolute, sep }) {
+  const rel = paths.relative(root, file);
+  return rel !== '..' && !rel.startsWith(`..${paths.sep}`) && !paths.isAbsolute(rel);
+}
+
+const propertyName = value => {
+  if (typeof value !== 'string') return false;
+  if (/^sc-domain:[a-z0-9.-]+$/i.test(value)) return true;
+  try { const url = new URL(value); return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash; }
+  catch { return false; }
+};
+const connectionGrants = new Set(['none', 'ok', 'refused', 'revoked', 'token_present_unverified']);
+const permissionLevels = new Set(['siteOwner', 'siteFullUser', 'siteRestrictedUser', 'siteUnverifiedUser']);
+
+// State files are editable local input. Never spread them into an agent response: even a
+// nested credential field or malformed typed field must not become connection metadata.
+export function connectionStatus(connection, tokenPresent) {
+  const raw = connection && typeof connection === 'object' ? connection : {};
+  const result = { grant: connectionGrants.has(raw.grant) ? raw.grant : (tokenPresent ? 'token_present_unverified' : 'none'),
+    token_in_env: Boolean(tokenPresent) };
+  if (typeof raw.checked_at === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(raw.checked_at) && Number.isFinite(Date.parse(raw.checked_at))) result.checked_at = new Date(raw.checked_at).toISOString();
+  if (Number.isInteger(raw.last_status) && raw.last_status >= 100 && raw.last_status <= 599) result.last_status = raw.last_status;
+  if (Array.isArray(raw.properties)) result.properties = raw.properties.filter(propertyName);
+  if (raw.permission_levels && typeof raw.permission_levels === 'object' && !Array.isArray(raw.permission_levels)) {
+    result.permission_levels = Object.fromEntries(Object.entries(raw.permission_levels)
+      .filter(([property, level]) => propertyName(property) && permissionLevels.has(level)));
+  }
+  return result;
+}
+
+// Resolve existing ancestors as well as leaves: nonexistent outputs can still escape through
+// a symlinked parent. Recheck on every call so config edits do not silently widen the root.
+async function contained(root, file) {
+  const inside = path => {
+    if (!isWithinContextRoot(root, path)) throw new Error('Context path is outside the configured repository root');
+  };
+  inside(file);
+  let parent = file;
+  for (;;) {
+    try { inside(await realpath(parent)); break; }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      parent = dirname(parent);
+    }
+  }
+  return file;
+}
+
+export async function contextService(cwd, env = process.env) {
+
+  const root = await realpath(cwd);
+  const pathsOf = async () => {
+    for (const dir of [DEFAULTS.dir, LEGACY_DIR]) await contained(root, join(root, dir, 'config.json'));
+    const config = await loadConfig({ root });
+    const file = await loadContextConfig(config.dir);
+    const paths = contextPaths({ dir: config.dir, file });
+    for (const path of Object.values(paths)) await contained(root, path);
+    return { config, paths };
+  };
+  const service = {
+    status: async () => {
+      const { paths } = await pathsOf();
+      const state = await readContextState(paths.contextState);
+      const { rows, problems, missing } = await readGscRows(paths.gsc);
+      const manual = await readManual(paths.manual);
+      const facts = await readSiteFacts(paths.siteFacts);
+      return {
+        project: (await pathsOf()).config.project,
+        connection: connectionStatus(state.connection, Boolean(readEnv(env, 'GSC_TOKEN').value)),
+        handoff: state.handoff ?? null, availability: state.availability ?? {},
+        last_fetch_count: Object.keys(state.last_fetch ?? {}).length,
+        gsc_rows: rows.length, gsc_file_missing: missing, gsc_problems: problems,
+        site_fact_rows: facts.rows.length,
+        manual_present: manual.present, manual_entries: manual.entries.length,
+      };
+    },
+    manual: async () => {
+      const { paths } = await pathsOf();
+      const manual = await readManual(paths.manual);
+      if (!manual.present) return { error: `no manual.md at ${paths.manual}` };
+      return buildManualContext({ manual });
+    },
+    focus: async a => {
+      const { paths } = await pathsOf();
+      const manual = await readManual(paths.manual);
+      const { rows } = await readGscRows(paths.gsc);
+      const state = await readContextState(paths.contextState);
+      const window = a?.start && a?.end ? windowFromRange(a.start, a.end) : recentWindows({ days: 28, count: 1 })[0];
+      return { ...selectFocusPages({ manual, rows, window, connection: state.connection ?? null }), window };
+    },
+    page: async a => {
+      const { paths } = await pathsOf();
+      const { rows } = await readGscRows(paths.gsc);
+      const state = await readContextState(paths.contextState);
+      const manual = await readManual(paths.manual);
+      const window = a?.start && a?.end ? windowFromRange(a.start, a.end) : null;
+      return pageContext({ rows, page: a.page, window, properties: state.connection?.properties ?? null, connection: state.connection ?? null, manual });
+    },
+    refresh: async a => {
+      const { paths } = await pathsOf();
+      const token = readEnv(env, 'GSC_TOKEN').value ?? null;
+      const client = token ? createGoogleClient({ accessToken: token }) : null;
+      return refreshContext({ client, paths, properties: a?.properties ?? null, dataState: a?.dataState ?? 'final' });
+    },
+    import: async a => {
+      const { paths } = await pathsOf();
+      return importHandoff({ paths, file: await contained(root, resolve(root, a.file)) });
+    },
+    buildProfile: async (a, deps = {}) => {
+      const { paths } = await pathsOf();
+      return buildSiteProfile({ site: a?.site ?? null, paths, extraPages: a?.pages ?? [], ...(deps.transport ? { transport: deps.transport } : {}), ...(deps.acquisition ? { acquisition: deps.acquisition } : {}) });
+    },
+    checkProfile: async () => {
+      const { paths } = await pathsOf();
+      let profileText;
+      try { profileText = await readFile(paths.siteProfile, 'utf8'); }
+      catch { return { error: `no site-profile.md at ${paths.siteProfile}` }; }
+      const { rows } = await readSiteFacts(paths.siteFacts);
+      const manual = await readManual(paths.manual);
+      return validateProfileCitations({ profileText, facts: rows, manual });
+    },
+  };
+  return Object.fromEntries(Object.entries(service).map(([name, handler]) => [name, async (args = {}) => {
+    if (Boolean(args.start) !== Boolean(args.end)) throw new Error('start and end must be supplied together');
+    return handler(args);
+  }]));
+}
+
+export async function createContextServer({ root, env = process.env }) {
+  if (!root) throw new Error('A repository --root is required');
+  const context = await contextService(root, env);
+  const server = new McpServer({ name: 'agentlinkops-local-context', version: '0.1.0' });
+  // Serialize file operations, including reads: refresh/import share state files and must not
+  // lose updates when an agent submits several calls concurrently.
+  let tail = Promise.resolve();
+  registerContextTools({ context, contextTool(name, description, scope, input, handler, write) {
+    server.registerTool(name, {
+      description, inputSchema: z.strictObject(input),
+      annotations: { readOnlyHint: !write, destructiveHint: false,
+        idempotentHint: !write, openWorldHint: ['context_gsc_refresh', 'context_profile_build'].includes(name) },
+    }, args => {
+      const result = tail.then(async () => {
+        try {
+          const value = await handler(args);
+          return { content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value,
+            ...(value.error || value.unresolved?.length ? { isError: true } : {}) };
+        } catch (error) {
+          // Redact tokens even from third-party exception strings; stdout is protocol-only.
+          let message = String(error.message ?? 'Context operation failed');
+          for (const secret of [env.AGENTLINKOPS_GSC_TOKEN, env.LINKTRAIL_GSC_TOKEN, env.AGENTLINKOPS_GA4_TOKEN, env.LINKTRAIL_GA4_TOKEN].filter(Boolean)) message = message.replaceAll(secret, '[redacted]');
+          return { isError: true, content: [{ type: 'text', text: message }] };
+        }
+      });
+      tail = result.catch(() => {});
+      return result;
+    });
+  } });
+  return server;
+}
+
+const directlyInvoked = await (async () => {
+  try { return process.argv[1] && import.meta.url === pathToFileURL(await realpath(process.argv[1])).href; }
+  catch { return false; }
+})();
+if (directlyInvoked) {
+  const args = process.argv.slice(2);
+  if (args.length !== 2 || args[0] !== '--root') {
+    console.error('Usage: node cli/context-mcp.js --root /absolute/customer/repository');
+    process.exitCode = 2;
+  } else {
+    // Build once before accepting protocol traffic so invalid roots fail at startup.
+    const server = await createContextServer({ root: args[1] });
+    serveStdio(() => server, { onerror: () => console.error('Local context MCP transport error') });
+  }
+}

package/cli/context.js

@@ -0,0 +1,340 @@
+import {parseArgs as parseArguments} from './args.js';
+// `agentlinkops context …` — the DP-0017 first-party context surface (T02 GSC + manual, T03 site
+// profile). STANDALONE BY CONFLICT RULE: this card may not edit src/mcp.js or register tools,
+// so nothing here is dispatched from cli/main.js yet. The module is directly runnable:
+//
+//   node cli/context.js status
+//   node cli/context.js gsc page https://example.com/guide --json
+//
+// and the wiring into main.js's USAGE/dispatch (plus any MCP tool registration) is the recorded
+// follow-up for the next wave. Everything below needs no account; `gsc refresh` needs a
+// customer-supplied token in AGENTLINKOPS_GSC_TOKEN (LINKTRAIL_GSC_TOKEN still accepted) and refuses quietly into `manual_only`
+// without one — the path with no Google is a complete configuration, not a failure.
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { loadConfig, ConfigError } from './config.js';
+import { readEnv } from './env.js';
+import {
+  contextPaths, loadContextConfig, readManual, buildManualContext, parseManual,
+  readContextState, readGscRows, refreshContext, pageContext, selectFocusPages,
+  importHandoff, forgetContext, createGoogleClient, recentWindows, windowFromRange,
+} from '../src/context/gsc.js';
+import { buildSiteProfile, renderSiteProfile, validateProfileCitations, readSiteFacts } from '../src/context/site-profile.js';
+import {
+  refreshGa4Context, landingPageContext, keyEventsContext, businessContextForPage,
+  importGa4Handoff, forgetGa4Context, createGa4Client, readGa4Rows, GA4_SCOPE,
+} from '../src/context/ga4.js';
+
+const USAGE = `agentlinkops context — first-party search context in your repository (DP-0017)
+
+  agentlinkops context status [--json]                 connection state, windows, availability floors
+  agentlinkops context manual [--json]                 the manual.md context (works with no Google)
+  agentlinkops context focus [--json]                  nominated focus pages (manual, then GSC clicks)
+  agentlinkops context gsc refresh [--property P]… [--data-state all] [--json]
+                                                    bounded read-only refresh (<=12 calls/property,
+                                                    hard cap 50; needs AGENTLINKOPS_GSC_TOKEN, else
+                                                    reports manual_only)
+  agentlinkops context gsc page URL [--start D] [--end D] [--json]
+                                                    page/query context for a supplied page, from
+                                                    repo rows — no Google needed
+  agentlinkops context gsc import FILE [--json]        import an agent/connector handoff snapshot
+  agentlinkops context gsc forget [--source gsc|site|all] [--json]
+                                                    remove tool-owned context files; manual.md and
+                                                    site-profile.md are never touched
+  agentlinkops context profile build [--site ORIGIN] [--page URL]… [--json]
+                                                    bounded public sitemap + <=10 page profile
+  agentlinkops context profile render [--force] [--json]
+                                                    write the editable site-profile.md scaffold
+                                                    (never overwrites judgments without --force)
+  agentlinkops context profile check [--json]          every [fact:…]/[manual:…] citation resolves
+  agentlinkops context ga4 refresh --property P [--start D --end D] [--json]
+                                                    optional GA4 business context (<=4 reports/
+                                                    property, hard cap 10; needs
+                                                    AGENTLINKOPS_GA4_TOKEN, else reports ga4_absent)
+  agentlinkops context ga4 page URL [--start D] [--end D] [--json]
+                                                    aggregate landing-page context + configured
+                                                    key events, with measurement caveats
+  agentlinkops context ga4 key-events [--json]         the configured key events and their totals
+  agentlinkops context ga4 import FILE [--json]        import an agent/connector GA4 handoff snapshot
+  agentlinkops context ga4 forget [--json]             remove GA4 rows + GA4 state only
+  agentlinkops context business URL [--start D] [--end D] [--json]
+                                                    GSC search layer and GA4 business layer for a
+                                                    page, side by side — never joined
+
+Read-only. Google scopes requested: webmasters.readonly (GSC) and analytics.readonly (GA4,
+separate consent) only. No CMS, no paid index, no Links API, no AI-report API.`;
+
+const parseArgs = argv => parseArguments(argv,["property", "page"],{property:[],page:[]});
+
+async function resolvePaths(cwd) {
+  const config = await loadConfig({ cwd });
+  const file = await loadContextConfig(config.dir);
+  return { config, paths: contextPaths({ dir: config.dir, file }) };
+}
+
+export async function contextMain(argv = process.argv.slice(2), { cwd = process.cwd(), out = console.log, err = console.error, env = process.env } = {}) {
+  const args = parseArgs(argv);
+  const area = args._[0] ?? 'help';
+  const command = args._[1] ?? null;
+  if (area === 'help' || args.help) { out(USAGE); return 0; }
+  try {
+    const { config, paths } = await resolvePaths(cwd);
+
+    if (area === 'status') {
+      const state = await readContextState(paths.contextState);
+      const { rows, problems, missing } = await readGscRows(paths.gsc);
+      const ga4 = await readGa4Rows(paths.ga4);
+      const manual = await readManual(paths.manual);
+      const facts = await readSiteFacts(paths.siteFacts);
+      const gscToken = readEnv(env, 'GSC_TOKEN'), ga4Token = readEnv(env, 'GA4_TOKEN');
+      const tokenPresent = Boolean(gscToken.value);
+      const ga4TokenPresent = Boolean(ga4Token.value);
+      const summary = {
+        project: config.project,
+        connection: { ...(state.connection ?? { grant: tokenPresent ? 'token_present_unverified' : 'none' }), token_in_env: tokenPresent },
+        handoff: state.handoff ?? null,
+        availability: state.availability ?? {},
+        last_fetch_count: Object.keys(state.last_fetch ?? {}).length,
+        ga4: { ...(state.ga4 ?? { grant: ga4TokenPresent ? 'token_present_unverified' : 'none' }), token_in_env: ga4TokenPresent, rows: ga4.rows.length, file_missing: ga4.missing },
+        gsc_rows: rows.length, gsc_file_missing: missing, gsc_problems: problems,
+        site_fact_rows: facts.rows.length,
+        manual_present: manual.present, manual_entries: manual.entries.length,
+      };
+      if (args.json) { out(JSON.stringify(summary, null, 1)); return 0; }
+      out(`connection grant: ${summary.connection.grant}${tokenPresent ? ` (${gscToken.name} present)` : ''}`);
+      out(`gsc rows: ${rows.length}${missing ? ' (no gsc.jsonl yet)' : ''}`);
+      const ga4Configured = (state.ga4?.key_events_config ?? []).length;
+      out(`ga4: ${summary.ga4.grant}${summary.ga4.property ? ` ${summary.ga4.property}` : ''}  rows ${ga4.rows.length}${ga4Configured ? `  ${ga4Configured} key event(s) configured` : ''}`);
+      out(`site facts: ${facts.rows.length}  manual: ${manual.present ? `${manual.entries.length} entr(ies)` : 'absent'}`);
+      if (Object.keys(summary.availability).length) out(`availability floors: ${JSON.stringify(summary.availability)}`);
+      return 0;
+    }
+
+    if (area === 'manual') {
+      const manual = await readManual(paths.manual);
+      if (!manual.present) { err(`no manual.md at ${paths.manual} — the no-Google floor; create it with target pages, site description, offering, assets, competitors`); return 2; }
+      const context = buildManualContext({ manual });
+      if (args.json) { out(JSON.stringify(context, null, 1)); return 0; }
+      out(JSON.stringify(context.inputs, null, 1));
+      out(`${context.pages.length} target page(s) nominated by manual alone`);
+      return 0;
+    }
+
+    if (area === 'focus') {
+      const manual = await readManual(paths.manual);
+      const { rows } = await readGscRows(paths.gsc);
+      const state = await readContextState(paths.contextState);
+      const window = args.start && args.end ? windowFromRange(args.start, args.end) : (recentWindows({ days: 28, count: 1 })[0]);
+      const focus = selectFocusPages({ manual, rows, window, connection: state.connection ?? null });
+      if (args.json) { out(JSON.stringify({ ...focus, window }, null, 1)); return 0; }
+      for (const entry of focus.pages) out(`${entry.page}  ${entry.nominated_by.join('+')}${entry.observation ? `  clicks ${entry.observation.clicks ?? 'null'}` : ''}`);
+      return 0;
+    }
+
+    if (area === 'gsc') {
+      if (command === 'refresh') {
+        const token = readEnv(env, 'GSC_TOKEN').value ?? null;
+        const client = token ? createGoogleClient({ accessToken: token }) : null;
+        const result = await refreshContext({
+          client, paths,
+          properties: args.property?.length ? args.property : null,
+          dataState: args['data-state'] === 'all' ? 'all' : 'final',
+        });
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        out(`state: ${result.state}`);
+        for (const property of result.properties) out(`  ${property.siteUrl}: ${property.state}${property.rows_written ? `, ${property.rows_written} row(s)` : ''}`);
+        out(`calls: ${JSON.stringify(result.calls)}  served from repo: ${result.served_from_repo}`);
+        for (const note of result.notes) out(`note: ${note}`);
+        return 0;
+      }
+      if (command === 'page') {
+        const page = args._[2];
+        if (!page) { err('agentlinkops context gsc page URL'); return 2; }
+        const { rows } = await readGscRows(paths.gsc);
+        const state = await readContextState(paths.contextState);
+        const manual = await readManual(paths.manual);
+        const window = args.start && args.end ? windowFromRange(args.start, args.end) : null;
+        const result = pageContext({ rows, page, window, properties: state.connection?.properties ?? null, connection: state.connection ?? null, manual });
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        out(`state: ${result.state}  window: ${result.window ? `${result.window.start}..${result.window.end}` : 'n/a'}${result.final_through ? `  final through ${result.final_through}` : ''}`);
+        if (result.page_totals) out(`totals: clicks ${result.page_totals.clicks}  impressions ${result.page_totals.impressions}  ctr ${result.page_totals.ctr}  avg position ${result.page_totals.average_position}`);
+        for (const query of result.queries.slice(0, 20)) out(`  "${query.query}"  ${query.clicks} clicks  ${query.impressions} impr  ctr ${query.ctr}  avg ${query.average_position}`);
+        for (const note of result.notes) out(`note: ${note}`);
+        return 0;
+      }
+      if (command === 'import') {
+        const file = args._[2];
+        if (!file) { err('agentlinkops context gsc import FILE'); return 2; }
+        const result = await importHandoff({ paths, file });
+        if (result.error) { err(result.error); return 2; }
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        out(`imported ${result.accepted} row(s) from connector(s): ${result.connectors.join(', ')}`);
+        for (const refused of result.refused.slice(0, 20)) out(`  refused row ${refused.row}: ${refused.reason}`);
+        if (result.refused.length > 20) out(`  … and ${result.refused.length - 20} more`);
+        return result.refused.length ? 0 : 0;
+      }
+      if (command === 'forget') {
+        const source = args.source === true ? 'gsc' : (args.source ?? 'gsc');
+        const result = await forgetContext({ paths, source });
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        for (const item of result.removed) out(`removed ${item.path}`);
+        for (const item of result.kept) out(`kept ${item.path} (${item.owner}-owned)`);
+        out(result.note);
+        return 0;
+      }
+      err(`unknown context gsc command: ${command ?? '(none)'}\n\n${USAGE}`);
+      return 2;
+    }
+
+    if (area === 'ga4') {
+      if (command === 'refresh') {
+        const token = readEnv(env, 'GA4_TOKEN').value ?? null;
+        const client = token ? createGa4Client({ accessToken: token }) : null;
+        const property = Array.isArray(args.property) ? args.property[0] : args.property;
+        if (client && !property) { err('agentlinkops context ga4 refresh --property properties/123 (or a bare numeric id)'); return 2; }
+        const window = args.start && args.end ? windowFromRange(args.start, args.end) : undefined;
+        const result = await refreshGa4Context({ client, paths, property, windows: window ? [window] : null });
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        out(`state: ${result.state}${result.property ? `  property: ${result.property}` : ''}`);
+        if (result.key_events_configured) out(`key events configured: ${result.key_events_configured.map(e => e.event_name).join(', ') || '(none)'}`);
+        out(`calls: ${JSON.stringify(result.calls)}  served from repo: ${result.served_from_repo}  rows: ${result.rows_written}`);
+        for (const note of result.notes) out(`note: ${note}`);
+        return 0;
+      }
+      if (command === 'page') {
+        const page = args._[2];
+        if (!page) { err('agentlinkops context ga4 page URL'); return 2; }
+        const { rows } = await readGa4Rows(paths.ga4);
+        const state = await readContextState(paths.contextState);
+        const window = args.start && args.end ? windowFromRange(args.start, args.end) : null;
+        const result = landingPageContext({ rows, page, window, connection: state.ga4 ?? null });
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        out(`state: ${result.state}  property: ${result.property ?? 'n/a'}  window: ${result.window ? `${result.window.start}..${result.window.end}` : 'n/a'}`);
+        if (result.totals) out(`totals: sessions ${result.totals.sessions}  key events ${result.totals.key_events}  per session ${result.totals.key_events_per_session}  revenue ${result.totals.total_revenue}${result.currency_code ? ` ${result.currency_code}` : ''}`);
+        for (const event of result.events.slice(0, 20)) out(`  key event "${event.event_name}"  ${event.key_events} (s)  revenue ${event.total_revenue}`);
+        for (const caveat of result.caveats) out(`caveat ${caveat.code}: ${caveat.note}`);
+        for (const note of result.notes) out(`note: ${note}`);
+        return 0;
+      }
+      if (command === 'key-events') {
+        const { rows } = await readGa4Rows(paths.ga4);
+        const window = args.start && args.end ? windowFromRange(args.start, args.end) : null;
+        const result = keyEventsContext({ rows, window });
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        out(`state: ${result.state}  property: ${result.property ?? 'n/a'}${result.window ? `  window: ${result.window.start}..${result.window.end}` : ''}`);
+        for (const event of result.key_events) out(`  "${event.event_name}" (${event.counting_method ?? 'counting method unknown'})  key events: ${event.key_events ?? 'withheld/null'}  [${event.basis}]`);
+        for (const caveat of result.caveats) out(`caveat ${caveat.code}: ${caveat.note}`);
+        for (const note of result.notes) out(`note: ${note}`);
+        return 0;
+      }
+      if (command === 'import') {
+        const file = args._[2];
+        if (!file) { err('agentlinkops context ga4 import FILE'); return 2; }
+        const result = await importGa4Handoff({ paths, file });
+        if (result.error) { err(result.error); return 2; }
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        out(`imported ${result.accepted} row(s) from connector(s): ${result.connectors.join(', ')}`);
+        for (const refused of result.refused.slice(0, 20)) out(`  refused row ${refused.row}: ${refused.reason}`);
+        return 0;
+      }
+      if (command === 'forget') {
+        const result = await forgetGa4Context({ paths });
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        for (const item of result.removed) out(`removed ${item.path}`);
+        for (const item of result.kept) out(`kept ${item.path} (${item.owner}-owned)`);
+        out(result.note);
+        return 0;
+      }
+      err(`unknown context ga4 command: ${command ?? '(none)'}\n\n${USAGE}`);
+      return 2;
+    }
+
+    if (area === 'business') {
+      const page = args._[1];
+      if (!page) { err('agentlinkops context business URL'); return 2; }
+      const gsc = await readGscRows(paths.gsc);
+      const ga4 = await readGa4Rows(paths.ga4);
+      const state = await readContextState(paths.contextState);
+      const manual = await readManual(paths.manual);
+      const window = args.start && args.end ? windowFromRange(args.start, args.end) : null;
+      const result = businessContextForPage({
+        gscRows: gsc.rows, ga4Rows: ga4.rows, page, window,
+        properties: state.connection?.properties ?? null, connection: state.connection ?? null,
+        ga4Connection: state.ga4 ?? null, manual,
+      });
+      if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+      out(`state: ${result.state}  relation: ${result.relation}`);
+      const search = result.layers.search, business = result.layers.business;
+      out(`search layer: ${search.state}${search.page_totals ? ` — clicks ${search.page_totals.clicks}, impressions ${search.page_totals.impressions}` : ''}`);
+      out(`business layer: ${business.state}${business.totals ? ` — sessions ${business.totals.sessions}, key events ${business.totals.key_events}` : ''}`);
+      for (const caveat of result.caveats) out(`caveat ${caveat.code}: ${caveat.note}`);
+      return 0;
+    }
+
+    if (area === 'profile') {
+      if (command === 'build') {
+        const result = await buildSiteProfile({
+          site: args.site === true ? null : (args.site ?? null),
+          paths, extraPages: args.page ?? [],
+        });
+        if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
+        out(`origin ${result.origin}: robots ${result.robots.outcome}${result.robots.reason ? ` (${result.robots.reason})` : ''}, ${result.sitemaps.documents} sitemap document(s), ${result.sitemaps.urls_found} URL(s)`);
+        out(`pages: ${result.pages.length} (cap ${result.limits.selected_pages}${result.limits.pages_capped ? ', CAPPED' : ''})`);
+        for (const page of result.pages) out(`  ${page.outcome === 'fetched' ? 'ok      ' : page.outcome.padEnd(8, ' ')}  ${page.url}${page.outcome !== 'fetched' ? `  [${page.reason}]` : ''}`);
+        out(`sitemap counters: failures ${JSON.stringify(result.sitemaps.failures)} skipped ${JSON.stringify(result.sitemaps.skipped)} truncated ${result.sitemaps.truncated}`);
+        for (const note of result.notes) out(`note: ${note}`);
+        return 0;
+      }
+      if (command === 'render') {
+        const { rows } = await readSiteFacts(paths.siteFacts);
+        if (!rows.length) { err(`no site facts at ${paths.siteFacts} — run \`agentlinkops context profile build\` first`); return 2; }
+        const manual = await readManual(paths.manual);
+        let existing = null;
+        try { existing = await readFile(paths.siteProfile, 'utf8'); } catch { /* absent is the normal first run */ }
+        if (existing && !args.force) {
+          err(`site-profile.md already exists at ${paths.siteProfile} and holds judgments; pass --force to regenerate (this discards edits)`);
+          return 2;
+        }
+        const origin = rows.find(row => row.kind === 'site.robots')?.url?.replace(/\/robots\.txt$/u, '') ?? null;
+        const markdown = renderSiteProfile({ facts: rows, manual, origin });
+        const { writeFile, mkdir } = await import('node:fs/promises');
+        const { dirname } = await import('node:path');
+        await mkdir(dirname(paths.siteProfile), { recursive: true });
+        await writeFile(paths.siteProfile, markdown, 'utf8');
+        const check = validateProfileCitations({ profileText: markdown, facts: rows, manual });
+        out(`wrote ${paths.siteProfile} (${check.citations} citation(s), ${check.unresolved.length} unresolved)${existing ? ' --force: previous judgments were replaced' : ''}`);
+        return 0;
+      }
+      if (command === 'check') {
+        let markdown;
+        try { markdown = await readFile(paths.siteProfile, 'utf8'); } catch { err(`no site-profile.md at ${paths.siteProfile}`); return 2; }
+        const { rows } = await readSiteFacts(paths.siteFacts);
+        const manual = await readManual(paths.manual);
+        const check = validateProfileCitations({ profileText: markdown, facts: rows, manual });
+        if (args.json) { out(JSON.stringify(check, null, 1)); return check.unresolved.length ? 1 : 0; }
+        out(`${check.citations} citation(s) checked, ${check.unresolved.length} unresolved`);
+        for (const ref of check.unresolved) out(`  UNRESOLVED ${ref}`);
+        out('facts are read-only to the profile: editing a judgment never edits a fact row');
+        return check.unresolved.length ? 1 : 0;
+      }
+      err(`unknown context profile command: ${command ?? '(none)'}\n\n${USAGE}`);
+      return 2;
+    }
+
+    err(`unknown context area: ${area}\n\n${USAGE}`);
+    return 2;
+  } catch (error) {
+    if (error instanceof ConfigError) { err(error.message); return 2; }
+    err(`agentlinkops context: ${error?.message ?? error}`);
+    return 2;
+  }
+}
+
+// Directly runnable: `node cli/context.js …`. Registration in cli/main.js (USAGE + dispatch)
+// and any MCP tool registration in src/mcp.js are the recorded follow-up for the next wave.
+const invokedDirectly = (() => {
+  try { return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href; } catch { return false; }
+})();
+if (invokedDirectly) {
+  contextMain().then(code => process.exit(code), error => { console.error(error); process.exit(2); });
+}