specrails-desktop 2.25.0 → 2.26.1

package/server/dist/agent-operator-prompt.js

@@ -37,11 +37,12 @@ coding pipelines over them.
 - **Rail** — a persistent numbered launch slot that REMEMBERS its config across
   launches (assigned tickets, mode, profile, engine, name). Modes: \`implement\`
   (one pipeline job — Architect → Developer → Reviewer → Ship — over the rail's
-  tickets), \`batch-implement\` (dependency-aware waves), Freestyle (wire value
-  \`ultracode\` — hands the spec straight to the model, one job per ticket,
-  Claude-only, optional interactive in-job chat), \`loop\` (runs a saved
-  workflow graph per ticket). Launching spawns AI CLI processes that WRITE CODE,
-  RUN TESTS and COMMIT in the repo — it costs money and runs for minutes.
+  tickets), \`batch-implement\` (dependency-aware waves), Freestyle (API mode
+  value \`freestyle\` only — call it \`Freestyle\` in prose; it sends a free-form
+  autonomous prompt straight to Claude, one job per ticket, Claude-only,
+  optional interactive in-job chat), \`loop\` (runs a saved workflow graph per
+  ticket). Launching spawns AI CLI processes that WRITE CODE, RUN TESTS and
+  COMMIT in the repo — it costs money and runs for minutes.
 - **Job** — one spawned run. Outcomes mutate spec status AUTOMATICALLY: launch →
   \`in_progress\`; success → \`done\`; revert → back to \`todo\`; partial confidence →
   \`done\` + \`needs_review\`. NEVER patch a status the pipeline manages; only
@@ -76,6 +77,11 @@ coding pipelines over them.
   outcome. Never claim success from the 202 acceptance alone.
 - Prefer \`specrails_guide\` / \`specrails_search\` / \`specrails_describe\` to
   discover the exact action and arguments before calling an unfamiliar tool.
+- **User-facing naming:** always call the free-form autonomous rail mode
+  \`Freestyle\`. The canonical API / id / token values are \`freestyle\`,
+  \`factory:freestyle\`, and \`{{cmd:freestyle}}\`; use those exact values inside
+  tool arguments or when quoting raw data. Do not invent or use another name for
+  this capability.
 - Ground claims about the user's code with
   \`specrails_code(tree | read_file | summary)\` before asserting how the codebase
   works; \`specrails_projects(get)\` returns the repo's absolute path.
@@ -112,6 +118,39 @@ tool for exactly that, and never refuse or push this back to the user's terminal
   (\`rm -rf\`, force-push, branch deletion, history rewrite) to "make something
   work" — surface the blocker instead.
 
+## Support & troubleshooting
+
+When the user asks for help installing or using Specrails, asks "how do I...?",
+reports a broken setup, provider CLI/auth issue, MCP/Agent Chat issue, failed
+job, missing agents/skills/slash commands, PR-delivery confusion, costs, or
+plugin trouble, this is SUPPORT — not backlog work. Call
+\`specrails_support(action:'triage', question, projectId?)\` first and answer
+from its diagnostics/playbook. Do NOT create or propose a spec unless the user
+explicitly pivots from troubleshooting to product work.
+
+For job failures that mention missing agents, missing skills, missing
+\`/specrails:*\` commands, \`/opsx:*\` commands, "baseline agents", or a
+command not installed, explain the storage model correctly: upstream agents,
+skills and slash commands live in the app-global specrails-core framework, NOT
+inside the selected project. Give the user the repair path:
+
+- If global core may be stale, offer
+  \`specrails_support(action:'core_update_check')\`, then with confirmation
+  \`specrails_support(action:'core_update_apply')\`.
+- If global core is current and there is no concrete failing job/error, say the
+  core installation looks healthy. Do NOT infer a MyProject problem from
+  \`setup/checkpoints\`.
+- A setup checkpoint summary showing pending checkpoints, 0 agents, or
+  0 \`specrails:*\` commands is NOT a specrails-core health signal and is NOT a
+  reason to run \`specrails_setup(install)\`. Do not say they "live in
+  MyProject", and do not claim MyProject's projection is broken from that alone.
+- If a real job still reports missing core definitions while global core is
+  current, ask for/read \`specrails_jobs(get)\` or \`specrails_jobs(diagnostic)\`
+  and report it as a framework-loading/job diagnostic issue, not a project setup
+  checkpoint issue.
+- Manual fallback for standalone/legacy core installs: from the project root run
+  \`npx specrails-core@latest update\`, then retry the job.
+
 ## Permission ladder & confirmation rules
 
 Your actions are gated by a cumulative level the user steers live with
@@ -141,7 +180,9 @@ above the current level, say so up front.
 
 ## Think in specs (default stance)
 
-When the user describes work to be done, the natural unit is a SPEC:
+When the user describes product/code work to be done, the natural unit is a
+SPEC. This default does NOT apply to support/troubleshooting questions; route
+those through \`specrails_support\` instead.
 
 1. Check the backlog for duplicates first: \`specrails_specs(list)\`.
 2. Capture the work as a spec — pick the right creation path (next section).
@@ -331,8 +372,14 @@ summary later.
   is explicit, covering Jira projects whose Review status has not been mapped to
   Specrails \`on_review\`. You do NOT need to know or pass the branch name. If
   there is no confident open PR match, the normal new-work flow is preserved.
+- A published PR card (\`decision:'pr_ready'\`) is STILL an open PR continuation
+  target, not a blocker. If the user asks for modifications on that PR, assign
+  the same spec(s) to a rail and launch again; do NOT tell them they must publish,
+  discard, or merge first. \`pr_decision_pending\` should only block unresolved
+  deliveries with no continuable PR head yet.
 - Launch proposal shape: tickets (ids + titles), rail number, mode, engine and
-  model/profile, plus "runs for minutes and costs money". Wait for yes.
+  model/profile, plus "runs for minutes and costs money". If the API mode is
+  \`freestyle\`, write "Freestyle" to the user. Wait for yes.
 - **Parallel launches are safe and normal.** Every rail launch runs its work in
   its own isolated git worktree, so launching several rails at the same time
   never makes them collide — spread independent specs across rails and launch
@@ -343,9 +390,9 @@ summary later.
   tickets to the returned \`railIndex\`, and launch. Never wedge waiting for a
   slot and never steal a configured rail's tickets to free one.
 - **Launching many rails**: \`specrails_rails(launch_all)\` launches every rail
-  that has tickets and no active run / pending PR decision in ONE call, each
-  with its own stored mode/engine/profile, and returns per-rail outcomes
-  (launched / skipped with reason / failed) — report them per rail. It is
+  that has tickets and no active run / uncontinuable pending PR decision in ONE
+  call, each with its own stored mode/engine/profile, and returns per-rail
+  outcomes (launched / skipped with reason / failed) — report them per rail. It is
   ai-spawn: propose it with the total rail + spec count and cost framing
   first. One yes covers the whole batch when the user asked for the batch
   ("launch everything") — do not re-ask per rail.
@@ -424,4 +471,4 @@ When the user has no projects yet, or asks to add one:
 Setup is QUICK-only (fast, offline). Do NOT offer, mention, or attempt a "full"
 or "enrich" install — that flow is deprecated and not available through you.
 `;
-exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; short async 202 ops (spec generation, ai-edit) may be awaited with specrails_watch (projectId required), but after a rail/job LAUNCH is accepted end your reply immediately — progress streams live in the conversation's run card and the app; watch a launched run only when the user explicitly asks you to wait, with a bounded untilMs; never claim success from a 202 acceptance alone — verify from a terminal event or a domain read (e.g. specrails_jobs get); respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when refining a spec, ground it in the real codebase FIRST (specrails_code tree/read_file/summary + specrails_specs list) and show the evolving draft as one fenced spec-draft JSON block (title, description, labels, priority, acceptanceCriteria) at the end of each turn that changed it — the app renders it as a live card; persist the refined spec with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; commit_draft appends a Contract Layer by default via one short background AI pass — pass contractRefine false when the user declines it; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise.`;
+exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; support/troubleshooting/install/usage/job-failure questions use specrails_support first and never become specs unless the user pivots to product work; missing agents/skills/slash commands concern the app-global specrails-core framework, never project-owned files — never say agents/skills/commands live inside the project; project setup checkpoints are not a core health signal, so pending/0 agents/0 commands must not trigger specrails_setup(install) or a project repair recommendation; offer core_update_check/core_update_apply only for global core updates, and if global core is current ask for the concrete job error/diagnostic; an on_review spec with an open PR, including a published pr_ready card, can be relaunched to continue that PR branch — do not require publish/discard/merge first; short async 202 ops (spec generation, ai-edit) may be awaited with specrails_watch (projectId required), but after a rail/job LAUNCH is accepted end your reply immediately — progress streams live in the conversation's run card and the app; watch a launched run only when the user explicitly asks you to wait, with a bounded untilMs; never claim success from a 202 acceptance alone — verify from a terminal event or a domain read (e.g. specrails_jobs get); call the free-form autonomous rail mode Freestyle in prose — freestyle/factory:freestyle/{{cmd:freestyle}} are canonical API/id/token values for that same capability; respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when refining a spec, ground it in the real codebase FIRST (specrails_code tree/read_file/summary + specrails_specs list) and show the evolving draft as one fenced spec-draft JSON block (title, description, labels, priority, acceptanceCriteria) at the end of each turn that changed it — the app renders it as a live card; persist the refined spec with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; commit_draft appends a Contract Layer by default via one short background AI pass — pass contractRefine false when the user declines it; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise.`;

package/server/dist/agent-store.js

@@ -11,24 +11,35 @@ exports.findAgentSystemMessage = findAgentSystemMessage;
 exports.updateAgentMessageContent = updateAgentMessageContent;
 const crypto_1 = require("crypto");
 const agent_tier_1 = require("./agent-tier");
-function mapMessage(row) {
-    let ids = [];
-    if (row.attachment_ids) {
-        try {
-            const parsed = JSON.parse(row.attachment_ids);
-            if (Array.isArray(parsed))
-                ids = parsed.filter((x) => typeof x === 'string');
-        }
-        catch {
-            /* ignore malformed */
-        }
+function parseJsonArray(raw, predicate) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.filter(predicate) : [];
+    }
+    catch {
+        return [];
     }
+}
+function isContextRef(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const row = value;
+    return (typeof row.kind === 'string' &&
+        typeof row.id === 'string' &&
+        typeof row.label === 'string' &&
+        typeof row.token === 'string');
+}
+function mapMessage(row) {
+    const ids = parseJsonArray(row.attachment_ids, (x) => typeof x === 'string');
     return {
         id: row.id,
         conversation_id: row.conversation_id,
         role: row.role,
         content: row.content,
         attachment_ids: ids,
+        context_refs: parseJsonArray(row.context_refs, isContextRef),
         created_at: row.created_at,
     };
 }
@@ -71,7 +82,8 @@ function deleteAgentConversation(db, id) {
 function addAgentMessage(db, input) {
     const id = (0, crypto_1.randomUUID)();
     const attachmentIds = input.attachmentIds && input.attachmentIds.length ? JSON.stringify(input.attachmentIds) : null;
-    db.prepare('INSERT INTO agent_messages (id, conversation_id, role, content, attachment_ids) VALUES (?, ?, ?, ?, ?)').run(id, input.conversationId, input.role, input.content, attachmentIds);
+    const contextRefs = input.contextRefs && input.contextRefs.length ? JSON.stringify(input.contextRefs) : null;
+    db.prepare('INSERT INTO agent_messages (id, conversation_id, role, content, attachment_ids, context_refs) VALUES (?, ?, ?, ?, ?, ?)').run(id, input.conversationId, input.role, input.content, attachmentIds, contextRefs);
     // Touch the parent so the list stays ordered by latest activity.
     db.prepare("UPDATE agent_conversations SET updated_at = datetime('now') WHERE id = ?").run(input.conversationId);
     return mapMessage(db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id));

package/server/dist/db.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ULTRACODE_PRE_PROMPT = void 0;
+exports.DEFAULT_FREESTYLE_PRE_PROMPT = void 0;
 exports.initDb = initDb;
 exports.createJob = createJob;
 exports.markJobInteractive = markJobInteractive;
@@ -39,7 +39,7 @@ exports.skipJob = skipJob;
 exports.getPipelineJobs = getPipelineJobs;
 exports.getStats = getStats;
 exports.getProjectSettings = getProjectSettings;
-exports.getUltracodePrePrompt = getUltracodePrePrompt;
+exports.getFreestylePrePrompt = getFreestylePrePrompt;
 exports.updateProjectSettings = updateProjectSettings;
 exports.getQuickContractRefineLast = getQuickContractRefineLast;
 exports.hasQuickContractRefineLast = hasQuickContractRefineLast;
@@ -643,7 +643,7 @@ const MIGRATIONS = [
         }
     },
     // Migration 32: jobs.interactive — 1 when the job is an interactive persistent
-    // ultracode session (the user sends multiple prompts across turns; the job
+    // freestyle session (the user sends multiple prompts across turns; the job
     // stays 'running' until an explicit finalize, at which point every turn's real
     // tokens/cost/num_turns are already summed into the row and status flips to
     // 'completed'); 0 (default) for standard autonomous jobs. Additive + idempotent
@@ -1226,13 +1226,13 @@ function getStats(db) {
 }
 // ─── Project settings ─────────────────────────────────────────────────────────
 /**
- * Default pre-prompt used by Ultracode (Claude-only rails) when the project
- * has no per-project override. Ultracode skips the OpenSpec pipeline entirely:
+ * Default pre-prompt used by Freestyle (Claude-only rails) when the project
+ * has no per-project override. Freestyle skips the OpenSpec pipeline entirely:
  * it hands Claude the spec text plus this instruction and lets it work
  * autonomously end-to-end.
  */
-exports.DEFAULT_ULTRACODE_PRE_PROMPT = [
-    'You are operating in ULTRACODE: fully autonomous, end-to-end implementation.',
+exports.DEFAULT_FREESTYLE_PRE_PROMPT = [
+    'You are operating in FREESTYLE: fully autonomous, end-to-end implementation.',
     'Implement the following spec COMPLETELY in this repository. You have full access to the codebase and tools.',
     'Work independently until the feature is done: write the code, the tests, update docs as needed, and make sure everything builds and the test suite passes.',
     'Do NOT follow any structured architect/developer/reviewer pipeline — use your own judgement and the repo conventions.',
@@ -1242,21 +1242,21 @@ function getProjectSettings(db) {
     const telemetryRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.pipeline_telemetry_enabled'`).get();
     const modelRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.orchestrator_model'`).get();
     const prePromptRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.pre_prompt'`).get();
-    const ultraPrePromptRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.ultracode_pre_prompt'`).get();
+    const freestylePrePromptRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.freestyle_pre_prompt'`).get();
     const integrationBranchRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.integration_branch'`).get();
     return {
         pipelineTelemetryEnabled: telemetryRow?.value === 'true',
         orchestratorModel: modelRow?.value ?? 'sonnet',
         prePrompt: prePromptRow?.value ?? '',
-        ultraPrePrompt: ultraPrePromptRow?.value ?? '',
+        freestylePrePrompt: freestylePrePromptRow?.value ?? '',
         integrationBranch: integrationBranchRow?.value ?? '',
     };
 }
-/** Resolve the effective Ultracode pre-prompt: the per-project override when
+/** Resolve the effective Freestyle pre-prompt: the per-project override when
  *  set, otherwise the built-in default. */
-function getUltracodePrePrompt(db) {
-    const override = getProjectSettings(db).ultraPrePrompt.trim();
-    return override || exports.DEFAULT_ULTRACODE_PRE_PROMPT;
+function getFreestylePrePrompt(db) {
+    const override = getProjectSettings(db).freestylePrePrompt.trim();
+    return override || exports.DEFAULT_FREESTYLE_PRE_PROMPT;
 }
 function updateProjectSettings(db, patch) {
     if (patch.pipelineTelemetryEnabled !== undefined) {
@@ -1273,12 +1273,12 @@ function updateProjectSettings(db, patch) {
             db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.pre_prompt', ?)`).run(patch.prePrompt);
         }
     }
-    if (patch.ultraPrePrompt !== undefined) {
-        if (patch.ultraPrePrompt.trim() === '') {
-            db.prepare(`DELETE FROM queue_state WHERE key = 'config.ultracode_pre_prompt'`).run();
+    if (patch.freestylePrePrompt !== undefined) {
+        if (patch.freestylePrePrompt.trim() === '') {
+            db.prepare(`DELETE FROM queue_state WHERE key = 'config.freestyle_pre_prompt'`).run();
         }
         else {
-            db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.ultracode_pre_prompt', ?)`).run(patch.ultraPrePrompt);
+            db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.freestyle_pre_prompt', ?)`).run(patch.freestylePrePrompt);
         }
     }
     if (patch.integrationBranch !== undefined) {

package/server/dist/desktop-db.js

@@ -430,6 +430,12 @@ function applyDesktopMigrations(db) {
         CREATE INDEX IF NOT EXISTS idx_agent_inv_conv ON agent_invocations(conversation_id);
       `);
         },
+        // 21: structured context refs selected in the Agent Composer (`@`, `#`, `/`,
+        // and the `+` palette). Persisted with the user row so conversation bubbles
+        // can re-render exact chips after refresh without guessing from text.
+        () => {
+            db.exec(`ALTER TABLE agent_messages ADD COLUMN context_refs TEXT;`);
+        },
     ];
     for (let i = 0; i < migrations.length; i++) {
         const version = i + 1;

package/server/dist/desktop-router.js

@@ -64,7 +64,11 @@ function isGeminiBetaDisabled() {
 }
 // Theme allow-list. Mirror of THEME_IDS in `client/src/lib/themes.ts` —
 // kept duplicated to avoid pulling client code into the server bundle.
-const THEME_ID_ALLOWLIST = new Set(['dracula', 'aurora-light', 'obsidian-dark', 'matrix', 'specrails']);
+const THEME_ID_ALLOWLIST = new Set(['dracula', 'aurora-light', 'obsidian-dark', 'code-rain', 'specrails', 'galaxy']);
+const LEGACY_THEME_ID_MAP = {
+    'star-wars': 'galaxy',
+    matrix: 'code-rain',
+};
 // Language allow-list. Mirror of LANGUAGE_IDS in `client/src/lib/i18n.ts` —
 // kept duplicated to avoid pulling client code into the server bundle.
 const LANGUAGE_ID_ALLOWLIST = new Set(['en', 'es', 'fr', 'de', 'pt', 'it', 'zh', 'ja']);
@@ -840,7 +844,10 @@ function createDesktopRouter(registry, broadcast) {
     // Persisted under desktop_settings key `ui_theme`. Default seeded by migration 8.
     router.get('/theme', (_req, res) => {
         const stored = (0, desktop_db_1.getDesktopSetting)(registry.desktopDb, 'ui_theme');
-        const theme = stored && THEME_ID_ALLOWLIST.has(stored) ? stored : 'specrails';
+        const migrated = stored ? LEGACY_THEME_ID_MAP[stored] : undefined;
+        const theme = migrated ?? (stored && THEME_ID_ALLOWLIST.has(stored) ? stored : 'specrails');
+        if (migrated)
+            (0, desktop_db_1.setDesktopSetting)(registry.desktopDb, 'ui_theme', migrated);
         res.json({ theme });
     });
     router.patch('/theme', (req, res) => {

package/server/dist/feature-flags.js

@@ -29,8 +29,8 @@ function isJiraEnabled() {
     return process.env.SPECRAILS_JIRA_SECTION !== 'false';
 }
 /**
- * Interactive ultracode jobs: when launched with the rail's "Interactive"
- * toggle, an ultracode (Claude-only) job becomes a persistent chat session —
+ * Interactive freestyle jobs: when launched with the rail's "Interactive"
+ * toggle, an freestyle (Claude-only) job becomes a persistent chat session —
  * the user sends multiple prompts across turns, the job stays resident until an
  * explicit "Finalize Job" action, and every turn's real token spend is summed
  * into the single job row. Server-side default ON; set

package/server/dist/index.js

@@ -541,7 +541,7 @@ function applyPtyWsRateLimiting(ws) {
         mcpManager.start().catch((err) => console.error('[mcp] boot start failed:', err));
     }
     // ─── App-global agent chat (drives the app via its own MCP) ────────────────
-    const agentChatManager = new agent_chat_manager_1.AgentChatManager(broadcast, registry.desktopDb, port);
+    const agentChatManager = new agent_chat_manager_1.AgentChatManager(broadcast, registry.desktopDb, port, registry);
     _agentChatManager = agentChatManager;
     // Publish the instance to the process-wide registry so the rails layer can
     // post PR-decision cards (safe-pr-review-flow). Left null when agent chat is

package/server/dist/interactive-job-session.js

@@ -8,9 +8,9 @@
 // newline-delimited stream-json message written to stdin, the agent works, and
 // the turn ends on a `result` event WITHOUT killing the child. Two settle modes:
 //
-//   'finalize' (ultracode) — the session idles between turns until the user
+//   'finalize' (freestyle) — the session idles between turns until the user
 //     explicitly finalizes (SIGTERM), at which point QueueManager flips the job
-//     to a terminal status. Byte-identical to the original interactive-ultracode
+//     to a terminal status. Byte-identical to the original interactive-freestyle
 //     behaviour.
 //   'auto' (every other command — the default-interactive flip) — the session
 //     settles ITSELF the moment it goes QUIESCENT: a turn `result` arrived and
@@ -163,7 +163,7 @@ class InteractiveJobSession {
         this._nextEventSeq = deps.nextEventSeq ?? null;
         this._spawn = deps.spawn ?? cli_prompt_1.spawnAiCli;
     }
-    /** Spawn the resident child and run the first turn (the ultracode prompt). */
+    /** Spawn the resident child and run the first turn (the freestyle prompt). */
     start(spec, firstPrompt) {
         const child = this._spawn(spec.binary, spec.args, {
             env: spec.env ?? process.env,

package/server/dist/loop-command-catalog.js

@@ -8,12 +8,12 @@
  *    claude `/specrails:<name>`, codex `$<name>` (skill), gemini `/specrails:<name>`.
  *    Mirrors QueueManager's rail invocation (`/specrails:implement #1 #2 --yes`).
  *  - `template`: a provider-invariant curated prompt (no core coupling).
- *  - `native`: a raw autonomous command (ultracode) — claude-only, NOT a slash
+ *  - `native`: a raw autonomous Freestyle command — claude-only, NOT a slash
  *    command; it expands to a self-contained autonomous prompt.
  *
  * Each command declares its TICKET SCOPE:
  *  - `all`        → one run over ALL the rail's tickets (`#1 #2 #3`). implement, batch.
- *  - `per-ticket` → one run per ticket. ultracode (and the default).
+ *  - `per-ticket` → one run per ticket. Freestyle (and the default).
  *
  * Expansion order in the engine: `expandCommands()` FIRST (injects the ticket ids),
  * then `interpolateSpec()` resolves any remaining `{{spec.*}}` data tokens.
@@ -24,10 +24,10 @@ exports.getLoopCommand = getLoopCommand;
 exports.expandCommands = expandCommands;
 exports.dominantTicketScope = dominantTicketScope;
 exports.referencesClaudeOnlyCommand = referencesClaudeOnlyCommand;
-/** The autonomous prompt a `native` command (ultracode) expands to for the
- *  LoopRunManager path. Factory ultracode loops route to QueueManager's real
- *  `_buildUltracodePrompt` instead (phase A); this is the custom-loop fallback. */
-const ULTRACODE_PROMPT = [
+/** The autonomous prompt a `native` command (Freestyle) expands to for the
+ *  LoopRunManager path. Factory Freestyle loops route to QueueManager's real
+ *  `_buildFreestylePrompt` instead (phase A); this is the custom-loop fallback. */
+const FREESTYLE_PROMPT = [
     'Implement the following spec completely and autonomously. Explore the codebase first, then write the code and tests and make the full test suite pass. Work end-to-end without stopping for confirmation; do not open a pipeline — just do it.',
     '',
     'Title: {{spec.title}}',
@@ -68,9 +68,9 @@ exports.LOOP_COMMANDS = [
         ticketScope: 'all',
     },
     {
-        name: 'ultracode',
-        label: 'ultracode',
-        description: 'Autonomous per-ticket implementation — Claude works the spec end-to-end with no pipeline. Claude only.',
+        name: 'freestyle',
+        label: 'Freestyle',
+        description: 'Free-form autonomous per-ticket implementation — Claude receives the spec as a prompt and works it end-to-end with no pipeline. Claude only. Internal token: {{cmd:freestyle}}.',
         native: true,
         claudeOnly: true,
         ticketScope: 'per-ticket',
@@ -241,7 +241,7 @@ function expandCommands(text, opts) {
         if (cmd.coreCommand)
             return nativeInvocation(cmd.coreCommand, opts.provider, ids);
         if (cmd.native)
-            return ULTRACODE_PROMPT;
+            return FREESTYLE_PROMPT;
         // Provider-native prefix (e.g. {{cmd:loop}} → /loop | $goal) wins for the
         // providers it lists; everyone else falls back to the generic template.
         if (cmd.providerNative) {
@@ -267,7 +267,7 @@ function dominantTicketScope(text) {
     }
     return sawPerTicket ? 'per-ticket' : 'per-ticket';
 }
-/** True if a prompt references any claude-only command (e.g. ultracode). */
+/** True if a prompt references any claude-only command (e.g. Freestyle's canonical token). */
 function referencesClaudeOnlyCommand(text) {
     for (const m of text.matchAll(CMD_TOKEN_RE)) {
         if (COMMANDS_BY_NAME.get(m[1])?.claudeOnly)

package/server/dist/loop-factory.js

@@ -30,15 +30,15 @@ exports.FACTORY_LOOPS = [
         graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:batch}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
     },
     {
-        id: 'factory:ultracode',
-        // Renamed from "Ultracode": the mode hands the spec straight to the model
+        id: 'factory:freestyle',
+        // User-facing name for the canonical freestyle mode: it hands the spec straight to the model
         // with full freedom — no pipeline, it works like a regular coding agent.
-        // The id/mode strings stay 'ultracode' (wire + rail back-compat).
+        // The id/mode strings are the canonical rail contract.
         name: 'Freestyle',
         description: 'Hands the spec straight to the model with full freedom — no pipeline, it works like a regular coding agent, then verify + refine until green. Claude only.',
-        mode: 'ultracode',
+        mode: 'freestyle',
         claudeOnly: true,
-        graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:ultracode}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
+        graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:freestyle}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
     },
     {
         id: 'factory:openspec',
@@ -67,7 +67,7 @@ function factoryLoopForMode(mode) {
         return FACTORY_BY_ID.get('factory:implement');
     if (mode === 'batch-implement')
         return FACTORY_BY_ID.get('factory:batch');
-    if (mode === 'ultracode')
-        return FACTORY_BY_ID.get('factory:ultracode');
+    if (mode === 'freestyle')
+        return FACTORY_BY_ID.get('factory:freestyle');
     return undefined;
 }

package/server/dist/loop-graph.js

@@ -129,13 +129,13 @@ function successors(graph, nodeId) {
         .filter((n) => n !== undefined);
 }
 /** Whether a loop "needs a ticket/spec" — it references a `{{spec.*}}` token or a
- *  ticket-consuming command (`{{cmd:implement|batch|ultracode}}`). Ticket-needing
+ *  ticket-consuming command (`{{cmd:implement|batch|freestyle}}`). Ticket-needing
  *  loops belong on a rail (the rail provides the spec). Ticket-LESS loops are
  *  standalone (repo-wide CI watch, lint, audit…) and run from the Loops page's
  *  "Run" action, NOT a rail — launching one on a rail would just re-run the same
  *  spec-less loop once per ticket. Mirrors the client's `loop-ticket-need.ts`. */
 const SPEC_TOKEN_RE = /\{\{\s*spec\./;
-const TICKET_CMD_RE = /\{\{\s*cmd:(implement|batch|ultracode)\b/;
+const TICKET_CMD_RE = /\{\{\s*cmd:(implement|batch|freestyle)\b/;
 function loopNeedsTicket(graph) {
     if (!graph)
         return false;

package/server/dist/loop-run-manager.js

@@ -220,7 +220,7 @@ class LoopRunManager {
             railIndex: req.railIndex ?? null,
         });
         // Surface the run as a JOB so the full session streams live in the Jobs list
-        // + JobDetail, exactly like implement/ultracode. The job id IS the run id;
+        // + JobDetail, exactly like implement/freestyle. The job id IS the run id;
         // createJob is idempotent. Synchronous (before the first await) so the row
         // exists by the time the launch responds → "View Log" never 404s.
         const jobCommand = `loop: ${req.loopName ?? req.loopId}${req.ticketId != null ? ` #${req.ticketId}` : ''}`;

package/server/dist/mcp/guide.js

@@ -53,6 +53,13 @@ Codex, Gemini) to implement specs.
 
 ## Creating specs — three paths, one decision rule
 
+Before creating a spec, classify the user's intent. If they are asking for
+help using Specrails, installation/setup, a failed job, missing agents/skills,
+MCP connection, provider auth, GitHub/PR delivery, costs, or "how do I...?"
+support, DO NOT create a spec. Call \`specrails_support(action:'triage')\`
+and solve it conversationally first. Only move to spec creation when the user
+explicitly asks for product/backlog work.
+
 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
@@ -105,15 +112,20 @@ heading inside the description); \`labels\`; \`priority\`. Spec content is Engli
   other work, create one and proceed; never wait for a slot.
 - Parallel launches are safe and normal: each launch isolates its work in
   per-ticket git worktrees, so several rails can run at once. \`launch_all\`
-  (ai-spawn) launches EVERY rail that has tickets and no active run / pending
-  PR decision in one call, each with its stored mode/engine/profile, returning
-  per-rail outcomes (launched / skipped with reason / failed).
+  (ai-spawn) launches EVERY rail that has tickets and no active run /
+  uncontinuable pending PR decision in one call, each with its stored
+  mode/engine/profile, returning per-rail outcomes (launched / skipped with
+  reason / failed).
 - Relaunching an \`on_review\` ticket with a matching OPEN GitHub PR continues
   that PR's head branch automatically. Jira-linked \`in_progress\` tickets can
   also continue an open PR when the match is explicit, covering Jira projects
   whose Review status has not been mapped to Specrails \`on_review\`. New
   tickets, or tickets without a confident open-PR match, keep the normal
   branch-from-integration flow.
+- A published PR delivery (\`decision:'pr_ready'\`) is still an open PR
+  continuation target when it has a PR URL/head branch covering the rail's
+  tickets. Do not tell the user to Publish/Discard/Merge first when they ask for
+  more changes on that same PR; assign the spec(s) to a rail and launch again.
 - Projects without Git cannot use isolated worktrees or PR continuation. A
   launch degrades to shared-cwd execution and returns \`isolationUnavailable\`;
   explain that it writes directly to files and no PR card/branch will appear.
@@ -123,9 +135,11 @@ heading inside the description); \`labels\`; \`priority\`. Spec content is Engli
   - \`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)\`).
+  - Freestyle: sends a free-form autonomous prompt straight to Claude — one job
+    per ticket; Claude-only; \`model\` picker; optional \`interactive\` in-job
+    chat (settle with \`specrails_jobs(finalize)\`). To launch it through the API,
+    pass the canonical mode value \`freestyle\`. In user-facing language, call
+    the feature "Freestyle".
   - \`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
@@ -169,7 +183,10 @@ Tools cannot raise their own permissions in either regime. Common tiers:
 list/get/spending/watch = read; commit_draft, from_prompt, update, set_tickets,
 create_rail, plugin install, Jira connect = write; spec create/generate, rail
 launch/launch_all, chat send, job spawn = ai-spawn; spec delete, rail stop, job
-purge, plugin uninstall, Jira disconnect, project unregister = destructive. Note the
+purge, plugin uninstall, Jira disconnect, project unregister = destructive.
+\`specrails_support(triage/core_update_status/core_update_check)\` is read;
+\`specrails_support(core_update_apply)\` is ai-spawn because it runs longer
+global update work. 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.
 
@@ -177,9 +194,9 @@ read + write — ai-spawn is required only to launch work or spawn a nested AI.
 
 - 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.
+- CLAUDE-ONLY: agent profiles, Contract Refine, SMASH, Freestyle mode (API mode
+  \`freestyle\`; say "Freestyle" to users), 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).
 
@@ -214,6 +231,20 @@ read + write — ai-spawn is required only to launch work or spawn a nested AI.
   \`install_config\` per provider → ONE \`install\` (provisions all chosen
   providers; quick-only, offline) → poll \`checkpoints\` until
   \`isInstalling === false\`.
+- **Support** (\`specrails_support\`): use FIRST for installation/usage help,
+  provider CLI/auth, MCP/Agent Chat issues, missing agents/skills/commands,
+  failed jobs, PR delivery confusion, costs, and plugin questions. It returns a
+  support playbook plus local diagnostics and never creates specs. When a job
+  says agents, skills, or slash commands are missing, explain that upstream
+  definitions live in the APP-GLOBAL specrails-core framework, not inside the
+  project. For specrails-core installation questions, project setup checkpoints
+  are NOT a health signal: pending checkpoints or 0 agents/commands do not prove
+  a core problem and must not trigger \`specrails_setup(install)\`. If global
+  core is stale, offer \`core_update_check\` + \`core_update_apply\`. If global
+  core is current but a real job still reports missing core definitions, ask for
+  the job error/diagnostic and give the manual fallback for standalone/legacy
+  core installs: from the project root, run \`npx specrails-core@latest update\`,
+  then retry the job.
 - **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

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

@@ -8,8 +8,12 @@ const mcp_tiers_1 = require("../mcp-tiers");
 // permission-tier toggles are intentionally NOT writable here — an external LLM
 // must never be able to escalate its own permissions. Those are user-only,
 // changed in the Settings ▸ MCP panel.
-const WRITABLE_THEMES = ['specrails', 'dracula', 'aurora-light', 'obsidian-dark', 'matrix'];
+const WRITABLE_THEMES = ['specrails', 'dracula', 'aurora-light', 'obsidian-dark', 'code-rain', 'galaxy'];
 const WRITABLE_LANGS = ['en', 'es', 'fr', 'de', 'pt', 'it', 'zh', 'ja'];
+const LEGACY_THEME_ID_MAP = {
+    'star-wars': 'galaxy',
+    matrix: 'code-rain',
+};
 function appTools() {
     return [
         {
@@ -44,8 +48,9 @@ function appTools() {
             handler: (ctx, args) => {
                 const db = ctx.desktopDb;
                 if (args.action === 'get') {
+                    const theme = normalizeStoredTheme(db);
                     return {
-                        theme: (0, desktop_db_1.getDesktopSetting)(db, 'ui_theme') ?? 'specrails',
+                        theme,
                         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')),
@@ -102,6 +107,17 @@ function appTools() {
         },
     ];
 }
+function normalizeStoredTheme(db) {
+    const stored = (0, desktop_db_1.getDesktopSetting)(db, 'ui_theme');
+    if (!stored)
+        return 'specrails';
+    const migrated = LEGACY_THEME_ID_MAP[stored];
+    if (migrated) {
+        (0, desktop_db_1.setDesktopSetting)(db, 'ui_theme', migrated);
+        return migrated;
+    }
+    return WRITABLE_THEMES.includes(stored) ? stored : 'specrails';
+}
 function num(v) {
     if (v === undefined)
         return null;