@intentic/extension-manifest 1.176.3

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@intentic/extension-manifest",
+  "version": "1.176.3",
+  "description": "What an intentic extension DECLARES — the intentic-extension.json schema and the sandbox-route allowlist rule",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intentic/intentic.git",
+    "directory": "_sandbox/extension-manifest"
+  },
+  "files": [
+    "dist",
+    "src",
+    "intentic-extension.schema.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": {
+        "@intentic/src": "./src/index.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "@intentic/src": "./src/index.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "tslib": "2.8.1",
+    "zod": "4.4.3",
+    "@intentic/base": "1.176.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.2",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@intentic/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsgo",
+    "watch": "tsgo --build --watch",
+    "schema": "tsgo && node scripts/write-schema.mjs"
+  }
+}

package/src/bundle.ts

@@ -0,0 +1,41 @@
+/* WHAT A PUBLISHED BUNDLE MAY IMPORT — the loader's side of the manifest contract, stated where both sides can
+ * read it. The host fetches an extension's entry bytes and imports them from a blob: URL, which has two hard
+ * consequences: a relative import resolves against a blob: URL that was never created (a 404 for a file that
+ * exists on disk), and a bare specifier resolves only if the shell's import map publishes it. Both failures are
+ * invisible to the author — their own workspace loads the directory live — and fatal for every installer.
+ *
+ * It lives HERE, beside the manifest schema, because two independent judges have to agree on it: the daemon's
+ * readiness check (before an author publishes) and the registry scanner (re-deriving the same answer cold, at
+ * the pinned sha, every night). Two hand-rolled copies of this rule would drift exactly the way the manifest
+ * schema and its published copy once did. */
+
+// What the shell's import map publishes to a bundle (the web app's hostModules.ts is the runtime source of
+// truth; its shim generator and this list are both asserted against the same module names).
+export const HOST_PUBLISHED_SPECIFIERS = ["vue", "@intentic/extension-api", "@intentic/extension-ui", "@tanstack/vue-query"] as const;
+
+// Every specifier a single-file ESM bundle names: static imports, re-exports, bare side-effect imports, and
+// dynamic import(). A bundle is one file by contract, so a regex over its text is the right instrument — there
+// is no module graph to walk.
+export const bundleSpecifiers = (source: string): string[] => [
+    ...new Set([
+        ...[...source.matchAll(/(?:^|\n)\s*(?:import|export)[^;\n]*?from\s*["'`]([^"'`]+)["'`]/gu)].map((match) => match[1] ?? ""),
+        ...[...source.matchAll(/\bimport\s*\(\s*["'`]([^"'`]+)["'`]\s*\)/gu)].map((match) => match[1] ?? ""),
+        ...[...source.matchAll(/(?:^|\n)\s*import\s*["'`]([^"'`]+)["'`]/gu)].map((match) => match[1] ?? ""),
+    ]),
+];
+
+/* Why this bundle cannot load, or undefined when it can. One sentence naming the offending specifiers, because
+ * both callers surface it verbatim: the readiness row to the author, the registry facts to anyone browsing. */
+export const bundleProblem = (source: string): string | undefined => {
+    const specifiers = bundleSpecifiers(source);
+    const relative = specifiers.filter((specifier) => specifier.startsWith(".") || specifier.startsWith("/"));
+    if (relative.length > 0) {
+        return `imports a second file (${relative.join(", ")}) — a bundle is imported from a blob URL, so nothing relative to it can resolve`;
+    }
+    const published = new Set<string>(HOST_PUBLISHED_SPECIFIERS);
+    const unpublished = specifiers.filter((specifier) => !published.has(specifier));
+    if (unpublished.length > 0) {
+        return `imports ${unpublished.join(", ")}, which the host does not publish — bundle it in, or use one of: ${HOST_PUBLISHED_SPECIFIERS.join(", ")}`;
+    }
+    return undefined;
+};

package/src/contribution-point.ts

@@ -0,0 +1,26 @@
+import type { z } from "zod";
+
+/* A CONTRIBUTION POINT, DEFINED ONCE — its key, its shape, and the sentence that explains it to the person
+ * writing the manifest, in one object.
+ *
+ * The three used to live apart, and only two of them lived anywhere at all. The key and the shape sat in one
+ * file that every feature had to edit to add anything, in two places (the schema, then the key on `contributes`);
+ * the explanation sat in a `//` comment above it, where the extension author — the only reader it was written
+ * for — could never see it. So the manifest was a thing you wrote by copying another extension's and guessing,
+ * with a misspelt contribution point dropped in silence rather than named.
+ *
+ * Binding the description to the schema is what changes that: it rides `z.describe`, so it reaches the generated
+ * authoring schema (json-schema.ts) and comes back as hover text in the author's editor. The prose that is for
+ * MAINTAINERS — why a point exists, what it replaced, what it deliberately does not do — stays a comment in the
+ * point's own file, because it is not what someone filling in a field needs to read. */
+export interface ContributionPoint<Name extends string = string, Schema extends z.ZodType = z.ZodType> {
+    // The key under `contributes` in intentic-extension.json.
+    readonly name: Name;
+    /* Written for the author, in the second person, and kept to what they must decide: what declaring this gets
+     * them, and what the host does with it. It lands verbatim in editor hover text, so a paragraph of rationale
+     * here is a paragraph in a tooltip. */
+    readonly description: string;
+    // The value shape under that key — an array for a point that takes many entries, the entry itself for a
+    // point that takes one. `contributes` makes every one of them optional; a point is never required.
+    readonly schema: Schema;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./bundle.js";
+export * from "./contribution-point.js";
+export * from "./json-schema.js";
+export * from "./manifest.js";
+export * from "./permissions.js";
+export * from "./points/index.js";
+export * from "./powers-diff.js";

package/src/json-schema.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { ExtensionManifestSchema } from "./manifest.js";
+
+/* THE AUTHORING SCHEMA — what an editor reads to help someone write `intentic-extension.json`.
+ *
+ * A manifest was previously written by copying another extension's and guessing. Nothing told the author what a
+ * field meant, because every explanation lived in a `//` comment in this package; and nothing told them when
+ * they got one wrong, because zod STRIPS unknown keys at every level rather than refusing them. A misspelt
+ * `viewers` was not an error — it was a viewer that never appeared, discovered at install, with the manifest
+ * parsing perfectly.
+ *
+ * So: the same points, emitted as JSON Schema, with the descriptions that ride each one (contribution-point.ts)
+ * arriving as hover text. Editors resolve `$schema` and give completion, documentation and a red squiggle on a
+ * key nothing declares.
+ *
+ * STRICT HERE, LENIENT AT RUNTIME, and the asymmetry is the point. Authoring is where an unknown key is a typo
+ * and should be shouted about. Runtime is where an unknown key is a manifest written for a NEWER host, which an
+ * older daemon must go on installing with the point it doesn't understand ignored — refusing it outright would
+ * make every addition to this list a breaking change. */
+
+// Where the published copy answers, so `$schema` in a manifest resolves for an author who has installed nothing.
+export const MANIFEST_SCHEMA_URL = "https://intentic.dev/intentic-extension.schema.json";
+
+/* `additionalProperties: false` on every object node, so a key nothing declares is flagged where it is typed.
+ *
+ * Skips a node that already carries `additionalProperties` — that is a `z.record`, whose whole shape is "any key,
+ * this value" (a cli capability's `env`), and pinning it closed would reject every entry it exists to accept. */
+const closeToUnknownKeys = (node: unknown): void => {
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            closeToUnknownKeys(item);
+        }
+        return;
+    }
+    if (typeof node !== "object" || node === null) {
+        return;
+    }
+    const schema = node as Record<string, unknown>;
+    if (schema["type"] === "object" && schema["properties"] !== undefined && schema["additionalProperties"] === undefined) {
+        schema["additionalProperties"] = false;
+    }
+    for (const value of Object.values(schema)) {
+        closeToUnknownKeys(value);
+    }
+};
+
+/* The manifest schema as JSON Schema. `io: "input"` because this describes what an author WRITES — the shape
+ * going in, before any refinement or default has been applied to it. */
+export const manifestJsonSchema = (): Record<string, unknown> => {
+    const schema = z.toJSONSchema(ExtensionManifestSchema, { unrepresentable: "any", io: "input" }) as Record<string, unknown>;
+    closeToUnknownKeys(schema);
+    return {
+        ...schema,
+        $id: MANIFEST_SCHEMA_URL,
+        title: "intentic extension manifest",
+        description: "What an intentic extension declares: who it is, which host it needs, what code it ships, and what it contributes.",
+    };
+};
+
+// The committed file's exact bytes, so the generator and the check that guards it cannot disagree about
+// formatting — four spaces and a trailing newline, the repo's shape for a committed generated document.
+export const serializeManifestJsonSchema = (schema: Record<string, unknown>): string => `${JSON.stringify(schema, undefined, 4)}\n`;

package/src/manifest.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { MARK_FIELDS } from "./mark.js";
+import { contributesSchema } from "./points/index.js";
+
+/* The extension manifest: `intentic-extension.json` at the extension repo root (deliberately NOT inside
+ * .claude-plugin/ — that directory is Claude Code's namespace with its own semantics). The manifest is the
+ * approval surface: the install dialog shows exactly these declared contributions before the owner confirms,
+ * and the host refuses runtime registrations (views, commands) whose ids the approved manifest never declared.
+ *
+ * This file is the ENVELOPE only — who the extension is, which host it needs, what code it ships, how far it
+ * may reach. What it may CONTRIBUTE is one file per contribution point under points/, assembled here; see
+ * contribution-point.ts for why the description travels with the schema instead of sitting in a comment. */
+
+export const ExtensionManifestSchema = z.object({
+    /* The authoring schema this manifest is written against — editors read it and give the author completion,
+     * hover text and a red squiggle on a misspelt key. Declared so it survives the parse rather than being
+     * silently stripped, which is what would otherwise happen to the one field an author is most likely to add
+     * by hand. Nothing at runtime reads it. */
+    $schema: z.string().optional().describe("The authoring schema, for editor completion and validation. Nothing at runtime reads it."),
+    publisher: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    // The extension's own semver — display/identity only; the installed code identity is the pinned commit sha.
+    version: z.string().min(1).describe("Your own semver — display and identity only. The installed code's identity is the pinned commit sha."),
+    /* The section this extension sits under in the Sandbox hub's Extensions tab — a grouping by what it is FOR,
+     * declared because it cannot be derived. Nine of the first-party extensions contribute a rail tile, so a
+     * grouping read off `contributes` puts more than half the list in one section and says nothing about any of
+     * them. Deliberately a loose string, exactly like a connector's `catalog.category`: the vocabulary belongs
+     * to the surface that renders it (extensionCategories.ts in the web app), and an extension declaring a
+     * section this app has never heard of lands in "Other" rather than failing to install. */
+    category: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+            "Which section of the Extensions tab this sits under — a grouping by what it is FOR, which cannot be derived from what it contributes. A section this app has never heard of lands in “Other” rather than failing to install.",
+        ),
+    /* What the extension is drawn as wherever it is LISTED rather than used — the Extensions tab, a registry
+     * being browsed, the gallery. Deliberately here and not on a view: `Activation.icon` is the glyph of one
+     * rail tile, it only exists once the extension's code has activated in this browser, and nine of the
+     * first-party extensions register no view at all. An extension that is switched off, daemon-only, or not
+     * yet installed still has to look like something. See MARK_FIELDS. */
+    ...MARK_FIELDS,
+    // Semver range over the host's extension API version (extensionApiVersion) — checked before activation.
+    engines: z
+        .object({ intentic: z.string().min(1) })
+        .describe("A semver range over the host's extension API version, checked before your code is activated."),
+    // Repo-relative path of the prebuilt single-file ESM bundle (built with `vue` and `@intentic/extension-api`
+    // as externals); absent ⇒ an extension with no UI entry.
+    entry: z
+        .string()
+        .min(1)
+        .refine((value) => !value.split("/").includes(".."), { message: "entry must stay inside the checkout" })
+        .optional()
+        .describe(
+            "Repo-relative path of your prebuilt single-file ESM bundle, built with `vue` and `@intentic/extension-api` as externals. Absent ⇒ an extension with no UI.",
+        ),
+    /* Repo-relative path of the prebuilt single-file node ESM SERVER bundle — the extension's BACKEND half,
+     * exporting `activateServer(api, context)`. Loaded by the daemon's backend host (a separate supervised
+     * process, so a toggle or a live edit is a host restart rather than a daemon death) and served under the
+     * extension's own route namespace `/x/<id>/…`, which the daemon proxies. Self-contained by construction:
+     * the host provides no import map and the baked checkout has no node_modules, so everything but node
+     * builtins must be bundled in. Absent ⇒ the extension has no backend. */
+    server: z
+        .string()
+        .min(1)
+        .refine((value) => !value.split("/").includes(".."), { message: "server must stay inside the checkout" })
+        .optional()
+        .describe(
+            "Repo-relative path of your prebuilt single-file node ESM server bundle, exporting `activateServer`. Served under your own route namespace, which the daemon proxies. Nothing is provided at runtime but node builtins, so bundle everything else in. Absent ⇒ no backend.",
+        ),
+    // Declared reach, both halves in one grammar — "<METHOD> <path-glob>" where `*` matches one path segment
+    // (e.g. "GET /panels", "POST /panels/*/start") — so the install dialog, the gate and the usage ledger read
+    // one vocabulary.
+    //   sandbox — the daemon routes the UI half may call through api.sandbox (the host refuses undeclared
+    //             ones). An extension's OWN namespace `/x/<its id>/…` needs no entry: its backend is its own.
+    //   daemon  — the daemon routes the SERVER half may call through api.daemon, enforced by the daemon's
+    //             extension-token grant. Separate from `sandbox` because the halves run as different
+    //             principals: the UI acts with the owner's session, the backend with a minted per-extension
+    //             token, and a grant to one must never quietly widen the other.
+    // Absent (or an absent key) ⇒ that half makes no daemon calls.
+    permissions: z
+        .object({
+            sandbox: z
+                .array(z.string())
+                .optional()
+                .describe("Daemon routes your UI half may call. Your own backend namespace needs no entry — its backend is your own code."),
+            daemon: z
+                .array(z.string())
+                .optional()
+                .describe(
+                    "Daemon routes your SERVER half may call. Separate from `sandbox` because the two halves run as different principals — the UI as the owner's session, the backend as a minted per-extension token — so a grant to one must never quietly widen the other.",
+                ),
+        })
+        .optional()
+        .describe(
+            'How far this extension may reach into the daemon, as "<METHOD> <path-glob>" entries where `*` matches one path segment — e.g. "GET /panels", "POST /panels/*/start". The install dialog shows these, the host refuses anything undeclared, and the usage ledger records which were actually earned.',
+        ),
+    contributes: contributesSchema.optional(),
+});
+export type ExtensionManifest = z.infer<typeof ExtensionManifestSchema>;
+
+// The extension's identity everywhere (capability entries, /ext routes, settings namespaces) — derived, never
+// declared, so it can't contradict the publisher/name the install dialog showed.
+export const extensionIdOf = (manifest: Pick<ExtensionManifest, "publisher" | "name">): string => `${manifest.publisher}.${manifest.name}`;

package/src/mark.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+/* HOW SOMETHING LOOKS BEFORE ANY OF ITS CODE RUNS — the mark a capability card and an extension are drawn
+ * with, in ONE shape because one component draws both (<BrandMark>) and a second copy of these two fields is a
+ * second answer to what happens when a slug 404s.
+ *
+ * Two tiers, and neither is required. `logo` is a simple-icons slug fetched from a CDN: exactly right for a
+ * card standing in for somebody else's product (GitHub, Postgres, Slack), useless for the many things that
+ * have no brand in that set, and unreachable in an offline sandbox — so it can never be the only tier. `icon`
+ * is a name from the host's own bundled vocabulary, which ships in the image, follows the theme and costs no
+ * request; it is what actually carries a first-party extension. What declares neither is drawn as its
+ * initials, so no row is ever blank and no author is obliged to have a brand.
+ *
+ * A slug that fails to load and an icon name this build has never heard of both fall to the tier BELOW rather
+ * than to a hole — the rule the rail already applies to Activation.icon, here for the surfaces that must draw
+ * an extension whose code is not running: one that is switched off, one that is daemon-only, one being read
+ * about in a registry before it is installed at all. */
+export const MARK_FIELDS = {
+    // A simple-icons slug (https://cdn.simpleicons.org/<slug>). A "/<hex>" suffix forces a colour for marks
+    // that vanish against the surface they land on (github's near-black).
+    logo: z
+        .string()
+        .optional()
+        .describe(
+            'A simple-icons slug, fetched from a CDN — right for standing in for somebody else\'s product. Add a "/<hex>" suffix to force a colour for a mark that vanishes against the surface it lands on. Unreachable in an offline sandbox, so it falls back to `icon`, then to initials.',
+        ),
+    // A name from the host's icon set (@intentic/ui IconName), drawn when no simple-icons slug fits.
+    icon: z
+        .string()
+        .optional()
+        .describe(
+            "A name from the host's own icon set, drawn when no simple-icons slug fits. It ships in the image, follows the theme and costs no request — what actually carries a first-party extension. An unknown name falls back to initials rather than to a hole.",
+        ),
+};

package/src/permissions.ts

@@ -0,0 +1,36 @@
+/* The sandbox-route permission model. An extension declares in its manifest exactly which daemon routes it may
+ * reach through `api.sandbox.request/json`, as "<METHOD> <path-glob>" strings where `*` matches exactly one path
+ * segment. The host matches every call against these and refuses an undeclared route — so an extension's backend
+ * reach is explicit, diffable, and reviewable rather than an ambient client to the whole daemon. */
+
+const escapeRegExp = (literal: string): string => literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+interface CompiledRoute {
+    readonly method: string;
+    readonly test: (path: string) => boolean;
+}
+
+// "<METHOD> <path-glob>" → a method + an anchored path matcher. Each `*` in the glob matches one path segment
+// ([^/]+); everything else is literal. Throws on a malformed entry so a bad manifest fails loudly at load.
+const compile = (entry: string): CompiledRoute => {
+    const spaceIndex = entry.indexOf(" ");
+    if (spaceIndex < 0) {
+        throw new Error(`invalid sandbox permission "${entry}" — expected "<METHOD> <path-glob>", e.g. "GET /panels"`);
+    }
+    const method = entry.slice(0, spaceIndex).trim().toUpperCase();
+    const glob = entry.slice(spaceIndex + 1).trim();
+    const source = `^${glob.split("*").map(escapeRegExp).join("[^/]+")}$`;
+    const regex = new RegExp(source);
+    return { method, test: (path) => regex.test(path) };
+};
+
+// Whether `method path` is covered by any of the declared permissions. The query string is ignored (routes are
+// matched on path only), and the method is compared case-insensitively.
+export const sandboxRouteAllowed = (permissions: readonly string[], method: string, path: string): boolean => {
+    const route = path.split("?")[0] ?? path;
+    const wanted = method.toUpperCase();
+    return permissions.some((entry) => {
+        const compiled = compile(entry);
+        return compiled.method === wanted && compiled.test(route);
+    });
+};

package/src/points/agent.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// "This checkout is ALSO a Claude Code plugin": the daemon hands the directory to the Agent SDK's plugin
+// loader, which reads skills/agents/hooks/commands/.mcp.json each turn — the daemon never parses plugin
+// internals.
+export const AgentContributionSchema = z.object({
+    path: z.string().optional().describe("Relative to the extension checkout. Absent ⇒ the checkout root."),
+});
+export type AgentContribution = z.infer<typeof AgentContributionSchema>;
+
+export const agentPoint = {
+    name: "agent",
+    description:
+        "Declare that this checkout is also a Claude Code plugin, so the agent picks up its skills, agents, hooks, commands and MCP servers each turn. The daemon hands the directory to the plugin loader and never parses what is in it.",
+    schema: AgentContributionSchema,
+} as const satisfies ContributionPoint;

package/src/points/automation-templates.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+/* A STARTING POINT in the automation composer — a trigger, a prompt written for that trigger's payload, and
+ * whatever guard or hold makes it safe to leave on. Pure prefill: creating one makes an ordinary automation and
+ * the daemon knows nothing about templates afterwards.
+ *
+ * IT LIVES WITH THE AREA THAT KNOWS THE SERVICE, which is the point of it being a contribution at all. The
+ * automation surface used to carry every one of these — Komodo's, Sentry's, Stripe's, CI's, the chore book's —
+ * so a pack that gained something worth reacting to could not say so without an edit to a surface it has
+ * nothing to do with. A template declared here appears when the pack is installed and its capability connected,
+ * and disappears with it.
+ *
+ * The daemon validates each one against the real trigger schema when it builds the catalogue and drops what
+ * does not parse, so a template can never offer a trigger that `upsert` would refuse. */
+export const AutomationTemplateContributionSchema = z.object({
+    // Prefills the automation name, and is what "does one of these exist already" is asked by — so it must be
+    // spelled as an automation id, not as prose.
+    id: z
+        .string()
+        .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/)
+        .describe('Prefills the automation name, and is what "does one of these exist already" is asked by — so spell it as an id, not as prose.'),
+    title: z.string().min(1),
+    logo: z.string().min(1).optional().describe("A simple-icons slug for the card."),
+    icon: z.string().min(1).optional().describe("A name from the host's icon set, drawn when no simple-icons slug fits."),
+    // Capability providers that make this template WORK — any one connected is enough (fixing CI rides github
+    // or gitlab). Omitted ⇒ nothing to connect, always offered.
+    requires: z
+        .array(z.string().min(1))
+        .optional()
+        .describe(
+            "Capability providers that make this template work — any one connected is enough (fixing CI rides github or gitlab). Omitted ⇒ nothing to connect, so it is always offered.",
+        ),
+    // Shaped loosely here and parsed strictly at the merge: the manifest package cannot see the trigger union
+    // (the dependency runs the other way), so the daemon is where a declaration meets the real schema.
+    trigger: z
+        .object({
+            kind: z.enum(["schedule", "event", "listener", "workspace"]),
+            cron: z.string().min(1).optional(),
+            provider: z.string().min(1).optional(),
+            eventType: z.string().min(1).optional(),
+            event: z.string().min(1).optional(),
+        })
+        .describe(
+            "What wakes it. Checked against the real trigger schema when the daemon builds the catalogue, so a template can never offer one that would be refused.",
+        ),
+    guard: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A condition that must hold before the turn runs — what makes a template safe to leave switched on."),
+    holdForSeconds: z.number().int().positive().optional().describe("Wait this long and coalesce repeats, rather than firing on every event."),
+    prompt: z.string().min(1).describe("The turn this starts. You own the trigger's payload vocabulary, so you own the prompt that reads it."),
+    note: z.string().min(1).optional(),
+    setup: z.string().min(1).optional().describe("What the user must do themselves before this can work."),
+    description: z.string().min(1).optional(),
+    /* Absent ⇒ the create dialog's gallery, where you go once you know what you want. `create` puts a card on
+     * the page that makes the automation switched off in one click; `configure` puts one there that opens the
+     * dialog prefilled, for a template that cannot work unconfigured. Both are for what a user would never
+     * think to go looking for, and a pack that marked everything as offered would have built a gallery with
+     * extra steps. */
+    offer: z
+        .enum(["create", "configure"])
+        .optional()
+        .describe(
+            "Absent ⇒ it waits in the gallery, where you go once you know what you want. `create` puts a card on the page that makes it, switched off, in one click. `configure` puts one there that opens the dialog prefilled, for a template that cannot work unconfigured. Both are for what a user would never think to go looking for — mark everything as offered and you have rebuilt the gallery with extra steps.",
+        ),
+    // Whether what this makes watches THIS codebase (the chores shelf) rather than the outside world. Declared
+    // rather than read off the trigger: a nightly dependency sweep and a nightly Stripe poll are both schedules.
+    chore: z
+        .boolean()
+        .optional()
+        .describe(
+            "Whether what this makes watches THIS codebase rather than the outside world. Declared rather than read off the trigger — a nightly dependency sweep and a nightly Stripe poll are both schedules.",
+        ),
+});
+export type AutomationTemplateContribution = z.infer<typeof AutomationTemplateContributionSchema>;
+
+export const automationTemplatesPoint = {
+    name: "automationTemplates",
+    description:
+        "Starting points this pack offers in the automation composer — a trigger, a prompt written for that trigger's payload, and whatever guard makes it safe to leave on. Declared by whoever knows the service rather than by the composer, so they appear when your pack is installed and disappear with it. Pure prefill: creating one makes an ordinary automation.",
+    schema: z.array(AutomationTemplateContributionSchema),
+} as const satisfies ContributionPoint;

package/src/points/bin.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// A checkout-relative directory of executables the daemon prepends to the AGENT's PATH each turn — how an
+// extension ships a command-line tool for the agent (the CLI-tools path). The files ARE the approved code (they
+// ride the sha-pinned checkout); the daemon only adds the dir to PATH.
+export const binPoint = {
+    name: "bin",
+    description:
+        "A checkout-relative directory of executables the daemon puts on the agent's PATH every turn — how you ship the agent a command-line tool. The files are the approved code themselves: they ride the pinned checkout, and the daemon only adds the directory to PATH.",
+    schema: z
+        .string()
+        .min(1)
+        .refine((value) => !value.split("/").includes(".."), { message: "bin must stay inside the checkout" }),
+} as const satisfies ContributionPoint;