@codewithjuber/forgekit 0.8.0

package/src/uivisual.js

@@ -0,0 +1,334 @@
+// forge uicheck visual — the Playwright visual loop (P6 §5,
+// docs/plans/substrate-v2/07-ui-quality-gate.md). The static fingerprint parses
+// SOURCE CSS/classes; it cannot see rendered reality — cascade results, computed
+// values, runtime theming. This module renders the page in a real browser (when one
+// is available) and feeds the COMPUTED styles of every visible element through the
+// SAME fingerprint pipeline as `uicheck design`, so the two gates share one geometry.
+//
+// ADR-0005 discipline: playwright is an OPTIONAL tier. package.json stays
+// dependency-free; the module resolves playwright-core/playwright dynamically (or an
+// explicit FORGE_PLAYWRIGHT module path) and degrades to a clear "skipped" note —
+// absence is never a crash and never a gate failure.
+//
+// Security: a CLI that fetches arbitrary URLs by default is an exfiltration hazard
+// (a hook could be steered into beaconing repo contents via a crafted URL). http(s)
+// targets are therefore refused unless the host is loopback — `--remote` is the
+// explicit human override.
+import { existsSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { BRAND } from "./brand.js";
+import {
+  activeTasteStyle,
+  fingerprintText,
+  loadProjectFingerprint,
+  loadTasteProfile,
+  profileChecks,
+  scaleChecks,
+  UI_GATE_DEFAULTS,
+  uiGate,
+} from "./uifingerprint.js";
+
+// ---------------------------------------------------------------------------
+// Optional-tier resolution — dynamic, never a package.json dependency.
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a playwright runtime: FORGE_PLAYWRIGHT (an explicit module path or bare
+ * name — how tests and scratch installs point at an out-of-tree copy) wins and is
+ * authoritative when set; otherwise try `playwright-core` then `playwright`. Returns
+ * the module (something with `.chromium.launch`) or null — never throws. Browser
+ * binaries follow playwright's own PLAYWRIGHT_BROWSERS_PATH handling.
+ * @returns {Promise<{chromium:{launch:Function}}|null>}
+ */
+export async function resolvePlaywright() {
+  const explicit = process.env.FORGE_PLAYWRIGHT;
+  const candidates = explicit ? [explicit] : ["playwright-core", "playwright"];
+  for (const spec of candidates) {
+    try {
+      let entry = spec;
+      if (spec.includes("/") || spec.includes("\\")) {
+        // A path (to the package dir or its entry file): resolve through require's
+        // algorithm so a directory's package.json "main" is honored, then import as
+        // a file URL (playwright ships CJS; the default export is module.exports).
+        entry = pathToFileURL(
+          createRequire(import.meta.url).resolve(isAbsolute(spec) ? spec : resolve(spec)),
+        ).href;
+      }
+      const mod = await import(entry);
+      const pw = mod?.default?.chromium ? mod.default : mod;
+      if (typeof pw?.chromium?.launch === "function") return pw;
+    } catch {}
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Target resolution — the security guard lives here, BEFORE any browser exists.
+// ---------------------------------------------------------------------------
+
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1", "0.0.0.0"]);
+const isLoopbackHost = (host) =>
+  LOOPBACK.has(host) ||
+  host.endsWith(".localhost") ||
+  /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+
+/**
+ * Normalize a CLI target to a navigable URL. Local paths become file:// URLs;
+ * http(s) URLs are allowed only for loopback hosts unless `remote` is set — the
+ * refusal is the default so no hook or agent can quietly point the gate at the
+ * network. Never throws.
+ * @param {string} target
+ * @param {{remote?:boolean, cwd?:string}} [opts]
+ * @returns {{ok:true, url:string}|{ok:false, reason:string}}
+ */
+export function resolveTarget(target, { remote = false, cwd = process.cwd() } = {}) {
+  const t = String(target ?? "").trim();
+  if (!t) return { ok: false, reason: "no target given" };
+  if (/^https?:\/\//i.test(t)) {
+    let u;
+    try {
+      u = new URL(t);
+    } catch {
+      return { ok: false, reason: `unparseable URL: ${t}` };
+    }
+    if (!remote && !isLoopbackHost(u.hostname))
+      return {
+        ok: false,
+        reason: `refusing non-local URL ${u.origin} — fetching arbitrary URLs by default is an exfiltration hazard; pass --remote to override deliberately`,
+      };
+    return { ok: true, url: u.href };
+  }
+  if (/^file:\/\//i.test(t)) return { ok: true, url: t };
+  if (/^[a-z][a-z0-9+.-]*:/i.test(t))
+    return { ok: false, reason: `unsupported URL scheme: ${t} (use a file path or http(s))` };
+  const p = isAbsolute(t) ? t : join(cwd, t);
+  if (!existsSync(p)) return { ok: false, reason: `no such file: ${t}` };
+  return { ok: true, url: pathToFileURL(p).href };
+}
+
+// ---------------------------------------------------------------------------
+// Computed styles → the shared fingerprint vector.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{color?:string, backgroundColor?:string, margin?:string, padding?:string,
+ *   gap?:string, fontFamily?:string, borderRadius?:string, boxShadow?:string}} ComputedRecord
+ */
+
+// Runs INSIDE the page (a string so the repo typechecks without DOM lib types):
+// walk visible elements and lift exactly the computed properties the fingerprint
+// measures. Values arrive fully resolved — the cascade, var() indirection, and
+// runtime theming have already happened, which is the whole point of the loop.
+// Two artifact classes must NOT leak into the vector, because they are layout
+// residue rather than authored design decisions:
+//   - `margin: auto` — getComputedStyle returns the USED value (a centered 1180px
+//     container at 1280 reports "0px 50px"), so margins go through the Typed OM
+//     (computedStyleMap), which keeps `auto` symbolic; auto sides are dropped.
+//   - elements the page never painted (e.g. <option> inside a closed <select>)
+//     still carry UA-stylesheet paddings — zero client rects filters them out.
+const EXTRACT_JS = `(() => {
+  const out = [];
+  const SIDES = ["top", "right", "bottom", "left"];
+  for (const el of document.querySelectorAll("body, body *")) {
+    const tag = el.tagName;
+    if (tag === "SCRIPT" || tag === "STYLE" || tag === "TEMPLATE" || tag === "NOSCRIPT") continue;
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden") continue;
+    if (el.getClientRects().length === 0) continue; // never painted → UA noise only
+    let margin = cs.margin;
+    if (el.computedStyleMap) {
+      const map = el.computedStyleMap();
+      margin = SIDES.map((s) => String(map.get("margin-" + s)))
+        .filter((v) => v !== "auto")
+        .join(" ");
+    }
+    out.push({
+      color: cs.color,
+      backgroundColor: cs.backgroundColor,
+      margin,
+      padding: cs.padding,
+      gap: cs.gap,
+      fontFamily: cs.fontFamily,
+      borderRadius: cs.borderRadius,
+      boxShadow: cs.boxShadow,
+    });
+  }
+  return out;
+})()`;
+
+// Fully transparent computed colors ("rgba(0, 0, 0, 0)" — every unset background)
+// carry no design decision and must not vote black into the palette.
+const TRANSPARENT_RE = /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0\s*\)$/;
+
+/**
+ * Serialize computed-style records into synthetic CSS text with the exact property
+ * spellings fingerprintText's extractors match — the rendered path reuses the SAME
+ * parser/vector as the static path instead of duplicating its math. Identical
+ * records collapse to one block (dedup is cosmetic: the fingerprint already
+ * uniquifies, this just bounds the text).
+ * @param {ComputedRecord[]} records
+ * @returns {string}
+ */
+export function computedStylesToCss(records) {
+  const seen = new Set();
+  const blocks = [];
+  for (const r of records ?? []) {
+    const decls = [];
+    const push = (prop, v) => {
+      const s = String(v ?? "").trim();
+      if (!s || s === "none" || s === "auto" || /^normal\b/.test(s) || TRANSPARENT_RE.test(s))
+        return;
+      decls.push(`${prop}: ${s}`);
+    };
+    push("color", r.color);
+    push("background-color", r.backgroundColor);
+    push("margin", r.margin);
+    push("padding", r.padding);
+    push("gap", r.gap);
+    push("font-family", r.fontFamily);
+    push("border-radius", r.borderRadius);
+    push("box-shadow", r.boxShadow);
+    if (!decls.length) continue;
+    const block = `x { ${decls.join("; ")}; }`;
+    if (!seen.has(block)) {
+      seen.add(block);
+      blocks.push(block);
+    }
+  }
+  return blocks.join("\n");
+}
+
+/** file targets → basename sans extension; URLs → host+path; always [a-z0-9-]. */
+function targetSlug(url) {
+  const u = new URL(url);
+  const base =
+    u.protocol === "file:"
+      ? (u.pathname.split("/").pop() || "page").replace(/\.[^.]+$/, "")
+      : `${u.hostname}${u.pathname}`;
+  return (
+    base
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "page"
+  );
+}
+
+/** The two spec viewports: desktop + phone (§5: "2 viewports"). */
+export const DEFAULT_VIEWPORTS = [
+  [1280, 800],
+  [390, 844],
+];
+
+/**
+ * Render `target` headless at each viewport, fingerprint the computed styles of all
+ * visible elements (one vector across viewports — a design system is one system),
+ * and save a screenshot per viewport under `.forge/ui/`.
+ * @param {string} target file path, file:// URL, or (loopback) http(s) URL
+ * @param {{viewports?:number[][], timeoutMs?:number, remote?:boolean, root?:string,
+ *   pw?:{chromium:{launch:Function}}|null}} [opts]
+ * @returns {Promise<{ok:true, url:string, fingerprint:import("./uifingerprint.js").Fingerprint,
+ *   screenshots:string[], elements:number}|{ok:false, skipped?:boolean, reason:string}>}
+ */
+export async function renderedFingerprint(target, opts = {}) {
+  const {
+    viewports = DEFAULT_VIEWPORTS,
+    timeoutMs = 15000,
+    remote = false,
+    root = process.cwd(),
+    pw = null,
+  } = opts;
+  const t = resolveTarget(target, { remote, cwd: root });
+  if (!t.ok) return { ok: false, reason: "reason" in t ? t.reason : "bad target" };
+  const playwright = pw ?? (await resolvePlaywright());
+  if (!playwright)
+    return {
+      ok: false,
+      skipped: true,
+      reason: "playwright is not installed (optional tier, ADR-0005)",
+    };
+  let browser;
+  try {
+    browser = await playwright.chromium.launch({ headless: true });
+  } catch (err) {
+    // Installed module but no usable browser binary — same graceful-absence class.
+    return { ok: false, skipped: true, reason: `browser launch failed: ${err.message}` };
+  }
+  try {
+    const outDir = join(root, ".forge", "ui");
+    mkdirSync(outDir, { recursive: true });
+    const slug = targetSlug(t.url);
+    /** @type {ComputedRecord[]} */
+    const records = [];
+    const screenshots = [];
+    for (const [width, height] of viewports) {
+      const page = await browser.newPage({ viewport: { width, height } });
+      await page.goto(t.url, { timeout: timeoutMs, waitUntil: "load" });
+      records.push(...(await page.evaluate(EXTRACT_JS)));
+      const shot = join(outDir, `${slug}-${width}x${height}.png`);
+      await page.screenshot({ path: shot });
+      screenshots.push(shot);
+      await page.close();
+    }
+    const fingerprint = fingerprintText(computedStylesToCss(records));
+    return { ok: true, url: t.url, fingerprint, screenshots, elements: records.length };
+  } catch (err) {
+    return { ok: false, reason: `render failed: ${err.message}` };
+  } finally {
+    await browser.close().catch(() => {});
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The gate — rendered fingerprint through the SAME pipeline as `uicheck design`.
+// ---------------------------------------------------------------------------
+
+/**
+ * Render, fingerprint, and gate: uiGate (slop + conformance vs the ledger's project
+ * fingerprint) + scaleChecks + taste-profile checks — identical semantics to
+ * `uicheck design`, applied to what the browser actually painted.
+ * @param {string} target
+ * @param {{taste?:string|null, remote?:boolean, root?:string, viewports?:number[][],
+ *   timeoutMs?:number, pw?:{chromium:{launch:Function}}|null}} [opts]
+ *   `taste` is the EXPLICIT profile name (unknown → error, like `design --taste`);
+ *   when omitted, a `forge taste`-managed DESIGN.md style is picked up automatically.
+ * @returns {Promise<{ok:false, skipped?:boolean, reason:string}|{ok:true, fail:boolean,
+ *   pass:boolean, slop:number, conform:number|null, violations:object[], checks:object[],
+ *   fingerprint:object, screenshots:string[], elements:number, url:string,
+ *   hasProjectFingerprint:boolean, taste:string|null, tauSlop:number, tauConform:number}>}
+ */
+export async function visualGate(target, opts = {}) {
+  const { taste = null, root = process.cwd() } = opts;
+  const tasteName = taste ?? activeTasteStyle(root);
+  const profile = tasteName ? loadTasteProfile(tasteName) : null;
+  if (taste && !profile)
+    return {
+      ok: false,
+      reason: `unknown taste profile "${taste}" — run \`${BRAND.cli} taste\` to list styles`,
+    };
+  const r = await renderedFingerprint(target, { ...opts, root });
+  if (!r.ok) return /** @type {{ok:false, skipped?:boolean, reason:string}} */ (r);
+  const projectFp = loadProjectFingerprint(root);
+  const tauSlop = profile?.gate?.tau_slop ?? UI_GATE_DEFAULTS.tauSlop;
+  const tauConform = profile?.gate?.tau_conform ?? UI_GATE_DEFAULTS.tauConform;
+  const gate = uiGate(r.fingerprint, { projectFp, tauSlop, tauConform });
+  const checks = [
+    ...scaleChecks(r.fingerprint),
+    ...(profile ? profileChecks(r.fingerprint, profile) : []),
+  ];
+  return {
+    ok: true,
+    fail: !gate.pass || checks.some((c) => !c.pass),
+    ...gate,
+    checks,
+    fingerprint: r.fingerprint,
+    screenshots: r.screenshots,
+    elements: r.elements,
+    url: r.url,
+    hasProjectFingerprint: !!projectFp,
+    taste: profile ? tasteName : null,
+    tauSlop,
+    tauConform,
+  };
+}

package/src/util.js

@@ -0,0 +1,71 @@
+// forge util — shared micro-utilities. Extracted from duplicated copies across
+// cortex.js, recall.js, cortex_hook.js, doctor.js, harden.js, route.js, adjudicate.js,
+// scope.js, atlas.js, preflight.js, and cortex_hook_main.js.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+
+export const slug = (s) =>
+  String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+
+export const clamp01 = (x) => Math.max(0, Math.min(1, x));
+
+export const MS_PER_DAY = 86400000;
+export const epochDay = () => Math.floor(Date.now() / MS_PER_DAY);
+
+export function hasBin(bin) {
+  try {
+    execFileSync(bin, ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function contentHash(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+let cachedAuthor;
+/** The identity stamped on ledger provenance/evidence — FORGE_AUTHOR env override,
+ *  else the git identity, else "" (attribution is best-effort, never a hard fail).
+ *  Cached per process: hooks call this per event and `git config` is a subprocess. */
+export function gitAuthor() {
+  if (process.env.FORGE_AUTHOR !== undefined) return process.env.FORGE_AUTHOR;
+  if (cachedAuthor !== undefined) return cachedAuthor;
+  try {
+    const get = (k) =>
+      execFileSync("git", ["config", "--get", k], { stdio: ["ignore", "pipe", "ignore"] })
+        .toString()
+        .trim();
+    const name = get("user.name");
+    const email = get("user.email");
+    cachedAuthor = email ? `${name} <${email}>` : name;
+  } catch {
+    cachedAuthor = "";
+  }
+  return cachedAuthor;
+}
+
+export const IGNORE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  "out",
+  "target",
+  "__pycache__",
+  ".forge",
+  "coverage",
+  ".venv",
+  "vendor",
+]);
+
+export const SRC_EXT = /\.(js|jsx|ts|tsx|mjs|cjs|py)$/;
+
+export const CODE_EXT =
+  /\.(js|ts|jsx|tsx|mjs|cjs|py|go|rs|java|rb|php|c|cc|cpp|h|hpp|cs|json|ya?ml|toml|md|css|scss|html|vue|svelte)$/i;

package/src/verify.js

@@ -0,0 +1,117 @@
+// forge verify — the independent verification layer. Deterministic-first and
+// cross-tool: it trusts the project's OWN tests (never a benchmark number) and
+// reuses `atlas` to flag calls to symbols that exist nowhere in the codebase
+// (a cheap, zero-LLM hallucination signal). It emits a provenance stamp so a
+// reviewer reads WHAT was checked, not the authoring transcript.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { build as buildAtlas, has, isStale, load as loadAtlas } from "./atlas.js";
+
+// Shared call-site extractor — one source of truth with atlas.js (they used to duplicate this).
+export { extractCalledSymbols } from "./extract.js";
+
+import { extractCalledSymbols } from "./extract.js";
+
+/** Pure: which called symbols are defined nowhere in the atlas (possible hallucinations). */
+export function findUnknownSymbols(atlas, symbols) {
+  return symbols.filter((s) => !has(atlas, s));
+}
+
+function git(args, cwd) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8" });
+  } catch (err) {
+    if (process.env.FORGE_DEBUG === "1")
+      process.stderr.write(`forge verify git: ${err?.message ?? err}\n`);
+    return "";
+  }
+}
+
+// Run the project's own tests (JS or Python). The gate trusts these, not a benchmark. Bounded by
+// a timeout (FORGE_VERIFY_TIMEOUT_MS, default 10 min) so a hanging test can't hang the gate — a
+// timeout is reported as an honest "did not complete", never as a pass.
+function runTests(cwd) {
+  const timeout = Number(process.env.FORGE_VERIFY_TIMEOUT_MS) || 600000;
+  const run = (cmd, args) =>
+    execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: "pipe", timeout });
+  try {
+    if (existsSync(join(cwd, "package.json"))) {
+      run("npm", ["test"]);
+      return { ran: true, passed: true, runner: "npm test" };
+    }
+    if (existsSync(join(cwd, "pyproject.toml")) || existsSync(join(cwd, "pytest.ini"))) {
+      run("pytest", ["-q"]);
+      return { ran: true, passed: true, runner: "pytest" };
+    }
+    return { ran: false };
+  } catch (e) {
+    if (e.code === "ETIMEDOUT" || e.signal === "SIGTERM") {
+      return { ran: true, passed: false, timedOut: true, output: `test run exceeded ${timeout}ms` };
+    }
+    return {
+      ran: true,
+      passed: false,
+      output: String(e.stdout || e.message || "").slice(-600),
+    };
+  }
+}
+
+/**
+ * M6 — checkpoint cadence as an optimal-stopping threshold rule (spec §6:
+ * docs/plans/substrate-v2/06-faculties-and-mechanisms.md). Insert a checkpoint once
+ * the expected loss of continuing-while-wrong exceeds the check's price:
+ * pErr·tokensPerStep·costPerToken·n > checkCost, i.e. check every
+ * n* = ⌈checkCost / (pErr · tokensPerStep · costPerToken)⌉ meaningful steps. No
+ * magic constants: pErr is measured per tier from ledger outcome history, the costs
+ * are priced — riskier/cheaper tiers get smaller n* automatically. Clamped to
+ * [1, 50]: even a near-free check shouldn't fire more than every step, and even a
+ * near-riskless run must still checkpoint eventually. Pure.
+ * @param {{pErr: number, tokensPerStep: number, costPerToken?: number, checkCost: number}} f
+ *   pErr = per-step error hazard; tokensPerStep = tokens put at risk per step;
+ *   checkCost priced in the same token-cost unit.
+ * @returns {number} integer steps between checkpoints, in [1, 50]
+ */
+export function checkpointCadence({ pErr, tokensPerStep, costPerToken = 1, checkCost }) {
+  const n = Math.ceil(checkCost / (pErr * tokensPerStep * costPerToken));
+  // Degenerate inputs (NaN from bad measurements) fail SAFE: check every step.
+  if (Number.isNaN(n)) return 1;
+  return Math.min(50, Math.max(1, n)); // zero risk → Infinity → the 50-step ceiling
+}
+
+export function verify({ targetRoot = process.cwd(), base = "HEAD" } = {}) {
+  const diff =
+    git(["diff", "--unified=0", base], targetRoot) ||
+    git(["diff", "--unified=0", "--cached"], targetRoot);
+  const added = diff
+    .split("\n")
+    .filter((l) => l.startsWith("+") && !l.startsWith("+++"))
+    .map((l) => l.slice(1))
+    .join("\n");
+  const changedFiles = git(["diff", "--name-only", base], targetRoot).split("\n").filter(Boolean);
+
+  // Verify runs AFTER edits — a cached, stale atlas would miss newly-added-but-undefined symbols
+  // (false negatives) or flag just-defined ones (false positives). Rebuild when stale; the
+  // incremental build only re-parses the files that changed, so this stays cheap.
+  const cached = loadAtlas(targetRoot);
+  const atlas = cached && !isStale(targetRoot, cached) ? cached : buildAtlas({ root: targetRoot });
+  const symbols = extractCalledSymbols(added);
+  // When the graph was capped (huge repo, files dropped), "defined nowhere" is unreliable — a
+  // symbol may live in a dropped file — so don't assert hallucinations.
+  const unknown = atlas.capped ? [] : findUnknownSymbols(atlas, symbols);
+  const tests = runTests(targetRoot);
+
+  const provenance = {
+    base,
+    changedFiles,
+    tests,
+    symbolsChecked: symbols.length,
+    unknownSymbols: unknown,
+  };
+  mkdirSync(join(targetRoot, ".forge"), { recursive: true });
+  writeFileSync(join(targetRoot, ".forge", "provenance.json"), JSON.stringify(provenance, null, 2));
+
+  // Hard gate = the project's own tests. Unknown symbols are advisory (heuristic).
+  const ok = tests.ran ? tests.passed === true : true;
+  return { ok, provenance, unknown, tests, changedFiles };
+}

package/templates/project-layer/.claude/settings.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(npm run dev)",
+      "Bash(npm run migrate:status)",
+      "Bash(psql:* -c \\\"SELECT*)"
+    ],
+    "ask": [
+      "Bash(npm run migrate:*)",
+      "Bash(psql:*)",
+      "Bash(docker compose:*)",
+      "Bash(ssh:*)"
+    ],
+    "deny": [
+      "Read(./widget/keys/**)",
+      "Bash(psql:* DROP *)",
+      "Bash(psql:* TRUNCATE *)",
+      "Bash(psql:* DELETE FROM *)"
+    ]
+  }
+}

package/templates/project-layer/.claude/skills/hostlelo-deploy/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: hostlelo-deploy
+description: Safe, staged deploy of Hostlelo services to the VPS. Use when asked to deploy, ship, or release a Hostlelo change (kernel, widget, or Telegram control plane).
+disable-model-invocation: true
+---
+
+# Hostlelo deploy
+
+Staged deploy with a check at each gate. Never skip verification. Never deploy
+with a failing build or uncommitted secrets.
+
+## Preflight
+1. `git status` — clean tree, no `.env`/keys staged.
+2. Run tests + typecheck + build locally; abort on any failure.
+3. Confirm target: kernel box vs Hermes vs widget/CDN. Confirm branch.
+4. If DB schema changed: review the migration, confirm it's reversible, and get
+   explicit user OK before running it against prod.
+
+## Deploy
+5. Push to the deploy branch / trigger the pipeline (use `gh`/CLI, not manual
+   clicks). Prefer the project's existing deploy script over ad-hoc commands.
+6. Apply migrations in order; capture output.
+
+## Verify (required)
+7. Health check the service (HTTP 200 / expected response) via the public URL
+   behind Cloudflare.
+8. Smoke test the changed surface:
+   - Widget: load `widget.js`, confirm a grounded price answer, confirm no
+     hallucinated numbers.
+   - Telegram: one command round-trips.
+9. Report: what deployed, migration result, health/smoke evidence, and the
+   rollback command if it needs reverting.
+
+## Rollback
+State the exact revert (previous release/tag or `git revert`) before finishing so
+it's one step away if something regresses.
+
+<!-- Replace bracketed bits with real host targets/scripts; keep secrets out. -->

package/templates/project-layer/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md — <project>
+
+Cross-tool rules (read by Codex, Cursor, Copilot, Gemini, Aider, Zed, and by
+Claude Code when CLAUDE.md points here). Keep tool-agnostic and thin.
+
+## Stack
+<!-- e.g. Next.js 16 (App Router) · TypeScript · Node · Postgres+pgvector · OpenRouter -->
+
+## Commands
+- Install: `npm ci`
+- Dev: `npm run dev`
+- Test / typecheck / lint: `npm test` · `npm run typecheck` · `npm run lint`
+- Build: `npm run build`
+- DB migrate: `<command>`
+
+## Rules
+- Reuse existing components/utils before writing new; smallest change that works.
+- Verify the current best library from live sources before adding a dependency;
+  prefer what the project already uses.
+- Wrap fallible async in try/catch; guard array/object access; explicit errors.
+- UI: build + check mobile AND desktop; clear loading/empty/error states; follow
+  `DESIGN.md` if present.
+- Verify before "done": run tests/build/lint and show output; screenshot UI.
+- Never commit secrets or `.env*`; never run destructive DB/FS commands without
+  confirmation.
+
+## References
+- Visual rules: @DESIGN.md (if present)

package/templates/project-layer/CLAUDE.md

@@ -0,0 +1,40 @@
+# Hostlelo — project instructions
+
+Drop this into a Hostlelo repo root. Adds project context on top of the global
+`~/.claude/CLAUDE.md`. Keep it lean; prune anything Claude gets right without it.
+
+Shared cross-tool rules (stack, commands, engineering rules) live in **@AGENTS.md**
+so Cursor/Codex/Gemini read the same source. This file holds only Claude-specific
++ Hostlelo-specific bits. Keep CLAUDE.md thin; put general rules in AGENTS.md.
+
+## Stack
+- Runtime: Node.js. DB: self-hosted Postgres (18+) with **pgvector** on the VPS.
+- LLM: routed through **OpenRouter** — never hardcode a single provider; use the
+  configured routing/env, and pick cheap models for classify/embed, stronger
+  models only for hard generation.
+- Delivery surfaces: customer AI **chat widget** (`widget.js`) and **Telegram**
+  owner control plane. Infra: Linode VPS + Cloudflare Tunnel/Access.
+
+## Non-negotiables
+- **Grounding-first.** Customer-facing answers (esp. prices/plans) must come from
+  the verified KB, never guessed. If unverified, say so or defer — do not invent
+  numbers, features, or availability.
+- **Secrets** live in env / the secrets store, never in code, logs, or commits.
+  `.env*` and key files are hook-protected — don't work around it.
+- Neutral, worldwide tone in customer replies (no forced regional greeting).
+
+## Workflow
+- Prefer readymade, well-maintained OSS libraries/SDKs over hand-rolled code —
+  it's faster and cheaper to run. Justify any new dependency briefly.
+- Before DB or deploy changes: read the migration/deploy path first; never run
+  destructive SQL (`DROP`/`TRUNCATE`) or touch prod without explicit confirmation.
+- Verify every change: run the app's tests/typecheck/build and show output.
+- Deploy via the `hostlelo-deploy` skill (safe, staged, with rollback notes).
+
+## Commands
+<!-- Fill these in from package.json so Claude doesn't guess: -->
+- Install: `npm ci`
+- Dev: `npm run dev`
+- Test / typecheck / lint: `npm test` · `npm run typecheck` · `npm run lint`
+- Build: `npm run build`
+- DB migrate: `<your migrate command>`