@intelligo-dev/cli 1.0.0-beta.1 → 1.0.0-beta.13

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @intelligo-dev/cli — operational commands for an Intelligo application.
+ *
+ * Exported as functions as well as a binary so CI can call the checks
+ * directly (see the migration-chain gate) without shelling out.
+ */
+
+export {
+  runChecks,
+  formatResults,
+  exitCodeFor,
+  type CheckResult,
+  type DoctorOptions,
+} from "./commands/doctor.js";
+
+export {
+  migrateCheck,
+  hashMigration,
+  formatMigrateCheck,
+  migrateCheckExitCode,
+  type MigrateCheckResult,
+} from "./commands/migrate-check.js";
+
+export {
+  readMigrationChain,
+  inspectMigrationChain,
+  type MigrationChain,
+  type ChainProblem,
+} from "./migrations.js";
+
+/**
+ * Where the framework's chain lives. Exported because a consumer's own
+ * operational scripts — baselining a push-provisioned database, a
+ * one-off audit — otherwise hardcode
+ * `node_modules/@intelligo-dev/core/src/db/migrations`, which is right
+ * in an application and wrong in the framework repository, and which
+ * silently stops being either if the package layout ever changes.
+ */
+export { resolveMigrationsDir, MIGRATION_LOCATIONS } from "./migrations-dir.js";

package/src/manifest.ts

@@ -0,0 +1,93 @@
+/**
+ * Generated-source manifest.
+ *
+ * Intelligo generates starting source into the consumer's repository
+ * and then stops owning it. That promise needs a mechanism,
+ * because "never overwrite a customized file" requires knowing which
+ * files were generated, from which template version, and whether the
+ * consumer has since edited them.
+ *
+ * The manifest records a content hash per generated file at the moment
+ * it was written. A file whose hash still matches was not touched and
+ * can be re-generated safely; one whose hash differs is the consumer's
+ * code now, and an upgrade may only show them a diff.
+ *
+ * Deliberately not a lockfile of package versions: it tracks template
+ * provenance, not dependencies.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export const MANIFEST_FILE = "intelligo.manifest.json";
+
+export type GeneratedFile = {
+  /** Path relative to the consumer application root. */
+  path: string;
+  /** sha256 of the contents Intelligo wrote. */
+  hash: string;
+};
+
+export type FeatureEntry = {
+  templateVersion: string;
+  files: GeneratedFile[];
+  /**
+   * Placeholder substitutions the files were generated with
+   * (`__APP_NAME__` → "acme"). Recorded so an upgrade check can hash the
+   * template *as it would be written for this app*; the raw template
+   * would make every substituted file look permanently outdated.
+   */
+  variables?: Record<string, string>;
+};
+
+export type Manifest = {
+  schemaVersion: 1;
+  frameworkVersion: string;
+  features: Record<string, FeatureEntry>;
+};
+
+export function hashContents(contents: string): string {
+  return createHash("sha256").update(contents).digest("hex");
+}
+
+export function emptyManifest(frameworkVersion: string): Manifest {
+  return { schemaVersion: 1, frameworkVersion, features: {} };
+}
+
+export function readManifest(appRoot: string): Manifest | null {
+  const file = path.join(appRoot, MANIFEST_FILE);
+  if (!existsSync(file)) return null;
+  return JSON.parse(readFileSync(file, "utf8")) as Manifest;
+}
+
+export function writeManifest(appRoot: string, manifest: Manifest): void {
+  writeFileSync(
+    path.join(appRoot, MANIFEST_FILE),
+    `${JSON.stringify(manifest, null, 2)}\n`
+  );
+}
+
+/**
+ * Record a feature's generated files, replacing any previous entry for
+ * the same feature — re-generating is how a consumer accepts a new
+ * template version, and the recorded hashes must then describe what is
+ * actually on disk.
+ */
+export function recordFeature(
+  manifest: Manifest,
+  feature: string,
+  templateVersion: string,
+  files: GeneratedFile[],
+  variables?: Record<string, string>
+): Manifest {
+  return {
+    ...manifest,
+    features: {
+      ...manifest.features,
+      [feature]: variables
+        ? { templateVersion, files, variables }
+        : { templateVersion, files },
+    },
+  };
+}

package/src/migrations-dir.ts

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Where the framework's migration chain lives, relative to the
+ * directory the CLI is run from.
+ *
+ * Two layouts are real: the framework repository itself, where core is
+ * a workspace package, and a consumer application, where core arrives
+ * from the registry and ships its migrations inside the package (they
+ * are in `files`, next to `dist`). The first match wins, so a checkout
+ * that has both — the framework repo — reads its own source.
+ */
+export const MIGRATION_LOCATIONS = [
+  "packages/core/src/db/migrations",
+  "node_modules/@intelligo-dev/core/src/db/migrations",
+] as const;
+
+export function resolveMigrationsDir(root: string): string | null {
+  for (const relative of MIGRATION_LOCATIONS) {
+    const dir = path.join(root, relative);
+    if (existsSync(dir)) return dir;
+  }
+  return null;
+}

package/src/migrations.ts

@@ -0,0 +1,133 @@
+/**
+ * Migration-chain inspection.
+ *
+ * Drizzle keeps two sources of truth: the `.sql` files on disk and
+ * `meta/_journal.json`, which is what `drizzle-kit migrate` actually
+ * reads. Nothing keeps them in step: a file missing from the journal is
+ * silently skipped by `migrate`, while `drizzle-kit push` from
+ * `schema.ts` hides the gap.
+ *
+ * The drift is invisible until someone provisions a database from the
+ * migrations, at which point it is a production incident rather than a
+ * CI failure. These helpers make it a check.
+ */
+
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+export type JournalEntry = {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+};
+
+export type MigrationChain = {
+  dir: string;
+  /** `.sql` files present on disk, sorted by their numeric prefix. */
+  files: string[];
+  /** Tags drizzle-kit will actually apply, in order. */
+  journalTags: string[];
+  /** On disk but absent from the journal — `migrate` skips these. */
+  unregistered: string[];
+  /** In the journal but missing from disk — `migrate` fails on these. */
+  missing: string[];
+};
+
+function tagOf(file: string): string {
+  return file.replace(/\.sql$/, "");
+}
+
+export function readMigrationChain(dir: string): MigrationChain {
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith(".sql"))
+    .sort();
+
+  let journalTags: string[] = [];
+  try {
+    const journal = JSON.parse(
+      readFileSync(path.join(dir, "meta", "_journal.json"), "utf8")
+    ) as { entries?: JournalEntry[] };
+    journalTags = (journal.entries ?? []).map((e) => e.tag);
+  } catch {
+    // No journal at all is itself the maximal drift: every file is
+    // unregistered, which the caller reports.
+    journalTags = [];
+  }
+
+  const registered = new Set(journalTags);
+  const onDisk = new Set(files.map(tagOf));
+
+  return {
+    dir,
+    files,
+    journalTags,
+    unregistered: files.map(tagOf).filter((t) => !registered.has(t)),
+    missing: journalTags.filter((t) => !onDisk.has(t)),
+  };
+}
+
+export type ChainProblem = { level: "error" | "warn"; message: string };
+
+export function inspectMigrationChain(chain: MigrationChain): ChainProblem[] {
+  const problems: ChainProblem[] = [];
+
+  if (chain.files.length === 0) {
+    problems.push({ level: "error", message: `No .sql files in ${chain.dir}` });
+    return problems;
+  }
+
+  if (chain.missing.length > 0) {
+    problems.push({
+      level: "error",
+      message:
+        `Journal references ${chain.missing.length} migration(s) that are not on disk ` +
+        `(drizzle-kit migrate will fail): ${chain.missing.join(", ")}`,
+    });
+  }
+
+  if (chain.unregistered.length > 0) {
+    problems.push({
+      level: "error",
+      message:
+        `${chain.unregistered.length} of ${chain.files.length} migration files are not in ` +
+        `meta/_journal.json, so drizzle-kit migrate skips them: ` +
+        `${chain.unregistered.slice(0, 5).join(", ")}` +
+        (chain.unregistered.length > 5 ? ", …" : ""),
+    });
+  }
+
+  // Numbering problems. Two files sharing a prefix is worse than a
+  // gap: `migrate` orders by tag, so which one runs first depends on
+  // the rest of the filename rather than on intent.
+  const numbers = chain.files
+    .map((f) => Number.parseInt(f.slice(0, 4), 10))
+    .filter((n) => Number.isFinite(n));
+
+  const seen = new Map<number, number>();
+  for (const n of numbers) seen.set(n, (seen.get(n) ?? 0) + 1);
+  const duplicates = [...seen.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([n]) => String(n).padStart(4, "0"));
+  if (duplicates.length > 0) {
+    problems.push({
+      level: "warn",
+      message: `Duplicate migration prefixes (apply order is filename-dependent): ${duplicates.join(", ")}`,
+    });
+  }
+
+  const unique = [...new Set(numbers)].sort((a, b) => a - b);
+  for (let i = 1; i < unique.length; i++) {
+    const prev = unique[i - 1]!;
+    const cur = unique[i]!;
+    if (cur > prev + 1) {
+      problems.push({
+        level: "warn",
+        message: `Gap in migration numbering: ${String(prev).padStart(4, "0")} → ${String(cur).padStart(4, "0")}`,
+      });
+    }
+  }
+
+  return problems;
+}

package/src/model-catalogue.ts

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Where the shipped model catalogue (`DEFAULT_MODELS`) can be read from,
+ * relative to the directory the CLI is run from: the framework
+ * repository's own source, then the installed package's source, then
+ * its build. The CLI reads the file rather than importing the package,
+ * so `doctor` works in an app whose dependencies do not even load.
+ */
+export const MODEL_CATALOGUE_LOCATIONS = [
+  "packages/executions/src/pricing.ts",
+  "node_modules/@intelligo-dev/executions/src/pricing.ts",
+  "node_modules/@intelligo-dev/executions/dist/pricing.js",
+] as const;
+
+/**
+ * The ids `DEFAULT_MODELS` prices, or null when no catalogue file is
+ * found or the declaration is not in it.
+ */
+export function readCatalogueModelIds(root: string): Set<string> | null {
+  for (const relative of MODEL_CATALOGUE_LOCATIONS) {
+    const file = path.join(root, relative);
+    if (!existsSync(file)) continue;
+    const text = readFileSync(file, "utf8");
+    const start = text.indexOf("export const DEFAULT_MODELS");
+    if (start === -1) continue;
+    return new Set(
+      [
+        ...text.slice(start).matchAll(/\bid:\s*"([a-z0-9-]+\/[a-z0-9._-]+)"/g),
+      ].map((m) => m[1]!)
+    );
+  }
+  return null;
+}

package/src/registry-items.ts

@@ -0,0 +1,132 @@
+/**
+ * The registry's pages as `intelligo create` offers them: what each one
+ * is, what else it needs installed first, and the commands that install
+ * a selection into a fresh app.
+ *
+ * Installing is the shadcn CLI's job, not this package's — the items
+ * are shadcn-schema JSON served at intelligo.dev/r, and the scaffold's
+ * components.json already names that registry as `@intelligo`. What the
+ * CLI adds is the order: an item that imports a sibling's files
+ * (requires.json `items`) has to land after it.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import type { RegistryRequires } from "./commands/doctor.js";
+
+export type RegistryItem = { title: string; description: string };
+export type RegistryCatalogue = {
+  items: Record<string, RegistryItem>;
+  requires: RegistryRequires;
+};
+
+/** Both files are build-time copies from packages/registry (see scripts/). */
+export function readRegistryCatalogue(templatesDir: string): RegistryCatalogue {
+  const read = (file: string) =>
+    JSON.parse(readFileSync(path.join(templatesDir, file), "utf8"));
+  return {
+    items: (
+      read("registry-items.json") as { items: Record<string, RegistryItem> }
+    ).items,
+    requires: read("registry-requires.json") as RegistryRequires,
+  };
+}
+
+/** The description's opening clause — short enough for one picker line. */
+export function shortDescription(description: string, max = 64): string {
+  const head = description.split(/[:.]\s|\s—\s/)[0]!.trim();
+  return head.length <= max ? head : `${head.slice(0, max - 1).trimEnd()}…`;
+}
+
+/**
+ * The selection plus everything it depends on, dependencies first.
+ * Unknown names throw rather than being dropped: a typo in `--items`
+ * should not quietly install less than was asked for.
+ */
+export function withDependencies(
+  selected: readonly string[],
+  requires: RegistryRequires
+): string[] {
+  const order: string[] = [];
+  const seen = new Set<string>();
+  const visit = (name: string) => {
+    if (seen.has(name)) return;
+    const entry = requires.items[name];
+    if (!entry) {
+      throw new Error(
+        `Unknown registry item "${name}". Available: ${Object.keys(requires.items).join(", ")}`
+      );
+    }
+    seen.add(name);
+    for (const dependency of entry.items ?? []) visit(dependency);
+    order.push(name);
+  };
+  for (const name of selected) visit(name);
+  return order;
+}
+
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+
+/**
+ * Whichever manager ran the CLI (`pnpm dlx`, `npx`, `bunx`… all set
+ * npm_config_user_agent), else pnpm — the one the scaffold documents.
+ */
+export function detectPackageManager(
+  userAgent: string | undefined = process.env.npm_config_user_agent
+): PackageManager {
+  const name = userAgent?.split("/")[0];
+  return name === "npm" || name === "yarn" || name === "bun" ? name : "pnpm";
+}
+
+export type Command = { command: string; args: string[] };
+
+export function formatCommand(c: Command): string {
+  return [c.command, ...c.args].join(" ");
+}
+
+const EXEC: Record<PackageManager, string[]> = {
+  pnpm: ["pnpm", "exec"],
+  npm: ["npx"],
+  yarn: ["yarn"],
+  bun: ["bunx"],
+};
+
+/** Whether the app has its own shadcn binary, i.e. dependencies are installed. */
+export function hasLocalShadcn(appRoot: string): boolean {
+  return existsSync(path.join(appRoot, "node_modules", ".bin", "shadcn"));
+}
+
+/**
+ * The commands that put `items` into the app at `appRoot`: install the
+ * dependencies when shadcn is not there yet (the scaffold declares it),
+ * then the design-system base, then the items in dependency order.
+ * `--overwrite` because the base replaces the scaffold's globals.css,
+ * and items that share a file agree on it — the same flags the
+ * reference app is regenerated with.
+ */
+export function installPlan(
+  items: readonly string[],
+  options: { appRoot: string; packageManager: PackageManager }
+): Command[] {
+  if (items.length === 0) return [];
+  const [command, ...exec] = EXEC[options.packageManager];
+  const add = (names: string[]): Command => ({
+    command: command!,
+    args: [
+      ...exec,
+      "shadcn",
+      "add",
+      ...names.map((n) => `@intelligo/${n}`),
+      "--yes",
+      "--overwrite",
+    ],
+  });
+  return [
+    ...(hasLocalShadcn(options.appRoot)
+      ? []
+      : [{ command: options.packageManager, args: ["install"] }]),
+    add(["intelligo"]),
+    add([...items]),
+  ];
+}

package/templates/admin-page/admin-page.tsx.tpl

@@ -1,11 +1,10 @@
 /**
- * The Intelligo operational console, mounted in your app.
+ * The operational console, mounted in your app.
  *
  * The screen itself ships from @intelligo-dev/admin so every deployment
  * shows the same operational truth — a fork could quietly stop showing
  * you unsettled executions. What is generated here is only the mount:
- * the route, the authorization call, and your own page chrome
- * (ADR-0002).
+ * the route, the authorization call, and your own page chrome.
  *
  * Access is gated on PLATFORM_ADMIN_EMAILS, not on a workspace role.
  * Workspace `owner` is per-tenant and every signup has one.

package/templates/app-scaffold/assistant-route.ts.tpl

@@ -5,7 +5,7 @@
  * it runs inside an execution — entitlement decided, worst-case cost
  * held, usage settled, audit emitted. Swap `callModel` for a Mastra
  * agent, an AI SDK call, or anything else and nothing around it
- * changes (ADR-0003).
+ * changes.
  */
 
 import { requireWorkspace } from "@intelligo-dev/auth";
@@ -15,7 +15,7 @@ import { CAPABILITIES, composeIntelligo, executions } from "@/lib/intelligo";
 export const maxDuration = 60;
 
 async function callModel(prompt: string) {
-  // Replace this with your framework's call.
+  // Your AI framework's call goes here.
   const inputTokens = Math.max(1, Math.ceil(prompt.length / 4));
   return {
     text: `Echo: ${prompt}`,

package/templates/app-scaffold/auth-route.ts.tpl

@@ -0,0 +1,10 @@
+/**
+ * Better-Auth's HTTP mount.
+ *
+ * Every call the auth client makes is a request to `/api/auth/*` on
+ * this app's own origin; without this file every sign-in POST answers
+ * 404. The handlers come from `@intelligo-dev/next`, so the app never
+ * depends on `better-auth` directly.
+ */
+
+export { GET, POST } from "@intelligo-dev/next/auth";

package/templates/app-scaffold/components.json.tpl

@@ -1,6 +1,6 @@
 {
   "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
+  "style": "base-nova",
   "rsc": true,
   "tsx": true,
   "tailwind": {
@@ -19,5 +19,9 @@
     "lib": "@/lib",
     "hooks": "@/hooks"
   },
-  "registries": {}
+  "registries": {
+    "@intelligo": "https://intelligo.dev/r/{name}.json"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle"
 }

package/templates/app-scaffold/db-schema.ts.tpl

@@ -0,0 +1,29 @@
+/**
+ * Tables this application owns.
+ *
+ * Everything the framework needs — users, workspaces, members, plans,
+ * subscriptions, credits, executions, audit events, notifications,
+ * conversations, documents — is `@intelligo-dev/core`'s and arrives
+ * with its own migrations. Define your product's tables here, scope
+ * them to a workspace, and reference framework tables by import:
+ *
+ *   import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+ *   import { organization, users } from "@intelligo-dev/core/db/schema";
+ *
+ *   export const reports = pgTable("reports", {
+ *     id: text("id").primaryKey(),
+ *     workspaceId: text("workspace_id")
+ *       .notNull()
+ *       .references(() => organization.id, { onDelete: "cascade" }),
+ *     createdBy: text("created_by").references(() => users.id),
+ *     createdAt: timestamp("created_at").defaultNow().notNull(),
+ *   });
+ *
+ * Then `pnpm db:generate` writes the migration into ./drizzle and
+ * `pnpm db:migrate` applies it after the framework's chain.
+ *
+ * Intelligo never reads these tables (every table has one
+ * owner), so their shape is entirely yours.
+ */
+
+export {};

package/templates/app-scaffold/drizzle-journal.json.tpl

@@ -0,0 +1,5 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": []
+}

package/templates/app-scaffold/drizzle.config.ts.tpl

@@ -0,0 +1,45 @@
+import { defineConfig } from "drizzle-kit";
+import { config } from "dotenv";
+
+// drizzle-kit does not load env files; Next.js does. Same precedence.
+config({ path: ".env.local" });
+config({ path: ".env" });
+
+/**
+ * Your application's migration chain — and only yours.
+ *
+ * The framework's tables (users, workspaces, plans, credits, executions,
+ * …) arrive inside `@intelligo-dev/core` together with their migration
+ * history, and `intelligo migrate` applies that chain. This config
+ * covers the tables you own: list their schema files here, generate
+ * with `pnpm db:generate`, apply with `pnpm db:migrate`.
+ * `drizzle/meta/_journal.json` starts empty so `db:migrate` succeeds
+ * before you own a table — drizzle-kit exits 1, with no message, when
+ * the journal is missing.
+ *
+ * Two chains, one database, so they record themselves in different
+ * tables: the framework in drizzle's default `__drizzle_migrations`,
+ * yours in `__app_migrations`. Do not merge them — drizzle-kit applies
+ * by timestamp, and a framework migration published after you
+ * generated one of yours would be skipped silently.
+ *
+ * Your schema may reference framework tables (`references(() =>
+ * users.id)`); drizzle-kit emits the foreign key by name and does not
+ * try to create the framework's table.
+ *
+ * Do not point `drizzle-kit push` at this config: push diffs the whole
+ * database against the schema it sees, and this config deliberately
+ * sees only yours.
+ */
+export default defineConfig({
+  dialect: "postgresql",
+  schema: ["./lib/db/schema.ts"],
+  out: "./drizzle",
+  migrations: { table: "__app_migrations", schema: "drizzle" },
+  // The framework's columns are snake_case in Postgres and camelCase in
+  // TypeScript. Keep the same convention so joins read naturally.
+  casing: "snake_case",
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});

package/templates/app-scaffold/env.example.tpl

@@ -1,6 +1,18 @@
+# ============================================
 # Required — the app will not boot without these.
+# ============================================
+
+# Postgres with the pgvector extension (Neon, Supabase, RDS, or local).
 DATABASE_URL=
+# Driver is chosen from the URL (Neon hosts get the WebSocket driver,
+# everything else node-postgres). Force it with pg | neon-serverless.
+# INTELLIGO_DB_DRIVER=
+
+# At least 32 characters. Generate with: openssl rand -base64 32
 BETTER_AUTH_SECRET=
+
+# Where users reach the app. Auth callbacks, email links and redirects
+# are built from it, so production needs the public https URL.
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 
 # Which product's plans the billing engine bills against. Your
@@ -8,6 +20,58 @@ NEXT_PUBLIC_APP_URL=http://localhost:3000
 # variable is here so CLI tooling can check it without booting the app.
 INTELLIGO_BILLING_PRODUCT=__APP_SLUG__
 
+# ============================================
+# Optional — everything works locally without these.
+# ============================================
+
+# Sign in with Google or GitHub. A provider's button appears once both
+# of its values are set; the callback URL to register with the provider
+# is NEXT_PUBLIC_APP_URL + /api/auth/callback/google (or /github).
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
+
+# Email. Without a provider, emails (verification, invitations, reset
+# links) are printed to the server console, and sign-ups are not held
+# for email verification.
+# RESEND_API_KEY=
+# The sender of every email, on a domain verified with Resend. Required
+# with RESEND_API_KEY: there is no built-in sender, so sends fail without
+# it. Loops ignores it and takes the sender from each template.
+# EMAIL_FROM=Acme <noreply@example.com>
+# The product's name in every email's heading and footer; defaults to
+# the display name in EMAIL_FROM. SUPPORT_EMAIL is the address the
+# footer offers for replies; without it the footer offers none.
+# APP_NAME=Acme
+# SUPPORT_EMAIL=support@example.com
+# Loops sends by template id instead of HTML: map each template with
+# LOOPS_TRANSACTIONAL_ID_<KEY>, e.g. LOOPS_TRANSACTIONAL_ID_VERIFY_EMAIL.
+# LOOPS_API_KEY=
+# With both keys set Resend wins; force one with resend | loops | console.
+# EMAIL_PROVIDER=
+
+# Stripe. Billing pages say "not configured" until these are set; the
+# webhook at /api/webhooks/stripe verifies with the secret.
+# STRIPE_SECRET_KEY=
+# STRIPE_WEBHOOK_SECRET=
+
+# Which registered payment provider serves payments outside Stripe
+# (registerPaymentProvider in the composition root). Defaults to the
+# in-memory mock, which production refuses.
+# PAYMENT_MODE=
+
+# AI providers. Chat runs on a built-in stub model until lib/chat-model.ts
+# names a real one. Set only the key of the provider that model belongs
+# to — the provider's SDK reads it, and the framework checks none of them.
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GOOGLE_GENERATIVE_AI_API_KEY=
+
+# Bearer token your scheduler sends to /api/cron/maintenance
+# (`intelligo add maintenance`). At least 32 characters.
+# CRON_SECRET=
+
 # Comma-separated emails allowed to reach the Intelligo admin console.
 # Closed by default: with no value, nobody is a platform admin.
-PLATFORM_ADMIN_EMAILS=
+# PLATFORM_ADMIN_EMAILS=