@foldrun/core 0.2.0

package/src/triggers.ts

@@ -0,0 +1,287 @@
+// The ways a flow starts that are not a person, a clock or a bare POST.
+//
+// Four triggers live here, and they share one shape: something happened,
+// the flow file said it cares, the happening becomes the first step's task.
+//
+//   trigger: flow      another flow of this workspace finished (`after:`, `on:`)
+//   trigger: storage   a file landed under a storage/ prefix (`path:`)
+//   trigger: email     a message arrived at the flow's inbox URL
+//   signature:         a webhook delivery must carry a provider's HMAC
+//
+// None of them evaluates anything. A flow that chains on another does not
+// read that run's fields; it receives what the run concluded, as text, and
+// an agent reads it — the same rule as every other handoff in the format.
+
+import crypto from "node:crypto";
+import { platform } from "./platform.ts";
+import { listFlows, readRun, type FlowInfo, type FlowStep, type RunRecord } from "./store.ts";
+import { getSecret } from "./secrets.ts";
+
+/** The last step's result — the same reading runner.ts makes, kept local so
+ *  this module never imports the runner (the queue imports both). */
+function runResult(run: RunRecord): string | null {
+  for (let i = run.steps.length - 1; i >= 0; i--) {
+    const r = run.steps[i].result;
+    if (r && r.trim()) return r;
+  }
+  return null;
+}
+
+/** Staple a payload to the first step, the way the run route staples a task. */
+export function withTask(steps: FlowStep[], tag: string, body: string): FlowStep[] {
+  const text = body.trim();
+  if (!text) return steps;
+  return steps.map((s, i) => (i === 0 ? { ...s, instruction: `${s.instruction}\n\n<${tag}>\n${text}\n</${tag}>` } : s));
+}
+
+// ------------------------------------------------------------ trigger: flow
+
+/** The flows a finished run should start, by this workspace's own files. */
+export function chainedFlows(tenant: string, workspace: string, finished: RunRecord): FlowInfo[] {
+  if (finished.status !== "completed" && finished.status !== "failed") return [];
+  if (finished.flow.startsWith("adhoc:") || finished.flow.startsWith("eval:")) return [];
+  return listFlows(tenant, workspace).filter(
+    (f) =>
+      f.trigger === "flow" &&
+      f.after === finished.flow &&
+      f.steps.length > 0 &&
+      // A flow chained on itself is a loop with no bound — refused here and
+      // by foldrun check, never started.
+      f.name !== finished.flow &&
+      (f.on === "any" || f.on === finished.status),
+  );
+}
+
+/**
+ * Start every flow chained on a run that just settled. The finished run's
+ * one-line summary and its final result are the task; the run id rides
+ * along so the chained flow can name what it is reacting to. Returns the
+ * run ids started. Never throws: a chained flow that cannot start is a
+ * logged failure of that flow, not of the run that finished.
+ */
+export async function fireChainedFlows(tenant: string, workspace: string, finished: RunRecord): Promise<string[]> {
+  const flows = chainedFlows(tenant, workspace, finished);
+  if (flows.length === 0) return [];
+  const started: string[] = [];
+  const result = (runResult(finished) ?? "").slice(0, 20_000);
+  const body =
+    `run: ${finished.id}\nflow: ${finished.flow}\nstatus: ${finished.status}\n` +
+    (finished.summary ? `summary: ${finished.summary}\n` : "") +
+    (result ? `\n${result}` : "");
+  for (const flow of flows) {
+    try {
+      const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "previous_run", body), flow.name, flow.model, [
+        `after:${finished.flow}`,
+      ]);
+      started.push(run.id);
+      console.log(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name} started after ${finished.flow} ${finished.status}`);
+    } catch (err) {
+      console.error(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name}:`, err instanceof Error ? err.message : err);
+    }
+  }
+  return started;
+}
+
+// --------------------------------------------------------- trigger: storage
+
+/** Does a stored path fall under a flow's `path:` prefix? A prefix names a
+ *  folder ("leads/") or a file ("leads/latest.csv"); an empty prefix is all
+ *  of storage/. */
+export function underPrefix(rel: string, prefix: string | null): boolean {
+  const p = (prefix ?? "").replace(/^\/+/, "");
+  if (!p) return true;
+  return rel === p || rel.startsWith(p.endsWith("/") ? p : `${p}/`) || (p.endsWith("/") && rel.startsWith(p));
+}
+
+/**
+ * Start the flows watching a storage prefix that just gained files. `by`
+ * says who wrote them: a run's own copy-back (`run:<id>`) must not restart
+ * the flow that produced it, or a flow writing to its own trigger folder is
+ * a loop — every other writer counts.
+ */
+export async function fireStorageTriggers(
+  tenant: string,
+  workspace: string,
+  paths: string[],
+  by: string,
+): Promise<string[]> {
+  if (paths.length === 0) return [];
+  let flows: FlowInfo[];
+  try {
+    flows = listFlows(tenant, workspace).filter((f) => f.trigger === "storage" && f.steps.length > 0);
+  } catch {
+    return [];
+  }
+  if (flows.length === 0) return [];
+  const writerFlow = by.startsWith("run:") ? readRun(tenant, workspace, by.slice(4))?.flow ?? null : null;
+  const started: string[] = [];
+  for (const flow of flows) {
+    if (writerFlow === flow.name) continue;
+    const hits = paths.filter((p) => underPrefix(p, flow.path));
+    if (hits.length === 0) continue;
+    try {
+      const body = `by: ${by}\n${hits.map((h) => `- storage/${h}`).join("\n")}`;
+      const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "storage_event", body), flow.name, flow.model, [
+        "storage",
+      ]);
+      started.push(run.id);
+    } catch (err) {
+      console.error(`[foldrun] trigger: storage — ${tenant}/${workspace}/${flow.name}:`, err instanceof Error ? err.message : err);
+    }
+  }
+  return started;
+}
+
+// ------------------------------------------------------ signed webhooks
+
+export interface SignatureVerdict {
+  ok: boolean;
+  reason: string;
+  /** Slack's url_verification handshake: answer with this and start nothing. */
+  challenge?: string;
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+}
+
+/**
+ * Check a webhook delivery against the flow's declared `signature:`. The
+ * secret's VALUE is read here, host-side, from the vault; the flow file only
+ * ever names it. Each provider signs differently, and the four supported
+ * are exactly the four whose scheme is documented and stable:
+ *
+ *   github  X-Hub-Signature-256: sha256=HMAC(body)
+ *   stripe  Stripe-Signature: t=<ts>,v1=HMAC(`${ts}.${body}`), ±5 min
+ *   slack   X-Slack-Signature: v0=HMAC(`v0:${ts}:${body}`), ±5 min,
+ *           plus the url_verification challenge Slack sends when the URL
+ *           is first saved — answered, not run
+ *   hmac    X-Signature: hex HMAC(body) — for anything you sign yourself
+ */
+export function verifyWebhookSignature(
+  tenant: string,
+  workspace: string,
+  flow: FlowInfo,
+  rawBody: string,
+  header: (name: string) => string | null,
+  now = Date.now(),
+): SignatureVerdict {
+  if (!flow.signature) return { ok: true, reason: "no signature required" };
+  if (!flow.signingSecret) return { ok: false, reason: `signature: ${flow.signature} needs signing_secret: \${NAME}` };
+  const secret = getSecret(tenant, flow.signingSecret, workspace);
+  if (!secret) return { ok: false, reason: `signing secret ${flow.signingSecret} is not set` };
+  const hmac = (data: string) => crypto.createHmac("sha256", secret.value).update(data).digest("hex");
+  const fresh = (ts: number) => Math.abs(now / 1000 - ts) <= 300;
+
+  switch (flow.signature) {
+    case "github": {
+      const sig = header("x-hub-signature-256") ?? "";
+      const ok = sig.startsWith("sha256=") && safeEqual(sig.slice(7), hmac(rawBody));
+      return { ok, reason: ok ? "github signature verified" : "X-Hub-Signature-256 did not match" };
+    }
+    case "stripe": {
+      const sig = header("stripe-signature") ?? "";
+      const parts = Object.fromEntries(sig.split(",").map((p) => p.trim().split("=") as [string, string]));
+      const ts = Number(parts.t);
+      if (!Number.isFinite(ts) || !parts.v1) return { ok: false, reason: "Stripe-Signature is missing t= or v1=" };
+      if (!fresh(ts)) return { ok: false, reason: "Stripe-Signature timestamp is outside the 5-minute window" };
+      const ok = safeEqual(parts.v1, hmac(`${ts}.${rawBody}`));
+      return { ok, reason: ok ? "stripe signature verified" : "Stripe-Signature v1 did not match" };
+    }
+    case "slack": {
+      // The handshake is unsigned in effect — Slack signs it, but a URL that
+      // cannot answer it is never saved, so answer before anything else.
+      try {
+        const parsed = JSON.parse(rawBody) as { type?: string; challenge?: string };
+        if (parsed?.type === "url_verification" && typeof parsed.challenge === "string") {
+          return { ok: true, reason: "slack url_verification", challenge: parsed.challenge };
+        }
+      } catch {
+        // not JSON — an ordinary signed delivery (form-encoded slash command)
+      }
+      const ts = Number(header("x-slack-request-timestamp"));
+      const sig = header("x-slack-signature") ?? "";
+      if (!Number.isFinite(ts)) return { ok: false, reason: "X-Slack-Request-Timestamp is missing" };
+      if (!fresh(ts)) return { ok: false, reason: "X-Slack-Request-Timestamp is outside the 5-minute window" };
+      const ok = sig.startsWith("v0=") && safeEqual(sig.slice(3), hmac(`v0:${ts}:${rawBody}`));
+      return { ok, reason: ok ? "slack signature verified" : "X-Slack-Signature did not match" };
+    }
+    case "hmac": {
+      const sig = (header("x-signature") ?? "").replace(/^sha256=/, "");
+      const ok = safeEqual(sig, hmac(rawBody));
+      return { ok, reason: ok ? "signature verified" : "X-Signature did not match" };
+    }
+  }
+  return { ok: false, reason: `unknown signature scheme ${String(flow.signature)}` };
+}
+
+// --------------------------------------------------------- trigger: email
+
+export interface InboundEmail {
+  from: string;
+  to: string;
+  subject: string;
+  text: string;
+}
+
+/**
+ * One shape out of the several inbound-email services post. JSON bodies
+ * (Resend, Postmark, Cloudflare Email Workers, anything hand-rolled) and
+ * form-encoded ones (Mailgun, SendGrid's inbound parse) both reduce to
+ * from / to / subject / text; HTML is stripped to text when that is all
+ * there is. Null when nothing in the body looks like a message.
+ */
+export function normaliseInboundEmail(contentType: string | null, raw: string): InboundEmail | null {
+  let fields: Record<string, unknown> = {};
+  const ct = (contentType ?? "").toLowerCase();
+  if (ct.includes("application/json") || raw.trim().startsWith("{")) {
+    try {
+      fields = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+    // Resend wraps the message in `data`; Postmark and others do not.
+    if (fields.data && typeof fields.data === "object") fields = { ...fields, ...(fields.data as object) };
+  } else if (ct.includes("application/x-www-form-urlencoded") || ct.includes("multipart/form-data")) {
+    if (ct.includes("multipart/form-data")) {
+      // SendGrid's inbound parse is multipart; the parts we need are plain
+      // text fields, so a minimal reader is enough and avoids a dependency.
+      const boundary = ct.match(/boundary=("?)([^";]+)\1/)?.[2];
+      if (!boundary) return null;
+      for (const part of raw.split(`--${boundary}`)) {
+        const m = part.match(/name="([^"]+)"\r?\n\r?\n([\s\S]*?)\r?\n$/);
+        if (m) fields[m[1]] = m[2];
+      }
+    } else {
+      for (const [k, v] of new URLSearchParams(raw)) fields[k] = v;
+    }
+  } else {
+    return null;
+  }
+  const pick = (...names: string[]): string => {
+    for (const n of names) {
+      const v = fields[n];
+      if (typeof v === "string" && v.trim()) return v.trim();
+      if (Array.isArray(v) && v.length && typeof v[0] === "string") return v.join(", ");
+      if (v && typeof v === "object" && typeof (v as { email?: unknown }).email === "string") {
+        return String((v as { email: string }).email);
+      }
+    }
+    return "";
+  };
+  const from = pick("from", "From", "sender", "FromFull", "envelope_from");
+  const subject = pick("subject", "Subject");
+  const html = pick("html", "HtmlBody", "body-html");
+  const text =
+    pick("text", "TextBody", "body-plain", "stripped-text", "plain") ||
+    html.replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+  if (!from && !subject && !text) return null;
+  return { from, to: pick("to", "To", "recipient", "ToFull"), subject, text };
+}
+
+/** The task an inbound email becomes. */
+export function emailTask(mail: InboundEmail): string {
+  return `from: ${mail.from}\nto: ${mail.to}\nsubject: ${mail.subject}\n\n${mail.text}`.slice(0, 20_000);
+}

package/src/webhook.ts

@@ -0,0 +1,183 @@
+// Per-flow webhook tokens, derived rather than stored: HMAC of the flow's
+// identity under the install's secret key. Stable across restarts, unique
+// per flow, and rotating FOLDRUN_SECRET_KEY invalidates every hook at once.
+
+import fs from "node:fs";
+import path from "node:path";
+import { dataRoot } from "./paths.ts";
+import { workspaceDir } from "./store.ts";
+import crypto from "node:crypto";
+
+const keyFile = () => path.join(dataRoot(), ".secret-key");
+
+/**
+ * The install's secret key. Every derived token — flow hooks, git secrets —
+ * hangs off this one value, so rotating it invalidates all of them together.
+ */
+export function installKey(): string {
+  if (process.env.FOLDRUN_SECRET_KEY) return process.env.FOLDRUN_SECRET_KEY;
+  if (fs.existsSync(keyFile())) return fs.readFileSync(keyFile(), "utf8");
+  // secrets.ts creates this on first use; fall back to a fixed dev value so
+  // hook URLs stay stable before any secret has been set.
+  return "foldrun-dev-install";
+}
+
+// Per-hook rotation without storing tokens: what is stored is a generation
+// counter, and the token is derived from identity + generation. Rotating a
+// hook that leaked is one increment; the old token dies instantly; nothing
+// secret ever sits in the file. Generation 0 keeps the original formula, so
+// every hook URL handed out before rotation existed still works.
+
+interface HookState {
+  gen: number;
+  rotatedAt: string;
+}
+
+function hooksFile(tenant: string, workspace: string) {
+  return path.join(workspaceDir(tenant, workspace), "hooks.json");
+}
+
+function readHooks(tenant: string, workspace: string): Record<string, HookState> {
+  const file = hooksFile(tenant, workspace);
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function hookGeneration(tenant: string, workspace: string, flow: string): number {
+  return readHooks(tenant, workspace)[flow]?.gen ?? 0;
+}
+
+/** Invalidate a hook's URL and mint the next one. Returns the new path. */
+export function rotateWebhook(tenant: string, workspace: string, flow: string): string {
+  const hooks = readHooks(tenant, workspace);
+  hooks[flow] = { gen: (hooks[flow]?.gen ?? 0) + 1, rotatedAt: new Date().toISOString() };
+  const file = hooksFile(tenant, workspace);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(hooks, null, 2));
+  return webhookPath(tenant, workspace, flow);
+}
+
+export function webhookToken(tenant: string, workspace: string, flow: string): string {
+  const gen = hookGeneration(tenant, workspace, flow);
+  const identity = gen === 0 ? `${tenant}/${workspace}/${flow}` : `${tenant}/${workspace}/${flow}#${gen}`;
+  return crypto.createHmac("sha256", installKey()).update(identity).digest("hex").slice(0, 32);
+}
+
+export function webhookPath(tenant: string, workspace: string, flow: string): string {
+  return `/api/hooks/${tenant}/${workspace}/${flow}?token=${webhookToken(tenant, workspace, flow)}`;
+}
+
+// ---------- one-click approval ----------
+
+/**
+ * The token in an emailed approve/reject link. Same shape as a hook token:
+ * derived from the run's identity under the install key, never stored, so
+ * a link keeps working across restarts and dies with a key rotation. A run
+ * id is unique, so there is no generation counter — a leaked link is dealt
+ * with by deciding the run, after which the link does nothing.
+ *
+ * The `approve:` prefix keeps this HMAC family apart from the hook family:
+ * without it a run id that happened to spell `tenant/ws/flow` would mint a
+ * working hook token.
+ */
+export function approveToken(tenant: string, workspace: string, runId: string): string {
+  return crypto
+    .createHmac("sha256", installKey())
+    .update(`approve:${tenant}/${workspace}/${runId}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * The token that releases a run parked on `wait: event`. Its own HMAC
+ * family, so an approval link cannot double as an event URL or the reverse.
+ */
+export function eventToken(tenant: string, workspace: string, runId: string): string {
+  return crypto
+    .createHmac("sha256", installKey())
+    .update(`event:${tenant}/${workspace}/${runId}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/** The URL a `wait: event` step is released at — absolute when the install
+ *  knows its origin, a path otherwise. */
+export function eventUrl(tenant: string, workspace: string, runId: string): string {
+  const p = `/api/events/${tenant}/${workspace}/${runId}?token=${eventToken(tenant, workspace, runId)}`;
+  const base = publicUrl();
+  return base ? `${base}${p}` : p;
+}
+
+/**
+ * Where this install can be reached from outside, or null. The platform has
+ * never needed to know its own address — every URL it hands out has been a
+ * path, completed by whoever pasted it. A link in an email has no such
+ * reader, so this is the one place an absolute origin is required.
+ */
+export function publicUrl(): string | null {
+  const raw = process.env.FOLDRUN_PUBLIC_URL?.trim();
+  if (!raw) return null;
+  return raw.replace(/\/+$/, "");
+}
+
+// ---------- delivery log ----------
+
+// Every POST at a hook URL, kept: accepted ones with their run id, refused
+// ones with why. A webhook that "never fires" is indistinguishable from one
+// that fires and is refused — unless someone wrote down the refusals.
+
+export interface HookDelivery {
+  t: string;
+  flow: string;
+  outcome: "accepted" | "invalid-token" | "invalid-signature" | "not-webhook" | "no-flow" | "error";
+  runId?: string;
+  bytes?: number;
+  detail?: string;
+}
+
+function deliveriesFile(tenant: string, workspace: string) {
+  return path.join(workspaceDir(tenant, workspace), "hook-deliveries.jsonl");
+}
+
+const KEEP_DELIVERIES = 500;
+
+export function recordDelivery(tenant: string, workspace: string, delivery: HookDelivery) {
+  const file = deliveriesFile(tenant, workspace);
+  if (!fs.existsSync(path.dirname(file))) return; // no workspace, nothing to log against
+  fs.appendFileSync(file, JSON.stringify(delivery) + "\n");
+  // Bounded: compact to the newest KEEP when it doubles. Amortised cheap,
+  // and a log that grows forever is a disk-full incident with a delay.
+  try {
+    const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    if (lines.length > KEEP_DELIVERIES * 2) {
+      const tmp = `${file}.tmp`;
+      fs.writeFileSync(tmp, lines.slice(-KEEP_DELIVERIES).join("\n") + "\n");
+      fs.renameSync(tmp, file);
+    }
+  } catch {
+    // compaction is best-effort; the append already landed
+  }
+}
+
+export function readDeliveries(tenant: string, workspace: string, limit = 20): HookDelivery[] {
+  const file = deliveriesFile(tenant, workspace);
+  if (!fs.existsSync(file)) return [];
+  return fs
+    .readFileSync(file, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .slice(-limit)
+    .reverse()
+    .map((line) => {
+      try {
+        return JSON.parse(line) as HookDelivery;
+      } catch {
+        return null;
+      }
+    })
+    .filter((d): d is HookDelivery => d !== null);
+}

package/templates/blog-desk/AGENTS.md

@@ -0,0 +1,13 @@
+---
+name: blog-desk
+description: A two-agent blog desk. Read flows/publish.md first.
+foldrun_version: "0.1"
+---
+
+# Blog desk
+
+Context every agent here shares.
+
+- We write for working farmers, not gardeners. They read on a phone, outdoors.
+- House style is in `knowledge/house-style.md` — read it before drafting.
+- Deliverables go in `outputs/`.

package/templates/blog-desk/agents/researcher/agent.md

@@ -0,0 +1,11 @@
+---
+name: researcher
+description: Finds one thing worth writing about, and says why.
+model: fast
+tools:
+  - web
+  - read
+---
+
+Pick exactly one topic, in a short paragraph, and say who it helps and why now.
+Do not write the article.

package/templates/blog-desk/agents/writer/agent.md

@@ -0,0 +1,8 @@
+---
+name: writer
+description: Turns a brief into a short draft.
+tools:
+  - files
+---
+
+Write a short draft from the brief you were given. Save it to outputs/draft.md.

package/templates/blog-desk/evals/writer-quality.md

@@ -0,0 +1,10 @@
+---
+name: writer-quality
+agent: writer
+model: fast
+---
+
+## writes something
+task: Write two sentences about rain.
+expect:
+  - judge: it is two sentences and mentions rain

package/templates/blog-desk/flows/publish.md

@@ -0,0 +1,10 @@
+---
+name: publish
+trigger: manual
+---
+
+Read the numbers, not the order of the lines.
+Same number = at the same time. Different number = one after the other.
+
+1. [[researcher]] — find one topic worth writing about
+2. [[writer]] — draft it

package/templates/blog-desk/knowledge/house-style.md

@@ -0,0 +1,9 @@
+---
+type: Reference
+name: house-style
+description: How we write. Agents read this; they never rewrite it.
+status: stable
+---
+
+- Short sentences. One idea each.
+- Say the number, not "significant growth".

package/templates/blog-desk/knowledge/index.md

@@ -0,0 +1,9 @@
+---
+okf_version: "0.2"
+---
+
+# Knowledge
+
+## Reference
+
+- [house-style](house-style.md) — How we write. Agents read this; they never rewrite it. _(unverified)_

package/templates/hello/AGENTS.md

@@ -0,0 +1,18 @@
+---
+name: hello
+description: A runnable demo — one agent, one flow, no network and no secrets.
+foldrun_version: "0.1"
+---
+
+# hello
+
+Everything here is deliberately small enough to run in one step. There are no
+API keys and no network calls: the point is to prove the loop — an agent reads
+what it was given, does the work, and writes back what it learned as a
+conformant OKF document.
+
+The one piece of code is `tools/wordcount/`, and it is the shape every script
+tool should take: a `tool.md` holding the contract and a `run.py` holding the
+program, in one folder. The definition names `run.py` and never the scope it
+lives in, so the folder is correct copied into any workspace or installed at
+the account. Code stays a real file — lint it, test it, run it by hand.

package/templates/hello/agents/curator/agent.md

@@ -0,0 +1,32 @@
+---
+name: curator
+description: Reviews what the workspace has remembered — stale, duplicated or contradicting facts — and tidies memory without inventing anything.
+model: default
+tools:
+  - files
+  - search
+  - history
+---
+
+You look after this workspace's memory: the files under `../../memory/` and
+under each agent's `memory/`. Agents write there one fact per file, and nobody
+prunes it, so over months it gains duplicates, facts that later runs
+contradicted, and notes that stopped being true.
+
+Do exactly this:
+
+1. Read the memory index and every memory file. Use `search_files` to find
+   files that say the same thing in different words, and `recall_runs` to see
+   what recent runs concluded — a fact a run has since contradicted is stale.
+2. For each problem, act, and prefer the smallest change:
+   - Two files saying one thing: keep the better-written one, fold anything
+     only the other had into it, delete the other.
+   - A fact a later run or a knowledge file contradicts: correct it, and say
+     in the file what changed and which run showed it.
+   - A note that was only ever true for one day (a count, a cursor, "today"):
+     move it to `../../state/` if it is still useful, else delete it.
+   - Anything you are not sure about: leave it, and list it in your report.
+3. Never write a fact you did not find in a file or a run. Never touch
+   `knowledge/` — that is what people gave the agents, and it is theirs.
+4. Reply with a one-line headline (how many files reviewed, merged, corrected,
+   removed), then the list of what you changed and what you left for a person.

package/templates/hello/agents/notetaker/agent.md

@@ -0,0 +1,24 @@
+---
+name: notetaker
+description: Reads the house style, writes one short note, checks its length, and records what it learned.
+model: fast
+tools:
+  - files
+  - wordcount
+---
+
+You are writing a single short note for the Northwind blog.
+
+Do exactly this, in order:
+
+1. Read the workspace's knowledge and follow the house style in it. Load the
+   `plain-english` skill before you draft.
+2. Draft two sentences about rain gauges, then call the `wordcount` tool on
+   your draft. If it reports more than 2 sentences, cut it down and check
+   again. Save the final text to `outputs/note.md`.
+3. Write one thing you learned to `../../memory/` as a new file — one fact,
+   plain markdown, a sentence or two. The platform records who wrote it.
+4. Update `../../state/publishing.md`: increase the note count by one and set
+   the last topic to what you wrote about. Keep it as markdown.
+
+Then stop. Do not create anything else.

package/templates/hello/evals/house-style.md

@@ -0,0 +1,16 @@
+---
+name: house-style
+agent: notetaker
+model: fast
+---
+
+## uses a real number
+task: Write two sentences about the RG-100 rain gauge.
+expect:
+  - contains: 0.2mm
+  - not-contains: significant
+
+## does not claim accuracy
+task: Write two sentences about the RG-100 rain gauge.
+expect:
+  - judge: states a resolution and does not claim an accuracy percentage

package/templates/hello/flows/memory-review.md

@@ -0,0 +1,7 @@
+---
+name: memory-review
+description: Tidy what the agents have remembered. Run it by hand, or on a schedule once memory has grown.
+trigger: manual
+---
+
+1. [[curator]] — review every memory file for duplicates, stale facts and contradictions; fix what is certain, report the rest

package/templates/hello/flows/note.md

@@ -0,0 +1,7 @@
+---
+name: note
+description: The whole demo — one agent, one step.
+trigger: manual
+---
+
+1. [[notetaker]] — read the house style, write the note, record what you learned