specrails-desktop 2.0.0

package/docs/internals/openspec-workflow.md

@@ -0,0 +1,282 @@
+# OpenSpec (opsx) Workflow
+
+> **Note:** The OpenSpec Changes UI (the `/changes` route in the dashboard) was removed in the SPEA-341 redesign. There is no dashboard surface for the `opsx:*` workflow — you drive it from a Claude Code conversation, not from the app UI.
+
+OpenSpec is the structured change-management workflow this repository uses to evolve itself. Every feature, fix, or refactor goes through a lifecycle of **artifacts** — from a proposal to an archived implementation — so that whoever (human or AI) picks up the work always has the full context.
+
+This is a **contributor** workflow: it manages the app's _own_ changes under `openspec/`. It is not a per-project end-user feature exposed in the dashboard.
+
+---
+
+## How it works
+
+The `opsx:*` commands are **Claude Code slash commands** (defined in `.claude/commands/opsx/`). When you type one in a Claude Code conversation, the assistant drives the standalone **`openspec` Node CLI** to scaffold change directories, read artifact templates, and report status — then does the actual artifact authoring, code edits, and verification **directly in the conversation**.
+
+Two consequences worth internalizing:
+
+- **They do not require the specrails-desktop server.** `opsx:*` is independent of the app process; nothing is queued, no rail is launched, and nothing streams to the Dashboard.
+- **They are distinct from `/specrails:implement`.** The Architect → Developer → Reviewer agent pipeline is a _separate_ flow (`specrails-desktop implement`, backed by the `sr-architect` / `sr-developer` / `sr-reviewer` agents). `opsx:apply` does **not** spawn those agents — it implements tasks itself, in the same conversation.
+
+Under the hood the assistant calls the `openspec` binary for state, e.g.:
+
+```bash
+openspec list --json                          # active + recent changes
+openspec new change "<name>"                  # scaffold a change directory
+openspec status --change "<name>" --json      # artifact graph + progress
+openspec instructions <artifact-id> --change "<name>" --json   # template + context
+openspec instructions apply --change "<name>" --json           # apply context files
+```
+
+You normally won't run these by hand — the slash command orchestrates them for you.
+
+---
+
+## Where changes live
+
+Changes are scaffolded under your project's `openspec/` directory:
+
+```
+openspec/
+  config.yaml                 # selects the workflow schema (here: spec-driven)
+  changes/
+    <name>/                   # an active change
+      proposal.md
+      design.md
+      tasks.md
+      specs/<capability>/spec.md
+      ...
+    archive/                  # completed changes, date-prefixed
+      2026-04-20-pipeline-telemetry/
+      2026-04-24-add-agents-profiles/
+      ...
+  specs/                      # main (synced) capability specs
+```
+
+Archives land under `openspec/changes/archive/` (singular `archive`) with a `YYYY-MM-DD-<name>` directory name.
+
+---
+
+## Artifacts are schema-driven
+
+There is **no fixed list** of artifact filenames. The set is determined by the **workflow schema** declared in `openspec/config.yaml` (`schema: spec-driven` in this repo). The assistant reads the live artifact graph from `openspec status --change <name> --json` and never assumes specific names.
+
+For the default **`spec-driven`** schema the artifacts are:
+
+| Artifact | Purpose |
+|----------|---------|
+| `proposal.md` | Why / What changes / Capabilities / Impact |
+| `specs/<capability>/spec.md` | One delta spec per capability listed in the proposal |
+| `design.md` | Technical decisions, architecture, implementation approach |
+| `tasks.md` | Checkboxed implementation tasks (`- [ ]` / `- [x]`) |
+
+Some changes also carry `context-bundle.md` and a `.openspec.yaml` marker. Other schemas define a different artifact set entirely — always trust the CLI status output, not a hardcoded list.
+
+---
+
+## The change lifecycle
+
+```
+opsx:explore        (optional) think through the idea first — no code
+   │
+   ▼
+opsx:new            scaffold the change, show the first artifact template
+   │
+   ▼
+opsx:ff             generate all apply-ready artifacts in one pass
+   │   (or opsx:continue to create one artifact at a time and review each)
+   │
+   ▼
+opsx:apply          implement the tasks in-conversation, flipping - [ ] → - [x]
+   │
+   ▼
+opsx:verify         in-conversation Completeness / Correctness / Coherence report
+   │
+   ▼
+opsx:sync           (when needed) merge delta specs into openspec/specs/
+   │
+   ▼
+opsx:archive        move the change to openspec/changes/archive/YYYY-MM-DD-<name>/
+```
+
+---
+
+## Commands reference
+
+Run these as Claude Code slash commands inside a conversation in the repo.
+
+### `opsx:explore` — Think before you build
+
+A thinking-partner mode for shaping an idea, investigating the codebase, or comparing approaches. It reads files and draws diagrams but **never writes application code**. It may capture decisions into OpenSpec artifacts if you ask, but it won't implement.
+
+```
+/opsx:explore real-time collaboration
+```
+
+Use it when the problem is still fuzzy. When things crystallize, it can flow straight into a proposal.
+
+---
+
+### `opsx:new` — Start a new change
+
+Scaffolds the change directory and **shows the first artifact's template and instructions** — then stops and waits for your direction. It deliberately creates **no artifacts yet**.
+
+```
+/opsx:new add-user-auth
+```
+
+You can also pass a description instead of a name and let the assistant derive a kebab-case name.
+
+---
+
+### `opsx:ff` — Fast-forward artifact creation
+
+Generates every artifact required to start implementation in one pass (in dependency order, reading each upstream artifact for context). Best when the task is well-defined and you want to go straight to `opsx:apply`.
+
+```
+/opsx:ff add-user-auth
+```
+
+The assistant loops the schema's artifacts, creating each one until everything `apply.requires` is done.
+
+---
+
+### `opsx:continue` — Create the next artifact, one at a time
+
+Creates exactly **one** artifact per invocation — the next one whose dependencies are satisfied — then stops. Use it when you want to review and adjust each artifact before the next is drafted.
+
+```
+/opsx:continue add-user-auth
+```
+
+Run it repeatedly until all artifacts exist, then move on to `opsx:apply`.
+
+---
+
+### `opsx:apply` — Implement the change
+
+Reads the change's context files (via `openspec instructions apply --json`), then **implements the tasks directly in the conversation** — making the code edits and marking each task `- [ ]` → `- [x]` in the tasks file as it goes. It loops until all tasks are complete or it hits something that needs your input.
+
+```
+/opsx:apply add-user-auth
+```
+
+> **Not the app pipeline.** `opsx:apply` does the work itself, in-conversation. It does **not** queue a server job, spawn Architect/Developer/Reviewer agents, or stream to the Dashboard. For the agent pipeline, use `specrails-desktop implement` instead.
+
+---
+
+### `opsx:verify` — Verify the implementation
+
+Reads the artifacts and builds an in-conversation **verification report** across three dimensions:
+
+- **Completeness** — are all `tasks.md` checkboxes done? Are all spec requirements implemented?
+- **Correctness** — does the implementation match the requirements and cover the scenarios?
+- **Coherence** — does the code follow the decisions in `design.md` and the project's patterns?
+
+```
+/opsx:verify add-user-auth
+```
+
+Issues are graded CRITICAL / WARNING / SUGGESTION with file/line references. Resolve any CRITICALs (manually or by re-running `opsx:apply`), then verify again before archiving.
+
+---
+
+### `opsx:sync` — Sync delta specs to main specs
+
+When a change adds, modifies, removes, or renames requirements, `opsx:sync` merges those delta specs (`openspec/changes/<name>/specs/`) into the main specs at `openspec/specs/<capability>/spec.md`. It's an **agent-driven intelligent merge** — it can add a single scenario without rewriting the whole requirement, and is idempotent. The change stays active; archive it once implementation is done.
+
+```
+/opsx:sync add-user-auth
+```
+
+---
+
+### `opsx:archive` — Archive a completed change
+
+Moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>/`. Before moving, it checks artifact and task completion (warning if anything is incomplete) and, when delta specs exist, offers to sync them first.
+
+```
+/opsx:archive add-user-auth
+```
+
+---
+
+### `opsx:bulk-archive` — Archive several changes at once
+
+Archives multiple completed changes in a single operation, checking the codebase to resolve spec conflicts intelligently. Use it when you've finished a batch of parallel changes.
+
+```
+/opsx:bulk-archive
+```
+
+---
+
+### `opsx:onboard` — Guided walkthrough
+
+A teaching mode that walks you through a complete OpenSpec cycle on real work in the codebase, narrating each step. Run it the first time you touch this workflow. (It checks that the `openspec` CLI is installed before starting.)
+
+```
+/opsx:onboard
+```
+
+---
+
+## Use cases
+
+### Feature implementation
+
+```
+/opsx:ff add-user-auth      # scaffold + generate all artifacts
+# review the generated proposal / design / tasks
+/opsx:apply add-user-auth   # implement the tasks in-conversation
+/opsx:verify add-user-auth  # check completeness/correctness/coherence
+/opsx:sync add-user-auth    # merge delta specs into main specs (if any)
+/opsx:archive add-user-auth # archive
+```
+
+### Bug fix
+
+For a well-understood bug, go straight to fast-forward:
+
+```
+/opsx:ff fix-token-refresh
+# review the generated artifacts to confirm they describe the fix
+/opsx:apply fix-token-refresh
+/opsx:verify fix-token-refresh
+/opsx:archive fix-token-refresh
+```
+
+### Refactor with careful artifact review
+
+Use `opsx:explore` to think first, then create artifacts one at a time:
+
+```
+/opsx:explore the auth system is getting unwieldy
+/opsx:new refactor-auth
+/opsx:continue refactor-auth   # creates the proposal — review it
+/opsx:continue refactor-auth   # creates the next artifact — review it
+# ...repeat until all artifacts exist...
+/opsx:apply refactor-auth
+/opsx:verify refactor-auth
+/opsx:archive refactor-auth
+```
+
+---
+
+## Browsing changes via the app API
+
+Although the dashboard `/changes` UI was removed, the server still **reads** the OpenSpec directory and exposes two read-only endpoints (per project):
+
+| Endpoint | Returns |
+|----------|---------|
+| `GET /api/projects/:projectId/changes` | Active + archived changes (parsed from `openspec/changes/`) |
+| `GET /api/projects/:projectId/changes/:changeId/artifacts/:artifact` | A single artifact's content (`proposal.md`, `design.md`, `tasks.md`, `delta-spec.md`, `context-bundle.md`) |
+
+These are handy for tooling that wants to surface the artifact set without parsing the filesystem directly.
+
+---
+
+## Further reading
+
+- [CLI reference](../cli.md) — the `specrails-desktop` CLI and its verbs
+- [Architecture](architecture.md) — server modules and how the app is wired
+- [Adding a provider](adding-a-provider.md) — extending the provider adapter contract

package/docs/internals/operations-runbook.md

@@ -0,0 +1,198 @@
+# Operations Runbook
+
+Common operational procedures for running, recovering, and updating specrails-desktop. Everything here is verified against the shipped code. The app binds to `127.0.0.1` only.
+
+For the full data-directory layout, every CLI flag, env vars, and app/project settings, see [Configuration](configuration.md).
+
+## Starting the app
+
+```bash
+# Start the app server (daemonized — it detaches and returns once ready)
+specrails-desktop start
+
+# Start on a non-default port (the --port flag may appear in any position)
+specrails-desktop --port 5000 start
+```
+
+`start` writes the server PID to `~/.specrails/manager.pid` and appends the server's stdout/stderr to `~/.specrails/desktop.log`. The default port is `4200`.
+
+## Stopping the app
+
+```bash
+specrails-desktop stop
+```
+
+`stop` reads the PID file and sends `SIGTERM`. If the PID file is stale (no such process), it prints `[specrails-desktop] server is not running (stale pid file)` and removes the file for you — so you rarely need to delete `manager.pid` by hand.
+
+## Status / health check
+
+The first thing to run when something looks wrong:
+
+```bash
+# Is the app up? On what URL/PID? How many projects?
+specrails-desktop status
+
+# Same, against a custom port
+specrails-desktop --port 5000 status
+
+# One-line manager status (also usable as a script-friendly probe)
+specrails-desktop --status
+```
+
+`status` prints `server: running (pid <n>) on http://127.0.0.1:<port>`, the project count, and each project name. It exits non-zero when the app is not running.
+
+> `specrails-desktop --jobs` is **not** functional against the running server — the server does not expose a cross-project `/api/jobs` route, so the command prints a message that jobs history requires a manager with SQLite persistence and exits `1`. Browse job history per project in the app's **Jobs** page instead.
+
+## App data location
+
+All app data lives under `~/.specrails/` (the path is hardcoded to your home directory — there is no override env var):
+
+```
+~/.specrails/
+  desktop.sqlite    # App-level SQLite: project registry + desktop_settings
+  desktop.token     # Auto-generated API token (mode 0600)
+  manager.pid       # PID of the running server (removed on a clean stop)
+  desktop.log       # Server stdout/stderr (appended on each start)
+  projects/
+    <slug>/
+      jobs.sqlite   # Per-project job history, invocations, telemetry pointers
+```
+
+See [Configuration](configuration.md#specrails-directory-structure) for the complete per-project subtree (telemetry blobs, explore-cwd, terminals, attachments, etc.) and how the `<slug>` is derived.
+
+> **Auth token caveat.** `~/.specrails/desktop.token` gates every `/api/*` request and WebSocket upgrade. Deleting it (or doing a full `rm -rf ~/.specrails`) regenerates a fresh token on the next start, which can leave an already-open browser tab or CLI on the old token — reload the app after a token reset. See [Configuration → Authentication](configuration.md#authentication).
+
+## Log files
+
+The app already daemonizes and writes its output to `~/.specrails/desktop.log` on every `start` — you do not need to redirect anything yourself.
+
+```bash
+# Follow the live log
+tail -f ~/.specrails/desktop.log
+
+# Show the last 200 lines
+tail -n 200 ~/.specrails/desktop.log
+```
+
+The log file is opened in append mode, so it accumulates across restarts. Truncate or rotate it manually if it grows large.
+
+## Backups
+
+To back up all app data, copy the whole directory while the app is stopped:
+
+```bash
+specrails-desktop stop
+cp -r ~/.specrails/ ~/specrails-backup-$(date +%Y%m%d)/
+```
+
+Your project source code and each project's `.specrails/` folder (specs, profiles, plugins) live in your repos, not here — they are not part of this backup.
+
+## Troubleshooting
+
+### Port already in use
+
+```bash
+# Find the process bound to the port (use your custom port if not 4200)
+lsof -i :4200
+
+# Stop the app cleanly
+specrails-desktop stop
+
+# Last resort: kill by recorded PID
+kill "$(cat ~/.specrails/manager.pid)"
+```
+
+If you run the app on a custom port, point `lsof` and `status` at that port (`--port <n>`).
+
+### Server won't start after a crash
+
+A clean `stop` already clears a stale PID file. If a crash left one behind and `start` still refuses:
+
+```bash
+rm ~/.specrails/manager.pid
+specrails-desktop start
+```
+
+### Registry database reset (loses project registrations)
+
+> **Warning:** `desktop.sqlite` is the project registry *and* the app-settings store. Deleting it unregisters **every** project and resets all app settings. Your project source and each project's specrails-core install are untouched, but you must re-add each project afterward.
+
+```bash
+# Back up first, then reset
+cp ~/.specrails/desktop.sqlite ~/.specrails/desktop.sqlite.bak
+specrails-desktop stop
+rm -f ~/.specrails/desktop.sqlite*   # the glob also clears the WAL/SHM sidecars
+specrails-desktop start              # re-creates an empty registry
+
+# Re-register each project
+specrails-desktop add /path/to/project-a
+specrails-desktop add /path/to/project-b
+```
+
+### Per-project reset (keeps the registration)
+
+To clear one project's job history, invocations, and telemetry pointers while keeping it registered, delete just that project's `jobs.sqlite` with the app stopped:
+
+```bash
+specrails-desktop stop
+rm -f ~/.specrails/projects/<slug>/jobs.sqlite*
+specrails-desktop start
+```
+
+The `<slug>` matches the project's directory name, lowercased with non-alphanumeric runs collapsed to hyphens (e.g. `My App v2!` → `my-app-v2`). The project's registration in `desktop.sqlite` and its on-disk `.specrails/` assets are left intact; the per-project DB is re-created empty on next start.
+
+## Updates
+
+For an npm-installed server:
+
+```bash
+npm update -g specrails-desktop
+specrails-desktop stop && specrails-desktop start
+```
+
+The desktop app self-updates via Tauri's passive updater — no manual step needed.
+
+## Desktop app
+
+These commands require the **Rust toolchain** and `@tauri-apps/cli` (a devDependency), in addition to a checked-out repo with both `npm install` trees (root + `client/`).
+
+### Development
+
+```bash
+npm run dev:desktop
+```
+
+Runs `tauri dev` — a hot-reloading desktop window backed by the dev server.
+
+### Production build
+
+```bash
+npm run build:desktop
+```
+
+This single script chains the full pipeline: `build:server` → client build → `build:sidecar` → `tauri build`. There is **no** `npm run tauri` script — `npm run tauri dev` / `npm run tauri build` fail with `Missing script: tauri`.
+
+The macOS build is signed + notarized. The Windows x64 and arm64 builds ship **unsigned** in v1 (users see a SmartScreen warning → "More info → Run anyway"). See [Windows](../platforms/windows.md) and [macOS](../platforms/macos.md) for platform specifics.
+
+### Build the server sidecar only
+
+```bash
+npm run build:sidecar
+```
+
+Bundles the Express server (and the `node-pty` native module) into the standalone sidecar that Tauri ships. `build:desktop` runs this for you; run it on its own only when iterating on server code for a desktop build.
+
+### Regenerate app icons
+
+```bash
+npm run generate-icons
+```
+
+Regenerates every icon size (PNG/ICNS/ICO) from `src-tauri/icons/icon.svg` via `tauri icon`. Requires the Rust toolchain + `@tauri-apps/cli`. Run after any icon design change.
+
+## Further reading
+
+- [Configuration](configuration.md) — full data layout, app/project settings, auth token, env vars
+- [CLI reference](../cli.md) — every command and flag in detail
+- [Architecture](architecture.md) — server modules, data flow, WebSocket protocol
+- [macOS](../platforms/macos.md) · [Windows](../platforms/windows.md) — platform-specific operations

package/docs/internals/profiles.md

@@ -0,0 +1,152 @@
+# Profiles — Quick start
+
+Profiles let you save a named combination of orchestrator model, agent
+chain, per-agent models, and routing rules, and pick one per rail at
+launch time. Different rails on the Dashboard can run different profiles
+simultaneously — useful for batch runs where each feature needs a
+different flavor of pipeline.
+
+Requires **`specrails-core >= 4.1.0`** in the target project. Without
+it, the app still lets you create/edit profiles but the pipeline runs in
+legacy mode (a yellow banner on the Agents page tells you when this is
+the case).
+
+---
+
+## 1. Open the Agents section
+
+From any project, click **Agents** in the right sidebar (next to
+Dashboard/Jobs/Analytics/Settings).
+
+- **Profiles** tab — create and edit profiles.
+- **Usage** tab — see which profiles are actually being used.
+- **Catalog** tab — read the upstream `sr-*` agents or author custom
+  `custom-*` ones via the Studio.
+
+When the project has no profiles yet, the empty state offers two entry
+points:
+
+- **Migrate from current agents** — reads your existing
+  `.claude/agents/` frontmatter models and creates a `default` profile
+  mirroring today's behavior (zero-loss). It requires the baseline trio
+  `sr-architect`, `sr-developer`, and `sr-reviewer` to be present — the
+  server rejects the migration if any is missing.
+- **Blank profile** — start from scratch.
+
+## 2. Saved profiles vs selection
+
+Two orthogonal concepts:
+
+- **Saved profiles** — the set of profiles in the project (`.specrails/profiles/*.json`).
+  Committed to git, shared with the team.
+- **Selection** — which profile this particular invocation uses. Per-rail,
+  per-launch.
+
+Resolution order when no explicit selection is passed:
+
+1. The profile named `default` (or `project-default`).
+2. Legacy mode (no profile active).
+
+## 3. Pick a profile at launch
+
+Profiles are picked on the **Dashboard rails board**, not in a separate
+wizard. Each rail header has a compact profile dropdown
+(`RailProfileSelector`):
+
+- Pick a profile once and it persists across launches of that rail
+  (stored per rail; sent inline on `POST /rails/:i/launch`, or set on its
+  own via `PUT /rails/:i/profile`).
+- Concurrent rails can run different profiles at the same time, so a batch
+  spread across rails can give each feature its own flavor of pipeline.
+- The selector **self-hides** when the project has no profiles, so it never
+  leaves an empty gap in the rail header.
+
+The "No profile" option is always available — use it to run a
+rail exactly as it did pre-4.1.0.
+
+### Codex / multi-provider
+
+Agent profiles are a **Claude-only** feature. When a rail's AI engine is
+Codex, the app force-nulls the profile and runs the rail in legacy mode —
+Codex has no agent-profile concept. The profile selector is hidden for
+Codex rails, so a profile picked on one engine never silently applies to
+the other.
+
+## 4. Author a custom agent (Agent Studio)
+
+From the Catalog tab, create a new custom agent via:
+
+- **Template** — start from one of ~50 curated templates spanning many
+  categories (engineering, product, data, security, …) — for example
+  Security Reviewer, Performance Profiler, Data Engineer, or UI/UX Polisher.
+- **Generate** — describe the agent in natural language; Claude drafts the
+  full `.md` for you to review and edit before saving.
+- **Blank** — start from a minimal template.
+- **Duplicate** — copy any existing agent (upstream or custom).
+
+Custom agents live at `.claude/agents/custom-*.md` and are never touched
+by `specrails-core`'s installer/update scripts. Every save appends a new
+version row; open **History** in the Studio to browse and restore.
+
+Click **Test** in the Studio to run the current draft against a sample
+task in an isolated `claude` invocation — no files are written, and you
+see output, token count, and duration inline.
+
+## 5. Observe
+
+- A **profile badge** (themed with the `accent-primary` color) appears on
+  each job row showing which profile it ran under.
+- The **Usage** tab shows usage per profile for the last 7/30/90 days:
+  jobs, success rate, avg duration, avg tokens, and avg cost.
+- The **diagnostic ZIP export** on a job includes `profile.json` with
+  the exact snapshot that rail used.
+
+## 6. Troubleshooting
+
+- **Upgrade banner on Agents page** — `npx specrails-core@latest update`
+  in the project to bring it to ≥ 4.1.0.
+- **Save disabled with "N issues to resolve"** — the live validator
+  enforces the baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`)
+  and routing ordering. Among the rules: a `default: true` routing rule (if
+  present) must be the **last** entry in `routing` and must target
+  `sr-developer`. Fix the listed issues and Save re-enables.
+- **"agent 'xyz' already exists" (409)** — the name collides with an
+  existing file in `.claude/agents/`. Pick a different name.
+- **The whole Agents section is missing** — it can be disabled server-side
+  with `SPECRAILS_AGENTS_SECTION=false`, which 404s the entire
+  `/profiles` router. Unset it (or leave it at its default) to restore the
+  section.
+
+## 7. Reserved paths
+
+`specrails-core`'s installer guarantees it will never touch:
+
+- `.specrails/profiles/**` — your profile catalog.
+- `.claude/agents/custom-*.md` — your custom agents.
+
+Everything else under `.specrails/` (install-config, specrails-version,
+setup-templates) is managed by the installer and may be overwritten on
+update.
+
+## 8. For developers
+
+A few internals worth knowing if you're working on this surface:
+
+- **Version gate.** Profile-aware spawns are gated by
+  `projectSupportsProfiles()` (`server/queue-manager.ts`), which reads the
+  project's `.specrails/specrails-version` and requires
+  `specrails-core >= 4.1.0`. Below that, the rail spawns in legacy mode and
+  no profile env var is injected.
+- **Snapshot per job.** When a rail launches with a profile, the resolved
+  profile is written to
+  `~/.specrails/projects/<slug>/jobs/<jobId>/profile.json` (chmod `400`, so
+  mid-run edits are impossible) before the `claude` process spawns. The
+  spawn env then carries `SPECRAILS_PROFILE_PATH` pointing at that file.
+  The same snapshot is persisted to the `job_profiles` table for the Usage
+  analytics.
+- **REST surface.** All profile operations live under
+  `/api/projects/:projectId/profiles` — list/get/create/update/delete,
+  `/:name/duplicate`, `/:name/rename`, `/resolve`, `/migrate-from-settings`,
+  `/analytics`, `/core-version`, and the catalog routes under `/catalog`.
+  The router 404s entirely when `SPECRAILS_AGENTS_SECTION=false`. See
+  [api-reference.md](api-reference.md) for the full route list.