lastlight 0.5.1 → 0.6.2

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.

package/plugins/lastlight/skills/lastlight-server/references/env-schema.md

@@ -0,0 +1,103 @@
+# Overlay config reference — `instance/secrets/.env` + `instance/config.yaml`
+
+The server reads config in layers: packaged `config/default.yaml` → overlay
+`instance/config.yaml` → `instance/secrets/.env` env vars → `LASTLIGHT_*` env.
+Secrets stay env-only and out of git. The container entrypoint copies
+`instance/secrets/.env` → `/app/.env` and `instance/secrets/*.pem` → `/app/*.pem`
+(mode 600) at boot, and the overlay is mounted read-only at `/app/instance`.
+
+## `instance/secrets/.env`  (mode 0600)
+
+Write exactly these keys. `WEBHOOK_SECRET` and `ADMIN_SECRET` are random 32-byte
+hex (`openssl rand -hex 32`). Include only the ONE provider key that matches the
+model.
+
+```dotenv
+# ── Last Light — Environment Variables ─────────────────────
+
+# Overlay (this deployment's private config + assets)
+LASTLIGHT_OVERLAY_DIR=/app/instance
+
+# ── GitHub App (required) ────────────────────────────────
+GITHUB_APP_ID=123456
+# PEM lives at instance/secrets/app.pem; the entrypoint symlinks it to /app/app.pem.
+GITHUB_APP_PRIVATE_KEY_PATH=./app.pem
+GITHUB_APP_INSTALLATION_ID=789012
+
+# ── Webhook (required) — must match the GitHub App's webhook secret ──
+WEBHOOK_SECRET=<openssl rand -hex 32>
+
+# ── Domain (used by Caddy for TLS) ───────────────────────
+DOMAIN=lastlight.example.com
+
+# ── Model + provider API key ─────────────────────────────
+LASTLIGHT_MODEL=anthropic/claude-sonnet-4-6
+# Set whichever ONE matches LASTLIGHT_MODEL:
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# ── Admin dashboard ──────────────────────────────────────
+ADMIN_SECRET=<openssl rand -hex 32>
+# Optional — protects /admin with a password (>=8 chars):
+# ADMIN_PASSWORD=...
+
+# ── Slack (optional) ─────────────────────────────────────
+# SLACK_BOT_TOKEN=xoxb-...
+# SLACK_APP_TOKEN=xapp-...
+# SLACK_DELIVERY_CHANNEL=C0123456
+# SLACK_ALLOWED_USERS=U0123,U0456
+```
+
+Notes:
+- `GITHUB_APP_PRIVATE_KEY_PATH=./app.pem` is correct as-is — it's resolved
+  inside the container, not on the host. Just place the file at
+  `instance/secrets/app.pem`.
+- Provider-key detection: `sk-ant-…` is Anthropic; `sk-or-…` is OpenRouter; any
+  other `sk-…` is OpenAI.
+- **Removing** an env var later requires a container *recreate*
+  (`lastlight server start agent`), not just a restart — compose injects
+  `env_file` vars at creation time. Adding/changing one only needs
+  `lastlight server restart agent`.
+
+## `instance/config.yaml`
+
+Non-secret overlay config, merged over `config/default.yaml`. Arrays replace;
+maps deep-merge. Minimum useful content is the managed-repos list:
+
+```yaml
+# Last Light — private deployment overlay config
+# Merged over config/default.yaml at startup. Restart to apply:
+#   lastlight server restart agent
+managedRepos:
+  - owner/repo
+  - owner/another-repo
+```
+
+If there are no repos yet, write `managedRepos: []` and tell the user to add
+entries before the bot will act. You can also override `models`, `variants`,
+`routes`, and `disabled.*` here — see the repo's `config/default.yaml` for the
+full shape.
+
+## `instance/.gitignore`
+
+So the overlay can become a private git repo without leaking secrets:
+
+```gitignore
+secrets/
+*.pem
+```
+
+## `instance/docker-compose.override.yml`  (only if Caddy is disabled)
+
+Write this ONLY when the user opts out of Caddy TLS (they terminate TLS
+elsewhere). Then symlink it into the working dir as `./docker-compose.override.yml`
+(or run `lastlight server setup` / `update`, which ensures the symlink).
+
+```yaml
+# Deployment compose override — this deployment opted out of Caddy TLS.
+services:
+  caddy:
+    profiles:
+      - disabled
+```

package/plugins/lastlight/skills/lastlight-server/references/operations.md

@@ -0,0 +1,60 @@
+# Last Light server — day-2 operations
+
+All commands are **host-local** (run on the server, not over HTTP) and operate
+on the working directory. That directory resolves from `--home` →
+`LASTLIGHT_HOME` → the saved `serverHome` (from `lastlight server setup`) →
+`~/lastlight`.
+
+## Lifecycle
+
+```bash
+lastlight server status            # docker compose ps + core/overlay version drift
+lastlight server start [service]   # docker compose up -d (whole stack, or one service)
+lastlight server stop [service]    # stop one service, or `down` the whole stack
+lastlight server restart [service] # restart (default service: agent)
+```
+
+## Apply config changes
+
+- **Overlay config.yaml or an added/changed `.env` value:**
+  `lastlight server restart agent` — no image rebuild.
+- **Removing an `.env` value:** `lastlight server start agent` (recreate) — a
+  restart can't unset env_file vars injected at container creation.
+- **Code/asset changes** (anything under `src/`, `workflows/`, `skills/`,
+  `agent-context/`, `config/default.yaml`): a full rebuild — `lastlight server
+  update`.
+
+## Redeploy after a code change (the canonical deploy)
+
+```bash
+lastlight server update            # pull core + overlay, build images, recreate, restart sidecars, health-check
+#   flags: --no-core --no-overlay --no-build --yes
+```
+
+This: git-pulls the core repo and the `instance/` overlay, builds the `agent` +
+`sandbox` (+ best-effort `sandbox-qa`) images, `docker compose up -d
+--remove-orphans`, force-restarts the egress sidecars (coredns + nginx + otel),
+and health-checks `http://127.0.0.1:8644/health`.
+
+## Logs & health
+
+```bash
+curl -fsS http://127.0.0.1:8644/health
+lastlight server logs agent --follow          # live harness logs
+lastlight server logs [service] --tail 200 --since 10m
+lastlight server list                          # the lastlight-* containers
+```
+
+## Debug a running instance (over the admin API)
+
+These talk to the instance over HTTP (need `lastlight login` first — see the
+lastlight-client skill):
+
+```bash
+lastlight workflow list [--status s] [--workflow name]
+lastlight workflow log <id> [--follow]
+lastlight session list ; lastlight session log <id> --follow
+lastlight logs search "<text>" [--scope errors|messages|all]
+lastlight approvals list|approve <id>|reject <id>
+lastlight stats [--daily n | --hourly n]
+```