@basaltkit/ai 1.5.0 → 1.6.1

package/dist/commands.js

@@ -6,7 +6,7 @@ import { applyFixEdits, fixableIds, planFix, renderFixes } from './doctor/fixes.
 import { createProvider, providerEnvFromProcess } from './provider/factory.js';
 import { createPlan } from './plan/plan.js';
 import { renderPlan } from './plan/render.js';
-import { runMake } from './make/make.js';
+import { packageSteps, runMake } from './make/make.js';
 import { renderMakeResult } from './make/render.js';
 import { runPrismaPush } from './make/schema.js';
 import { verifyProject } from './make/verify.js';
@@ -39,7 +39,7 @@ export function aiCommands(options = {}) {
                 io.log('');
                 if (args.length > 0) {
                     io.log(`You asked: "${args.join(' ')}"`);
-                    io.log('Natural-language planning & scaffolding (ai:plan / ai:make) land in the next phase.');
+                    io.log(`Plan it with: basalt ai:plan "${args.join(' ')}"`);
                     io.log('');
                 }
                 io.log('Available now:');
@@ -180,8 +180,17 @@ export function aiCommands(options = {}) {
                     io.error(error.message);
                     return 1;
                 }
-                renderPlan(plan, io);
+                renderPlan(plan, io, { footer: false });
                 io.log('');
+                // ai:make only scaffolds entities. A plan without any (a package to
+                // install or wire, config, docs) is complete as shown — say so before
+                // the confirmation prompt instead of failing after it.
+                if (plan.entities.length === 0) {
+                    io.log(packageSteps(plan).length > 0
+                        ? 'Nothing to scaffold — this plan reuses ecosystem packages. Run the package steps above.'
+                        : 'Nothing to scaffold — the steps above are applied by hand.');
+                    return 0;
+                }
                 // Agent review over the generated code — read-only, uses the same provider.
                 const agentReview = async (result) => {
                     if (flags['review'] !== true)

package/dist/index.d.ts

@@ -15,7 +15,8 @@ export { analyze, type AnalysisReport } from './analyze/run.js';
 export { createPlan, parsePlan, type CreatePlanOptions } from './plan/plan.js';
 export { buildPlanContext } from './plan/context.js';
 export { BASALT_KNOWLEDGE } from './plan/knowledge.js';
-export { renderPlan } from './plan/render.js';
+export { ECOSYSTEM_PACKAGES, renderEcosystemCatalog, type EcosystemPackage } from './plan/packages.js';
+export { renderPlan, type RenderPlanOptions } from './plan/render.js';
 export type { ArchitecturePlan, PlanEntity, PlanField, PlanRelation, PlanStep, PlanStepKind, } from './plan/types.js';
 export { runMake } from './make/make.js';
 export { assertSafePlan, UnsafePlanError } from './plan/identifiers.js';

package/dist/index.js

@@ -21,6 +21,7 @@ export { analyze } from './analyze/run.js';
 export { createPlan, parsePlan } from './plan/plan.js';
 export { buildPlanContext } from './plan/context.js';
 export { BASALT_KNOWLEDGE } from './plan/knowledge.js';
+export { ECOSYSTEM_PACKAGES, renderEcosystemCatalog } from './plan/packages.js';
 export { renderPlan } from './plan/render.js';
 // Implementation (spec §4 Implement) — execute a plan via the generator + review gate.
 export { runMake } from './make/make.js';

package/dist/make/make.d.ts

@@ -12,3 +12,5 @@ import type { MakeOptions, MakeResult } from './types.js';
  * touches the database, never deletes.
  */
 export declare function runMake(ctx: ProjectContext, plan: ArchitecturePlan, options?: MakeOptions): Promise<MakeResult>;
+/** The plan's `package` steps as instructions — ai:make never installs dependencies itself. */
+export declare function packageSteps(plan: ArchitecturePlan): string[];

package/dist/make/make.js

@@ -28,7 +28,10 @@ export async function runMake(ctx, plan, options = {}) {
     assertSafePlan(plan);
     const entities = plan.entities.filter((e) => e.name.trim() !== '');
     if (entities.length === 0) {
-        throw new Error('ai:make — the plan has no entity to generate.');
+        const packages = packageSteps(plan);
+        throw new Error(packages.length > 0
+            ? `ai:make — nothing to generate: the plan reuses ecosystem packages. ${packages.join(' ')}`
+            : 'ai:make — the plan has no entity to generate.');
     }
     throwIfAborted(options.signal);
     const baseDir = options.baseDir ?? process.cwd();
@@ -222,7 +225,8 @@ function augmentFiles(files, entity, plan, ctx, opts) {
     return { files: out, augmented, guarded, audited };
 }
 function buildFollowUps(plan, resources, schema, migration) {
-    const followUps = [];
+    // Packages first: the generated code may depend on them being wired.
+    const followUps = packageSteps(plan);
     const prismaResources = resources.filter((r) => r.prisma);
     if (prismaResources.length > 0) {
         if (!schema?.found) {
@@ -257,6 +261,12 @@ function buildFollowUps(plan, resources, schema, migration) {
     }
     return followUps;
 }
+/** The plan's `package` steps as instructions — ai:make never installs dependencies itself. */
+export function packageSteps(plan) {
+    return plan.steps
+        .filter((step) => step.kind === 'package')
+        .map((step) => `${step.title}${step.command ? ` — \`${step.command}\`` : ''}${step.detail ? `: ${step.detail}` : ''}`);
+}
 function reviewBuild(ctx, plan, resources, schema, migration) {
     const items = [];
     // Tenant isolation — the gate the spec cares most about.

package/dist/plan/context.d.ts

@@ -2,7 +2,7 @@ import type { ProjectContext } from '../context/project.js';
 /**
  * Compact, relevant-only project summary for the planner (spec §18 Context
  * Engineering — never ship the whole project to the model). Surfaces exactly what
- * the Architect needs to ground a plan: enabled capabilities, existing models and
- * the generator's flags.
+ * the Architect needs to ground a plan: enabled capabilities, existing models,
+ * the ecosystem packages already installed and the generator's flags.
  */
 export declare function buildPlanContext(ctx: ProjectContext): string;

package/dist/plan/context.js

@@ -1,8 +1,9 @@
+import { ECOSYSTEM_PACKAGES } from './packages.js';
 /**
  * Compact, relevant-only project summary for the planner (spec §18 Context
  * Engineering — never ship the whole project to the model). Surfaces exactly what
- * the Architect needs to ground a plan: enabled capabilities, existing models and
- * the generator's flags.
+ * the Architect needs to ground a plan: enabled capabilities, existing models,
+ * the ecosystem packages already installed and the generator's flags.
  */
 export function buildPlanContext(ctx) {
     const s = ctx.stack;
@@ -25,12 +26,18 @@ export function buildPlanContext(ctx) {
     const models = ctx.prisma && ctx.prisma.models.length > 0
         ? ctx.prisma.models.map((m) => `${m.name}${m.tenantScoped ? ' (tenantId)' : ''}`).join(', ')
         : '(none)';
+    // Catalog packages only: the store/driver packages (-prisma, -s3…) are
+    // implementation detail the planner reaches through the catalog entry.
+    const catalog = new Set(ECOSYSTEM_PACKAGES.map((p) => p.name));
+    const installed = ctx.installed.filter((name) => catalog.has(name));
     const lines = [
         'PROJECT STACK:',
         ...caps.map((c) => `- ${c}`),
         '',
         `EXISTING PRISMA MODELS: ${models}`,
         '',
+        `INSTALLED ECOSYSTEM PACKAGES: ${installed.join(', ') || '(none)'} — use these as they are; any other catalog package needs a "package" install step.`,
+        '',
         'GENERATOR: `basalt make:resource <Name>` — flags: --prisma, --soft-delete, --no-register, --dir, --force.',
     ];
     if (ctx.app)

package/dist/plan/knowledge.d.ts

@@ -6,4 +6,4 @@
  * This is deliberately prescriptive: the plan must reuse the generator and the
  * platform plugins, never hand-roll parallel abstractions.
  */
-export declare const BASALT_KNOWLEDGE = "You are the Architect agent for Basalt \u2014 a batteries-included SaaS framework for Node.js/TypeScript (Fastify + Prisma + Zod). You turn a developer's natural-language request into a precise, convention-following implementation PLAN. You PLAN only; you never write code here.\n\nABSOLUTE RULES \u2014 always use the framework's official APIs and generators, never invent new ones:\n\n1. SCAFFOLDING. Create a resource with the generator, not by hand:\n   `basalt make:resource <Name>` \u2014 generates a full vertical: Zod schema, repository, service, DI plugin, typed routes and a test, all on-convention and auto-wired into src/app.ts.\n   Flags: --prisma (Prisma-backed repository + a schema.prisma model with id/createdAt/updatedAt), --soft-delete (adds deletedAt, a restore() method + route), --no-register (skip wiring), --dir=<path>, --force.\n\n2. PERSISTENCE. Prisma via prismaPlugin. Models live in schema.prisma. After editing the schema, run `basalt prisma:sync` to generate the client + migration. Use --prisma so the generator emits the model for you.\n\n3. MULTI-TENANCY. When tenancy is enabled, every tenant-owned model MUST carry a `tenantId` column, and the tenancy layer scopes queries by the current tenant. NEVER plan a query that ignores tenant isolation. Platform-global tables (users, tenants, plans) are the only exceptions.\n\n4. RBAC / PERMISSIONS. For each resource, register `<resource>.view`, `<resource>.create`, `<resource>.update`, `<resource>.delete` and guard the matching routes with the permission check. Use the resource name in plural, lowercase (e.g. `patients.create`).\n\n5. AUDIT. Emit an audit event for each state change: `<resource>.created`, `<resource>.updated`, `<resource>.deleted` (singular resource).\n\n6. VALIDATION + DOCS. Every route carries a Zod schema; OpenAPI is generated from it automatically \u2014 no separate doc wiring.\n\n7. TESTS. Every resource ships a test (the generator creates one; extend it for domain rules).\n\nGROUNDING: Reuse what already exists in the project. Avoid name collisions with existing models. Only add what is missing. Prefer editing the schema + running the generator over hand-writing files.\n\nOUTPUT: Return ONLY a single JSON object (no prose, no markdown fences) matching exactly:\n{\n  \"summary\": string,                     // 1-2 sentences on the approach\n  \"entities\": [                          // domain entities to create\n    { \"name\": string, \"fields\": [{ \"name\": string, \"type\": string, \"enum\"?: string[] }], \"tenantScoped\": boolean,\n      \"relations\": [{ \"name\": string, \"model\": string }] }   // belongs-to: this model gets a <name>Id FK \u2192 <model>\n  ],\n  \"steps\": [                             // ordered implementation steps\n    { \"order\": number, \"title\": string, \"kind\": \"generator\"|\"schema\"|\"migration\"|\"service\"|\"routes\"|\"permissions\"|\"audit\"|\"test\"|\"docs\"|\"other\", \"detail\": string, \"command\": string, \"files\": string[] }\n  ],\n  \"permissions\": string[],               // e.g. [\"patients.view\",\"patients.create\",...]\n  \"auditEvents\": string[],               // e.g. [\"patient.created\",...]\n  \"tenantScoped\": boolean,               // does this feature involve tenant-owned data\n  \"warnings\": string[]                   // risks, decisions to confirm, missing info\n}\nFor generator steps, put the exact command in \"command\" (e.g. \"basalt make:resource Patient --prisma --soft-delete\"). Omit \"command\"/\"files\" when not applicable.\n\nENUMS: a field with a fixed set of values (a status/state) MUST set \"enum\" to those values \u2014 e.g. \"estado (pago/pendente)\" \u2192 { \"name\": \"estado\", \"type\": \"String\", \"enum\": [\"pago\", \"pendente\"] }. It becomes a validated z.enum([...]) (stored as a String column), never a free z.string().\n\nRELATIONS: express a belongs-to as an entry in \"relations\" (e.g. an Appointment belongs to a Patient \u2192 { \"name\": \"patient\", \"model\": \"Patient\" }). Do NOT also add the \"<name>Id\" field to \"fields\" \u2014 the FK column, the @relation and the inverse field are generated. Prefer generating both sides of a relation in the same plan.";
+export declare const BASALT_KNOWLEDGE: string;

package/dist/plan/knowledge.js

@@ -1,3 +1,4 @@
+import { renderEcosystemCatalog } from './packages.js';
 /**
  * The Architect agent's system prompt — Basalt's conventions and official APIs,
  * encoded so the model plans *with* the framework instead of inventing its own
@@ -10,6 +11,11 @@ export const BASALT_KNOWLEDGE = `You are the Architect agent for Basalt — a ba
 
 ABSOLUTE RULES — always use the framework's official APIs and generators, never invent new ones:
 
+0. ECOSYSTEM FIRST. Before planning any resource, check whether an official package already covers the capability (catalog below). If one does, use it: a "package" step whose "command" installs it (\`pnpm add <package>\`, plus its Prisma store when the app uses Prisma) and whose "detail" says how to wire its plugin/routes in src/app.ts — or, when the project already has it installed, a "package" step with no "command" that only wires/uses it. NEVER generate a resource, model or module that duplicates a package (no Comment model when @basaltkit/comments exists, no Notification table, no File/Attachment model, no Team/Invitation model, no AuditLog). Do NOT list a package-covered concept in "entities" — entities are only the domain models no package provides. Only generate from scratch what the catalog does not cover, and say so in "warnings" when a package covers it only partly.
+
+ECOSYSTEM CATALOG:
+${renderEcosystemCatalog()}
+
 1. SCAFFOLDING. Create a resource with the generator, not by hand:
    \`basalt make:resource <Name>\` — generates a full vertical: Zod schema, repository, service, DI plugin, typed routes and a test, all on-convention and auto-wired into src/app.ts.
    Flags: --prisma (Prisma-backed repository + a schema.prisma model with id/createdAt/updatedAt), --soft-delete (adds deletedAt, a restore() method + route), --no-register (skip wiring), --dir=<path>, --force.
@@ -36,14 +42,14 @@ OUTPUT: Return ONLY a single JSON object (no prose, no markdown fences) matching
       "relations": [{ "name": string, "model": string }] }   // belongs-to: this model gets a <name>Id FK → <model>
   ],
   "steps": [                             // ordered implementation steps
-    { "order": number, "title": string, "kind": "generator"|"schema"|"migration"|"service"|"routes"|"permissions"|"audit"|"test"|"docs"|"other", "detail": string, "command": string, "files": string[] }
+    { "order": number, "title": string, "kind": "package"|"generator"|"schema"|"migration"|"service"|"routes"|"permissions"|"audit"|"test"|"docs"|"other", "detail": string, "command": string, "files": string[] }
   ],
   "permissions": string[],               // e.g. ["patients.view","patients.create",...]
   "auditEvents": string[],               // e.g. ["patient.created",...]
   "tenantScoped": boolean,               // does this feature involve tenant-owned data
   "warnings": string[]                   // risks, decisions to confirm, missing info
 }
-For generator steps, put the exact command in "command" (e.g. "basalt make:resource Patient --prisma --soft-delete"). Omit "command"/"files" when not applicable.
+For generator steps, put the exact command in "command" (e.g. "basalt make:resource Patient --prisma --soft-delete"); for package steps, the install command (e.g. "pnpm add @basaltkit/comments @basaltkit/comments-prisma"), or omit it when the package is already installed. Omit "command"/"files" when not applicable.
 
 ENUMS: a field with a fixed set of values (a status/state) MUST set "enum" to those values — e.g. "estado (pago/pendente)" → { "name": "estado", "type": "String", "enum": ["pago", "pendente"] }. It becomes a validated z.enum([...]) (stored as a String column), never a free z.string().
 

package/dist/plan/packages.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The ecosystem catalog the Architect plans with: each official package, the
+ * capability it covers and the entry points an app wires. Without it the model
+ * only knew the generator and rebuilt features (comments, files, notifications…)
+ * as fresh resources instead of installing the package that already ships them.
+ *
+ * Kept in sync with `packages/*` by `tests/plan-packages.test.ts`.
+ */
+export interface EcosystemPackage {
+    /** npm name, e.g. `@basaltkit/comments`. */
+    name: string;
+    /** What it provides, in the words a request would use. */
+    covers: string;
+    /** The plugin factory wired in src/app.ts. */
+    plugin?: string;
+    /** Ready-made routes the app spreads into its route list. */
+    routes?: string;
+    /** The Prisma-backed store package, when the default store is in-memory. */
+    prisma?: string;
+    /**
+     * The wiring as the package README shows it, one line — so a plan names the
+     * real options instead of guessing them (it once wrote
+     * `app.register(mailerPlugin, { provider: 'smtp' })`).
+     */
+    example?: string;
+    /** The same wiring with the Prisma store, for apps on Prisma. */
+    prismaExample?: string;
+    /** The DI token a service resolves with `ctx().container.get(TOKEN)`. */
+    token?: string;
+}
+export declare const ECOSYSTEM_PACKAGES: readonly EcosystemPackage[];
+/** The catalog for the planner's system prompt: one entry per package, wiring indented under it. */
+export declare function renderEcosystemCatalog(packages?: readonly EcosystemPackage[]): string;

package/dist/plan/packages.js

@@ -0,0 +1,166 @@
+export const ECOSYSTEM_PACKAGES = [
+    {
+        name: '@basaltkit/auth', covers: 'login, signup, JWT/sessions, password reset, MFA, OAuth, passkeys, API keys',
+        plugin: 'authPlugin', routes: 'authRoutes', prisma: '@basaltkit/auth-prisma', token: 'AUTH',
+        example: 'authPlugin({ users: new MemoryUserSource(), secret: env.AUTH_SECRET }) + fastifyPlugin({ routes: [...authRoutes()] })',
+        prismaExample: 'const s = prismaAuthStores(prisma); authPlugin({ secret: env.AUTH_SECRET, users: s.users, sessions: s.sessions, refreshTokens: s.refreshTokens, tokens: s.tokens, mfa: s.mfa })',
+    },
+    {
+        name: '@basaltkit/permissions', covers: 'roles, permissions, policies, route guards (RBAC)',
+        plugin: 'permissionsPlugin', prisma: '@basaltkit/permissions-prisma', token: 'GATE',
+        example: 'permissionsPlugin({ store })',
+        prismaExample: 'const p = prismaAccessStore(prisma); permissionsPlugin({ store: p.store })',
+    },
+    {
+        name: '@basaltkit/tenancy', covers: 'multi-tenancy: tenant resolution and tenant context',
+        plugin: 'tenancyPlugin', prisma: '@basaltkit/tenancy-prisma', token: 'TENANCY',
+        example: 'tenancyPlugin({ source, resolvers: [headerResolver()] })',
+        prismaExample: 'tenancyPlugin({ source: prismaTenantSource(prisma), resolvers: [subdomainResolver({ base: env.APP_DOMAIN })] })',
+    },
+    {
+        name: '@basaltkit/teams', covers: 'team members, roles inside a tenant, email invitations',
+        plugin: 'teamsPlugin', routes: 'teamRoutes', prisma: '@basaltkit/teams-prisma', token: 'TEAMS',
+        example: 'teamsPlugin() + fastifyPlugin({ routes: [...teamRoutes()] })',
+        prismaExample: 'const t = prismaTeamsStores(prisma); teamsPlugin({ memberships: t.memberships, invitations: t.invitations })',
+    },
+    {
+        name: '@basaltkit/comments', covers: 'comment threads on any resource, @mentions, resolve/reopen',
+        plugin: 'commentsPlugin', routes: 'commentRoutes', prisma: '@basaltkit/comments-prisma', token: 'COMMENTS',
+        example: 'commentsPlugin() + fastifyPlugin({ routes: [...commentRoutes()] })',
+        prismaExample: 'commentsPlugin({ store: prismaCommentsStore(prisma).store })',
+    },
+    {
+        name: '@basaltkit/activity', covers: 'user-facing activity feed / history of changes',
+        plugin: 'activityPlugin', prisma: '@basaltkit/activity-prisma', token: 'ACTIVITY',
+        example: "activityPlugin(); then container.get(ACTIVITY).in('project').performedOn('project', id).log('published')",
+        prismaExample: 'activityPlugin({ store: prismaActivityStore(prisma).store })',
+    },
+    {
+        name: '@basaltkit/audit', covers: 'append-only audit trail of state changes',
+        plugin: 'auditPlugin', prisma: '@basaltkit/audit-prisma', token: 'AUDIT',
+        example: 'eventsPlugin() + auditPlugin()',
+        prismaExample: 'auditPlugin({ store: prismaAuditStore(prisma).store })',
+    },
+    {
+        name: '@basaltkit/notifications', covers: 'in-app and email notifications, per-user preferences',
+        plugin: 'notificationsPlugin', routes: 'inAppRoutes', prisma: '@basaltkit/notifications-prisma', token: 'NOTIFIER',
+        example: 'mailerPlugin({ driver: \'log\', from: env.MAIL_FROM }) + notificationsPlugin()',
+        prismaExample: 'notificationsPlugin({ inApp: prismaInAppStore(prisma).store, preferences: prismaPreferenceStore(prisma) })',
+    },
+    {
+        name: '@basaltkit/files', covers: 'file uploads and attachments, quotas, signed URLs',
+        plugin: 'filesPlugin', routes: 'fileRoutes', prisma: '@basaltkit/files-prisma', token: 'FILES',
+        example: "storagePlugin({ disks: { uploads: { driver: 'local', root: './storage' } } }) + filesPlugin({ disk: 'uploads', validate: { maxSize: 5_000_000 } }) + fastifyPlugin({ routes: [...fileRoutes()] })",
+        prismaExample: "filesPlugin({ disk: 'uploads', store: prismaFilesStore(prisma).store })",
+    },
+    {
+        name: '@basaltkit/files-versions', covers: 'document versions / revisions on top of files',
+        plugin: 'fileVersionsPlugin', token: 'FILE_VERSIONS',
+        example: 'fileVersionsPlugin({ store: prismaFileVersionsStore(prisma).store })  // store from @basaltkit/files-prisma/versions',
+    },
+    {
+        name: '@basaltkit/storage', covers: 'disk/object storage (local, S3, Azure, GCS)',
+        plugin: 'storagePlugin', token: 'STORAGE',
+        example: "storagePlugin({ default: 'uploads', disks: { uploads: { driver: 'local', root: './storage' } } })",
+    },
+    {
+        name: '@basaltkit/drives', covers: 'import from Google Drive, OneDrive/SharePoint, Dropbox',
+        plugin: 'drivesPlugin', token: 'DRIVES',
+        example: "drivesPlugin({ providers: [dropboxDrive({ clientId, clientSecret })], keys: [{ id: '2026-09', key: env.DRIVES_ENCRYPTION_KEY }], secret: env.APP_SECRET })",
+    },
+    {
+        name: '@basaltkit/subscriptions', covers: 'billing: plans, subscriptions, trials, usage limits, payment gateways',
+        plugin: 'subscriptionsPlugin', prisma: '@basaltkit/subscriptions-prisma', token: 'SUBSCRIPTIONS',
+        example: "subscriptionsPlugin({ plans, fallbackPlan: 'free', gateway }) + routes billingRoutes({ successUrl, cancelUrl }), invoiceRoutes(); guard with meta: { subscribed: 'pro' } / { feature: 'api' }",
+        prismaExample: 'const s = prismaSubscriptionsStores(prisma); subscriptionsPlugin({ plans, store: s.store, usage: s.usage, webhooks: s.webhooks })',
+    },
+    {
+        name: '@basaltkit/webhooks', covers: 'outbound webhooks with signing and retries',
+        plugin: 'webhooksPlugin', prisma: '@basaltkit/webhooks-prisma', token: 'WEBHOOKS',
+        example: "eventsPlugin() + webhooksPlugin({ secret: env.WEBHOOK_SECRET, events: ['invoice.*'] })",
+        prismaExample: 'webhooksPlugin({ store: prismaWebhookStore(prisma).store, secret: env.WEBHOOK_SECRET })',
+    },
+    {
+        name: '@basaltkit/events', covers: 'typed domain events, listeners, transactional outbox',
+        plugin: 'eventsPlugin', prisma: '@basaltkit/events-prisma', token: 'EVENTS',
+        example: "eventsPlugin() + outboxPlugin({ store, captureEvents: ['invoice.*'], dispatch: async (entry) => { … } })",
+        prismaExample: 'outboxPlugin({ store: prismaOutboxStore(prisma, { claim: true }).store, dispatch })',
+    },
+    {
+        name: '@basaltkit/queue', covers: 'background jobs (BullMQ, RabbitMQ, SQS, Kafka)',
+        plugin: 'queuePlugin', token: 'QUEUE',
+        example: 'queuePlugin({ jobs: [SendWelcomeEmail] })  // no connection = sync driver; bullmqQueuePlugin({ jobs, connection: env.REDIS_URL }) from @basaltkit/queue-bullmq',
+    },
+    {
+        name: '@basaltkit/scheduler', covers: 'scheduled / recurring tasks (cron-like)',
+        plugin: 'schedulerPlugin', token: 'SCHEDULER',
+        example: "schedulerPlugin({ define: (schedule) => { schedule.call('backup', async () => { … }).daily().at('03:00') } })",
+    },
+    {
+        name: '@basaltkit/mailer', covers: 'sending email (SMTP, Resend, SES, Mailgun)',
+        plugin: 'mailerPlugin', token: 'MAILER',
+        example: "mailerPlugin({ driver: 'log', from: env.MAIL_FROM })  // or driver: 'resend', resend: { apiKey }; SMTP: driver: smtpMailer({ url }) from @basaltkit/mailer-smtp; send with container.get(MAILER)",
+    },
+    {
+        name: '@basaltkit/inbound-mail', covers: 'receiving email',
+        routes: 'inboundMailRoutes',
+        example: "fastifyPlugin({ routes: [...inboundMailRoutes({ driver: signedDriver({ secret: env.INBOUND_SECRET }), routes: [{ address: '{tenant}@in.example.com', handler }] })] })",
+    },
+    {
+        name: '@basaltkit/realtime', covers: 'live updates over WebSocket/SSE, presence',
+        plugin: 'realtimePlugin', token: 'REALTIME',
+        example: "realtimePlugin({ bridge: [bridgeRule({ hook: 'note:created', channel: 'notes', event: 'created' })] })",
+    },
+    {
+        name: '@basaltkit/search', covers: 'full-text search (Postgres, Elasticsearch, Meilisearch)',
+        plugin: 'searchPlugin', token: 'SEARCH',
+        example: "searchPlugin({ indexes: [defineIndex({ name: 'notes', fields: ['title', 'body'] })] })",
+    },
+    {
+        name: '@basaltkit/cache', covers: 'caching with tags and tenant scoping',
+        plugin: 'cachePlugin', token: 'CACHE',
+        example: "cachePlugin({ driver: 'memory' })  // shared: driver: redisCache(env.REDIS_URL) from @basaltkit/cache-redis",
+    },
+    {
+        name: '@basaltkit/flags', covers: 'feature flags and percentage rollouts',
+        plugin: 'flagsPlugin', token: 'FLAGS',
+        example: 'flagsPlugin(defineFlags({ newDashboard: { default: false, tenants: { acme: true } }, betaSearch: { default: false, rollout: 25 } }))',
+    },
+    {
+        name: '@basaltkit/exports', covers: 'CSV/JSON/XLSX exports and CSV import',
+        plugin: 'exportsPlugin', token: 'EXPORTS',
+        example: "exportsPlugin({ formatters: [createCsvFormatter({ delimiter: ';' })] })",
+    },
+    {
+        name: '@basaltkit/i18n', covers: 'translations, locale, number/date formatting',
+        plugin: 'i18nPlugin', token: 'I18N',
+        example: "i18nPlugin({ locales: { en, pt }, defaultLocale: 'en' })",
+    },
+    {
+        name: '@basaltkit/backup', covers: 'PostgreSQL backups',
+        plugin: 'backupPlugin', token: 'BACKUP',
+        example: "storagePlugin({ disks: { backups: { driver: 'local', root: './backups', scope: null } } }) + backupPlugin({ connectionUrl: env.DATABASE_URL, disk: 'backups', retention: 7 })",
+    },
+    {
+        name: '@basaltkit/mcp', covers: 'expose routes as MCP tools for AI agents',
+        plugin: 'mcpPlugin', token: 'MCP',
+        example: "mcpPlugin({ routes, serverInfo: { name: 'app', version: '1.0.0' } }) + fastifyPlugin({ routes: [...routes, ...mcpRoutes()] }); opt a route in with meta: { mcp: { name } }",
+    },
+];
+/** The catalog for the planner's system prompt: one entry per package, wiring indented under it. */
+export function renderEcosystemCatalog(packages = ECOSYSTEM_PACKAGES) {
+    return packages
+        .map((p) => {
+        const lines = [`- ${p.name} — ${p.covers}`];
+        if (p.example)
+            lines.push(`    wire: ${p.example}`);
+        if (p.prismaExample)
+            lines.push(`    with Prisma (${p.prisma}): ${p.prismaExample}`);
+        else if (p.prisma)
+            lines.push(`    Prisma store: ${p.prisma}`);
+        if (p.token)
+            lines.push(`    use: ctx().container.get(${p.token})`);
+        return lines.join('\n');
+    })
+        .join('\n');
+}

package/dist/plan/plan.js

@@ -3,6 +3,7 @@ import { runGeneration } from '../generate.js';
 import { buildPlanContext } from './context.js';
 import { BASALT_KNOWLEDGE } from './knowledge.js';
 const STEP_KINDS = [
+    'package',
     'generator',
     'schema',
     'migration',

package/dist/plan/render.d.ts

@@ -1,4 +1,8 @@
 import type { LineWriter } from '../render.js';
 import type { ArchitecturePlan } from './types.js';
+export interface RenderPlanOptions {
+    /** Print the "what next" footer (default `true`); ai:make, which acts next itself, turns it off. */
+    footer?: boolean;
+}
 /** Render an {@link ArchitecturePlan} in the spec's `ARCHITECTURE PLAN` style. */
-export declare function renderPlan(plan: ArchitecturePlan, io: LineWriter): void;
+export declare function renderPlan(plan: ArchitecturePlan, io: LineWriter, options?: RenderPlanOptions): void;

package/dist/plan/render.js

@@ -1,5 +1,5 @@
 /** Render an {@link ArchitecturePlan} in the spec's `ARCHITECTURE PLAN` style. */
-export function renderPlan(plan, io) {
+export function renderPlan(plan, io, options = {}) {
     io.log('ARCHITECTURE PLAN');
     io.log('');
     io.log(`Request: "${plan.request}"`);
@@ -49,7 +49,13 @@ export function renderPlan(plan, io) {
         for (const warning of plan.warnings)
             io.log(`  - ${warning}`);
     }
+    if (options.footer === false)
+        return;
     io.log('');
     io.log('This is a plan only — nothing was changed.');
-    io.log('Next: `basalt ai:make` will execute it (arrives in the next phase).');
+    // ai:make only scaffolds entities: suggesting it for a plan without any
+    // would end in "nothing to generate" after a confirmation prompt.
+    io.log(plan.entities.length > 0
+        ? `Next: basalt ai:make "${plan.request}" implements it.`
+        : 'Nothing for ai:make to generate — the steps above are applied by hand.');
 }

package/dist/plan/types.d.ts

@@ -1,4 +1,6 @@
-export type PlanStepKind = 'generator' | 'schema' | 'migration' | 'service' | 'routes' | 'permissions' | 'audit' | 'test' | 'docs' | 'other';
+export type PlanStepKind = 
+/** Install and/or wire an official `@basaltkit/*` package instead of generating code. */
+'package' | 'generator' | 'schema' | 'migration' | 'service' | 'routes' | 'permissions' | 'audit' | 'test' | 'docs' | 'other';
 export interface PlanField {
     name: string;
     type: string;

package/dist/schema/index.d.ts

@@ -230,6 +230,7 @@ export declare const PlanStepKindSchema: z.ZodEnum<{
     generator: "generator";
     migration: "migration";
     other: "other";
+    package: "package";
     permissions: "permissions";
     routes: "routes";
     schema: "schema";
@@ -245,6 +246,7 @@ export declare const PlanStepSchema: z.ZodObject<{
         generator: "generator";
         migration: "migration";
         other: "other";
+        package: "package";
         permissions: "permissions";
         routes: "routes";
         schema: "schema";
@@ -281,6 +283,7 @@ export declare const ArchitecturePlanSchema: z.ZodObject<{
             generator: "generator";
             migration: "migration";
             other: "other";
+            package: "package";
             permissions: "permissions";
             routes: "routes";
             schema: "schema";

package/dist/schema/index.js

@@ -123,6 +123,7 @@ export const PlanEntitySchema = z.object({
     relations: z.array(PlanRelationSchema).optional(),
 });
 export const PlanStepKindSchema = z.enum([
+    'package',
     'generator',
     'schema',
     'migration',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/ai",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -31,7 +31,7 @@
   ],
   "dependencies": {
     "zod": "^4.6.7",
-    "@basaltkit/cli": "^1.7.0",
+    "@basaltkit/cli": "^1.7.1",
     "@basaltkit/generator": "^1.7.0"
   },
   "devDependencies": {