@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/dist/lifecycle/manifest.js

@@ -55,6 +55,7 @@
  * caller that reads the file and hands the parsed value here.
  */
 import { isAgentPluginName, MAX_NAME_LENGTH } from '../core/plugin-name.js';
+import { resolveAgentPluginIdentityNamespace } from '../core/identity-namespace.js';
 export { isAgentPluginName } from '../core/plugin-name.js';
 import { readAgentPluginCompatibilityMetadata } from "./compatibility-metadata.js";
 import { parseAgentPluginExports } from './exports.js';
@@ -174,17 +175,18 @@ function collectManifestProblems({ raw, identityNamespace }, { nameError } = {})
 }
 /**
  * Validates an already-`JSON.parse`d `plugin.json` value against the 1.0.0/1.1.0 grammar.
- * Hosts inject identityNamespace; the default retains the existing plugin extension format.
+ * Hosts inject identityNamespace; the default is `jini`, with a legacy-key fallback.
  *
  * @throws Nothing — every failure is reported via the returned `errors`, matching this codebase's
  * own convention for expected validation outcomes (`plugin-runtime/manifest.ts`,
  * `plugin-runtime/discovery.ts`).
  * @complexity O(k + n) time and space in the input keys and keyword entries.
  */
-export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu" } = {}) {
+export function parseAgentPluginManifest({ value }, optional = {}) {
     if (!isJsonObject(value))
         return { ok: false, errors: ["plugin.json must be a JSON object"] };
     const raw = value;
+    const identityNamespace = resolveAgentPluginIdentityNamespace({ value }, optional);
     const nameResult = resolveManifestName(raw);
     const { errors, warnings } = collectManifestProblems({ raw, identityNamespace }, { nameError: nameResult.error });
     if (errors.length > 0)
@@ -406,7 +408,7 @@ function collectMcpConfigErrors({ raw }, { pluginManifest } = {}) {
 }
 /** The per-server metadata `plugin.json` declares under `extensionNamespace`, or `{}` when it declares none. */
 function readExtensionServers({ pluginManifest, extensionNamespace }) {
-    const manifest = parseAgentPluginManifest({ value: pluginManifest });
+    const manifest = parseAgentPluginManifest({ value: pluginManifest }, { identityNamespace: extensionNamespace });
     if (!manifest.ok)
         return {};
     return readAgentPluginExtension({ manifest: manifest.manifest, namespace: extensionNamespace, read: ({ value }) => isJsonObject(value.mcpServers) ? value.mcpServers : {} }) ?? {};

package/dist/lifecycle/node.js

@@ -3,6 +3,7 @@ import { randomInt, randomUUID } from 'node:crypto';
 import os from 'node:os';
 import { performance } from 'node:perf_hooks';
 import { setTimeout } from 'node:timers/promises';
+import { readBootIdentity } from '@jini-ai/platform/fs/file-lock';
 /** Granularity of the uniform [0, 1) value: crypto.randomInt's largest exclusive bound (2^48 - 1). */
 const RANDOM_RESOLUTION = 2 ** 48 - 1;
 /** Opt-in native effects. Layout, fetch, guard, namespace and provisioning remain host-owned. */
@@ -19,6 +20,7 @@ export function createNodeAgentPluginEffects(_required, optional = {}) {
             pid: process.pid,
             platform: process.platform,
             hostname: () => os.hostname(),
+            bootIdentity: () => readBootIdentity({}),
             isAlive: ({ pid }) => {
                 if (!Number.isSafeInteger(pid) || pid <= 0)
                     return false;

package/dist/lifecycle/persistent-state.js

@@ -23,7 +23,7 @@ export function createPersistentStateModule(ports, _optional = {}) {
         assertOwnedPath: (required, optional = {}) => assertPluginStatePath({ ...effects, ...required }, optional),
         migrate: (required, optional = {}) => migratePluginLayout({ ...effects, ...required,
             parsePluginId: ({ value }) => {
-                const parsed = parseAgentPluginManifest({ value });
+                const parsed = parseAgentPluginManifest({ value }, { identityNamespace: ports.extensionNamespace });
                 if (!parsed.ok)
                     throw new Error(parsed.errors.join('; '));
                 return parsed.manifest.name;

package/dist/lifecycle/ports.d.ts

@@ -1,4 +1,5 @@
 import type { Clock, IdGenerator } from "@jini-ai/core/primitives";
+import type { BootIdentity } from "@jini-ai/platform/fs/file-lock";
 import type { AgentPluginServerMetadataReader } from './manifest.js';
 import type { AgentPluginLayoutPort } from './layout.js';
 import type { AgentPluginDeliveryMode, InstalledAgentPlugin } from './types.js';
@@ -24,6 +25,10 @@ export interface AgentPluginProcessPort {
     isAlive(required: {
         readonly pid: number;
     }): boolean;
+    /** The kernel boot this process runs in, recorded in every lock it takes. Without it a lock left by
+     * a killed process is never provably this machine's once the hostname's spelling changes (macOS
+     * `name.lan`/`name.local`), and a never-ageing plugin state lock then wedges every boot. */
+    bootIdentity?(): BootIdentity | undefined;
 }
 /** The host implements federation in its own composition layer. No MCP dependency is required. */
 export interface AgentPluginMcpProvisioningPort {
@@ -85,6 +90,9 @@ export interface AgentPluginLifecyclePorts {
     readonly process: AgentPluginProcessPort;
     readonly layout: AgentPluginLayoutPort;
     readonly productName: string;
+    /** This host's own `extensions` key in plugin.json (README "Extension namespaces"). A plugin
+     * declares one entry per host it supports; the lifecycle reads only this key and never assumes
+     * a particular host's. Publisher ids are kept as declared: no alias, no rewrite between keys. */
     readonly extensionNamespace: string;
     /** Host boot policy may migrate every workspace before seeding the requested workspace.
      * A failure refuses all publication; absent uses the owner's single-workspace migration. */

package/dist/lifecycle/seed-bundled.js

@@ -186,13 +186,16 @@ function buildModule(ports) {
             const packing = typeof optional.packing === 'function'
                 ? await optional.packing({ sourceDir: args.sourceDir, dirName: args.dirName }, {}) : optional.packing;
             const packed = await packAgentPluginDirectory(args.sourceDir, packing);
+            // No revision pruning here, not even of the digest the ledger recorded last boot: that digest
+            // names the bytes this build once published, not what is on disk now, so an operator edit
+            // under it would be deleted. Every same-name copy stays; the ledger selects this build's.
             const installed = await installAgentPlugin({
                 archive: packed.bytes,
                 expectedSha256: packed.sha256,
                 archiveReader: packed.archiveReader ?? createBundledSourceArchiveReader(),
                 layout: args.layout,
                 workspaceId: args.workspaceId,
-            });
+            }, { pruneSupersededRevisions: false });
             const { recorded } = await recordBundledAgentPluginIfAbsent({ workspaceRoot: args.layout.forWorkspace({ workspaceId: args.workspaceId }).root, pluginId: installed.pluginId }, { enabled: ports.seededEnabledPluginIds.has(installed.pluginId) });
             return {
                 pluginId: installed.pluginId,

package/dist/manifest.d.ts

@@ -59,7 +59,7 @@ export interface McpManifest {
 }
 export declare function isMcpManifest(value: unknown): value is McpManifest;
 /** Object-argument facade for the legacy structural validator.
- * Hosts inject identityNamespace; the default retains the existing plugin extension format. */
+ * Hosts inject identityNamespace; the default is `jini`, with a legacy-key fallback. */
 export declare function validatePluginManifest(required: {
     readonly value: unknown;
 }, optional?: {

package/dist/manifest.js

@@ -1,4 +1,5 @@
 import { validatePluginIdentity } from "@jini-ai/core/plugin-directory";
+import { resolveAgentPluginIdentityNamespace } from './core/identity-namespace.js';
 /**
  * Types for the Agent Plugins 1.0.0 open standard (published by a Technical Steering Committee
  * with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel). A plugin is a
@@ -29,9 +30,9 @@ export function isMcpManifest(value) {
     return typeof servers === 'object' && servers !== null && !Array.isArray(servers);
 }
 /** Object-argument facade for the legacy structural validator.
- * Hosts inject identityNamespace; the default retains the existing plugin extension format. */
+ * Hosts inject identityNamespace; the default is `jini`, with a legacy-key fallback. */
 export function validatePluginManifest(required, optional = {}) {
-    return isPluginManifest(required.value) && validatePluginIdentity({ manifest: required.value, namespace: optional.identityNamespace ?? "tovu" }).errors.length === 0;
+    return isPluginManifest(required.value) && validatePluginIdentity({ manifest: required.value, namespace: resolveAgentPluginIdentityNamespace(required, optional) }).errors.length === 0;
 }
 /** Object-argument facade for the legacy structural validator. */
 export function validateMcpManifest(required) {

package/fly/deploy-configs/fly.mjs

@@ -0,0 +1,115 @@
+/**
+ * @file The Fly deploy-config generator: renders `fly.toml` from the host's `DeploymentDescriptor`
+ * (`[build]`, `[env]`, `[[mounts]]`, `[http_service]` with a check on the descriptor's health path).
+ * A host's CI can import this dependency-free module directly (the workflow template's generate
+ * step); there is no checked-in `fly.toml` to read. Host-specific runtime switches arrive in
+ * `options.env` and host notes are appended by the host after render: this module defaults none.
+ *
+ * No enumerated region allow-list here, unlike the Render/Railway renderers: Fly's region catalog is
+ * large (~30 codes) and had no authoritative source to enumerate against without risking rejecting a
+ * real one. Only presence is checked.
+ *
+ * Every quoted sink (`app = "${...}"`, `source = "${...}"`, `primary_region = "${...}"`) goes through
+ * the host kit's `assertNoConfigInjection` first: `--region 'iad"\nprimary_region_evil="x'` once closed
+ * the quoted value early and emitted a real extra `primary_region_evil` key into `fly.toml` (moved
+ * here from the host's kit doc; regression pinned in `__tests__/fly.test.mjs`).
+ *
+ * Plain JS by owner decision (2026-09-29). The host passes the kit: `assertNoConfigInjection`,
+ * `validationError(message)`, `migrationsNote`.
+ */
+
+/**
+ * @typedef {{ readonly name: string, readonly requirement: "boot-blocking" | "recommended" }} DeploymentSecret
+ * @typedef {{ readonly appName: string, readonly port: number, readonly dockerfilePath: string, readonly volumeMountPath: string, readonly volumeName: string, readonly healthCheckPath: string, readonly secrets: readonly DeploymentSecret[] }} DeploymentDescriptor
+ * @typedef {{ readonly region: string, readonly env?: Readonly<Record<string, string>>, readonly buildArgs?: Readonly<Record<string, string>> }} RenderDeployConfigOptions
+ * @typedef {{ readonly assertNoConfigInjection: (fieldLabel: string, value: string) => void, readonly validationError: (message: string) => Error, readonly migrationsNote: string }} DeployConfigKit
+ * @typedef {{ readonly filename: string, readonly contents: string, readonly notes: readonly string[] }} RenderedDeployConfig
+ */
+
+/**
+ * Serializes explicitly supplied non-secret variables as TOML assignments. JSON string quoting
+ * also escapes TOML basic strings, including URLs, backslashes, quotes and control characters.
+ * @param {{ values: Readonly<Record<string, string>>, secrets: readonly DeploymentSecret[], label: string }} input
+ * @param {DeployConfigKit} kit Error factory supplied by the host.
+ * @returns {string} Indented assignments, or an empty string for an empty map.
+ * @throws {Error} For invalid variable names, non-string values or declared secret names.
+ * @complexity O(n + s), where n is the total variable text and s the secret count.
+ */
+function renderVariables({ values, secrets, label }, kit) {
+  const secretNames = new Set(secrets.map(secret => secret.name));
+  return Object.entries(values).map(([name, value]) => {
+    if (!/^[A-Za-z_]\w*$/.test(name) || typeof value !== "string" || secretNames.has(name)) {
+      throw kit.validationError(`${label} must contain only non-secret string variables with valid names`);
+    }
+    // JSON permits a literal DEL character; TOML requires it to be escaped too.
+    return `  ${name} = ${JSON.stringify(value).replace(/\u007f/g, "\\u007f")}\n`;
+  }).join("");
+}
+
+/**
+ * Renders the descriptor and optional non-secret env/build arguments without I/O. The established
+ * three-argument generator port is retained for compatibility with every hosting plugin.
+ * @param {DeploymentDescriptor} descriptor
+ * @param {RenderDeployConfigOptions} options
+ * @param {DeployConfigKit} kit
+ * @returns {RenderedDeployConfig}
+ * @throws {Error} The host's validation error for missing/unsafe identifiers or invalid variables.
+ * @complexity O(n + s), where n is variable text and s the declared secret count.
+ */
+function render(descriptor, options, kit) {
+  const region = options.region.trim();
+  if (!region) {
+    throw kit.validationError("--region is required for --target fly (no default region is assumed)");
+  }
+  kit.assertNoConfigInjection("--region", region);
+  kit.assertNoConfigInjection("the derived Fly app name (fly.toml's app)", descriptor.appName);
+  kit.assertNoConfigInjection("the derived Fly volume name (fly.toml's [[mounts]].source)", descriptor.volumeName);
+
+  const buildArgs = renderVariables({ values: options.buildArgs ?? {}, secrets: descriptor.secrets, label: "buildArgs" }, kit);
+  const env = renderVariables({
+    values: { PORT: String(descriptor.port), ...options.env },
+    secrets: descriptor.secrets,
+    label: "env",
+  }, kit);
+
+  const contents = `app = "${descriptor.appName}"
+primary_region = "${region}"
+
+[build]
+  dockerfile = "${descriptor.dockerfilePath}"
+
+${buildArgs ? `[build.args]\n${buildArgs}\n` : ""}[env]
+${env.trimEnd()}
+
+[[mounts]]
+  source = "${descriptor.volumeName}"
+  destination = "${descriptor.volumeMountPath}"
+
+[http_service]
+  internal_port = ${descriptor.port}
+  force_https = true
+  auto_stop_machines = false
+  auto_start_machines = true
+  min_machines_running = 1
+
+  [[http_service.checks]]
+    grace_period = "60s"
+    interval = "30s"
+    method = "GET"
+    timeout = "5s"
+    path = "${descriptor.healthCheckPath}"
+`;
+
+  const notes = [
+    `Create the volume before the first deploy — this file only MOUNTS it, it does not create it: ` +
+      `fly volumes create ${descriptor.volumeName} --region ${region} -a ${descriptor.appName}`,
+    kit.migrationsNote,
+    ...descriptor.secrets.map(
+      (secret) => `Set ${secret.name} (${secret.requirement}) with: fly secrets set ${secret.name}=<value> -a ${descriptor.appName}`
+    ),
+  ];
+
+  return { filename: "fly.toml", contents, notes };
+}
+
+export default { render };

package/fly/deploy-ops/fly.mjs

@@ -0,0 +1,102 @@
+/** Fly observer and app-secrets adapter. Auth, HTTP policy, bounded responses and audit belong to the host. */
+const text = value => String(value ?? "").slice(0, 2000);
+/** An app is a single path segment; encode only after validation to prevent path injection. */
+function app(ctx, target) {
+  if (typeof target !== "string" || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(target)) ctx.fail("Target must be a Fly app name.");
+  return encodeURIComponent(target);
+}
+/** Reduce mixed machine states without treating unchecked warnings or unknown states as health. */
+function overall(machines) {
+  if (machines.some(m => m.checks?.some(c => c.status === "critical"))) return "failing";
+  if (machines.some(m => ["replacing", "starting", "updating"].includes(m.state))) return "deploying";
+  if (machines.some(m => !["started", "stopped", "suspended", "created", "destroyed", "destroying", "stopping"].includes(m.state))) return "unknown";
+  const started = machines.filter(m => m.state === "started");
+  if (!started.length) return "stopped";
+  return started.every(m => (m.checks ?? []).every(c => c.status === "passing")) ? "healthy" : "unknown";
+}
+/** Prefer the resolved image over a mutable config tag when the Machines API supplies it. */
+function imageRef(machine) {
+  const ref = machine.image_ref;
+  if (typeof ref === "string") return ref;
+  if (ref?.repository) {
+    const registry = ref.registry ? `${ref.registry}/` : "";
+    const tag = ref.tag ? `:${ref.tag}` : "";
+    const digest = ref.digest ? `@${ref.digest}` : "";
+    return `${registry}${ref.repository}${tag}${digest}`;
+  }
+  return machine.config?.image;
+}
+/** Machine checks are optional, but every supplied check must carry a status. @complexity O(checks). */
+function invalidChecks({ checks }, _options = {}) {
+  return checks !== undefined && (!Array.isArray(checks) || checks.some(c => !c || typeof c.status !== "string"));
+}
+/** Return only machine identity/state and a bounded detail with region, image, checks and update time. */
+async function status(ctx, { target }) {
+  const response = await ctx.get(`https://api.machines.dev/v1/apps/${app(ctx, target)}/machines`);
+  if (!Array.isArray(response.json)) ctx.fail("Machine status response must be an array.");
+  if (response.json.some(m => !m || typeof m.id !== "string" || typeof m.state !== "string" || invalidChecks({ checks: m.checks }))) ctx.fail("Machine status response must be an array.");
+  const machines = response.json; const state = overall(machines);
+  return { platform: "fly", target, state, summary: `${machines.length} machines: ${state}`, items: machines.slice(0, 500).map(m => ({ id: text(m.id), state: text(m.state), detail: machineDetail({ machine: m }) })), checkedAt: ctx.nowIso() };
+}
+/** Bounded display detail; check names and statuses use the same per-field cap. @complexity O(checks). */
+function machineDetail({ machine }, _options = {}) {
+  const checks = (machine.checks ?? []).map(c => `${text(c.name)}:${text(c.status)}`).join(",");
+  return text(`region=${text(machine.region)}; image=${text(imageRef(machine))}; checks=${checks}; updated_at=${text(machine.updated_at)}`);
+}
+function flyLogOrigin({ entry }, _options = {}) {
+  return { ...(entry.timestamp || entry.at ? { at: text(entry.timestamp ?? entry.at) } : {}), ...(entry.instance || entry.source ? { source: text(entry.instance ?? entry.source) } : {}) };
+}
+function flyLogLine({ entry }, _options = {}) {
+  if (typeof entry === "string") return { message: text(entry) };
+  return { ...flyLogOrigin({ entry }), ...(entry.level ? { level: text(entry.level) } : {}), message: text(entry.message ?? entry.msg ?? "") };
+}
+/** HTTP logs endpoint not verified live. Accept array, logs wrapper, JSON lines or plain log text. */
+async function logs(ctx, { target, limit }) {
+  const response = await ctx.get(`https://api.fly.io/api/v1/apps/${app(ctx, target)}/logs`);
+  let entries = Array.isArray(response.json) ? response.json : response.json?.logs;
+  if (!Array.isArray(entries)) entries = response.text.split(/\r?\n/).filter(Boolean).map(line => { try { return JSON.parse(line); } catch { return { message: line }; } });
+  if (entries.some(entry => entry === null || (typeof entry !== "string" && (typeof entry !== "object" || Array.isArray(entry))))) ctx.fail("Log response contains an invalid entry.");
+  const lines = entries.slice(0, limit).map(entry => flyLogLine({ entry }));
+  return { platform: "fly", target, lines, truncated: response.truncated === true || entries.length > limit || entries.some(e => String(typeof e === "string" ? e : e.message ?? e.msg ?? "").length > 2000) };
+}
+/** List apps in personal (default) or the explicitly supplied organization. No credential is exposed. */
+async function listTargets(ctx, { org = "personal" } = {}) {
+  const response = await ctx.get(`https://api.machines.dev/v1/apps?org_slug=${encodeURIComponent(org)}`);
+  const apps = Array.isArray(response.json) ? response.json : response.json?.apps;
+  if (!Array.isArray(apps)) ctx.fail("App list response must contain an apps array.");
+  if (apps.some(a => !a || typeof a.name !== "string" || !a.name)) ctx.fail("App list response contains an invalid app.");
+  return { platform: "fly", targets: apps.slice(0, 500).map(a => ({ id: text(a.name), name: text(a.name), ...(a.status ? { state: text(a.status) } : {}) })) };
+}
+/** App secrets live under one Machines API collection; names are env-var shaped before encoding. */
+const secretsUrl = (ctx, target) => `https://api.machines.dev/v1/apps/${app(ctx, target)}/secrets`;
+function secretName(ctx, name) {
+  if (typeof name !== "string" || !/^[A-Za-z_]\w{0,127}$/.test(name)) ctx.fail("Secret name must be an environment variable name.");
+  return encodeURIComponent(name);
+}
+/** Names, Fly digests and update times only. Values are never requested by a listing. */
+async function listSecrets(ctx, { target }) {
+  const response = await ctx.get(secretsUrl(ctx, target));
+  const secrets = Array.isArray(response.json) ? response.json : response.json?.secrets;
+  if (!Array.isArray(secrets) || secrets.some(s => !s || typeof s.name !== "string" || !s.name)) ctx.fail("Secret list response must contain a secrets array.");
+  return { secrets: secrets.slice(0, 500).map(s => ({ name: text(s.name), ...(typeof s.digest === "string" ? { digest: text(s.digest) } : {}), ...(typeof s.updated_at === "string" ? { updatedAt: text(s.updated_at) } : {}) })), truncated: secrets.length > 500 };
+}
+/** Host-only value read for compare/copy. A name absent from the listing is reported, not fetched (Fly 404s it). */
+async function readSecret(ctx, { target, name }) {
+  const encoded = secretName(ctx, name);
+  if (!(await listSecrets(ctx, { target })).secrets.some(s => s.name === name)) return { absent: true };
+  const response = await ctx.get(`${secretsUrl(ctx, target)}/${encoded}?show_secrets=true`);
+  if (typeof response.json?.value !== "string") ctx.fail("Fly did not return the secret's value; the token may lack permission to read secrets.");
+  return { value: response.json.value };
+}
+/** POST stages the value: running machines keep the old one until the next deploy or machine update. */
+async function setSecret(ctx, { target, name, value }) {
+  const response = await ctx.send({ method: "POST", url: `${secretsUrl(ctx, target)}/${secretName(ctx, name)}`, body: { value } });
+  return { ...(Number.isInteger(response.json?.version) ? { version: response.json.version } : {}) };
+}
+/** DELETE is staged the same way; the variable stays in running machines until the next deploy. */
+async function unsetSecret(ctx, { target, name }) {
+  const response = await ctx.send({ method: "DELETE", url: `${secretsUrl(ctx, target)}/${secretName(ctx, name)}` });
+  return { ...(Number.isInteger(response.json?.version) ? { version: response.json.version } : {}) };
+}
+const secretCapabilities = { appliesOn: "next-deploy", supportsStaging: true };
+export default { status, logs, listTargets, secretCapabilities, listSecrets, readSecret, setSecret, unsetSecret };

package/fly/mcp.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {}
+}

package/fly/plugin.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "fly",
+  "version": "1.0.0",
+  "description": "Deploys the host's server to fly.io: one machine only for volume-backed state, secrets never in fly.toml, deploying ships code, not content. Contributes Fly operations, server config generation and the FlyV1 credential scheme.",
+  "author": "Tovu",
+  "license": "Apache-2.0",
+  "extensions": {
+    "tovu": {
+      "vendorAliases": ["FLY_", "fly.io", "flyctl", "fly.toml", "machines.dev", "flyv1"],
+      "displayName": "Fly.io",
+      "summary": "Puts the Tovu server itself online on Fly.io.",
+      "hostSignals": [
+        {
+          "env": "FLY_APP_NAME",
+          "facts": { "hosted": true, "trustProxyHops": 1, "nativeToolsRestricted": true },
+          "label": "Fly.io (FLY_APP_NAME)"
+        },
+        { "env": "FLY_MACHINE_ID", "facts": { "nativeToolsRestricted": true } },
+        { "env": "FLY_ALLOC_ID", "facts": { "nativeToolsRestricted": true } }
+      ],
+      "deploymentAdvice": "Set TOVU_RUNTIME_MODE=production (fly.toml and docker-compose.yml already do).",
+      "id": "tovu/fly",
+      "provides": [
+        "deploy-ops:fly",
+        "deploy-config:fly",
+        "credential-scheme:fly-io"
+      ],
+      "credentialCards": [
+        {
+          "target": "fly",
+          "title": "Connect Fly.io",
+          "label": "fly.io",
+          "ownedApiLabel": "fly.io",
+          "category": "hosting",
+          "intro": "Connect Fly.io to inspect and deploy the Tovu server and manage its Machines.",
+          "usedFor": [
+            "Deploys your Tovu server and checks its status and logs",
+            "Manages the app's running servers",
+            "Creates and manages apps when you grant access to the organization"
+          ],
+          "keyHint": "Use a deploy token scoped to this app. Use an org-scoped token only when creating or managing apps across that organization. In the Fly dashboard, select the app or organization, then Tokens. Avoid the short-lived login auth token.",
+          "saveKind": "api",
+          "additionalHosts": [
+            "https://api.machines.dev"
+          ],
+          "baseUrl": "https://api.fly.io"
+        }
+      ],
+      "toolKeywords": {
+        "credential_save": "fly flyio fly.io fly api token hosting account",
+        "custom_credential_list": "flyio fly.io",
+        "custom_credential_make_request": "fly.io",
+        "custom_credential_verify": "fly.io",
+        "deployment_ops_deploy": "fly",
+        "deployment_ops_list_secrets": "fly",
+        "deployment_ops_list_targets": "fly",
+        "deployment_ops_logs": "fly",
+        "deployment_ops_set_secret": "fly",
+        "deployment_ops_status": "fly fly.io",
+        "deployment_ops_unset_secret": "fly",
+        "search_agent_plugin_local": "fly.io"
+      }
+    }
+  },
+  "keywords": [
+    "deploy",
+    "hosting",
+    "fly",
+    "fly.io",
+    "flyctl",
+    "machines",
+    "server",
+    "volume",
+    "secrets",
+    "readyz",
+    "deploy-ops:fly",
+    "deploy-config:fly",
+    "credential-scheme:fly-io"
+  ]
+}

package/fly/scripts/render-deploy-workflow.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * @file Renders `skills/fly/references/fly-deploy.template.yml` into a GitHub Actions deploy workflow.
+ *
+ * One template serves two readers. An operator's assistant copies it by hand and fills its
+ * `<<PLACEHOLDER: ...>>` values; a host's own production deploy is rendered from it with that host's
+ * values file, so the shared parts of the workflow live here in the Fly plugin and only the host's
+ * own parts live with the host. The host's committed workflow is OUTPUT: the host's drift test
+ * fails while it differs from a fresh render.
+ *
+ * Template regions, one marker per line: `#>> <name>` ... `#<< <name>`. A region holds the operator
+ * default. When the values file names a block for `<name>`, the block's file replaces the whole
+ * region; otherwise the default stays. Regions do not nest. Every placeholder, in the template and
+ * in the blocks, must have a value; a missing one throws rather than shipping a workflow that
+ * deploys `<<PLACEHOLDER: ...>>`.
+ *
+ * Values file (JSON): `{ output, placeholders: { "<<PLACEHOLDER: ...>>": value }, blocks: { name:
+ * "relative/file.yml" } }`. Block paths resolve against the values file's own folder; `output` is
+ * relative to `--repo-root`. Nothing about any host is defaulted here.
+ *
+ * Usage: `node render-deploy-workflow.mjs --values <file> --repo-root <dir> [--check]` writes the
+ * values file's `output`, or with `--check` exits 1 when the committed file differs. A missing
+ * `--values` or `--repo-root` exits 2.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const OPEN = /^#>> ([a-z0-9-]+)$/;
+const CLOSE = /^#<< ([a-z0-9-]+)$/;
+const PLACEHOLDER = /<<PLACEHOLDER:[^>]+>>/g;
+const USAGE = "usage: render-deploy-workflow.mjs --values <file> --repo-root <dir> [--check]";
+
+export const PLUGIN_ROOT = path.resolve(import.meta.dirname, "..");
+export const TEMPLATE_PATH = path.join(PLUGIN_ROOT, "skills", "fly", "references", "fly-deploy.template.yml");
+
+/** Opens a region; a second open before the first closes is a template error. */
+function openRegion({ current, name, lineNumber }) {
+  if (current) throw new Error(`Line ${lineNumber}: region '${name}' opened inside '${current}'`);
+  return name;
+}
+
+function closeRegion({ current, name, lineNumber }) {
+  if (current !== name) throw new Error(`Line ${lineNumber}: '#<< ${name}' does not close an open region`);
+  return null;
+}
+
+function substitute({ line, placeholders }) {
+  return line.replace(PLACEHOLDER, (token) => {
+    if (!Object.hasOwn(placeholders, token)) throw new Error(`No value for ${token}`);
+    return placeholders[token];
+  });
+}
+
+/** A block's text as lines; the file's own trailing newline is not an extra empty line. */
+function blockLines(text) {
+  return text === "" ? [] : text.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n");
+}
+
+/**
+ * Lines one template line contributes: the block on the opening marker of a replaced region,
+ * nothing for any other marker or a replaced default, the line itself otherwise.
+ */
+function emitted({ line, region, open, blocks }) {
+  if (open) return Object.hasOwn(blocks, open) ? blockLines(blocks[open]) : [];
+  if (region !== null && Object.hasOwn(blocks, region)) return [];
+  return [line];
+}
+
+/**
+ * Renders the template text. `placeholders` maps each full `<<PLACEHOLDER: ...>>` token to its value;
+ * `blocks` maps region names to replacement text. A block for a region the template lacks throws,
+ * so a stale values file cannot silently drop a host step.
+ * @complexity O(lines).
+ */
+export function renderDeployWorkflow({ template, placeholders }, { blocks = {} } = {}) {
+  const out = [];
+  const seen = new Set();
+  let region = null;
+  template.replace(/\r\n/g, "\n").split("\n").forEach((line, index) => {
+    const lineNumber = index + 1;
+    const open = OPEN.exec(line)?.[1] ?? null;
+    const close = open ? null : CLOSE.exec(line)?.[1] ?? null;
+    if (close) {
+      region = closeRegion({ current: region, name: close, lineNumber });
+      return;
+    }
+    if (open) {
+      region = openRegion({ current: region, name: open, lineNumber });
+      seen.add(open);
+    }
+    out.push(...emitted({ line, region, open, blocks }));
+  });
+  if (region) throw new Error(`Region '${region}' is never closed`);
+  const unknown = Object.keys(blocks).filter((name) => !seen.has(name));
+  if (unknown.length) throw new Error(`No template region for block(s): ${unknown.join(", ")}`);
+  return out.map((line) => substitute({ line, placeholders })).join("\n");
+}
+
+/** Reads every block file the values name, relative to the values file's folder. */
+function readBlocks({ readFile, valuesPath, blocks = {} }) {
+  const folder = path.dirname(valuesPath);
+  return Object.fromEntries(Object.entries(blocks).map(([name, file]) => [name, readFile(path.resolve(folder, file))]));
+}
+
+/**
+ * Renders a host's workflow from the template and that host's values file.
+ * @complexity O(template lines + block bytes).
+ */
+export function renderFromValues({ readFile, valuesPath }, { templatePath = TEMPLATE_PATH } = {}) {
+  const values = JSON.parse(readFile(valuesPath));
+  const blocks = readBlocks({ readFile, valuesPath, blocks: values.blocks });
+  const contents = renderDeployWorkflow({ template: readFile(templatePath), placeholders: values.placeholders ?? {} }, { blocks });
+  return { output: values.output, contents };
+}
+
+/** The value after `name` in argv, or undefined. */
+function flag(argv, name) {
+  const index = argv.indexOf(name);
+  return index === -1 ? undefined : argv[index + 1];
+}
+
+/** CLI: write (default) or `--check` the rendered workflow. Returns the exit code. */
+export function main({ argv, readFile, writeFile, log }, { templatePath = TEMPLATE_PATH } = {}) {
+  const valuesPath = flag(argv, "--values");
+  const repoRoot = flag(argv, "--repo-root");
+  if (!valuesPath || !repoRoot) {
+    log(USAGE);
+    return 2;
+  }
+  const { output, contents } = renderFromValues({ readFile, valuesPath }, { templatePath });
+  const target = path.join(repoRoot, output);
+  if (!argv.includes("--check")) {
+    writeFile(target, contents);
+    log(`Rendered ${output}`);
+    return 0;
+  }
+  if (readFile(target) === contents) return 0;
+  log(`${output} differs from its render; re-run without --check`);
+  return 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = main({
+    argv: process.argv.slice(2),
+    readFile: (file) => readFileSync(file, "utf8"),
+    writeFile: (file, text) => writeFileSync(file, text),
+    log: (message) => console.log(message),
+  });
+}

package/fly/skills/fly/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: fly
+description: Deploy the host's server to fly.io with no CLI installed (flyctl runs on GitHub's runner) - one machine only for volume-backed state, secrets never in fly.toml, and deploying ships code, not content. Publishing a static export to a host is not this plugin's job - each host is its own plugin.
+---
+
+# Deploy the server to fly.io
+
+Follow the host guidance first: it names the server's own rules (secrets, mount path, port,
+production switch, first-boot steps) and its full procedure. This skill holds what is true for
+any server on Fly.
+
+## Connection card
+
+Choose the card yourself from its `usedFor` list. Reuse a saved key or working sign-in for that
+task. Never offer a replacement unless the person asks.
+
+Open **Connect Fly.io** with `credential_save {kind:"plugin-provider",target:"fly"}` for a new key. The card explains app-scoped deploy tokens and saves the `fly.io` credential with both API origins. In the Fly dashboard select the real app or organization, then **Tokens**; there is no universal app token-creation URL to guess. Only if the person explicitly asks to replace the saved key, rotate the existing row through `credential_save {kind:"api",target:"fly.io"}`.
+
+## Scope
+
+This plugin deploys **the server itself** (app, admin, database), not a static export. Static hosts
+are their own plugins.
+
+## Deploying to fly.io
+
+The server goes on one fly.io machine through a GitHub Actions workflow, so nobody installs flyctl
+or Docker. Say first: deploying ships code, not content. Rules that generic fly.io advice gets wrong:
+
+- **One machine only** when state lives on a Fly volume (SQLite): a volume attaches to one machine,
+  so a second machine gets its own divergent database. Never scale above 1 or autoscale.
+- **The volume hides the image's files at its mount path.** Nothing the server reads at boot may
+  live there in the image.
+- **Secrets go through `flyctl secrets set`**, never `fly.toml`, which is committed and public.
+- **The volume exists before the first deploy.** The workflow mounts it; it does not create it.
+
+The two templates the procedure writes are `references/fly.template.toml` and
+`references/fly-deploy.template.yml` (read them with this plugin's own tool,
+`file: "references/<name>"`). Every `<<PLACEHOLDER: ...>>` must be replaced; re-read the written
+files and confirm none survives. Every GitHub step belongs to the host's GitHub plugin.
+
+## When it fails
+
+Explain the cause in one plain sentence and the one next step.