@intentic/extension-manifest 1.248.0 → 1.250.0

package/src/mark.ts

@@ -1,50 +1,14 @@
 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.
- *
- * Three tiers, and none is required. `art` is the extension's OWN drawing, carried inline: the only tier an
- * author controls completely, and the only one that can make a grid of unfamiliar names look like a shelf of
- * distinct products rather than a column of identical glyphs. `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 carries a first-party extension that has not been drawn yet. What
- * declares none of them is drawn as its initials, so no row is ever blank and no author is obliged to have a
- * brand or an illustrator.
- *
- * ART BEATS A BRAND SLUG because they answer different questions. A slug says "this is Slack"; art says "this
- * is mine". An extension that stands in for somebody else's product should declare the slug and no art, and
- * one that is its own thing should declare art, but where both arrive, the author's own drawing is the more
- * specific claim and wins.
- *
- * Artwork that will not parse, a slug that fails to load and an icon name this build has never heard of all
- * 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. */
+// The mark a capability card or extension draws itself with, one shape since one component (<BrandMark>) draws both:
+// `art` (inline SVG, own drawing) beats `logo` (simple-icons slug) beats `icon` (host's set), falling back to initials
+// when none is declared.
 
-/* Big enough for a drawn mark, far too small for a traced photograph, which is the line being drawn. This
- * string rides every registry row and every manifest read, so it is a budget as much as a limit: at 4 KB the
- * whole official registry's artwork costs less than one screenshot, and an author who needs more than that is
- * shipping a raster they should be shipping as a brand slug or not at all. */
+// Big enough for a drawn mark, far too small for a traced photograph.
 const ART_MAX_BYTES = 4096;
 
 export const MARK_FIELDS = {
-    /* THE SVG DOCUMENT ITSELF, not a URL and not base64.
-     *
-     * A URL would put a stranger's server in the render path of a page listing extensions, a fetch that
-     * tracks who is browsing what, breaks in an offline sandbox, and 404s long after the row was approved:
-     * the three failures the `logo` tier already documents, with none of its excuse. Inline costs one string
-     * and always draws.
-     *
-     * Kept as READABLE TEXT rather than a data URI because of who reads it. The registry's curated file is
-     * reviewed by a human before anything is published, and `<rect fill="#5B4FE9"/><circle .../>` can be read
-     * in a diff, while base64 is a wall nobody checks, an opaque blob in the one file whose entire purpose is
-     * to be checked. The renderer does its own encoding at the point of use.
-     *
-     * It is drawn INERT (an <img>, never inline in the document), so a hostile registry row cannot script the
-     * page it is listed on, see <BrandMark>, which owns that guarantee and the sniff test that enforces it. */
+    // SVG document itself, not a URL or base64; drawn inert (<img>, never inlined) so a row can't script the page.
     art: z
         .string()
         .max(ART_MAX_BYTES)
@@ -52,15 +16,15 @@ export const MARK_FIELDS = {
         .describe(
             "This extension's own mark, as a complete SVG document inline: the tier an author controls fully. Give it a viewBox and let it fill its own square edge to edge; it is drawn as the tile, not as a glyph on a plate. Kept as readable SVG text (not base64) so a registry reviewer can see what they are publishing, drawn inert so it cannot script the page, and capped at 4 KB. Anything that does not parse as SVG falls back to `logo`, then `icon`, then initials.",
         ),
-    // 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).
+    // A simple-icons slug (https://cdn.simpleicons.org/<slug>). A "/<hex>" suffix forces a colour for a mark that
+    // vanishes against its surface.
     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.
+    // A name from the host's own icon set (@intentic/ui IconName), drawn when no simple-icons slug fits.
     icon: z
         .string()
         .optional()

package/src/points/automation-templates.ts

@@ -1,21 +1,11 @@
 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. */
+// A starting point in the automation composer: a trigger, a prompt written for that trigger's payload, and any guard
+// that makes it safe to leave on. Pure prefill, creating one makes an ordinary automation. The daemon validates each
+// against the real trigger schema when building the catalogue and drops what doesn't parse.
 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.
+    // Prefills the automation name and is what "does one exist already" is asked by, so spell it as an id, not prose.
     id: z
         .string()
         .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/)
@@ -23,16 +13,16 @@ export const AutomationTemplateContributionSchema = z.object({
     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.
+    // Capability providers that make this template work; any one connected is enough. 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.
+    // Shaped loosely here and parsed strictly at the merge, since this package can't see the daemon's real trigger
+    // union.
     trigger: z
         .object({
             kind: z.enum(["schedule", "event", "listener", "workspace"]),
@@ -54,19 +44,16 @@ export const AutomationTemplateContributionSchema = z.object({
     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. */
+    // Absent ⇒ waits in the gallery. `create` puts a card that makes it switched off in one click; `configure` opens
+    // the dialog prefilled, for a template that can't work unconfigured.
     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.
+    // Whether what this makes watches this codebase rather than the outside world; declared rather than read off the
+    // trigger, since a schedule can point either way.
     chore: z
         .boolean()
         .optional()

package/src/points/capabilities.ts

@@ -3,9 +3,8 @@ import { z } from "zod";
 import type { ContributionPoint } from "../contribution-point.js";
 import { MARK_FIELDS } from "../mark.js";
 
-// A field the "+" install dialog renders for a capability's config form (a slug key, a label, secret/optional
-// flags, an optional select, a `when` gate). Mirrors the platform catalog's field shape so the web can render
-// contributed cards from installed extensions exactly like core capability cards.
+// A field the install dialog's config form renders (key, label, secret/optional flags, a select, a `when` gate);
+// mirrors the platform catalog's own field shape.
 export const CapabilityFieldSchema = z.object({
     key: z.string().regex(/^[a-zA-Z][a-zA-Z0-9]*$/),
     label: z.string().min(1),
@@ -13,44 +12,31 @@ export const CapabilityFieldSchema = z.object({
     secret: z.boolean().optional().describe("Mask it, and never echo it back."),
     optional: z.boolean().optional(),
     multiline: z.boolean().optional(),
-    /* The answers most connections never change, folded behind the form's one "Advanced" disclosure. A form's
-     * length is what it costs to read, and a card that asks six questions whose defaults are right for nearly
-     * everyone was spending that cost on nearly everyone. The disclosure opens BY ITSELF while any advanced
-     * field holds a non-default value, so an edit never hides the settings it is standing on. */
+    // Folds this field behind the form's Advanced disclosure; it opens by itself while any advanced field holds a
+    // non-default value.
     advanced: z
         .boolean()
         .optional()
         .describe(
             "Fold this field behind the form's Advanced disclosure: for answers whose default is right for nearly everyone. The disclosure opens by itself while any advanced field holds a non-default value, so an edit never hides live settings.",
         ),
-    // An OPT-IN EXTRA rather than a decision, rendered as a switch, carried as the "on"/"off" the config
-    // schemas already speak (the vpn's pfs/aggressive precedent). A two-option Segmented can express the same
-    // value, and reads wrong for this: it presents a choice the user must make to proceed, sized like the
-    // required fields around it. Something the capability works fine without wants the control that is quiet
-    // when it is off. A switch always holds one of its two values, so such a field never blocks a submit
-    // whatever `optional` says.
+    // Renders as a switch carrying "on"/"off", for an opt-in extra rather than a required decision; always holds a
+    // value, so it never blocks a submit.
     boolean: z
         .boolean()
         .optional()
         .describe(
             'Render it as a switch, carrying "on"/"off". For an opt-in EXTRA rather than a decision: a two-option picker says the same thing but presents a choice the user must make to proceed, sized like the required fields around it. A switch always holds a value, so a field like this never blocks a submit.',
         ),
-    // A line under the control, for what the user cannot see from the label alone (a host requirement, when a
-    // value takes effect). The card's `hint` speaks for the whole card; this one is bound to the field it
-    // qualifies, which is where a per-option caveat has to sit to be read at all.
+    // A line under the control for what the label alone can't say (a host requirement, when a value takes effect).
     hint: z
         .string()
         .optional()
         .describe(
             "A line under this control, for what the label alone cannot say: a host requirement, when a value takes effect. The card's own `hint` speaks for the whole card; this one is bound to the field it qualifies.",
         ),
-    /* This field's value only takes effect after the sandbox is REBUILT, it rides the environment overlay
-     * rather than something the daemon can act on now. Rendered as a chip beside the label.
-     *
-     * The one fact a user needs before touching a control, and the one the form cannot infer: two switches
-     * side by side, identical in every visible way, can cost five seconds and five minutes. The docker card
-     * has exactly that pair (its GPU option is baked into the image; its engine options are a file dockerd
-     * rereads), and without this flag the only way to find out which you pressed is to press it. */
+    // Value only takes effect after a sandbox rebuild (rides the image overlay); shown as a chip since two
+    // otherwise-identical switches can cost very differently.
     rebuild: z
         .boolean()
         .optional()
@@ -62,13 +48,7 @@ export const CapabilityFieldSchema = z.object({
         .array(z.object({ value: z.string(), label: z.string() }))
         .optional()
         .describe("Turns the field into a select."),
-    /* Gates this field on the answers already given, the SSH credential that only applies to the auth mode
-     * chosen, the gateway fields that belong to one VPN provider. A `when` condition (@intentic/base/when)
-     * evaluated against the form's live values, so it re-reads as the user toggles.
-     *
-     * Refused at parse when it does not parse. A card is data an extension ships, and a condition nobody can
-     * evaluate is not a field that is always shown or always hidden, it is a card whose author believes it
-     * asks something it never asks. Failing the manifest names the card; failing at render names nothing. */
+    // Gates the field on answers already given; refused at parse when the `when` expression doesn't parse.
     when: z
         .string()
         .refine(isWhenExpression, { message: "not a valid `when` condition" })
@@ -76,19 +56,15 @@ export const CapabilityFieldSchema = z.object({
         .describe(
             "Only show this field while a condition over the answers already given holds: `auth == 'key'`, `provider in ['ipsec', 'fortinet']`, `!advanced`. Supports `&&`, `||`, `!`, comparisons and `in`.",
         ),
-    // A fixed value baked into the config rather than asked for, how a card pins a discriminator
-    // (platform="reddit", provider="stripe"). Rendered as nothing; sent as itself.
+    // A fixed value baked into the config rather than asked for, e.g. pinning a discriminator; renders as nothing.
     value: z
         .string()
         .optional()
         .describe(
             'A fixed value baked into the config rather than asked for: how a card pins its discriminator (platform="reddit", provider="stripe"). Renders as nothing.',
         ),
-    /* This field holds a TOTP seed, the base32 key (or otpauth:// URI) a service shows when enrolling an
-     * authenticator app. Declare it WITH `secret: true`: the seed is a durable second factor, so it is never
-     * echoed and, unlike an ordinary secret, never enters the agent's environment either, the daemon mints the
-     * six-digit codes on demand (`otp <name>` / GET /capabilities/<id>/otp) and only those cross, each dead
-     * within its period. A cli entry whose env references a totp field therefore fails to parse (see below). */
+    // Marks this field as a TOTP seed; declare with `secret: true`. Unlike an ordinary secret it never reaches the
+    // agent's environment, the daemon mints codes on demand.
     totp: z
         .boolean()
         .optional()
@@ -98,30 +74,13 @@ export const CapabilityFieldSchema = z.object({
 });
 export type CapabilityField = z.infer<typeof CapabilityFieldSchema>;
 
-/* WHETHER A FIELD IS IN PLAY, given what has been answered so far, and the only place that decides it.
- *
- * Two tiers ask this question about the same card. The web's form asks it to decide what to draw and what to
- * validate; the daemon asks it at install to decide which fields it may demand. They used to answer it with
- * their own copies of the same comparison, in different packages, and the answers only had to diverge once for
- * a card to become unusable in exactly one direction: a field the form never showed, refused at submit for
- * being empty. Nothing in either copy referred to the other, so the divergence would have arrived as a bug
- * report about one card rather than as a broken rule.
- *
- * It lives beside the schema for the reason the description does: this is a fact about the shape, and the two
- * consumers are in different packages. Parsed per call rather than cached, a card has a handful of fields,
- * this runs on a keystroke at worst, and a cache keyed by manifest strings is a map that outlives every
- * extension that ever declared one. */
+// Whether a field is in play given the answers so far. The web form and the daemon's install-time check both need this
+// same answer.
 export const fieldApplies = (field: CapabilityField, values: Readonly<Record<string, unknown>>): boolean =>
     field.when === undefined || evaluateWhen(parseWhen(field.when), values);
 
-/* HOW THIS CARD'S SETTINGS ARE TESTED, before they are saved. One authenticated request the daemon makes on the
- * form's behalf (capabilities.probe), declared as data for the same reason the form is: the check is per-service
- * and the machinery is not.
- *
- * It is worth declaring on any card whose failure is otherwise silent, which is most of them: a wrong token, a
- * host the sandbox cannot route to and a service that is simply not running all present identically as a card
- * that says "not connected" some time after the form was left. The probe turns each into a sentence on the form
- * the reader is still standing on. */
+// One authenticated request the daemon makes on the form's behalf, declared as data since the check is per-service.
+// Worth declaring on any card whose failure is otherwise silent.
 const ProbeSchema = z.object({
     url: z
         .string()
@@ -132,9 +91,7 @@ const ProbeSchema = z.object({
         .record(z.string(), z.string())
         .optional()
         .describe('The request headers, templated the same way: `{"Authorization": "Bearer ${token}"}`.'),
-    /* WHAT THE SERVICE CALLED THE CALLER, read out of the JSON answer so success can be specific: "authenticated
-     * as ada" is a different fact from "200 OK", and it is the one that tells a reader they connected the
-     * account they meant to. A dotted path; a miss just leaves the message general. */
+    // Dotted path into the JSON answer naming who the caller is, so success can say which account answered.
     identity: z
         .string()
         .optional()
@@ -145,16 +102,11 @@ const ProbeSchema = z.object({
         .describe("Accept a self-signed certificate, for a service whose local install ships one (Obsidian's Local REST API)."),
 });
 
-// The "+" card an entry renders: how it looks in the grid and how the user gets the credential it asks for.
-// Shared by every arm below, because none of that varies with the kind.
+// The install-dialog card: how it looks in the grid and how the user gets its credential. Shared by every kind below.
 const CatalogSchema = z.object({
     name: z.string().min(1),
     ...MARK_FIELDS,
-    // ONE LINE, aim for 60 characters or fewer. The grid clamps this at two lines and a card sits beside two
-    // others in a pane the index column has already taken 16rem out of, so a paragraph here is a paragraph the
-    // reader gets truncated. Everything longer belongs in `hint`, which the config form prints in full and the
-    // catalog's search reads. Not capped in the schema: an extension published before this rule should still
-    // install, and a card that reads badly is a worse outcome than one that fails to load only in theory.
+    // One line, aim for 60 characters or fewer; the grid clamps this at two lines. Anything longer belongs in `hint`.
     description: z
         .string()
         .min(1)
@@ -162,15 +114,15 @@ const CatalogSchema = z.object({
             "ONE LINE: aim for 60 characters or fewer. The grid clamps it at two lines in a narrow pane, so a paragraph here is a paragraph the reader gets truncated. Everything longer belongs in `hint`.",
         ),
     category: z.string().min(1),
-    // The paragraph. Shown under the add-form, and searched from the catalog, so the words that identify this
-    // card to someone hunting for it ("webauthn", "socket mode") belong here even when the tile can't show them.
+    // The paragraph shown under the add form and searched from the catalog; words someone would search for belong here
+    // even if the tile can't show them.
     hint: z
         .string()
         .optional()
         .describe(
             'The paragraph, shown under the add form and searched from the catalog, so the words that identify this card to someone hunting for it ("webauthn", "socket mode") belong here even when the tile cannot show them.',
         ),
-    // The credential-creation walkthrough the install dialog renders (the platform catalog's guide shape).
+    // The credential-creation walkthrough the install dialog renders.
     guide: z
         .object({
             url: z.string().optional(),
@@ -184,33 +136,20 @@ const CatalogSchema = z.object({
         .describe("The walkthrough the install dialog renders for getting the credential this card asks for."),
 });
 
-// Every arm carries these: the slug that becomes the card's /capabilities/<id> route AND the discriminator
-// value the daemon's handler resolves (a cli `provider`, a browser/host `platform`), plus the card and its form.
+// Every arm carries these: the slug (the card's /capabilities/<id> route and the discriminator value the daemon
+// resolves), the card, and its fields.
 const contributionBase = {
     id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
     catalog: CatalogSchema,
     fields: z.array(CapabilityFieldSchema),
 };
 
-/* A CAPABILITY CARD AS DATA. The catalog is the extensible layer; the HANDLERS are core, so an entry names one
- * of the kinds whose daemon-side machinery is fully generic over its data, and the machinery stays put. The
- * kinds NOT listed here are the ones whose card is one-to-one with a handler that owns real privilege (`docker`
- * bakes --privileged, `vpn` bakes NET_ADMIN, `extension` installs extensions, `devops` scaffolds repos): their
- * cards live in the platform catalog because separating card from handler would split one concept in two, and
- * because a manifest that could name them would be a manifest that grants itself privilege. That restriction is
- * this discriminated union, not a comment, a manifest naming any other kind fails to parse.
- *
- * `${id}` in a cli/host skill file is substituted with the instance name at apply time (so a host pack's tool
- * names read `mcp__my-laptop__run_command`), and, for `cli`, each `$ENVVAR` becomes its per-instance suffixed
- * name. A BROWSER pack's skill renders once per SITE rather than per instance, its seams are `${accounts}`
- * (the roster of connected accounts), `${tools}` (the core driving/connecting note) and `${site}` (the host,
- * for the generic card whose text can name no site of its own); `${id}` and per-field substitution do not
- * apply there (capabilities/account-skills.ts in the sandbox daemon). */
+// A capability card as data; kinds with genuine device privilege (docker, vpn, extension, devops) live in the platform
+// catalog instead, since a manifest that could name them would grant itself that privilege.
 export const CapabilityContributionSchema = z
     .discriminatedUnion("kind", [
-        // A CLI tool the AGENT gets, authenticated: the env vars its shell receives (value templates over the
-        // fields, `${field}` substitutes, `${field:uri}` percent-encodes), a SKILL.md cheatsheet, and an optional
-        // image fragment holding the client binary (psql, mysql, whisper).
+        // A CLI tool the agent gets, authenticated: env vars templated over the fields, a SKILL.md cheatsheet, and an
+        // optional image fragment for the client binary.
         z.object({
             ...contributionBase,
             kind: z.literal("cli"),
@@ -229,13 +168,8 @@ export const CapabilityContributionSchema = z
                 .min(1)
                 .optional()
                 .describe("A Dockerfile fragment holding the client binary this tool needs (psql, mysql, whisper)."),
-            /* PREFER THIS over `fragment` whenever the sandbox already ships a pack for the tool. A pack
-             * reference is resolved through the image's pack stamps, so on an image that BAKES the pack the
-             * capability enables with no overlay and no rebuild at all, and on one that doesn't, the overlay
-             * gets the pack's own fragment — the same bytes the image would have baked, never a second copy
-             * that can drift from it. Discord's voice transcription was exactly that second copy: a fragment
-             * whose RUN lines were byte-identical to the `whisper` pack, so a standard image compiled
-             * whisper.cpp once at publish and again in every overlay rebuild, for the same binary. */
+            // Prefer over `fragment` whenever the sandbox already ships a pack for the tool: an image that bakes the
+            // pack needs no rebuild, and the overlay can't drift from it.
             pack: z
                 .string()
                 .min(1)
@@ -247,21 +181,8 @@ export const CapabilityContributionSchema = z
                 "One authenticated request that tests this card's settings before they are saved, so a wrong token or an unreachable host is answered on the form rather than by a card that says 'not connected' afterwards.",
             ),
         }),
-        /* A site the agent acts on AS THE OWNER, through the shared logged-in Chromium. `loginUrl` is what the
-         * sign-in window opens; the profile it persists is the credential. `homeUrl` is where that same profile
-         * opens once it HAS one, the owner's own hands on the connected browser, which a login page is the wrong
-         * place to start (signed in, it only redirects). Two fields because for some platforms the login lives on
-         * another site entirely (YouTube signs in at accounts.google.com), so one cannot be derived from the other.
-         * No `env` and no `fragment`: the browser itself is core (one Chromium install serves every platform),
-         * only the identity is per-entry. A card never declares the account's username/password either, those are
-         * CORE form fields on every browser card (the catalog appends them; the daemon's add validation accepts
-         * them), because which box a login form wants filled is the same fact on every site.
-         *
-         * BOTH URLs ARE OPTIONAL, so that one card can be the GENERIC one: a site card pins them (Reddit knows
-         * where Reddit signs in), and the generic "browser session" card asks for them on its form instead, which
-         * is what lets a user connect a site nobody shipped a card for. A card must do one or the other, pin a
-         * URL or declare a field that supplies it, and the daemon's apply says so on the form when neither does,
-         * because the alternative is a sign-in window that opens on nothing. */
+        // A site the agent acts on as the owner through the shared browser; `loginUrl`/`homeUrl` are both optional so a
+        // card can be the generic one that asks for them on its form instead.
         z.object({
             ...contributionBase,
             kind: z.literal("browser"),
@@ -284,36 +205,27 @@ export const CapabilityContributionSchema = z
                     "Checkout-relative SKILL.md teaching the agent this site's actions: rendered once per site, all its connected accounts on one roster (`${accounts}`), the core tool note at `${tools}`.",
                 ),
         }),
-        // An operating system a connected computer can run, the skill pack that teaches the agent THAT machine's
-        // shell. The enrollment, the socket and the scope enforcement are core; only the pack varies.
+        // An operating system a connected computer can run; enrollment, socket and scope enforcement are core, only the
+        // skill pack varies.
         z.object({
             ...contributionBase,
             kind: z.literal("host"),
             skill: z.string().min(1).describe("Checkout-relative SKILL.md teaching the agent that machine's shell."),
         }),
-        /* A BROWSER FAMILY the user can connect their own copy of, through the extension they install in it.
-         * The `host` arm one layer in: the enrollment, the socket, the tool surface and the per-site grants are
-         * core (and, for the grants, the browser's own), so a card supplies exactly two things a family differs
-         * in — where its extension is installed from, and how its skill pack words the difference.
-         *
-         * `install` is a URL rather than a store id because the families do not share a store: Chrome, Edge and
-         * Firefox each have their own, and a self-hosted build is a zip on a page. The card renders it as the
-         * link in the connect dialog, so an unlisted family is one manifest entry away from working. */
+        // A browser family the user connects their own copy of; `install` is a URL since each family has its own store
+        // or none at all.
         z.object({
             ...contributionBase,
             kind: z.literal("webext"),
             install: z.url().describe("Where this browser's extension is installed from: its store listing, or a page offering the build."),
             skill: z.string().min(1).describe("Checkout-relative SKILL.md teaching the agent to drive this browser."),
         }),
-        /* A PRESET over a core kind: no payload at all, just a named card whose `fields` carry the defaults. What an
-         * ACP agent needs is a command, so "OpenCode" is entirely a name, a logo and a filled-in form, which is
-         * exactly what a catalog row is. */
+        // A preset over a core kind: no payload, just a name, a logo and a filled-in form.
         z.object({ ...contributionBase, kind: z.literal("agent") }),
     ])
     .superRefine((spec, ctx) => {
-        // The totp flag's one invariant, enforced where the manifest is parsed rather than trusted to authors: a
-        // seed the daemon mints codes from must never ride the env into the agent's shell, that would hand the
-        // agent the second factor itself instead of one expiring code at a time.
+        // A totp field's env must never be referenced: that would hand the agent the seed itself instead of the
+        // daemon's one-time codes.
         if (spec.kind !== "cli") {
             return;
         }
@@ -327,17 +239,11 @@ export const CapabilityContributionSchema = z
         }
     });
 export type CapabilityContribution = z.infer<typeof CapabilityContributionSchema>;
-// The arms carrying a per-instance SKILL.md, the daemon templates and installs these identically.
+// Arms carrying a per-instance SKILL.md, templated and installed identically by the daemon.
 export type SkillContribution = Extract<CapabilityContribution, { skill: string }>;
 
-/* The config key a kind's cards PIN to their own id, so a stored capability can be traced back to the card that
- * made it, the daemon resolves the entry's handler data through it, and the web tells one card's instances from
- * another's. `agent` has none on purpose: its cards are presets over one config shape, differing only in their
- * defaults, so every agent instance belongs to every agent card equally.
- *
- * Here, beside the schema, because it is a fact about the contribution shape, the daemon, the catalog and the
- * web all need it, and three copies of it is three chances for a card's instances to go missing. `satisfies`
- * rather than a lookup table so a new arm above is a compile error until this answers for it. */
+// The config key a kind's cards pin to their own id, so a stored capability traces back to its card. `agent` has none:
+// its cards differ only in defaults.
 const DISCRIMINATOR = { cli: "provider", browser: "platform", host: "platform", webext: "platform", agent: undefined } satisfies Record<
     CapabilityContribution["kind"],
     string | undefined

package/src/points/commands.ts

@@ -7,10 +7,8 @@ export const CommandContributionSchema = z.object({
     command: z.string().regex(/^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/),
     title: z.string().min(1).describe("What the command palette shows. The manifest's value wins over the one passed at registration."),
     icon: z.string().optional().describe("A name from the host's icon set, drawn beside the title."),
-    // An optional global keyboard shortcut, in the host's chord notation (`Mod`/`Ctrl`/`Shift`/`Alt` + key, e.g.
-    // "Mod+Shift+K"; `Mod` = ⌘ on Apple, Ctrl elsewhere). It is DECLARED here so it rides the install dialog's
-    // approval surface, a global shortcut is consequential, so like title/icon the manifest value is authoritative
-    // and the host binds only what was approved. Whitespace-free; an unparseable chord simply never fires.
+    // Global keyboard shortcut in the host's chord notation. Declared here so it rides the install dialog's approval;
+    // the host binds only what was approved.
     keybinding: z
         .string()
         .regex(/^\S+$/)
@@ -18,14 +16,8 @@ export const CommandContributionSchema = z.object({
         .describe(
             'A global keyboard shortcut, e.g. "Mod+Shift+K" — `Mod` is ⌘ on Apple and Ctrl elsewhere. Declared here because a global shortcut is consequential: the owner approves it at install, and the host binds only what was approved.',
         ),
-    /* When the KEYBINDING applies, a condition over the shell's context keys (`tabSurface == 'chat'`,
-     * `!editableTarget`; see @intentic/base/when). The palette ignores it: a command is always runnable by
-     * name, and what a condition decides is whether the chord is claimed from whatever else would have had it.
-     *
-     * Declared here because it could not be declared anywhere. The shell's own commands used to gate on a
-     * JavaScript predicate, which an extension has no way to ship, so every extension command took its chord
-     * globally, from every surface, including terminals where a bare key belongs to the program on the other
-     * end. A condition an extension can write is what makes a contributed shortcut safe to grant. */
+    // When the keybinding applies, as a condition over the shell's context keys; the palette ignores it since a command
+    // is always runnable by name. Without one the chord is claimed everywhere, including inside a terminal.
     when: z
         .string()
         .refine(isWhenExpression, { message: "not a valid `when` condition" })

package/src/points/documents.ts

@@ -1,16 +1,9 @@
 import { z } from "zod";
 import type { ContributionPoint } from "../contribution-point.js";
 
-/* A per-directory document family the extension may register at runtime (api.documents.register): the provider
- * marks the directory rows it can explain in the Workspace tree, and the host opens its component as a tab,
- * see DocumentProviderRegistration.
- *
- * Only the id and the label are declared, deliberately. The consequential part of a viewer is which FILES it
- * takes over, and of a command its global shortcut, both are decided in the manifest because the owner must see
- * them. A document provider takes nothing over: it adds an icon to rows it has something for, and every one of
- * those rows is evidence the owner can see for themselves. So the manifest gates WHETHER the extension may mark
- * up the tree at all, and the per-row wording stays with the provider, which is the only thing that knows what
- * it found. */
+// A per-directory document family the extension may register at runtime; the provider marks rows in the Workspace tree
+// it can explain, and the host opens its component as a tab. Only id and label are declared: which rows to mark is the
+// provider's own call, made visibly, so nothing else needs owner approval.
 export const DocumentContributionSchema = z.object({
     id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
     // The family's human name, shown in the install dialog beside the extension's other contributions.

package/src/points/environment.ts

@@ -1,18 +1,11 @@
 import { z } from "zod";
 import type { ContributionPoint } from "../contribution-point.js";
 
-// A Dockerfile fragment baked into the sandbox image overlay so the extension's tools are present at runtime
-// (a whisper binary, a psql client, …). The daemon rejects FROM and privileged `# intentic:runtime` directives
-// from extension fragments (those stay daemon-owned), and the owner approves the composed overlay + rebuilds
+// A Dockerfile fragment baked into the sandbox image overlay so the extension's tools exist at runtime. The daemon
+// rejects FROM and privileged `# intentic:runtime` directives; the owner approves the composed overlay and rebuild
 // out-of-band.
-/* NO `pack` FIELD HERE, deliberately, though its sibling the `cli` contribution has one. A pack reference is
- * the better way to ask for a tool the sandbox already ships (see that field), but expressing "either a
- * fragment or a pack" here means `fragment` stops being required — and that drops `required: ["fragment"]`
- * from the wire contract, which the lock gate correctly reads as something a client could have relied on. No
- * extension needs it yet: the one manifest using this point asks for an npm package, and a connector wanting
- * a packed tool declares it on its `cli` contribution, which is where the duplication this solves came from.
- * Worth adding the day something needs it, as a declared contract change with a Breaking-Note, rather than
- * spending one now on symmetry. */
+// No `pack` field here: expressing "either a fragment or a pack" would make `fragment` optional, which breaks the wire
+// contract's `required` list. Add one when an extension actually needs it.
 export const EnvironmentContributionSchema = z.object({
     fragment: z
         .string()