@hobocode/thought-layer 0.3.0 → 0.4.1

package/README.md

@@ -20,9 +20,9 @@ This is open source and BYOK by design. The point is to help people build real t
 
 **A Pi package** that adds, on top of the skills:
 
-- **Deterministic tools** the agent can call so the math is exact and never re-derived: `tl_score` (confidence to status and grade), `tl_domains` (availability, BYOK), `tl_project` (the numeric business projection), `tl_state` (the portable progress file), and `tl_scaffold` (a deterministic, deployable static site from the spec + brand).
-- **Slash commands** (prompt templates): `/tl` runs the whole flow; `/tl-speedrun` is the fast unranked path; `/tl-panel`, `/tl-grill`, `/tl-prd`, `/tl-naming` run each stage; `/tl-build` builds the hardened PRD into a deploy-ready artifact.
-- **A `tl` CLI** for any shell agent (`npx -y @hobocode/thought-layer tl ...`): `read`/`list`/`answer`/`feedback`/`artifact`/`cursor`/`export` for the shared progress file, and `scaffold` for the deployable static-site floor.
+- **Deterministic tools** the agent can call so the math is exact and never re-derived: `tl_score` (confidence to status and grade), `tl_domains` (availability, BYOK), `tl_project` (the numeric business projection), `tl_state` (the portable progress file), `tl_scaffold` (a deterministic, deployable static site from the spec + brand), and `deploy` (take the build live to a URL you own).
+- **Slash commands** (prompt templates): `/tl` runs the whole flow; `/tl-speedrun` is the fast unranked path; `/tl-panel`, `/tl-grill`, `/tl-prd`, `/tl-naming` run each stage; `/tl-build` builds the hardened PRD into a deploy-ready artifact; `/tl-deploy` takes it live.
+- **A `tl` CLI** for any shell agent (`npx -y @hobocode/thought-layer tl ...`): `read`/`list`/`answer`/`feedback`/`artifact`/`cursor`/`export` for the shared progress file, `scaffold` for the deployable static-site floor, and `deploy` to take the build live.
 
 ## Install
 
@@ -64,7 +64,7 @@ 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:** a `deploy` step that publishes it to a live URL you own (Netlify deploy-and-claim by default), closing the loop.
+- **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.
 
 ## Notes for contributors
 

package/core/deploy-io.ts

@@ -0,0 +1,367 @@
+// Node IO for the deploy step, shared by the deploy Pi tool and the `tl deploy`
+// CLI. The pure transforms live in deploy.ts; this reads build.json, walks the
+// publish dir, talks to the Netlify API (BYO token, file-digest method), or
+// delegates the zero-account path to the Netlify CLI's own --allow-anonymous
+// flow, then writes a deploy.json record.
+//
+// Two deploy models, both keeping ownership with the user and nothing phoning a
+// central account (the kit has no server):
+//   token     - deploy into the user's OWN Netlify account via NETLIFY_AUTH_TOKEN.
+//               The site is theirs from the first second. This is the primary,
+//               fully-in-process path (sha1 + fetch, no zip, no deps).
+//   anonymous - the user has no account yet: shell out to `netlify deploy
+//               --allow-anonymous` (Netlify's own supported flow) for a live URL
+//               plus a one-hour claim link. We never reverse-engineer that
+//               handshake; we use the vendor tool when it is installed.
+
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { resolveStatePath } from "./state-file.ts";
+import type { BuildManifest } from "./scaffold.ts";
+import type { StateOpResult } from "./state-ops.ts";
+import {
+  buildFileDigests, uploadPath, sanitizeSiteName, parseCliDeployOutput, deployRecord,
+  type FileMap, type DeployRecord,
+} from "./deploy.ts";
+
+const NETLIFY_API = "https://api.netlify.com/api/v1";
+
+export interface DeployRunOptions {
+  path?: string;       // state file / project dir, selects which build.json to read
+  dryRun?: boolean;    // plan only: walk + digest, no network or spawn
+  anonymous?: boolean; // force the no-account CLI path even if a token is set
+  siteName?: string;   // create the site under this name (else Netlify auto-names)
+  siteId?: string;     // deploy to an existing site (re-deploy) instead of creating one
+}
+
+// ---- locate + read the build manifest ----------------------------------------
+
+interface ResolvedBuild {
+  manifest: BuildManifest;
+  manifestPath: string;
+  publishDirAbs: string;
+  stateFile: string;
+}
+
+function readBuild(target?: string): ResolvedBuild {
+  const statePath = resolveStatePath(target);
+  const manifestPath = join(dirname(statePath), "build.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(
+      `No build.json found at ${manifestPath}. Run the build first: the thought-layer-build skill (/tl-build) ` +
+        `or the tl_scaffold tool (\`tl scaffold\`) writes the manifest the deploy reads.`,
+    );
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as BuildManifest;
+  // publishDir is relative to the project root (the parent of .thought-layer/),
+  // falling back to cwd; absolute wins as-is.
+  const projectRoot = dirname(dirname(statePath));
+  const publishDirAbs = resolvePublishDir(manifest.publishDir, projectRoot);
+  return { manifest, manifestPath, publishDirAbs, stateFile: statePath };
+}
+
+function resolvePublishDir(publishDir: string, projectRoot: string): string {
+  const candidates = [resolve(projectRoot, publishDir), resolve(process.cwd(), publishDir)];
+  for (const c of candidates) if (existsSync(c)) return c;
+  throw new Error(
+    `Publish dir "${publishDir}" from build.json does not exist (looked in ${candidates.join(" and ")}). ` +
+      `Re-run the build, or fix publishDir in build.json.`,
+  );
+}
+
+// ---- walk the publish dir into an in-memory file map --------------------------
+
+function walkPublishDir(dir: string): FileMap {
+  const files: FileMap = {};
+  const walk = (d: string): void => {
+    for (const name of readdirSync(d)) {
+      const full = join(d, name);
+      const st = statSync(full);
+      if (st.isDirectory()) walk(full);
+      else if (st.isFile()) {
+        const rel = relative(dir, full).split(/[\\/]/).join("/");
+        files["/" + rel] = readFileSync(full);
+      }
+    }
+  };
+  walk(dir);
+  return files;
+}
+
+// ---- the Netlify file-digest deploy (BYO token) ------------------------------
+
+interface DigestResult {
+  url: string;
+  adminUrl: string;
+  siteId: string;
+  deployId: string;
+  uploaded: number;
+  state: string;
+}
+
+async function netlifyJson(url: string, init: RequestInit, token: string): Promise<Record<string, unknown>> {
+  const res = await fetch(url, {
+    ...init,
+    headers: { Authorization: `Bearer ${token}`, ...(init.headers || {}) },
+  });
+  const body = await res.text();
+  if (!res.ok) {
+    throw new Error(`Netlify API ${res.status} ${res.statusText} on ${init.method || "GET"} ${url}: ${body.slice(0, 400)}`);
+  }
+  return body ? (JSON.parse(body) as Record<string, unknown>) : {};
+}
+
+async function digestDeploy(
+  files: FileMap,
+  opts: { token: string; siteName?: string; siteId?: string },
+): Promise<DigestResult> {
+  let siteId = opts.siteId;
+  let adminUrl = "";
+  let siteUrl = "";
+
+  if (!siteId) {
+    const body = opts.siteName ? JSON.stringify({ name: sanitizeSiteName(opts.siteName) }) : JSON.stringify({});
+    const site = await netlifyJson(`${NETLIFY_API}/sites`, { method: "POST", headers: { "Content-Type": "application/json" }, body }, opts.token);
+    siteId = String(site["id"] || "");
+    adminUrl = String(site["admin_url"] || "");
+    siteUrl = String(site["ssl_url"] || site["url"] || "");
+  }
+
+  const { digests, pathForDigest } = buildFileDigests(files);
+  const deploy = await netlifyJson(
+    `${NETLIFY_API}/sites/${siteId}/deploys`,
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ files: digests }) },
+    opts.token,
+  );
+  const deployId = String(deploy["id"] || "");
+  const required = Array.isArray(deploy["required"]) ? (deploy["required"] as string[]) : [];
+  if (!adminUrl) adminUrl = String(deploy["admin_url"] || "");
+
+  // Upload one file per unique required sha1.
+  let uploaded = 0;
+  for (const sha of required) {
+    const key = pathForDigest[sha];
+    const buf = key ? files[key] : undefined;
+    if (!key || !buf) continue; // Netlify asked for a digest we did not send; skip.
+    const r = await fetch(`${NETLIFY_API}/deploys/${deployId}/files/${uploadPath(key)}`, {
+      method: "PUT",
+      headers: { Authorization: `Bearer ${opts.token}`, "Content-Type": "application/octet-stream" },
+      body: new Uint8Array(buf), // Buffer is a Uint8Array; this satisfies BodyInit cleanly.
+    });
+    if (!r.ok) throw new Error(`Netlify upload ${r.status} for ${key}: ${(await r.text()).slice(0, 200)}`);
+    uploaded++;
+  }
+
+  // Poll until the deploy is live (small static sites are usually instant).
+  let state = String(deploy["state"] || "");
+  for (let i = 0; i < 30 && state !== "ready" && state !== "error"; i++) {
+    await new Promise((r) => setTimeout(r, 1000));
+    const d = await netlifyJson(`${NETLIFY_API}/deploys/${deployId}`, { method: "GET" }, opts.token);
+    state = String(d["state"] || "");
+    if (!siteUrl) siteUrl = String(d["ssl_url"] || d["deploy_ssl_url"] || "");
+  }
+  if (state === "error") throw new Error(`Netlify deploy ${deployId} reported state "error".`);
+
+  return { url: siteUrl, adminUrl, siteId: String(siteId), deployId, uploaded, state: state || "uploaded" };
+}
+
+// ---- the no-env-token path: delegate to the Netlify CLI ----------------------
+
+export function hasNetlifyCli(): boolean {
+  try {
+    const r = spawnSync("netlify", ["--version"], { encoding: "utf8", timeout: 15000 });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// --allow-anonymous shipped in the Netlify CLI in 2026-03; older CLIs reject it.
+// Probe `netlify deploy --help` so we guide instead of spawning a deploy that
+// errors on the unknown flag (and would otherwise prompt interactively).
+export function cliSupportsAnonymous(): boolean {
+  try {
+    const r = spawnSync("netlify", ["deploy", "--help"], { encoding: "utf8", timeout: 15000 });
+    return `${r.stdout || ""}${r.stderr || ""}`.includes("--allow-anonymous");
+  } catch {
+    return false;
+  }
+}
+
+// Is the CLI logged in via its OWN stored config (independent of our env)? This
+// matters because --allow-anonymous is a no-op when logged in, and a plain
+// deploy then needs a target site - so a logged-in CLI must create a site in the
+// user's account instead. getCurrentUser exits 0 with JSON when logged in.
+export function cliLoggedIn(): boolean {
+  try {
+    const r = spawnSync("netlify", ["api", "getCurrentUser", "--data", "{}"], { encoding: "utf8", timeout: 20000 });
+    return r.status === 0 && (r.stdout || "").trim().startsWith("{");
+  } catch {
+    return false;
+  }
+}
+
+export interface CliDeployResult {
+  url: string | null;
+  claimUrl: string | null;
+  owned: boolean;
+  siteName: string | null;
+  raw: string;
+}
+
+// Deploy via the Netlify CLI, picking flags from the CLI's own login state:
+//   logged in  -> create (or, with siteId, reuse) a site in the user's account,
+//                 owned immediately, no claim step.
+//   logged out -> an anonymous, claimable site (one-hour window).
+// --no-build forces a plain publish of our already-built static dir (no
+// framework detection / build step). The caller has decided the CLI path is
+// wanted and that the CLI exists + supports what is needed.
+function cliDeploy(publishDirAbs: string, opts: { siteName?: string; siteId?: string }, loggedIn: boolean): CliDeployResult {
+  const base = ["deploy", "--dir", publishDirAbs, "--prod", "--no-build"];
+  let args: string[];
+  let siteName: string | null = null;
+  if (loggedIn) {
+    if (opts.siteId) args = [...base, "--site", opts.siteId];
+    else {
+      siteName = sanitizeSiteName(opts.siteName || "") || `thought-layer-${randomBytes(4).toString("hex")}`;
+      args = [...base, "--create-site", siteName];
+    }
+  } else {
+    args = [...base, "--allow-anonymous"];
+  }
+  const r = spawnSync("netlify", args, { encoding: "utf8", timeout: 180000 });
+  const raw = `${r.stdout || ""}\n${r.stderr || ""}`.trim();
+  if (r.status !== 0) {
+    throw new Error(`netlify ${args.join(" ")} failed (exit ${r.status}). Output:\n${raw.slice(0, 800)}`);
+  }
+  const parsed = parseCliDeployOutput(raw);
+  // A claim link only applies to the anonymous (logged-out) site.
+  return { url: parsed.url, claimUrl: loggedIn ? null : parsed.claimUrl, owned: loggedIn, siteName, raw };
+}
+
+// ---- the orchestrator (mirrors runScaffold's result shape) -------------------
+
+export async function runDeploy(opts: DeployRunOptions, ctx: { deployedAt: string }): Promise<StateOpResult> {
+  let build: ResolvedBuild;
+  try {
+    build = readBuild(opts.path);
+  } catch (e) {
+    return { ok: false, message: (e as Error).message, details: {} };
+  }
+  const { manifest, publishDirAbs, stateFile } = build;
+  const files = walkPublishDir(publishDirAbs);
+  const fileCount = Object.keys(files).length;
+  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 token = process.env.NETLIFY_AUTH_TOKEN || process.env.NETLIFY_TOKEN || "";
+
+  const writeRecord = (rec: DeployRecord): string => {
+    const recPath = join(dirname(stateFile), "deploy.json");
+    mkdirSync(dirname(recPath), { recursive: true });
+    writeFileSync(recPath, JSON.stringify(rec, null, 2) + "\n");
+    return recPath;
+  };
+
+  // --- dry run: plan only, no network, no spawn ---
+  if (opts.dryRun) {
+    const { digests } = buildFileDigests(files);
+    return {
+      ok: true,
+      message:
+        `Dry run: would deploy ${fileCount} files from ${publishDirAbs} (entry ${manifest.entry}) to Netlify ` +
+        `via the ${token && !opts.anonymous ? "BYO-token digest" : "Netlify CLI (logged in -> a site in your account; logged out -> an anonymous claimable site)"} path.${backendWarn}`,
+      details: { dryRun: true, publishDir: publishDirAbs, entry: manifest.entry, fileCount, files: Object.keys(digests), hasBackend: manifest.hasBackend },
+    };
+  }
+
+  // --- CLI path: explicit (--anonymous), or the fallback when no env token ---
+  const wantCli = opts.anonymous || !token;
+  if (wantCli) {
+    // The three honest ways to go live, shown whenever the CLI path cannot run.
+    const guide = (lead: string, needs: string): StateOpResult => ({
+      ok: false,
+      message:
+        lead +
+        `To go live, choose one:\n` +
+        `  1. BYO token (deploys into your own account, owned immediately): set NETLIFY_AUTH_TOKEN and re-run.\n` +
+        `  2. Netlify CLI (\`npm i -g netlify-cli@latest\`) then re-run - logged in it creates a site in your account; logged out it deploys anonymously with a one-hour claim link.\n` +
+        `  3. Manual: drag ${publishDirAbs} onto https://app.netlify.com/drop.`,
+      details: { publishDir: publishDirAbs, needs },
+    });
+    if (!hasNetlifyCli()) {
+      return guide(
+        opts.anonymous
+          ? "A CLI deploy needs the Netlify CLI, which is not installed. "
+          : "No NETLIFY_AUTH_TOKEN is set and the Netlify CLI is not installed. ",
+        "token-or-cli",
+      );
+    }
+    const loggedIn = cliLoggedIn();
+    if (!loggedIn && !cliSupportsAnonymous()) {
+      return guide(
+        "You are not logged into the Netlify CLI and it is too old for --allow-anonymous (that shipped 2026-03). ",
+        "newer-cli-or-login-or-token",
+      );
+    }
+    try {
+      const { url, claimUrl, owned, siteName, raw } = cliDeploy(publishDirAbs, { siteName: opts.siteName, siteId: opts.siteId }, loggedIn);
+      const recPath = writeRecord(
+        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,
+        }),
+      );
+      // If anonymity was explicitly asked for but the CLI is logged in, it went
+      // to the account instead - say so rather than implying it was anonymous.
+      const anonNote = opts.anonymous && owned
+        ? `\n(Note: you asked for an anonymous deploy, but the Netlify CLI is logged in, so this went to your account. Run \`netlify logout\` first for a truly anonymous, claimable deploy.)`
+        : "";
+      return {
+        ok: true,
+        message: owned
+          ? `Deployed to your Netlify account via the CLI${siteName ? ` (new site ${siteName})` : ""}.${url ? ` Live: ${url}` : ""}` +
+            `\nIt is owned by your account - no claim needed.\nRecorded ${recPath}.${anonNote}${backendWarn}` +
+            (!url ? `\n(Could not parse a URL from the CLI output - see details.raw.)` : "")
+          : `Deployed anonymously.${url ? ` Live: ${url}` : ""}${claimUrl ? `\nClaim it within 1 hour (transfers ownership to your account): ${claimUrl}` : ""}` +
+            `\nRecorded ${recPath}.${backendWarn}` +
+            (!url || !claimUrl ? `\n(Could not parse a URL/claim link from the CLI output - see details.raw.)` : ""),
+        details: { mode: owned ? "cli" : "anonymous", url, claimUrl, owned, siteName, fileCount, raw },
+      };
+    } catch (e) {
+      return { ok: false, message: (e as Error).message, details: { mode: "cli" } };
+    }
+  }
+
+  // --- BYO-token path: deploy into the user's own account ---
+  try {
+    const r = await digestDeploy(files, { token, siteName: opts.siteName, siteId: opts.siteId });
+    const recPath = writeRecord(
+      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,
+      }),
+    );
+    return {
+      ok: true,
+      message:
+        `Deployed to your Netlify account (${r.uploaded} file${r.uploaded === 1 ? "" : "s"} uploaded, state ${r.state}).` +
+        `${r.url ? ` Live: ${r.url}` : ""}${r.adminUrl ? `\nManage: ${r.adminUrl}` : ""}` +
+        `\nIt is owned by your account - no claim needed. Re-deploy to the same site with --site ${r.siteId}.` +
+        `\nRecorded ${recPath}.${backendWarn}`,
+      details: { mode: "token", url: r.url, adminUrl: r.adminUrl, siteId: r.siteId, deployId: r.deployId, uploaded: r.uploaded, state: r.state },
+    };
+  } catch (e) {
+    return { ok: false, message: `Deploy failed: ${(e as Error).message}`, details: { mode: "token" } };
+  }
+}

package/core/deploy.ts

@@ -0,0 +1,115 @@
+// Deterministic, no-IO helpers for the deploy step: hash the publish dir into
+// the Netlify file-digest map, derive a safe site name, build the deploy.json
+// record, and parse the anonymous-CLI output. The fs walk and the network calls
+// live in deploy-io.ts; keeping these pure means the digest + record logic is
+// unit-testable without touching disk or the Netlify API.
+//
+// Netlify's file-digest deploy (the path we use with a BYO token) needs no zip
+// and no dependencies: POST a { "/path": sha1 } map, then PUT the raw bytes for
+// each sha1 Netlify reports back as `required`. crypto.createHash is the only
+// import and it is pure (content in, hex out).
+
+import { createHash } from "node:crypto";
+
+export const sha1Hex = (data: Buffer | string): string =>
+  createHash("sha1").update(data).digest("hex");
+
+// A file map is keyed by the site-relative path WITH a leading slash, posix
+// separators (e.g. "/index.html", "/assets/app.js") - the shape Netlify's
+// deploys endpoint expects in its `files` object.
+export type FileMap = Record<string, Buffer>;
+
+export interface FileDigests {
+  // path (leading slash) -> sha1, sent as the deploy `files` body.
+  digests: Record<string, string>;
+  // sha1 -> one path that has it, so an upload happens once per unique sha1
+  // even when several files share content.
+  pathForDigest: Record<string, string>;
+}
+
+export function buildFileDigests(files: FileMap): FileDigests {
+  const digests: Record<string, string> = {};
+  const pathForDigest: Record<string, string> = {};
+  for (const [path, buf] of Object.entries(files)) {
+    const key = normalizeKey(path);
+    const sha = sha1Hex(buf);
+    digests[key] = sha;
+    if (!(sha in pathForDigest)) pathForDigest[sha] = key;
+  }
+  return { digests, pathForDigest };
+}
+
+// Normalize a relative path to a leading-slash posix key.
+export function normalizeKey(path: string): string {
+  const posix = path.replace(/\\/g, "/").replace(/^\.?\/*/, "");
+  return "/" + posix;
+}
+
+// The URL segment for a PUT files/<path> upload: drop the leading slash and
+// percent-encode each segment (Netlify forbids raw # and ? in the path), while
+// preserving the slashes that separate directories.
+export function uploadPath(key: string): string {
+  return key
+    .replace(/^\/+/, "")
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/");
+}
+
+// Netlify site names are a global namespace of [a-z0-9-]. Derive a clean
+// candidate from a brand/product name; empty -> "" so the caller lets Netlify
+// assign a random subdomain instead (no collision risk).
+export function sanitizeSiteName(raw: string): string {
+  return String(raw || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/-+$/g, "");
+}
+
+// Pull the live URL and (anonymous only) the claim link out of `netlify deploy`
+// output. The CLI prints several *.netlify.app URLs - the production site URL
+// and a unique per-deploy URL (whose host carries a "--" prefix); prefer the
+// production one. The claim link only appears for an anonymous, unclaimed site;
+// we never synthesize it ourselves (the handshake is Netlify's, not ours).
+export function parseCliDeployOutput(output: string): { url: string | null; claimUrl: string | null } {
+  // Stop the URL at whitespace OR a wrapping bracket/quote: the CLI sometimes
+  // prints links as <url> or in a box, and a greedy \S* would swallow the ">".
+  const claim = output.match(/https:\/\/app\.netlify\.com\/claim[^\s<>"')\]]*/);
+  const all = (output.match(/https:\/\/[a-z0-9-]+\.netlify\.app[^\s<>"')\]]*/gi) || []).map(stripTrailingPunctuation);
+  const host = (u: string): string => u.replace(/^https:\/\//, "").split("/")[0]!;
+  const prod = all.find((u) => !host(u).includes("--")); // skip the per-deploy URL
+  return {
+    url: prod || all[0] || null,
+    claimUrl: claim ? stripTrailingPunctuation(claim[0]) : null,
+  };
+}
+
+const stripTrailingPunctuation = (s: string): string => s.replace(/[)\]>.,'"<]+$/, "");
+
+// The deploy record written next to build.json / the state file. Pure provenance
+// so a re-deploy can target the same site and the user can find their URLs.
+export interface DeployRecord {
+  app: "thought-layer";
+  kind: "deploy";
+  version: 1;
+  deployedAt: string;
+  mode: "token" | "cli" | "anonymous" | "dry-run";
+  provider: "netlify";
+  publishDir: string;
+  fileCount: number;
+  url: string | null;
+  adminUrl: string | null;
+  claimUrl: string | null;
+  siteId: string | null;
+  deployId: string | null;
+  hasBackend: boolean;
+  backendNote: string | null;
+  buildProducer: "agent" | "scaffold" | null;
+  stateFile: string | null;
+}
+
+export function deployRecord(input: Omit<DeployRecord, "app" | "kind" | "version" | "provider">): DeployRecord {
+  return { app: "thought-layer", kind: "deploy", version: 1, provider: "netlify", ...input };
+}

package/core/index.ts

@@ -17,3 +17,5 @@ export * from "./state-file.ts";
 export * from "./state-ops.ts";
 export * from "./scaffold.ts";
 export * from "./scaffold-io.ts";
+export * from "./deploy.ts";
+export * from "./deploy-io.ts";

package/dist/tl.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // bin/tl.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 
 // core/scoring.ts
 var CONFIDENCE_GOAL = 0.85;
@@ -669,12 +669,318 @@ function runScaffold(opts, ctx) {
   }
 }
 
+// core/deploy-io.ts
+import { spawnSync } from "child_process";
+import { randomBytes } from "crypto";
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync2, readdirSync as readdirSync2, statSync, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join3, relative, resolve as resolve3 } from "path";
+
+// core/deploy.ts
+import { createHash } from "crypto";
+var sha1Hex = (data) => createHash("sha1").update(data).digest("hex");
+function buildFileDigests(files) {
+  const digests = {};
+  const pathForDigest = {};
+  for (const [path, buf] of Object.entries(files)) {
+    const key = normalizeKey(path);
+    const sha = sha1Hex(buf);
+    digests[key] = sha;
+    if (!(sha in pathForDigest)) pathForDigest[sha] = key;
+  }
+  return { digests, pathForDigest };
+}
+function normalizeKey(path) {
+  const posix = path.replace(/\\/g, "/").replace(/^\.?\/*/, "");
+  return "/" + posix;
+}
+function uploadPath(key) {
+  return key.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
+}
+function sanitizeSiteName(raw) {
+  return String(raw || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/g, "");
+}
+function parseCliDeployOutput(output) {
+  const claim = output.match(/https:\/\/app\.netlify\.com\/claim[^\s<>"')\]]*/);
+  const all = (output.match(/https:\/\/[a-z0-9-]+\.netlify\.app[^\s<>"')\]]*/gi) || []).map(stripTrailingPunctuation);
+  const host = (u) => u.replace(/^https:\/\//, "").split("/")[0];
+  const prod = all.find((u) => !host(u).includes("--"));
+  return {
+    url: prod || all[0] || null,
+    claimUrl: claim ? stripTrailingPunctuation(claim[0]) : null
+  };
+}
+var stripTrailingPunctuation = (s) => s.replace(/[)\]>.,'"<]+$/, "");
+function deployRecord(input) {
+  return { app: "thought-layer", kind: "deploy", version: 1, provider: "netlify", ...input };
+}
+
+// core/deploy-io.ts
+var NETLIFY_API = "https://api.netlify.com/api/v1";
+function readBuild(target) {
+  const statePath = resolveStatePath(target);
+  const manifestPath = join3(dirname3(statePath), "build.json");
+  if (!existsSync2(manifestPath)) {
+    throw new Error(
+      `No build.json found at ${manifestPath}. Run the build first: the thought-layer-build skill (/tl-build) or the tl_scaffold tool (\`tl scaffold\`) writes the manifest the deploy reads.`
+    );
+  }
+  const manifest = JSON.parse(readFileSync2(manifestPath, "utf8"));
+  const projectRoot = dirname3(dirname3(statePath));
+  const publishDirAbs = resolvePublishDir(manifest.publishDir, projectRoot);
+  return { manifest, manifestPath, publishDirAbs, stateFile: statePath };
+}
+function resolvePublishDir(publishDir, projectRoot) {
+  const candidates = [resolve3(projectRoot, publishDir), resolve3(process.cwd(), publishDir)];
+  for (const c of candidates) if (existsSync2(c)) return c;
+  throw new Error(
+    `Publish dir "${publishDir}" from build.json does not exist (looked in ${candidates.join(" and ")}). Re-run the build, or fix publishDir in build.json.`
+  );
+}
+function walkPublishDir(dir) {
+  const files = {};
+  const walk = (d) => {
+    for (const name of readdirSync2(d)) {
+      const full = join3(d, name);
+      const st = statSync(full);
+      if (st.isDirectory()) walk(full);
+      else if (st.isFile()) {
+        const rel = relative(dir, full).split(/[\\/]/).join("/");
+        files["/" + rel] = readFileSync2(full);
+      }
+    }
+  };
+  walk(dir);
+  return files;
+}
+async function netlifyJson(url, init, token) {
+  const res = await fetch(url, {
+    ...init,
+    headers: { Authorization: `Bearer ${token}`, ...init.headers || {} }
+  });
+  const body = await res.text();
+  if (!res.ok) {
+    throw new Error(`Netlify API ${res.status} ${res.statusText} on ${init.method || "GET"} ${url}: ${body.slice(0, 400)}`);
+  }
+  return body ? JSON.parse(body) : {};
+}
+async function digestDeploy(files, opts) {
+  let siteId = opts.siteId;
+  let adminUrl = "";
+  let siteUrl = "";
+  if (!siteId) {
+    const body = opts.siteName ? JSON.stringify({ name: sanitizeSiteName(opts.siteName) }) : JSON.stringify({});
+    const site = await netlifyJson(`${NETLIFY_API}/sites`, { method: "POST", headers: { "Content-Type": "application/json" }, body }, opts.token);
+    siteId = String(site["id"] || "");
+    adminUrl = String(site["admin_url"] || "");
+    siteUrl = String(site["ssl_url"] || site["url"] || "");
+  }
+  const { digests, pathForDigest } = buildFileDigests(files);
+  const deploy = await netlifyJson(
+    `${NETLIFY_API}/sites/${siteId}/deploys`,
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ files: digests }) },
+    opts.token
+  );
+  const deployId = String(deploy["id"] || "");
+  const required = Array.isArray(deploy["required"]) ? deploy["required"] : [];
+  if (!adminUrl) adminUrl = String(deploy["admin_url"] || "");
+  let uploaded = 0;
+  for (const sha of required) {
+    const key = pathForDigest[sha];
+    const buf = key ? files[key] : void 0;
+    if (!key || !buf) continue;
+    const r = await fetch(`${NETLIFY_API}/deploys/${deployId}/files/${uploadPath(key)}`, {
+      method: "PUT",
+      headers: { Authorization: `Bearer ${opts.token}`, "Content-Type": "application/octet-stream" },
+      body: new Uint8Array(buf)
+      // Buffer is a Uint8Array; this satisfies BodyInit cleanly.
+    });
+    if (!r.ok) throw new Error(`Netlify upload ${r.status} for ${key}: ${(await r.text()).slice(0, 200)}`);
+    uploaded++;
+  }
+  let state = String(deploy["state"] || "");
+  for (let i = 0; i < 30 && state !== "ready" && state !== "error"; i++) {
+    await new Promise((r) => setTimeout(r, 1e3));
+    const d = await netlifyJson(`${NETLIFY_API}/deploys/${deployId}`, { method: "GET" }, opts.token);
+    state = String(d["state"] || "");
+    if (!siteUrl) siteUrl = String(d["ssl_url"] || d["deploy_ssl_url"] || "");
+  }
+  if (state === "error") throw new Error(`Netlify deploy ${deployId} reported state "error".`);
+  return { url: siteUrl, adminUrl, siteId: String(siteId), deployId, uploaded, state: state || "uploaded" };
+}
+function hasNetlifyCli() {
+  try {
+    const r = spawnSync("netlify", ["--version"], { encoding: "utf8", timeout: 15e3 });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+function cliSupportsAnonymous() {
+  try {
+    const r = spawnSync("netlify", ["deploy", "--help"], { encoding: "utf8", timeout: 15e3 });
+    return `${r.stdout || ""}${r.stderr || ""}`.includes("--allow-anonymous");
+  } catch {
+    return false;
+  }
+}
+function cliLoggedIn() {
+  try {
+    const r = spawnSync("netlify", ["api", "getCurrentUser", "--data", "{}"], { encoding: "utf8", timeout: 2e4 });
+    return r.status === 0 && (r.stdout || "").trim().startsWith("{");
+  } catch {
+    return false;
+  }
+}
+function cliDeploy(publishDirAbs, opts, loggedIn) {
+  const base = ["deploy", "--dir", publishDirAbs, "--prod", "--no-build"];
+  let args;
+  let siteName = null;
+  if (loggedIn) {
+    if (opts.siteId) args = [...base, "--site", opts.siteId];
+    else {
+      siteName = sanitizeSiteName(opts.siteName || "") || `thought-layer-${randomBytes(4).toString("hex")}`;
+      args = [...base, "--create-site", siteName];
+    }
+  } else {
+    args = [...base, "--allow-anonymous"];
+  }
+  const r = spawnSync("netlify", args, { encoding: "utf8", timeout: 18e4 });
+  const raw = `${r.stdout || ""}
+${r.stderr || ""}`.trim();
+  if (r.status !== 0) {
+    throw new Error(`netlify ${args.join(" ")} failed (exit ${r.status}). Output:
+${raw.slice(0, 800)}`);
+  }
+  const parsed = parseCliDeployOutput(raw);
+  return { url: parsed.url, claimUrl: loggedIn ? null : parsed.claimUrl, owned: loggedIn, siteName, raw };
+}
+async function runDeploy(opts, ctx) {
+  let build;
+  try {
+    build = readBuild(opts.path);
+  } catch (e) {
+    return { ok: false, message: e.message, details: {} };
+  }
+  const { manifest, publishDirAbs, stateFile } = build;
+  const files = walkPublishDir(publishDirAbs);
+  const fileCount = Object.keys(files).length;
+  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 token = process.env.NETLIFY_AUTH_TOKEN || process.env.NETLIFY_TOKEN || "";
+  const writeRecord = (rec) => {
+    const recPath = join3(dirname3(stateFile), "deploy.json");
+    mkdirSync3(dirname3(recPath), { recursive: true });
+    writeFileSync3(recPath, JSON.stringify(rec, null, 2) + "\n");
+    return recPath;
+  };
+  if (opts.dryRun) {
+    const { digests } = buildFileDigests(files);
+    return {
+      ok: true,
+      message: `Dry run: would deploy ${fileCount} files from ${publishDirAbs} (entry ${manifest.entry}) to Netlify via the ${token && !opts.anonymous ? "BYO-token digest" : "Netlify CLI (logged in -> a site in your account; logged out -> an anonymous claimable site)"} path.${backendWarn}`,
+      details: { dryRun: true, publishDir: publishDirAbs, entry: manifest.entry, fileCount, files: Object.keys(digests), hasBackend: manifest.hasBackend }
+    };
+  }
+  const wantCli = opts.anonymous || !token;
+  if (wantCli) {
+    const guide = (lead, needs) => ({
+      ok: false,
+      message: lead + `To go live, choose one:
+  1. BYO token (deploys into your own account, owned immediately): set NETLIFY_AUTH_TOKEN and re-run.
+  2. Netlify CLI (\`npm i -g netlify-cli@latest\`) then re-run - logged in it creates a site in your account; logged out it deploys anonymously with a one-hour claim link.
+  3. Manual: drag ${publishDirAbs} onto https://app.netlify.com/drop.`,
+      details: { publishDir: publishDirAbs, needs }
+    });
+    if (!hasNetlifyCli()) {
+      return guide(
+        opts.anonymous ? "A CLI deploy needs the Netlify CLI, which is not installed. " : "No NETLIFY_AUTH_TOKEN is set and the Netlify CLI is not installed. ",
+        "token-or-cli"
+      );
+    }
+    const loggedIn = cliLoggedIn();
+    if (!loggedIn && !cliSupportsAnonymous()) {
+      return guide(
+        "You are not logged into the Netlify CLI and it is too old for --allow-anonymous (that shipped 2026-03). ",
+        "newer-cli-or-login-or-token"
+      );
+    }
+    try {
+      const { url, claimUrl, owned, siteName, raw } = cliDeploy(publishDirAbs, { siteName: opts.siteName, siteId: opts.siteId }, loggedIn);
+      const recPath = writeRecord(
+        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
+        })
+      );
+      const anonNote = opts.anonymous && owned ? `
+(Note: you asked for an anonymous deploy, but the Netlify CLI is logged in, so this went to your account. Run \`netlify logout\` first for a truly anonymous, claimable deploy.)` : "";
+      return {
+        ok: true,
+        message: owned ? `Deployed to your Netlify account via the CLI${siteName ? ` (new site ${siteName})` : ""}.${url ? ` Live: ${url}` : ""}
+It is owned by your account - no claim needed.
+Recorded ${recPath}.${anonNote}${backendWarn}` + (!url ? `
+(Could not parse a URL from the CLI output - see details.raw.)` : "") : `Deployed anonymously.${url ? ` Live: ${url}` : ""}${claimUrl ? `
+Claim it within 1 hour (transfers ownership to your account): ${claimUrl}` : ""}
+Recorded ${recPath}.${backendWarn}` + (!url || !claimUrl ? `
+(Could not parse a URL/claim link from the CLI output - see details.raw.)` : ""),
+        details: { mode: owned ? "cli" : "anonymous", url, claimUrl, owned, siteName, fileCount, raw }
+      };
+    } catch (e) {
+      return { ok: false, message: e.message, details: { mode: "cli" } };
+    }
+  }
+  try {
+    const r = await digestDeploy(files, { token, siteName: opts.siteName, siteId: opts.siteId });
+    const recPath = writeRecord(
+      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
+      })
+    );
+    return {
+      ok: true,
+      message: `Deployed to your Netlify account (${r.uploaded} file${r.uploaded === 1 ? "" : "s"} uploaded, state ${r.state}).${r.url ? ` Live: ${r.url}` : ""}${r.adminUrl ? `
+Manage: ${r.adminUrl}` : ""}
+It is owned by your account - no claim needed. Re-deploy to the same site with --site ${r.siteId}.
+Recorded ${recPath}.${backendWarn}`,
+      details: { mode: "token", url: r.url, adminUrl: r.adminUrl, siteId: r.siteId, deployId: r.deployId, uploaded: r.uploaded, state: r.state }
+    };
+  } catch (e) {
+    return { ok: false, message: `Deploy failed: ${e.message}`, details: { mode: "token" } };
+  }
+}
+
 // bin/tl.ts
 var HELP = `tl - read/write a portable Thought Layer state file (default: .thought-layer/state.json)
 
   tl read [path] [--json]            where the run stands
   tl list [dir]                      list the state files under .thought-layer/ (juggle several ideas)
   tl scaffold [--out dist] [--domain x.com] [--founder "Name"]  deterministic deployable static site from the spec + brand
+  tl deploy [--dry-run] [--anonymous] [--name x] [--site id]  take build.json's publish dir live to a user-owned Netlify URL
   tl export [path]                   handoff check
   tl answer <qId> <value> [path]     record an answer
   tl feedback --data '<json>'        record a panel verdict ({qId,mode,personas,endState,round})
@@ -709,7 +1015,7 @@ function parseArgs(argv) {
 function readData(flags) {
   const d = flags["data"];
   if (d === void 0) return void 0;
-  const raw = d === "-" || d === true ? readFileSync2(0, "utf8") : String(d);
+  const raw = d === "-" || d === true ? readFileSync3(0, "utf8") : String(d);
   try {
     return JSON.parse(raw);
   } catch {
@@ -763,6 +1069,23 @@ function main() {
     else console.log(r2.message);
     process.exit(r2.ok ? 0 : 1);
   }
+  if (args[0] === "deploy") {
+    runDeploy(
+      {
+        path: typeof flags["path"] === "string" ? flags["path"] : void 0,
+        dryRun: flags["dry-run"] === true,
+        anonymous: flags["anonymous"] === true,
+        siteName: typeof flags["name"] === "string" ? flags["name"] : void 0,
+        siteId: typeof flags["site"] === "string" ? flags["site"] : void 0
+      },
+      { deployedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    ).then((r2) => {
+      if (flags["json"]) console.log(JSON.stringify(r2.details, null, 2));
+      else console.log(r2.message);
+      process.exit(r2.ok ? 0 : 1);
+    });
+    return;
+  }
   let payload;
   try {
     payload = buildOp(args, flags);

package/extensions/thought-layer.ts

@@ -9,7 +9,7 @@ import {
   aggregateConfidence, statusFromConfidence, gradeFromConfidence,
   checkDomains, registrarSearchUrl,
   computeProjection, fmtMoney,
-  applyStateOp, runScaffold,
+  applyStateOp, runScaffold, runDeploy,
   type Assumptions, type StateOp,
 } from "../core/index.ts";
 
@@ -203,4 +203,34 @@ export default function (pi: ExtensionAPI) {
       return text(r.message, r.details);
     },
   });
+
+  // deploy: take the build output (read from build.json's publishDir) live to a
+  // user-owned URL. Two models, both keeping ownership with the user and nothing
+  // phoning a central account: a BYO Netlify token (NETLIFY_AUTH_TOKEN, deploys
+  // into their own account via the file-digest API) or, with no token, the
+  // Netlify CLI's own --allow-anonymous flow for a 1-hour claimable URL. The
+  // token is read ONLY from the environment (BYOK), never passed as a parameter.
+  pi.registerTool({
+    name: "deploy",
+    label: "Thought Layer: deploy",
+    description:
+      "Take the built site live to a user-owned URL. Reads build.json (publishDir/entry) next to the state file, then deploys to Netlify. " +
+      "Two models, both BYOK with no lock-in: with NETLIFY_AUTH_TOKEN set (read from the environment only, never a parameter) it deploys into the user's OWN account via the file-digest API (no zip); with no token it uses the Netlify CLI's --allow-anonymous flow for an instant live URL plus a one-hour claim link. " +
+      "Run the build first (thought-layer-build / tl_scaffold). Use dryRun:true to preview the file plan with no network call. Static-first: if build.json has hasBackend:true it warns that only the front end ships this way.",
+    parameters: Type.Object({
+      path: Type.Optional(Type.String({ description: "State file (or project dir) whose build.json to deploy. Defaults to ./.thought-layer/state.json; honors a named file." })),
+      dryRun: Type.Optional(Type.Boolean({ description: "Plan only: walk the publish dir and report the files + target, with no network call or CLI spawn." })),
+      anonymous: Type.Optional(Type.Boolean({ description: "Force the no-account path (Netlify CLI --allow-anonymous) even if a token is set. Default: token path when NETLIFY_AUTH_TOKEN is set, else anonymous." })),
+      siteName: Type.Optional(Type.String({ description: "Token path only: create the site under this name (a-z0-9-). Omit to let Netlify assign a random subdomain." })),
+      siteId: Type.Optional(Type.String({ description: "Token path only: re-deploy to an existing site id instead of creating a new one." })),
+    }),
+    async execute(_id, params): Promise<ToolResult> {
+      const p = params as { path?: string; dryRun?: boolean; anonymous?: boolean; siteName?: string; siteId?: string };
+      const r = await runDeploy(
+        { path: p.path, dryRun: p.dryRun, anonymous: p.anonymous, siteName: p.siteName, siteId: p.siteId },
+        { deployedAt: new Date().toISOString() },
+      );
+      return text(r.message, r.details);
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobocode/thought-layer",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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>",
@@ -66,6 +66,8 @@
     "core/state-ops.ts",
     "core/scaffold.ts",
     "core/scaffold-io.ts",
+    "core/deploy.ts",
+    "core/deploy-io.ts",
     "dist",
     "README.md",
     "LICENSE"

package/prompts/tl-deploy.md

@@ -0,0 +1,7 @@
+Apply the **thought-layer-deploy** skill. Take the built site live to a URL I own, with no lock-in.
+
+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.
+
+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

@@ -95,4 +95,4 @@ Write three files with your own file tools (the manifest is NOT a `tl_state` art
 
 ## Persisting
 
-The build output and the three files live on disk; the portable `state.json` stays focused on validation and design. The only optional state touch is a best-effort cursor bump - `tl_state cursor` (or `tl cursor`) with `{ "backboneStage": 15, "phase": "built" }` - pure provenance; if the tool is absent or it fails, the build still succeeded. Tell the user where the artifact is (`<publishDir>`) and that the next step is the deploy (Phase 4, `/tl-deploy`, coming) which reads `build.json`.
+The build output and the three files live on disk; the portable `state.json` stays focused on validation and design. The only optional state touch is a best-effort cursor bump - `tl_state cursor` (or `tl cursor`) with `{ "backboneStage": 15, "phase": "built" }` - pure provenance; if the tool is absent or it fails, the build still succeeded. Tell the user where the artifact is (`<publishDir>`) and that the next step is the deploy - the **thought-layer-deploy** skill (`/tl-deploy`) or the `deploy` tool / `tl deploy` CLI, which reads `build.json` and takes it live to a URL they own.

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

@@ -0,0 +1,51 @@
+---
+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."
+---
+
+# Deploy it: the build goes live to a URL you own
+
+This is the last step of the loop: rigor -> spec -> build -> **a live, owned URL**. You are not writing a deploy script by hand; you run the kit's deploy tool, which reads the build manifest and takes the publish directory live. BYOK, nothing phones a central account, no lock-in.
+
+## Precondition: a build must exist
+
+The deploy reads `.thought-layer/build.json` (written by the **thought-layer-build** skill or the **tl_scaffold** tool), co-located with the state file. Honor the same selection as the rest of the kit: an explicit `--path` / tool `path` wins, then `THOUGHT_LAYER_STATE`, then the default `.thought-layer/state.json`.
+
+- **Required:** a `build.json` with a `publishDir` that exists on disk. If it is missing, **stop** and point the user at `/tl-build` (full build) or the `tl_scaffold` tool (an instant deployable landing floor). Do not invent a publish dir.
+- `build.json.publishDir` + `entry` are load-bearing; `hasBackend` decides the static-only warning below.
+
+## How to run it
+
+Use the tool, never a hand-written `curl`/`netlify` invocation:
+- **Pi:** the `deploy` tool. Start with `deploy { dryRun: true }` to show the plan, then `deploy {}` to go live (add `anonymous: true` to force the no-account path, `siteId` to re-deploy to the same site).
+- **Any shell agent (Claude Code, CI, a plain terminal):** `tl deploy` (via `npx -y @hobocode/thought-layer tl deploy`). Use `--dry-run` first, then `tl deploy`. Flags: `--anonymous`, `--name <slug>`, `--site <id>`, `--path <file>`.
+
+Always **dry-run first** and show the user the file list and the target, then deploy.
+
+## The two models (both keep ownership with the user)
+
+The tool picks automatically; explain which one ran.
+
+- **BYO token (the default when `NETLIFY_AUTH_TOKEN` is set).** Deploys straight into the user's own Netlify account via the file-digest API (no zip, no extra dependency). The site is theirs from the first second - **no claim step**. Re-deploy to the same site with `--site <id>` (the id is in the deploy output and `deploy.json`). The token is read **only from the environment** - never ask the user to paste it into the chat, and never put it in a tool parameter or a file.
+- **Netlify CLI (when no token is set).** Delegates to the user's installed Netlify CLI, and branches on the CLI's own login state (a logged-in CLI ignores `--allow-anonymous`, so the tool checks):
+  - **logged in** -> creates a new site in the user's own account (`--create-site`, owned immediately, **no claim**), or re-deploys to `--site <id>`.
+  - **logged out** -> an **anonymous, claimable** site (`--allow-anonymous`) with a **one-hour claim link** that transfers ownership to whatever account the user logs into. We never reverse-engineer that handshake; it needs a current CLI (`npm i -g netlify-cli@latest`; the flag shipped 2026-03).
+
+If neither a token nor a usable CLI is available, relay the tool's guidance honestly (set a token, install/update the CLI, or drag the publish dir onto https://app.netlify.com/drop) instead of pretending it deployed. If the user explicitly asked for an anonymous deploy but the CLI is logged in, the tool says it went to their account instead and that `netlify logout` first would make it anonymous - pass that on.
+
+## 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.
+
+## After it is live
+
+Report, plainly:
+- the **live URL**, and (anonymous only) the **claim link** with the one-hour window called out;
+- for the token path, that it is already owned by their account and how to re-deploy (`--site <id>`);
+- that a `.thought-layer/deploy.json` record was written (URL, mode, site/deploy ids) next to `build.json`.
+
+If the tool returned `ok: false`, do not claim success - surface its message (the next honest step) verbatim.
+
+## Persisting
+
+The deploy is a real-world side effect, not validation state, so it lives in `deploy.json` on disk, not in the portable `state.json`. The only optional state touch is a best-effort cursor bump - `tl_state cursor` (or `tl cursor`) with `{ "phase": "deployed" }` - pure provenance; if it fails, the deploy still happened.