loki-mode 7.121.2 → 7.121.4

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v7.121.2
+# Loki Mode v7.121.4
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -408,4 +408,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.121.2 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.121.4 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.121.2
+7.121.4

package/autonomy/app-runner.sh

@@ -723,6 +723,11 @@ _detect_port() {
         *make*)
             _APP_RUNNER_PORT=8080
             ;;
+        *http.server*|static)
+            # Static site served by python3 -m http.server. 8000 is python's
+            # http.server convention; keep it distinct from the 8080 catch-all.
+            _APP_RUNNER_PORT=8000
+            ;;
         *)
             _APP_RUNNER_PORT=8080
             ;;
@@ -914,6 +919,34 @@ app_runner_init() {
         return 0
     fi
 
+    # 9b. Static site: a web root with an index.html and no server-app signal
+    # above (no dev/start script, no Flask/Django/etc). A landing page / static
+    # site IS a serveable web app -- without this it fell through to "none" and
+    # got no preview, no health check, no screenshot (founder feedback: a hero/
+    # pricing/waitlist landing page showed "This app has no live server"). Serve
+    # it with python3 -m http.server (always present, zero deps). Guarded on a
+    # REAL web root index.html so genuine CLIs/libraries (no index.html) still
+    # honestly read "none" below -- this never green-washes a non-web artifact.
+    local static_root=""
+    if [ -f "$dir/index.html" ]; then
+        static_root="$dir"
+    elif [ -f "$dir/public/index.html" ]; then
+        static_root="$dir/public"
+    elif [ -f "$dir/dist/index.html" ]; then
+        static_root="$dir/dist"
+    elif [ -f "$dir/build/index.html" ]; then
+        static_root="$dir/build"
+    fi
+    if [ -n "$static_root" ]; then
+        _detect_port "static"
+        # Serve the static root on the detected port; bind localhost, no reload.
+        _APP_RUNNER_METHOD="python3 -m http.server ${_APP_RUNNER_PORT} --bind 127.0.0.1 --directory $static_root"
+        _write_detection "static" "$_APP_RUNNER_METHOD"
+        log_info "App Runner: detected static site (index.html) -> serving $static_root"
+        _APP_RUNNER_URL="http://localhost:${_APP_RUNNER_PORT}"
+        return 0
+    fi
+
     # 10. Fallback: nothing detected
     log_warn "App Runner: no application detected, continuing without app runner"
     _write_detection "none" ""

package/autonomy/lib/contract-scaffold/README.md

@@ -0,0 +1,83 @@
+# contract-scaffold (M1: the contract-first codegen spine)
+
+The single load-bearing mechanism behind "a real, wired app, not a static shell."
+See `artifacts/beat-replit-engineering-plan.md` (studied from Replit's Adopt) and
+`artifacts/replit-adopt-study.md`.
+
+## What it does
+
+`scaffold.sh <out_dir> <resource> [field:type ...]` emits a **contract-first**
+project skeleton:
+
+1. An **OpenAPI contract** (`openapi.yaml`) as a first-class artifact -- the single
+   source of truth for the API.
+2. An **Orval config** that generates typed react-query hooks FROM the contract.
+3. `package.json` + `tsconfig.json` with a real codegen + typecheck script.
+
+The point: after `npm run codegen`, a page can only call hooks that the contract
+defines. A page referencing an endpoint the backend does not implement **fails
+typecheck** -- so a static-shell-passed-off-as-wired becomes impossible.
+
+## Proven (tests/test-contract-scaffold.sh, 7/7)
+
+- scaffold -> real `openapi.yaml`
+- real Orval codegen -> `useListBookmark` / `useCreateBookmark` / `useDeleteBookmark`
+- a page on a REAL endpoint typechecks
+- a page on a NON-CONTRACT endpoint **fails typecheck** (drift blocked)
+
+Proven on a throwaway `bookmark` resource -- **general by construction, no
+knowledge of any specific PRD** (anti-teaching-to-the-test).
+
+## Status: STANDALONE + ADDITIVE -- wired into NO build lane
+
+This is a capability module, like FV-1 was. It changes zero existing build
+behavior. **Wiring it into the default build lane is the gated next step** (the
+M1->"M1-wire" fork, analogous to FV-1->FV-2): that step touches the parity-locked
+`run.sh`/`build_prompt.ts` core, reclassifies what every build produces, and
+requires bash+bun parity work + council review + founder sign-off. Do NOT wire it
+in as a solo/rushed action.
+
+## Scope
+
+Gap A (the generated app's own quality). NOT Gap B (Replit's managed cloud:
+hosted DB provisioning, auth, secrets, deploy infra -- multi-quarter, out).
+
+## M2 -- real backend floor (DONE, standalone)
+
+`generate.mjs <out_dir> <resource> [field:type ...]` produces a REAL Express +
+SQLite backend (via `templates/server/`, substitution NOT heredocs) that persists:
+POST creates a row that survives to a later GET, DELETE removes it, one seed row so
+the first screen is never blank. Every declared field is always bound (a partial
+POST persists cleanly, 201, never 500 -- a bug the FV harness caught).
+
+Proven (tests/test-backend-floor.sh, 6/6) on a throwaway `note` resource: generates,
+starts, POST persists, partial POST persists, and **FV-1 reports
+functional_status=verified** -- the convergence. A static shell would fail this.
+
+Architecture: template files + a Node substitutor, NOT bash heredocs emitting JS
+(heredocs collide with JS `${...}`/backticks -- learned the hard way; see the plan).
+
+## M3 -- design-system pass (DONE, standalone)
+
+`generate.mjs` also emits (into `src/`, from `templates/ui/`) a design system so a
+generated frontend looks DESIGNED, not default:
+- `theme.css` -- ROLE tokens (bg/surface/text/primary/...), a confident modern
+  default palette, and a parallel dark theme honored from the OS (`--no-ui` skips).
+- `<Resource>ListView.tsx` -- a data surface with all THREE UI states: a shimmer
+  skeleton (never a blank flash), an inviting empty state with a CTA, and a
+  first-run "you're viewing sample data" banner (backed by M2's seed row). Wired
+  to the M1 contract hook, so it cannot reference a non-contract endpoint.
+
+Small touches that make users smile: friendly copy, a clear primary action,
+graceful loading/empty/error states, no raw hex (re-theme from one block).
+
+Proven (tests/test-design-system.sh, 8/8): no raw hex in components, all three
+states, dark theme, AND the tokenized ListView TYPECHECKS against the generated
+contract hooks (the contract even caught a wrong response-type assumption in the
+UI -- the spine working as designed).
+
+## Next (wiring, see the plan)
+
+- Wire M1+M2+M3 into the build lane (GATED: touches parity-locked run.sh/
+  build_prompt.ts core -> bash+bun parity + council + founder sign-off).
+- Wire the FV harness into the completion verdict (FV-2, founder-gated).

package/autonomy/lib/contract-scaffold/generate.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// generate.mjs -- M2 backend-floor generator (template substitution, NOT heredocs).
+//
+// Reads the server template files and substitutes tokens derived from a portable
+// {resource, fields} descriptor, producing a REAL Express + SQLite backend that
+// persists. General by construction: no knowledge of any specific PRD.
+//
+// Why a Node generator and not a bash heredoc: a heredoc emitting JS collides with
+// JS `${...}` template literals and backticks (bit both the M1 yaml and a first
+// M2 js heredoc). Templates + substitution keeps generated code reviewable as real
+// code. See artifacts/beat-replit-engineering-plan.md (M2 architecture decision).
+//
+// Usage: node generate.mjs <out_dir> <resource> [field:type ...]
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const TPL = join(__dir, "templates", "server");
+
+const [, , outDir, resource, ...fieldArgs] = process.argv;
+if (!outDir || !resource) {
+  console.error("usage: generate.mjs <out_dir> <resource> [field:type ...]");
+  process.exit(2);
+}
+
+const fields = (fieldArgs.length ? fieldArgs : ["title:string"]).map((f) => {
+  const [name, type = "string"] = f.split(":");
+  return { name, type };
+});
+
+const cap = resource.charAt(0).toUpperCase() + resource.slice(1);
+const coll = resource.endsWith("s") ? resource : resource + "s";
+
+const sqlType = (t) =>
+  ["int", "integer", "number", "bool", "boolean"].includes(t) ? "INTEGER" : "TEXT";
+const seedVal = (t) =>
+  ["int", "integer", "number"].includes(t) ? "1"
+  : ["bool", "boolean"].includes(t) ? "0"
+  : "'sample value'";
+
+const tokens = {
+  __COLL__: coll,
+  __RESOURCE_CAP__: cap,
+  __COLUMNS_SQL__: fields.map((f) => `  ${f.name} ${sqlType(f.type)},`).join("\n"),
+  __SEED_COLS__: fields.length ? fields.map((f) => f.name).join(", ") + "," : "",
+  __SEED_VALS__: fields.length ? fields.map((f) => seedVal(f.type)).join(", ") + "," : "",
+  __INSERT_COLS__: fields.length ? fields.map((f) => f.name).join(", ") + "," : "",
+  __INSERT_PLACEHOLDERS__: fields.length ? fields.map((f) => "@" + f.name).join(", ") + "," : "",
+  __BODY_FIELDS__: fields.map((f) => `"${f.name}"`).join(", "),
+};
+
+function render(tpl) {
+  let out = tpl;
+  // Replace longer tokens first so __RESOURCE_CAP__ isn't partially hit, etc.
+  for (const key of Object.keys(tokens).sort((a, b) => b.length - a.length)) {
+    out = out.split(key).join(tokens[key]);
+  }
+  return out;
+}
+
+mkdirSync(join(outDir, "server"), { recursive: true });
+for (const [tpl, dest] of [
+  ["index.mjs.tmpl", "index.mjs"],
+  ["package.json.tmpl", "package.json"],
+]) {
+  const src = readFileSync(join(TPL, tpl), "utf8");
+  writeFileSync(join(outDir, "server", dest), render(src));
+}
+
+// M3: the design-system UI templates (tokens + dark + three states), wired to the
+// M1 contract hooks. Emitted into src/ alongside the generated client so a
+// generated frontend looks DESIGNED (not default) and cannot reference a
+// non-contract endpoint. Optional: skip with --no-ui.
+if (!process.argv.includes("--no-ui")) {
+  const UI = join(__dir, "templates", "ui");
+  mkdirSync(join(outDir, "src"), { recursive: true });
+  for (const [tpl, dest] of [
+    ["theme.css.tmpl", "theme.css"],
+    ["ListView.tsx.tmpl", `${cap}ListView.tsx`],
+  ]) {
+    const src = readFileSync(join(UI, tpl), "utf8");
+    writeFileSync(join(outDir, "src", dest), render(src));
+  }
+}
+
+console.log(`generated real backend floor at ${outDir}/server (Express + SQLite, /${coll})`);
+if (!process.argv.includes("--no-ui"))
+  console.log(`generated design-system UI at ${outDir}/src (tokens + dark + 3 states, wired to the contract)`);
+console.log(`next: (cd ${outDir}/server && npm install && PORT=3000 npm start)`);

package/autonomy/lib/contract-scaffold/scaffold.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# contract-scaffold/scaffold.sh -- M1: the contract-first codegen spine.
+#
+# The single load-bearing mechanism behind "a real wired app, not a static shell"
+# (see artifacts/beat-replit-engineering-plan.md, studied from Replit's Adopt).
+# It emits an OpenAPI contract as a first-class artifact, then generates typed
+# client hooks + validators FROM it, so a page PHYSICALLY CANNOT call an endpoint
+# the backend does not implement -- it will not typecheck. A static mock stops
+# being possible to pass off as a wired app.
+#
+# STATUS: STANDALONE + ADDITIVE. Wired into NO build lane. It is a capability
+# module proven on throwaway specs; wiring it into the default build is the
+# gated next step (like FV-1 -> FV-2), requiring bash+bun parity work + council.
+#
+# GENERAL by construction: it takes a portable {name, entity, fields} descriptor
+# and produces a contract-first skeleton for ANY simple REST resource. It has NO
+# knowledge of any specific PRD (anti-teaching-to-the-test).
+#
+# Usage:
+#   scaffold.sh <out_dir> <resource_name> [field:type ...]
+# Example:
+#   scaffold.sh /tmp/bookmarks bookmark url:string title:string
+set -euo pipefail
+
+OUT="${1:?usage: scaffold.sh <out_dir> <resource> [field:type ...]}"
+RES="${2:?resource name required}"
+shift 2 || true
+FIELDS=("$@")
+[ "${#FIELDS[@]}" -eq 0 ] && FIELDS=("title:string")
+
+# Plural collection path (naive but sufficient: append 's' unless already plural).
+case "$RES" in *s) COLL="$RES" ;; *) COLL="${RES}s" ;; esac
+
+mkdir -p "$OUT"
+
+# ---- 1. The OpenAPI contract (the single source of truth) -------------------
+# Build the schema properties + a create-body from the field descriptors.
+_props=""; _required=""; _create_props=""
+for f in "${FIELDS[@]}"; do
+    fname="${f%%:*}"; ftype="${f##*:}"
+    case "$ftype" in
+        int|integer|number) otype="integer" ;;
+        bool|boolean) otype="boolean" ;;
+        *) otype="string" ;;
+    esac
+    _props+="        ${fname}: { type: ${otype} }
+"
+    _create_props+="        ${fname}: { type: ${otype} }
+"
+    _required+="        - ${fname}
+"
+done
+
+cat > "$OUT/openapi.yaml" <<YAML
+openapi: 3.1.0
+info: { title: Api, version: 1.0.0 }
+servers: [{ url: /api }]
+paths:
+  /${COLL}:
+    get:
+      operationId: list${RES^}
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: { type: array, items: { \$ref: '#/components/schemas/${RES^}' } }
+    post:
+      operationId: create${RES^}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { \$ref: '#/components/schemas/${RES^}Create' }
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema: { \$ref: '#/components/schemas/${RES^}' }
+  /${COLL}/{id}:
+    delete:
+      operationId: delete${RES^}
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        '204': { description: No Content }
+components:
+  schemas:
+    ${RES^}:
+      type: object
+      required:
+        - id
+${_required}      properties:
+        id: { type: string }
+${_props}    ${RES^}Create:
+      type: object
+      required:
+${_required}      properties:
+${_create_props}
+YAML
+
+# ---- 2. Orval config: contract -> typed react-query hooks -------------------
+cat > "$OUT/orval.config.ts" <<'TS'
+import { defineConfig } from "orval";
+export default defineConfig({
+  client: {
+    input: "./openapi.yaml",
+    output: {
+      target: "./src/generated/api.ts",
+      client: "react-query",
+      mode: "single",
+      clean: true,
+      override: { header: () => ["// GENERATED by orval -- do not edit manually."] },
+    },
+  },
+});
+TS
+
+# ---- 3. package.json (real deps, real codegen script) ----------------------
+cat > "$OUT/package.json" <<JSON
+{
+  "name": "contract-first-${COLL}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "codegen": "orval --config ./orval.config.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": { "@tanstack/react-query": "^5.0.0", "react": "^18.0.0" },
+  "devDependencies": { "orval": "^8.0.0", "typescript": "^5.4.0", "@types/react": "^18.0.0" }
+}
+JSON
+
+cat > "$OUT/tsconfig.json" <<'JSON'
+{
+  "compilerOptions": {
+    "strict": true, "noEmit": true, "jsx": "react-jsx",
+    "module": "ESNext", "moduleResolution": "Bundler",
+    "target": "ES2022", "lib": ["ES2022", "DOM"], "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+JSON
+
+echo "scaffolded contract-first skeleton at $OUT (resource=$RES, collection=/$COLL)"
+echo "next: (cd $OUT && npm install && npm run codegen && npm run typecheck)"

package/autonomy/lib/contract-scaffold/templates/server/index.mjs.tmpl

@@ -0,0 +1,62 @@
+// Real backend FLOOR: Express + SQLite persistence implementing the M1 contract.
+// POST persists; GET reflects it; DELETE removes it -- a working data pipeline,
+// not a mock. Generated by contract-scaffold (template-substitution, general).
+// (Token reference intentionally omitted from this comment so the substitutor
+//  does not rewrite it; see generate.mjs for the token list.)
+import express from "express";
+import Database from "better-sqlite3";
+import { randomUUID } from "node:crypto";
+
+const db = new Database(process.env.DB_PATH || ":memory:");
+db.exec(`CREATE TABLE IF NOT EXISTS __COLL__ (
+  id TEXT PRIMARY KEY,
+__COLUMNS_SQL__
+  created_at TEXT NOT NULL
+);`);
+
+// Seed one row so the very first screen is never blank (the empty vs first-run
+// UI-state discipline: a real app greets the user with sample data, not a void).
+const seedCount = db.prepare("SELECT COUNT(*) AS c FROM __COLL__").get().c;
+if (seedCount === 0) {
+  db.prepare(
+    "INSERT INTO __COLL__ (id, __SEED_COLS__ created_at) VALUES (?, __SEED_VALS__ ?)"
+  ).run(randomUUID(), new Date().toISOString());
+}
+
+const app = express();
+app.use(express.json());
+
+// Only these keys are accepted from a POST body -- never arbitrary columns.
+// EVERY declared field is always bound (defaulting to null when the caller omits
+// it), so a partial POST persists cleanly instead of throwing "missing named
+// parameter". A real app tolerates optional fields; it does not 500 on them.
+const BODY_FIELDS = [__BODY_FIELDS__];
+function pickBody(body) {
+  const out = {};
+  for (const k of BODY_FIELDS) out[k] = body != null && body[k] !== undefined ? body[k] : null;
+  return out;
+}
+
+// GET /api/__COLL__  (list__RESOURCE_CAP__)
+app.get("/api/__COLL__", (_req, res) => {
+  res.json(db.prepare("SELECT * FROM __COLL__ ORDER BY created_at DESC").all());
+});
+
+// POST /api/__COLL__  (create__RESOURCE_CAP__) -- PERSISTS
+app.post("/api/__COLL__", (req, res) => {
+  const fields = pickBody(req.body);
+  const row = { id: randomUUID(), ...fields, created_at: new Date().toISOString() };
+  db.prepare(
+    "INSERT INTO __COLL__ (id, __INSERT_COLS__ created_at) VALUES (@id, __INSERT_PLACEHOLDERS__ @created_at)"
+  ).run(row);
+  res.status(201).json(row);
+});
+
+// DELETE /api/__COLL__/:id  (delete__RESOURCE_CAP__)
+app.delete("/api/__COLL__/:id", (req, res) => {
+  db.prepare("DELETE FROM __COLL__ WHERE id = ?").run(req.params.id);
+  res.status(204).end();
+});
+
+const port = process.env.PORT ? Number(process.env.PORT) : 3000;
+app.listen(port, () => console.log(`__RESOURCE_CAP__ API listening on port ${port}`));

package/autonomy/lib/contract-scaffold/templates/server/package.json.tmpl

@@ -0,0 +1,10 @@
+{
+  "name": "contract-first-__COLL__-server",
+  "private": true,
+  "type": "module",
+  "scripts": { "start": "node index.mjs" },
+  "dependencies": {
+    "express": "^5.0.0",
+    "better-sqlite3": "^12.0.0"
+  }
+}

package/autonomy/lib/contract-scaffold/templates/ui/ListView.tsx.tmpl

@@ -0,0 +1,75 @@
+// ListView.tsx -- a data surface that ships all THREE UI states with design
+// tokens, wired to the M1 contract hook. This is what "designed, not default"
+// looks like: skeleton while loading, an inviting empty state with a CTA, a
+// first-run "sample data" banner, and real rows in a tokenized card. It consumes
+// the generated hook, so it physically cannot reference a non-contract endpoint.
+//
+// Generated by contract-scaffold M3 (general: __COLL__/__RESOURCE_CAP__ tokens,
+// no product-specific content). Small touches that make users smile: friendly
+// copy, an icon, a clear primary action, graceful loading + empty states.
+import { useList__RESOURCE_CAP__, useCreate__RESOURCE_CAP__ } from "./generated/api";
+
+export function __RESOURCE_CAP__ListView() {
+  const { data, isLoading, isError } = useList__RESOURCE_CAP__();
+  const create = useCreate__RESOURCE_CAP__();
+  // Orval's react-query hook returns the full response object; the array is at
+  // .data.data, typed straight from the OpenAPI contract (a real __RESOURCE_CAP__[]).
+  // Reading it wrong is a typecheck error -- the contract-first spine catching a
+  // drift in the UI itself.
+  const items = data?.data ?? [];
+  // A seeded backend (M2) means the first real screen shows sample data, not a void.
+  const isFirstRun = items.length > 0 && items.length <= 1;
+
+  // State 1: skeleton -- never a blank flash while loading.
+  if (isLoading) {
+    return (
+      <section className="card" aria-busy="true" aria-label="Loading __COLL__">
+        <div className="skeleton" style={{ width: "40%", marginBottom: 12 }} />
+        <div className="skeleton" style={{ width: "100%", marginBottom: 8 }} />
+        <div className="skeleton" style={{ width: "90%" }} />
+      </section>
+    );
+  }
+
+  if (isError) {
+    return (
+      <section className="empty" role="alert">
+        <p>We couldn't load your __COLL__. Please try again.</p>
+      </section>
+    );
+  }
+
+  // State 2: empty -- a dashed invitation with a clear next action, never a void.
+  if (items.length === 0) {
+    return (
+      <section className="empty">
+        <h3 style={{ margin: "0 0 4px" }}>No __COLL__ yet</h3>
+        <p style={{ margin: "0 0 16px" }}>Get started by creating your first one.</p>
+        <button className="btn-primary" onClick={() => create.mutate({ data: {} as never })}>
+          Create __RESOURCE_CAP__
+        </button>
+      </section>
+    );
+  }
+
+  // State 3: populated (with a friendly first-run banner when it's sample data).
+  return (
+    <section>
+      {isFirstRun ? (
+        <div className="first-run" role="status">
+          <span aria-hidden="true">*</span>
+          You're viewing sample data. Create a __RESOURCE_CAP__ to make it yours.
+        </div>
+      ) : null}
+      <ul style={{ listStyle: "none", padding: 0, margin: "12px 0 0", display: "grid", gap: 12 }}>
+        {items.map((it) => (
+          <li key={String((it as { id?: unknown }).id)} className="card">
+            <pre style={{ margin: 0, fontFamily: "inherit", whiteSpace: "pre-wrap" }}>
+              {JSON.stringify(it, null, 2)}
+            </pre>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}

package/autonomy/lib/contract-scaffold/templates/ui/theme.css.tmpl

@@ -0,0 +1,99 @@
+/* theme.css -- design tokens (role-based, NEVER raw hex in components).
+ *
+ * Why this exists: generated apps look "AI-default" because they scatter raw
+ * colors and ship only a happy-path light theme. A real designed app uses ROLE
+ * tokens (bg, surface, text, primary, ...) referenced everywhere, ships a
+ * parallel dark theme from the same variable block, and honors the OS setting.
+ * Swapping one block re-themes the whole app. Modern, high-contrast, accessible.
+ *
+ * Generated by contract-scaffold M3 (general -- no product-specific colors;
+ * a strong neutral+indigo default any greenfield app can ship and re-brand).
+ */
+:root {
+  /* Surfaces */
+  --bg: #f7f8fa;
+  --surface: #ffffff;
+  --surface-2: #f0f2f5;
+  --border: #e3e6eb;
+  /* Text (AA contrast on --bg / --surface) */
+  --text: #1a1d24;
+  --text-muted: #5a6472;
+  /* Brand accent -- a confident modern indigo (re-brand by editing here only) */
+  --primary: #5b35e8;
+  --primary-contrast: #ffffff;
+  --primary-weak: #ece8fd;
+  /* Semantic */
+  --ok: #1f9d55;
+  --warn: #b7791f;
+  --danger: #c2333a;
+  /* Shape + depth (subtle, not shadow-heavy) */
+  --radius: 12px;
+  --radius-sm: 8px;
+  --shadow-sm: 0 1px 2px rgba(16, 24, 40, 0.06), 0 1px 3px rgba(16, 24, 40, 0.08);
+  --space: 16px;
+}
+
+/* Dark theme -- same roles, honored automatically from the OS preference. */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0f1117;
+    --surface: #171a21;
+    --surface-2: #1e222b;
+    --border: #2a2f3a;
+    --text: #eef1f6;
+    --text-muted: #9aa4b2;
+    --primary: #8b6dff;
+    --primary-contrast: #0f1117;
+    --primary-weak: #241f3d;
+    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4), 0 1px 3px rgba(0, 0, 0, 0.5);
+  }
+}
+/* Explicit override hook (a theme toggle sets data-theme on <html>). */
+:root[data-theme="dark"] {
+  --bg: #0f1117; --surface: #171a21; --surface-2: #1e222b; --border: #2a2f3a;
+  --text: #eef1f6; --text-muted: #9aa4b2; --primary: #8b6dff;
+  --primary-contrast: #0f1117; --primary-weak: #241f3d;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font: 15px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow-sm);
+  padding: var(--space);
+}
+.btn-primary {
+  background: var(--primary); color: var(--primary-contrast);
+  border: none; border-radius: var(--radius-sm);
+  padding: 8px 16px; font-weight: 600; cursor: pointer;
+}
+.btn-primary:hover { filter: brightness(1.05); }
+
+/* --- the three UI states every data surface ships --- */
+/* 1. skeleton (loading) -- a shimmer, never a blank flash */
+.skeleton {
+  background: linear-gradient(90deg, var(--surface-2) 25%, var(--border) 37%, var(--surface-2) 63%);
+  background-size: 400% 100%;
+  animation: shimmer 1.4s ease infinite;
+  border-radius: var(--radius-sm); height: 16px;
+}
+@keyframes shimmer { 0% { background-position: 100% 0; } 100% { background-position: 0 0; } }
+/* 2. empty state -- a dashed invitation with a CTA, never a void */
+.empty {
+  border: 1px dashed var(--border); border-radius: var(--radius);
+  padding: calc(var(--space) * 2); text-align: center; color: var(--text-muted);
+}
+/* 3. first-run banner -- "you're viewing sample data" so screen 1 is alive */
+.first-run {
+  background: var(--primary-weak); border: 1px solid var(--border);
+  border-radius: var(--radius); padding: 12px 16px; color: var(--text);
+  display: flex; align-items: center; gap: 8px; font-size: 14px;
+}