npm - @ainyc/canonry - Versions diffs - 4.190.1 → 4.192.0 - Mend

@ainyc/canonry 4.190.1 → 4.192.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/assets/index.html CHANGED Viewed

@@ -12,14 +12,14 @@
     <link rel="icon" type="image/png" sizes="32x32" href="./favicon-32.png" />
     <link rel="apple-touch-icon" href="./apple-touch-icon.png" />
     <title>Canonry</title>
-    <script type="module" crossorigin src="./assets/index-YVHujfy1.js"></script>
-    <link rel="modulepreload" crossorigin href="./assets/vendor-tanstack-CYBjbqVr.js">
-    <link rel="modulepreload" crossorigin href="./assets/vendor-radix-BpmvLvpp.js">
-    <link rel="modulepreload" crossorigin href="./assets/vendor-recharts-FA0uySU7.js">
-    <link rel="modulepreload" crossorigin href="./assets/vendor-lucide-dNHw1I5G.js">
-    <link rel="modulepreload" crossorigin href="./assets/vendor-markdown-9tTeP8v7.js">
+    <script type="module" crossorigin src="./assets/index-CCPMPGar.js"></script>
+    <link rel="modulepreload" crossorigin href="./assets/vendor-tanstack-ZXXkndVj.js">
+    <link rel="modulepreload" crossorigin href="./assets/vendor-radix-twS1M3FF.js">
+    <link rel="modulepreload" crossorigin href="./assets/vendor-recharts-D-cUuLZo.js">
+    <link rel="modulepreload" crossorigin href="./assets/vendor-lucide-CW2qe0uH.js">
+    <link rel="modulepreload" crossorigin href="./assets/vendor-markdown-B-Oq2NYq.js">
     <link rel="modulepreload" crossorigin href="./assets/vendor-yaml-GWJz5H2G.js">
-    <link rel="stylesheet" crossorigin href="./assets/index-BjjM151x.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-BtTEcbcB.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/{chunk-2II4ZMMH.js → chunk-32Q2NZ4S.js} RENAMED Viewed

@@ -5,11 +5,11 @@ import {
   installSkills,
   loadConfigRaw,
   saveConfigPatch
-} from "./chunk-32QBVRMN.js";
+} from "./chunk-36RKISAI.js";
 import {
   SKILL_MANIFEST_FILENAME,
   SkillsClients
-} from "./chunk-ROPJUNQN.js";
+} from "./chunk-BULKBROE.js";
 // src/skills-autosync.ts
 import fs from "fs";

package/dist/{chunk-32QBVRMN.js → chunk-36RKISAI.js} RENAMED Viewed

@@ -6,6 +6,7 @@ import {
   DISCOVERY_MAX_PROBES_CAP,
   DISCOVERY_PROBE_CONCURRENCY_CAP,
   GOOGLE_MARKETING_STORED_SNAPSHOT_PAGE_MAX,
+  RESEARCH_RUN_SCOPE,
   SKILL_MANIFEST_FILENAME,
   SkillsClients,
   adsActivateTreeRequestSchema,
@@ -36,6 +37,7 @@ import {
   gaMeasurementHostScopeSchema,
   googleAdsMetricsWindowSchema,
   gscPerformanceOrderBySchema,
+  isReadOnlyKey,
   keywordBatchRequestSchema,
   keywordGenerateRequestSchema,
   measurementChangesQuerySchema,
@@ -88,7 +90,9 @@ import {
   queryTrackingCommitRequestSchema,
   queryTrackingPreviewRequestSchema,
   reportPeriodSchema,
+  researchBatchCreateSchema,
   researchRunCreateSchema,
+  restrictedWriteScopes,
   resultsClearRequestSchema,
   runTriggerRequestSchema,
   schedulableRunKindSchema,
@@ -100,7 +104,7 @@ import {
   trafficEventKindSchema,
   trafficSeriesGranularitySchema,
   visibilityReportRequestSchema
-} from "./chunk-ROPJUNQN.js";
+} from "./chunk-BULKBROE.js";
 // src/cli-error.ts
 function isMachineFormat(format) {
@@ -2316,6 +2320,22 @@ var postApiV1ProjectsByNameResearchRuns = (options) => {
     }
   });
 };
+var postApiV1ProjectsByNameResearchBatches = (options) => {
+  return (options.client ?? client).post({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/v1/projects/{name}/research/batches",
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options.headers
+    }
+  });
+};
 var getApiV1ProjectsByNameQueryTracking = (options) => {
   return (options.client ?? client).get({
     security: [
@@ -8093,12 +8113,20 @@ var ApiClient = class {
       })
     );
   }
+  /** Atomically accept reviewed destinations with a shared retry identity. */
+  async startResearchBatch(project, request) {
+    return this.invoke(() => postApiV1ProjectsByNameResearchBatches({
+      client: this.heyClient,
+      path: { name: project },
+      body: request
+    }));
+  }
   async listResearchRuns(project, opts) {
     return this.invoke(
       () => getApiV1ProjectsByNameResearchRuns({
         client: this.heyClient,
         path: { name: project },
-        query: { limit: opts?.limit !== void 0 ? String(opts.limit) : void 0 }
+        query: { limit: opts?.limit !== void 0 ? String(opts.limit) : void 0, cursor: opts?.cursor }
       })
     );
   }
@@ -9557,7 +9585,12 @@ var researchRunStartInputSchema = z4.object({
 });
 var researchRunsListInputSchema = z4.object({
   project: projectNameSchema,
-  limit: z4.number().int().positive().max(100).optional().describe("Max saved research runs returned. Default 20.")
+  limit: z4.number().int().positive().max(100).optional().describe("Max saved research runs returned. Default 20."),
+  cursor: z4.string().min(1).optional().describe("Opaque cursor from the previous page.")
+});
+var researchBatchStartInputSchema = z4.object({
+  project: projectNameSchema,
+  request: researchBatchCreateSchema.describe("Reviewed concrete runs, at most 20 destinations and 50 total queries. Specify provider, model and location (null means none) for every run. Pin the plan revision for each market or Property. Reuse the same idempotencyKey and unchanged request after an uncertain response.")
 });
 var researchRunIdInputSchema = z4.object({
   project: projectNameSchema,
@@ -11501,6 +11534,7 @@ var canonryMcpTools = [
   }),
   defineTool({
     name: "canonry_research_run_start",
+    requiredScope: RESEARCH_RUN_SCOPE,
     title: "Start research query run",
     description: "Run final free-form queries once each against one API provider, with an optional exact model, location, or one configured market or Property destination. Scope never changes query text or fans out a group. Optional template provenance records the source template ID and version; callers must submit the fully expanded, editable final query text. Results retain that destination and provenance for later inspection. This does not add any query to the tracked basket or affect overview tracking.",
     access: "write",
@@ -11510,6 +11544,18 @@ var canonryMcpTools = [
     openApiOperations: ["POST /api/v1/projects/{name}/research/runs"],
     handler: (client2, input) => client2.startResearchRun(input.project, input.request)
   }),
+  defineTool({
+    name: "canonry_research_batch_start",
+    requiredScope: RESEARCH_RUN_SCOPE,
+    title: "Start reviewed research across destinations",
+    description: "Accept a reviewed research batch across explicit markets, Properties, or configured locations. Submit fully expanded, editable final queries with explicit provider/model/location for each destination; the API does not expand patterns or groups. All runs are saved together or none are saved, then processed independently. The required idempotencyKey prevents duplicate work on retries; changed input with the same key conflicts. Each run retains its scope, location and optional pattern provenance. Uses paid answer engines, never adds tracked queries or affects visibility measurements.",
+    access: "write",
+    tier: "discovery",
+    inputSchema: researchBatchStartInputSchema,
+    annotations: writeAnnotations({ idempotentHint: true, openWorldHint: true }),
+    openApiOperations: ["POST /api/v1/projects/{name}/research/batches"],
+    handler: (client2, input) => client2.startResearchBatch(input.project, input.request)
+  }),
   defineTool({
     name: "canonry_research_runs_list",
     title: "List research query runs",
@@ -11519,7 +11565,7 @@ var canonryMcpTools = [
     inputSchema: researchRunsListInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/research/runs"],
-    handler: (client2, input) => client2.listResearchRuns(input.project, input.limit === void 0 ? void 0 : { limit: input.limit })
+    handler: (client2, input) => client2.listResearchRuns(input.project, input.limit === void 0 && input.cursor === void 0 ? void 0 : { limit: input.limit, cursor: input.cursor })
   }),
   defineTool({
     name: "canonry_research_run_get",
@@ -12600,7 +12646,7 @@ var DynamicToolCatalog = class {
       loadedToolkits: [...this.loaded].sort(),
       coreTools: this.entries.filter((entry) => entry.tool.tier === "core").map((entry) => entry.tool.name),
       toolkits: CANONRY_MCP_TOOLKITS.map((toolkit) => this.toolkitEntry(toolkit)).filter((entry) => entry.toolCount > 0),
-      usage: "Call canonry_load_toolkit with one of the toolkit names listed in `toolkits[].name` to register its tools for the rest of this session. Wait for its response before calling any newly enabled tool."
+      usage: this.eager ? "All tools available on this connection are already loaded. Use their listed schemas; tool visibility does not grant server permissions." : "Call canonry_load_toolkit with one of the toolkit names listed in `toolkits[].name` to register its tools for the rest of this session. Wait for its response before calling any newly enabled tool."
     };
   }
   toolkitEntry(toolkit) {
@@ -12639,28 +12685,139 @@ var DynamicToolCatalog = class {
   }
 };
+// src/mcp/operations-guide.generated.ts
+var OPERATIONS_GUIDE = {
+  "guideVersion": "v1",
+  "operationsGuideUrl": "https://github.com/Canonry/canonry/blob/main/docs/agent-operations/v1.md",
+  "resourceUri": "canonry://agent-operations/v1",
+  "initialize": 'Canonry tracks how AI answer engines mention brands and cite domains.\nStart with canonry_help({intent:"status"}), or name your intended workflow. It returns a small route of currently available tools and approval boundaries. Follow its stored-evidence reads before proposing action. No skill, resource reader, plugin installation, or local CLI is required for connected MCP clients. A host-native Canonry skill, if installed, is optional additional guidance.\nmentioned = brand in answer TEXT; cited = domain in SOURCE links. Never compute one from the other. A null answerMentioned means not checked, not false. No recorded sweep means no measured figure.\nGet explicit approval for live provider reads, sweeps, probes, research, syncs, and writes, bounded to the target and requested work. A readOnlyHint or GET is not proof of a free operation. Live ads reads include canonry_ads_account, canonry_ads_geo_search, canonry_ads_live_delivery, canonry_ads_conversion_pixels, canonry_ads_conversion_event_settings. Google live reads/syncs include canonry_google_ads_customers, canonry_gtm_accounts, canonry_gtm_containers, canonry_gtm_workspaces, canonry_google_ads_sync, canonry_gtm_sync.\nHelp and skills grant no permissions. The server enforces authority. On missing tools or 403, report the boundary; do not switch credentials or endpoints to bypass it. Hosted catalogs are fixed; only use canonry_load_toolkit when help explicitly offers it.\n',
+  "approvalBoundary": [
+    "provider reads",
+    "sweeps",
+    "writes"
+  ],
+  "approvalRule": "Get explicit approval for the exact target, action, and bounded provider work before crossing a boundary. Existing approval covers only its stated scope; stop on refusal or ambiguous results.",
+  "authority": "Guidance and tool visibility are not permission grants. Server-side roles, scopes, project boundaries, quotas, and approval receipts remain authoritative. Never bypass a refusal with different credentials or endpoints.",
+  "workflows": {
+    "status": {
+      "keywords": [
+        "status",
+        "overview",
+        "health"
+      ],
+      "next": [
+        "canonry_projects_list",
+        "canonry_project_overview"
+      ],
+      "guidance": "Select an accessible project, then read its stored overview. Report freshness and missing evidence; do not start a sweep to fill a gap."
+    },
+    "diagnose": {
+      "keywords": [
+        "diagnose",
+        "diagnosis",
+        "regression",
+        "changed",
+        "change",
+        "troubleshoot"
+      ],
+      "next": [
+        "canonry_projects_list",
+        "canonry_project_overview",
+        "canonry_project_history"
+      ],
+      "guidance": "Compare stored history in the same project, period, provider/model, location, and query-class scope. Separate observed changes from possible causes; propose any live verification for approval."
+    },
+    "measurement": {
+      "keywords": [
+        "measurement",
+        "measure",
+        "portfolio",
+        "property",
+        "target",
+        "query",
+        "queries",
+        "research"
+      ],
+      "next": [
+        "canonry_projects_list",
+        "canonry_measurement_overview",
+        "canonry_measurement_setup",
+        "canonry_research_runs_list"
+      ],
+      "guidance": "Inspect existing measurement before editing it. Preserve Simple versus Advanced scope, Property/Target identity, market, provider/model, and query class. Direct research submits final queries in one context; reviewed batches submit explicit destinations under one retry key. Expand patterns client-side: scope records a destination and never rewrites queries or fans out a group. Research is separate from tracking; publication does not authorize a sweep."
+    },
+    "integrations": {
+      "keywords": [
+        "integrations",
+        "integration",
+        "connect",
+        "connection",
+        "traffic",
+        "gsc",
+        "ga4",
+        "ads",
+        "gtm"
+      ],
+      "next": [
+        "canonry_projects_list",
+        "canonry_project_get",
+        "canonry_ga_status",
+        "canonry_google_ads_status"
+      ],
+      "guidance": "Inspect stored connection status and snapshot freshness. Use the currently listed specialist tools for stored evidence. Connecting, selecting resources, syncing, and live provider reads require scoped approval; never request credentials in chat."
+    },
+    "reports": {
+      "keywords": [
+        "reports",
+        "report",
+        "reporting",
+        "summary"
+      ],
+      "next": [
+        "canonry_projects_list",
+        "canonry_report"
+      ],
+      "guidance": "Read the stored report for the selected project and period. Retain evidence dates, scope, sample sizes, missing data, and separate mention/citation signals; do not generate fresh runs implicitly."
+    }
+  },
+  "markdown": "# Canonry Operations Guide v1\n\nCanonry is an agent-first AI visibility platform. MCP is the universal entry\npoint for connected agents. Host-native skills are optional upgrades, not a\nprerequisite or a permission mechanism.\n\n## Connect and choose a route\n\nRead the initialization guidance, then call `canonry_help` with an `intent`:\n`status`, `diagnose`, `measurement`, `integrations`, `reports`, or a short task\ndescription. Select an accessible project with `canonry_projects_list` before\nusing its exact name in project tools. Inspect each listed tool's input schema;\nhelp suggests tool names, not invented arguments or authorization.\n\nHelp returns a versioned, compact route: connection `mode`, available `next`\ntools, workflow guidance, approval boundaries, and this guide's URL. It performs\nno provider calls, reads no project data, and changes no permissions.\n`includeCatalog: true` additionally returns toolkit details when needed.\n\nHosted connections use a fixed catalog. Help only suggests tools offered by that\nconnection; it never tells a hosted agent to dynamically load a toolkit. A\nprogressive local stdio connection may return `loadToolkits`: call\n`canonry_load_toolkit` with one returned name, await it, then call help again.\nLoading only changes local tool discovery, never server authority.\n\nThe optional `canonry://agent-operations/v1` MCP resource contains this same\nguide. If the host cannot read resources or open links, continue through help.\nDo not install a plugin, local runtime, or skill merely to use connected MCP.\nAn installed Codex or Claude Canonry skill contains a generated copy of this\nguide plus links to host-native references. It does not replace runtime help.\n\n## Vocabulary and evidence\n\n- **Mentioned** means the brand appears in answer text. **Cited** means its\n  domain appears in source links. Either, both, or neither can occur; never\n  compute one signal from the other.\n- `answerMentioned: null` means not checked, not false. Missing runs and empty\n  populations mean no measurement, not zero visibility.\n- Preserve project, time window, provider, requested/served model, location,\n  sample size, and query class when comparing evidence. Use server-returned\n  metrics; do not invent a score from incompatible populations.\n- Simple projects and Advanced portfolios share the workflow. For Advanced\n  results, preserve Property, Target, market, plan revision, and class scope.\n  Groups organize navigation; do not infer an unrequested fan-out.\n- Research is isolated evidence, not tracked measurement. A probe still spends\n  quota and persists evidence but is excluded from normal tracking metrics.\n\n## Workflows\n\n**Status:** read the stored overview and freshness first. Say when evidence is\nmissing instead of silently creating it.\n\n**Diagnose:** inspect stored history and comparable evidence. Explain what\nchanged separately from why it might have changed. A hypothesis is not a\nmeasured cause. Propose bounded verification if stored evidence is insufficient.\n\n**Measurement:** inspect the existing setup and results before proposing edits.\nKeep research, query tracking, plan publication, and sweep execution separate.\nFor direct research, submit the final editable query text in one context. For a\nreviewed batch, submit each explicit destination with its final text and one\nidempotency key. Pattern substitution happens in the client before either\nrequest; choosing a market or Property records a destination only and never\nrewrites a query or creates an automatic fan-out. `research.run` does not\nauthorize saving patterns, changing tracking, publishing plans, or settings.\nUse a supported preview where available, inspect its exact destination and\nrevision, then seek approval for the actual change. A preview may itself require\nwrite permission; never treat a dry-run flag as a universal safety guarantee.\n\n**Integrations:** inspect stored connection state and snapshot freshness first.\nProvider configuration evidence does not prove a browser event fired or a\nconversion was recorded. Connection, resource selection, refresh/sync, and live\nreads are separate actions. Credentials belong in the operator's secure setup\nflow, never in chat, tool arguments, reports, or public guidance.\n\n**Reports:** use saved evidence for the requested period and scope. Keep mention\nand citation signals separate, include dates and sample sizes, and state missing\nor stale inputs. Preparing a report does not authorize new measurement.\n\n## Authority and approval\n\nStart with stored evidence. Before a live provider read, sweep, probe, research\nrun, sync, write, or externally visible action, obtain approval covering its\nexact target, action, and bounded work. Approval already given for that exact\noperation need not be asked for again, but does not extend to more projects,\nlarger batches, retries with new identities, or recurring work.\n\nHTTP GET and MCP `readOnlyHint` describe aspects of an operation, not its cost\nor permission. Provider discovery, account reads, and live diagnostics may\nconsume quota even when labeled read-only. If the tool's effect is unclear,\ninspect its description and request direction before calling it.\n\nAuthentication, role/scope checks, project restrictions, quotas, and guarded\napproval receipts are enforced by the server. Help, skills, resources, and tool\nvisibility cannot grant authority. Never change credentials, endpoints, or\nproject identifiers to work around a missing tool or a `403` response.\n\nFor guarded ads writes, inspect unresolved operation receipts before retrying.\nUse the receipt's supported recovery action; do not replay a mutation under a\nnew identity. An executor cannot create or widen its own human approval grant.\nOn ambiguous results, exhausted bounds, or refusal, stop and report what is\nknown and what permission or operator action is needed.\n\n## Version and source\n\nThis public, versioned document is the source for initialization guidance,\nintent routes, the optional resource, and generated Canonry `SKILL.md` files.\nGuide v1 may receive compatible clarifications; incompatible routing contracts\nrequire a new guide version. The running server's help describes its actual\ncatalog and remains usable without fetching this document.\n"
+};
+// src/mcp/operations-guide.ts
+function operationsHelp(catalog, mode, intent = "", includeCatalog = false) {
+  const workflows = Object.keys(OPERATIONS_GUIDE.workflows);
+  const words = new Set(intent.toLowerCase().split(/[^a-z0-9-]+/));
+  const workflow = workflows.find((name) => OPERATIONS_GUIDE.workflows[name].keywords.some((word) => words.has(word))) ?? "status";
+  const route = OPERATIONS_GUIDE.workflows[workflow];
+  const available = /* @__PURE__ */ new Set([...catalog.coreTools, ...catalog.toolkits.filter((t) => t.loaded).flatMap((t) => t.tools)]);
+  const next = route.next.filter((name) => available.has(name)).slice(0, 4);
+  if (next.length < 2 && available.has("canonry_project_overview") && !next.includes("canonry_project_overview")) {
+    next.push("canonry_project_overview");
+  }
+  const wanted = route.next;
+  const loadToolkits = mode === "stdio-progressive" ? catalog.toolkits.filter((t) => !t.loaded && t.tools.some((name) => wanted.includes(name))).map((t) => t.name) : [];
+  return {
+    guideVersion: OPERATIONS_GUIDE.guideVersion,
+    mode,
+    scope: catalog.scope,
+    workflow,
+    next,
+    workflows,
+    guidance: route.guidance,
+    approvalBoundary: OPERATIONS_GUIDE.approvalBoundary,
+    approvalRule: OPERATIONS_GUIDE.approvalRule,
+    authority: OPERATIONS_GUIDE.authority,
+    operationsGuideUrl: OPERATIONS_GUIDE.operationsGuideUrl,
+    ...loadToolkits.length ? { loadToolkits } : {},
+    ...includeCatalog ? catalog : {}
+  };
+}
 // src/mcp/server.ts
 function createCanonryMcpServer(options = {}) {
   return createCanonryMcpServerWithCatalog(options).server;
 }
-var SERVER_INSTRUCTIONS = `Canonry tracks how AI answer engines mention a brand and cite a domain.
-Load the "canonry" skill before operator work (project setup, integrations, traffic sources, sweeps, diagnosis). It carries the procedures and the failure modes; this text is only a pointer. Use "aero" for analyst work: regression diagnosis, reporting.
-Two signals, never interchangeable:
-- mentioned = the brand appears in the answer TEXT the model wrote.
-- cited = the domain appears in the SOURCE links behind the answer.
-A model can do either, both or neither. Never compute one from the other, and never report a number for one under the other's name.
-Sweeps, probes, and research runs spend provider quota and write rows. Get explicit approval before any run, apply, or other mutation.
-Most reads are free. Five ads reads are NOT: canonry_ads_account, canonry_ads_geo_search, canonry_ads_live_delivery, canonry_ads_conversion_pixels and canonry_ads_conversion_event_settings call the provider live and spend against the advertiser account. They are marked read, so nothing in the tool list warns you. Get approval for those exactly as for a mutation.
-Google Marketing also calls providers live. Get approval before canonry_google_ads_customers, canonry_gtm_accounts, canonry_gtm_containers, canonry_gtm_workspaces, canonry_google_ads_sync or canonry_gtm_sync.
-A null answerMentioned means NOT CHECKED, not "not mentioned". Never coerce it to false.
-If no sweep has run, say so. Never state a mention or citation figure that no run produced.`;
+var SERVER_INSTRUCTIONS = OPERATIONS_GUIDE.initialize;
 function createCanonryMcpServerWithCatalog(options = {}) {
   const clientFactory = options.clientFactory ?? createApiClient;
   const client2 = clientFactory();
@@ -12673,7 +12830,7 @@ function createCanonryMcpServerWithCatalog(options = {}) {
   });
   server.validateToolInput = async (_tool, args) => args;
   const entries = [];
-  for (const registryTool of getCanonryMcpTools(scope, options.tiers)) {
+  for (const registryTool of getCanonryMcpTools(scope, options.tiers, options.credentialScopes)) {
     const tool = registryTool;
     const handler = tool.handler;
     const registered = server.registerTool(
@@ -12694,22 +12851,40 @@ function createCanonryMcpServerWithCatalog(options = {}) {
   const eager = options.eager === true || options.tiers !== void 0;
   const catalog = new DynamicToolCatalog(server, entries, scope, { eager });
   catalog.applyInitialEnablement();
-  registerMetaTools(server, catalog, { includeToolkitLoader: options.tiers === void 0 });
+  const mode = options.tiers !== void 0 ? "hosted-fixed-catalog" : eager ? "stdio-fixed-catalog" : "stdio-progressive";
+  registerMetaTools(server, catalog, { includeToolkitLoader: options.tiers === void 0, mode });
+  server.registerResource("canonry-agent-operations-v1", OPERATIONS_GUIDE.resourceUri, {
+    title: "Canonry Operations Guide v1",
+    description: "Optional public operations guidance. Use canonry_help when resources are unavailable.",
+    mimeType: "text/markdown"
+  }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: OPERATIONS_GUIDE.markdown }] }));
   return { server, catalog };
 }
 var loadToolkitInputSchema = z5.object({
   name: z5.enum(CANONRY_MCP_TOOLKIT_NAMES).describe("Toolkit name. List options with canonry_help.")
 });
+var helpInputSchema = z5.object({
+  intent: z5.string().max(200).optional().describe("Workflow (status, diagnose, measurement, integrations, reports) or a short task description."),
+  includeCatalog: z5.boolean().optional().describe("Include full toolkit details. Omit for a compact, actionable route.")
+});
 function registerMetaTools(server, catalog, opts) {
   server.registerTool(
     "canonry_help",
     {
-      title: "List Canonry MCP toolkits",
-      description: "List available toolkits and which are loaded. Call before canonry_load_toolkit if unsure which to load.",
-      inputSchema: {},
-      annotations: { readOnlyHint: true }
+      title: "Guide a Canonry workflow",
+      description: "Start here: route an intent to available stored-evidence tools, workflow guidance, and approval boundaries. No provider calls or installation required. Optionally include full toolkit details.",
+      inputSchema: helpInputSchema.shape,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    async () => withToolErrors(async () => catalog.helpResult())
+    async (input) => {
+      try {
+        const parsed = helpInputSchema.parse(input ?? {});
+        const result = operationsHelp(catalog.helpResult(), opts.mode, parsed.intent, parsed.includeCatalog);
+        return { ...jsonToolResult(result), structuredContent: result };
+      } catch (error) {
+        return errorToolResult(error);
+      }
+    }
   );
   if (!opts.includeToolkitLoader) return;
   server.registerTool(
@@ -12726,8 +12901,14 @@ function registerMetaTools(server, catalog, opts) {
     })
   );
 }
-function getCanonryMcpTools(scope = "all", tiers) {
-  const byScope = scope === "read-only" ? canonryMcpTools.filter((tool) => tool.access === "read") : [...canonryMcpTools];
+function getCanonryMcpTools(scope = "all", tiers, credentialScopes) {
+  const readOnly = scope === "read-only" || credentialScopes !== void 0 && isReadOnlyKey(credentialScopes);
+  const restricted = credentialScopes && restrictedWriteScopes(credentialScopes);
+  const byScope = readOnly ? canonryMcpTools.filter((tool) => tool.access === "read") : canonryMcpTools.filter((tool) => {
+    if (!restricted || tool.access === "read") return true;
+    if (tool.requiredScope && restricted.includes(tool.requiredScope)) return true;
+    return restricted.some((grant) => grant !== RESEARCH_RUN_SCOPE) && tool.tier === "ads";
+  });
   if (!tiers) return byScope;
   const wanted = new Set(tiers);
   return byScope.filter((tool) => wanted.has(tool.tier));