@meffecta/agent 1.0.7 → 1.0.9

package/README.md

@@ -1,142 +1,109 @@
-# @meffecta/agent
+# Meffecta Agent
 
-Set up and operate a **Meffecta Agent** deployment — a self-hosted Claude Code job runner
-that wakes on a schedule, a webhook, or new mail, and runs a job against a fresh clone of
-your own content repo.
+An AI colleague that runs in **your own Google Cloud**, on **your own jobs**, against your
+own systems. It wakes on a schedule, a webhook, or an email, does a piece of real work, and
+reports back — then goes back to sleep costing nothing.
 
-The agent itself is a container image (`ghcr.io/meffecta/agent`). This package is the tool
-that stands one up and runs it, and it is all you need: the engine's source is private,
-and nothing here depends on it.
+Work arrives finished, rather than waiting in a chat window for you to open it — though
+you can also just ask it something when you want to.
 
-```bash
-npx @meffecta/agent steps      # the whole set-up, in order
-npx @meffecta/agent help       # every command
-```
+### → [agent.meffecta.com](https://agent.meffecta.com)
 
-## What it does
+What it is, what you need, and the whole set-up in order. This package (`@meffecta/agent`)
+is the tool that stands one up and operates it.
 
-Run it from your **content repo** — the directory holding `deployment.env`, `jobs/`,
-`worlds/` and `SYSTEM.md`. That file says which GCP project and Cloud Run service this
-deployment is, so a command can never quietly act on the wrong one.
+## What people run it for
 
-```bash
-npx @meffecta/agent create-project        # a GCP project
-npx @meffecta/agent link-billing          # attach billing
-npx @meffecta/agent setup-infra           # registry, buckets, service account, service
-npx @meffecta/agent set-secret AGENT_API_SECRET --random
-npx @meffecta/agent set-env GIT_REPO_URL=https://github.com/you/your-content-repo.git
-npx @meffecta/agent deploy                # roll out the engine
-npx @meffecta/agent sync-triggers       # give it its triggers
-```
+A job is a page of plain-language instructions, so this is a sample rather than a menu —
+the agent does what your jobs say.
 
-Giving it access to something — Gmail, GA4, Grafana, PostHog, Cloudflare, an inbox
-trigger — is ongoing work rather than set-up, and each has a walkthrough:
+**Sales** — find prospects and check them against your CRM, research each company and its
+decision-maker, leave outreach drafts in the seller's own mailbox for them to send, and put
+a next step on every priority account.
 
-```bash
-npx @meffecta/agent connect              # what can be connected
-npx @meffecta/agent connect gmail        # what to do, in order, with the commands
-```
+**Marketing** — one weekly read across traffic, search, ads and campaigns. Website and
+search audits with fixes proposed. Ad reviews, where changes happen only on request. Watches
+form leads, contacts, and competitors' rankings.
 
-Then, day to day:
+**Customer care** — a support inbox that answers or hands over with the findings attached,
+learns from the conversations, and keeps help pages current as things change.
 
-```bash
-npx @meffecta/agent doctor                # is anything quietly broken?
-npx @meffecta/agent status                # revision, shape, triggers, queue
-npx @meffecta/agent jobs                  # what is registered, and what triggers it
-npx @meffecta/agent env                   # every setting (secret values never printed)
-npx @meffecta/agent secrets               # what is stored, and what the service reads
-npx @meffecta/agent triggers              # the Cloud Scheduler jobs and task queue
-npx @meffecta/agent logs --limit 100
-npx @meffecta/agent run morning-brief
-npx @meffecta/agent ask "how did search do last week"
-```
+**Compliance** — review an ISO 27001 document set against the standard, find what is overdue
+or contradicts itself, and draft revisions for a person to approve — sized to your business
+rather than to a template's idea of one. It never records that a control is in place: that
+claim is what an audit tests.
 
-`doctor` is the one to run when something feels wrong. It judges rather than describes,
-and it is aimed at the failures that produce no error anywhere: a scaled-to-zero service
-with no triggers runs nothing while looking perfectly healthy, an always-on one with
-triggers runs every cron twice, a sweep whose cadence no longer matches the inbox poll
-interval checks mail on yesterday's schedule for ever, and a registry that expired the
-image your revision pins will fail at the next cold start rather than the next deploy.
-Every finding carries the command that fixes it, and it exits non-zero on a real problem
-so CI can run it.
+**Engineering** — overnight error triage with fixes proposed as pull requests, a verdict on
+every proposed change, alerts traced to a likely cause, and weekly upkeep.
 
-## Two things worth knowing
+**Leadership** — a morning brief tailored to each person's role, daily status on what is
+live and in use, and weekly reviews that stay honest about flat weeks.
 
-**The version you install is the engine you deploy.** Each release records the engine build
-published alongside it, and `deploy` defaults to that image. Tooling and engine move
-together, so a script can never provision the wrong shape for the engine it is aimed at.
-`meffecta-agent version` tells you which pair you have.
+**Assistant** — email it anything: a lookup, a draft, a booking, a question. One calendar
+across Google and Microsoft 365. Inbox digests and the week ahead.
 
-**Secret values are never printed.** `secrets` lists what exists and whether the service
-reads it; `env` names secret-backed settings without resolving them. Setting one takes the
-value from a pipe, a file, or a hidden prompt — never from your shell history.
+## What it can reach
 
-## Writing a job
+Shipped with the engine, pointed at your accounts by your jobs:
 
-```bash
-meffecta-agent create-job "a marketing report every Wednesday at 2pm"
-```
+| | Reached out of the box |
+|---|---|
+| **Mail & calendar** | Gmail, Microsoft 365, Google Calendar |
+| **Documents** | Drive, Sheets, Docs, Slides |
+| **Your numbers** | GA4, Search Console, Google Ads, PostHog, Ahrefs |
+| **Your data** | BigQuery, Elasticsearch, MongoDB — and logs from Grafana or Coralogix |
+| **The market** | Google's live search results — real rankings, not a web search |
+| **CRM** | HubSpot, reading and writing as separate abilities |
+| **Work & content** | Linear issues and cycles; Webflow pages and CMS, staged before anything goes public |
+| **Slack** | Posts, threads and reactions — and answers when someone @-mentions it |
+| **Infrastructure** | Cloudflare, and a real headless browser for anything without an API |
+| **Your code** | any Git repo as the working directory, with pull requests as the output |
 
-The model runs **on your deployment**, not on your laptop — it already holds the Claude
-token, and more importantly its run has your content repo cloned and the engine's skills
-mounted, so it can read your existing jobs for house style, your worlds, and
-`systems/` for which systems this deployment can actually reach. It writes a file to
-`jobs/<name>.md` and stops: nothing is committed, pushed or deployed, because that prompt
-is something your agent will run and you should read it first.
+Anything else is a skill you add to your own repo — the engine never needs to know about it.
 
-What comes back is checked before it is written — a valid five-field cron in your
-deployment's timezone, a usable job name, no `inbox:` without `allowFrom:` (the engine
-refuses those, deliberately), an `effort:` the engine accepts, and no silent overwrite of
-an existing job. `--dry-run` prints without writing; `--name` overrides the chosen name.
+## How it works
 
-After you edit it by hand:
+Your **content repo** holds the jobs, the facts about your business, and the register of
+which systems this deployment may touch. Every run clones it fresh. Push a changed prompt
+and the next run uses it; there is nothing to build and nothing to deploy.
 
-```bash
-meffecta-agent check-jobs     # the same checks, on every job file here
-```
-
-## Anonymous analytics
-
-On by default, and one command to stop:
-
-```bash
-meffecta-agent analytics        # exactly what is sent, and the current state
-meffecta-agent analytics off    # or set DO_NOT_TRACK=1
-```
-
-**Sent:** which command ran — matched against the built-in list, never a word you typed —
-whether it worked, how long it took, the class of any error, this CLI's version and the
-engine tag it deploys, Node version, OS and architecture, how you installed it, and whether
-a `deployment.env` was found. Plus a random id generated on your machine, so repeat runs
-count as one install.
+Jobs are triggered by a **schedule**, a **webhook**, or **an email to an address you name**
+— and a job that runs out of time can hand the rest to a follow-up run of itself. Each job
+keeps its own memory across runs, and every prompt, result and transcript lands in a
+write-once audit bucket.
 
-**Never sent:** your GCP project or service name, region, repo URLs, account or email
-address, file paths, command arguments, secret names or values, job names, prompts — or any
-error *message*. Only the error's class, because messages routinely quote a project id, a
-path, or a line of `gcloud` output.
+## Built to be trusted with the keys
 
-Off automatically in CI. Nothing is written to your machine at all if you have opted out.
-It is one bounded request after the command's own work is finished, and a failure to send
-is silent — analytics can never delay or fail a deploy.
+It runs in **your** GCP project, on **your** credentials, billed to **your** Claude
+subscription. Nothing routes through Meffecta.
 
-## Requirements
+A job reaches only the systems your register lists, and reading and changing are separate
+abilities — a reporting job loads the reader and never the writer.
 
-`gcloud` (authenticated), `docker` (to mirror engine images into your registry), `git`, and
-Node 20+ — Node 24+ if you also run the `claude` CLI to mint the token. macOS or Linux.
+One shipped skill exists to change a paid account, Google Ads, and it is the most
+constrained thing here: every change is validated against the live account first and only
+applied on a second, explicit run; budgets can only go *down*; a campaign can be paused but
+never deleted; and the limits live in the script, not in the instructions, so no wording can
+talk its way past them.
 
-## Developing it
+A job reachable by email must say who may reach it, or it refuses everyone — an omission is
+not consent. Secret values are never printed, by any command.
 
-From a checkout of the engine repo:
+## Operating it
 
 ```bash
-cd cli && npm link      # `meffecta-agent` now runs the working tree
+npx @meffecta/agent steps      # the set-up, in order
+npx @meffecta/agent help       # every command — each also takes --help
+npx @meffecta/agent doctor     # the one to run when something feels wrong
 ```
 
-The scripts and docs are vendored into this package only at pack time, so a linked
-checkout falls back to the engine repo's own copies — edit either half and the next command
-picks it up. `npm rm -g @meffecta/agent` undoes it.
+Run commands from your content repo — the directory holding `deployment.env`, which says
+which project and service this deployment is, so a command can never act on the wrong one.
+
+**The version you install is the engine you deploy.** Each release records the engine build
+published alongside it, and `deploy` defaults to that image, so tooling and engine cannot
+drift apart. `meffecta-agent version` tells you which pair you have.
 
-## Documentation
+## Licence
 
-`npx @meffecta/agent help` lists every command; `npx @meffecta/agent steps` is the whole
-set-up in order, with the command for each step. Every command takes `--help`.
+UNLICENSED — for use by Meffecta deployments.

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.0.7",
-  "builtFrom": "26157a11d57ec9821672a644bf2ea5b3da3e23f5"
+  "engineTag": "1.0.9",
+  "builtFrom": "4769315eb49ce1036f888ffafb03881ec4e91131"
 }

package/lib/create-job.js

@@ -180,7 +180,7 @@ function buildPrompt(description, { timezone, existing }) {
     "",
     "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",
+    "  - systems/ — what this deployment can reach, one file per system, 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",
     "",

package/lib/verify-credentials.js

@@ -40,8 +40,8 @@ PART 2 — this deployment's own systems.
 
 Part 1 tests what the ENGINE knows how to test. It cannot test a system belonging to this
 deployment specifically. The register of those is \`systems/\` in your working directory —
-one file per system — or, in a deployment that has not moved to that yet, a single
-ENVIRONMENT.md table. Read whichever is present.
+one file per system. If it is not there, say so and stop: a deployment with no register has
+no systems of its own that anything can check.
 
 Each file's frontmatter says what to do:
   system:     what it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meffecta/agent",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Set up and operate a Meffecta Agent deployment — a self-hosted Claude Code job runner.",
   "type": "module",
   "bin": {
@@ -32,6 +32,7 @@
     "url": "git+https://github.com/meffecta/agent.git",
     "directory": "cli"
   },
+  "homepage": "https://agent.meffecta.com",
   "scripts": {
     "prepack": "node prepack.mjs",
     "postpack": "node prepack.mjs --clean"

package/scripts/verify-credentials.mjs

@@ -8,7 +8,8 @@
 // Never prints a credential value. Exits 1 if anything configured actually fails.
 
 import { execFile } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const env = process.env;
@@ -674,8 +675,8 @@ results.sort((a, b) => a.name.localeCompare(b.name));
 // because this script ships to EVERY deployment and knows every integration the engine
 // supports — which is always more than any one deployment uses. Listing them individually
 // asks the operator "why is Kleer in my report?", and the honest answer is that it is not
-// theirs and never was. The deployment's own register of what it can reach is
-// ENVIRONMENT.md in its content repo; the catalogue of what it could add is `connect`.
+// theirs and never was. The deployment's own register of what it can reach is `systems/`
+// in its content repo; the catalogue of what it could add is `connect`.
 // Credentials this script has never heard of.
 //
 // A deployment adds its own systems, and their keys are just secrets bound to the service:
@@ -685,8 +686,8 @@ results.sort((a, b) => a.name.localeCompare(b.name));
 // "everything works" while a set-but-never-exercised key sits beside it.
 //
 // So: name them, say plainly that nothing here can test them, and let the run that called
-// this reconcile them against ENVIRONMENT.md — the deployment's own register does know
-// what they are and which skill reaches them.
+// this reconcile them against `systems/` — the deployment's own register does know what
+// they are and which skill reaches them.
 //
 // Known-ness is decided from this file's own source, so the list maintains itself: if the
 // script mentions the variable, or the family it belongs to, it knows about it.
@@ -736,9 +737,39 @@ console.log(`\n${configured.length - failures.length} working, ${failures.length
 if (unknownCredentials.length) {
   // Names only. This script never prints a value, and that holds hardest for the ones it
   // does not understand.
+  //
+  // Which of them are a PROBLEM, though, is a question this script can answer without
+  // knowing anything about the systems themselves: the register travels into every run, so
+  // it is right here in the working directory. A credential named in it is deliberate, and
+  // proving it works is Part 2's job; one named nowhere is a key no skill will ever reach
+  // for, however valid it is. Printing the whole list as a to-do told the operator to
+  // register things that were already registered, which is how a real gap gets skimmed
+  // past.
+  const registered = new Set();
+  const registerDir = join(process.cwd(), "systems");
+  if (existsSync(registerDir)) {
+    for (const entry of readdirSync(registerDir)) {
+      if (!entry.endsWith(".md")) continue;
+      const text = readFileSync(join(registerDir, entry), "utf8");
+      for (const name of unknownCredentials) {
+        if (text.includes(name)) registered.add(name);
+      }
+    }
+  }
+  const unregistered = unknownCredentials.filter((name) => !registered.has(name));
   console.log(`\nSet, but nothing here knows how to test them (${unknownCredentials.length}):`);
   console.log(`  ${unknownCredentials.join(", ")}`);
-  console.log("  Each should have a row in ENVIRONMENT.md saying which skill reaches it.");
+  if (!existsSync(registerDir)) {
+    // No register to read — say the general thing rather than accuse every one of them.
+    console.log("  Each needs a file in systems/ saying which skill reaches it.");
+  } else {
+    if (registered.size) {
+      console.log(`  In systems/, so a job can reach them: ${[...registered].sort().join(", ")}`);
+    }
+    if (unregistered.length) {
+      console.log(`  Not in systems/, so no skill will find them: ${unregistered.join(", ")}`);
+    }
+  }
 }
 if (unconfigured.length) {
   console.log(`\nNot set up here (${unconfigured.length}): ${unconfigured.map((r) => r.name).join(", ")}.`);