lastlight 0.4.0 → 0.6.1

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.

package/plugins/lastlight/skills/lastlight-overlay/references/forking.md

@@ -0,0 +1,55 @@
+# Forking built-in assets with `lastlight fork`
+
+`lastlight fork` copies a built-in asset into the overlay (`instance/`) so your
+edited copy shadows the default by logical name. It's host-local — it operates on
+the working directory's files, not over HTTP.
+
+Path resolution: an explicit `--home <dir>` wins; otherwise if you're standing in
+an overlay it writes there (reading built-ins from the parent checkout); if
+you're in a core checkout it writes to `<checkout>/instance`; else it falls back
+to `LASTLIGHT_HOME` / the saved server home / `~/lastlight`.
+
+## Commands
+
+```bash
+lastlight fork                       # list forkable workflows + agent-context files; marks what's already forked
+lastlight fork <workflow>            # e.g. `lastlight fork build`
+lastlight fork agent-context         # all of soul.md / rules.md / security.md
+lastlight fork agent-context <file>  # a single persona file, e.g. soul.md
+```
+
+Flags: `--force` overwrites an existing overlay copy (otherwise existing files
+are skipped); `--home <dir>` targets a specific working directory.
+
+## What each fork copies
+
+- **`lastlight fork <workflow>`** copies the workflow YAML
+  (`workflows/<name>.yaml`) **plus every prompt and skill its phases reference**
+  (`workflows/prompts/*.md`, `skills/<name>/`). So the forked workflow is
+  self-contained and editable in the overlay. Existing destinations are skipped
+  unless `--force`.
+- **`lastlight fork agent-context [file]`** copies the agent "personality" files
+  (`agent-context/*.md` — typically `soul.md`, `rules.md`, `security.md`) into
+  `instance/agent-context/`. With no file argument it forks all of them; pass a
+  filename for just one.
+
+`agent-context` is forked only via the literal `agent-context` target — a bare
+name is always treated as a workflow.
+
+## Editing workflow
+
+1. Fork the asset.
+2. Edit the copy under `instance/…`.
+3. If the overlay is its own git repo, commit + push there.
+4. Apply: `lastlight server restart agent` (config/asset overlay change — no
+   image rebuild).
+5. Confirm with `lastlight server status` (lists forked/overridden assets) and
+   the dashboard `/config` view.
+
+## Common targets
+
+- Workflows: `build`, `pr-fix`, `pr-review`, `issue-triage`, `issue-comment`,
+  `repo-health`, and the `cron-*` workflows. Run `lastlight fork` to see the live
+  list.
+- Persona: `soul.md` (voice/identity), `rules.md` (hard rules), `security.md`
+  (security posture).

package/plugins/lastlight/skills/lastlight-overlay/references/overlay-layout.md

@@ -0,0 +1,52 @@
+# Overlay layout & layering rules
+
+The overlay is a private directory (often its own git repo) mounted read-only at
+`/app/instance` and pointed to by `LASTLIGHT_OVERLAY_DIR`. It is layered over the
+packaged defaults at startup.
+
+```
+instance/
+  config.yaml                  # merged over config/default.yaml
+  .gitignore                   # ignores secrets/ + *.pem
+  docker-compose.override.yml  # optional (e.g. Caddy disabled); symlinked into the project root
+  secrets/                     # host-only, gitignored
+    .env                       # all env vars (mode 0600)
+    app.pem                    # GitHub App private key (mode 0600)
+  agent-context/               # optional persona overrides
+    soul.md
+    rules.md
+    security.md
+  workflows/                   # optional workflow overrides
+    <name>.yaml
+    prompts/
+      <name>.md
+  skills/                      # optional skill overrides
+    <name>/
+      SKILL.md
+```
+
+## Layering / merge rules
+
+- **config.yaml** is deep-merged over the packaged `config/default.yaml`:
+  - **maps** deep-merge,
+  - **arrays** replace wholesale (e.g. `managedRepos`, `disabled.*`),
+  - environment variables override both.
+  - Secrets are env-only — never put them in config.yaml.
+- **Assets** (`workflows/`, `workflows/prompts/`, `skills/`, `agent-context/`)
+  resolve **layer-aware by logical name**: an overlay file with the same logical
+  name as a built-in *wins*; built-ins are the fallback. So you fork only what
+  you want to change.
+
+## What `config.yaml` can override
+
+`managedRepos`, `models` / per-task model overrides, `variants` (reasoning
+effort), `routes`, `approvals`, and `disabled.*`. See the repo's
+`config/default.yaml` for the authoritative shape and keys.
+
+## Applying changes
+
+- config.yaml change, or an added/changed `.env` value → `lastlight server
+  restart agent`.
+- **Removing** an `.env` value → `lastlight server start agent` (recreate).
+- The dashboard's `/config` view shows Default / Overlay / Merged (non-secret) so
+  you can confirm what took effect.

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

@@ -0,0 +1,124 @@
+---
+name: lastlight-server
+description: Install and configure a Last Light SERVER — the GitHub maintenance agent plus its docker-compose stack — on a host. Use when the user wants to "set up / install / deploy / stand up a Last Light server or instance", configure its GitHub App, models, managed repos, or domain, or get the agent running for the first time. Drives the `lastlight` CLI; for connecting an existing CLI to a server use lastlight-client instead, and for editing a running deployment's config use lastlight-overlay.
+version: 1.0.0
+tags: [lastlight, server, deploy, docker, setup]
+---
+
+# Install & configure a Last Light server
+
+A Last Light **server** runs the agent and a docker-compose stack on a host. It
+needs: Docker, a GitHub App (so it can act on repos), a model provider API key,
+and a list of repos it's allowed to manage. Configuration lives in a private
+**overlay** at `instance/` (a `config.yaml` plus `secrets/.env` + `secrets/app.pem`).
+
+Your job: gather the inputs, get the working directory in place, write the
+config, then build and launch. Prefer the deterministic file-writing path below
+(fully automatable) over the interactive wizard.
+
+## 1. Check prerequisites
+
+Run these and report anything missing before continuing:
+
+```bash
+docker info >/dev/null 2>&1 && echo "docker: ok" || echo "docker: NOT running"
+git --version; node --version
+command -v lastlight >/dev/null && lastlight --help >/dev/null 2>&1 && echo "lastlight: installed" || echo "lastlight: missing"
+```
+
+- Docker must be running.
+- If `lastlight` is missing: `npm i -g lastlight`.
+
+## 2. Gather inputs from the user
+
+Ask for each of these (don't guess). Group the questions; explain what each is for.
+
+**Required**
+- **GitHub App** — App ID, Installation ID, and the path to the App's private
+  key `.pem` file. (If they don't have a GitHub App yet, point them at GitHub →
+  Settings → Developer settings → GitHub Apps; it needs webhook + repo
+  contents/issues/pull-requests permissions. They install it on their repos to
+  get the Installation ID.)
+- **Domain** — the public hostname for webhooks/dashboard, e.g.
+  `lastlight.example.com`. Ask whether to use the bundled **Caddy** for
+  automatic TLS (default yes). The GitHub App webhook URL will be
+  `https://<domain>/webhook`.
+- **Managed repos** — one or more `owner/repo` the bot is allowed to act on. The
+  bot ignores any repo not listed.
+- **Model** — a `provider/model` string (default `anthropic/claude-sonnet-4-6`),
+  plus the **matching** provider API key. Key→provider mapping:
+  `sk-ant-…` → `ANTHROPIC_API_KEY`, `sk-or-…` → `OPENROUTER_API_KEY`, other
+  `sk-…` → `OPENAI_API_KEY`.
+
+**Optional**
+- Admin dashboard password (≥8 chars) to protect `/admin`.
+- Slack: bot token (`xoxb-…`), app token (`xapp-…`), delivery channel id,
+  allowed user ids.
+
+## 3. Working directory + overlay
+
+The server runs out of a working directory: a checkout of the lastlight repo
+plus an `instance/` overlay. Scaffold it (this clones the core repo if needed
+and creates/clones the overlay):
+
+```bash
+lastlight server setup            # interactive: confirms working dir + overlay
+```
+
+If you need to do this non-interactively / the user already has a checkout, work
+in that directory directly (it has `docker-compose.yml`, `workflows/`, `skills/`,
+`config/`). The overlay you write to is `<workdir>/instance/`.
+
+## 4. Write the configuration
+
+Create the overlay files directly (this is the automatable path — it avoids the
+TTY wizard). From the working directory:
+
+1. `mkdir -p instance/secrets && chmod 700 instance/secrets`
+2. Copy the user's PEM to `instance/secrets/app.pem` and `chmod 600` it.
+3. Generate two random secrets: `openssl rand -hex 32` for `WEBHOOK_SECRET` and
+   again for `ADMIN_SECRET`.
+4. Write `instance/secrets/.env` (`chmod 600`) and `instance/config.yaml`
+   following **`references/env-schema.md`** — it has the exact keys, value
+   formats, and ready-to-fill templates for both files.
+5. If the user declined Caddy, write `instance/docker-compose.override.yml` to
+   disable it (template in `references/env-schema.md`).
+
+Read `references/env-schema.md` now before writing the files — it has the precise
+key list and value formats.
+
+> Alternative (let the user drive): if they'd rather answer prompts themselves,
+> have them run `lastlight setup --server` in the working directory — the same
+> wizard, interactive. It is a TTY wizard, so you can't fill it in from a script.
+
+## 5. Build and launch
+
+```bash
+lastlight server update           # build images, bring stack up, restart sidecars, health-check
+```
+
+Then verify:
+
+```bash
+curl -fsS http://127.0.0.1:8644/health && echo "  ← healthy"
+lastlight server status           # compose state + version drift
+```
+
+## 6. Hand-off checklist
+
+Tell the user to:
+- Paste the generated `WEBHOOK_SECRET` and the webhook URL
+  (`https://<domain>/webhook`) into their **GitHub App** settings, and confirm a
+  test delivery succeeds.
+- Visit `https://<domain>/admin` (password is `ADMIN_PASSWORD` if they set one).
+- Make later config edits in the overlay, then `lastlight server restart agent`
+  (no rebuild). See the **lastlight-overlay** skill for forking workflows/assets.
+
+For day-2 operations (start/stop/restart/update, logs, redeploy after a code
+change), read **`references/operations.md`**.
+
+## Done when
+
+The stack is up, `GET /health` returns ok, `lastlight server status` shows the
+agent running, and the user has the webhook secret + URL to finish GitHub App
+setup. Report the webhook URL, dashboard URL, and which config you wrote.