specrails-desktop 2.18.2 → 2.19.1

package/server/dist/mcp/guide.js

@@ -10,73 +10,208 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SPECRAILS_GUIDE = void 0;
 exports.SPECRAILS_GUIDE = `# Specrails Desktop — Agent Guide
 
-You are operating Specrails Desktop through its MCP server. Specrails is a local
-dashboard + pipeline runner that manages multiple software projects and drives AI
-coding agents (Claude Code, Codex, Gemini) to implement specs.
+You are operating Specrails Desktop through its MCP server — either as an
+EXTERNAL MCP client (Claude Desktop, Cursor, a custom agent) or as the app's own
+embedded agent chat. Everything here applies to both, except Permissions, which
+differs by client kind (see below).
 
-## Core concepts
+Specrails is a local dashboard + pipeline runner that manages multiple software
+projects (registered repositories) and drives AI coding agents (Claude Code,
+Codex, Gemini) to implement specs.
+
+## The object model
 
 - **Project**: a registered repository. Almost every tool is project-scoped and
-  takes a \`projectId\`. Use \`specrails_select_project\` to set an active project so
-  you can omit \`projectId\` on later calls; pass an explicit \`projectId\` to override.
-- **Spec / ticket**: a unit of work in a project's backlog. Statuses: \`draft\`,
-  \`todo\`, \`in_progress\`, \`done\`, \`cancelled\`. Priorities: \`critical\`, \`high\`,
-  \`medium\`, \`low\`. INVARIANT: priority may be null ONLY when status is \`draft\`.
-- **Rail**: a launch slot that runs the AI pipeline over one or more assigned
-  tickets. Modes: \`implement\`, \`batch-implement\`, \`ultracode\`, \`loop\`. Launching a
-  rail spawns AI CLI processes that write code, run tests and commit — it costs
-  money and runs for minutes.
-- **Job**: one spawned pipeline run. Jobs stream logs/events over the WebSocket
-  and settle (completed/failed/canceled). Cost is authoritative for Claude and
-  estimated for Codex/Gemini.
-- **Profile**: a per-project agent configuration (which agents, which models,
-  routing). Profiles are CLAUDE-ONLY; they are ignored for Codex/Gemini rails.
-- **Provider / engine**: claude, codex, or gemini. A project installs one or
-  more. A requested provider must be one of the project's installed providers.
-- **Loop**: a saved, app-driven workflow graph runnable on a rail in \`loop\` mode.
+  takes a \`projectId\`. \`specrails_select_project\` sets a sticky active project
+  so later calls can omit it; an explicit \`projectId\` overrides.
+  \`specrails_projects(get)\` includes the repo's absolute path.
+- **Spec / ticket**: a unit of work in a project's backlog. Statuses \`draft\`,
+  \`todo\`, \`in_progress\`, \`done\`, \`cancelled\`, plus a \`needs_review\` boolean FLAG
+  set on \`done\` specs when the pipeline ships with partial confidence (it is
+  not a status). Priorities \`critical|high|medium|low\`. INVARIANT: priority may
+  be null ONLY when status is \`draft\`. Specs can be epics with children (see
+  SMASH) and can be Jira-backed (\`source: 'jira'\`).
+- **Rail**: a persistent numbered launch slot that runs the AI pipeline over its
+  assigned tickets. A rail REMEMBERS its config across launches: ticket ids,
+  mode, profile, engine, name. Launching spawns AI CLI processes that write
+  code, run tests and commit — it costs money and runs for minutes.
+- **Job**: one spawned pipeline run. Jobs stream events over the app's bus and
+  settle (completed/failed/canceled). Job outcome mutates spec status
+  AUTOMATICALLY: launch → \`in_progress\`; success → \`done\`; revert → \`todo\`;
+  partial confidence → \`done\` + \`needs_review\`. Do not patch statuses the
+  pipeline manages.
+- **Loop**: an APP-LEVEL saved workflow graph (not project-scoped). Author with
+  \`specrails_loops\`; RUN it with \`specrails_rails(launch, mode:'loop', loopId)\`.
+- **Profile**: per-project agent configuration (which agents, which models,
+  routing). CLAUDE-ONLY; forced to null for codex/gemini rails.
+- **Provider / engine**: claude, codex or gemini. A project installs one or
+  more; a requested engine must be one of the installed set.
 - **Plugin**: an MCP-based integration installed per project (e.g. serena).
 
+## Creating specs — three paths, one decision rule
+
+1. **Quick (AI-generated)** — \`specrails_specs(action:'generate', idea, …)\`, or
+   the simpler \`create\` with title/description: routes through the app's Quick
+   Add Spec — an AI pass structures the request into a complete spec, so
+   MCP-created specs are indistinguishable from UI-created ones. \`generate\`
+   additionally accepts \`contextScope\`, \`attachmentIds\`, \`createLocal\`. Async
+   (202): watch the returned ref. Use for clear, well-scoped requests.
+2. **Explore (multi-turn refinement)** — when requirements are fuzzy:
+   - \`specrails_chat(create, kind:'explore', contextScope)\` → keep the
+     conversation id.
+   - First \`send\`: text \`/specrails:explore-spec\` + blank line + the idea, with
+     \`lightweight: true\`, \`maxTurns: 20\`. Watch each turn by conversationId
+     (\`chat_done\` / \`chat_error\` are terminal).
+   - \`specrails_chat(spec_draft)\` reads the live structured draft the Explore
+     assistant maintains (title, description, labels, priority,
+     acceptanceCriteria, ready).
+   - When converged: \`specrails_specs(save_draft, conversationId)\` parks a
+     resumable draft ticket; \`specrails_specs(commit_draft, conversationId,
+     title, …)\` creates the real spec. Passing the conversationId preserves the
+     origin link ("Continue Explore", Contract Refine eligibility).
+   - \`contextScope\` flags: \`specrails\` (pipeline context), \`openspec\` (spec
+     history), \`full\` (whole-repo access), \`mcp\` (project .mcp.json servers),
+     \`userMcp\` (the user's own approved MCP servers), \`contractRefine\` (append
+     a Contract Layer after commit).
+   An EMBEDDED agent may instead run the refinement conversation ITSELF (no
+   nested AI spawn, no extra cost) and persist via path 3 — use the app's
+   Explore when the user wants the draft visible and resumable in the UI.
+3. **Direct insert (no AI)** — for a COMPLETE spec you already hold:
+   - \`specrails_specs(commit_draft)\` with NO \`conversationId\`/\`draftTicketId\`
+     is the canonical rich insert: \`title\` (required), \`description\`,
+     \`acceptanceCriteria\` (folded into an \`## Acceptance Criteria\` section),
+     \`priority\`, \`labels\`, \`shortSummary\` (max 240 chars). One write call.
+   - \`specrails_specs(from_prompt)\` stores a description verbatim but CANNOT
+     set acceptanceCriteria or shortSummary — prefer \`commit_draft\` for
+     structured specs.
+   - Follow with \`update\` for assignee/prerequisites/metadata when needed.
+   - Never route an already-refined spec through \`create\`/\`generate\` — they
+     REGENERATE the content with AI.
+
+A complete spec matches the app-generated shape: short imperative English
+\`title\`; one-sentence \`shortSummary\`; a \`description\` with the sections
+\`## Problem Statement\`, \`## Proposed Solution\`, \`## Out of Scope\`,
+\`## Technical Considerations\`, \`## Estimated Complexity\`; a separate
+\`acceptanceCriteria\` array (never duplicated inside the description; no title
+heading inside the description); \`labels\`; \`priority\`. Spec content is English.
+
+## Running the pipeline (rails)
+
+- Configure: \`set_tickets\` (replaces the assigned set), \`set_profile\` (null =
+  legacy), \`set_engine\` (null = project primary), \`set_name\`.
+- Launch modes:
+  - \`implement\`: one pipeline job (Architect → Developer → Reviewer → Ship)
+    over the rail's tickets.
+  - \`batch-implement\`: dependency-aware waves across many tickets.
+  - Freestyle (wire value \`ultracode\`): hands the spec straight to the model —
+    one job per ticket; Claude-only; \`model\` picker; optional
+    \`interactive\` in-job chat (settle with \`specrails_jobs(finalize)\`).
+  - \`loop\`: runs a published loop graph per ticket (\`loopId\`,
+    \`reasoning_effort\`).
+- Profiles are Claude-only: a profile set on a rail that is then pointed at
+  codex/gemini is force-nulled.
+- \`stop\` kills the rail's process tree AND cancels its queued jobs
+  (destructive).
+- \`specrails_jobs(spawn, command)\` bypasses rails and enqueues an arbitrary
+  slash-command job (e.g. \`/specrails:implement #5 --yes\`); \`queue\`, \`pause\`,
+  \`resume\`, \`reorder\`, \`priority\` manage the queue.
+
 ## Async results (IMPORTANT)
 
 Cost-incurring / streaming actions (launch a rail, generate a spec, send a chat
-turn, refine an agent, SMASH) return immediately with a reference (jobId /
-requestId) and emit their REAL result over the WebSocket bus. To get the actual
-outcome, call \`specrails_watch\` with the returned reference; it waits for the
-operation to settle and returns the final result. Do not assume success from the
-acceptance alone.
+turn, refine an agent, SMASH, install a plugin) return 202 immediately with a
+reference (jobId / conversationId / requestId) and emit the REAL result over
+the app's event bus. \`specrails_watch(projectId, ref, untilMs)\` waits for the
+operation to settle. Rules:
+
+- \`projectId\` is REQUIRED on watch — it does not default to the active project.
+- Default \`untilMs\` is 120000 (max 600000); rails routinely run longer.
+- \`settled:false\` means TIMEOUT, not failure: the operation may still be
+  running, or may have finished without a watch-terminal event. Re-watch with a
+  larger window or poll the domain read to confirm: \`specrails_jobs(get)\`,
+  \`specrails_specs(get)\`, \`specrails_plugins(health)\`.
+- Chat turns are watched by conversationId (\`chat_done\` / \`chat_error\`).
+
+Never assume success from the 202 acceptance alone.
+
+## Permissions — two regimes
+
+- **External MCP clients** (Claude Desktop, Cursor, …): four INDEPENDENT opt-in
+  tiers configured by the user in the app's Settings ▸ MCP — Read (always on),
+  Write, AI-spawn (costs money), Destructive. On refusal, tell the user to
+  enable the named tier in Settings ▸ MCP.
+- **The in-app agent chat**: a CUMULATIVE ladder the user steers live with
+  Shift+Tab — observe (read) ▸ edit (+write) ▸ operate (+ai-spawn) ▸ autonomous
+  (+destructive). It overrides the Settings checkboxes for that chat. On
+  refusal, tell the user to raise the level with Shift+Tab.
 
-## Permission tiers
+Tools cannot raise their own permissions in either regime. Common tiers:
+list/get/spending/watch = read; commit_draft, from_prompt, update, set_tickets,
+plugin install, Jira connect = write; spec create/generate, rail launch, chat
+send, job spawn = ai-spawn; spec delete, rail stop, job purge, plugin
+uninstall, Jira disconnect, project unregister = destructive. Note the
+embedded spec-refinement happy path (investigate + commit_draft) needs only
+read + write — ai-spawn is required only to launch work or spawn a nested AI.
 
-The server enforces four opt-in tiers, configured by the user in Settings ▸ MCP:
-- **Read** (always on): queries + resources.
-- **Write**: create/edit specs, settings, rail config.
-- **AI-spawn**: actions that spawn an AI CLI and cost money.
-- **Destructive**: delete data, kill processes, mutate external systems.
+## Providers & Claude-only surface
 
-If a tool is refused, the error names the tier the user must enable. Relay that
-to the user rather than retrying blindly.
+- Installed providers are per-project; AI-spawning calls may pick any installed
+  one (\`aiEngine\`); rails carry a per-rail engine.
+- CLAUDE-ONLY: agent profiles, Contract Refine, SMASH, Freestyle mode
+  (\`ultracode\`), interactive jobs. They are rejected or inert when the
+  effective engine is codex or gemini.
+- Cost figures are authoritative for claude and estimated for codex/gemini
+  (flagged as estimated in analytics).
 
-## Claude-only features
+## Domain cheat-sheet
 
-Agent profiles, Contract Refine, and SMASH are Claude-only. They are unavailable
-(and rejected) on projects whose selected provider is Codex or Gemini.
+- **Epics / SMASH** (\`specrails_specs\`): \`smash\` splits a large spec into child
+  specs (Claude-only); \`smash_undo\` restores (needs the \`smashedAt\` stamp);
+  \`delete_epic_children\` removes a whole family.
+- **Attachments**: \`list_attachments\` / \`get_attachment\` read files the user
+  attached in the app UI; \`generate\` / \`ai_edit\` accept \`attachmentIds\`.
+  Uploading new attachments is not available over MCP.
+- **Jira** (\`specrails_jira\`): per-project connection (the token stays
+  on-device). Jira-backed specs carry a LOCAL numeric id — never a \`PROJ-123\`
+  key; map via \`links\`. Status write-back flows through a durable outbox
+  (\`outbox\`, \`retry_outbox\`).
+- **Code explorer** (\`specrails_code\`): read-only repo browsing — \`tree\`
+  (provenance: which specs/jobs touched each file), \`read_file\`, \`summary\`,
+  \`provenance\`, \`diff\`. There is no MCP write path to files.
+- **Analytics** (\`specrails_analytics\`): \`spending\` aggregates by surface
+  (\`job\`, \`quick-spec\`, \`explore-spec\`, \`ai-edit\`, \`file-summary\`), model,
+  ticket, day. Prefer \`spending\` over raw \`invocations\`/\`export\` for token
+  economy. TWO budget knobs exist: \`specrails_analytics(budget_set,
+  dailyBudgetUsd)\` is PER-PROJECT and pauses that project's queue when
+  exceeded; \`specrails_settings(set, dailyBudgetUsd)\` is the APP-WIDE budget.
+- **Plugins** (\`specrails_plugins\`): per-project MCP integrations; \`preview\`
+  the diff before \`install\`; a degraded plugin never blocks rail launches.
+- **Profiles** (\`specrails_agents\`): per-project agent chains; the baseline
+  trio \`sr-architect\`/\`sr-developer\`/\`sr-reviewer\` is required; routing rules
+  end in a single terminal \`default: true\` rule; requires specrails-core
+  4.1.0 or newer.
+- **Setup** (\`specrails_setup\`): \`prerequisites\` → \`add_project\` →
+  \`install_config\` per provider → ONE \`install\` (provisions all chosen
+  providers; quick-only, offline) → poll \`checkpoints\` until
+  \`isInstalling === false\`.
+- **Loops lifecycle** (\`specrails_loops\`): Draft → \`publish\` (graph-validated)
+  → runnable; \`update\` reverts to Draft and returns 409 while running;
+  \`preview\` dry-runs token resolution without spawning; constants are shared
+  values graphs reference.
 
-## Typical workflow
+## Operating discipline
 
-1. \`specrails_projects(list)\` → pick a project; \`specrails_select_project\`.
-2. \`specrails_specs(list)\` → inspect the backlog. To ADD a spec from a user
-   request, use \`specrails_specs(action:'create')\` — it routes through **Quick
-   Add Spec**: the specrails agent generates a structured spec with AI from the
-   request, exactly like the app's "Add Spec" button (so MCP-created specs are
-   indistinguishable from UI-created ones). It is async — watch the returned ref
-   with \`specrails_watch\`. Use \`from_prompt\` only to store a finished spec verbatim.
-3. \`specrails_rails(set_tickets)\` then \`specrails_rails(launch)\` → run the pipeline;
-   \`specrails_watch\` the returned jobId.
-4. \`specrails_analytics(spending)\` → review cost.
+- Do not mutate statuses the pipeline manages (\`in_progress\`/\`done\` transitions
+  ride job outcomes).
+- Confirm cost-incurring (ai-spawn) and destructive actions with the user
+  first, with cost/risk framing.
+- Report ids and results verbatim; never fabricate outcomes.
+- Use \`specrails_search\` / \`specrails_describe\` to discover the exact action
+  and arguments instead of guessing.
 
 ## Resources
 
-Read-only state is also exposed as MCP resources: \`specrails://projects\`,
-\`specrails://projects/{id}/tickets\`, \`specrails://projects/{id}/rails\`,
-\`specrails://projects/{id}/analytics\`, and \`specrails://guide\` (this document).
+Read-only state is also exposed as MCP resources: \`specrails://guide\` (this
+document), \`specrails://projects\` (all registered projects), and
+\`specrails://projects/{projectId}\` (one project by id).
 `;

package/server/dist/mcp/tools/analytics.js

@@ -91,7 +91,7 @@ function analyticsTools() {
                     .number()
                     .nullable()
                     .optional()
-                    .describe('budget_set: daily budget cap USD (>0); null clears it'),
+                    .describe('budget_set: daily budget cap USD (>0); null clears it. PER-PROJECT daily cap — pauses this project\'s queue when exceeded. For the app-wide budget across all projects use specrails_settings.'),
                 jobCostThresholdUsd: zod_1.z
                     .number()
                     .nullable()

package/server/dist/mcp/tools/app-settings.js

@@ -15,16 +15,31 @@ function appTools() {
         {
             name: 'specrails_settings',
             title: 'App settings',
-            description: 'Read or update app-level Specrails settings (theme, language, daily budget, cost-alert threshold). ' +
-                'Actions: get, set. The MCP enable flag and permission tiers are read-only here (user-controlled in the app).',
+            description: 'Read or update app-level Specrails settings (theme, language, daily budget, cost-alert threshold, Code Explorer summary language + monthly summary budget). ' +
+                'Actions: get, set. The MCP enable flag and permission tiers are read-only here (user-controlled in the app). ' +
+                'dailyBudgetUsd here is APP-WIDE (all projects combined); per-project caps live in specrails_analytics(budget_set).',
             hintTier: 'read',
             tier: (args) => (args.action === 'set' ? 'write' : 'read'),
             inputSchema: {
                 action: zod_1.z.enum(['get', 'set']).describe('Operation'),
                 theme: zod_1.z.enum(WRITABLE_THEMES).optional(),
                 language: zod_1.z.enum(WRITABLE_LANGS).optional(),
-                dailyBudgetUsd: zod_1.z.number().min(0).nullable().optional(),
+                dailyBudgetUsd: zod_1.z
+                    .number()
+                    .min(0)
+                    .nullable()
+                    .optional()
+                    .describe('APP-WIDE daily budget cap USD across all projects; null clears it. Per-project caps live in specrails_analytics(budget_set).'),
                 costAlertThresholdUsd: zod_1.z.number().min(0).nullable().optional(),
+                summaryLanguage: zod_1.z
+                    .enum(['en', 'es'])
+                    .optional()
+                    .describe('Code Explorer file-summary language (app-wide)'),
+                summaryMonthlyBudgetUsd: zod_1.z
+                    .number()
+                    .min(0)
+                    .optional()
+                    .describe('Code Explorer monthly AI file-summary budget in USD (app-wide, default 5)'),
             },
             handler: (ctx, args) => {
                 const db = ctx.desktopDb;
@@ -34,6 +49,9 @@ function appTools() {
                         language: (0, desktop_db_1.getDesktopSetting)(db, 'ui_language') ?? null,
                         dailyBudgetUsd: num((0, desktop_db_1.getDesktopSetting)(db, 'desktop_daily_budget_usd')),
                         costAlertThresholdUsd: num((0, desktop_db_1.getDesktopSetting)(db, 'cost_alert_threshold_usd')),
+                        // Code Explorer settings (same keys + defaults as GET /api/code-explorer-settings)
+                        summaryLanguage: (0, desktop_db_1.getDesktopSetting)(db, 'summary_language') === 'es' ? 'es' : 'en',
+                        summaryMonthlyBudgetUsd: nonNegNum((0, desktop_db_1.getDesktopSetting)(db, 'summary_monthly_budget_usd')) ?? 5.0,
                         mcp: {
                             enabled: (0, mcp_tiers_1.isMcpEnabled)(db),
                             tierWrite: (0, mcp_tiers_1.isTierEnabled)(db, 'write'),
@@ -60,8 +78,25 @@ function appTools() {
                     writeNumOrClear(db, 'cost_alert_threshold_usd', args.costAlertThresholdUsd);
                     changed.push('costAlertThresholdUsd');
                 }
-                if (!changed.length)
-                    throw new Error('set requires at least one field (theme, language, dailyBudgetUsd, costAlertThresholdUsd).');
+                // Code Explorer settings — same validation as PATCH /api/code-explorer-settings.
+                if (args.summaryLanguage !== undefined) {
+                    if (args.summaryLanguage !== 'en' && args.summaryLanguage !== 'es') {
+                        throw new Error("summaryLanguage must be one of: 'en', 'es'.");
+                    }
+                    (0, desktop_db_1.setDesktopSetting)(db, 'summary_language', args.summaryLanguage);
+                    changed.push('summaryLanguage');
+                }
+                if (args.summaryMonthlyBudgetUsd !== undefined) {
+                    const v = args.summaryMonthlyBudgetUsd;
+                    if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) {
+                        throw new Error('summaryMonthlyBudgetUsd must be a non-negative number.');
+                    }
+                    (0, desktop_db_1.setDesktopSetting)(db, 'summary_monthly_budget_usd', String(v));
+                    changed.push('summaryMonthlyBudgetUsd');
+                }
+                if (!changed.length) {
+                    throw new Error('set requires at least one field (theme, language, dailyBudgetUsd, costAlertThresholdUsd, summaryLanguage, summaryMonthlyBudgetUsd).');
+                }
                 return { ok: true, changed };
             },
         },
@@ -73,6 +108,11 @@ function num(v) {
     const n = Number(v);
     return Number.isFinite(n) ? n : null;
 }
+/** Mirror of the code-explorer-settings route parsing: finite AND >= 0, else null. */
+function nonNegNum(v) {
+    const n = num(v);
+    return n !== null && n >= 0 ? n : null;
+}
 function writeNumOrClear(db, key, value) {
     if (value === null)
         (0, desktop_db_1.setDesktopSetting)(db, key, '');

package/server/dist/mcp/tools/chat.js

@@ -19,7 +19,12 @@ function chatTools() {
             name: 'specrails_chat',
             title: 'Chat / Explore',
             description: 'Manage a project\'s chat & Explore-Spec conversations and drive their AI turns. ' +
+                'EXPLORE RECIPE: create(kind:\'explore\', contextScope) → send the bootstrap text "/specrails:explore-spec\\n\\n<idea>" ' +
+                'with {lightweight:true, maxTurns:20} → watch chat_done per turn → spec_draft to read the accumulated draft → ' +
+                'persist via specrails_specs(commit_draft, conversationId=<this conversation>) which preserves origin linkage, ' +
+                'Contract Refine and "Continue Explore". NOTE: spec_draft state is in-memory; it returns {draft:null} after a server restart. ' +
                 'Actions: list_conversations, get (conversation + messages), create (kind sidebar|explore, optional provider/model/contextScope), ' +
+                'update (rename title / change model), ' +
                 'send (cost-incurring — spawns the AI CLI and streams the reply async over WS), abort (interrupt the in-flight turn), ' +
                 'delete (destructive — removes the conversation, its messages, and clears linked draft origin), minimize (arm Explore idle-kill timer), ' +
                 'restore (cancel the idle-kill timer), spec_draft (read the in-memory Explore spec-draft state), messages (persisted history only).',
@@ -59,7 +64,9 @@ function chatTools() {
                 contextScope: zod_1.z
                     .record(zod_1.z.unknown())
                     .optional()
-                    .describe('Explore-only context scope flags for create (mcp/userMcp/full/specrails/openspec/contractRefine)'),
+                    .describe('Explore-only context scope flags for create: {full: repo-wide investigation, specrails: specs context, ' +
+                    'openspec: openspec context, mcp: load project .mcp.json (spawns from repo cwd, slower), ' +
+                    "userMcp: user's approved MCP servers, contractRefine: append Contract Layer on commit}"),
                 // update params
                 title: zod_1.z.string().optional().describe('New title for update'),
                 // send params
@@ -127,7 +134,7 @@ function chatTools() {
                         return {
                             ...r,
                             conversationId: requireConv(),
-                            hint: `Turn accepted (202). The assistant reply streams over WebSocket — use specrails_watch with conversationId "${requireConv()}" to await completion (chat_done / chat_error).`,
+                            hint: `Turn accepted (202). The assistant reply streams over WebSocket — use specrails_watch with conversationId "${requireConv()}" to await completion (chat_done / chat_error). Each send spawns a fresh AI CLI turn (cost); Explore turns accumulate the spec_draft.`,
                         };
                     }
                     case 'abort':

package/server/dist/mcp/tools/code.js

@@ -11,8 +11,9 @@ const types_1 = require("./types");
  *
  * Every op is per-project under `/api/projects/:projectId/code/*`. The v1 edit
  * path (PUT /code/file) is intentionally NOT exposed — Code Explorer is
- * read-only here. The app-level GET/PATCH /api/code-explorer-settings ops are
- * app-scoped settings, surfaced by the settings domain, not here.
+ * read-only here. The app-level code-explorer settings (summary language +
+ * monthly summary budget) are surfaced by specrails_settings
+ * (summaryLanguage / summaryMonthlyBudgetUsd), not here.
  *
  * Encode query strings explicitly so file paths with spaces/`#`/`?` survive.
  */

package/server/dist/mcp/tools/jobs.js

@@ -23,10 +23,11 @@ function jobsTools() {
                 'cancel (destructive — cancels a running/queued job or deletes a terminal one), ' +
                 'purge (destructive — bulk-delete persisted job rows in a date range), ' +
                 'pause / resume (queue), reorder (queued-job order), priority (change a queued job\'s priority), ' +
-                'compare (two jobs side-by-side), export (up to 10k rows as JSON/CSV), ' +
+                'compare (two jobs side-by-side), export (up to 10k rows as JSON/CSV — inlines everything; prefer list/stats for token economy), ' +
                 'diagnostic (binary ZIP — returns a note, not the bytes), run_state (project run state), ' +
+                'pipeline (read a pipeline\'s jobs + statuses — use after composing dependent spawns), ' +
                 'activity (recent activity feed), stats, metrics, default_spec_model, ' +
-                'interactive_turn (ai-spawn — send one more prompt to a running interactive ultracode job), ' +
+                'interactive_turn (ai-spawn — send one more prompt to a running interactive Freestyle/ultracode job), ' +
                 'finalize (finalize a running interactive job).',
             hintTier: 'read',
             tier: (a) => {
@@ -56,6 +57,7 @@ function jobsTools() {
                     'export',
                     'diagnostic',
                     'run_state',
+                    'pipeline',
                     'activity',
                     'stats',
                     'metrics',
@@ -84,7 +86,7 @@ function jobsTools() {
                     .optional()
                     .describe('Priority for spawn / priority action'),
                 dependsOnJobId: zod_1.z.string().optional().describe('Make the spawned job depend on this job id'),
-                pipelineId: zod_1.z.string().optional().describe('Group the spawned job into this pipeline'),
+                pipelineId: zod_1.z.string().optional().describe('Pipeline id: group the spawned job into this pipeline (spawn) / pipeline to read (pipeline)'),
                 profileName: zod_1.z
                     .string()
                     .optional()
@@ -143,7 +145,7 @@ function jobsTools() {
                         });
                         return {
                             ...r,
-                            hint: 'Spawned an AI CLI job (incurs token cost). Use specrails_watch with the returned jobId to await completion.',
+                            hint: 'Spawned an AI CLI job (incurs token cost). Use specrails_jobs(get, jobId) to poll status; specrails_watch settles for this jobId via its 5s job-status poll fallback (terminal events stream only for rail-launched or interactive jobs).',
                         };
                     }
                     case 'cancel': {
@@ -191,7 +193,11 @@ function jobsTools() {
                             qs.set('from', args.from);
                         if (args.to)
                             qs.set('to', args.to);
-                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/jobs/export?${qs.toString()}`);
+                        const data = await (0, types_1.apiCall)(ctx, 'GET', `${base}/jobs/export?${qs.toString()}`);
+                        return {
+                            note: 'Inlines up to 10k rows — prefer list/stats for token economy.',
+                            data,
+                        };
                     }
                     case 'diagnostic': {
                         const id = args.jobId;
@@ -210,6 +216,12 @@ function jobsTools() {
                     }
                     case 'run_state':
                         return (0, types_1.apiCall)(ctx, 'GET', `${base}/state`);
+                    case 'pipeline': {
+                        const id = args.pipelineId;
+                        if (!id)
+                            throw new Error('pipeline requires a "pipelineId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/pipelines/${encodeURIComponent(id)}`);
+                    }
                     case 'activity': {
                         const qs = new URLSearchParams();
                         if (args.limit !== undefined)
@@ -240,7 +252,7 @@ function jobsTools() {
                         const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/jobs/${encodeURIComponent(id)}/messages`, { text });
                         return {
                             ...r,
-                            hint: 'Queued an additional interactive turn (incurs token cost). Use specrails_watch with the jobId to follow the job.',
+                            hint: 'Queued an additional interactive turn (incurs token cost). specrails_watch settles when the whole job finalizes; a single turn\'s completion arrives as job.turn_done in the events array.',
                         };
                     }
                     case 'finalize': {

package/server/dist/mcp/tools/loops.js

@@ -7,11 +7,16 @@ const types_1 = require("./types");
  * Loops — the GLOBAL (cross-project) visual loop-builder library. Routes live at
  * `/api/loops*` and `/api/loop-templates` (NOT under `/projects` — no projectId).
  * Gated server-side by SPECRAILS_LOOPS_SECTION (every route 404s when off).
+ * Exception: the standalone run actions (`run` / `run_get`) ARE project-scoped
+ * (`/api/projects/:projectId/loop-runs*`) — a ticket-less loop runs directly
+ * against a project with no rail and no ticket.
  *
  * A single domain-facade tool with an `action` enum and a dynamic tier:
- *   - read:        list, get, templates, factory, commands, constants_list, preview
+ *   - read:        list, get, templates, factory, commands, constants_list,
+ *                  preview, run_get
  *   - write:       constant_create, constant_update, import, create, from_template,
  *                  fork, update, publish, unpublish, duplicate
+ *   - ai-spawn:    run (spawns an AI CLI, incurs cost, async 202)
  *   - destructive: constant_delete, delete
  */
 function loopsTools() {
@@ -20,7 +25,9 @@ function loopsTools() {
             name: 'specrails_loops',
             title: 'Loops',
             description: 'Manage the global (cross-project) loop library and its templates/factory/constants. ' +
-                'Loops are visual builder graphs reused across projects; this is an APP-LEVEL domain (no projectId). ' +
+                'Loops are visual builder graphs reused across projects; this is an APP-LEVEL domain (no projectId, except the run actions). ' +
+                'To RUN a loop on a project\'s tickets: publish it, then specrails_rails(launch, mode:\'loop\', loopId=…). ' +
+                'For a standalone ticket-less run use the run action. ' +
                 'Actions: ' +
                 'list (all saved loops), ' +
                 'get (one loop by id), ' +
@@ -37,12 +44,16 @@ function loopsTools() {
                 'update (name/description/graph — reverts to Draft, 409 while running), ' +
                 'publish (graph-validated), unpublish (409 while running), ' +
                 'duplicate (copy a loop), ' +
-                'delete (destructive — 409 while running).',
+                'delete (destructive — 409 while running), ' +
+                'run (ai-spawn — standalone ticket-less run of a Published loop against a project: spawns an AI CLI, incurs token cost, returns 202 with loopRunId), ' +
+                'run_get (read one loop run\'s live/terminal state — the post-timeout recovery read).',
             hintTier: 'read',
             tier: (a) => {
                 const action = a.action;
                 if (action === 'delete' || action === 'constant_delete')
                     return 'destructive';
+                if (action === 'run')
+                    return 'ai-spawn';
                 if ([
                     'constant_create',
                     'constant_update',
@@ -81,9 +92,16 @@ function loopsTools() {
                     'unpublish',
                     'duplicate',
                     'delete',
+                    'run',
+                    'run_get',
                 ])
                     .describe('Operation to perform'),
-                loopId: zod_1.z.string().optional().describe('Loop id (for get / update / publish / unpublish / duplicate / delete)'),
+                projectId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Project id (run / run_get only — defaults to the active project; ignored by every other action)'),
+                loopId: zod_1.z.string().optional().describe('Loop id (for get / update / publish / unpublish / duplicate / delete / run — must be Published for run)'),
+                loopRunId: zod_1.z.string().optional().describe('Loop run id (for run_get — returned by run)'),
                 constantId: zod_1.z.string().optional().describe('Constant id (for constant_update / constant_delete)'),
                 templateId: zod_1.z.string().optional().describe('Template id (for from_template)'),
                 factoryId: zod_1.z.string().optional().describe('Factory loop id (for fork)'),
@@ -97,7 +115,18 @@ function loopsTools() {
                     .optional()
                     .describe('Loop graph object { nodes, edges, ... } (for create / update; required for preview)'),
                 value: zod_1.z.string().optional().describe('Constant value (for constant_create / constant_update)'),
-                provider: zod_1.z.string().optional().describe('Provider for token resolution in preview (default "claude")'),
+                provider: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Provider for token resolution in preview (default "claude") / AI engine for run (must be installed on the project; default = project primary)'),
+                model: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Model for run — validated against the chosen provider\'s catalog; omit for the provider default'),
+                reasoning_effort: zod_1.z
+                    .enum(['low', 'medium', 'high'])
+                    .optional()
+                    .describe('Reasoning-effort tier for run'),
                 loops: zod_1.z.array(zod_1.z.unknown()).optional().describe('Array of loop export envelopes (for import)'),
             },
             async handler(ctx, args) {
@@ -214,6 +243,29 @@ function loopsTools() {
                             ...(args.name !== undefined ? { name: args.name } : {}),
                         });
                     }
+                    // ── Standalone runs (project-scoped) ────────────────────────────────
+                    case 'run': {
+                        if (!loopId)
+                            throw new Error('run requires a "loopId" (the loop must be Published).');
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/loop-runs`, {
+                            loopId,
+                            ...(args.provider !== undefined ? { provider: args.provider } : {}),
+                            ...(args.model !== undefined ? { model: args.model } : {}),
+                            ...(args.reasoning_effort !== undefined ? { reasoning_effort: args.reasoning_effort } : {}),
+                        });
+                        return {
+                            ...r,
+                            hint: 'Run accepted (202). Use specrails_watch with the returned loopRunId (loop.run_completed / loop.run_stopped are terminal), or poll specrails_loops(run_get, loopRunId) after a timeout.',
+                        };
+                    }
+                    case 'run_get': {
+                        const loopRunId = args.loopRunId;
+                        if (!loopRunId)
+                            throw new Error('run_get requires a "loopRunId".');
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/loop-runs/${encodeURIComponent(loopRunId)}`);
+                    }
                     // ── Destructive ─────────────────────────────────────────────────────
                     case 'delete': {
                         if (!loopId)