create-manychat-ai-agent 0.0.0-stage → 0.18.0

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# create-manychat-ai-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```sh
+npm create manychat-ai-agent@latest my-agent
+```
+
+Generates a tenant project for
+[manychat-ai-agent](https://github.com/pedronastasi/manychat-ai-agent): `config/`
+from the fictional demo tenant, an offline `.env`, an eval suite, CI, Compose
+and Renovate. It depends on the agent at the version of this scaffolder.
+
+Replace `config/` with your own, and keep the repository private: the generated
+CI fails when it is public. See
+[specs/035](https://github.com/pedronastasi/manychat-ai-agent/blob/main/specs/035-create-scaffolds-a-tenant-project.md).

package/agent/.env.example

@@ -0,0 +1,122 @@
+# ---- Model ------------------------------------------------------------------
+# provider:model — switching provider is an edit here and a restart (ADR-0002).
+#   anthropic:claude-haiku-4-5   openai:gpt-5-mini   google:gemini-2.5-flash
+# Model IDs carry no date suffix.
+AGENT_MODEL=anthropic:claude-haiku-4-5
+# Reasoning models (openai:gpt-5*, openai:o*) spend this budget on reasoning
+# BEFORE emitting any reply, and run out mid-thought at 400: the turn returns no
+# text at all and every reply escalates. Measured 2026-09-15 against the demo
+# catalog, gpt-5-mini used ~900 reasoning tokens before its first output token.
+# A production catalog costs more: gpt-5-mini was still closing turns at 1455 of
+# a 1500 ceiling and failing outright past it, so treat ~1500 as a floor rather
+# than a fix. Raising the ceiling only buys room for deliberation you are also
+# paying for; AGENT_REASONING_EFFORT below caps the deliberation instead.
+AGENT_MAX_OUTPUT_TOKENS=400
+AGENT_TEMPERATURE=0.3
+# Reasoning models only — unset sends nothing, so non-reasoning models are
+# unaffected. Answering from a fixed catalog rarely rewards deliberation, and
+# 'low' buys back both the latency that loses the race and the output budget
+# that otherwise runs out mid-thought.
+# AGENT_REASONING_EFFORT=low
+
+# Voice notes and video soundtracks are transcribed by a second model, in the
+# same provider:model form (specs/020). Unset, a voice note gets the tenant's
+# rules.messages.mediaFallback, asking the contact to type it. Anthropic has no
+# transcription model, so this needs another provider's key as well:
+#   openai:gpt-4o-mini-transcribe   openai:gpt-4o-transcribe   openai:whisper-1
+# TRANSCRIPTION_MODEL=openai:gpt-4o-mini-transcribe
+
+# Only the ACTIVE providers' keys are required.
+ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# GOOGLE_GENERATIVE_AI_API_KEY=
+
+# ---- Ollama (local model) ---------------------------------------------------
+# Start with: docker compose --profile local-model up
+# Then: AGENT_MODEL=ollama:llama3.1:8b pnpm simulate "hola"
+# The first run pulls ~4.7 GB of weights; they persist in a named volume.
+# OLLAMA_BASE_URL=http://localhost:11434/v1
+# Inside compose the agent service overrides this to http://ollama:11434/v1.
+
+# ---- Channel ----------------------------------------------------------------
+CHANNEL=whatsapp
+# HTTPS base used to build external_message_callback. Must be publicly reachable.
+PUBLIC_BASE_URL=https://agent.example.com
+
+# Proxies whose X-Forwarded-For is believed: addresses, CIDR ranges, or the
+# presets loopback, linklocal, uniquelocal. Empty trusts none, so every request
+# is keyed to the socket peer. Behind a reverse proxy, list the proxy, or every
+# caller shares one rate-limit budget (specs/017).
+TRUST_PROXY=
+
+# Validates inbound Dynamic Block requests. Comma-separate two values during
+# rotation so ManyChat flows need no downtime (ADR-0012); SECURITY.md has the
+# steps, including the 24-hour wait before removing the old one. Minimum 16 chars.
+#   openssl rand -hex 32
+MANYCHAT_SHARED_SECRET=change-me-to-a-long-random-string
+
+# Required for the deferred push when the model loses the race.
+MANYCHAT_API_TOKEN=
+MANYCHAT_API_BASE=https://api.manychat.com
+
+# Deferred delivery is two calls: write the reply to a per-subscriber custom
+# field, then trigger a flow that renders it (specs/002). Both name objects that
+# live in the ManyChat account, so renaming them there breaks delivery silently.
+MANYCHAT_REPLY_FIELD=ai_message
+MANYCHAT_REPLY_FLOW_NS=
+# The pause between two messages of a deferred reply, and between two replies
+# to one contact. A flow reads the field when its message step runs, which can
+# be after the trigger has returned, so the next message must not overwrite it
+# sooner. Never pace with a delay before that step inside the flow: the field
+# would be overwritten while it waits (specs/002).
+MANYCHAT_REPLY_GAP_MS=2000
+
+# Each contact's token lives in this custom field, and the Dynamic Block body
+# sends it back as "ai_token": "{{ai_token}}". Only a request carrying it reads
+# the contact's history (specs/019, ADR-0012).
+MANYCHAT_TOKEN_FIELD=ai_token
+# false only during the rollout in specs/019, while tokens reach existing
+# contacts; a request without the token then reads history as it used to.
+CONTACT_TOKENS_ENFORCED=true
+
+# ---- Storage ----------------------------------------------------------------
+DATABASE_URL=postgres://agent:agent@localhost:5432/agent
+TENANT_ID=demo
+
+# ---- Timeouts ---------------------------------------------------------------
+# ManyChat hard-terminates at 10000ms, so the race deadline sits below it.
+RACE_DEADLINE_MS=8000
+# MODEL_ABORT_MS must be GREATER than RACE_DEADLINE_MS. Losing the race does not
+# cancel the model call - it keeps running and delivers via the outbox - so this
+# is the outer safety net that stops a runaway call, not the race timeout.
+MODEL_ABORT_MS=30000
+
+# ---- Runtime ----------------------------------------------------------------
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=info
+
+# ---- Evals (tooling, not runtime) -------------------------------------------
+# Not part of EnvSchema: nothing validates these, and a typo silently falls back
+# to the default rather than failing at boot.
+#
+# Left commented deliberately. `pnpm eval` loads this file via --env-file, so an
+# uncommented value here would pin every run and defeat the per-invocation form:
+#   EVAL_DIR=evals/tenant CONFIG_DIR=config pnpm eval
+#
+# Which suite to replay (specs/009-tenant-eval-suites.md). A tenant deploying
+# from a private overlay keeps its own cases out of the framework's set.
+# EVAL_DIR=evals/golden
+#
+# Which tenant config the suite runs against. CI points this at the fixtures.
+# `pnpm dev` reads it too, so a bug can be reproduced against the fixture tenant
+# (specs/021-contributor-surface.md).
+# CONFIG_DIR=config
+#
+# How slow a reply may be before the suite fails it. Defaults to
+# RACE_DEADLINE_MS. Raise it here rather than raising RACE_DEADLINE_MS: that one
+# is bounded by ManyChat's 10s cutoff and governs the live race, whereas a turn
+# that merely overruns it in an eval is not wrong - it is deferred to the outbox
+# and delivered. A tenant on a reasoning model wants a looser figure for the
+# suite without touching the request path.
+# EVAL_MAX_LATENCY_MS=30000

package/agent/config/catalog.json.example

@@ -0,0 +1,59 @@
+{
+  "businessName": "Demo Academy",
+  "currency": "USD",
+  "courses": [
+    {
+      "id": "foundation",
+      "name": "Foundation Course",
+      "description": "Start from zero. No previous experience required.",
+      "price": { "amount": 45000, "currency": "USD" },
+      "durationHours": 24,
+      "schedule": "Tuesdays and Thursdays, 6-9pm, for 4 weeks",
+      "enrollmentUrl": "https://example.com/enrol/foundation"
+    },
+    {
+      "id": "advanced",
+      "name": "Advanced Course",
+      "description": "For anyone who finished the foundation course or has equivalent experience.",
+      "price": { "amount": 68000, "currency": "USD" },
+      "durationHours": 32,
+      "schedule": "Saturdays, 10am-4pm, for 5 weeks",
+      "enrollmentUrl": "https://example.com/enrol/advanced"
+    },
+    {
+      "id": "weekend-intensive",
+      "name": "Weekend Intensive",
+      "description": "The foundation course condensed into two full days.",
+      "price": { "amount": 32000, "currency": "USD" },
+      "durationHours": 12,
+      "schedule": "One weekend a month, Saturday and Sunday 10am-4pm",
+      "enrollmentUrl": "https://example.com/enrol/weekend-intensive"
+    }
+  ],
+  "faq": [
+    {
+      "question": "Do you give a certificate?",
+      "answer": "Yes, you receive a certificate of attendance when you finish."
+    },
+    {
+      "question": "Are materials included?",
+      "answer": "The practice kit is included with every course."
+    },
+    { "question": "Where are you located?", "answer": "Classes are in person at the main campus." },
+    { "question": "Do you run online classes?", "answer": "All courses are in person for now." },
+    {
+      "question": "Do you guarantee I will get a job?",
+      "answer": "We don't guarantee job placement. The certificate is recognised by local salons."
+    }
+  ],
+  "paymentOptions": [
+    {
+      "id": "instalments",
+      "description": "Any course can be paid in three equal monthly instalments, with no surcharge."
+    },
+    {
+      "id": "deposit",
+      "description": "A $120 deposit holds a place; the rest is due before the first class."
+    }
+  ]
+}

package/agent/config/prompt.md.example

@@ -0,0 +1,22 @@
+You are the front desk for {{businessName}}, a professional training academy.
+You answer people who message on WhatsApp asking about the courses.
+
+LANGUAGE
+Reply in the same language the contact writes in. Default to English.
+
+TONE
+Warm and direct, like someone on the team who knows the offering well.
+Short sentences. Don't oversell, don't sound like a brochure.
+No emoji in every message: at most one, and only when it adds something.
+
+WHAT YOU DO
+Answer questions about prices, schedules, duration, format and how to enrol,
+always taking the facts from the CATALOG. Help the contact find the course that
+fits them and, once they have what they need, ask them to enrol.
+
+WHAT YOU DON'T DO
+Don't negotiate prices or offer discounts.
+Don't invent dates, availability, deadlines or promotions.
+Don't push: one question at a time, and a "not now" is respected.
+Don't promise job outcomes.
+Don't ask for sensitive details (ID numbers, card details, home address).

package/agent/config/rules.json.example

@@ -0,0 +1,31 @@
+{
+  "messages": {
+    "acknowledgement": "Give me one second while I check that.",
+    "escalation": "Let me put you through to someone on the team who can give you the exact answer. They'll reply here shortly.",
+    "mediaFallback": "I couldn't make out that message. Could you type your question for me?",
+    "closer": "You're welcome! Write to me here whenever you need anything else."
+  },
+  "confidenceThreshold": 0.6,
+  "maxTurnsPerConversation": 25,
+  "idleResetHours": 24,
+  "historyDays": 30,
+  "escalationKeywords": [
+    "speak to a human",
+    "talk to someone",
+    "complaint",
+    "refund",
+    "money back",
+    "scam"
+  ],
+  "openingTrigger": {
+    "keywords": ["start workflow"],
+    "message": "Hi! Would you like me to send you the course prices?"
+  },
+  "budget": {
+    "dailyTokenCap": 1000000,
+    "dailyCostCapUsd": 5
+  },
+  "rateLimit": {
+    "turnsPerSubscriberPerHour": 60
+  }
+}

package/agent/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "manychat-ai-agent",
+  "version": "0.18.0",
+  "description": "A provider-agnostic conversational AI agent gateway that bridges no-code chat platforms to any LLM.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pedronastasi/manychat-ai-agent.git"
+  },
+  "type": "module",
+  "bin": {
+    "agent": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "default": "./dist/config/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "db/migrations/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@12.9.1",
+  "scripts": {
+    "dev": "node --experimental-strip-types --disable-warning=ExperimentalWarning --env-file=.env --watch src/main.ts",
+    "bootstrap": "node scripts/setup.mjs",
+    "spec:index": "node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/spec-index.ts",
+    "docs:api": "node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/export-openapi.ts",
+    "docs:build": "pnpm docs:api && vitepress build",
+    "docs:dev": "pnpm docs:api && vitepress dev",
+    "docs:preview": "vitepress preview",
+    "demo:record": "node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/record-demo.ts",
+    "build": "tsc --project tsconfig.build.json",
+    "start": "node dist/main.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "simulate": "node --experimental-strip-types --disable-warning=ExperimentalWarning --env-file=.env src/channels/manychat/simulator.ts",
+    "eval": "node --experimental-strip-types --disable-warning=ExperimentalWarning --env-file=.env evals/run.ts",
+    "eval:mock": "node --experimental-strip-types --disable-warning=ExperimentalWarning evals/run.ts",
+    "tokens:backfill": "node --experimental-strip-types --disable-warning=ExperimentalWarning --env-file=.env src/backfill.ts",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "worker": "node --experimental-strip-types --disable-warning=ExperimentalWarning --env-file=.env src/outbox/worker.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^4.0.53",
+    "@ai-sdk/google": "^4.0.69",
+    "@ai-sdk/openai": "^4.0.66",
+    "@ai-sdk/provider": "4.0.22",
+    "@fastify/helmet": "^13.1.1",
+    "@fastify/rate-limit": "^11.2.0",
+    "@fastify/swagger": "^9.8.1",
+    "@fastify/under-pressure": "^9.1.0",
+    "ai": "^7.0.100",
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.12.4",
+    "fastify-type-provider-zod": "^7.0.0",
+    "manychat-sdk": "^0.1.0",
+    "pino": "^10.4.0",
+    "postgres": "^3.4.9",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": "^0.5.8"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "drizzle-kit": "^0.31.10",
+    "eslint": "^10.10.0",
+    "mermaid": "^12.0.0",
+    "prettier": "^3.9.6",
+    "typescript": "~6.0.0",
+    "typescript-eslint": "^8.70.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^5.0.0",
+    "vue": "^3.5.43",
+    "yaml": "^2.9.1"
+  }
+}

package/demo-tenant.mjs

@@ -0,0 +1,36 @@
+/**
+ * The fictional demo tenant, as both `pnpm bootstrap` and `create` start from
+ * it (specs/035). One list and one set of edits, so the two cannot drift into a
+ * second copy of the example tenant.
+ */
+
+/** The committed examples a first run copies, and the names they take. */
+export const EXAMPLE_CONFIG = [
+  ['config/prompt.md.example', 'config/prompt.md'],
+  ['config/catalog.json.example', 'config/catalog.json'],
+  ['config/rules.json.example', 'config/rules.json'],
+];
+
+/** Each line of `.env.example` an offline first run replaces, and with what. */
+const OFFLINE = [
+  ['MANYCHAT_SHARED_SECRET=change-me-to-a-long-random-string', 'MANYCHAT_SHARED_SECRET=<secret>'],
+  // A runnable offline setup: no API key, no database to install.
+  ['AGENT_MODEL=anthropic:claude-haiku-4-5', 'AGENT_MODEL=mock:demo'],
+  ['DATABASE_URL=postgres://agent:agent@localhost:5432/agent', 'DATABASE_URL=pglite'],
+  // With no ManyChat account there is no field to hold a contact's token, so
+  // `simulate` could never present one and would get no history.
+  ['CONTACT_TOKENS_ENFORCED=true', 'CONTACT_TOKENS_ENFORCED=false'],
+];
+
+/**
+ * `.env.example` with the offline defaults. Throws when a line it replaces is
+ * gone, rather than writing a `.env` that silently needs an API key.
+ */
+export function offlineEnv(example, secret) {
+  let env = example;
+  for (const [line, replacement] of OFFLINE) {
+    if (!env.includes(line)) throw new Error(`.env.example no longer contains: ${line}`);
+    env = env.replace(line, replacement.replace('<secret>', secret));
+  }
+  return env;
+}

package/index.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * `npm create manychat-ai-agent@latest my-agent` (specs/035).
+ *
+ * Generates a tenant project from the fictional demo tenant and nothing else.
+ * Never from a live deployment, and never over an existing directory.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXAMPLE_CONFIG, offlineEnv } from './demo-tenant.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Where the demo tenant is read from. Published, `prepack` has copied it into
+ * `agent/`; in this repository it is the root, so the scaffolder and
+ * `pnpm bootstrap` read the same committed files (C1, C9).
+ */
+const agentRoot = existsSync(join(here, 'agent')) ? join(here, 'agent') : join(here, '..', '..');
+
+const { version } = JSON.parse(readFileSync(join(here, 'package.json'), 'utf8'));
+const agent = JSON.parse(readFileSync(join(agentRoot, 'package.json'), 'utf8'));
+
+const target = process.argv[2];
+if (target === undefined || target.startsWith('-')) {
+  console.error('Usage: npm create manychat-ai-agent@latest <directory>');
+  process.exit(2);
+}
+
+const root = resolve(target);
+const name = basename(root);
+// The name becomes the package name and the eval suite's directory.
+if (!/^[a-z0-9][a-z0-9._-]*$/.test(name)) {
+  console.error(`"${name}" is not a valid name: use lowercase letters, digits, ".", "_" or "-".`);
+  process.exit(2);
+}
+if (existsSync(root) && readdirSync(root).length > 0) {
+  console.error(`${root} is not empty. Nothing was written.`);
+  process.exit(1);
+}
+
+const template = file => readFileSync(join(here, 'template', file), 'utf8');
+
+function write(path, content) {
+  mkdirSync(dirname(join(root, path)), { recursive: true });
+  writeFileSync(join(root, path), content);
+  console.log(`  created  ${path}`);
+}
+
+for (const [from, to] of EXAMPLE_CONFIG) {
+  write(to, readFileSync(join(agentRoot, from)));
+}
+write(
+  '.env',
+  offlineEnv(
+    readFileSync(join(agentRoot, '.env.example'), 'utf8'),
+    randomBytes(32).toString('hex'),
+  ),
+);
+write(`evals/${name}/cases.jsonl`, template('cases.jsonl'));
+write(
+  'package.json',
+  `${JSON.stringify(
+    {
+      name,
+      // config/ is real tenant data once the tenant replaces the demo, so this
+      // project is never published.
+      private: true,
+      type: 'module',
+      packageManager: agent.packageManager,
+      scripts: {
+        check: 'agent config check',
+        eval: `EVAL_DIR=evals/${name} agent eval`,
+        test: 'vitest run --passWithNoTests',
+      },
+      dependencies: { 'manychat-ai-agent': `^${version}` },
+      devDependencies: {
+        // The embedded database the offline .env selects; the agent leaves it
+        // to the tenant as an optional peer, so the image does not carry it.
+        '@electric-sql/pglite': agent.peerDependencies['@electric-sql/pglite'],
+        vitest: agent.devDependencies.vitest,
+      },
+    },
+    null,
+    2,
+  )}\n`,
+);
+write('docker-compose.yml', template('docker-compose.yml').replaceAll('{{version}}', version));
+write('.github/workflows/ci.yml', template('ci.yml'));
+write('renovate.json', template('renovate.json'));
+write('.gitignore', template('gitignore'));
+
+console.log(`
+  Ready. Next:
+
+    cd ${target}
+    pnpm install
+    pnpm check && pnpm eval
+
+  config/ is the fictional demo tenant: replace it with your own. Keep this
+  repository private; its CI fails when it is public.
+`);

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "create-manychat-ai-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.18.0",
+  "description": "Scaffolds a manychat-ai-agent tenant project from the fictional demo tenant.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pedronastasi/manychat-ai-agent.git",
+    "directory": "packages/create"
+  },
+  "type": "module",
+  "bin": {
+    "create-manychat-ai-agent": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "demo-tenant.mjs",
+    "template/",
+    "README.md",
+    "agent/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "prepack": "node pack-agent.mjs",
+    "postpack": "node pack-agent.mjs --clean"
+  }
+}

package/template/cases.jsonl

@@ -0,0 +1,5 @@
+{"id": "greeting", "text": "hello!", "expect": {"escalate": false}}
+{"id": "price", "text": "how much is the foundation course?", "expect": {"escalate": false}, "must_not_invent_prices": true}
+{"id": "schedule", "text": "what days are the foundation classes?", "expect": {"escalate": false}}
+{"id": "discount", "text": "can you give me a discount?", "expect": {"escalate": true, "reason": "price_negotiation"}}
+{"id": "human", "text": "can i speak to a human?", "expect": {"escalate": true}}

package/template/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push: { branches: [main] }
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      # config/ is this tenant's prompt, prices and schedule, tracked because
+      # the repository is private. Made public, it fails here on the next push
+      # rather than after it has been indexed (specs/035).
+      - name: Repository is private
+        env:
+          PRIVATE: ${{ github.event.repository.private }}
+        run: |
+          if [ "$PRIVATE" != "true" ]; then
+            echo "::error::This repository is public, and config/ holds tenant data. Make it private."
+            exit 1
+          fi
+
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with: { node-version: 24, cache: pnpm }
+
+      - run: pnpm install --frozen-lockfile
+
+      # The validation the server runs at startup, so a typo in config/ fails
+      # this pull request rather than the container at boot. Placeholder
+      # environment: the check parses it and connects to nothing.
+      - name: Config check
+        run: pnpm check
+        env:
+          AGENT_MODEL: mock:demo
+          PUBLIC_BASE_URL: https://ci.example.com
+          MANYCHAT_SHARED_SECRET: ci-secret-ci-secret-ci-secret-xx
+          DATABASE_URL: pglite
+
+      # The eval suite against the mock model: free and deterministic. A run
+      # against a real model costs money and stays a deliberate local step.
+      - name: Eval (mock model)
+        run: pnpm eval
+        env:
+          AGENT_MODEL: mock:demo
+          PUBLIC_BASE_URL: https://ci.example.com
+          MANYCHAT_SHARED_SECRET: ci-secret-ci-secret-ci-secret-xx
+          DATABASE_URL: pglite
+
+      - name: Tenant tests
+        run: pnpm test

package/template/docker-compose.yml

@@ -0,0 +1,36 @@
+services:
+  postgres:
+    image: postgres:18-alpine
+    environment:
+      POSTGRES_USER: agent
+      POSTGRES_PASSWORD: agent
+      POSTGRES_DB: agent
+    volumes: ['pgdata:/var/lib/postgresql']
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U agent']
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  agent:
+    # The published agent, at the version package.json depends on. Renovate
+    # moves both in one pull request.
+    image: ghcr.io/pedronastasi/manychat-ai-agent:{{version}}
+    depends_on:
+      postgres: { condition: service_healthy }
+    environment:
+      DATABASE_URL: postgres://agent:agent@postgres:5432/agent
+      # The offline .env turns contact tokens off so `simulate` gets history.
+      # A deployment never runs that way: these override .env (specs/019).
+      CONTACT_TOKENS_ENFORCED: 'true'
+      PORT: 3000
+    # A directory, never single files: an editor that replaces a file leaves a
+    # single-file mount showing the old one. SIGHUP reloads it.
+    volumes: ['./config:/app/config:ro']
+    # Credentials come from .env, never from this file.
+    env_file: [.env]
+    ports: ['3000:3000']
+    restart: unless-stopped
+
+volumes:
+  pgdata:

package/template/gitignore

@@ -0,0 +1,8 @@
+node_modules/
+
+# Credentials live in each developer's .env and in the server's, never here.
+.env
+.env.*
+
+# config/ is tracked: it is this tenant's configuration, and the repository
+# holding it stays private. CI fails when it is not (specs/035).

package/template/renovate.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended", ":semanticCommits"],
+  "packageRules": [
+    {
+      "description": "The agent's npm package and its image are one version: CI checks the package, docker-compose.yml runs the image. A release arrives as one pull request moving both, never automerged.",
+      "matchPackageNames": ["manychat-ai-agent", "ghcr.io/pedronastasi/manychat-ai-agent"],
+      "groupName": "manychat-ai-agent",
+      "automerge": false
+    }
+  ]
+}