@domesystems/templates 0.1.1 → 0.2.0

package/README.md

@@ -1,168 +1,59 @@
-# Dome templates
+# Dome Templates CLI
 
-Reusable, importable governed-agent templates. Each template combines an HCL
-configuration bundle for Dome with an optional companion application.
+Download, configure, and run governed-agent templates from the Dome Template
+Library. The package contains no template source: each template is fetched as a
+versioned ZIP archive from the Library when you run `init` or `up`.
 
-## Use the template CLI
+## Install and run
 
-The public package is also an executable. It copies the template, creates a
-local `.env` from `.env.example`, and generates the Compose file from the
-runtime declaration in `template.yaml` — individual templates do not need a
-Dockerfile or a committed Compose file.
+Use `npx`; Node.js 20 or newer is required.
 
 ```bash
-# Create a working copy in ./ai-agent-for-documentation.
+# Download a template into ./ai-agent-for-documentation.
 npx @domesystems/templates init ai-agent-for-documentation
 
-# Initialize when needed, provision Dome, then start the selected runtime.
+# Download if needed, provision Dome, and run it locally.
 npx @domesystems/templates up ai-agent-for-documentation
 ```
 
-`up` runs `dome import dome.tf`, then `docker compose` with a generated,
-Git-ignored `.dome-compose.yaml`. Use `--no-start` to provision without
-starting a container, `--skip-provision` to start an already-provisioned
-template, `--detach` for a background container, and `--dir <directory>` to
-choose a local destination.
+By default, archives come from
+`https://templates.domesystems.ai/templates/downloads/<template>.zip`.
 
-Runtime selection is explicit rather than guessed:
-
-```yaml
-app:
-  runtime:
-    pattern: chat         # chat or run
-    language: python      # python or typescript
-    image_tag: "0.1.0"    # optional; defaults to latest
-```
-
-The CLI maps `language` and `pattern` to a shared, published runtime image.
-For an unusual runtime, set `app.runtime.image` to a complete image reference
-(including its tag) to override that mapping.
-Add a template directory to the package's `files` list when publishing a new
-template so the CLI can discover it.
-
-## Use a template
+For local Library development, point the CLI at a local download server:
 
 ```bash
-git clone https://github.com/dome-systems/templates.git
-cd templates/<template>
-
-brew install dome-systems/tap/dome
-dome auth login
-dome sandbox provision
-
-# Preview resources, variables, and required permissions. Changes nothing.
-dome import dome.tf --plan-only
-
-# Apply after reviewing the preview. Dome prompts for required variables.
-dome import dome.tf
+DOME_TEMPLATES_BASE_URL=http://localhost:3001/templates/downloads \
+  npx @domesystems/templates init ai-agent-for-documentation
 ```
 
-Imports run as asynchronous jobs in Dome. Existing resources are converged by
-name, missing resources are created, and any destructive replacement is
-refused. Secrets are input variables: they are never committed to a template
-or returned in an export.
-
-Every built companion app needs the one-time agent token created by the import:
-
-```bash
-dome import outputs <job-id>
-cp .env.example .env
-docker compose up
-```
-
-Tool and model credentials remain in Dome; the app only holds its agent token.
-
-### Runtime image
-
-Templates do not build a runtime themselves. In development, clone the sibling
-`dome-systems/template-runtime` repository and build the archetype image before
-starting a template:
-
-```bash
-cd template-runtime
-docker build -f Dockerfile.chat -t ghcr.io/dome-systems/runtime-py-chat:dev .
-docker build -f Dockerfile.run -t ghcr.io/dome-systems/runtime-py-run:dev .
-```
-
-TypeScript equivalents are available as `ghcr.io/dome-systems/runtime-ts-chat`
-and `ghcr.io/dome-systems/runtime-ts-run`; substitute either image in a template's Compose file
-when using the Node runtime.
-
-The CLI-generated Compose configuration uses the appropriate image and mounts
-only the template's local `app/` configuration. Release templates should set a
-versioned `app.runtime.image_tag` rather than relying on `latest`.
+## Commands
 
-## Runtime contract
-
-Every built companion app follows the same small operational contract:
-
-| Surface | Guarantee |
-|---|---|
-| `.env.example` | The complete committed list of values a local operator may need. It contains names and setup guidance, never real values. |
-| `docker-compose.yml` | Starts the app on port `3000`, loads `.env`, mounts `app/` read-only, and declares the health check. |
-| `GET /health` | Liveness only: returns `200 {"status":"ok"}` without calling Dome or an upstream system. Offline mode is valid. `/healthz` is an equivalent compatibility alias. |
-| `GET /readyz` | Readiness of the initialized runtime API. Returns `200`; its `mode` is `live` or `offline`. |
-| Docker `HEALTHCHECK` | Probes `/health`; inherited by every shared runtime image and repeated in Compose for a visible local contract. |
-
-The Library renders each template's committed `.env.example` verbatim, so setup
-requirements have one source of truth. Add a new variable there when the
-companion app needs it; use `app.options.env` in `template.yaml` as well when
-that value is interpolated into an agent prompt, starter, or help text.
-
-## Archetype containers
-
-The separate `dome-systems/template-runtime` repository builds one image per app
-shape. They contain no template-specific code — a template mounts an
-`app/agent.yaml` giving its **prompt**, its **skills** and its **invoker**, which
-is the shape the Dome agent runtime will take, so swapping a container for the
-real runner is a config move rather than a rewrite.
-
-Four UIs cover all 249 templates. A report is a run whose output is a table; an approval
-console is a queue with two extra buttons.
-
-| Archetype | Covers | Shapes | State |
-|---|---|---|---|
-| `ghcr.io/dome-systems/runtime-py-chat` | 66 | interactive-assistant | Built |
-| `ghcr.io/dome-systems/runtime-py-run` | 120 | scheduled-job, report-dashboard | Built |
-| `dome/template-queue` | 48 | triage-queue, approval-console | Not built |
-| `dome/template-console` | 15 | external-service, developer-harness | Not built |
-
-The governance drawer is shared chrome across all four, not a per-archetype feature.
-
-Tools go through the Gateway over MCP; models go through the Broker's
-Anthropic-compatible ingress. Both authenticate with the same agent token, which is why
-the container holds one secret and no provider key. Without `DOME_TOKEN` it starts in
-offline mode: the chrome works and the allow-list is still enforced, but tools and model
-are simulated.
-
-## What is source and what is generated
-
-`dome.tf` is the configuration source of truth for Dome resources. It is a
-portable HCL bundle that `dome import` can inspect, preview, and apply.
-`template.yaml` is catalog metadata and the source of truth for choosing the
-shared local runtime; `rules/*.cedar` and `app/instructions.md` are
-human-authored source.
-
-## Relationship to the Template Library
-
-This repository is the Library's only template-content source. A merge to `main`
-dispatches its commit SHA to `dome-systems/web-library`; that repository checks out
-and builds the exact revision, then opens or updates one source-refresh PR. The
-Library does not copy or edit template content, and a refresh PR must be merged
-before the new source can be published.
-
-The dispatch uses the `LIBRARY_SOURCE_SYNC_TOKEN` repository secret. It needs a
-fine-grained token that may dispatch workflows in `dome-systems/web-library`.
-
-## Validation
-
-Run the metadata and source-reference checks locally:
-
-```bash
-npm install
-npm run validate
-terraform fmt -check -recursive
+```text
+npx @domesystems/templates init <template> [--dir <directory>] [--force]
+npx @domesystems/templates up <template> [--dir <directory>] [--port <host-port>] [--skip-provision] [--provision] [--no-start] [--detach] [--verbose] [--force]
 ```
 
-CI runs the same checks. A plan-only import against a designated Dome sandbox can
-be added when CI has an appropriate non-production workspace and credentials.
+| Command | Option | What it does |
+|---|---|---|
+| `init` | `--dir <directory>` | Downloads into this directory. Defaults to `./<template>`. |
+| `init` | `--force` | Allows a non-empty destination; downloaded source files can replace existing files. |
+| `up` | `--dir <directory>` | Uses this existing template directory, or downloads it when it does not exist. |
+| `up` | `--port <host-port>` | Publishes the runtime at `http://localhost:<host-port>`; default `3000`. |
+| `up` | `--skip-provision` | Does not run `dome import`. |
+| `up` | `--provision` | Re-imports Dome resources even when local credentials already exist. |
+| `up` | `--no-start` | Does not start Docker after setup. |
+| `up` | `--detach` | Starts Docker Compose in the background. |
+| `up` | `--verbose` | Shows generated Compose details and the full Dome import response. |
+| `up` | `--force` | Allows a non-empty destination only when `up` needs to download it. |
+
+`up` reuses a configured `.env` by default, so routine restarts do not import
+resources again. Use `--provision` after changing the template’s Dome
+resources. Status markers are colored in compatible terminals; set `NO_COLOR=1`
+to turn colors off.
+
+## Security and source
+
+The CLI accepts only archives whose contents live below the requested template
+directory. It rejects traversal paths, unsupported archive entries, oversized
+downloads, and archives without `template.yaml` before copying files into your
+project. The Template Library controls the ZIP contents and current revision.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@domesystems/templates",
-  "version": "0.1.1",
-  "description": "Initialize and run Dome governed-agent templates.",
+  "version": "0.2.0",
+  "description": "Download, initialize, and run Dome governed-agent templates.",
   "type": "module",
   "bin": {
     "dome-templates": "bin/dome-templates.mjs"
@@ -9,9 +9,7 @@
   "files": [
     "bin",
     "src",
-    "ai-agent-for-documentation",
-    "ai-agent-for-notion",
-    "ai-agent-for-release-notes"
+    "README.md"
   ],
   "engines": {
     "node": ">=20"
@@ -24,6 +22,8 @@
     "test": "node --test"
   },
   "dependencies": {
+    "unzipper": "0.12.3",
+    "unzipper": "0.12.3",
     "yaml": "2.9.0"
   }
 }

package/src/cli.mjs

@@ -1,16 +1,29 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import readline from "node:readline/promises";
 import { readManifest } from "./manifest.mjs";
 import { imageForRuntime, renderCompose } from "./runtime.mjs";
-import { copyTemplate, initializeEnvironment } from "./template-files.mjs";
+import { downloadTemplate, initializeEnvironment } from "./template-files.mjs";
 
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function color(code, text) {
+  return supportsColor ? `\u001B[${code}m${text}\u001B[0m` : text;
+}
+
+function status(kind, message) {
+  const styles = {
+    info: ["●", "36"],
+    success: ["✓", "32"],
+    warning: ["→", "33"],
+  };
+  const [marker, code] = styles[kind];
+  return `${color(code, marker)} ${message}`;
+}
 
 function usage() {
-  return `Usage:\n  npx @domesystems/templates init <template> [--dir <directory>] [--force]\n  npx @domesystems/templates up <template> [--dir <directory>] [--skip-provision] [--no-start] [--detach] [--force]\n\nCommands:\n  init  Copy a template locally and create .env from .env.example.\n  up    Initialize (when needed), generate Compose from template.yaml, provision Dome, and start it.\n\nThe generated .dome-compose.yaml is ignored by Git. Runtime images are selected\nfrom app.runtime.language and app.runtime.pattern in template.yaml.\n`;
+  return `Usage:\n  npx @domesystems/templates init <template> [--dir <directory>] [--force]\n  npx @domesystems/templates up <template> [--dir <directory>] [--port <host-port>] [--skip-provision] [--provision] [--no-start] [--detach] [--verbose] [--force]\n\nCommands:\n  init  Download a template locally and create .env from .env.example.\n  up    Download when needed, generate Compose from template.yaml, provision Dome, and start it.\n\nTemplates are downloaded from templates.domesystems.ai by default. A configured\nlocal .env skips provisioning automatically. Use --provision to re-sync\nexisting resources. Use --port to choose the local host port (default: 3000).\nThe generated .dome-compose.yaml is ignored by Git. Use --verbose to show the\nfull Dome import response for troubleshooting.\n`;
 }
 
 function fail(message) {
@@ -20,13 +33,21 @@ function fail(message) {
 function parseArguments(argv) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) return { help: true };
   const [command, slug, ...rest] = argv;
-  const options = { force: false, provision: true, start: true, detach: false, directory: undefined };
+  const options = { force: false, provision: true, forceProvision: false, start: true, detach: false, verbose: false, directory: undefined, port: 3000 };
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
     if (argument === "--force") options.force = true;
     else if (argument === "--skip-provision") options.provision = false;
+    else if (argument === "--provision") options.forceProvision = true;
     else if (argument === "--no-start") options.start = false;
     else if (argument === "--detach") options.detach = true;
+    else if (argument === "--verbose") options.verbose = true;
+    else if (argument === "--port") {
+      const port = Number(rest[index + 1]);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) fail("--port requires an integer from 1 to 65535.");
+      options.port = port;
+      index += 1;
+    }
     else if (argument === "--dir") {
       options.directory = rest[index + 1];
       if (!options.directory) fail("--dir requires a directory.");
@@ -40,15 +61,10 @@ function parseArguments(argv) {
   return { command, slug, options };
 }
 
-function templateSource(slug) {
+function validateTemplateSlug(slug) {
   if (slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") {
     fail(`Invalid template slug: ${slug}`);
   }
-  const source = path.join(packageRoot, slug);
-  if (!fs.statSync(path.join(source, "template.yaml"), { throwIfNoEntry: false })?.isFile()) {
-    fail(`Unknown template: ${slug}`);
-  }
-  return source;
 }
 
 function targetDirectory(slug, directory) {
@@ -59,15 +75,19 @@ function isEmpty(directory) {
   return !fs.existsSync(directory) || fs.readdirSync(directory).length === 0;
 }
 
-function init(slug, options, output) {
-  const source = templateSource(slug);
+async function init(slug, options, output, fetchImplementation) {
+  validateTemplateSlug(slug);
   const target = targetDirectory(slug, options.directory);
   if (!isEmpty(target) && !options.force) {
     throw new Error(`${target} already exists and is not empty. Choose --dir or pass --force.`);
   }
-  copyTemplate(source, target);
+  output(status("info", `Downloading ${slug}…`));
+  const archiveURL = await downloadTemplate(slug, target, {
+    baseURL: process.env.DOME_TEMPLATES_BASE_URL,
+    fetchImplementation,
+  });
   const environmentCreated = initializeEnvironment(target);
-  output(`Initialized ${slug} in ${target}.`);
+  output(status("success", `Downloaded ${slug} from ${archiveURL}.`));
   if (environmentCreated) {
     output("Created .env from .env.example.");
     output("When you run `up`, Dome will prompt for import credentials; they are never written to .env.");
@@ -76,10 +96,18 @@ function init(slug, options, output) {
   return target;
 }
 
-function resolveUpDirectory(slug, options, output) {
+async function resolveUpDirectory(slug, options, output, fetchImplementation) {
   const target = targetDirectory(slug, options.directory);
-  if (fs.statSync(path.join(target, "template.yaml"), { throwIfNoEntry: false })?.isFile()) return target;
-  return init(slug, options, output);
+  if (fs.statSync(path.join(target, "template.yaml"), { throwIfNoEntry: false })?.isFile()) {
+    const environmentCreated = initializeEnvironment(target);
+    if (environmentCreated) {
+      output("Created .env from .env.example.");
+      output("When you run `up`, Dome will prompt for import credentials; they are never written to .env.");
+      output("After import, `up` writes DOME_TOKEN and DOME_GATEWAY_URL into .env. Add any other template-specific runtime values before starting.");
+    }
+    return target;
+  }
+  return init(slug, options, output, fetchImplementation);
 }
 
 function run(command, args, cwd) {
@@ -104,10 +132,24 @@ function runJSON(command, args, cwd, { displayOutput = true } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, { cwd, stdio: ["inherit", "pipe", "inherit"] });
     let output = "";
+    let displayed = 0;
     child.stdout.on("data", (chunk) => {
       const text = chunk.toString();
       output += text;
-      if (displayOutput) process.stdout.write(text);
+      if (displayOutput === true) {
+        process.stdout.write(text);
+        displayed = output.length;
+      } else if (displayOutput === "before-final-json") {
+        const match = /(?:^|\n)\{/.exec(output);
+        if (match) {
+          const jsonStart = match.index + (match[0][0] === "\n" ? 1 : 0);
+          if (jsonStart > displayed) process.stdout.write(output.slice(displayed, jsonStart));
+          displayed = jsonStart;
+        } else {
+          process.stdout.write(text);
+          displayed = output.length;
+        }
+      }
     });
     child.on("error", (error) => reject(new Error(`Could not run ${command}: ${error.message}`)));
     child.on("close", (status) => {
@@ -124,6 +166,15 @@ function runJSON(command, args, cwd, { displayOutput = true } = {}) {
   });
 }
 
+function importSummary(response) {
+  const results = response.data?.job?.results ?? [];
+  const counts = new Map();
+  for (const result of results) counts.set(result.action, (counts.get(result.action) ?? 0) + 1);
+  if (counts.size === 0) return "Dome import completed.";
+  const descriptions = [...counts].map(([action, count]) => `${count} ${action}${count === 1 ? "" : "s"}`);
+  return `Dome import complete: ${descriptions.join(", ")}.`;
+}
+
 function replaceEnvironmentValue(source, name, value) {
   const expression = new RegExp(`^${name}=.*$`, "m");
   if (!expression.test(source)) throw new Error(`The runtime .env is missing ${name}.`);
@@ -137,6 +188,16 @@ function undefinedEnvironmentValues(source) {
     .filter(Boolean);
 }
 
+function runtimeEnvironmentIsConfigured(target) {
+  const environmentPath = path.join(target, ".env");
+  if (!fs.statSync(environmentPath, { throwIfNoEntry: false })?.isFile()) return false;
+  const environment = fs.readFileSync(environmentPath, "utf8");
+  const missing = new Set(undefinedEnvironmentValues(environment));
+  return ["DOME_TOKEN", "DOME_GATEWAY_URL"].every(
+    (name) => new RegExp(`^${name}=`, "m").test(environment) && !missing.has(name),
+  );
+}
+
 async function fillRuntimeEnvironment(target, output) {
   const environmentPath = path.join(target, ".env");
   let environment = fs.readFileSync(environmentPath, "utf8");
@@ -198,7 +259,7 @@ async function writeRuntimeEnvironment(target, manifest, importResponse, output)
   output(`Configured ${environmentPath} with the one-time agent token and Gateway URL.`);
 }
 
-export async function main(argv, { output = console.log, error = console.error } = {}) {
+export async function main(argv, { output = console.log, error = console.error, fetchImplementation = globalThis.fetch } = {}) {
   try {
     const parsed = parseArguments(argv);
     if (parsed.help) {
@@ -207,22 +268,35 @@ export async function main(argv, { output = console.log, error = console.error }
     }
     const { command, slug, options } = parsed;
     if (command === "init") {
-      init(slug, options, output);
+      await init(slug, options, output, fetchImplementation);
       return;
     }
 
-    const target = resolveUpDirectory(slug, options, output);
+    const target = await resolveUpDirectory(slug, options, output, fetchImplementation);
     const manifest = readManifest(target);
     const composePath = path.join(target, ".dome-compose.yaml");
-    fs.writeFileSync(composePath, renderCompose(manifest.app.runtime));
-    output(`Generated ${path.basename(composePath)} using ${imageForRuntime(manifest.app.runtime)}.`);
+    fs.writeFileSync(composePath, renderCompose(manifest.app.runtime, options.port));
+    if (options.verbose) {
+      output(status("info", `Generated ${path.basename(composePath)} with ${imageForRuntime(manifest.app.runtime)} for http://localhost:${options.port}.`));
+    }
 
-    if (options.provision) {
-      const imported = await runJSON("dome", ["import", "dome.tf", "--format", "json"], target);
+    const alreadyProvisioned = runtimeEnvironmentIsConfigured(target);
+    if (options.provision && alreadyProvisioned && !options.forceProvision) {
+      const nextStep = options.start
+        ? "Dome is already set up — starting the app. To update Dome resources later, use --provision."
+        : "Dome is already set up. To update Dome resources later, use --provision.";
+      output(status("success", nextStep));
+    } else if (options.provision) {
+      output(status("info", "Setting up Dome resources…"));
+      const imported = await runJSON("dome", ["import", "dome.tf", "--format", "json"], target, {
+        displayOutput: options.verbose ? true : "before-final-json",
+      });
+      if (!options.verbose) output(status("success", importSummary(imported)));
       await writeRuntimeEnvironment(target, manifest, imported, output);
     }
     if (options.start) {
       await fillRuntimeEnvironment(target, output);
+      output(status("info", `Starting app at http://localhost:${options.port}…`));
       const args = ["compose", "-f", ".dome-compose.yaml", "up"];
       if (options.detach) args.push("--detach");
       run("docker", args, target);

package/src/runtime.mjs

@@ -16,7 +16,7 @@ export function imageForRuntime(runtime) {
   return `${image}:${runtime.image_tag ?? "latest"}`;
 }
 
-export function renderCompose(runtime) {
+export function renderCompose(runtime, hostPort = 3000) {
   const image = imageForRuntime(runtime);
-  return `# Generated by @domesystems/templates. Do not edit; update template.yaml instead.\nservices:\n  app:\n    image: ${image}\n    env_file: .env\n    volumes:\n      - ./app:/config:ro\n    ports:\n      - \"3000:3000\"\n    healthcheck:\n      test: [\"CMD\", \"python\", \"-c\", \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:3000/health', timeout=2)\"]\n      interval: 30s\n      timeout: 3s\n      start_period: 10s\n      retries: 3\n`;
+  return `# Generated by @domesystems/templates. Do not edit; update template.yaml instead.\nservices:\n  app:\n    image: ${image}\n    env_file: .env\n    volumes:\n      - ./app:/config:ro\n    ports:\n      - \"${hostPort}:3000\"\n    healthcheck:\n      test: [\"CMD\", \"python\", \"-c\", \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:3000/health', timeout=2)\"]\n      interval: 30s\n      timeout: 3s\n      start_period: 10s\n      retries: 3\n`;
 }

package/src/template-files.mjs

@@ -1,7 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import unzipper from "unzipper";
 
 const excludedNames = new Set([".env", ".git", ".terraform", "node_modules", "docker-compose.yml", ".dome-compose.yaml"]);
+const maximumArchiveBytes = 50 * 1024 * 1024;
+const maximumExtractedBytes = 100 * 1024 * 1024;
+
+function archivePath(relative) {
+  const normalized = relative.replaceAll("\\", "/");
+  const withoutTrailingSlash = normalized.replace(/\/+$/, "");
+  if (!withoutTrailingSlash || normalized.startsWith("/") || normalized.includes("\0") || withoutTrailingSlash.split("/").some((part) => part === "." || part === "..")) {
+    throw new Error(`Template archive contains an unsafe path: ${relative}`);
+  }
+  return withoutTrailingSlash;
+}
+
+function relativeArchivePath(entryPath, slug) {
+  const normalized = archivePath(entryPath);
+  if (normalized === slug) return undefined;
+  const prefix = `${slug}/`;
+  if (!normalized.startsWith(prefix)) throw new Error(`Template archive must contain files under ${prefix}`);
+  const relative = normalized.slice(prefix.length);
+  if (!relative) throw new Error("Template archive contains an invalid empty path.");
+  return relative;
+}
 
 export function copyTemplate(source, destination) {
   fs.mkdirSync(destination, { recursive: true });
@@ -26,3 +49,52 @@ export function initializeEnvironment(templateDirectory) {
   }
   return false;
 }
+
+export async function downloadTemplate(slug, destination, { baseURL, fetchImplementation = globalThis.fetch } = {}) {
+  const archiveURL = new URL(`${slug}.zip`, `${(baseURL ?? "https://templates.domesystems.ai/templates/downloads").replace(/\/$/, "")}/`);
+  const response = await fetchImplementation(archiveURL, { headers: { accept: "application/zip" } });
+  if (!response.ok) throw new Error(`Could not download ${slug}: ${response.status} ${response.statusText}.`);
+
+  const archive = Buffer.from(await response.arrayBuffer());
+  if (archive.length === 0 || archive.length > maximumArchiveBytes) throw new Error(`Template archive must be between 1 byte and ${maximumArchiveBytes / 1024 / 1024} MiB.`);
+
+  let directory;
+  try {
+    directory = await unzipper.Open.buffer(archive);
+  } catch {
+    throw new Error(`Downloaded ${slug} is not a valid ZIP archive.`);
+  }
+
+  let extractedBytes = 0;
+  const entries = directory.files
+    .map((entry) => ({ entry, relative: relativeArchivePath(entry.path, slug) }))
+    .filter(({ relative }) => relative !== undefined);
+  for (const { entry, relative } of entries) {
+    if (entry.type !== "File" && entry.type !== "Directory") throw new Error(`Template archive contains an unsupported entry: ${relative}`);
+    if (entry.type === "File") {
+      extractedBytes += entry.uncompressedSize;
+      if (extractedBytes > maximumExtractedBytes) throw new Error(`Template archive expands beyond ${maximumExtractedBytes / 1024 / 1024} MiB.`);
+    }
+  }
+
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), "dome-template-"));
+  try {
+    const source = path.join(staging, slug);
+    for (const { entry, relative } of entries) {
+      const target = path.join(source, relative);
+      if (entry.type === "Directory") {
+        fs.mkdirSync(target, { recursive: true });
+      } else {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, await entry.buffer());
+      }
+    }
+    if (!fs.statSync(path.join(source, "template.yaml"), { throwIfNoEntry: false })?.isFile()) {
+      throw new Error(`Downloaded ${slug} does not contain template.yaml.`);
+    }
+    copyTemplate(source, destination);
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+  return archiveURL.toString();
+}

package/ai-agent-for-documentation/.env.example

@@ -1,12 +0,0 @@
-# The container holds exactly one secret.
-#
-# Tool credentials went into Dome when dome import ran and live behind the gateway.
-# The provider key lives with the Broker. Neither is here, and neither should be.
-
-# Revealed once after import: dome import outputs <job-id>
-DOME_TOKEN=
-
-# The gateway ROOT — not a bare host, and not the /mcp path.
-# Copy the "Gateway URL" from the command above. The container derives
-# /mcp for tools and /v1/messages for models from it.
-DOME_GATEWAY_URL=

package/ai-agent-for-documentation/app/agent.yaml

@@ -1,31 +0,0 @@
-name: docs-answerer
-title: Ask questions about product documentation
-summary: "A chat agent that answers questions from the Dome Platform documentation.\
-  \ Nothing to set up upstream \u2014 the documentation MCP server takes no credential,\
-  \ so this reaches a real system on the first run. The connection carries three tools.\
-  \ Two answer questions. The third returns the whole documentation index, and the\
-  \ agent will reach for it \u2014 Dome refuses, and names the rule that refused it."
-shape: interactive-assistant
-prompt_file: instructions.md
-help_file: help.md
-model: claude-haiku-4-5-20251001
-pool: docs-pool
-max_tokens: 4096
-skills:
-- name: answer-from-documentation
-  description: Search the documentation, read the most relevant pages, answer from
-    them.
-  tools:
-  - domedocs/search
-  - domedocs/get_page
-  - domedocs/list_pages
-invoker:
-  kind: chat
-options:
-  identity:
-    mode: none
-  model:
-    provider: anthropic
-    model: claude-haiku-4-5-20251001
-forbidden:
-- domedocs/list_pages

package/ai-agent-for-documentation/app/help.md

@@ -1,19 +0,0 @@
-Ask a question about the Dome Platform in plain language. The agent searches the
-public documentation at `docs.domesystems.ai`, reads the pages it finds, and
-answers from them.
-
-**Nothing to set up upstream.** The documentation MCP server takes no
-credential, so this template reaches a real system on its first run. The only
-key the workspace needs is a model provider key — every template needs one —
-and it goes to Dome, not into this container.
-
-**Ask something broad.** "What is Dome" or "what does the gateway do". The agent
-will reach for the documentation index to orient itself, that call will come
-back refused, and you will watch it fall back to search and answer anyway. The
-refusal is the rule, not the prompt.
-
-**Show detail** in the header opens the design: the topology, which tools are
-permitted, and the instructions the model was given.
-
-Nothing here is the record. Every call, allowed or refused, is in the audit log
-in Dome.

package/ai-agent-for-documentation/app/instructions.md

@@ -1,21 +0,0 @@
-You answer questions about the Dome Platform from its documentation.
-
-Work like this:
-
-1. If the question is broad — "what is Dome", "how does authorization work" —
-   start from the documentation index to see what exists.
-2. Search the documentation for the terms in the question. Search results carry
-   the path of every page they match.
-3. Read pages rather than searching repeatedly. Two or three searches is
-   plenty; after that, open the most promising pages in full **using the paths
-   the search results gave you**. Do not invent a path and try it.
-4. Answer from what you read, and name the pages you used.
-
-If the documentation does not contain the answer, say so plainly. Do not fill
-the gap from general knowledge — a confident answer that is not in the
-documentation is worse than no answer, because the reader cannot tell the
-difference.
-
-Use whatever tools you have been given, and do not decline a request on the
-assumption that you lack permission. If a call comes back refused, say what came
-back and carry on with the tools that do work.