@meffecta/agent 1.0.2 → 1.0.7

package/lib/create-job.js

@@ -0,0 +1,344 @@
+// `create-job "<what you want it to do>"` — a job definition written by the agent itself.
+//
+// A job file is small but unforgiving: five cron fields in the deployment's timezone,
+// frontmatter the engine parses strictly, an `inbox:` that fails closed without
+// `allowFrom:`, and a prompt that has to name the world and skills this deployment
+// actually has. Someone who has just installed the CLI knows none of that, and the failure
+// is quiet — a job that never registers looks exactly like a job that has not run yet.
+//
+// WHERE THE MODEL RUNS: on the deployment, not here. It already holds the Claude token, so
+// nothing new is needed on the operator's machine — but the real reason is context. A run
+// has the content repo cloned and the engine's default skills mounted, so it can read the
+// existing jobs for house style, the worlds, and the systems/ register for what this
+// deployment can actually reach. A `claude` on the laptop would see the content repo and
+// none of the skills, and would invent capabilities that are not there.
+//
+// WHAT COMES BACK IS NOT TRUSTED. The file is parsed with the engine's own frontmatter
+// rules and checked before it is written: a valid cron, a name that is a name, `allowFrom:`
+// whenever `inbox:` appears, an effort the engine accepts. A model that returns something
+// plausible-but-wrong is the expected case, not the exceptional one — this command's value
+// is the checking, not the generating.
+//
+// It writes a file and stops. No commit, no push, no deploy: the operator reads the prompt
+// their agent will run before anyone else does.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { requireDeployment, UserError } from "./config.js";
+import { parseFlags } from "./flags.js";
+import { api } from "./gcloud.js";
+
+/** The engine's list, and it rejects anything else (src/jobs.ts). */
+const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+
+/** Sentinels rather than code fences: a job prompt may itself contain fenced blocks. */
+const BEGIN = "JOB_FILE_BEGIN";
+const END = "JOB_FILE_END";
+
+/**
+ * A cron field, in the five-field form Cloud Scheduler and croner both accept. Deliberately
+ * strict: a field the engine would take but Cloud Scheduler would reject creates a job that
+ * registers locally and silently never fires on a scaled-to-zero deployment.
+ */
+function validCronField(field, min, max, names = []) {
+  return field.split(",").every((part) => {
+    const [range, step] = part.split("/");
+    if (step !== undefined && !/^\d+$/.test(step)) {
+      return false;
+    }
+    if (range === "*") {
+      return true;
+    }
+    const value = (token) => {
+      const index = names.indexOf(token.toLowerCase());
+      return index >= 0 ? index : Number(token);
+    };
+    const bounds = range.split("-");
+    if (bounds.length > 2) {
+      return false;
+    }
+    return bounds.every((token) => {
+      const n = value(token);
+      return Number.isInteger(n) && n >= min && n <= max;
+    });
+  });
+}
+
+const MONTHS = ["", "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+
+export function validCron(expression) {
+  const fields = (expression ?? "").trim().split(/\s+/);
+  if (fields.length !== 5) {
+    return false;
+  }
+  const [minute, hour, dom, month, dow] = fields;
+  return (
+    validCronField(minute, 0, 59) &&
+    validCronField(hour, 0, 23) &&
+    validCronField(dom, 1, 31) &&
+    validCronField(month, 1, 12, MONTHS) &&
+    validCronField(dow, 0, 6, DAYS)
+  );
+}
+
+/** A job name is a filename, a Cloud Scheduler job id, and a memory directory. */
+export function validName(name) {
+  return /^[a-z0-9](?:[a-z0-9-]{0,46}[a-z0-9])?$/.test(name ?? "");
+}
+
+/**
+ * The engine's frontmatter rules, exactly (src/jobs.ts): a leading `---` block of
+ * `key: value` lines. Reimplemented rather than imported because the CLI ships without the
+ * engine — but it must not drift, so a test compares the two on the same input.
+ */
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) {
+    return { meta: {}, body: content.trim() };
+  }
+  const meta = {};
+  for (const line of match[1].split("\n")) {
+    const [key, ...rest] = line.split(": ");
+    if (key && rest.length) {
+      meta[key.trim()] = rest.join(": ").replace(/^["']|["']$/g, "");
+    }
+  }
+  return { meta, body: match[2].trim() };
+}
+
+/** Pull the file out of the model's answer. Returns null when it did not follow the shape. */
+export function extractJobFile(answer) {
+  const start = answer.indexOf(BEGIN);
+  const stop = answer.indexOf(END);
+  if (start < 0 || stop < 0 || stop < start) {
+    return null;
+  }
+  const file = answer.slice(start + BEGIN.length, stop).trim();
+  const named = answer.match(/JOB_NAME:\s*([^\n]+)/);
+  const notes = answer.match(/JOB_NOTES:\s*([^\n]+)/);
+  return {
+    name: named?.[1].trim().replace(/\.md$/, ""),
+    file: `${file}\n`,
+    notes: notes?.[1].trim(),
+  };
+}
+
+/**
+ * Everything that would make the engine, or Cloud Scheduler, quietly not run this. Returns
+ * a list of human problems — empty means it is safe to write.
+ */
+export function validateJob({ name, file, existing = [] }) {
+  const problems = [];
+  if (!validName(name)) {
+    problems.push(
+      `"${name}" is not usable as a job name. It becomes a filename, a Cloud Scheduler job id and a memory directory: lower-case letters, digits and hyphens.`,
+    );
+  }
+  if (existing.includes(name)) {
+    problems.push(`A job called "${name}" already exists. Pass --name to call this one something else.`);
+  }
+  const { meta, body } = parseFrontmatter(file);
+  if (!file.startsWith("---\n")) {
+    problems.push("No frontmatter block — the engine would read the whole file as the prompt.");
+  }
+  if (body.length < 20) {
+    problems.push("The prompt body is empty or too short to be a job.");
+  }
+  if (meta.cron !== undefined && !validCron(meta.cron)) {
+    problems.push(`cron: "${meta.cron}" is not a valid five-field expression, so no trigger would be created.`);
+  }
+  // The engine enforces this and fails closed; catching it here explains why.
+  if (meta.inbox && !meta.allowFrom) {
+    problems.push(
+      `inbox: ${meta.inbox} without allowFrom: — the engine refuses to register a mail-triggered job with no sender policy, deliberately. Add allowFrom: with the addresses or domains allowed to trigger it.`,
+    );
+  }
+  if (meta.effort && !EFFORT_LEVELS.includes(meta.effort)) {
+    problems.push(`effort: ${meta.effort} is not one of ${EFFORT_LEVELS.join(", ")} — the engine would ignore it.`);
+  }
+  if (meta.timeoutSeconds !== undefined) {
+    const seconds = Number(meta.timeoutSeconds);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+      problems.push(`timeoutSeconds: ${meta.timeoutSeconds} is not a positive number — the engine would ignore it.`);
+    }
+  }
+  if (!meta.cron && !meta.webhook && !meta.inbox) {
+    // Not an error: a job you trigger by hand is a real thing, and worth saying out loud
+    // rather than leaving someone waiting for a schedule that was never asked for.
+    problems.push(
+      "__note__No cron:, webhook: or inbox: — this job will only run when you ask it to, with `meffecta-agent run`.",
+    );
+  }
+  return problems;
+}
+
+/** What the deployment is asked. The response contract is the load-bearing part. */
+function buildPrompt(description, { timezone, existing }) {
+  return [
+    "You are writing ONE job definition file for the Meffecta Agent deployment you are running in.",
+    "",
+    "Before writing anything, read what this deployment actually is:",
+    "  - jobs/*.md in your working directory — the house style, and what already exists",
+    "  - systems/ (or ENVIRONMENT.md) — what this deployment can reach, and the variables for each",
+    "  - worlds/ if present — the projects/products a job can be pointed at",
+    "  - your own available skills — use only skills that exist; never invent a capability",
+    "",
+    "The operator asked for:",
+    `  ${JSON.stringify(description)}`,
+    "",
+    "Rules:",
+    `  - cron: is five fields, interpreted in ${timezone}. "every Wednesday at 2pm" is "0 14 * * 3".`,
+    "  - Use cron: only if a schedule was actually asked for. Otherwise omit it.",
+    "  - If the job is triggered by mail, inbox: REQUIRES allowFrom: — the engine refuses",
+    "    to register one without it. Never emit inbox: without allowFrom:.",
+    "  - effort: must be one of low, medium, high, xhigh, max, or omitted.",
+    "  - Do not invent env vars, worlds, repos or skills. If something is needed that this",
+    "    deployment does not have, say so in JOB_NOTES rather than pretending it exists.",
+    "  - The prompt body should say what to produce and where it goes (email? a file? a PR?),",
+    "    and be specific about the data source, matching how the existing jobs are written.",
+    existing.length ? `  - These names are taken: ${existing.join(", ")}` : "",
+    "",
+    "Answer in EXACTLY this shape and nothing else — no preamble, no code fences:",
+    "",
+    "JOB_NAME: <short-kebab-case-name>",
+    `${BEGIN}`,
+    "---",
+    "<frontmatter lines>",
+    "---",
+    "<the prompt body>",
+    `${END}`,
+    "JOB_NOTES: <one line: anything the operator must set up or decide, or 'none'>",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+export async function createJob(args) {
+  const { flags, positional } = parseFlags(args, { name: {}, model: {}, "dry-run": { type: "boolean" } });
+  const description = positional.join(" ").trim();
+  if (!description) {
+    throw new UserError(
+      'What should it do? e.g.\n\n  meffecta-agent create-job "a marketing report every Wednesday at 2pm"',
+    );
+  }
+  const d = requireDeployment();
+  const jobsDir = resolve(process.cwd(), "jobs");
+  const existing = existsSync(jobsDir)
+    ? readdirSync(jobsDir)
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => f.replace(/\.md$/, ""))
+    : [];
+
+  const timezone = d.TIMEZONE ?? "Europe/Stockholm";
+  console.error(`Asking ${d.SERVICE} to write it — it can see your jobs, worlds and skills. This takes a minute.`);
+  const params = new URLSearchParams({ prompt: buildPrompt(description, { timezone, existing }) });
+  if (flags.model) {
+    params.set("model", String(flags.model));
+  }
+  const answer = await api(d, `/test?${params}`, { accept: "text/markdown" });
+
+  const extracted = extractJobFile(answer);
+  if (!extracted?.file) {
+    throw new UserError(
+      `The deployment did not answer in the expected shape, so nothing was written.\n\n${answer.slice(0, 600)}`,
+    );
+  }
+  const name = String(flags.name ?? extracted.name ?? "").trim();
+  const problems = validateJob({ name, file: extracted.file, existing });
+  const notes = problems.filter((p) => p.startsWith("__note__")).map((p) => p.slice("__note__".length));
+  const errors = problems.filter((p) => !p.startsWith("__note__"));
+
+  console.log("");
+  console.log(`── jobs/${name || "?"}.md ${"─".repeat(Math.max(0, 60 - name.length))}`);
+  console.log(extracted.file.trimEnd());
+  console.log("─".repeat(72));
+
+  if (extracted.notes && extracted.notes.toLowerCase() !== "none") {
+    console.log(`\nIt says: ${extracted.notes}`);
+  }
+  for (const note of notes) {
+    console.log(`\nℹ ${note}`);
+  }
+  if (errors.length) {
+    console.log("");
+    for (const problem of errors) {
+      console.log(`✖ ${problem}`);
+    }
+    throw new UserError("\nNot written. Re-run to try again, or fix it by hand from the text above.");
+  }
+
+  const { meta } = parseFrontmatter(extracted.file);
+  if (flags["dry-run"]) {
+    console.log("\n(dry run — nothing written)");
+    return 0;
+  }
+  const target = resolve(jobsDir, `${name}.md`);
+  mkdirSync(jobsDir, { recursive: true });
+  writeFileSync(target, extracted.file);
+  console.log(`\n✔ Written to jobs/${name}.md — read it before you commit it. It is a prompt your agent will run.`);
+  console.log("");
+  console.log("  git add jobs/ && git commit && git push     the prompt is live on the next run");
+  if (meta.cron) {
+    console.log(`  meffecta-agent deploy                       registers the schedule (${meta.cron}, ${timezone})`);
+  }
+  console.log(
+    `  meffecta-agent run ${name}${" ".repeat(Math.max(1, 24 - name.length))}try it now, before any schedule does`,
+  );
+  return 0;
+}
+
+/**
+ * `check-jobs` — the same validation, on files that already exist.
+ *
+ * `create-job` writes a file and stops so the operator reads it first, which means the
+ * next thing that happens is a hand-edit. Without this, editing the cron by hand puts you
+ * straight back into the silent failure the checking existed to prevent — and the jobs
+ * written before this command existed have never been checked at all.
+ */
+export async function checkJobs() {
+  const jobsDir = resolve(process.cwd(), "jobs");
+  if (!existsSync(jobsDir)) {
+    throw new UserError(`No jobs/ directory in ${process.cwd()}. Run this from your content repo.`);
+  }
+  const files = readdirSync(jobsDir).filter((f) => f.endsWith(".md"));
+  if (files.length === 0) {
+    console.log('No job files yet. Write one: meffecta-agent create-job "..."');
+    return 0;
+  }
+  const names = files.map((f) => f.replace(/\.md$/, ""));
+  let failed = 0;
+  for (const file of files.sort()) {
+    const name = file.replace(/\.md$/, "");
+    // `existing` excludes this file, or every job would collide with itself.
+    const problems = validateJob({
+      name,
+      file: readFileSync(resolve(jobsDir, file), "utf8"),
+      existing: names.filter((other) => other !== name),
+    });
+    const errors = problems.filter((p) => !p.startsWith("__note__"));
+    const notes = problems.filter((p) => p.startsWith("__note__"));
+    if (errors.length === 0 && notes.length === 0) {
+      console.log(`✔ ${name}`);
+      continue;
+    }
+    console.log(`${errors.length ? "✖" : "·"} ${name}`);
+    for (const problem of errors) {
+      console.log(`    ${problem}`);
+    }
+    for (const note of notes) {
+      console.log(`    ${note.slice("__note__".length)}`);
+    }
+    failed += errors.length ? 1 : 0;
+  }
+  console.log("");
+  console.log(
+    failed
+      ? `${failed} of ${files.length} would not register or run as written.`
+      : `${files.length} job file(s), all valid. Triggers still need a restart: meffecta-agent deploy`,
+  );
+  return failed ? 1 : 0;
+}
+
+/** Exported for the test that keeps this parser in step with the engine's. */
+export const __internals = { buildPrompt, BEGIN, END };

package/lib/doctor.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { requireDeployment, UserError } from "./config.js";
 import { api, capture, gcloudArgs, requireCommand } from "./gcloud.js";
+import { cliVersion, isNewer, latestPublished } from "./version.js";
 
 /**
  * Judge a deployment, rather than describe it.
@@ -39,7 +40,7 @@ class Report {
 
 const MARK = { [OK]: "✓", [WARN]: "!", [FAIL]: "✗" };
 
-/** Cron minutes the sweep should run at, given the poll interval. Mirrors setup-scheduler.sh. */
+/** Cron minutes the sweep should run at, given the poll interval. Mirrors sync-triggers.sh. */
 
 /**
  * The jobs the content repo declares on disk, parsed the way the engine parses them.
@@ -83,7 +84,7 @@ export function readLocalJobs(dir) {
 
 export function expectedSweepSchedule(pollSeconds) {
   // Unset means the engine's own default; 0 must clamp to one minute rather than fall
-  // back to it, which is what setup-scheduler.sh does and what doctor has to agree with.
+  // back to it, which is what sync-triggers.sh does and what doctor has to agree with.
   const raw = pollSeconds === undefined || pollSeconds === null || pollSeconds === "" ? 300 : Number(pollSeconds);
   const seconds = Number.isFinite(raw) ? raw : 300;
   const minutes = Math.max(1, Math.ceil(seconds / 60));
@@ -105,7 +106,7 @@ export function judgeTriggering({ minScale, external, throttled }) {
       level: FAIL,
       title: "Scaled to zero with no triggers",
       detail: "Nothing in the service fires on its own, so no job will ever run. It will look healthy.",
-      fix: "meffecta-agent setup-scheduler",
+      fix: "meffecta-agent sync-triggers",
     });
   } else if (!scaledToZero && external) {
     findings.push({
@@ -182,13 +183,40 @@ export async function doctor() {
     );
   }
 
+  // Being several releases behind is a health fact, and nothing else in the CLI mentions it
+  // unprompted. Non-fatal when the registry is unreachable: offline is not a broken
+  // deployment, and a doctor that fails on a network hiccup stops being run.
+  const latest = await latestPublished();
+  if (latest && isNewer(latest, cliVersion())) {
+    r.warn(
+      `A newer @meffecta/agent is published (${cliVersion()} → ${latest})`,
+      "Each release pins the engine image published beside it, so upgrading the tooling is how a deployment moves engine version.",
+      "meffecta-agent upgrade",
+    );
+  }
+
   const secrets = new Set(
     capture("gcloud", gcloudArgs(d, ["secrets", "list", "--format=value(name)"]))
       .split("\n")
       .filter(Boolean)
       .map((n) => n.split("/").pop()),
   );
-  for (const name of ["AGENT_WEBHOOK_SECRET", "CLAUDE_CODE_OAUTH_TOKEN", "GITHUB_TOKEN"]) {
+  // AGENT_WEBHOOK_SECRET is the old name for AGENT_API_SECRET and the engine still reads
+  // it, so a deployment on the old one is working, not broken — check the pair, not the
+  // preferred name, or doctor fails a healthy service.
+  const apiSecretName = env.AGENT_API_SECRET
+    ? "AGENT_API_SECRET"
+    : env.AGENT_WEBHOOK_SECRET
+      ? "AGENT_WEBHOOK_SECRET"
+      : "AGENT_API_SECRET";
+  if (apiSecretName === "AGENT_WEBHOOK_SECRET") {
+    r.warn(
+      "AGENT_WEBHOOK_SECRET is the old name",
+      "It guards the whole API, not just webhooks, and is now AGENT_API_SECRET. The engine reads both.",
+      "meffecta-agent set-secret AGENT_API_SECRET   (paste the same value, deploy, then delete the old one)",
+    );
+  }
+  for (const name of [apiSecretName, "CLAUDE_CODE_OAUTH_TOKEN", "GITHUB_TOKEN"]) {
     const ref = env[name]?.valueFrom?.secretKeyRef?.name;
     if (!env[name]) {
       r.fail(`${name} not set`, "Required by the engine.", `meffecta-agent set-secret ${name}`);
@@ -277,7 +305,7 @@ export async function doctor() {
         drifted.length && `${drifted.length} schedule(s) out of date: ${drifted.map((j) => j.name).join(", ")}`,
         stale.length && `${stale.length} trigger(s) for jobs that no longer exist: ${stale.join(", ")}`,
       ].filter(Boolean);
-      r.fail("Triggers do not match the content repo", parts.join("; "), "meffecta-agent setup-scheduler");
+      r.fail("Triggers do not match the content repo", parts.join("; "), "meffecta-agent sync-triggers");
     } else if (wanted.length) {
       r.ok("Cron triggers", `${wanted.length} in place, all matching the content repo`);
     }
@@ -306,7 +334,7 @@ export async function doctor() {
       r.fail(
         "No sweep",
         "Due follow-ups, runs left behind by a dead process, and watched inboxes are all handled by the sweep. Without it they never happen.",
-        "meffecta-agent setup-scheduler",
+        "meffecta-agent sync-triggers",
       );
     } else {
       const watchesInbox = jobs.some((j) => j.inbox);
@@ -319,7 +347,7 @@ export async function doctor() {
               ? `AGENT_INBOX_POLL_SECONDS=${value("AGENT_INBOX_POLL_SECONDS") ?? 300} wants "${expected}"`
               : `no job watches an inbox, so "${expected}" is enough`
           }.`,
-          "meffecta-agent setup-scheduler",
+          "meffecta-agent sync-triggers",
         );
       } else {
         r.ok("Sweep", `${sweep.schedule}${watchesInbox ? " — matching the inbox poll interval" : ""}`);
@@ -351,7 +379,7 @@ export async function doctor() {
       r.fail(
         "No task queue",
         "External triggers are configured but the queue is missing.",
-        "meffecta-agent setup-scheduler",
+        "meffecta-agent sync-triggers",
       );
     }
   }

package/lib/gcloud.js

@@ -38,6 +38,31 @@ export function capture(command, args) {
   return result.stdout.trim();
 }
 
+/**
+ * Run a command and resolve with its stdout, or null when it fails.
+ *
+ * `capture` throws, which is right for a command acting on one thing. It is wrong for
+ * taking an inventory: a half-finished set-up is exactly what someone is looking at when
+ * they ask what exists, and stopping at the first absent resource would hide the rest.
+ * Here a missing thing is an answer.
+ *
+ * stdout only, deliberately — gcloud narrates on stderr ("Encryption: Google-managed key")
+ * even when asked for JSON. It is still drained, or a large one would fill the pipe and
+ * hang the read.
+ */
+export function probe(command, args) {
+  return new Promise((resolveRun) => {
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    child.stdout.on("data", (chunk) => {
+      out += chunk;
+    });
+    child.stderr.on("data", () => {});
+    child.on("error", () => resolveRun(null));
+    child.on("close", (code) => resolveRun(code === 0 ? out.trim() : null));
+  });
+}
+
 export function requireCommand(name, why) {
   const found = spawnSync(process.platform === "win32" ? "where" : "which", [name], { encoding: "utf8" });
   if (found.status !== 0) {
@@ -69,27 +94,31 @@ export function serviceUrl(deployment) {
 }
 
 /**
- * The deployment's webhook secret, straight from Secret Manager into memory. It is never
+ * The deployment's API secret, straight from Secret Manager into memory. It is never
  * printed, never passed as a process argument, and only ever leaves here as a header.
+ *
+ * AGENT_WEBHOOK_SECRET is the old name — it guarded webhooks once, then everything else —
+ * and the engine still reads it, so this tries both rather than telling a deployment that
+ * works fine that its secret is missing.
  */
-export function webhookSecret(deployment) {
-  try {
-    return capture(
-      "gcloud",
-      gcloudArgs(deployment, ["secrets", "versions", "access", "latest", "--secret=AGENT_WEBHOOK_SECRET"]),
-    );
-  } catch {
-    throw new UserError(
-      "Could not read AGENT_WEBHOOK_SECRET from Secret Manager.\n" +
-        "Create it first: meffecta-agent set-secret AGENT_WEBHOOK_SECRET --random",
-    );
+export function apiSecret(deployment) {
+  for (const name of ["AGENT_API_SECRET", "AGENT_WEBHOOK_SECRET"]) {
+    try {
+      return capture("gcloud", gcloudArgs(deployment, ["secrets", "versions", "access", "latest", `--secret=${name}`]));
+    } catch {
+      // Try the other name before deciding there is no secret at all.
+    }
   }
+  throw new UserError(
+    "Could not read AGENT_API_SECRET from Secret Manager (nor the old AGENT_WEBHOOK_SECRET).\n" +
+      "Create it first: meffecta-agent set-secret AGENT_API_SECRET --random",
+  );
 }
 
 /** An authenticated request to the deployment's own API. */
 export async function api(deployment, path, { method = "GET", body, accept } = {}) {
   const url = `${serviceUrl(deployment)}${path}`;
-  const headers = { Authorization: `Bearer ${webhookSecret(deployment)}` };
+  const headers = { Authorization: `Bearer ${apiSecret(deployment)}` };
   if (accept) {
     headers.Accept = accept;
   }

package/lib/integrations.js

@@ -132,6 +132,57 @@ const INTEGRATIONS = {
     ],
   },
 
+  hubspot: {
+    title: "HubSpot CRM",
+    gives: "query-hubspot — pipelines, contacts, deals, activity. manage-hubspot writes, and only when a job says to",
+    needs: [
+      "A private app in the HubSpot portal: Settings → Integrations → Private Apps → Create.",
+      "Grant only the scopes the jobs need — crm.objects.*.read for reporting; add the",
+      "matching .write scopes only if a job is meant to change records.",
+    ],
+    steps: [["meffecta-agent set-secret HUBSPOT_TOKEN", "the private app's access token"]],
+    more: [
+      "A second portal is HUBSPOT_<NAME>_TOKEN, and the job says which portal it may touch.",
+      "Reading and writing are two skills on purpose: a reporting job loads query-hubspot and",
+      "then cannot alter the CRM at all, because the ability to is not in its context.",
+      "Rotate the token from the same screen; HubSpot can expire the old one after 7 days.",
+    ],
+  },
+
+  kleer: {
+    title: "Kleer accounting and payroll",
+    gives:
+      "query-kleer — invoices out and in, payment status, vouchers, the SIE4E export, payroll runs, bank transactions. Read-only",
+    needs: [
+      "A Kleer API token, requested through your accounting consultant — Kleer issues it by",
+      "SMS, there is no self-service. It inherits the permissions of the Kleer user it is",
+      "bound to, so ask for it on a READ-ONLY user: that, not the skill, is what stops a",
+      "write. (Kleer was PE Accounting before the rebrand; the docs still say PE in places.)",
+    ],
+    steps: [["meffecta-agent set-secret KLEER_API_TOKEN", "the token Kleer sent"]],
+    more: [
+      "Company ids are discovered at run time from the token, so nothing else needs setting.",
+      "There is a test environment on the same token, mirroring production a day behind —",
+      "worth pointing a new job at first, since live books are not a place to explore.",
+    ],
+  },
+
+  mongodb: {
+    title: "A MongoDB database",
+    gives: "query-mongodb — counts, filters and aggregations over a product database. Read-only",
+    needs: [
+      "A MongoDB user with the `read` role on the database and nothing more, and a connection",
+      "URI for it. The role is the real boundary — the skill refuses to write, but a",
+      "read-only user makes a mistake impossible rather than merely forbidden.",
+    ],
+    steps: [["meffecta-agent set-secret ACME_MONGODB_URI_READONLY", "one per database, named for the project"]],
+    more: [
+      "Connection strings are per-database, so there is no single shared variable: name each",
+      "one for its project and give it a file in the deployment's systems/ register, which is where",
+      "the skill looks for the name. The driver already ships in the engine image.",
+    ],
+  },
+
   cloudflare: {
     title: "Cloudflare",
     gives: "cloudflare — DNS, cache purge, Pages deployments, certificate checks",
@@ -157,7 +208,7 @@ const INTEGRATIONS = {
       ],
       ["meffecta-agent set-env AGENT_INBOX_ACCOUNT=SALES", "OAuth path only: which GMAIL_<NAME>_* account to read"],
       ["meffecta-agent set-env AGENT_INBOX_POLL_SECONDS=300", "how often; the sweep inherits this cadence"],
-      ["meffecta-agent setup-scheduler", "re-syncs the sweep to that interval"],
+      ["meffecta-agent sync-triggers", "re-syncs the sweep to that interval"],
     ],
     more: [
       "Then, in the job's frontmatter:",
@@ -171,7 +222,7 @@ const INTEGRATIONS = {
       "before the run starts, so it never reaches the model. Leave it out and the job",
       "refuses every message — an omission is not read as consent.",
       "",
-      "  marcus@acme.com   one address        @acme.com    that domain (or *@acme.com)",
+      "  you@acme.com      one address        @acme.com    that domain (or *@acme.com)",
       "  *@*.acme.com      any subdomain      *            anyone at all",
       "",
       "A subdomain rule does not cover the bare domain; list both if you want both.",