@hobocode/thought-layer 0.4.1 → 0.5.0

package/README.md

@@ -17,6 +17,10 @@ This is open source and BYOK by design. The point is to help people build real t
 - **thought-layer-prd.** Draft the complete PRD — with a first-cut domain glossary and testable requirements — from the validated idea and business model. The plan the grill then hardens.
 - **thought-layer-grill.** The last design step: grills the draft PRD against the domain one question at a time, sharpening the glossary and hardening the requirements inline until it is build-ready. Runs after the PRD, not instead of the framework.
 - **thought-layer-naming.** Name the thing, with rationale and domain-ready slugs.
+- **thought-layer-build.** Build the hardened PRD into a static-first, deploy-ready artifact, verified to run, and leave a manifest the deploy step reads. When a requirement genuinely needs a server, it also emits a real backend (serverless functions, a `schema.sql`, a names-only `.env.example`, and a `BACKEND.md` guide), with Neon Postgres as the documented default.
+- **thought-layer-deploy.** Take the build live to a URL you own, with no lock-in: a Netlify token deploys into your own account, or the Netlify CLI handles a logged-in or anonymous deploy.
+- **thought-layer-speedrun.** A fast, unranked path to a build-ready spec when you do not need the full panel and score.
+- **Optional deep-dives**, pulled in when you want to go further than the backbone: `thought-layer-strategy`, `thought-layer-brand`, `thought-layer-market-research`, and `thought-layer-business-model`.
 
 **A Pi package** that adds, on top of the skills:
 
@@ -30,11 +34,11 @@ This is open source and BYOK by design. The point is to help people build real t
 
 ```bash
 pi install npm:@hobocode/thought-layer
-# or, before it is published:
+# or track the latest from GitHub:
 pi install git:github.com/hobocode-ofc/thought-layer-kit
 ```
 
-Installing the package lights up the skills, the `/tl` commands, and the `tl_score` / `tl_domains` / `tl_project` tools. You can also invoke a skill directly with `/skill:thought-layer-panel`.
+Installing the package lights up the skills, the `/tl` commands, and the deterministic tools (`tl_score`, `tl_domains`, `tl_project`, `tl_state`, `tl_scaffold`, `deploy`). You can also invoke a skill directly with `/skill:thought-layer-panel`.
 
 ### Claude Code (or any agent that reads the Agent Skills format)
 
@@ -65,6 +69,8 @@ The hosted version of the rigor lives at [weareallproductmanagersnow.com](https:
 - **Done:** the rigor as portable skills; a Pi package with deterministic tools + slash commands; the portable progress file (`tl_state` / the `tl` CLI) shared with the web app; and the speedrun.
 - **Phase 3 (done):** a `build` step that turns the hardened PRD into a deploy-ready artifact, built by your own agent (`/tl-build`), with a deterministic `tl_scaffold` tool that writes an instantly-deployable branded static site as the floor.
 - **Phase 4 (done):** a `deploy` step (`/tl-deploy`, the `deploy` tool, or `tl deploy`) that takes the build live to a URL you own, closing the loop. With a Netlify token it deploys into your own account via the file-digest API (owned immediately, no claim step); with no token it delegates to your Netlify CLI - logged in it creates a site in your account, logged out it deploys anonymously with a one-hour claim link. BYOK, no central account, no lock-in. `--dry-run` shows the plan first.
+- **Backend-capable build (done):** when the three-question backend test shows a product genuinely needs a server, `/tl-build` emits a real backend alongside the static front end (serverless functions per backend requirement, a `schema.sql`, a names-only `.env.example`, an updated `netlify.toml`, and a `BACKEND.md` guide), with Neon Postgres as the documented default and overridable to any Postgres. Static stays the default, gated by the same backend test.
+- **Next:** automated backend deploy. `tl deploy` ships the static front end today and points at `BACKEND.md` for the one-time backend steps; teaching the deploy step to provision the database and ship the functions into your own account is the follow-up.
 
 ## Notes for contributors
 

package/SECURITY.md

@@ -0,0 +1,50 @@
+# Security
+
+The Thought Layer Kit is bring-your-own-key by design. It has no server, no
+telemetry, and no central account. The threat model and the guarantees below
+follow from that.
+
+## What the kit handles
+
+- **Secrets are read from the environment only.** The Netlify token
+  (`NETLIFY_AUTH_TOKEN` / `NETLIFY_TOKEN`) and the domain-check key
+  (`THOUGHT_LAYER_DOMAIN_KEY` / `RAPIDAPI_KEY`) are read from `process.env`. They
+  are never accepted as tool or CLI parameters, never logged or printed, and
+  never written to disk. The `deploy.json` record stores the resulting URLs and
+  ids, never the token. When a build emits a backend, the generated `.env.example`
+  is a names-only contract (every line is a bare `NAME=`): real values live only
+  in the host environment, never in a committed file.
+- **Deploys go to your own account.** With a token, the deploy uses Netlify's
+  file-digest API to publish into your account. With no token, it delegates to
+  your installed Netlify CLI (a site in your account when logged in, or an
+  anonymous, claimable site when logged out). Nothing is hosted on infrastructure
+  we control, and there is no claim handshake we mediate.
+- **No shell injection.** External commands (the Netlify CLI) are invoked with an
+  argument array and no shell, so values such as a site name or publish directory
+  cannot break out into a shell. Site names are sanitized to `[a-z0-9-]`.
+- **File writes are confined.** The scaffold and state-file writers resolve paths
+  against the working directory; the state file and build artifacts live under
+  `.thought-layer/` and the chosen publish directory.
+- **No network calls you did not ask for.** The only outbound requests are to the
+  Netlify API (deploy) and, if you set a domain key, the RapidAPI domains
+  endpoint. There is no analytics or phone-home.
+
+## What stays your responsibility
+
+- The kit runs inside your own agent (Pi, Claude Code, or another) on your own
+  model and keys. The quality and safety of code an agent builds from a spec is a
+  function of that agent and model, not the kit.
+- Keep your provider keys and Netlify token in your environment or your agent's
+  secret store, not in committed files. `.thought-layer/` and `.env` are
+  gitignored in this repo for that reason.
+
+## Reporting a vulnerability
+
+Email security reports to **jerm@hobocode.net**. Please include steps to
+reproduce and the affected version. We aim to acknowledge within a few days.
+Public disclosure is welcome once a fix is released.
+
+## Supported versions
+
+The latest published `@hobocode/thought-layer` release on npm is the supported
+version. Fixes ship forward; please update before reporting.

package/core/backend.ts

@@ -0,0 +1,272 @@
+// The typed contract + deterministic boilerplate for the backend-capable build.
+//
+// Static stays the default. When the build skill's three-question backend test
+// says a product genuinely needs a server (a browser-unsafe secret, shared or
+// persistent state, or trusted server-side enforcement), the agent emits a real
+// serverless backend alongside the static front end. This module is the
+// deterministic floor for that path, mirroring scaffold.ts: the agent supplies
+// judgment (which functions, which tables), and these pure helpers render the
+// fixed, dash-free boilerplate (the env contract and the deploy guide) and
+// coerce a hand-written backend block into a clean shape.
+//
+// Pure TypeScript, no node imports. The chosen runtime DB driver
+// (`@neondatabase/serverless`) is a dependency of the GENERATED product, never
+// of the kit. Nothing here holds or provisions credentials: secrets live only
+// in the host environment, and the emitted .env.example carries names, never
+// values.
+//
+// Copy rule (enforced by tests): no em-dashes, no en-dashes, and no spaced
+// hyphen dashes (" - ", " -- ") in any generated prose. Use commas, colons,
+// periods, and parentheses instead.
+
+export type BackendKind = "serverless" | "server" | null;
+
+// One environment variable the backend reads. Names only: a value never lives
+// in this spec, the manifest, or the emitted .env.example. Real values stay in
+// the host environment.
+export interface EnvVarSpec {
+  name: string;
+  required: boolean;
+  description: string;
+}
+
+// Where the backend keeps shared or persistent state. The kit's documented
+// default is Neon Postgres, reached through the `DATABASE_URL` connection
+// string. Overridable to any Postgres by pointing `DATABASE_URL` elsewhere.
+export interface DatabaseSpec {
+  provider: string; // "neon" by default
+  schemaFile: string; // "schema.sql"
+  envVar: string; // "DATABASE_URL"
+}
+
+// The structured backend payload carried on the build manifest. The build skill
+// writes it when hasBackend is true; the deploy-automation follow-up consumes
+// it. Today the deploy step only reads it for messaging.
+export interface BackendMeta {
+  backendKind: BackendKind;
+  functionsDir: string; // "netlify/functions"
+  runtime: string; // "nodejs20.x"
+  nodeVersion: string; // "20"
+  envVars: EnvVarSpec[];
+  database: DatabaseSpec | null;
+  guide: string; // "BACKEND.md"
+}
+
+// The single documented default database. Neon is also exactly what managed
+// Netlify DB provisions, so it is both the Netlify native choice and portable.
+export const NEON_DEFAULT_DB: DatabaseSpec = {
+  provider: "neon",
+  schemaFile: "schema.sql",
+  envVar: "DATABASE_URL",
+};
+
+// ---- helpers -----------------------------------------------------------------
+
+// Coerce a name to a safe environment-variable identifier. Real env var names
+// are UPPER_SNAKE; this hardens the names-only invariant so a stray space or
+// lowercase letter can never produce a line that fails the `^[A-Z0-9_]+=$`
+// security check.
+function envName(raw: string): string {
+  const cleaned = String(raw || "")
+    .trim()
+    .toUpperCase()
+    .replace(/[^A-Z0-9_]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return cleaned || "VAR";
+}
+
+// Dedupe by safe name and sort, so the same set of vars always renders byte for
+// byte the same regardless of input order.
+function dedupeSortEnv(envVars: EnvVarSpec[]): EnvVarSpec[] {
+  const seen = new Set<string>();
+  const out: EnvVarSpec[] = [];
+  for (const v of envVars || []) {
+    const name = envName(v?.name ?? "");
+    if (seen.has(name)) continue;
+    seen.add(name);
+    out.push({ name, required: v?.required !== false, description: String(v?.description ?? "") });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ---- the names-only env contract ---------------------------------------------
+
+// Render a deterministic .env.example. Every variable line is exactly `NAME=`
+// with nothing after the equals sign. The security invariant (no value is ever
+// written) is locked by a unit test that matches `^[A-Z0-9_]+=$` on every
+// non-comment, non-blank line.
+export function renderEnvExample(envVars: EnvVarSpec[]): string {
+  const vars = dedupeSortEnv(envVars);
+  const lines: string[] = [
+    "# Environment variables for this project.",
+    "# Names only. Real values live in your host environment (the Netlify UI, or netlify env:set), never in this file.",
+    "# Copy this file to .env for local work and fill the values there. .env is gitignored; this .env.example is committed so the contract travels with the repo.",
+  ];
+  if (vars.length === 0) {
+    lines.push("", "# No backend environment variables were declared for this build.");
+    return lines.join("\n") + "\n";
+  }
+  for (const v of vars) {
+    const note = v.description.trim() ? v.description.trim() : "Set this value in your host environment.";
+    lines.push("", `# ${note} (${v.required ? "required" : "optional"})`, `${v.name}=`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+// ---- the deploy guide --------------------------------------------------------
+
+export interface BackendEndpoint {
+  name: string; // function file name without extension, glossary-named
+  rid: string; // the backend requirement id it implements
+  summary: string; // one line of what it does
+}
+
+export interface BackendGuideInput {
+  brandName?: string;
+  backendKind?: BackendKind;
+  functionsDir?: string;
+  runtime?: string;
+  database?: DatabaseSpec | null;
+  envVars?: EnvVarSpec[];
+  endpoints?: BackendEndpoint[];
+}
+
+const cell = (s: string): string => String(s ?? "").replace(/\|/g, "\\|").replace(/\n+/g, " ").trim();
+
+// Render a deterministic BACKEND.md for the Neon-on-Netlify path. The agent
+// supplies the endpoint and env lists; the prose, section order, and the honest
+// "deploy automation is a follow-up" status are fixed and dash-free.
+export function renderBackendGuide(input: BackendGuideInput): string {
+  const brand = (input.brandName || "This project").trim() || "This project";
+  const functionsDir = (input.functionsDir || "netlify/functions").trim() || "netlify/functions";
+  const db = input.database ?? NEON_DEFAULT_DB;
+  const envVars = dedupeSortEnv(input.envVars || []);
+  const endpoints = [...(input.endpoints || [])].sort(
+    (a, b) => String(a.rid).localeCompare(String(b.rid)) || String(a.name).localeCompare(String(b.name)),
+  );
+
+  const envRows =
+    envVars.length > 0
+      ? envVars
+          .map((v) => `| \`${v.name}\` | ${v.required ? "yes" : "no"} | ${cell(v.description) || "Set in your host environment."} |`)
+          .join("\n")
+      : `| \`${db.envVar}\` | yes | ${db.provider === "neon" ? "Neon Postgres connection string" : "Database connection string"} |`;
+
+  const fnRows =
+    endpoints.length > 0
+      ? endpoints.map((e) => `| \`${cell(e.name)}\` | ${cell(e.rid)} | ${cell(e.summary) || "See the function source."} |`).join("\n")
+      : "| (none emitted) | n/a | This build declared a backend but wrote no functions; see DECISIONS.md. |";
+
+  return `# Backend deploy guide
+
+${brand} needs a server side, so the build emitted a backend alongside the static front end. This guide covers what is in the repo, the honest status of automated backend deploy, and the one-time manual steps to take it live yourself.
+
+## What is in the repo
+
+- \`${functionsDir}/\`: one serverless function per backend requirement (the table further down maps each to its R-ID). The front end calls a function at \`/.netlify/functions/<name>\`.
+- \`${db.schemaFile}\`: the database schema. Tables and columns use the project glossary terms. Apply it once against your database.
+- \`.env.example\`: the environment variable names this backend reads. Names only, no values. Copy it to \`.env\` for local work and set real values in your host environment.
+- \`netlify.toml\`: declares the functions directory (\`[functions] directory = "${functionsDir}"\`) so Netlify bundles and serves the functions next to the static publish directory.
+
+## Status: automated backend deploy is a follow-up
+
+\`tl deploy\` publishes the static front end today. It does not yet provision the database or ship the functions for you; that automation is the next piece of work. Until it lands, do the steps below once. The front end deploys and works now; the functions go live when you complete these steps.
+
+## 1. Provision the database
+
+The documented default is Neon Postgres. Netlify DB is managed Neon, so this is the Netlify native choice as well as a portable one.
+
+1. Create a Neon project at neon.tech, or run \`netlify db init\` to provision managed Neon from your own Netlify account.
+2. Copy the connection string. It looks like \`postgresql://USER:PASSWORD@HOST/DB?sslmode=require\`.
+3. Apply the schema once: \`psql "$${db.envVar}" -f ${db.schemaFile}\`.
+
+When you provision managed Neon through Netlify, Netlify sets \`NETLIFY_DATABASE_URL\` for you. The code reads \`${db.envVar}\` as the portable name, so set that (or map one to the other) in the next step.
+
+To use a different Postgres provider, point \`${db.envVar}\` at it instead. Any standard Postgres works with the Neon serverless driver, so this is not locked to one vendor.
+
+## 2. Set the environment variables
+
+Set these in your host environment (the Netlify UI under Site settings, Environment variables, or \`netlify env:set NAME value\`). Never commit real values; \`.env.example\` carries names only.
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+${envRows}
+
+## 3. The functions
+
+Each backend requirement maps to one function. The front end reaches it at \`/.netlify/functions/<name>\`.
+
+| Function | Requirement | Does |
+| --- | --- | --- |
+${fnRows}
+
+## 4. Deploy with the functions present
+
+1. Confirm \`netlify.toml\` declares the functions directory.
+2. Set the environment variables from step 2 on the target site.
+3. From the project root, with the functions in place, run \`netlify deploy --prod\`. (Once the backend deploy automation lands, \`tl deploy\` will do this for you.)
+
+\`netlify deploy\` ships both the static publish directory and the functions in one go. After it completes, call a function once to confirm it responds, then use the live site.
+`;
+}
+
+// ---- defensive normalizer ----------------------------------------------------
+
+function normalizeDatabase(raw: unknown): DatabaseSpec | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+  const str = (v: unknown, fb: string): string => (typeof v === "string" && v.trim() ? v.trim() : fb);
+  return {
+    provider: str(r["provider"], "neon"),
+    schemaFile: str(r["schemaFile"], "schema.sql"),
+    envVar: str(r["envVar"], "DATABASE_URL"),
+  };
+}
+
+function normalizeEnvVars(raw: unknown): EnvVarSpec[] {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set<string>();
+  const out: EnvVarSpec[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const r = item as Record<string, unknown>;
+    const name = typeof r["name"] === "string" ? r["name"].trim() : "";
+    if (!name) continue; // drop nameless vars
+    if (seen.has(name)) continue; // dedupe
+    seen.add(name);
+    out.push({
+      name,
+      required: typeof r["required"] === "boolean" ? r["required"] : true,
+      description: typeof r["description"] === "string" ? r["description"] : "",
+    });
+  }
+  return out;
+}
+
+// Coerce a hand-written backend block (the agent fills it into build.json) into
+// a clean BackendMeta, or null when there is nothing recognizable. Mirrors the
+// progress.ts normalizers: forgiving on input, strict on output.
+export function normalizeBackendMeta(raw: unknown): BackendMeta | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+
+  const kindRaw = r["backendKind"];
+  const kind: BackendKind = kindRaw === "server" ? "server" : kindRaw === "serverless" ? "serverless" : null;
+  const envVars = normalizeEnvVars(r["envVars"]);
+  const database = normalizeDatabase(r["database"]);
+  const hasFunctionsDir = typeof r["functionsDir"] === "string" && (r["functionsDir"] as string).trim().length > 0;
+
+  // Nothing the deploy step could act on: treat as no backend.
+  if (kind === null && envVars.length === 0 && database === null && !hasFunctionsDir) return null;
+
+  const str = (v: unknown, fb: string): string => (typeof v === "string" && v.trim() ? v.trim() : fb);
+  return {
+    backendKind: kind ?? "serverless",
+    functionsDir: str(r["functionsDir"], "netlify/functions"),
+    runtime: str(r["runtime"], "nodejs20.x"),
+    nodeVersion: str(r["nodeVersion"], "20"),
+    envVars,
+    database,
+    guide: str(r["guide"], "BACKEND.md"),
+  };
+}

package/core/deploy-io.ts

@@ -257,9 +257,22 @@ export async function runDeploy(opts: DeployRunOptions, ctx: { deployedAt: strin
     return { ok: false, message: `Publish dir ${publishDirAbs} is empty - nothing to deploy.`, details: {} };
   }
 
+  // build.json may predate the backend block, so read it defensively.
+  const backend = manifest.backend ?? null;
   const backendWarn = manifest.hasBackend
-    ? ` WARNING: build.json says hasBackend:true${manifest.backendNote ? ` (${manifest.backendNote})` : ""}; ` +
-      `this static deploy publishes only the front end - the server part needs serverless functions or a separate host.`
+    ? (() => {
+        const guide = backend?.guide || "BACKEND.md";
+        const dbEnv = backend?.database?.envVar || "DATABASE_URL";
+        const names = (backend?.envVars || []).map((v) => v.name).filter(Boolean);
+        const others = names.filter((n) => n !== dbEnv);
+        const envList = others.length ? `${dbEnv} plus ${others.join(", ")}` : dbEnv;
+        return (
+          `\n\nStatic deploy: the front end goes live now. This project also has a backend ` +
+          `(build.json hasBackend is true${manifest.backendNote ? `: ${manifest.backendNote}` : ""}). ` +
+          `The backend artifact (serverless functions, schema.sql, a names-only .env.example) is built but not auto-deployed yet; backend deploy automation is a follow-up. ` +
+          `To run it yourself, follow ${guide}: provision Neon Postgres, set ${envList} in your host environment, then run netlify deploy with the functions present.`
+        );
+      })()
     : "";
 
   const token = process.env.NETLIFY_AUTH_TOKEN || process.env.NETLIFY_TOKEN || "";
@@ -318,7 +331,8 @@ export async function runDeploy(opts: DeployRunOptions, ctx: { deployedAt: strin
         deployRecord({
           deployedAt: ctx.deployedAt, mode: owned ? "cli" : "anonymous", publishDir: manifest.publishDir, fileCount,
           url, adminUrl: null, claimUrl, siteId: null, deployId: null,
-          hasBackend: manifest.hasBackend, backendNote: manifest.backendNote, buildProducer: manifest.producer, stateFile,
+          hasBackend: manifest.hasBackend, backendNote: manifest.backendNote, backendKind: backend?.backendKind ?? null,
+          buildProducer: manifest.producer, stateFile,
         }),
       );
       // If anonymity was explicitly asked for but the CLI is logged in, it went
@@ -349,7 +363,8 @@ export async function runDeploy(opts: DeployRunOptions, ctx: { deployedAt: strin
       deployRecord({
         deployedAt: ctx.deployedAt, mode: "token", publishDir: manifest.publishDir, fileCount,
         url: r.url || null, adminUrl: r.adminUrl || null, claimUrl: null, siteId: r.siteId, deployId: r.deployId,
-        hasBackend: manifest.hasBackend, backendNote: manifest.backendNote, buildProducer: manifest.producer, stateFile,
+        hasBackend: manifest.hasBackend, backendNote: manifest.backendNote, backendKind: backend?.backendKind ?? null,
+        buildProducer: manifest.producer, stateFile,
       }),
     );
     return {

package/core/deploy.ts

@@ -10,6 +10,7 @@
 // import and it is pure (content in, hex out).
 
 import { createHash } from "node:crypto";
+import type { BackendKind } from "./backend.ts";
 
 export const sha1Hex = (data: Buffer | string): string =>
   createHash("sha1").update(data).digest("hex");
@@ -106,6 +107,10 @@ export interface DeployRecord {
   deployId: string | null;
   hasBackend: boolean;
   backendNote: string | null;
+  // Provenance of the backend payload from build.json (null for a static build).
+  // The static deploy does not ship a backend; this just records what the build
+  // declared, for the deploy-automation follow-up to read.
+  backendKind?: BackendKind | null;
   buildProducer: "agent" | "scaffold" | null;
   stateFile: string | null;
 }

package/core/index.ts

@@ -15,6 +15,7 @@ export * from "./stages.ts";
 export * from "./stage-map.ts";
 export * from "./state-file.ts";
 export * from "./state-ops.ts";
+export * from "./backend.ts";
 export * from "./scaffold.ts";
 export * from "./scaffold-io.ts";
 export * from "./deploy.ts";

package/core/scaffold.ts

@@ -11,6 +11,7 @@
 // so this emits plain HTML. Pure: no fs, no Date - the caller supplies builtAt.
 
 import type { ProgressState } from "./progress.ts";
+import type { BackendMeta } from "./backend.ts";
 
 export interface StarterSiteSpec {
   brandName: string;
@@ -45,6 +46,11 @@ export interface BuildManifest {
   stack: string;
   hasBackend: boolean;
   backendNote: string | null;
+  // The structured backend payload, present only when the build emitted a real
+  // backend (hasBackend true). Optional + nullable so existing static build.json
+  // files round-trip and the deploy reader tolerates its absence. The deploy
+  // automation follow-up consumes it; today only deploy messaging reads it.
+  backend?: BackendMeta | null;
   buildCommand: string | null;
   installCommand: string | null;
   nodeVersion: string;
@@ -264,6 +270,7 @@ export function scaffoldManifest(
     stack: "static",
     hasBackend: false,
     backendNote: null,
+    backend: null,
     buildCommand: null,
     installCommand: null,
     nodeVersion: "20",

package/dist/tl.js

@@ -624,6 +624,7 @@ function scaffoldManifest(publishDir, builtAt, provenance) {
     stack: "static",
     hasBackend: false,
     backendNote: null,
+    backend: null,
     buildCommand: null,
     installCommand: null,
     nodeVersion: "20",
@@ -867,7 +868,17 @@ async function runDeploy(opts, ctx) {
   if (fileCount === 0) {
     return { ok: false, message: `Publish dir ${publishDirAbs} is empty - nothing to deploy.`, details: {} };
   }
-  const backendWarn = manifest.hasBackend ? ` WARNING: build.json says hasBackend:true${manifest.backendNote ? ` (${manifest.backendNote})` : ""}; this static deploy publishes only the front end - the server part needs serverless functions or a separate host.` : "";
+  const backend = manifest.backend ?? null;
+  const backendWarn = manifest.hasBackend ? (() => {
+    const guide = backend?.guide || "BACKEND.md";
+    const dbEnv = backend?.database?.envVar || "DATABASE_URL";
+    const names = (backend?.envVars || []).map((v) => v.name).filter(Boolean);
+    const others = names.filter((n) => n !== dbEnv);
+    const envList = others.length ? `${dbEnv} plus ${others.join(", ")}` : dbEnv;
+    return `
+
+Static deploy: the front end goes live now. This project also has a backend (build.json hasBackend is true${manifest.backendNote ? `: ${manifest.backendNote}` : ""}). The backend artifact (serverless functions, schema.sql, a names-only .env.example) is built but not auto-deployed yet; backend deploy automation is a follow-up. To run it yourself, follow ${guide}: provision Neon Postgres, set ${envList} in your host environment, then run netlify deploy with the functions present.`;
+  })() : "";
   const token = process.env.NETLIFY_AUTH_TOKEN || process.env.NETLIFY_TOKEN || "";
   const writeRecord = (rec) => {
     const recPath = join3(dirname3(stateFile), "deploy.json");
@@ -921,6 +932,7 @@ async function runDeploy(opts, ctx) {
           deployId: null,
           hasBackend: manifest.hasBackend,
           backendNote: manifest.backendNote,
+          backendKind: backend?.backendKind ?? null,
           buildProducer: manifest.producer,
           stateFile
         })
@@ -957,6 +969,7 @@ Recorded ${recPath}.${backendWarn}` + (!url || !claimUrl ? `
         deployId: r.deployId,
         hasBackend: manifest.hasBackend,
         backendNote: manifest.backendNote,
+        backendKind: backend?.backendKind ?? null,
         buildProducer: manifest.producer,
         stateFile
       })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobocode/thought-layer",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "The Thought Layer: rigor for building. Validate an idea, grill it into a buildable spec, then build and deploy it, inside the agent you already use. BYOK, no telemetry.",
   "license": "MIT",
   "author": "Hobocode LLC <jerm@hobocode.net>",
@@ -64,12 +64,14 @@
     "core/stage-map.ts",
     "core/state-file.ts",
     "core/state-ops.ts",
+    "core/backend.ts",
     "core/scaffold.ts",
     "core/scaffold-io.ts",
     "core/deploy.ts",
     "core/deploy-io.ts",
     "dist",
     "README.md",
+    "SECURITY.md",
     "LICENSE"
   ]
 }

package/prompts/tl-build.md

@@ -2,6 +2,6 @@ Apply the **thought-layer-build** skill. Build the hardened PRD into a static-fi
 
 If there is no hardened PRD in the state file (`state.prd.markdown` + requirements), say so and point me to `/tl` (or `/tl-prd` then `/tl-grill`) rather than building from a bare idea - only proceed cold if I tell you to.
 
-Honor the ubiquitous language (the glossary), R-ID traceability, the out-of-scope list, mobile+desktop, the brand if present, and the full SEO/discoverability layer. Default to static; escalate to a backend only when a requirement genuinely needs one, and flag loudly that the default deploy path is static. Verify the build runs, and leave `.thought-layer/build.json` + `DECISIONS.md` + `TRACEABILITY.md`.
+Honor the ubiquitous language (the glossary), R-ID traceability, the out-of-scope list, mobile+desktop, the brand if present, and the full SEO/discoverability layer. Default to static; when the three-question backend test shows a requirement genuinely needs a server, build the real backend too: serverless functions under `netlify/functions/` (one per backend R-ID, glossary-named), a `schema.sql`, a names-only `.env.example` (with `!.env.example` un-ignored in `.gitignore`), an updated `netlify.toml`, and a `BACKEND.md` guide, recorded in the manifest's `backend` block. Be honest that backend deploy automation is a follow-up, so `tl deploy` still ships the static front end for now. Verify the build runs, and leave `.thought-layer/build.json` + `DECISIONS.md` + `TRACEABILITY.md`.
 
 Read the spec from the state file (default `.thought-layer/state.json`; honor `--path` / `THOUGHT_LAYER_STATE` if a named file is in use). For the fastest deployable floor, or if a full build is too much, run the **tl_scaffold** tool to write a branded, SEO-complete static landing site and the same `build.json` manifest.

package/prompts/tl-deploy.md

@@ -2,6 +2,6 @@ Apply the **thought-layer-deploy** skill. Take the built site live to a URL I ow
 
 Read `.thought-layer/build.json` (next to the state file; honor `--path` / `THOUGHT_LAYER_STATE` if a named file is in use) for the publish directory and entry. If there is no `build.json`, say so and point me to `/tl-build` (or the `tl_scaffold` tool) rather than guessing - the build has to run first.
 
-Default to a dry run first so I can see exactly which files would ship and where. Then deploy: if `NETLIFY_AUTH_TOKEN` is set, deploy into my own Netlify account (owned immediately); otherwise delegate to my Netlify CLI - logged in it creates a site in my account, logged out it deploys anonymously with a one-hour claim link. Read the token only from the environment, never ask me to paste it. If `build.json` says `hasBackend: true`, warn me clearly that this static deploy publishes only the front end.
+Default to a dry run first so I can see exactly which files would ship and where. Then deploy: if `NETLIFY_AUTH_TOKEN` is set, deploy into my own Netlify account (owned immediately); otherwise delegate to my Netlify CLI - logged in it creates a site in my account, logged out it deploys anonymously with a one-hour claim link. Read the token only from the environment, never ask me to paste it. If `build.json` says `hasBackend: true`, tell me plainly that this static deploy ships only the front end for now (backend deploy automation is a follow-up), and point me at `BACKEND.md` for the one-time steps to run the backend (provision Neon, set `DATABASE_URL`, then `netlify deploy` with the functions present).
 
 After it is live, tell me the URL and (anonymous only) the claim link, and that a `.thought-layer/deploy.json` record was written.

package/skills/thought-layer-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: thought-layer-build
-description: "Turn the hardened PRD into a static-first, deploy-ready artifact, built directly by this agent. Reads the build brief from the shared state file (PRD, glossary, R-ID requirements, brand, business context, open to-dos), then builds a self-contained site or a Vite/static build that yields a predictable publish directory (dist/), honoring ubiquitous language, R-ID traceability, the out-of-scope list, mobile+desktop, brand, and the full SEO/discoverability layer. Escalates to a backend only when the spec genuinely requires server-side, and flags loudly that the default deploy path is static. Verifies the build runs and writes a .thought-layer/build.json manifest for the deploy step. Run it after the grill has hardened the PRD; it is a standalone build step, not a validation stage."
+description: "Turn the hardened PRD into a static-first, deploy-ready artifact, built directly by this agent. Reads the build brief from the shared state file (PRD, glossary, R-ID requirements, brand, business context, open to-dos), then builds a self-contained site or a Vite/static build that yields a predictable publish directory (dist/), honoring ubiquitous language, R-ID traceability, the out-of-scope list, mobile+desktop, brand, and the full SEO/discoverability layer. When the spec genuinely requires a server, it also emits a real backend (serverless functions under netlify/functions/, a schema.sql, a names-only .env.example, an updated netlify.toml, and a BACKEND.md guide) and records it in the manifest, while staying honest that backend deploy automation is a follow-up so the default deploy path stays static. Verifies the build runs and writes a .thought-layer/build.json manifest for the deploy step. Run it after the grill has hardened the PRD; it is a standalone build step, not a validation stage."
 ---
 
 # Build it: the hardened PRD becomes a deploy-ready artifact
@@ -49,7 +49,17 @@ Default to a self-contained static site or a Vite/Astro/static build whose outpu
 
 If all three are no, build **static, full stop.** localStorage, static data files, BYOK client-side AI calls, and third-party embeddable widgets do **not** count as a backend - many specs that sound like they need a server can ship a compelling static slice first.
 
-**When a backend is genuinely required:** build the static parts anyway, set `hasBackend: true` + `backendNote` in the manifest, and **warn loudly** in chat: the default deploy publishes a static `dist/` to Netlify, so the server part will not deploy that way and needs serverless functions or a separate host. Build the static shell with a clear seam for the backend.
+**When a backend is genuinely required, build it for real (do not just warn).** Build the static front end as above, set `hasBackend: true` and a one-line `backendNote`, and emit a coherent, buildable serverless backend alongside it:
+
+- **Serverless functions, one per backend R-ID**, under `netlify/functions/`. Name each file in the ubiquitous language (the glossary term for what it does, e.g. `netlify/functions/dispatch.ts`), open it with a comment naming the R-ID it implements, and keep it inside the out-of-scope boundary. Each function reads its inputs, talks to the database, and returns JSON. Give the front end a clear seam: it calls the function at `fetch('/.netlify/functions/<name>')`, never a hardcoded host.
+- **A `schema.sql`** at the project root, derived from the PRD data requirements and the domain entities. Name tables and columns in the glossary terms (no synonyms), and keep it idempotent where you can (`create table if not exists ...`).
+- **Neon Postgres by default.** The functions reach the database through the Neon serverless driver (`@neondatabase/serverless`, added to the product's `package.json`, never the kit's) and read the connection string from `DATABASE_URL` (Netlify sets `NETLIFY_DATABASE_URL` when you provision managed Neon, so read `DATABASE_URL` and map it). Neon is the single documented default and is overridable to any Postgres by pointing `DATABASE_URL` elsewhere; state that in `BACKEND.md` and do not invent a second provider.
+- **A names-only `.env.example`** at the project root listing every variable the backend reads (`DATABASE_URL` plus any others), each as a bare `NAME=` under a one-line comment. Never write a real value; real values live only in the host environment.
+- **An updated `netlify.toml`.** Extend the existing publish + redirect block (do not replace it) with a `[functions]` table declaring `directory = "netlify/functions"`. Keep the static publish dir and the SPA redirect intact.
+- **A `BACKEND.md` deploy guide** at the project root: what is in the repo, the honest status (automated backend deploy is a follow-up, so `tl deploy` ships only the front end today), how to provision Neon, the env-var table, the function-to-R-ID table, and the manual `netlify deploy` steps. The kit's `renderBackendGuide` and `renderEnvExample` helpers (in `core/backend.ts`) produce a dash-free skeleton if you have the core available; otherwise write the same content by hand.
+- **A project `.gitignore`** that ignores `.env` and `.env.*` but un-ignores the contract with `!.env.example`. Without that line the env contract is silently un-committable, and the deploy follow-up cannot read it.
+
+Then record the backend in the manifest's `backend` block (shape below). Do **not** attempt to deploy the backend in this step: `tl deploy` publishes the static front end, and backend deploy automation is the explicit follow-up. Say so plainly in chat and point the user at `BACKEND.md`.
 
 ## SEO and discoverability (build all of it, do not skip it)
 
@@ -67,7 +77,8 @@ Do not declare victory - check:
 2. **Confirm the publish dir + entry load.** `dist/index.html` (or your entry) exists and is non-trivial. Where a preview or browser tool is available, load it and confirm it renders; otherwise inspect the built HTML for the expected title/nav/hero and that the mobile viewport meta is set.
 3. **R-ID coverage.** Walk TRACEABILITY.md: each R-ID is implemented (with a pointer) or explicitly deferred (with a reason). Put the counts in `build.json.requirements`.
 4. **SEO check.** Confirm the SEO files are actually in the publish dir; set `build.json.seo.*` from reality, not intent.
-5. **Report** what is built and what is deferred, plainly, in chat.
+5. **Backend check (only when `hasBackend`).** Each backend R-ID maps to a function in TRACEABILITY.md; `netlify/functions/` has one file per backend R-ID; `.env.example` is values-free (every variable line is a bare `NAME=`, never a value); `schema.sql` is non-empty; `netlify.toml` declares the functions directory; `.gitignore` has `!.env.example`. Do **not** try to run the backend or reach a database here (there is no `DATABASE_URL` in the build env); confirm the artifact is coherent and buildable, not live.
+6. **Report** what is built and what is deferred, plainly, in chat.
 
 ## Honest about being model-built
 
@@ -82,6 +93,7 @@ Write three files with your own file tools (the manifest is NOT a `tl_state` art
 { "app": "thought-layer", "kind": "build", "version": 1, "builtAt": "<ISO>",
   "producer": "agent", "publishDir": "dist", "entry": "index.html",
   "stack": "static|vite|astro|next-static|other", "hasBackend": false, "backendNote": null,
+  "backend": null,
   "buildCommand": null, "installCommand": null, "nodeVersion": "20",
   "provenance": { "stateFile": "<the file you read>", "prdTs": <state.prd.ts>, "grillDone": <bool>, "fromSpeedrun": <bool> },
   "requirements": { "total": 0, "built": 0, "deferred": 0, "deferredIds": [] },
@@ -90,6 +102,17 @@ Write three files with your own file tools (the manifest is NOT a `tl_state` art
   "verified": { "buildRan": true, "publishDirExists": true, "entryLoads": true, "notes": "..." } }
 ```
   `publishDir` + `entry` are load-bearing - the deploy step reads them. (The `tl_scaffold` tool writes this same manifest with `producer: "scaffold"`.)
+
+  When `hasBackend` is `true`, populate `backend` (leave it `null` for a static build). This is the forward-looking contract the backend deploy automation will consume:
+
+```jsonc
+"backend": {
+  "backendKind": "serverless", "functionsDir": "netlify/functions",
+  "runtime": "nodejs20.x", "nodeVersion": "20",
+  "envVars": [{ "name": "DATABASE_URL", "required": true, "description": "Neon Postgres connection string" }],
+  "database": { "provider": "neon", "schemaFile": "schema.sql", "envVar": "DATABASE_URL" },
+  "guide": "BACKEND.md" }
+```
 - `DECISIONS.md` - every choice the spec did not pin down, one line each, with the reason.
 - `TRACEABILITY.md` - the R-ID map. (`SEO.md` comes from the SEO step.)
 

package/skills/thought-layer-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: thought-layer-deploy
-description: "Take the built site live to a user-owned URL with no lock-in, the last step after the build. Reads .thought-layer/build.json (the publish dir + entry) next to the state file, then deploys to Netlify by one of two BYOK models: with NETLIFY_AUTH_TOKEN set it deploys into the user's OWN account via the file-digest API (owned immediately, no claim), and with no token it delegates to the user's Netlify CLI (logged in: a new site in their account; logged out: an anonymous, claimable URL with a one-hour claim link). Static-first: if build.json says hasBackend it warns that only the front end ships this way. Prefers the deploy tool (Pi) or the tl deploy CLI (any shell agent) so the deploy is one mechanical, honest step, never hand-rolled. Run it after thought-layer-build (or tl_scaffold) has produced build.json."
+description: "Take the built site live to a user-owned URL with no lock-in, the last step after the build. Reads .thought-layer/build.json (the publish dir + entry) next to the state file, then deploys to Netlify by one of two BYOK models: with NETLIFY_AUTH_TOKEN set it deploys into the user's OWN account via the file-digest API (owned immediately, no claim), and with no token it delegates to the user's Netlify CLI (logged in: a new site in their account; logged out: an anonymous, claimable URL with a one-hour claim link). Static-first: if build.json says hasBackend, the build also emitted a backend (functions, schema.sql, a names-only .env.example, BACKEND.md), but backend deploy automation is a follow-up, so this step ships only the front end for now and points at BACKEND.md. Prefers the deploy tool (Pi) or the tl deploy CLI (any shell agent) so the deploy is one mechanical, honest step, never hand-rolled. Run it after thought-layer-build (or tl_scaffold) has produced build.json."
 ---
 
 # Deploy it: the build goes live to a URL you own
@@ -35,7 +35,7 @@ If neither a token nor a usable CLI is available, relay the tool's guidance hone
 
 ## Static-first honesty
 
-The default deploy publishes a **static** publish directory. If `build.json.hasBackend` is `true`, the tool warns and you must repeat it plainly: only the front end goes live this way; the server part needs serverless functions or a separate host. Do not imply a backend is running when it is not.
+The default deploy publishes a **static** publish directory. If `build.json.hasBackend` is `true`, the build also emitted a real backend (serverless functions, a `schema.sql`, a names-only `.env.example`, an updated `netlify.toml`, and a `BACKEND.md` guide), but **backend deploy automation is a follow-up**, so this step ships only the front end for now. The tool warns; repeat its guidance plainly and point the user at `BACKEND.md`. To run the backend they provision Neon Postgres, set `DATABASE_URL` (and the other names from `.env.example`) in their host environment, then run `netlify deploy` with the functions present. Do not imply a backend is running when it is not.
 
 ## After it is live