makersclaw 0.1.0

package/templates/next/files/lib/data.js

@@ -0,0 +1,171 @@
+import { headers } from "next/headers";
+import { artifactId, ident, query } from "./db";
+import { markSample } from "./sample";
+
+// SERVER reads. Import from server components and server actions only —
+// this file pulls in next/headers, so a "use client" file cannot import it
+// (the build says so). Every read returns { ..., error } and never throws:
+// a missing table or an unreachable database becomes error text the
+// surface can show, and console.error puts it in the log tail the
+// platform agent reads.
+
+const ORDER = /^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*(asc|desc)?\s*$/i;
+
+/** "updated_at desc, id" → validated ORDER BY text. */
+export function orderClause(orderBy, fallback) {
+  const parts = String(orderBy ?? fallback)
+    .split(",")
+    .map((p) => {
+      const m = ORDER.exec(p);
+      if (!m) throw new Error(`invalid orderBy: ${orderBy}`);
+      return `${ident(m[1])} ${m[2] ? m[2].toUpperCase() : "ASC"}`;
+    });
+  return parts.join(", ");
+}
+
+/** Dates and other non-JSON values become plain so rows can cross into
+ *  client components. pg already returns bigint/numeric as strings. */
+export function plain(row) {
+  const out = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (v instanceof Date) out[k] = Number.isNaN(v.getTime()) ? null : v.toISOString();
+    else if (Buffer.isBuffer(v)) out[k] = v.toString("base64");
+    else out[k] = v;
+  }
+  return out;
+}
+
+// { column: value } → "WHERE ..." text; params is filled in place.
+// null → IS NULL, an array → = ANY, anything else → equality.
+function whereClause(filter, params) {
+  const where = [];
+  for (const [col, val] of Object.entries(filter ?? {})) {
+    if (val === null) {
+      where.push(`${ident(col)} IS NULL`);
+    } else if (Array.isArray(val)) {
+      params.push(val);
+      where.push(`${ident(col)} = ANY($${params.length})`);
+    } else {
+      params.push(val);
+      where.push(`${ident(col)} = $${params.length}`);
+    }
+  }
+  return where.length ? ` WHERE ${where.join(" AND ")}` : "";
+}
+
+function failed(what, error) {
+  const message = error?.message ?? String(error);
+  console.error(`[data] could not read ${what}: ${message}`);
+  return message;
+}
+
+/**
+ * Rows of a source table. `filter` is { column: value }; `orderBy` is
+ * "updated_at desc" (default: idColumn desc); `limit` caps at 5000.
+ *   → { rows, error }
+ */
+export async function loadRows({ source, idColumn = "id", orderBy, limit = 500, filter }) {
+  try {
+    const params = [];
+    const sql =
+      `SELECT * FROM ${ident(source)}` +
+      whereClause(filter, params) +
+      ` ORDER BY ${orderClause(orderBy, `${idColumn} desc`)}` +
+      ` LIMIT ${Math.max(1, Math.min(5000, Number(limit) || 500))}`;
+    const { rows } = await query(sql, params);
+    return { rows: rows.map(plain), error: null };
+  } catch (error) {
+    return { rows: [], error: failed(source, error) };
+  }
+}
+
+/** One row by id. `row` is null when there is none. → { row, error } */
+export async function loadRow({ source, idColumn = "id", id }) {
+  try {
+    const { rows } = await query(`SELECT * FROM ${ident(source)} WHERE ${ident(idColumn)} = $1 LIMIT 1`, [id]);
+    return { row: rows[0] ? plain(rows[0]) : null, error: null };
+  } catch (error) {
+    return { row: null, error: failed(source, error) };
+  }
+}
+
+/** How many rows match `filter`. → { count, error } */
+export async function countRows({ source, filter }) {
+  try {
+    const params = [];
+    const { rows } = await query(`SELECT count(*)::int AS n FROM ${ident(source)}${whereClause(filter, params)}`, params);
+    return { count: rows[0]?.n ?? 0, error: null };
+  } catch (error) {
+    return { count: 0, error: failed(source, error) };
+  }
+}
+
+/** Rows per distinct value of `column` (a state column, an owner…).
+ *  NULL values count under the key "null". → { counts: { [value]: n }, error } */
+export async function countBy({ source, column, filter }) {
+  try {
+    const params = [];
+    const { rows } = await query(
+      `SELECT ${ident(column)} AS v, count(*)::int AS n FROM ${ident(source)}${whereClause(filter, params)} GROUP BY 1 ORDER BY 2 DESC`,
+      params,
+    );
+    const counts = {};
+    for (const r of rows) counts[r.v === null ? "null" : String(r.v)] = r.n;
+    return { counts, error: null };
+  } catch (error) {
+    return { counts: {}, error: failed(`${source}.${column}`, error) };
+  }
+}
+
+/**
+ * What happened, newest first: public.artifact_activity for this artifact
+ * (every lib/actions.js write and everything the agent recorded with the
+ * sql verb). `surface` narrows to one surface key; `since` (ISO or Date)
+ * to rows after that time. Rows: { id, at, action, surface, row_ref,
+ * detail, data, by }. → { rows, error }
+ */
+export async function loadActivity({ limit = 100, surface, since } = {}) {
+  const id = artifactId();
+  if (!id) {
+    return { rows: [], error: failed("public.artifact_activity", "no CLAW_ARTIFACT_ID; product_run sets it") };
+  }
+  try {
+    const params = [id];
+    let where = `WHERE artifact_id = $1`;
+    if (surface) {
+      params.push(String(surface));
+      where += ` AND surface = $${params.length}`;
+    }
+    if (since) {
+      params.push(since instanceof Date ? since.toISOString() : String(since));
+      where += ` AND at > $${params.length}::timestamptz`;
+    }
+    params.push(Math.max(1, Math.min(1000, Number(limit) || 100)));
+    const { rows } = await query(
+      `SELECT id, at, action, surface, row_ref, detail, data, by
+       FROM public.artifact_activity ${where} ORDER BY at DESC, id DESC LIMIT $${params.length}`,
+      params,
+    );
+    return { rows: rows.map(plain), error: null };
+  } catch (error) {
+    return { rows: [], error: failed("public.artifact_activity", error) };
+  }
+}
+
+/** Sample rows get stable ids and a `_sample: true` marker (lib/sample.js,
+ *  pure — the Fixture part uses it in the browser). Kept here so server
+ *  code keeps one import. */
+export { markSample };
+
+/** The surface key of the current request (middleware.js sets it from
+ *  /s/<key>), unless the caller names one — a string, or the page's
+ *  `surface` object. */
+export async function currentSurface(explicit) {
+  if (typeof explicit === "string" && explicit) return explicit;
+  if (explicit && typeof explicit === "object" && typeof explicit.key === "string") return explicit.key;
+  try {
+    return (await headers()).get("x-claw-surface") || null;
+  } catch {
+    return null;
+  }
+}

package/templates/next/files/lib/db.js

@@ -0,0 +1,72 @@
+import { Pool } from "pg";
+
+// One pool per process; DATABASE_URL comes from this directory's .env,
+// written by app_database and sourced by product_run at start.
+const pool =
+  globalThis._pgPool ??
+  new Pool({ connectionString: process.env.DATABASE_URL, max: 3 });
+globalThis._pgPool = pool;
+
+export const query = (text, params) => pool.query(text, params);
+
+/** The artifact this app belongs to. product_run sets it from the folder
+ *  the app runs in; every activity row keys on it, and so does the
+ *  Activity tab the OS draws on the app window. */
+export function artifactId() {
+  return process.env.CLAW_ARTIFACT_ID || null;
+}
+
+const IDENT = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/** Quote a table or column name for SQL: "investors" → "investors",
+ *  "public.investors" → "public"."investors". Anything else throws, so a
+ *  typo in a surface config can never reach the database as SQL. */
+export function ident(name) {
+  const parts = String(name ?? "").split(".");
+  if (!parts.length || parts.length > 2 || !parts.every((p) => IDENT.test(p))) {
+    throw new Error(`invalid identifier: ${name}`);
+  }
+  return parts.map((p) => `"${p}"`).join(".");
+}
+
+/**
+ * Record what happened, for the Activity tab the OS draws on the app
+ * window (and any surface that reads the table with loadActivity). Every
+ * lib/actions.js write calls this; the artifact's agent writes the same
+ * table with the sql verb.
+ * Never throws — an activity line must not fail the write it describes.
+ *
+ *   action   found, drafted, sent, replied, skipped, edited, moved, added…
+ *   surface  the surface key the row belongs to (the OS tab shows its
+ *            label; a link into the app is /s/<surface>?row=<row_ref>)
+ *   row_ref  the id in that surface's source table
+ *   detail   one sentence
+ *   data     anything worth keeping (jsonb)
+ *   by       'agent' | 'user:<email>' | 'run:<id>'
+ */
+export async function logActivity({ action, surface, row_ref, detail, data, by }) {
+  const id = artifactId();
+  if (!id) {
+    console.warn(`[activity] not recorded (no CLAW_ARTIFACT_ID): ${action} ${detail ?? ""}`);
+    return false;
+  }
+  try {
+    await query(
+      `INSERT INTO public.artifact_activity (artifact_id, action, surface, row_ref, detail, data, by)
+       VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7)`,
+      [
+        id,
+        String(action || "edited"),
+        surface ?? null,
+        row_ref == null ? null : String(row_ref),
+        detail ?? null,
+        JSON.stringify(data ?? {}),
+        by || "user:unknown",
+      ],
+    );
+    return true;
+  } catch (error) {
+    console.error(`[activity] not recorded: ${String(error)}`);
+    return false;
+  }
+}

package/templates/next/files/lib/hooks.js

@@ -0,0 +1,218 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { claw, publishStatus } from "./claw";
+import { cancelJob, startJob } from "./platform";
+
+// The React side of the _claw API, without any look: fetching, polling,
+// streaming and cleanup. A surface renders what comes back and owns every
+// pixel. "use client" only: the _claw API is browser-side.
+//
+// There is no chat, runs or activity hook here, and there will not be:
+// those are STANDING surfaces and the OS draws them as tabs on the app
+// window (docs/ARTIFACT-CONTRACTS.md §9). `useJob` is the other thing —
+// work a founder commissions from inside the app, which is not a surface
+// at all: it opens because they pressed something and it closes when the
+// work lands (SOP §2.3, ARTIFACT-CONTRACTS §9f).
+//
+// While the gateway has no _claw routes yet (`unavailable`), polls back
+// off to once a minute so a preview that is still being wired does not
+// hammer 404s.
+
+const BACKOFF_MS = 60000;
+
+/**
+ * GET one _claw route. Fetches on mount, again every `every` ms while the
+ * tab is visible, and on reload(). A failed poll keeps the last data and
+ * sets `error`. Cleared on unmount.
+ *   → { data, error, loading, unavailable, reload }
+ */
+export function useClaw(path, { every, enabled = true } = {}) {
+  const [state, setState] = useState({ data: null, error: null, loading: Boolean(enabled), unavailable: false });
+  const [tick, setTick] = useState(0);
+  const lastRef = useRef(0);
+  const unavailableRef = useRef(false);
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+
+  useEffect(() => {
+    if (!enabled) return undefined;
+    const controller = new AbortController();
+    let alive = true;
+    const load = async () => {
+      lastRef.current = Date.now();
+      const r = await claw(path, { signal: controller.signal });
+      if (!alive || r.aborted) return;
+      unavailableRef.current = Boolean(r.unavailable);
+      if (r.ok) setState({ data: r.data, error: null, loading: false, unavailable: false });
+      else setState((s) => ({ ...s, error: r.error, loading: false, unavailable: Boolean(r.unavailable) }));
+    };
+    load();
+    const id = every
+      ? setInterval(() => {
+          if (document.visibilityState !== "visible") return;
+          if (unavailableRef.current && Date.now() - lastRef.current < BACKOFF_MS) return;
+          load();
+        }, every)
+      : null;
+    return () => {
+      alive = false;
+      controller.abort();
+      if (id) clearInterval(id);
+    };
+  }, [path, every, enabled, tick]);
+
+  return { ...state, reload };
+}
+
+/**
+ * Who this app is (_claw/me). Also publishes the status onto <html>
+ * so reportError can tell a preview fault from a runtime one.
+ *   → { artifact, user, blueprint, loading, error, unavailable, reload }
+ */
+export function useArtifact() {
+  const { data, ...rest } = useClaw("me");
+  const artifact = data?.artifact ?? null;
+  useEffect(() => {
+    publishStatus(artifact?.status);
+  }, [artifact?.status]);
+  return { artifact, user: data?.user ?? null, blueprint: data?.blueprint ?? null, ...rest };
+}
+
+/** A settled tool call closes the LAST running step with that name, not
+ *  the first: two calls to the same tool in one turn settle in order. */
+function settleStep(steps, name, status) {
+  const next = [...steps];
+  for (let i = next.length - 1; i >= 0; i -= 1) {
+    if (next[i].name === name && next[i].status === "running") {
+      next[i] = { ...next[i], status };
+      return next;
+    }
+  }
+  return next;
+}
+
+const IDLE = {
+  running: false,
+  steps: [],
+  text: "",
+  error: null,
+  sessionId: null,
+  progress: 0,
+  finishedAt: null,
+};
+
+/**
+ * Commission work and follow it: the job half of SOP §2.3. One job at a
+ * time per hook — call it once per place the founder can start something.
+ *
+ *   const job = useJob();
+ *   <button onClick={() => job.start("Draft a launch checklist for …")}>
+ *
+ * State, for the panel the surface draws:
+ *   running     a job is in flight
+ *   steps       [{ name, label, status }] — `label` is the founder's
+ *               phrase ("Searching the web"), `status` running | done |
+ *               failed. Show labels; the raw name is there for debugging.
+ *   text        what the agent has written so far, growing. This is its
+ *               account of the work, NOT the deliverable — the deliverable
+ *               is rows on a surface.
+ *   progress    bumps every time a step settles. Feed it to a data hook's
+ *               reload so rows appear as they land:
+ *                 useEffect(() => { reload(); }, [job.progress]);
+ *   error       a message, or null
+ *   sessionId   the thread. Pass it back to start() to refine what this
+ *               job produced; keep it on the object's row and the founder
+ *               can pick the conversation up where the thing lives.
+ *   finishedAt  ISO time the last job settled, or null
+ *
+ * Actions: start(message, { sessionId }) · cancel() · reset().
+ *
+ * The panel this drives must not exist when nothing is running — that is
+ * §2.3's test, and a standing one is the monitoring console §2.7 warns
+ * about. On delivery, close it and let the rows speak.
+ */
+export function useJob() {
+  const [state, setState] = useState(IDLE);
+  const abortRef = useRef(null);
+  const sessionRef = useRef(null);
+  const aliveRef = useRef(true);
+
+  useEffect(() => {
+    aliveRef.current = true;
+    return () => {
+      aliveRef.current = false;
+      abortRef.current?.abort();
+    };
+  }, []);
+
+  const start = useCallback(async (message, { sessionId } = {}) => {
+    const text = String(message ?? "").trim();
+    if (!text) return { ok: false, error: "nothing to ask" };
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    const thread = sessionId ?? null;
+    sessionRef.current = thread;
+    setState({ ...IDLE, running: true, sessionId: thread });
+
+    const onEvent = ({ event, data }) => {
+      if (!aliveRef.current) return;
+      if (event === "session") {
+        sessionRef.current = data?.session_id ?? sessionRef.current;
+        setState((s) => ({ ...s, sessionId: sessionRef.current }));
+      } else if (event === "delta") {
+        setState((s) => ({ ...s, text: s.text + (data?.text ?? "") }));
+      } else if (event === "tool") {
+        const name = data?.name ?? "tool";
+        const label = data?.label ?? name;
+        setState((s) =>
+          data?.status === "running"
+            ? { ...s, steps: [...s.steps, { name, label, status: "running" }] }
+            : {
+                ...s,
+                steps: settleStep(s.steps, name, data?.status ?? "done"),
+                progress: s.progress + 1,
+              },
+        );
+      } else if (event === "done") {
+        setState((s) => ({
+          ...s,
+          running: false,
+          text: data?.text || s.text,
+          progress: s.progress + 1,
+          finishedAt: new Date().toISOString(),
+        }));
+      } else if (event === "error") {
+        setState((s) => ({ ...s, running: false, error: data?.message ?? "the agent stopped" }));
+      }
+    };
+
+    const result = await startJob(text, {
+      sessionId: thread ?? undefined,
+      onEvent,
+      signal: controller.signal,
+    });
+    if (!aliveRef.current) return result;
+    // A stream that ends without `done` (a dropped connection, a 4xx
+    // before the first frame) must still leave the panel closable.
+    if (!result.ok && !result.aborted)
+      setState((s) => ({ ...s, running: false, error: s.error ?? result.error }));
+    else setState((s) => (s.running ? { ...s, running: false, finishedAt: new Date().toISOString() } : s));
+    return result;
+  }, []);
+
+  const cancel = useCallback(async () => {
+    abortRef.current?.abort();
+    const id = sessionRef.current;
+    setState((s) => ({ ...s, running: false, finishedAt: new Date().toISOString() }));
+    if (id) await cancelJob(id);
+  }, []);
+
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    sessionRef.current = null;
+    setState(IDLE);
+  }, []);
+
+  return { ...state, start, cancel, reset };
+}

package/templates/next/files/lib/platform.js

@@ -0,0 +1,59 @@
+import { claw, clawStream, reportError } from "./claw";
+
+// Typed wrappers over the _claw API (lib/claw.js), one per route an app
+// has a reason to call. BROWSER only — the grant cookie is the identity —
+// so call these from "use client" files; lib/hooks.js wraps them.
+//
+// Every call resolves { ok, status, data } or { ok: false, status, error,
+// unavailable }; nothing throws. `unavailable: true` (404 or no network)
+// means the gateway has no such route yet — render a quiet "not connected
+// yet" state, not an error.
+//
+// Three things live here: who the app is (`me`), the error relay
+// (`reportError`), and COMMISSIONING — `startJob` / `cancelJob`, the work
+// a founder asks for from inside the app (SOP §2.3). Monitoring is still
+// not an app's business: the OS draws Agent, Runs and Activity as tabs on
+// the window and the title bar holds the run controls, so nothing here
+// lists chats, runs or activity. `claw(path, opts)` and `clawStream` in
+// lib/claw.js are the generic doors for the rest of §5.
+
+/** GET _claw/me → { artifact: { id, name, vehicle, status, home },
+ *  user: { id, email }, blueprint } */
+export function me() {
+  return claw("me");
+}
+
+/**
+ * Commission work: POST _claw/chat as a stream, and call `onEvent` for
+ * every frame — `session` (once, first, carrying the thread's id),
+ * `delta` ({ text } as the answer is written), `tool` ({ name, label,
+ * status }: `label` is the founder-facing phrase, `status` running | done
+ * | failed), `done` ({ text }), `error` ({ message }).
+ *
+ * Pass `sessionId` to continue a thread the app already holds — refining
+ * the thing this job produced. Leave it out and the job gets a thread of
+ * its own, so two jobs never land in one conversation.
+ *
+ * The deliverable is NOT the text: the agent writes rows, and the surface
+ * shows them. Treat `delta` as what it is doing, not as the output.
+ */
+export function startJob(message, { sessionId, onEvent, signal } = {}) {
+  return clawStream(
+    "chat",
+    sessionId ? { message, session_id: sessionId } : { message, job: true },
+    onEvent ?? (() => {}),
+    { signal },
+  );
+}
+
+/** POST _claw/cancel — stop a job's turn. The rows it already wrote stay;
+ *  so does its run in the Runs tab. */
+export function cancelJob(sessionId) {
+  return claw("cancel", { method: "POST", body: { session_id: sessionId } });
+}
+
+export { reportError };
+
+export const platform = { me, startJob, cancelJob, reportError };
+
+export default platform;

package/templates/next/files/lib/sample.js

@@ -0,0 +1,12 @@
+// Pure, importable from either side (lib/data.js re-exports it for server
+// code; components/parts/fixture.jsx uses it in the browser).
+
+/** Sample rows get stable ids and a `_sample: true` marker, so a surface
+ *  can label them until real rows exist and refuse to edit them. */
+export function markSample(sample, idColumn = "id") {
+  return (sample ?? []).map((r, i) => ({
+    ...r,
+    [idColumn]: r[idColumn] ?? `sample-${i + 1}`,
+    _sample: true,
+  }));
+}

package/templates/next/files/middleware.js

@@ -0,0 +1,42 @@
+import { NextResponse } from "next/server";
+
+// The only door is the Makersclaw dashboard proxy, which stamps this token
+// on every request. The sandbox port itself is public, so without this
+// check anyone with the URL could read the founder's data.
+//
+// It also tells the server which surface a request is for: /s/<key> becomes
+// the x-claw-surface request header, so lib/data.js and lib/actions.js can
+// stamp activity rows with the surface without every surface file having
+// to pass its own key down.
+//
+// The theme: the OS window opens the app with ?theme=light|dark to match
+// the desk, and the product proxy carries it as the x-claw-theme header
+// on every later request (the browser's cookies never reach the app).
+// ?theme= on any URL wins for that request and sets the claw_theme cookie
+// too, so the app keeps its theme when run without the proxy (local
+// `next dev`). app/layout.jsx reads header, then cookie, onto
+// <html data-theme>.
+const THEMES = new Set(["light", "dark"]);
+
+export function middleware(request) {
+  const expected = process.env.CLAW_PRODUCT_TOKEN;
+  if (expected && request.headers.get("x-claw-product-token") !== expected) {
+    return new NextResponse("Open this app from your Makersclaw dashboard.", {
+      status: 401,
+    });
+  }
+  const headers = new Headers(request.headers);
+  headers.delete("x-claw-surface");
+  const m = /^\/s\/([^/?#]+)/.exec(request.nextUrl.pathname);
+  if (m) headers.set("x-claw-surface", decodeURIComponent(m[1]));
+  const theme = request.nextUrl.searchParams.get("theme");
+  const themed = Boolean(theme && THEMES.has(theme));
+  if (themed) headers.set("x-claw-theme", theme);
+  const response = NextResponse.next({ request: { headers } });
+  if (themed) {
+    response.cookies.set("claw_theme", theme, { path: "/", maxAge: 60 * 60 * 24 * 365, sameSite: "lax" });
+  }
+  return response;
+}
+
+export const config = { matcher: "/:path*" };

package/templates/next/files/next.config.mjs

@@ -0,0 +1,41 @@
+// The dashboard reaches this app at /p/<label>/ through the workspace proxy,
+// so every link and asset must carry that prefix. product_run sets
+// CLAW_BASE_PATH at build AND start time; leave it unset to run at /.
+//
+// `env` inlines the same value into the client bundle: lib/claw.js needs it
+// to address the _claw API from the browser. The <html data-claw-base-path>
+// attribute app/layout.jsx renders is the runtime copy and is read first, so
+// a start under a different prefix than the build still resolves.
+//
+// allowedOrigins is NOT optional here, and it is not yours to edit. Next 15
+// refuses a Server Action whose `Origin` header disagrees with
+// `x-forwarded-host` — and in this stack they always disagree, because the
+// sandbox ingress rewrites `x-forwarded-host` to its own vercel.run name
+// while the browser is on the product host. Without this the app loads
+// perfectly and its FIRST SAVE fails, which reads like a broken button
+// rather than a proxy policy. product_run derives the value
+// (src/lib/products.ts productAllowedOrigins): the product's own FQDN in
+// production, the dashboard's dev origin under a path prefix. Hardcoding a
+// localhost origin here ships an app that works in dev and refuses every
+// write in production.
+const allowedOrigins = (process.env.CLAW_ALLOWED_ORIGINS || "")
+  .split(",")
+  .map((o) => o.trim())
+  .filter(Boolean);
+
+// `npm run check` builds into its own folder (CLAW_DIST_DIR=.next-check,
+// check/run.mjs) so it never touches `.next`: in the sandbox the running
+// dev server owns that folder as another user, and a second `next build`
+// there dies with EACCES on .next/trace before it starts.
+const nextConfig = {
+  basePath: process.env.CLAW_BASE_PATH || "",
+  distDir: process.env.CLAW_DIST_DIR || ".next",
+  env: {
+    CLAW_BASE_PATH: process.env.CLAW_BASE_PATH || "",
+  },
+  ...(allowedOrigins.length > 0
+    ? { experimental: { serverActions: { allowedOrigins } } }
+    : {}),
+};
+
+export default nextConfig;

package/templates/next/files/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "artifact",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "check": "node check/run.mjs",
+    "test": "node check/run.mjs"
+  },
+  "dependencies": {
+    "@tailwindcss/postcss": "^4",
+    "next": "^15.4.0",
+    "pg": "^8.16.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tailwindcss": "^4"
+  }
+}

package/templates/next/files/postcss.config.mjs

@@ -0,0 +1,3 @@
+// Tailwind v4 runs as a PostCSS plugin; app/globals.css imports it. No
+// tailwind.config.js: tokens live in globals.css under @theme.
+export default { plugins: { "@tailwindcss/postcss": {} } };

package/templates/next/files/schema.sql

@@ -0,0 +1,22 @@
+-- Reference only. artifact_scaffold creates this table in the workspace
+-- database when it copies the template; nothing in the app runs this file.
+-- (docs/ARTIFACT-CONTRACTS.md §4)
+--
+-- Every write the app makes (lib/actions.js → lib/db.js logActivity) and
+-- every action the artifact's agent takes (its brief tells it to insert
+-- here with the sql verb) lands in this table, keyed by the artifact id
+-- product_run passes as CLAW_ARTIFACT_ID. The Activity tab the OS draws on
+-- the app window reads it (§9b), and so can any surface via loadActivity.
+
+create table if not exists public.artifact_activity (
+  id bigserial primary key,
+  artifact_id uuid not null,
+  at timestamptz not null default now(),
+  action text not null,          -- found, drafted, sent, replied, skipped, edited…
+  surface text,                  -- surface key
+  row_ref text,                  -- id in the surface's source table
+  detail text,                   -- one sentence
+  data jsonb not null default '{}'::jsonb,
+  by text not null default 'agent'  -- 'agent' | 'user:<email>' | 'run:<id>'
+);
+create index if not exists artifact_activity_artifact_at on public.artifact_activity (artifact_id, at desc);