@zackbart/connecta 0.12.1 → 0.13.0

package/dist/skills.js

@@ -1,5 +1,5 @@
-export const CONNECTA_INSTRUCTIONS = 'Connecta exposes integrations behind seven meta-tools, and execute_code is the primary one: write an async arrow function and use connecta.search (empty query browses every catalog), connecta.describe, connecta.call, and connecta.batch inside it for discovery, two or more calls, dependent steps, loops, joins, and reducing large results before they reach you. For a single read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than through a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
-export const USAGE_SKILL = `# Connecta usage
+export const CONNECTA_INSTRUCTIONS = 'Connecta exposes seven meta-tools. For one read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than a program. For read-only reduction, multiple or dependent calls, loops, joins, or branches, do not call top-level search_tools: make one execute_code call whose program searches, selects, calls, and reduces; never return discovery for another call. connecta.ui(html) is a guest function inside execute_code, never a connector address or search_tools result; pass one HTML string for display-only, or bind named read-only refresh/drill-down calls in its optional reads argument, and return the same initial summary data the HTML renders. Unannotated, write-capable, or destructive tools stay top level: search_tools, then call_destructive_tool; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
+const USAGE_SKILL_BASE = `# Connecta usage
 
 ## The surface
 
@@ -19,7 +19,7 @@ Use exact addresses from discovery; never invent one. Search 2–4 distinctive a
 
 One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the \`connecta\` functions, and \`console.log\`.
 
-- \`connecta.search({})\` browses every catalog; \`safety: "readOnly"\` narrows to calls a program can execute, \`connector: "<id>"\` to one. This filters results, not authority; matches carry \`address\` and annotations.
+- \`connecta.search({})\` loads all catalogs; pass \`connector: "<id>"\` when obvious to load one. \`safety: "readOnly"\` keeps executable calls. Neither grants authority. Matches carry \`address\` and annotations.
 - Exact schemas: \`connecta.describe({ address: "connector.tool" })\` for one, \`{ addresses: [...] }\` for many; \`format: "json"\` only for exact constraints.
 - Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\` — how a program tells a policy refusal from a transient failure.
 - Search inside the run, not before it; return only the reduction the answer needs, never raw payloads.
@@ -27,19 +27,17 @@ One async arrow function. The only capabilities are one global per connector (\`
 
 ## Rendering a view
 
-\`connecta.ui(html)\` renders one view per successful run for the client, never for the model. Fetch first, check the shape in code. On a surprise — empty array, missing key — return a trimmed first record instead of rendering: the wrong view becomes the sample you needed. Otherwise render from the variables you return; the model reads the return value, not the view.
+\`connecta.ui(html)\` renders a display-only view on success for the client, never for the model. Fetch first, check the shape in code. On a surprise — empty array, missing key — return a trimmed first record instead of rendering: the wrong view becomes the sample you needed. Otherwise render from the variables you return; the model reads the return value, not the view.
+
 `;
-/**
- * Appended to USAGE_SKILL only when the deployment actually has at least one
- * connector guide. A deployment with none — every deployment that has not
- * adopted the feature — keeps the base guide byte-for-byte, rather than paying
- * context for an instruction to fetch guides that do not exist.
- */
-export const CONNECTOR_GUIDES_SECTION = `
+/** Deployment-scoped guide routing appended to the shared usage guide. */
+const CONNECTOR_GUIDES_SECTION = `
 ## Per-connector guides
 
-Some connectors here ship their own usage guide — preferred tools, address quirks, pagination conventions, rate-limit etiquette, query patterns. \`skills({})\` lists each one as \`connector:<connectorId>\`; fetch it with \`skills({ name: "connector:<connectorId>" })\`. \`search_tools\`, \`connecta.search\`, and \`connecta.describe\` set \`guide\` on matches whose connector has one. Read a connector's guide before working with it for the first time in a task.
+When a connector here ships a deployment-scoped usage guide, \`skills({})\` and discovery return the exact \`guide\` name plus a bounded \`guideSummary\` saying what it covers. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop: fetch before calling. \`guideRequiredReasons\` says why — \`connector_required\` and \`approval_required\` stand however you expand the schema; \`schema_truncated\` clears once describe returns the exact one. Otherwise fetch when the summary names a connector-specific sequence, unit, pagination rule, alias, or generic API convention relevant to the task. A read-only call whose compact schema is complete and unambiguous may proceed without fetching an otherwise irrelevant guide. Connector guides do not replace the shared Connecta usage guide and never apply to another deployment implicitly.
 `;
+/** Shared Connecta routing guidance, byte-identical across deployments. */
+export const USAGE_SKILL = USAGE_SKILL_BASE + CONNECTOR_GUIDES_SECTION;
 /** The always-loaded MCP `instructions` string. */
 export function instructionsFor() {
     return CONNECTA_INSTRUCTIONS;
@@ -48,11 +46,14 @@ export function instructionsFor() {
 export function hasConnectorGuides(connectors) {
     return connectors.some((connector) => connectorGuide(connector) !== undefined);
 }
-/** The built-in usage guide, plus the guides section when there is one to point at. */
-function usageSkill(connectors) {
-    if (!hasConnectorGuides(connectors))
-        return USAGE_SKILL;
-    return USAGE_SKILL + CONNECTOR_GUIDES_SECTION;
+/**
+ * The built-in usage guide is byte-identical across deployments, so an agent
+ * that has read it once in a task never needs an equivalent deployment-local
+ * copy. Guide-free deployments still pay no fixed tool-description cost: the
+ * conditional notes in meta-tools.ts remain absent.
+ */
+function usageSkill(_connectors) {
+    return USAGE_SKILL;
 }
 const AVAILABLE_SKILLS = [
     {
@@ -76,7 +77,8 @@ export function connectorSkillName(connectorId) {
 /** The connector's guide, or undefined when it declares none (or a blank one). */
 export function connectorGuide(connector) {
     const guide = connector.usageGuide;
-    return guide && guide.trim() !== "" ? guide : undefined;
+    const content = typeof guide === "string" ? guide : guide?.content;
+    return content && content.trim() !== "" ? content : undefined;
 }
 const SUMMARY_LENGTH = 120;
 /** A `---`/`***`/`___` rule, which also opens and closes YAML frontmatter. */
@@ -106,8 +108,17 @@ function withoutFrontmatter(lines) {
  * the connector's own description when the guide opens with nothing but
  * markup.
  */
+function boundedSummary(summary) {
+    const line = summary.replace(/\s+/g, " ").trim();
+    if (line === "")
+        return undefined;
+    return line.length <= SUMMARY_LENGTH
+        ? line
+        : `${line.slice(0, SUMMARY_LENGTH - 1).trimEnd()}…`;
+}
 function summarizeGuide(connector, guide) {
     let inFence = false;
+    let headingFallback;
     for (const raw of withoutFrontmatter(guide.split("\n"))) {
         if (FENCE_RE.test(raw)) {
             inFence = !inFence;
@@ -117,6 +128,7 @@ function summarizeGuide(connector, guide) {
             continue;
         if (raw.trim() === "" || NOT_SUMMARY_RE.test(raw))
             continue;
+        const heading = /^\s*#{1,6}/.test(raw);
         const line = raw
             // `\s*` (not `\s+`) so a bare `#` strips to nothing and is skipped, and
             // an unspaced `#Heading` is still read as a heading.
@@ -126,11 +138,32 @@ function summarizeGuide(connector, guide) {
             .trim();
         if (line === "")
             continue;
-        return line.length <= SUMMARY_LENGTH
-            ? line
-            : `${line.slice(0, SUMMARY_LENGTH - 1).trimEnd()}…`;
+        if (heading) {
+            headingFallback ??= boundedSummary(line);
+            continue;
+        }
+        return boundedSummary(line) ?? line;
     }
-    return connector.description ?? `Usage guide for "${connector.id}".`;
+    if (headingFallback)
+        return headingFallback;
+    const fallback = connector.description ?? `Usage guide for "${connector.id}".`;
+    return boundedSummary(fallback) ?? `Usage guide for "${connector.id}".`;
+}
+/** Bounded, decision-useful discovery summary for a connector guide. */
+export function connectorGuideSummary(connector) {
+    const guide = connectorGuide(connector);
+    if (!guide)
+        return undefined;
+    const configured = typeof connector.usageGuide === "object"
+        ? boundedSummary(connector.usageGuide.summary ?? "")
+        : undefined;
+    return configured ?? summarizeGuide(connector, guide);
+}
+/** Whether correct use always depends on conventions outside the tool schema. */
+export function connectorGuideRequired(connector) {
+    return (connectorGuide(connector) !== undefined &&
+        typeof connector.usageGuide === "object" &&
+        connector.usageGuide.required === true);
 }
 /**
  * Every fetchable skill: the built-in guides plus one entry per connector that
@@ -143,12 +176,14 @@ export function listSkills(connectors) {
         description: skill.description,
     }));
     for (const connector of connectors) {
-        const guide = connectorGuide(connector);
-        if (!guide)
+        // Undefined here means "no guide" and nothing else: a connector that has
+        // one always summarizes to a non-empty line, configured or derived.
+        const summary = connectorGuideSummary(connector);
+        if (!summary)
             continue;
         listing.push({
             name: connectorSkillName(connector.id),
-            description: summarizeGuide(connector, guide),
+            description: summary,
         });
     }
     return listing;

package/dist/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -189,13 +189,17 @@ export interface Connector {
      */
     callAdmission?: ConnectorCallAdmissionPolicy;
     /**
-     * Optional agent-facing usage guide (markdown) for this connector — preferred
-     * tools, address quirks, pagination conventions, rate-limit etiquette, good
-     * query patterns. Listed by the `skills` meta-tool as `connector:<id>` and
-     * returned verbatim by `skills({ name: "connector:<id>" })`. Keep it concise
-     * and imperative; it is read by agents, not operators.
+     * Optional agent-facing usage guide for this connector. A string preserves
+     * the original markdown-only contract. The structured form can add a short
+     * discovery summary and require review when even a complete compact schema
+     * cannot describe correct use (for example a generic API wrapper or a
+     * cross-operation sequencing rule).
+     *
+     * Listed by `skills` as `connector:<id>` and returned verbatim by
+     * `skills({ name: "connector:<id>" })`. The guide remains deployment-owned
+     * configuration; no runtime registration or shared mutable copy exists.
      */
-    usageGuide?: string;
+    usageGuide?: string | ConnectorUsageGuide;
     /** Optional operator-managed credential slot rendered on /credentials. */
     credential?: ConnectorCredentialConfig;
     /** Optional server-side check used by /credentials' Test action. */
@@ -267,6 +271,22 @@ export interface Connector {
      */
     handleRequest?(request: Request, ctx: ConnectorContext): Promise<Response | null>;
 }
+export interface ConnectorUsageGuide {
+    /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
+    content: string;
+    /**
+     * Bounded discovery hint describing the conventions the guide covers. When
+     * omitted, Connecta derives a summary from the guide's first meaningful line.
+     */
+    summary?: string;
+    /**
+     * Require review before every operation on this connector. Reserve this for
+     * cases whose correct arguments or sequence cannot be expressed by the
+     * downstream tool schema; mutations and truncated schemas are required
+     * automatically and do not need this flag.
+     */
+    required?: boolean;
+}
 /** Result of one sandboxed code execution. */
 export interface ExecuteResult {
     result: unknown;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,sDAAsD;AACtD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;;OAGG;IACH,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,oEAAoE;IACpE,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,MAAM,WAAW,eAAgB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,6EAA6E;AAC7E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,oEAAoE;AACpE,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,gBAAgB,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,MAAM,CAAC,EAAE,4BAA4B,CAAC;IACtC;;;;OAIG;IACH,YAAY,CAAC,CACX,KAAK,EAAE,QAAQ,CAAC,2BAA2B,CAAC,GAC3C,MAAM,CAAC;CACX;AAED,2EAA2E;AAC3E,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,KAAK,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC7C,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/D,qEAAqE;AACrE,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,yEAAyE;IACzE,MAAM,IAAI,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;CACrD;AAED,iEAAiE;AACjE,MAAM,WAAW,8BAA8B;IAC7C,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;CAC3C;AAED,2EAA2E;AAC3E,MAAM,WAAW,yBAAyB;IACxC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,8BAA8B,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,OAAO,EAAE,SAAS,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,KAAK,oBAAoB,GAAG,IAAI,GAAG,eAAe,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,oBAAoB,CAAC;IAC5B,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,4BAA4B,CAAC;IAC7C;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAAC;IAC1C,0EAA0E;IAC1E,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,oEAAoE;IACpE,cAAc,CAAC,CACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC,+EAA+E;IAC/E,eAAe,CAAC,CACd,MAAM,EAAE,yBAAyB,EACjC,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACrD,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,uEAAuE;IACvE,MAAM,CAAC,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACzD;;;;;OAKG;IACH,SAAS,CAAC,CACR,GAAG,EAAE,gBAAgB,EACrB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GACzB,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5B;;;;OAIG;IACH,cAAc,CAAC,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E;;;;OAIG;IACH,UAAU,CAAC,CACT,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,gBAAgB,EACrB,cAAc,CAAC,EAAE,eAAe,GAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,CACZ,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7E,uEAAuE;IACvE,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACpE,sEAAsE;IACtE,iBAAiB,CAAC,IAAI,iBAAiB,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7E,2EAA2E;IAC3E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,uCAAuC;AACvC,MAAM,MAAM,UAAU,GAClB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEtC,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,UAAU,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,kBAAkB,CAAC,CACjB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACpD;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,+EAA+E;IAC/E,cAAc,CAAC,CACb,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,GACd,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC9C,sCAAsC;IACtC,SAAS,CACP,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,GACd,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACrC"}

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.12.1";
+export declare const CONNECTA_VERSION = "0.13.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.12.1";
+export const CONNECTA_VERSION = "0.13.0";
 //# sourceMappingURL=version.js.map

package/documentation/code-mode.md

@@ -209,7 +209,7 @@ documented functions as the whole surface.
 ```js
 const page = await connecta.search({
   query: "pipeline run job logs",   // 2–4 distinctive action/object terms
-  connector: "ci",                  // optional single-connector filter
+  connector: "ci",                  // load one obvious connector, not every catalog
   safety: "readOnly",               // or "approvalRequired" / "all"
   limit: 8,                         // 1–100, default 8
   offset: 0,
@@ -221,12 +221,12 @@ const page = await connecta.search({
 
 **S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Each entry in `tools` carries `address`, `name`, and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes; capped shapes remain structurally valid with `unknown` types plus `/* truncated */`, and carry `inputSchemaTruncated` or `outputSchemaTruncated`. Use `connecta.describe` (or JSON search) for omitted exact constraints.
 
-**S1a.** `safety: "readOnly"` returns exactly the tools available through `connecta.call`, connector shortcuts, and `connecta.batch`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. This filters rows only: it grants no authority and changes no admission decision.
+**S1a.** `connector` loads only the named catalog; omit it only when the integration is ambiguous, because an unscoped search fans out across every configured connector. `safety: "readOnly"` returns exactly the tools available through `connecta.call`, connector shortcuts, and `connecta.batch`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. These filters grant no authority and change no admission decision.
 
-**S2.** With schemas requested, a match whose input (or output) schema resolves
-to an object shape also carries `inputKeys`, `requiredInputKeys`, and
-`outputKeys`: the same names the rendered schema shows, ready to check before
-building arguments. A schema that is not an object shape — a union, an array, an
+**S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`, and `outputKeys`:
+the same names the rendered schema shows, ready to check before
+building arguments. Match inputs, truncation, safety, and outputs, not lexical
+rank; search distinct operations separately and use `outputKeys`, not guessed roots. A non-object schema — a union, an array, an
 unresolvable `$ref` — carries no lists rather than empty ones, because absent
 means "read the schema" where `[]` would claim the tool takes no fields. The
 lists come from the same walk that renders the compact schema, so a top-level
@@ -503,10 +503,9 @@ the security posture live in the [design record](./mcp-ui-design.md)
 [#277](https://github.com/zackbart/connecta/issues/277)); this section is the
 contract, and it wins where the two disagree.
 
-**U1.** `connecta.ui(html)` accepts exactly one argument: a non-empty string of
-HTML. A non-string, an empty string, an options bag, or an MCP block object
-throws catchably and nothing is accepted. There is no options parameter and no
-sugar form, for `M1`'s reason: sugar is how a one-shape contract grows hair.
+**U1.** `connecta.ui(html, options?)` accepts one non-empty HTML string and at
+most the bounded read manifest `V1` defines. The one-argument call stays
+display-only; every other shape throws catchably and accepts nothing.
 
 **U2.** At most one payload per run. A second call throws catchably, naming the
 constraint; the first accepted payload stands. One tool result renders one view,
@@ -514,7 +513,7 @@ and last-wins would silently discard a payload the program deliberately
 supplied.
 
 **U3.** Delivered on success only, and out of model context: the tool result
-gains `_meta["connecta/ui"] = { html }` and the JSON envelope gains `ui: true`,
+gains `_meta["connecta/ui"] = { html, reads? }` and the JSON envelope gains `ui: true`,
 so the model learns a view rendered without seeing its bytes. `structuredContent`
 stays the envelope alone. The single-label `connecta/ui` prefix is deliberate —
 connecta has no domain to reverse, and fabricating one to satisfy MCP's
@@ -527,27 +526,27 @@ with `emittedDiscarded: N` when one failure discards both.
 
 **U4.** The payload spends the aggregate emit byte budget
 (`ConnectaConfig.execute.maxEmittedBytes`), measured at the call as the
-serialized bytes of `{ html }` — `M5`'s measurement. Over budget throws
+serialized bytes of `{ html, reads? }` — `M5`'s measurement. Over budget throws
 catchably, naming the budget and the room remaining, with nothing partially
 accepted. It spends no block count (`maxEmittedBlocks`: it is not a block) and no
 host-call budget (`L4`). One transport bound covers everything rich a program
 delivers.
 
 **U5.** One static shell: a connecta-authored HTML5 document at
-`ui://connecta/program-ui/v1`, mimeType `text/html;profile=mcp-app`, declared on
+`ui://connecta/program-ui/v2`, mimeType `text/html;profile=mcp-app`, declared on
 `execute_code` via `_meta.ui.resourceUri` together with an explicit
-`_meta.ui.visibility: ["model"]` — the default `["model","app"]` would tell hosts
-the view may call `execute_code`. A `resources/read` handler answers exactly that
+`_meta.ui.visibility: ["model"]`. Only `call_tool` declares app visibility; all
+other tools say model-only. A `resources/read` handler answers exactly that
 URI and fails on any other; `resources/list` is served and returns an empty list.
 The version segment bumps whenever the shell's bytes change, because hosts cache
 templates by URI.
 
-**U6.** The shell is display-only. It renders the payload in a nested iframe
+**U6.** The shell renders the payload in a nested iframe
 (`srcdoc`, `sandbox="allow-scripts"`, no `allow-same-origin`) and declares no CSP
 domains, so the host applies its restrictive default and the `about:srcdoc` frame
-inherits `default-src 'none'; connect-src 'none'`. Program UI gets scripts and
-local interactivity and nothing else: no network, no tool calls, no conversation
-messages, no host-mediated links. The shell participates in the Apps lifecycle —
+inherits `default-src 'none'; connect-src 'none'`. One argument stays display-only;
+a `V1` manifest installs only named `connecta.read`, with no direct network, raw
+tool calls, discovery, conversation, writes, or links. The shell participates in the Apps lifecycle —
 initialize, tool-result, size-changed, resource-teardown — and forwards no
 channel whatsoever from the inner frame to the host. That isolation makes
 program views fixed-height by construction: with no bridge there is no
@@ -583,13 +582,25 @@ declaration in order to register tool metadata conditionally stays refused
 
 **U12.** The return value, not the view, is what the model reads. `U3` puts the
 view out of model context, so a program that renders one also returns the summary
-the model should reason over, built from the same variables the view renders — a
+the model should reason over, built from the same variables the initial view renders — a
 view the return value does not mirror is a view nobody in the loop can check.
 This binds program authors and nothing else: connecta never reads the HTML, diffs
 it against the return, or enforces the correspondence. A heuristic there would be
 the same mistake as automatic host-side projection, refused in `ethos.md`
 ([#282](https://github.com/zackbart/connecta/issues/282)).
 
+**U13.** The always-loaded MCP instructions locate `connecta.ui(html)` before an
+agent chooses a route: it is a guest function inside `execute_code`, never a
+connector address or catalog result, takes one HTML string, and carries `U12`'s
+mirrored-return duty. The detailed tool description proved too late to stop cold
+agents from searching downstream catalogs for UI; the location distinction
+therefore rides `initialize`, under a 1,000-character ceiling for the complete
+instructions string. This promotes existing contract, not capability: the
+seven-tool surface, guest API, catalog, Apps delivery, and runtime do not change
+([#286](https://github.com/zackbart/connecta/issues/286)).
+
+Bounded view reads follow normative [`V1`–`V8`](./program-ui-read-calls.md) ([#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)).
+
 ## Retry semantics
 
 **Y1.** Connecta retries nothing beneath a program. `call_tool` accepts an
@@ -872,6 +883,7 @@ the upstream `Executor` shape assignable.
 | `U7`, `U8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `U9` | `test/execute-ui.test.ts` (a `ui` byte aggregate distinct from `emitted`, absent when nothing was accepted) |
 | `U12` | `test/server.test.ts` (the `connecta.ui` bullet carries the return-value clause); a duty on program authors, so the description is the only place it can be enforced |
+| `U13` | `test/code-first-surface.test.ts`, `test/server.test.ts` (served `initialize.instructions` locate UI inside `execute_code`, exclude it from catalog search, state the one-string call and mirrored return, and stay within the complete 1,000-character budget) |
 | `X3` | `test/quickjs-executor.test.ts` (cancels a running child) |
 | `X4` | `test/guest-api-contract.test.ts` (string logs only) |
 | `X6` | `test/quickjs-executor.test.ts` (never-settling await) |

package/documentation/connectors.md

@@ -1,15 +1,116 @@
 # Connectors
 
 Connectors are the boundary between Connecta's fixed meta-tool surface and
-downstream capabilities. `api()` defines a deliberate HTTP API surface;
-`remoteMcp()` aggregates another MCP endpoint. Both publish the same tool
-definitions and pass through the same catalog, read-only admission, invocation,
-result-size, and activity paths.
+downstream capabilities. Prefer a prebuilt connection when Connecta maintains
+one for the provider. Use `api()` to define a deliberate HTTP API surface and
+`remoteMcp()` to aggregate any other MCP endpoint. All three authoring paths
+produce ordinary `Connector` instances and pass through the same catalog,
+read-only admission, credentials, storage, invocation, result-size, and
+activity paths.
 
 Connector instances are deployment configuration. They are not registered or
 reconfigured at runtime. Request-local clients, transports, abort signals, and
 catalogs must be released with the request that created them.
 
+## Prebuilt connections
+
+A prebuilt connection is an independently imported provider constructor, not a
+registry or a second connector interface. It packages behavior Connecta can
+maintain universally: provider endpoints and authentication defaults, tool
+definitions or downstream catalog behavior, schemas and annotations, lean
+result shapes, typed errors, pagination and retry conventions, and a short
+usage guide where schemas cannot carry the advice.
+
+The deployment still supplies the account-specific identity and policy:
+
+- a unique connector `id`, which owns its address, storage, credential,
+  catalog, admission, and activity namespaces;
+- a human-readable `title` and a concrete `purpose` or audience;
+- supported authentication overrides; and
+- account-specific instructions appended to, rather than replacing, the safe
+  provider guidance.
+
+Imports and registration stay explicit and a la carte:
+
+```ts
+import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
+
+const analytics = mixpanel("product_analytics", {
+  title: "Product analytics",
+  purpose: "Production product decisions for the growth team",
+});
+```
+
+The constructor may use `remoteMcp()` or `api()` internally. Callers should not
+need to care which transport gives the better agent-facing surface, and the
+choice does not grant the connection different runtime privileges. Two
+instances of the same provider are isolated in exactly the same way as two
+hand-written connectors with different ids.
+
+A prebuilt connection's vetted annotations are fill-in only. They classify what
+the downstream leaves unannotated and may always tighten a classification; they
+never overrule an explicit downstream `destructiveHint: true` or
+`readOnlyHint: false`. The fail-closed read-only invariant is unchanged by the
+authoring path.
+
+Prebuilt means preferred when available, not mandatory. A deployment may mix
+prebuilt connections, custom `remoteMcp()` connections, and custom `api()`
+connections. Connecta makes no completeness promise: providers without a
+maintained prebuilt connection continue to use the public primitives without
+loss of support.
+
+```ts
+import { createConnecta, remoteMcp, api } from "@zackbart/connecta";
+import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
+import { quickJsExecutor } from "@zackbart/connecta/quickjs";
+
+export const connecta = createConnecta({
+  executor: quickJsExecutor(),
+  connectors: [
+    // Maintained prebuilt connection.
+    mixpanel("product_analytics", {
+      purpose: "Production product decisions for the growth team",
+    }),
+    // Custom downstream MCP server, no prebuilt connection needed.
+    remoteMcp("linear", {
+      url: "https://mcp.linear.app/mcp",
+      description: "Issue tracking for the platform team",
+    }),
+    // Deliberate in-house HTTP surface, hand-written tool by hand-written tool.
+    api("billing", {
+      description: "Internal billing reads",
+      credential: { label: "Billing API token" },
+      tools: [
+        {
+          name: "get_invoice",
+          description: "Fetch one invoice by id.",
+          annotations: { readOnlyHint: true },
+          inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" } },
+            required: ["id"],
+          },
+          handler: async ({ id }, ctx) => {
+            const response = await fetch(
+              `https://billing.internal.example/invoices/${id}`,
+              { headers: { Authorization: `Bearer ${await ctx.credential?.get()}` } },
+            );
+            return response.json();
+          },
+        },
+      ],
+    }),
+  ],
+});
+```
+
+All three are ordinary `Connector` instances by the time the registry sees
+them. Nothing in the list is privileged by how it was authored.
+
+Maintained provider guides:
+
+- [Mixpanel](./mixpanel.md)
+
 ## MCP version skew
 
 Connecta deliberately sits between protocol generations
@@ -53,6 +154,17 @@ Tool calls must use the shared invocation path. That keeps direct calls, batch
 children, and code-mode host calls aligned on safety, retries, admission,
 timeouts, validation, result guards, and typed failures.
 
+Connector usage guides are configuration too. `usageGuide` accepts the
+historical markdown string or `{ content, summary?, required? }`; the latter
+lets discovery explain what the guide covers without loading it. The summary
+is only a bounded routing hint. Mark a guide `required` only when no complete
+tool schema can describe correct use, such as a generic operation wrapper or a
+mandatory cross-tool sequence. Mutations and truncated compact schemas already
+produce automatic review requirements. Two deployments may reuse the same
+constant and override its summary or requirement in their own config, but
+Connecta stores no runtime template and never lets one deployment's guide apply
+to another.
+
 For remote MCP tools, that path checks the catalog's advertised `inputSchema`
 before provider dispatch. Supported mismatches become bounded, payload-free
 `invalid_args` findings; a schema the local validator cannot evaluate passes

package/documentation/mcp-ui-design.md

@@ -319,14 +319,14 @@ official spec at all — it survives there as background prose, not as a deferre
 item with a queue position. Adopting a payload format the official spec never
 took, on the path the official spec superseded, is two bets on one square.
 
-**View-initiated tool calls from program UI.** Gated, not refused. The
-host-mediated `tools/call` path exists in the Apps spec and would go through
-the same admission, annotation, and consent path as any other call, so the
-safety story is not the blocker. What is missing is the argument: a
-program-authored UI that drives tools needs its own use case and its own
-consent story, and neither exists yet. Display-only until one arrives, and
-gated twice over: `U5` declares `_meta.ui.visibility: ["model"]` so no host is
-ever told the view may call, and `U6`'s shell has no bridge to call with.
+**View-initiated tool calls from program UI.** This original gate was split by
+[#287](https://github.com/zackbart/connecta/issues/287) on 2026-08-02. Bounded
+refresh, pagination, and drill-down reads are accepted through named bindings
+and the existing `call_tool`; mutations remain gated. The evidence, threat
+trace, and boundary between live reads and Executor's artifact product live in
+[`program-ui-read-calls.md`](./program-ui-read-calls.md). The normative contract
+is `V1`–`V8` in [`code-mode.md`](./code-mode.md); it supersedes this record's
+display-only clauses where they disagree.
 
 **Downstream MCP Apps template passthrough** (downstream connectors declaring
 their own `ui://` templates, proxied through connecta's `resources/read`).