constellai 0.3.0

package/scripts/publish-public.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Push the CLEAN, COMPILED-distribution tree to the PUBLIC repo (`public` remote = gabriel7silva/constella).
+ *
+ * The public repo ships the *product*, not the source: docs, the launcher (bin/), runtime scripts,
+ * the native skills library, config, and the generated DB migrations (drizzle/) — but **NO `src/`**
+ * and **no committed build** (the compiled `.next` reaches users through the npm tarball, not git).
+ * This script builds that filtered tree in a temporary git index, secret-scans exactly what it will
+ * publish, and REFUSES on any finding. It never runs automatically.
+ *
+ *   node scripts/publish-public.mjs            # scan only (dry run)
+ *   node scripts/publish-public.mjs --push     # scan, then force-push the clean tree to `public main`
+ */
+import { execSync } from "node:child_process";
+import { readFileSync, statSync, mkdtempSync, existsSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PUSH = process.argv.includes("--push");
+
+// Tracked paths that must NEVER reach the public repo (the whole point: no source, no test config).
+const EXCLUDE = ["src", "playwright.config.ts", "e2e", "tests"];
+
+// Mirror of src/server/git-scan.ts — sensitive filenames + high-confidence inline secret patterns.
+const SENSITIVE_FILE = /(^|\/)(\.env(\.[\w.-]+)?|id_[rd]sa\w*|.*\.(pem|key|p12|pfx|keystore|jks|ppk|asc)|credentials?\.json|service[-_]?account[\w.-]*\.json|.*\.(sql|dump|bak|sqlite3?|db)|npm-debug\.log|.*\.local)$/i;
+const ALLOW_FILE = /(\.env\.(example|sample|template|dist)|\.env-example)$/i;
+// Legit source that the SENSITIVE_FILE regex over-matches: Drizzle migrations are DDL, not DB dumps.
+const ALLOW_PATH = /^drizzle\/.*\.sql$/i;
+// Obvious placeholder credentials in doc/example connection strings — not real secrets.
+const PLACEHOLDER = /^(user|username|admin|root|pass|password|pwd|secret|example|changeme|x{3,}|your|host|localhost|db|name|app|<)/i;
+const SECRETS = [
+  ["AWS access key", /\bAKIA[0-9A-Z]{16}\b/],
+  ["GitHub token", /\bgh[posru]_[A-Za-z0-9]{30,}\b/],
+  ["GitHub fine-grained PAT", /\bgithub_pat_[A-Za-z0-9_]{40,}\b/],
+  ["OpenAI/Anthropic key", /\bsk-[A-Za-z0-9_-]{20,}\b/],
+  ["Google API key", /\bAIza[0-9A-Za-z_-]{30,}\b/],
+  ["Slack token", /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/],
+  ["Private key block", /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/],
+  ["JWT", /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{6,}\b/],
+  // DB URL with creds — only flag when the user:pass aren't obvious placeholders.
+  ["DB URL with creds", /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp):\/\/([^\s:@/]+):([^\s:@/]+)@/, (m) => !PLACEHOLDER.test(m[1]) && !PLACEHOLDER.test(m[2])],
+  ["Telegram bot token", /\b\d{6,}:[A-Za-z0-9_-]{35,}\b/],
+];
+const TEXT = /\.(m?[jt]sx?|json|md|css|ya?ml|toml|sh|env|txt|html?)$/i;
+
+const isExcluded = (f) => EXCLUDE.some((p) => f === p || f.startsWith(p + "/"));
+
+// 1) Ensure the generated migrations exist (the public repo ships them; they build a fresh end-user
+//    DB via `drizzle-kit migrate`). Generated from src/db/schema.ts, which exists in this dev tree.
+if (!existsSync("drizzle") || readdirSync("drizzle").filter((f) => f.endsWith(".sql")).length === 0) {
+  console.log("• Generating DB migrations (drizzle/) from the schema…");
+  execSync("npx drizzle-kit generate --config drizzle.config.mjs", { stdio: "inherit" });
+}
+
+// 2) Compute exactly the file list that will be published: tracked files minus EXCLUDE, plus the
+//    on-disk drizzle/ migrations (gitignored in this dev repo, force-added to the public tree).
+const tracked = execSync("git ls-files", { encoding: "utf8" }).split("\n").map((s) => s.trim()).filter(Boolean);
+// drizzle/ is gitignored in the dev repo, so list it straight off disk (cross-platform fs walk) — these
+// generated migrations are force-added into the public tree below.
+function walkDir(dir) {
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = `${dir}/${e.name}`;
+    if (e.isDirectory()) out.push(...walkDir(p));
+    else out.push(p);
+  }
+  return out;
+}
+const drizzleFiles = existsSync("drizzle") ? walkDir("drizzle") : [];
+const publishFiles = [...new Set([...tracked.filter((f) => !isExcluded(f)), ...drizzleFiles])];
+
+// 3) Secret-scan exactly that set.
+const findings = [];
+for (const f of publishFiles) {
+  if (SENSITIVE_FILE.test(f) && !ALLOW_FILE.test(f) && !ALLOW_PATH.test(f)) { findings.push(`${f}: sensitive file`); continue; }
+  if (!TEXT.test(f)) continue;
+  let body;
+  try { if (statSync(f).size > 512 * 1024) continue; body = readFileSync(f, "utf8"); } catch { continue; }
+  for (const [name, re, valid] of SECRETS) {
+    const m = body.match(re);
+    if (m && (!valid || valid(m))) { findings.push(`${f}: ${name}`); break; }
+  }
+}
+// Belt-and-suspenders: make sure no src/ slipped into the publish set.
+const leaked = publishFiles.filter((f) => f === "src" || f.startsWith("src/"));
+if (leaked.length) findings.push(`src/ leaked into the public tree (${leaked.length} file(s)) — aborting`);
+
+if (findings.length) {
+  console.error(`\n✖ Refusing to publish — ${findings.length} potential secret/sensitive/source finding(s):`);
+  for (const x of findings.slice(0, 30)) console.error("  - " + x);
+  process.exit(1);
+}
+console.log(`✓ Clean: ${publishFiles.length} files to publish (no src/, no secrets). Migrations: ${publishFiles.filter((f) => f.startsWith("drizzle/")).length} file(s).`);
+
+if (!PUSH) {
+  console.log("\nDry run. To publish the clean compiled tree to the public repo, run:");
+  console.log("  node scripts/publish-public.mjs --push");
+  process.exit(0);
+}
+
+// 4) Build the filtered tree in a TEMP git index (HEAD minus EXCLUDE, plus drizzle/), then push it
+//    as a fresh root commit. Force-push = the public repo is a clean mirror, not a shared history.
+console.log("\nStaging the clean public tree…");
+const TMP_INDEX = join(mkdtempSync(join(tmpdir(), "constella-public-")), "index");
+const env = { ...process.env, GIT_INDEX_FILE: TMP_INDEX, GIT_TERMINAL_PROMPT: "0" };
+execSync("git read-tree HEAD", { env, stdio: "inherit" });
+for (const p of EXCLUDE) execSync(`git rm -r --cached --ignore-unmatch -- "${p}"`, { env, stdio: "ignore" });
+if (existsSync("drizzle")) execSync("git add -f -- drizzle", { env, stdio: "inherit" });
+const tree = execSync("git write-tree", { env }).toString().trim();
+const commit = execSync(`git commit-tree ${tree} -m "Constella — compiled distribution (docs, launcher, migrations; no source)"`, { env }).toString().trim();
+
+console.log(`Pushing clean tree (${commit.slice(0, 9)}) to \`public\` (gabriel7silva/constella)…`);
+// Fully-qualify the destination ref: pushing a bare commit object to `main` fails on an empty remote
+// (git can't guess the ref). `refs/heads/main` creates/overwrites the branch deterministically.
+execSync(`git push -f public ${commit}:refs/heads/main`, { stdio: "inherit", env });
+console.log("✓ Pushed. The npm tarball (with the prebuilt .next) is published separately via `npm publish`.");

package/scripts/smoke-login.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Pre-publish smoke gate for the client runtime.
+ *
+ * The published 0.2.15 shipped an inconsistent `.next` artifact (incremental build over a stale
+ * `.next/server` + `.next/static` under OneDrive) whose RSC/manifest referenced client-chunk state the emitted
+ * static chunks didn't match. It looked fine on the server (HTML/chunks all 200) but crashed at HYDRATION with
+ * "invariant expected layout router to be mounted" → the root "Something broke at the root" page. A server-side
+ * check (curl) can't catch this — only loading the page in a real browser does.
+ *
+ * This boots the BUILT package in an isolated runtime and loads /login (both the signin and signup screens) in
+ * headless Chrome, failing (exit 1) if the page crashes at hydration. Run it AFTER `npm run validate` (a clean
+ * `build:release`) and BEFORE `npm publish`. See docs/{en,pt}/RELEASE_SMOKE.md.
+ *
+ *   npm run validate && npm run smoke && npm publish --access public --ignore-scripts
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync, openSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const LAUNCHER = join(ROOT, "bin", "constella.mjs");
+const WIN = process.platform === "win32";
+
+if (!existsSync(join(ROOT, ".next", "BUILD_ID"))) {
+  console.error("✖ smoke: no build found (.next/BUILD_ID). Run `npm run validate` first.");
+  process.exit(1);
+}
+
+let chromium;
+try { ({ chromium } = await import("@playwright/test")); }
+catch { try { ({ chromium } = await import("playwright")); } catch { console.error("✖ smoke: Playwright not installed (devDependency)."); process.exit(1); } }
+
+// Real-but-throwaway secrets so the launcher boots without generating/persisting into a real home.
+const SECRETS = [
+  "BETTER_AUTH_SECRET=smoke_secret_0123456789abcdef0123456789abcdef",
+  "CONSTELLA_VAULT_KEY=c21va2V2YXVsdGtleXNtb2tldmF1bHRrZXlzbW9rZTAwMA==",
+  "CONSTELLA_WORKER_SECRET=smoke_worker_secret_0123456789abcdef",
+].join("\n");
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function waitReady(url, ms = 90_000) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    try { const r = await fetch(url); if (r.ok) return true; } catch { /* not up yet */ }
+    await sleep(1000);
+  }
+  return false;
+}
+
+function killPort(port) {
+  try {
+    if (WIN) {
+      const out = spawnSyncText("powershell", ["-NoProfile", "-Command",
+        `Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess`]);
+      out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean).forEach((pid) => {
+        try { spawn("taskkill", ["/F", "/T", "/PID", pid], { stdio: "ignore" }); } catch { /* gone */ }
+      });
+    }
+  } catch { /* best-effort */ }
+}
+function spawnSyncText(cmd, args) {
+  try { return execFileSync(cmd, args, { timeout: 9000, windowsHide: true }).toString(); } catch { return ""; }
+}
+
+function killTree(child) {
+  try { if (WIN) spawn("taskkill", ["/F", "/T", "/PID", String(child.pid)], { stdio: "ignore" }); else process.kill(-child.pid, "SIGKILL"); }
+  catch { /* already gone */ }
+}
+
+async function launchBrowser() {
+  for (const channel of ["chrome", "msedge"]) {
+    try { return await chromium.launch({ channel, headless: true }); } catch { /* try next */ }
+  }
+  try { return await chromium.launch({ headless: true }); }
+  catch (e) { console.error("✖ smoke: could not launch a browser (install Chrome/Edge, or `npx playwright install chromium`):", e.message); process.exit(2); }
+}
+
+async function checkScreen(label, pwSet, port) {
+  killPort(port);
+  const home = join(tmpdir(), `constella-smoke-${label}-${port}`);
+  rmSync(home, { recursive: true, force: true });
+  mkdirSync(join(home, "organizations"), { recursive: true });
+  writeFileSync(join(home, ".env"), `${SECRETS}\nCONSTELLA_OPERATOR_PW_SET=${pwSet}\n`, { mode: 0o600 });
+  const logPath = join(home, "boot.log");
+  const logFd = openSync(logPath, "a");
+
+  const child = spawn(process.execPath, [LAUNCHER, "--start"], {
+    cwd: ROOT,
+    env: { ...process.env, CONSTELLA_HOME: home, PORT: String(port) },
+    stdio: ["ignore", logFd, logFd],
+    detached: !WIN,
+    windowsHide: true,
+  });
+
+  const url = `http://127.0.0.1:${port}/login`;
+  try {
+    if (!(await waitReady(url))) {
+      console.error(`✖ smoke[${label}]: server never became ready on ${url}. boot.log tail:`);
+      try { console.error(readFileSync(logPath, "utf8").split(/\r?\n/).slice(-12).join("\n")); } catch { /* no log */ }
+      return false;
+    }
+    const browser = await launchBrowser();
+    const errors = [];
+    const page = await (await browser.newContext()).newPage();
+    page.on("console", (m) => { if (m.type() === "error") errors.push(m.text()); });
+    page.on("pageerror", (e) => errors.push(String(e?.message || e)));
+    let bodyText = "";
+    try {
+      const resp = await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+      if (!resp || resp.status() !== 200) errors.push("HTTP " + (resp ? resp.status() : "no-response"));
+      await page.waitForTimeout(3500); // let hydration + the React scheduler (MessagePort) flush
+      bodyText = await page.evaluate(() => document.body.innerText).catch(() => "");
+    } catch (e) { errors.push("GOTO " + e.message); }
+    await browser.close();
+
+    const blob = `${errors.join("\n")}\n${bodyText}`;
+    if (/invariant expected layout router|broke at the root|Failed to find Server Action/i.test(blob)) {
+      console.error(`✖ smoke[${label}]: /login CRASHED at hydration.`);
+      errors.slice(0, 6).forEach((e) => console.error("   " + String(e).slice(0, 200)));
+      return false;
+    }
+    console.log(`✓ smoke[${label}]: /login hydrated clean (HTTP 200, no invariant).`);
+    return true;
+  } finally {
+    killTree(child);
+  }
+}
+
+console.log("• smoke: loading /login from the built package in headless Chrome…");
+let ok = true;
+ok = (await checkScreen("signin", 1, 3191)) && ok;
+ok = (await checkScreen("signup", 0, 3192)) && ok;
+console.log(ok ? "\n✓ smoke PASSED — safe to publish." : "\n✖ smoke FAILED — do NOT publish. Rebuild clean: `npm run validate` (full `.next` purge), then re-run `npm run smoke`.");
+process.exit(ok ? 0 : 1);

package/scripts/start-all.mjs

@@ -0,0 +1,45 @@
+// Launches the web server (next start) AND the background worker together, so a single
+// `pnpm start` runs everything. The worker hosts the Telegram bot poll, cron tick, and the
+// filesystem sync watcher — without it, inbound Telegram messages are never fetched. Keeping
+// them in one command means the operator can't forget to start the worker separately.
+//
+// Dependency-free (no `concurrently`): spawns both as child processes, forwards their output,
+// and shuts both down together when either dies or on Ctrl-C.
+import { spawn } from "node:child_process";
+
+// Running from source via `pnpm start` is DEVELOPER mode — show the run-mode picker + Config chips.
+// (The published `constella` CLI sets CONSTELLA_PUBLIC=1 instead, which hides them.)
+if (!process.env.CONSTELLA_PUBLIC) process.env.CONSTELLA_DEV = "1";
+
+const procs = [];
+let shuttingDown = false;
+
+function shutdown(code) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  for (const { p } of procs) { try { p.kill(); } catch { /* already gone */ } }
+  process.exit(code);
+}
+
+function run(name, args, extraEnv) {
+  const p = spawn(process.execPath, args, {
+    stdio: ["ignore", "inherit", "inherit"],
+    env: { ...process.env, ...extraEnv },
+  });
+  p.on("exit", (code) => {
+    console.log(`[${name}] exited (${code}) — shutting down the other process too.`);
+    shutdown(code ?? 1);
+  });
+  p.on("error", (e) => { console.error(`[${name}] failed to start:`, e.message); shutdown(1); });
+  procs.push({ name, p });
+}
+
+process.on("SIGINT", () => shutdown(0));
+process.on("SIGTERM", () => shutdown(0));
+
+console.log("Constella → starting web server + worker (single command).");
+// Web server first. `next start` loads .env on its own.
+run("web", ["node_modules/next/dist/bin/next", "start"]);
+// Worker shortly after so the server is usually up first (the worker also self-retries if not).
+// Plain Node needs --env-file to read .env (next does it internally).
+setTimeout(() => run("worker", ["--env-file=.env", "bin/worker.mjs"]), 1500);

package/scripts/trim-next.mjs

@@ -0,0 +1,23 @@
+// Runs on `prepack` (npm pack / npm publish): strip the parts of `.next` that `next start` does NOT
+// need, so the published tarball ships only the production runtime. The dev-server artifacts
+// (.next/dev — turbopack output + a multi-GB development log), the build cache, and trace files are
+// regenerated locally by `next dev`/`next build` and must never travel to end users.
+//
+// npm's `files` allowlist re-includes the whole `.next` dir and overrides nested .npmignore rules, so
+// deleting these on disk before packing is the reliable way to keep the package small + clean.
+import { rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const NEXT = join(process.cwd(), ".next");
+if (!existsSync(NEXT)) {
+  console.error("• trim-next: no .next/ — nothing to trim (skipping).");
+  process.exit(0);
+}
+for (const sub of ["dev", "cache", "trace"]) {
+  const p = join(NEXT, sub);
+  if (existsSync(p)) {
+    rmSync(p, { recursive: true, force: true });
+    console.error(`• trim-next: removed .next/${sub}`);
+  }
+}
+console.error("• trim-next: .next trimmed to the production runtime.");

package/scripts/vps-clean.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+#
+# vps-clean.sh — wipe a Constella VPS back to a CLEAN SLATE, keeping Tailscale. NO Docker.
+#
+# Removes: the constella systemd service, the global `constellai` CLI, the runtime data (~/.constella),
+# and the npx cache. KEEPS: the host Tailscale install + your tailnet session (so an SSH-over-tailnet
+# connection survives). Use it to simulate a fresh install before re-running the VPS install.
+#
+# Run on the VPS (NOT your laptop):
+#   curl -fsSL https://raw.githubusercontent.com/gabriel7silva/constella/main/scripts/vps-clean.sh | bash
+#   # non-interactive (no prompt):
+#   curl -fsSL https://raw.githubusercontent.com/gabriel7silva/constella/main/scripts/vps-clean.sh | bash -s -- --yes
+#
+set -u
+
+PKG="constellai"
+HOME_DIR="${CONSTELLA_HOME:-$HOME/.constella}"   # the runtime root (DB, secrets, workspaces)
+SUDO=""; [ "$(id -u)" -ne 0 ] && command -v sudo >/dev/null 2>&1 && SUDO="sudo"
+say() { printf '%s\n' "$*"; }
+
+ASSUME_YES=0
+for a in "$@"; do { [ "$a" = "--yes" ] || [ "$a" = "-y" ]; } && ASSUME_YES=1; done
+
+say "This will PERMANENTLY remove from this host:"
+say "  • the constella systemd service"
+say "  • the Constella runtime data: $HOME_DIR  (operator account, orgs, workspaces)"
+say "  • the global '$PKG' CLI and the npx cache"
+say "It KEEPS Tailscale (the host install + your tailnet session) untouched."
+say ""
+if [ "$ASSUME_YES" -ne 1 ]; then
+  if [ -e /dev/tty ]; then
+    printf 'Type "clean" to proceed: '
+    read -r ANS < /dev/tty || ANS=""
+    [ "$ANS" = "clean" ] || { say "Aborted."; exit 1; }
+  else
+    say "Non-interactive shell — re-run with --yes to confirm. Aborted."; exit 1
+  fi
+fi
+
+# 1) Stop + remove the systemd service.
+if systemctl list-unit-files 2>/dev/null | grep -q '^constella\.service'; then
+  say "• Stopping + removing the constella systemd service…"
+  $SUDO systemctl disable --now constella 2>/dev/null
+  $SUDO rm -f /etc/systemd/system/constella.service
+  $SUDO systemctl daemon-reload 2>/dev/null
+else
+  say "• No constella systemd service — skipping."
+fi
+
+# 2) Remove the CLI + the runtime data for a true clean slate.
+say "• Removing Constella data + CLI…"
+$SUDO npm rm -g "$PKG" 2>/dev/null || true
+rm -rf "$HOME_DIR"
+rm -rf "$HOME/.npm/_npx"
+
+# 3) Verify Tailscale survived.
+say ""
+say "✓ Clean slate. Tailscale check:"
+if command -v tailscale >/dev/null 2>&1; then
+  tailscale version 2>/dev/null | head -1
+  tailscale ip -4 2>/dev/null | head -1
+else
+  say "  ! Tailscale not found on PATH — it may not have been installed on the host."
+fi
+say ""
+say "Reinstall fresh with:   npx constellai --vps"

package/scripts/vps-install.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Constella VPS install — native + Tailscale + systemd. NO Docker.
+#
+# Installs Node >= 20 + the published `constellai` CLI, joins Tailscale on the host, and registers a
+# systemd service that runs `constella --vps` (starts on boot, restarts on crash). The server binds
+# 0.0.0.0 and is reachable PRIVATELY on your tailnet at :3000.
+#
+#   curl -fsSL https://raw.githubusercontent.com/gabriel7silva/constella/main/scripts/vps-install.sh | bash
+#
+set -euo pipefail
+
+PKG="constellai"
+SUDO=""; [ "$(id -u)" -ne 0 ] && SUDO="sudo"
+say() { printf '%s\n' "$*"; }
+
+# The user the service runs as (owns ~/.constella + the agent-CLI auth). Under sudo, the real operator.
+RUN_USER="${SUDO_USER:-$(id -un)}"
+RUN_HOME="$(getent passwd "$RUN_USER" 2>/dev/null | cut -d: -f6)"; [ -n "${RUN_HOME:-}" ] || RUN_HOME="$HOME"
+CHOME="${CONSTELLA_HOME:-$RUN_HOME/.constella}"
+
+say "✦ Constella VPS install — native + Tailscale + systemd"
+
+# 1) Node >= 20 (better-sqlite3/sharp ship prebuilt binaries; build tools are a fallback).
+ensure_node() {
+  local major=0
+  command -v node >/dev/null 2>&1 && major="$(node -v 2>/dev/null | sed 's/v\([0-9]*\).*/\1/')"
+  if [ "${major:-0}" -ge 20 ] 2>/dev/null; then return 0; fi
+  say "• Installing Node 22 (>= 20 required)…"
+  if   command -v apt-get >/dev/null 2>&1; then curl -fsSL https://deb.nodesource.com/setup_22.x | $SUDO -E bash - && $SUDO apt-get install -y nodejs
+  elif command -v dnf     >/dev/null 2>&1; then $SUDO dnf install -y nodejs npm gcc-c++ make python3
+  elif command -v pacman  >/dev/null 2>&1; then $SUDO pacman -S --needed --noconfirm nodejs npm base-devel python
+  else say "✖ Couldn't auto-install Node. Install Node >= 20 manually, then re-run."; exit 1
+  fi
+}
+ensure_node
+if ! { command -v make >/dev/null 2>&1 && { command -v cc >/dev/null 2>&1 || command -v gcc >/dev/null 2>&1; }; }; then
+  command -v apt-get >/dev/null 2>&1 && { $SUDO apt-get update -y >/dev/null 2>&1 || true; $SUDO apt-get install -y build-essential python3 ripgrep >/dev/null 2>&1 || true; }
+fi
+
+# 2) The Constella CLI.
+say "• Installing the ${PKG} CLI…"
+$SUDO npm install -g "$PKG"
+BIN="$(command -v constella || true)"; [ -n "$BIN" ] || BIN="/usr/bin/constella"
+
+# 3) Tailscale on the host (the host IS the tailnet node — no sidecar, no auth key prompt).
+if ! command -v tailscale >/dev/null 2>&1; then
+  say "• Installing Tailscale…"; curl -fsSL https://tailscale.com/install.sh | $SUDO sh
+fi
+say "• Joining your tailnet (a browser auth URL prints if this host isn't joined yet)…"
+$SUDO tailscale up || true
+
+# 4) systemd service — runs `constella --vps` on boot, restarts on crash. CONSTELLA_SKIP_TAILSCALE=1
+#    because step 3 already joined the tailnet (the launcher won't re-run `tailscale up`).
+say "• Registering the systemd service (constella.service)…"
+$SUDO tee /etc/systemd/system/constella.service >/dev/null <<EOF
+[Unit]
+Description=Constella
+After=network-online.target tailscaled.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${RUN_USER}
+Environment=CONSTELLA_RUN_MODE=vps
+Environment=CONSTELLA_HOME=${CHOME}
+Environment=CONSTELLA_SKIP_TAILSCALE=1
+ExecStart=${BIN} --vps --host 0.0.0.0 --port 3000
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+EOF
+$SUDO systemctl daemon-reload
+$SUDO systemctl enable --now constella
+
+# 5) Reach URL = the host's tailnet IP.
+sleep 2
+IP="$(tailscale ip -4 2>/dev/null | head -1 || true)"
+say ""
+say "✓ Constella is running as a systemd service (starts on boot, restarts on crash)."
+say "  Reach it on your tailnet:  http://${IP:-<host-tailnet-ip>}:3000   (run: tailscale ip -4)"
+say "  Manage:  systemctl status constella   ·   journalctl -u constella -f   ·   systemctl restart constella"
+say "  First load → /login (login is enforced in VPS mode)."

package/scripts/vps-update.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Constella VPS updater — native. Updates the global `constellai` CLI and restarts the systemd service.
+# NO Docker. Your data in ~/.constella (DB, secrets, workspaces) is preserved; migrations run on boot.
+#
+#   bash scripts/vps-update.sh            # -> latest published version on npm
+#   bash scripts/vps-update.sh 0.2.30     # -> a specific version
+#
+set -euo pipefail
+
+PKG="constellai"
+SUDO=""; [ "$(id -u)" -ne 0 ] && SUDO="sudo"
+say() { printf '%s\n' "$*"; }
+VERSION="${1:-latest}"
+
+say "• Installing ${PKG}@${VERSION}…"
+$SUDO npm install -g "${PKG}@${VERSION}"
+
+if systemctl list-unit-files 2>/dev/null | grep -q '^constella\.service'; then
+  say "• Restarting the constella service…"
+  $SUDO systemctl restart constella
+else
+  say "• No systemd service found — relaunch manually:  constella --vps"
+fi
+
+IP="$(tailscale ip -4 2>/dev/null | head -1 || true)"
+say ""
+say "✓ Constella updated (${VERSION}) and restarted. Data in ~/.constella preserved."
+say "  Reach it at:  http://${IP:-<host-tailnet-ip>}:3000   ·   logs: journalctl -u constella -f"

package/skills/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing to the `skills/` knowledge base
+
+This directory is a **curated, research-backed reference library** for AI agents working on Constella. It is **not** the runtime `.claude/skills/` directory (those are per-org executable procedures indexed by `src/server/sync.ts`). Files here are knowledge agents *consult*.
+
+## Non-negotiable trust rules
+
+1. **Official sources only.** Every factual claim, URL, and install command must come from an official origin: the project's own docs site, its official GitHub repo/org, or the canonical standards body (OWASP, W3C, IETF, MDN, the framework's own site). **Reject** blogs, Medium, marketing reposts, content farms, and Stack Overflow as *sources* (they may be linked under "Further reading" only if clearly labeled community).
+2. **Never invent.** If you cannot verify a fact against an official source, omit it. A short, correct skill beats a long, plausible-but-wrong one. No invented install flags, version numbers, API names, or URLs.
+3. **Cite & summarize, never copy.** Paraphrase in your own words and link the source. Do not paste large passages from Codrops, component.gallery, docs, etc. Respect licensing.
+4. **Install commands verbatim.** For stack/language skills, copy the install command **exactly** as it appears on the official install/getting-started page, and cite that page URL.
+5. **Stamp `verified:`** with the date the URLs/claims were last checked (`YYYY-MM-DD`).
+
+## Slug & path conventions
+- Lowercase, hyphenated, ASCII, Windows-safe: `fly-io`, `aspnet-core`, `csharp`, `cpp`, `spring-boot`.
+- One folder per skill. Knowledge skills live at `<group>/<slug>/SKILL.md`. Process skills live at `process/<slug>/SKILL.md` but use Format B below.
+- A skill folder may add `reference.md`, `cheatsheet.md`, or `examples/` for depth — keep `SKILL.md` short and link to them (progressive disclosure).
+
+## Minimum bar (knowledge skills) — below bar = flagged, not shipped
+Frontmatter + Official sources + Install/setup (stacks & languages) + ≥3 Core concepts + ≥3 Best practices + ≥2 Common pitfalls.
+
+---
+
+## Format A — Knowledge `SKILL.md`
+Used by: `meta/`, `engineering/`, `design/`, `languages/`, `stacks/`, `references/`.
+
+```markdown
+---
+name: <slug>
+description: <one sentence, ≤160 chars — what it covers + when to consult it>
+domain: <engineering|design|language|stack|reference|meta>
+category: <e.g. backend, database, security>   # optional sub-group
+tags: [<keyword>, <keyword>]
+official_sources:
+  - <official-docs-url>
+  - <official-repo-url>
+verified: <YYYY-MM-DD>
+---
+
+# <Human Title>
+
+## Overview
+2–4 sentences: what it is, the problem it solves, when to read this.
+
+## Official sources
+- Docs: <url>
+- Repo: <url>
+- Install / download: <url>
+
+## Install / setup            <!-- stack & language skills only -->
+```bash
+<exact command copied from the official install page>
+```
+
+## Core concepts
+- <3–7 ideas needed to use this correctly>
+
+## Best practices
+- <official/widely-endorsed practice — link a source for any non-obvious claim>
+
+## Common pitfalls
+- <mistake> → <correct approach>
+
+## Examples
+```<lang>
+<minimal correct snippet; deeper examples go in reference.md>
+```
+
+## Further reading
+- reference.md — deep dive (loaded only when needed)
+- <deeper official guide URL>
+
+## Related skills
+- ../<sibling-slug> — why it relates
+```
+
+---
+
+## Format B — Runtime `# Skill —` procedure
+Used by: `process/` (executable, matches the existing `.claude/skills/` convention so it could be promoted into a workspace later).
+
+```markdown
+# Skill — <slug>
+
+**Trigger:** <when this procedure applies>
+
+<one-line summary of what the agent produces>
+
+## When to use
+<conditions>
+
+## When NOT to use
+- <when a more specific skill applies, or the trigger is absent>
+
+## Required context & inputs
+- <what to read/gather first>
+
+## Procedure
+1. <step>
+2. <step>
+3. <step>
+
+## Output format
+- <the artifact produced; paths relative to the workspace>
+
+## Quality & validation rules
+- <how to know each step succeeded; the definition of done>
+
+## Failure handling
+- <what to do when a step fails; where to record it>
+
+## Related
+- Sources: <official method/standard URLs — e.g. scrumguides.org, adr.github.io, owasp.org>
+- Skills: <sibling process skills>
+```
+
+---
+
+## How an agent uses this library
+1. Identify the task domain and the org's declared stack (from `.claude/CLAUDE.md`).
+2. Open the matching `SKILL.md` (e.g. `orm: Drizzle` → `stacks/orm/drizzle/SKILL.md`).
+3. Follow `Further reading` / `reference.md` only if you need depth.
+4. Trust the `Official sources`; if `verified:` is stale, re-check before relying on version-specific details.