lastlight 0.5.1 → 0.6.1

package/dist/skills-install.js

@@ -0,0 +1,179 @@
+/**
+ * Host-local `lastlight skills …` — install the Last Light Claude Code skills
+ * into a local Claude Code instance.
+ *
+ * The skills live in this package's `plugins/lastlight/` tree (shipped via the
+ * package `files` allowlist) and are also exposed as a Claude Code marketplace
+ * via `.claude-plugin/marketplace.json` at the package root. Two install paths:
+ *
+ *  1. **Marketplace** (preferred when the `claude` CLI is present): register the
+ *     bundled marketplace by local path and install the plugin. Using the
+ *     bundled path keeps the installed skills version-matched to this CLI and
+ *     works offline — no dependency on the core repo being public.
+ *  2. **Copy fallback** (no `claude` CLI): copy each `skills/<name>/` directory
+ *     into the scope's skills dir (`~/.claude/skills` for user,
+ *     `<cwd>/.claude/skills` for project), which Claude Code auto-discovers with
+ *     no marketplace at all.
+ *
+ * Like `lastlight fork` / `lastlight server`, this operates on local files — not
+ * over HTTP.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import chalk from "chalk";
+/** Marketplace + plugin identifiers — must match `.claude-plugin/marketplace.json`. */
+const MARKETPLACE_NAME = "lastlight-skills";
+const PLUGIN_NAME = "lastlight";
+// ── bundle resolution ────────────────────────────────────────────────────────
+/**
+ * Package root that holds `.claude-plugin/marketplace.json` and
+ * `plugins/<plugin>/`. Resolves for both dev (`src/skills-install.ts` → repo
+ * root) and compiled/installed (`dist/skills-install.js` → package root).
+ */
+function bundleRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+function pluginDir() {
+    return path.join(bundleRoot(), "plugins", PLUGIN_NAME);
+}
+function skillsSrcDir() {
+    return path.join(pluginDir(), "skills");
+}
+/** Names of the bundled skill directories (each holding a SKILL.md). */
+function bundledSkillNames() {
+    const dir = skillsSrcDir();
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, "SKILL.md")))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function assertBundlePresent() {
+    if (bundledSkillNames().length === 0) {
+        throw new Error(`No bundled skills found under ${skillsSrcDir()} — the package may be built without the plugins/ assets.`);
+    }
+}
+// ── scope paths ──────────────────────────────────────────────────────────────
+function scopeSkillsDir(scope) {
+    const base = scope === "project" ? process.cwd() : os.homedir();
+    return path.join(base, ".claude", "skills");
+}
+// ── claude CLI detection ─────────────────────────────────────────────────────
+function hasClaudeCli() {
+    const probe = spawnSync("claude", ["--version"], { stdio: "ignore" });
+    return probe.status === 0;
+}
+/** Run a `claude` subcommand, inheriting stdio so the user sees progress. */
+function claude(args) {
+    const res = spawnSync("claude", args, { stdio: "inherit" });
+    return res.status === 0;
+}
+// ── copy fallback ────────────────────────────────────────────────────────────
+function copySkills(scope) {
+    const destRoot = scopeSkillsDir(scope);
+    fs.mkdirSync(destRoot, { recursive: true });
+    const installed = [];
+    for (const name of bundledSkillNames()) {
+        const src = path.join(skillsSrcDir(), name);
+        const dest = path.join(destRoot, name);
+        // Bundle skills are managed artifacts — replace any existing copy so it
+        // tracks this CLI version.
+        fs.rmSync(dest, { recursive: true, force: true });
+        fs.cpSync(src, dest, { recursive: true });
+        installed.push(name);
+    }
+    return installed;
+}
+// ── commands ─────────────────────────────────────────────────────────────────
+export async function skillsInstall(opts) {
+    assertBundlePresent();
+    const scope = opts.scope ?? "user";
+    const names = bundledSkillNames();
+    // Preferred: register the bundled marketplace + install via the claude CLI.
+    if (!opts.noMarketplace && hasClaudeCli()) {
+        console.log(chalk.dim(`Using the claude CLI (marketplace: ${bundleRoot()})`));
+        // `marketplace add` may report "already added" — non-fatal; proceed to install.
+        claude(["plugin", "marketplace", "add", bundleRoot()]);
+        const ok = claude(["plugin", "install", `${PLUGIN_NAME}@${MARKETPLACE_NAME}`, "--scope", scope]);
+        if (ok) {
+            console.log(chalk.green(`✓ Installed ${PLUGIN_NAME}@${MARKETPLACE_NAME}`) +
+                chalk.dim(` (${scope} scope) — ${names.length} skills`));
+            console.log(chalk.dim("  Start a new Claude Code session to use them."));
+            return;
+        }
+        console.log(chalk.yellow("claude plugin install failed — falling back to copying skills."));
+    }
+    // Fallback: copy skill dirs into the scope's skills directory.
+    const installed = copySkills(scope);
+    const destRoot = scopeSkillsDir(scope);
+    console.log(chalk.green(`✓ Copied ${installed.length} skills`) +
+        chalk.dim(` → ${destRoot}`));
+    for (const n of installed)
+        console.log(chalk.dim(`  • ${n}`));
+    console.log(chalk.dim("  Start a new Claude Code session to use them."));
+}
+export async function skillsList(opts) {
+    assertBundlePresent();
+    const names = bundledSkillNames();
+    const userDir = scopeSkillsDir("user");
+    const projDir = scopeSkillsDir("project");
+    console.log(chalk.bold(`Bundled Last Light skills (${names.length})`));
+    for (const n of names) {
+        const marks = [];
+        if (fs.existsSync(path.join(userDir, n)))
+            marks.push("user");
+        if (fs.existsSync(path.join(projDir, n)))
+            marks.push("project");
+        const where = marks.length ? chalk.green(` [installed: ${marks.join(", ")}]`) : chalk.dim(" [not installed]");
+        console.log(`  • ${n}${where}`);
+    }
+    console.log(chalk.dim(`\nInstall: lastlight skills install [--scope user|project]\n` +
+        `Marketplace: ${PLUGIN_NAME}@${MARKETPLACE_NAME} (${bundleRoot()})`));
+}
+export async function skillsUninstall(opts) {
+    const scope = opts.scope ?? "user";
+    // Best-effort marketplace uninstall if the claude CLI is present.
+    if (!opts.noMarketplace && hasClaudeCli()) {
+        claude(["plugin", "uninstall", `${PLUGIN_NAME}@${MARKETPLACE_NAME}`, "--scope", scope]);
+    }
+    // Remove any copied skill dirs in this scope.
+    const destRoot = scopeSkillsDir(scope);
+    let removed = 0;
+    for (const n of bundledSkillNames()) {
+        const dest = path.join(destRoot, n);
+        if (fs.existsSync(dest)) {
+            fs.rmSync(dest, { recursive: true, force: true });
+            removed++;
+        }
+    }
+    console.log(chalk.green(`✓ Uninstalled Last Light skills`) +
+        chalk.dim(` (${scope} scope${removed ? `, removed ${removed} copied dirs` : ""})`));
+}
+/** Entry point dispatched from `src/cli.ts` for `lastlight skills …`. */
+export async function skills(args, opts) {
+    const sub = args[0] ?? "install";
+    switch (sub) {
+        case "install":
+            return skillsInstall(opts);
+        case "list":
+            return skillsList(opts);
+        case "uninstall":
+        case "remove":
+            return skillsUninstall(opts);
+        default:
+            console.error("Usage:\n" +
+                "  lastlight skills install [--scope user|project] [--no-marketplace]\n" +
+                "  lastlight skills list\n" +
+                "  lastlight skills uninstall [--scope user|project]");
+            process.exit(1);
+    }
+}
+//# sourceMappingURL=skills-install.js.map

package/dist/skills-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-install.js","sourceRoot":"","sources":["../src/skills-install.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lastlight",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "GitHub repository maintenance agent — Agent SDK harness",
   "type": "module",
   "main": "dist/index.js",
@@ -24,7 +24,9 @@
     "agent-context",
     "deploy",
     "sandbox.Dockerfile",
-    "docker-compose.yml"
+    "docker-compose.yml",
+    ".claude-plugin",
+    "plugins"
   ],
   "repository": {
     "type": "git",

package/plugins/lastlight/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin.json",
+  "name": "lastlight",
+  "displayName": "Last Light",
+  "version": "0.6.1",
+  "description": "Install, configure and operate Last Light (GitHub maintenance agent) — its server, CLI client, deployment overlay, and the Last Light Evals harness.",
+  "author": { "name": "Clifton Cunningham" },
+  "homepage": "https://github.com/cliftonc/lastlight",
+  "repository": "https://github.com/cliftonc/lastlight",
+  "license": "MIT",
+  "keywords": ["lastlight", "github-agent", "evals", "devops", "setup", "docker"]
+}

package/plugins/lastlight/README.md

@@ -0,0 +1,44 @@
+# Last Light — Claude Code plugin
+
+A bundle of [Claude Code](https://docs.claude.com/en/docs/claude-code) skills
+that help you install, configure and operate **Last Light** (a GitHub
+repository-maintenance agent) and **Last Light Evals** (its eval harness).
+
+These are *Claude Code* skills — they run on your machine and drive the
+`lastlight` / `lastlight-evals` CLIs for you. They are distinct from Last
+Light's *internal* sandbox skills under the repo's top-level `skills/` dir
+(which are staged into the agent's own workflows).
+
+## Skills
+
+| Skill | Use it when you want to… |
+|-------|--------------------------|
+| `lastlight-server` | Install & configure a Last Light **server** (the agent + docker stack) on a host. |
+| `lastlight-client` | Point the `lastlight` **CLI client** at an existing server and log in. |
+| `lastlight-overlay` | Create a deployment **overlay** instance and fork/customize workflows, prompts, skills, or the agent persona. |
+| `lastlight-evals` | Scaffold and run a **Last Light Evals** workspace (datasets, models, model comparisons). |
+
+## Install
+
+**Fastest — via the lastlight CLI** (installs the version-matched skills bundled
+with the CLI, no marketplace registration needed):
+
+```bash
+npm i -g lastlight
+lastlight skills install            # → ~/.claude/skills (user scope)
+lastlight skills install --scope project   # → ./.claude/skills (this repo only)
+```
+
+**Via the Claude Code plugin marketplace** (from a checkout of this repo):
+
+```bash
+claude plugin marketplace add ./        # or: cliftonc/lastlight if public
+claude plugin install lastlight@lastlight-skills
+```
+
+**Manual** — copy any `skills/<name>/` directory here into `~/.claude/skills/`
+(personal, all projects) or a project's `.claude/skills/`. Claude Code
+auto-discovers them on the next session.
+
+After installing, start a new Claude Code session and say e.g. *"set up a Last
+Light server"* or *"scaffold a Last Light evals workspace"*.

package/plugins/lastlight/skills/lastlight-client/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: lastlight-client
+description: Install the `lastlight` CLI and connect it as a CLIENT to an existing Last Light server — log in, save the token, and verify the connection. Use when the user wants to "connect / point my lastlight CLI at a server", "log in to Last Light", "set up the lastlight client", or run lastlight commands against a remote instance. For standing up the server itself use lastlight-server; for editing a deployment's config use lastlight-overlay.
+version: 1.0.0
+tags: [lastlight, client, cli, login, auth]
+---
+
+# Install & configure the Last Light CLI client
+
+The `lastlight` CLI is a thin HTTP client: it POSTs triggers and reads a running
+instance's admin API. As a *client* it needs only the instance URL and an auth
+token, saved to `~/.lastlight/config.json` (mode 0600).
+
+## 1. Install the CLI
+
+```bash
+command -v lastlight >/dev/null && echo "installed" || npm i -g lastlight
+```
+
+## 2. Get the server URL
+
+Ask the user for the instance URL (e.g. `https://lastlight.example.com`). If they
+don't know it, they need it from whoever runs the server.
+
+## 3. Log in
+
+Two paths — pick based on environment:
+
+- **Browser handoff (default, interactive desktop):**
+  ```bash
+  lastlight login https://lastlight.example.com
+  ```
+  Opens the dashboard; the user authenticates with whatever method the server
+  has (password / Slack / GitHub OAuth) and the token is captured automatically.
+
+- **Headless / no browser (SSH, CI, server box):**
+  ```bash
+  lastlight login https://lastlight.example.com --password
+  ```
+  Prompts for the admin password and POSTs it to `/admin/api/login`. Requires the
+  server to have `ADMIN_PASSWORD` set.
+
+The token (≈7-day TTL) is saved to `~/.lastlight/config.json`.
+
+## 4. Verify
+
+```bash
+lastlight status
+```
+
+Confirm: **Server healthy**, **Token valid**. If the token shows
+`expired/invalid`, re-run `lastlight login`.
+
+## Overrides & alternatives
+
+- Skip the saved file with env vars or flags (precedence: flags → env → saved
+  file → default `http://localhost:8644`):
+  ```bash
+  LASTLIGHT_URL=https://ll.example.com LASTLIGHT_TOKEN=... lastlight status
+  lastlight status --url https://ll.example.com --token ...
+  ```
+- `lastlight logout` clears the saved config.
+- One-shot wizard: `lastlight setup --client` is equivalent to `lastlight login`.
+
+## What you can do once connected
+
+```bash
+lastlight chat "hello"                 # chat with the bot (REPL if no message)
+lastlight owner/repo#123               # triage an issue (default, cheap)
+lastlight build owner/repo#123         # full build cycle
+lastlight triage|review owner/repo[#N] # repo scan or single issue/PR
+lastlight health|security owner/repo   # repo-level report
+lastlight workflow list|log <id>       # inspect runs
+lastlight session list|log <id> -f     # tail a sandbox session
+lastlight logs search "<text>"         # search errors / transcripts
+lastlight approvals list|approve|reject
+```
+
+## Done when
+
+`lastlight status` reports the server healthy and the token valid. Report the
+connected instance URL and a couple of commands the user can run next.

package/plugins/lastlight/skills/lastlight-evals/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: lastlight-evals
+description: Scaffold, configure and run a Last Light EVALS workspace — the harness that runs Last Light's real workflows against a mocked GitHub and grades them deterministically. Use when the user wants to "set up / scaffold Last Light Evals", "create an evals workspace or instance", "run evals", "compare models", or author new eval cases (triage / code-fix instances). GitHub is mocked, so no real GitHub token is needed — only a model provider API key.
+version: 1.0.0
+tags: [lastlight, evals, benchmark, models, swe-bench]
+---
+
+# Set up & run Last Light Evals
+
+`lastlight-evals` runs Last Light's **real** production workflows (issue-triage,
+build, …) end-to-end against a mocked GitHub, grades the results deterministically
+(no LLM-as-judge), and compares models on pass rate, cost, and latency. It's a
+thin CLI on top of the `lastlight` core package (via the `lastlight/evals`
+barrel), so it exercises the same workflows/skills production does. SWE-bench
+compatible. **Node 24+.**
+
+## 1. Check prerequisites
+
+```bash
+node --version    # need >= 24
+command -v lastlight-evals >/dev/null && echo "installed" || npm i -g lastlight-evals
+```
+
+## 2. Scaffold a workspace
+
+```bash
+lastlight-evals init my-evals       # or: lastlight-evals init  (→ ./lastlight-evals-workspace)
+```
+
+This scaffolds an **overlay + evals** workspace:
+- `workflows/`, `skills/`, `agent-context/` — empty dirs for override assets
+- `evals/datasets/` — seeded from the built-in `triage` + `code-fix` samples
+- `evals/models.json` — a copy of the built-in model registry
+- `config.yaml`, `.gitignore`, `README.md`
+- optionally `git init` + a private `gh repo create`
+
+## 3. Configure providers (`.env`)
+
+Create `.env` in the workspace with **at least one** provider key. GitHub is
+mocked end-to-end, so **no real GitHub token is needed** (the harness sets a
+dummy one internally).
+
+```dotenv
+# any one (or more) of:
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+FIREWORKS_API_KEY=fw-...
+OPENROUTER_API_KEY=sk-or-...
+DEEPSEEK_API_KEY=...
+```
+
+Useful optional vars: `EVAL_MODELS` (comma-list override), `LASTLIGHT_EVALS_OUT`
+(scorecard dir, default `./eval-results/`), `LASTLIGHT_CORE_DIR` (point at a local
+lastlight checkout to eval un-published asset edits), `CI=1` (don't open a
+browser). See **`references/models-json.md`** for the model registry format and
+how `--compare` is key-gated.
+
+## 4. Run
+
+```bash
+cd my-evals
+lastlight-evals run --overlay .                 # default model, triage tier
+lastlight-evals run triage --overlay .          # one tier
+lastlight-evals run triage code-fix --overlay . # multiple tiers
+lastlight-evals run triage --model haiku        # fuzzy match in models.json
+lastlight-evals run triage --model openai/gpt-5.5,anthropic/claude-opus-4-8
+lastlight-evals run --compare                   # cross-vendor set (only models whose envKey is present)
+lastlight-evals run triage --runs 3             # repeat each case 3× (worst-case verdict, mean metrics)
+lastlight-evals run triage --no-open            # don't open the report
+```
+
+Output lands in `./eval-results/<tiers>/`: `index.html` (scorecard),
+`scorecard.json`, `predictions.jsonl` (SWE-bench format). Re-render a report
+without re-running: `lastlight-evals report ./eval-results/triage`.
+
+## 5. Author eval cases (optional)
+
+Two tiers ship: **triage** (cheap, issue-triage) and **code-fix** (heavy, build
+workflow with held-out tests). To add cases or a custom tier, read
+**`references/instance-schema.md`** — it has the `SweBenchInstance` schema, the
+exact files to create for each tier, and worked examples.
+
+Quick shape:
+- **Triage case:** append a `SweBenchInstance` to `datasets/triage/instances.json`
+  with `issue`, `triage_gold`, and `expect_github`.
+- **Code-fix case:** add the instance to `datasets/code-fix/instances.json` **and**
+  create `datasets/code-fix/repos/<instance_id>/` (fixture repo at base) +
+  `datasets/code-fix/tests/<instance_id>/` (held-out tests applied at grade time).
+- **Custom tier:** a new `datasets/<tier>/` with `tier.json` +
+  `instances.json` (+ `repos/` & `tests/` for code-fix-style tiers). Discovery is
+  automatic — no code change.
+
+## Done when
+
+The workspace is scaffolded, `.env` has a working provider key, and a run
+produces a scorecard under `eval-results/`. Report the workspace path, the
+provider(s) configured, and the command to run/compare.

package/plugins/lastlight/skills/lastlight-evals/references/instance-schema.md

@@ -0,0 +1,84 @@
+# Eval instance schema & authoring cases
+
+An eval case is a **`SweBenchInstance`** — SWE-bench-compatible core fields plus
+Last Light extensions (the GitHub fixtures + behavioral expectations that let the
+harness drive and grade the real workflow against a mocked GitHub).
+
+Datasets are discovered from (overlay > user > built-in): `<overlay>/evals/datasets/`,
+`--datasets <dir>` / `LASTLIGHT_EVALS_DATASETS`, and the package's built-in
+`datasets/`. A tier is a directory with a `tier.json` and an `instances.json`.
+
+## `tier.json`
+
+```json
+{ "name": "triage", "defaultWorkflow": "issue-triage", "description": "..." }
+```
+
+## `SweBenchInstance` fields
+
+```jsonc
+{
+  // ── SWE-bench core ──
+  "instance_id": "triage__my-case",      // unique id
+  "repo": "owner/repo",                   // logical; fixture origin is a local bare repo
+  "base_commit": "0000000...",            // code-fix only
+  "problem_statement": "short issue text",
+  "patch": "...",                          // gold patch — reference only, NOT graded
+  "test_patch": "...",                     // held-out tests (code-fix)
+  "FAIL_TO_PASS": ["test id 1"],          // must go red→green (code-fix)
+  "PASS_TO_PASS": ["test id 2"],          // must stay green (code-fix)
+
+  // ── Last Light extensions ──
+  "workflow": "issue-triage",             // optional; defaults to the tier's defaultWorkflow
+  "issue": {                               // seed state for the fake GitHub
+    "number": 110, "title": "...", "body": "...",
+    "labels": [], "user": "alice",
+    "comments": [{ "user": "bob", "body": "..." }],
+    "state": "open"
+  },
+  "triage_gold": { "category": "bug", "state": "ready-for-agent" },  // triage grading
+  "expect_github": {                       // behavioral assertions on recorded GitHub calls
+    "labels_added": ["bug"],
+    "labels_absent": ["wontfix"],
+    "issue_closed": false,
+    "comment_matches": "(?i)thanks",
+    "pr_opened": { "base": "main", "head_is_branch": true, "title_matches": "(?i)fix" }
+  }
+}
+```
+
+Every `expect_github` field is optional — only the present ones are checked.
+
+## Add a triage case
+
+Append a `SweBenchInstance` to `datasets/triage/instances.json` with `issue`,
+`triage_gold`, and the `expect_github` assertions (e.g. `labels_added`). That's
+it — triage is graded on the triage decision + GitHub mutations.
+
+## Add a code-fix case (three things, keyed by `instance_id`)
+
+1. **`datasets/code-fix/instances.json`** — append the instance with
+   `base_commit`, `FAIL_TO_PASS`, `PASS_TO_PASS`, `issue`, and `expect_github`
+   (e.g. `pr_opened`).
+2. **`datasets/code-fix/repos/<instance_id>/`** — the fixture repo at the base
+   commit (the buggy code *before* the fix; no held-out tests here).
+3. **`datasets/code-fix/tests/<instance_id>/`** — the held-out test files, copied
+   into the repo at grade time and run to compute `FAIL_TO_PASS` / `PASS_TO_PASS`.
+
+## Add a custom tier
+
+Create `datasets/<tier-name>/` with `tier.json` (`name`, `defaultWorkflow`,
+`description`) + `instances.json`. For code-fix-style tiers also add `repos/<id>/`
+and `tests/<id>/`. Discovery auto-finds it — no code change. Run it with
+`lastlight-evals run <tier-name> --overlay .`.
+
+## Grading (how a case passes)
+
+- **Behavioral:** did the workflow take the expected GitHub actions
+  (`expect_github`)?
+- **Triage:** did the decision match `triage_gold`?
+- **Execution (code-fix):** all `FAIL_TO_PASS` green AND all `PASS_TO_PASS` still
+  green after applying held-out tests.
+- With `--runs N` (N>1) the binary verdict is **worst-case** (passes only if every
+  trial passed); the scorecard also shows per-verdict pass counts to expose
+  variance.

package/plugins/lastlight/skills/lastlight-evals/references/models-json.md

@@ -0,0 +1,42 @@
+# Model registry — `models.json`
+
+The eval harness picks models from a `models.json`. Resolution: the scaffolded
+`evals/models.json` is picked up automatically (or pass `--models-file <path>`).
+
+```json
+{
+  "default": "openai/gpt-5.4-mini",
+  "compare": [
+    { "id": "openai/gpt-5.5",            "label": "GPT-5.5",        "provider": "OpenAI",          "envKey": "OPENAI_API_KEY" },
+    { "id": "anthropic/claude-opus-4-8", "label": "Claude Opus 4.8","provider": "Anthropic",       "envKey": "ANTHROPIC_API_KEY" },
+    { "id": "fireworks/accounts/fireworks/models/glm-5p2", "label": "GLM-5.2", "provider": "Fireworks (open)", "envKey": "FIREWORKS_API_KEY" }
+  ]
+}
+```
+
+Fields:
+- **`default`** — the single model `run` uses when not `--compare`.
+- **`compare`** — the cross-vendor set `--compare` runs. **Each entry runs only if
+  its `envKey` is present** in the environment, so you can list many and only the
+  ones you have keys for execute. Add/remove freely.
+- Per entry: `id` is the agentic-pi/pi-ai `provider/model` spec; `label` is the
+  scorecard display name; `provider` is a grouping label; `envKey` is the env var
+  that gates it.
+
+## Selecting models on the CLI
+
+```bash
+lastlight-evals run triage --model haiku                 # fuzzy substring match against ids/labels
+lastlight-evals run triage --model openai/gpt-5.5        # exact provider/model id
+lastlight-evals run triage --model glm,deepseek          # comma-list
+lastlight-evals run --compare                            # the whole compare set (key-gated)
+```
+
+You can also override the set with `EVAL_MODELS=<comma-list>` in the environment.
+
+## Provider keys
+
+Set whichever provider keys you have in the workspace `.env`:
+`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `FIREWORKS_API_KEY` (GLM / DeepSeek /
+GPT-OSS), `OPENROUTER_API_KEY`, `DEEPSEEK_API_KEY`. No GitHub credentials needed —
+GitHub is mocked.

package/plugins/lastlight/skills/lastlight-overlay/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: lastlight-overlay
+description: Create or customize a Last Light deployment OVERLAY (the private instance/ repo) — scaffold it, then fork built-in workflows, prompts, skills, or the agent persona (agent-context) so a deployment can override them. Use when the user wants to "create a Last Light overlay / instance repo", "customize / fork a workflow", "override a prompt or skill", "change the agent's persona/soul/rules", or tune a deployment's config without forking the whole codebase. For first-time server install use lastlight-server.
+version: 1.0.0
+tags: [lastlight, overlay, instance, fork, workflows, customization]
+---
+
+# Create & customize a Last Light overlay
+
+Last Light keeps per-deployment customization in a private **overlay** at
+`instance/`, layered over the packaged defaults at startup. The overlay can hold
+`config.yaml`, `secrets/`, and overrides of any asset — `workflows/`,
+`workflows/prompts/`, `skills/`, `agent-context/`. An overlay copy **shadows the
+built-in by logical name**, so you only fork what you want to change.
+
+These are host-local file operations on the working directory (resolved from
+`--home` → `LASTLIGHT_HOME` → saved `serverHome` → `~/lastlight`).
+
+## 1. Scaffold or adopt the overlay
+
+```bash
+lastlight server setup
+```
+
+This scaffolds/adopts the working directory: clones the core repo if needed, then
+**creates a fresh overlay** (scaffold + optional private `gh repo create`) or
+**clones an existing** overlay repo — your choice at the prompt. It also symlinks
+`instance/docker-compose.override.yml` and saves the working dir for later
+`lastlight server …` commands.
+
+Read **`references/overlay-layout.md`** for the full directory shape and how the
+layering/merge rules work (arrays replace, maps deep-merge, overlay wins by
+name).
+
+## 2. Tune non-secret config
+
+Edit `instance/config.yaml` to set `managedRepos`, and optionally override
+`models`, `variants`, `routes`, `approvals`, `disabled.*`. Secrets stay in
+`instance/secrets/.env` (never in config.yaml).
+
+## 3. Fork built-in assets to customize them
+
+Use `lastlight fork` — it copies a built-in into `instance/` so your edited copy
+shadows the default. Read **`references/forking.md`** for exactly what each fork
+copies and the editing workflow.
+
+```bash
+lastlight fork                     # list forkable workflows + agent-context (marks what's already forked)
+lastlight fork <workflow>          # copy a workflow YAML + every prompt & skill its phases reference
+lastlight fork agent-context       # copy soul.md / rules.md / security.md (the persona)
+lastlight fork agent-context soul.md   # just one persona file
+#   add --force to overwrite an existing overlay copy; --home <dir> to target a specific working dir
+```
+
+Then edit the copied files under `instance/…`.
+
+## 4. Apply
+
+- **Config-only or overlay-asset edits** (committed to the overlay): take effect
+  with `lastlight server restart agent` — no image rebuild.
+- If the overlay is a separate git repo, commit + push there first, then restart.
+
+```bash
+lastlight server status            # shows forked/overridden assets + version drift
+lastlight server restart agent
+```
+
+## Done when
+
+The overlay exists with the intended `config.yaml` and any forked assets under
+`instance/`, `lastlight server status` lists the overrides, and the agent has
+been restarted to apply them. Report which assets were forked and where they live.