lastlight 0.1.15 → 0.2.1

package/skills/browser-qa/scripts/agent-browser.mjs

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+// agent-browser.mjs — bundled headless-browser driver for Tier B browser QA.
+//
+// CONTRACT
+// --------
+// Runs inside the `lastlight-sandbox-qa:latest` docker image, which bakes in
+// Playwright + Chromium at PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers and
+// makes the global `playwright` package resolvable via NODE_PATH. The calling
+// agent has bash + file tools but NO vision: it reasons over this CLI's JSON
+// stdout (extracted text, assertion results, console errors). The PNG
+// screenshots are human evidence only — the agent never "sees" them.
+//
+// Subcommands:
+//   doctor
+//     Runtime probe. Launches headless Chromium (--no-sandbox), opens
+//     about:blank, closes. On success prints {"ok":true,"chromium":"<version>"}
+//     and exits 0; on ANY failure prints {"ok":false,"error":"..."} and exits 1.
+//     The skill runs this first to decide browser-vs-text.
+//
+//   run <flow.json> [--base-url URL] [--out-dir DIR] [--record-dir DIR]
+//     Executes a FLOW in ONE Chromium session (state preserved across steps) and
+//     prints a single JSON report.
+//
+//     With --record-dir DIR (or `"record": true` in the flow), the whole session
+//     is screen-recorded via Playwright's native recordVideo and saved to
+//     <record-dir>/session.webm (default: the out-dir). The saved path is
+//     reported as `video` in the JSON. Used by the `/demo` workflow, which then
+//     composites the raw webm into a titled mp4 with compose-demo.sh.
+//
+//     Flow shape:
+//       { "baseUrl": "http://localhost:3000",
+//         "viewport": {"width":1280,"height":800},
+//         "steps": [
+//           {"name":"home", "goto":"/"},
+//           {"click":"text=Login"},
+//           {"fill":["#email","a@b.com"]},
+//           {"type":["#search","hello"]},
+//           {"press":"Enter"},
+//           {"waitFor":"#dashboard"},
+//           {"assertText":"Welcome"},
+//           {"text":"h1"},
+//           {"screenshot":"after-login"}
+//         ] }
+//     A step may combine an action plus a trailing `screenshot`.
+//
+//     Per-step semantics:
+//       - A step error (selector not found, assertion fail, timeout) is recorded
+//         {ok:false} and the run CONTINUES (best-effort QA) — EXCEPT a `goto`
+//         that throws is FATAL: remaining steps are marked skipped.
+//       - assertText passes if the text is visible anywhere on the page; on miss
+//         the step is {ok:false} but the run continues.
+//       - text extracts a selector's textContent into the step result.
+//       - screenshot writes <out-dir>/<basename>.png (full page).
+//
+//     Final stdout: one JSON object
+//       { ok, baseUrl, steps:[{index,action,ok,ms,text?,screenshot?,error?}],
+//         consoleErrors:[...], screenshots:[paths] }
+//     Exit 0 even when steps failed (the agent reads the JSON to judge). Exit
+//     non-zero only on a FATAL harness error (bad flow file, launch failure).
+//
+// Dependency-free apart from playwright.
+
+import { readFileSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+// This file is ESM (.mjs); playwright is a CJS package. createRequire gives us
+// a `require` that resolves an absolute package-dir path (see loadPlaywright).
+const require = createRequire(import.meta.url);
+
+const WAIT_TIMEOUT = 10_000; // sane default for waitFor / assertText probes
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+async function loadPlaywright() {
+  // Resolve playwright via CJS `require`: it handles an absolute package-dir
+  // path ($LASTLIGHT_PLAYWRIGHT, baked into the QA image) by reading the
+  // package.json `main` — which ESM `import()` of a directory does NOT do — and
+  // it honours NODE_PATH for the bare-specifier fallback. playwright ships a CJS
+  // entry, so `require` returns { chromium, … } directly.
+  const candidates = [process.env.LASTLIGHT_PLAYWRIGHT, 'playwright'].filter(Boolean);
+  for (const spec of candidates) {
+    try {
+      return require(spec);
+    } catch {
+      // try the next candidate
+    }
+  }
+  emit({
+    ok: false,
+    error:
+      'playwright not available — browser QA needs the lastlight-sandbox-qa image',
+  });
+  process.exit(1);
+}
+
+async function doctor() {
+  const { chromium } = await loadPlaywright();
+  let browser;
+  try {
+    browser = await chromium.launch({ headless: true, args: ['--no-sandbox'] });
+    const page = await browser.newPage();
+    await page.goto('about:blank');
+    const version = browser.version();
+    await page.close();
+    emit({ ok: true, chromium: version });
+    process.exit(0);
+  } catch (err) {
+    emit({ ok: false, error: String(err && err.message ? err.message : err) });
+    process.exit(1);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+// Resolve a goto target against the base URL. Absolute URLs pass through.
+function resolveUrl(target, baseUrl) {
+  if (/^https?:\/\//i.test(target)) return target;
+  if (!baseUrl) return target;
+  return baseUrl.replace(/\/+$/, '') + '/' + String(target).replace(/^\/+/, '');
+}
+
+// Returns the action name for a step (for reporting) — first recognized key.
+function actionOf(step) {
+  for (const k of [
+    'goto',
+    'click',
+    'fill',
+    'type',
+    'press',
+    'waitFor',
+    'assertText',
+    'text',
+  ]) {
+    if (k in step) return k;
+  }
+  if ('screenshot' in step) return 'screenshot';
+  return 'noop';
+}
+
+async function execStep(page, step, baseUrl, outDir, screenshots) {
+  const result = {};
+  let fatal = false;
+
+  if ('goto' in step) {
+    // Navigation failure is FATAL.
+    try {
+      await page.goto(resolveUrl(step.goto, baseUrl), {
+        waitUntil: 'load',
+        timeout: WAIT_TIMEOUT * 3,
+      });
+    } catch (err) {
+      throw Object.assign(new Error(`goto failed: ${err.message}`), {
+        fatal: true,
+      });
+    }
+  } else if ('click' in step) {
+    await page.click(step.click, { timeout: WAIT_TIMEOUT });
+  } else if ('fill' in step) {
+    const [sel, val] = step.fill;
+    await page.fill(sel, val, { timeout: WAIT_TIMEOUT });
+  } else if ('type' in step) {
+    const [sel, val] = step.type;
+    await page.locator(sel).first().pressSequentially(val, {
+      timeout: WAIT_TIMEOUT,
+    });
+  } else if ('press' in step) {
+    await page.keyboard.press(step.press);
+  } else if ('waitFor' in step) {
+    await page.locator(step.waitFor).first().waitFor({
+      state: 'visible',
+      timeout: WAIT_TIMEOUT,
+    });
+  } else if ('assertText' in step) {
+    // Pass if visible anywhere on the page; miss => step fails, run continues.
+    try {
+      await page
+        .getByText(step.assertText, { exact: false })
+        .first()
+        .waitFor({ state: 'visible', timeout: WAIT_TIMEOUT });
+    } catch {
+      throw new Error(`assertText not found: ${JSON.stringify(step.assertText)}`);
+    }
+  } else if ('text' in step) {
+    const txt = await page
+      .locator(step.text)
+      .first()
+      .textContent({ timeout: WAIT_TIMEOUT });
+    result.text = txt == null ? '' : txt.trim();
+  }
+
+  // A trailing screenshot can ride along with any action (or stand alone).
+  if ('screenshot' in step) {
+    const base = String(step.screenshot).replace(/[^a-zA-Z0-9._-]/g, '_');
+    const path = join(outDir, `${base}.png`);
+    await page.screenshot({ path, fullPage: true });
+    result.screenshot = path;
+    screenshots.push(path);
+  }
+
+  return { result, fatal };
+}
+
+async function run(flowPath, baseUrlArg, outDirArg, recordDirArg) {
+  let flow;
+  try {
+    flow = JSON.parse(readFileSync(resolve(flowPath), 'utf8'));
+  } catch (err) {
+    emit({ ok: false, error: `cannot read flow file: ${err.message}` });
+    process.exit(1);
+  }
+  if (!flow || !Array.isArray(flow.steps)) {
+    emit({ ok: false, error: 'flow file must have a "steps" array' });
+    process.exit(1);
+  }
+
+  const baseUrl = baseUrlArg || flow.baseUrl || '';
+  const outDir = resolve(outDirArg || process.cwd());
+  // Record the session when --record-dir is passed OR the flow opts in with
+  // `"record": true`. The .webm lands in the record dir (default: out-dir).
+  const doRecord = !!recordDirArg || flow.record === true;
+  const videoDir = resolve(recordDirArg || outDir);
+  try {
+    mkdirSync(outDir, { recursive: true });
+  } catch {
+    /* best effort */
+  }
+  if (doRecord) {
+    try {
+      mkdirSync(videoDir, { recursive: true });
+    } catch {
+      /* best effort */
+    }
+  }
+
+  const viewport = flow.viewport || { width: 1280, height: 800 };
+  const { chromium } = await loadPlaywright();
+  let browser;
+  const steps = [];
+  const screenshots = [];
+  const consoleErrors = [];
+  let videoPath = null;
+
+  try {
+    browser = await chromium.launch({ headless: true, args: ['--no-sandbox'] });
+  } catch (err) {
+    emit({
+      ok: false,
+      error: `browser launch failed: ${err && err.message ? err.message : err}`,
+    });
+    process.exit(1);
+  }
+
+  try {
+    const context = await browser.newContext({
+      viewport,
+      // Playwright records video per-context; the size matches the viewport so
+      // the clip isn't letterboxed. The .webm is flushed on context.close().
+      ...(doRecord ? { recordVideo: { dir: videoDir, size: viewport } } : {}),
+    });
+    const page = await context.newPage();
+
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    page.on('pageerror', (err) => {
+      consoleErrors.push(String(err && err.message ? err.message : err));
+    });
+
+    let fatalHit = false;
+    for (let i = 0; i < flow.steps.length; i++) {
+      const step = flow.steps[i];
+      const action = actionOf(step);
+
+      if (fatalHit) {
+        steps.push({ index: i, action, ok: false, ms: 0, error: 'skipped (prior fatal step)' });
+        continue;
+      }
+
+      const started = Date.now();
+      try {
+        const { result } = await execStep(page, step, baseUrl, outDir, screenshots);
+        steps.push({ index: i, action, ok: true, ms: Date.now() - started, ...result });
+      } catch (err) {
+        const entry = {
+          index: i,
+          action,
+          ok: false,
+          ms: Date.now() - started,
+          error: String(err && err.message ? err.message : err),
+        };
+        steps.push(entry);
+        if (err && err.fatal) fatalHit = true; // navigation failure: skip the rest
+      }
+    }
+
+    // Finalize a recording (if any) BEFORE emitting: saving the video requires
+    // the context to close, which flushes the .webm to disk. A save failure is a
+    // reported finding, not a fatal run error.
+    if (doRecord) {
+      const video = page.video();
+      await context.close();
+      if (video) {
+        const target = join(videoDir, 'session.webm');
+        try {
+          await video.saveAs(target);
+          videoPath = target;
+          await video.delete().catch(() => {});
+        } catch (err) {
+          consoleErrors.push(
+            `video save failed: ${err && err.message ? err.message : err}`,
+          );
+        }
+      }
+    }
+
+    emit({
+      ok: steps.every((s) => s.ok),
+      baseUrl,
+      steps,
+      consoleErrors,
+      screenshots,
+      ...(videoPath ? { video: videoPath } : {}),
+    });
+    process.exit(0);
+  } catch (err) {
+    // Unexpected harness error mid-run — still emit a JSON object.
+    emit({
+      ok: false,
+      error: String(err && err.message ? err.message : err),
+      baseUrl,
+      steps,
+      consoleErrors,
+      screenshots,
+      ...(videoPath ? { video: videoPath } : {}),
+    });
+    process.exit(1);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+
+  if (cmd === 'doctor') {
+    await doctor();
+    return;
+  }
+
+  if (cmd === 'run') {
+    const positional = [];
+    let baseUrl;
+    let outDir;
+    let recordDir;
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === '--base-url') baseUrl = rest[++i];
+      else if (a === '--out-dir') outDir = rest[++i];
+      else if (a === '--record-dir') recordDir = rest[++i];
+      else positional.push(a);
+    }
+    if (!positional[0]) {
+      emit({ ok: false, error: 'usage: agent-browser.mjs run <flow.json> [--base-url URL] [--out-dir DIR] [--record-dir DIR]' });
+      process.exit(1);
+    }
+    await run(positional[0], baseUrl, outDir, recordDir);
+    return;
+  }
+
+  emit({ ok: false, error: 'usage: agent-browser.mjs <doctor|run> ...' });
+  process.exit(1);
+}
+
+main().catch((err) => {
+  emit({ ok: false, error: String(err && err.message ? err.message : err) });
+  process.exit(1);
+});

package/skills/building/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: building
+description: Install dependencies and run the test/lint/typecheck gate for a change inside the sandbox — package-manager detection, install-first, and (when implementing) TDD discipline. Use when implementing, fixing, or verifying code in a pre-cloned repo.
+version: 1.0.0
+tags: [build, test, sandbox]
+---
+
+# Building
+
+How to install, build, test, and gate a change in the sandbox. The same
+discipline whether you're implementing a feature, fixing review feedback, or
+verifying someone else's PR.
+
+## Workspace & git
+
+The harness pre-cloned the repo; your cwd is the repo root (or a `<repo>/`
+subdirectory — check with `ls -la`). Git is configured for clone/push/pull/fetch.
+If auth fails after ~1 hour, call the `github_refresh_git_auth` MCP tool. Suppress
+noise where it helps: `git clone --quiet`, `git push --quiet`, `CI=true`.
+
+## Install-first
+
+`node_modules` (and any other dependency dir) is **always** absent on arrival —
+by design, not a blocker. **Installing is the first step, not a reason to skip
+verification.** Detect the package manager from the lockfile and use the
+frozen/CI variant:
+
+- `package-lock.json` → `npm ci`
+- `pnpm-lock.yaml` → `corepack pnpm install --frozen-lockfile`
+- `yarn.lock` → `corepack yarn install --frozen-lockfile`
+
+Node is available via `fnm` + `corepack`; the egress allowlist permits the public
+package registries, so install works. For a monorepo, install at the root, then
+operate on the changed package. For non-Node repos, use the ecosystem's
+equivalent (`pip install`, `cargo build`, `go mod download`, …) read from the
+project's manifest.
+
+The **only** acceptable "couldn't verify" is when the install or build command
+*itself* fails — quote the exact command and error, and scope your work to what
+you could check. Never cite "deps aren't installed" as the reason: you install them.
+
+**If the repo's only test path needs an external service that won't run in the
+sandbox** (a live database, a cloud API, a running daemon), do **not** report
+that verification "could not run." Add a focused unit or CLI test project that
+exercises your change against in-memory fixtures or fakes, run *that*, and paste
+its output. A change you couldn't execute even once is unverified — building a
+runnable path is part of the work, not an optional extra.
+
+## The gate
+
+While iterating, run **only the tests covering the files you touched** — not the
+whole suite on every edit. Then, **once before committing or claiming done, run
+the full gate and require all of it to pass:**
+
+1. Full test command — zero failures.
+2. Lint command (if present) — fix all errors.
+3. Typecheck command (if present) — fix all errors.
+
+If any step fails, fix it and re-run only what failed until clean. Do not commit
+or report done until the full suite, lint, and typecheck all pass. Cite the
+actual command output — static reasoning is not verification.
+
+## TDD (when implementing)
+
+When you are *writing* code (not just verifying a PR): write the **failing test
+first**, watch it go red, then implement until it goes green, then refactor.
+Test behaviour through the public interface, not implementation details. The red
+test is the proof the test can fail — a test that was never red proves nothing.
+
+## Decomposition budget (when implementing)
+
+The gate passing is necessary, not sufficient — a green test does not excuse an
+unmaintainable function. Before you commit, decompose:
+
+- Keep each function under **roughly 15 cyclomatic complexity** (branches +
+  loops + boolean operators). If you're past that, extract helpers.
+- One function = one responsibility. A function that **parses, validates, and
+  emits is three functions** — split it before committing, not "later."
+- The refactor step of red-green-refactor is where this happens. Don't skip it
+  because the tests already pass.
+
+## Type safety — no compiler-silencing assertions
+
+The gate requires `tsc` (or the project's typechecker) to pass — but passing it
+by *suppressing* it is a regression, not a fix. **Never** use `as any`, an
+unchecked `as`-cast, `@ts-ignore`/`@ts-expect-error`, `# type: ignore`, or the
+equivalent to:
+
+- silence a compiler error instead of fixing the underlying type, or
+- bypass a validator/guard the same code path defines (e.g. casting past a Zod
+  schema, a runtime type guard, or a parse function so the value skips the very
+  check that file exists to enforce).
+
+If the types genuinely can't express something, narrow with a real type guard or
+fix the type — don't assert your way past it.

package/skills/chat/SKILL.md

@@ -1,17 +1,36 @@
+---
+name: chat
+description: Conversational assistant for messaging-platform threads (Slack, Discord). Answer questions about repos, PRs, and issues, explain code, and guide users to natural-language triggers (e.g. "build owner/repo#N", "triage owner/repo", "review PRs on owner/repo", "status").
+---
+
 # Chat
 
-Conversational assistant for messaging platforms (Slack, Discord, etc.).
+You are answering in a messaging thread (Slack, Discord). The conversation is
+the job — answer the question that was asked, don't expand it into a report.
+
+## What you do
+
+- Answer questions about repositories, issues, pull requests, and code.
+- Explain how the bot's workflows behave.
+- Report status on running work when asked.
+
+## What you don't do
+
+Chat is **read-and-explain only**. You don't review PRs, triage issues, run
+builds, or change anything. When the user wants an *action*, name the
+natural-language trigger and stop:
 
-## Behavior
+- code changes → `build owner/repo#N`
+- issue triage → `triage owner/repo`
+- PR review → `review PRs on owner/repo`
+- security scan → `security review owner/repo`
+- running-task status → `status`
 
-- Answer questions about repositories, issues, and pull requests
-- Explain code and development workflows
-- Provide status on running tasks when asked
-- Suggest commands for actions: `/build`, `/triage`, `/review`, `/status`
+Phrase triggers as natural language — never with a leading `/`, which Slack
+intercepts before it reaches Last Light.
 
-## Guidelines
+## Style
 
-- Keep responses concise — messaging platforms have limited rendering
-- Use markdown sparingly (bold for emphasis, code blocks for code)
-- Be direct and actionable
-- If the user wants to trigger an action, guide them to the appropriate slash command
+- Concise — messaging panes are narrow. A few sentences beats a wall of text.
+- Markdown sparingly: bold for emphasis, fenced blocks for code.
+- Lead with the answer. Cite `path:line` when pointing at code.

package/skills/code-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: code-review
+description: The shared rubric for reviewing a code change — finding tiers (Critical/Important/Suggestions/Nits) and what to check (correctness, security, edge cases, regression risk, test coverage). Use when reviewing a PR or a branch diff.
+version: 1.0.0
+tags: [review, code-quality]
+---
+
+# Code Review
+
+The shared rubric for assessing a code change. Used both by a PR review and by
+the build cycle's branch-diff reviewer — the *procedure* differs (where the diff
+comes from, how the verdict is recorded), but the rubric below is the same.
+
+Review the change **in full context** — read each changed file, not just the
+hunk. For a large change (>300 lines or >5 files): trace data flow through
+modified functions, check callers of anything whose signature or behaviour
+changed for regression risk, and check that tests cover the actual risk areas,
+not just the happy path.
+
+## Finding tiers
+
+Categorise every finding into exactly one tier:
+
+- **Critical** — security issues, data loss, breaking changes, silent
+  data-dropping (see Correctness below). Blocks merge.
+- **Important** — missing tests, performance problems, type errors, **avoidable
+  duplication**, **excessive complexity**, **compiler-silencing assertions**.
+  Should fix.
+- **Suggestions** — clarity, naming, minor DRY tidy-ups. Nice to have.
+- **Nits** — style, formatting. Optional.
+
+## What to check
+
+- **Correctness** — does it do what it claims? Logic errors, off-by-one, wrong
+  conditions, mishandled async. **A silent default or a dropped output for an
+  input the code doesn't support is a correctness bug, not graceful handling** —
+  flag any unsupported case that is silently defaulted, skipped, or omitted
+  instead of warned-and-skipped or warned-and-surfaced.
+- **Edge cases** — empty/null inputs, boundaries, error paths, concurrency.
+- **Security** — injection, auth/authorization, secret handling, untrusted input.
+- **Complexity** — flag functions past ~15 cyclomatic complexity or that mix
+  parse/validate/emit responsibilities; ask for helper extraction. This is an
+  **Important** finding, not a nit.
+- **Duplication** — flag avoidable duplicated logic (two or more clone groups of
+  the same code/branching). DRY is **should-fix** here, not merely "nice to have."
+- **Type safety** — flag `as any`, unchecked `as`-casts, or `@ts-ignore` used to
+  silence the compiler or to bypass a validator the same code path defines.
+- **Regression risk** — existing callers of changed functions; behaviour changes
+  that ripple.
+- **Test coverage** — do the tests exercise the real risk, or just the happy path?
+- **Fit** — does it match the codebase's existing patterns and conventions?
+
+## Calibration
+
+- Don't nitpick generated files (lockfiles, compiled assets).
+- Don't repeat what linters/CI already catch.
+- Don't block over style preferences alone.
+- Read the room: if a human reviewer already approved, lower the bar for blocking
+  — prefer a comment over requesting changes on non-critical findings.

package/skills/debug-production/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: debug-production
+description: Debug a running Last Light instance (usually production) via the `lastlight` CLI instead of SSH. Use when investigating a failed/stuck workflow, a bad agent run, a phase error, or "why didn't the bot do X" — anything that previously meant SSHing in to read SQLite or session logs.
+version: 1.0.0
+tags: [ops, debugging, cli]
+---
+
+# Debug a Last Light instance via the CLI
+
+Read a running instance's state over its admin API with the `lastlight` CLI —
+no SSH, no poking SQLite or jsonl files on the box. Every command takes
+`--json` for machine-parseable output; prefer it when you need to extract
+fields.
+
+## 0. Connect
+
+The CLI talks to whatever instance you logged into (saved in
+`~/.lastlight/config.json`). Confirm you're pointed at the right one and the
+token is valid:
+
+```bash
+lastlight status            # instance URL, server health, token validity
+```
+
+If the token is missing/expired, authenticate (the prod instance URL lives in
+local agent memory — see the "Last Light production server" note):
+
+```bash
+lastlight login https://<instance>     # browser handoff (password/Slack/GitHub)
+lastlight login https://<instance> --password   # headless fallback
+```
+
+For one-off targeting without saving, pass `--url` / `--token` on any command,
+or set `LASTLIGHT_URL` / `LASTLIGHT_TOKEN` (env wins over the saved config).
+
+## 1. Find the broken run
+
+```bash
+lastlight workflow list --status failed          # recent failures
+lastlight workflow list --status active          # running + paused now
+lastlight workflow list --workflow pr-review --limit 50
+```
+
+Copy the run `ID` from the table.
+
+## 2. Inspect the run's phases
+
+```bash
+lastlight workflow log <run-id>          # run header + per-phase table (✓/✗, duration, session id, error)
+lastlight workflow log <run-id> --follow # then tail the current phase live
+```
+
+The phase table shows which phase failed, its error snippet, and the `SESSION`
+id you need for the transcript.
+
+## 3. Read / tail the agent transcript
+
+```bash
+lastlight session list                   # recent sandbox sessions (TYPE, MODEL, LIVE)
+lastlight session log <session-id>       # full transcript
+lastlight session log <session-id> --follow   # live tail (SSE) of an in-flight phase
+```
+
+## 4. Search across runs
+
+```bash
+lastlight logs search "ECONNREFUSED"                 # errors ledger (default)
+lastlight logs search "rate limit" --scope all       # errors + transcript content
+lastlight logs search "could not clone" --scope messages --limit 20
+```
+
+`--scope errors` (default) matches the executions ledger (error/skill/repo);
+`messages` greps recent session transcripts; `all` does both.
+
+## 5. Raw server / docker logs
+
+When the workflow + session views aren't enough — a crash before any session
+was written, a sidecar misbehaving, harness boot errors — read the actual
+container logs (`docker logs`) over the API:
+
+```bash
+lastlight server list                    # the lastlight-* containers + status
+lastlight server logs                    # the agent harness (default), last 200 lines
+lastlight server logs --tail 500 --since 10m
+lastlight server logs --follow           # live tail (Ctrl-C to stop)
+lastlight server logs coredns-strict     # a specific sidecar by service or container name
+```
+
+## 6. Approvals & health
+
+```bash
+lastlight approvals list                 # paused gates waiting on a human
+lastlight approvals approve <id> --reason "looks good"
+lastlight approvals reject  <id> --reason "wrong approach"
+
+lastlight stats                          # totals + per-skill success/fail
+lastlight stats --daily 14               # last 14 days of cost/tokens
+```
+
+## Tips
+
+- Add `--json` to any command to pipe into `jq` (e.g.
+  `lastlight workflow list --status failed --json | jq -r '.workflowRuns[].id'`).
+- Triage flow: `workflow list --status failed` → `workflow log <id>` → grab the
+  failed phase's session → `session log <session-id>` → if it's a recurring
+  symptom, `logs search "<error text>"` to see how often it happens.
+- These are read-only except `approvals approve/reject` and the trigger
+  commands (`build`/`triage`/`review`/…) — debugging never mutates the box.