create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/workers/state-detectors/gemini.js

@@ -9,6 +9,25 @@ const { baseDetector, stripAnsi } = require('./base');
 
 const GEMINI_STATUS_FRAGMENT_RE = /^(?:[\s\d•◦·∙●○✦✧◆◇◐◓◑◒|/\\-]+|Thinking\.{0,3}|Working\.{0,3}|Running\.{0,3}|Responding\.{0,3}|Loading\.{0,3}|esc\s+to\s+(?:cancel|interrupt)|ctrl\+c\s+to\s+(?:quit|cancel)|press\s+enter\s+to\s+send|shift\+enter\s+for\s+newline)$/iu;
 
+// The WORKING subset of the status vocabulary. Two precise signals, both shown
+// only mid-generation: the in-flight "esc to cancel/interrupt" hint, and a
+// STANDALONE spinner/status line ("✦ Thinking…"). Anchoring the verb to a whole
+// status line keeps ordinary prose ("I'm working on the fix") from matching, and
+// the idle composer hints ("press enter to send", "ctrl+c to quit") are excluded
+// entirely — so it never mislabels an idle session as generating. server.js's
+// generating-gate uses this to suppress the idle-notify so a long, output-quiet
+// Gemini turn whose composer matches a global prompt pattern is not flagged
+// "Needs You". (Gemini has no detectWaitingInput hook, so this is its only guard.)
+const GEMINI_INTERRUPT_HINT_RE = /\besc\s+to\s+(?:cancel|interrupt)\b/i;
+const GEMINI_WORKING_STATUS_LINE_RE = /^[\s•◦·∙●○✦✧◆◇◐◓◑◒|/\\-]*(?:Thinking|Working|Running|Responding|Loading)\b\.{0,3}\s*$/i;
+function detectActivelyGenerating(text) {
+  // Split on newlines FIRST (base.stripAnsi drops them), then strip per line.
+  return String(text || '').split(/\r?\n/).slice(-12).some(line => {
+    const t = stripAnsi(line).trim();
+    return GEMINI_INTERRUPT_HINT_RE.test(t) || GEMINI_WORKING_STATUS_LINE_RE.test(t);
+  });
+}
+
 function isCursorAddressedRedraw(data) {
   const s = String(data || '');
   return (
@@ -33,4 +52,6 @@ module.exports = {
     }
     return true;
   },
+
+  detectActivelyGenerating,
 };

package/template/claude-task-manager/workers/state-detectors/index.js

@@ -11,6 +11,8 @@ const { baseDetector } = require('./base');
 const claudeCode = require('./claude-code');
 const codex = require('./codex');
 const gemini = require('./gemini');
+const opencode = require('./opencode');
+const cursor = require('./cursor');
 
 // Provider-id → detector. Adding a new provider is just an import + entry.
 const _detectors = new Map([
@@ -18,6 +20,8 @@ const _detectors = new Map([
   ['codex', codex],
   ['gemini', gemini],
   ['gemini-cli', gemini],
+  ['opencode', opencode],
+  ['cursor', cursor],
 ]);
 
 function getStateDetector(providerId) {
@@ -25,6 +29,30 @@ function getStateDetector(providerId) {
   return baseDetector;
 }
 
+// Single authoritative "is this session blocked at a LIVE approval/choice widget
+// right now?" decision, delegated to the provider's own state detector. This is
+// the one place the banner path should ask — replacing global, provider-blind
+// content regexes. Hide-unless-confident: returns live only when the detector
+// positively confirms an approval/choice widget AND no ready/finished composer is
+// on screen (a live widget REPLACES the composer). Unknown providers / detectors
+// without a detectWaitingInput hook → {live:false}.
+function isSessionAtLivePrompt(providerId, text) {
+  const detector = getStateDetector(providerId);
+  try {
+    const wi = typeof detector.detectWaitingInput === 'function' ? detector.detectWaitingInput(text) : null;
+    const reason = wi && wi.reason;
+    if (reason !== 'approval' && reason !== 'choice') return { live: false, reason: null };
+    const readyComposer = typeof detector.detectReadyComposer === 'function' && detector.detectReadyComposer(text);
+    const turnFinished = typeof detector.detectTurnFinished === 'function' && detector.detectTurnFinished(text);
+    if (readyComposer || turnFinished) return { live: false, reason: null };
+    return { live: true, reason };
+  } catch {
+    // A detector throwing must never break the caller's idle-notify path; default
+    // to not-live (hide-unless-confident).
+    return { live: false, reason: null };
+  }
+}
+
 function registerStateDetector(providerId, detector) {
   if (!providerId || !detector) return;
   _detectors.set(providerId, detector);
@@ -40,6 +68,7 @@ function listStateDetectors() {
 
 module.exports = {
   getStateDetector,
+  isSessionAtLivePrompt,
   registerStateDetector,
   listStateDetectors,
   baseDetector,

package/template/claude-task-manager/workers/state-detectors/opencode.js

@@ -0,0 +1,103 @@
+'use strict';
+// OpenCode TUI state detector.
+//
+// OpenCode redraws prompt/footer/status regions and can re-emit startup
+// diagnostics while the agent is actually sitting at its input prompt. Those
+// frames should still paint in the terminal, but they must not be treated as
+// model activity. Approval widgets and real tool output remain active.
+
+const { baseDetector } = require('./base');
+
+const OPENCODE_FOOTER_LINE_RE = /^(?:gpt|claude|codex|gemini|opencode|deepseek|kimi|moonshot|qwen|llama|mistral)[\w.+-]*(?:\s+[\w.+-]+){0,8}\s+[·-]\s+(?:~|\/|\.\.?\/)/i;
+const OPENCODE_PROMPT_LINE_RE = /^(?:>|›|❯)\s*(?:\S.*)?$/;
+const OPENCODE_BUSY_LINE_RE = /^(?:[•●◦▪·*]\s*)?(?:(?:Waiting\s+for\s+background\s+terminal\b.*)|(?:Working|Thinking|Reading|Writing|Editing|Running|Searching|Planning|Analyzing|Calling|Using|Processing|Crunching)\b.*\b(?:esc|interrupt|cancel)\b)/i;
+const OPENCODE_PASSIVE_STATUS_LINE_RE = /^(?:[•●◦▪·*]\s*)?(?:Ready|Waiting|Idle|Stopped|Done|Complete|Completed)\b/i;
+const OPENCODE_CONTROL_HINT_RE = /^(?:esc|ctrl-c|ctrl\+c|press\s+enter)\b.*(?:interrupt|cancel|confirm|send)/i;
+const OPENCODE_SKILL_WARNING_RE = /^(?:⚠\s*)?Skipped loading\s+\d+\s+skill\(s\)\s+due to invalid SKILL\.md files\./i;
+const OPENCODE_SKILL_DESCRIPTION_RE = /^\/.*\/SKILL\.md:\s+invalid description:\s+exceeds maximum length of\s+\d+\s+characters$/i;
+
+function stripAnsiPreserveLines(data) {
+  return String(data || '')
+    // Cursor-addressed redraws otherwise collapse multiple rows together after
+    // stripping CSI. Preserve row boundaries before removing control codes.
+    .replace(/\x1b\[[0-9]+;[0-9]+[Hf]/g, '\n')
+    .replace(/\x1b\[[0-9]+[ABCD]/g, '\n')
+    .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+    .replace(/\r/g, '\n')
+    .replace(/[\x00-\x09\x0b\x0c\x0e-\x1f\x7f]/g, '');
+}
+
+function printableLines(data) {
+  return stripAnsiPreserveLines(data)
+    .replace(/\u00a0/g, ' ')
+    .split(/\n+/)
+    .map(line => line.trim())
+    .filter(Boolean);
+}
+
+function isOpenCodePassiveLine(line) {
+  const text = String(line || '').trim();
+  if (!text) return true;
+  return OPENCODE_FOOTER_LINE_RE.test(text) ||
+    OPENCODE_PROMPT_LINE_RE.test(text) ||
+    OPENCODE_PASSIVE_STATUS_LINE_RE.test(text) ||
+    OPENCODE_CONTROL_HINT_RE.test(text) ||
+    OPENCODE_SKILL_WARNING_RE.test(text) ||
+    OPENCODE_SKILL_DESCRIPTION_RE.test(text);
+}
+
+function isOpenCodeBusyLine(line) {
+  return OPENCODE_BUSY_LINE_RE.test(String(line || '').trim());
+}
+
+// The agent is mid-turn when its busy/spinner line ("Working… esc to cancel") is on
+// screen. server.js's generating-gate uses this to suppress the idle-notify so a
+// long, output-quiet OpenCode turn whose composer matches a global prompt pattern is
+// not mislabeled "Needs You". Tail-scoped; same busy signal detectWaitingInput gates.
+function detectActivelyGenerating(text) {
+  return printableLines(text).slice(-12).some(isOpenCodeBusyLine);
+}
+
+function detectWaitingInput(text) {
+  const lines = printableLines(text).slice(-10);
+  if (!lines.length) return null;
+  if (lines.some(isOpenCodeBusyLine)) return null;
+  if (!lines.some(line => OPENCODE_PROMPT_LINE_RE.test(line))) return null;
+  return { reason: 'input' };
+}
+
+module.exports = {
+  ...baseDetector,
+  id: 'opencode',
+  // OpenCode progress can be sparse, but prompt/footer redraws are filtered
+  // below. Keep a provider hold only for meaningful activity frames.
+  idleDebounceMs: 10000,
+
+  isActiveChunk(data) {
+    if (!baseDetector.isActiveChunk(data)) return false;
+    const lines = printableLines(data);
+    if (lines.length && lines.every(line => isOpenCodePassiveLine(line) && !isOpenCodeBusyLine(line))) {
+      return false;
+    }
+    return true;
+  },
+
+  isStatusOnlyChunk(data) {
+    const lines = printableLines(data);
+    return !!(lines.length && lines.every(line => isOpenCodePassiveLine(line) || isOpenCodeBusyLine(line)));
+  },
+
+  isBusyStatusChunk(data) {
+    const lines = printableLines(data);
+    return lines.some(isOpenCodeBusyLine);
+  },
+
+  detectWaitingInput,
+  detectActivelyGenerating,
+  _test: {
+    printableLines,
+    isOpenCodePassiveLine,
+    isOpenCodeBusyLine,
+  },
+};

package/template/docs/design/markdown-review-pane.md

@@ -0,0 +1,206 @@
+# Markdown Review Pane — Design System
+
+**Status:** Implemented · 2026-05-21
+**Scope:** `#review&type=doc` workspace inside the Code Review panel
+**Files:** `claude-task-manager/public/css/reviews.css`, `claude-task-manager/public/js/reviews.js`
+
+This doc captures the design rationale behind the May 2026 markdown-review
+redesign so future work doesn't reintroduce the patterns we deliberately
+removed.
+
+---
+
+## Problem we solved
+
+The original markdown review pane was a code-editor surface re-skinned for
+prose:
+
+- Line-number gutter always visible in the rendered/docs view
+- Single 24/19/16px heading scale, no clear hierarchy between H1 and H4
+- Inline code rendered in **amber** (`#e0af68` Tokyo Night yellow), making
+  every identifier read as a warning
+- TOC sidebar prefixed every entry with a literal `#` glyph; hierarchy
+  conveyed by glyph repetition (`#`, `##`, `###`) instead of indentation
+- Hardcoded RGBA tints from the dark palette (`rgba(122,162,247,0.06)`)
+  showed barely-visible on the light theme bg
+- Workspace bg matched the page bg, so code blocks didn't read as
+  contained content
+- Article max-width of 920px exceeded the 80-character readability sweet
+  spot
+
+The result felt like a `cat foo.md` dump with extra chrome, not a designed
+reading surface.
+
+---
+
+## Design tokens (theme-aware)
+
+The whole redesign uses CSS custom properties from the existing CTM
+palette. Both light and dark are defined in `public/index.html`:
+
+| Token | Dark | Light | Role in the markdown pane |
+|---|---|---|---|
+| `--bg` | `#1a1b26` | `#f6f7f9` | Workspace surface |
+| `--bg-light` | `#24283b` | `#ffffff` | Code-block & elevated card bg |
+| `--bg-lighter` | `#1f2333` | `#eceef2` | Recessed (gutters, table th) |
+| `--fg` | `#c0caf5` | `#0f172a` | Body text, primary headings |
+| `--fg-dim` | `#a9b1d6` | `#3d4b5e` | H4, secondary metadata |
+| `--fg-muted` | `#7f88a8` | `#52606f` | H5/H6 (kicker), line-gutter |
+| `--accent` | `#7aa2f7` | `#3b66e0` | Links, active TOC rail, focus |
+| `--accent-soft` | `rgba(122,162,247,0.13)` | `rgba(59,102,224,0.10)` | Inline code bg, segmented active fill, hovered block bg |
+| `--border` | `#414868` | `rgba(15,23,42,0.10)` | H2 hairline, hr, card outline |
+
+No hardcoded hex in the new CSS. Every color flows from the token system,
+so the next theme palette retune Just Works.
+
+---
+
+## Five-level type scale
+
+| Level | Size | Weight | Treatment |
+|---|---|---|---|
+| H1 | 28px | 700 | `letter-spacing: -0.01em`, 16px bottom margin |
+| H2 | 22px | 650 | 28px top margin, 1px bottom hairline (`--border`) |
+| H3 | 17px | 600 | 22px top margin |
+| H4 | 15px | 600 | Muted color (`--fg-dim`) — sub-section label |
+| H5/H6 | 12px | 700 | Uppercase, 0.08em tracking — used as "eyebrow" |
+
+Body text: **15px / line-height 1.7 / `--fg`**. The 1.7 line-height puts
+prose squarely in the GitHub-docs / Stripe-docs comfort band; the dense
+1.62 we had before read as compressed.
+
+`scroll-margin-top: 16px` on every heading so deep-link anchors don't
+collide with sticky chrome.
+
+---
+
+## Layout
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│ CTM topbar                                                    │
+├─────────────┬─────────────────────────────────────────────────┤
+│  TOC rail   │      .cr-doc-article (max-width 800px)         │
+│             │  ┌─────────────────────────────────────────┐    │
+│  • Heading  │  │ # Document Title                        │    │
+│   Heading   │  │ ─────────                               │    │
+│    Heading  │  │ ## Section H2 ─────────────────────────│    │
+│             │  │                                         │    │
+│  ─ active   │  │ Body paragraph rendered at 15/1.7…      │    │
+│             │  │                                         │    │
+│             │  │ `inline code` reads as body, faintly    │    │
+│             │  │ tinted accent-soft.                     │    │
+│             │  │                                         │    │
+│             │  │ ```                                     │    │
+│             │  │ block code on --bg-light w/ border      │    │
+│             │  │ ```                                     │    │
+│             │  └─────────────────────────────────────────┘    │
+└─────────────┴─────────────────────────────────────────────────┘
+```
+
+- **Article width capped at 800px.** Past ~75 characters per line,
+  readability drops sharply (Bringhurst, *The Elements of Typographic
+  Style*). 800px at 15px font sits at ~75ch.
+- **Top padding 24px, side padding 32px, bottom padding 96px.** Bottom
+  pad lets the user scroll the last section into a comfortable reading
+  position rather than glued to the viewport bottom.
+
+---
+
+## What we hide vs reveal
+
+| Element | Default state | Hover/active state |
+|---|---|---|
+| `.cr-doc-block-lines` (line-range gutter) | Opacity 0, positioned `left: -44px` | Opacity 0.55 on block hover; full opacity in source/split pane |
+| `.cr-doc-comment-btn` (the `+` button) | Opacity 0 | Opacity 1 on block hover, active, or focus-visible |
+| Source-pane line numbers | Visible by default | Same |
+
+Rationale: line numbers and the `+` glyph belong with **source-code
+review**. In **rendered mode** they're affordances you reach for, not
+content. Hiding them by default keeps the surface looking like a doc;
+hover/focus brings them back when you need to anchor a review comment.
+
+---
+
+## TOC sidebar
+
+- **No `#` glyph.** Markdown syntax in a parsed UI looked like a bug.
+- **Depth via padding-left.** H1 = 8px, H2 = 14px, H3 = 28px, H4 = 42px,
+  H5/H6 = 56px. Combined with shrinking font size (12 → 11.5 → 11) and
+  color stepping (`--fg` → `--fg-dim` → `--fg-muted`) the hierarchy
+  reads at a glance.
+- **Active state.** Subtle `--accent-soft` fill + `box-shadow: inset 2px
+  0 0 var(--accent)` rail on the left edge. Reads as "you are here"
+  without dominating.
+
+---
+
+## Scroll-spy
+
+`setupDocScrollSpy()` in `reviews.js` uses an `IntersectionObserver`
+scoped to `.cr-diff-area`. Each `.cr-doc-block` is observed; the topmost
+intersecting block (by `boundingClientRect.top`, smallest = closest to
+top of viewport) becomes the "active" reader position. Its nearest
+preceding heading block is then resolved (`headingFor` map) and that
+heading's TOC entry gets the `.active` class.
+
+```
+rootMargin: '-12px 0px -70% 0px'
+```
+
+That means a heading is "active" only while it's in the top **30%** of
+the visible pane — same band Stripe Docs and Notion use. Anything below
+that doesn't fight for the active marker.
+
+The observer is rebuilt every render (the DOM is reset). Old observer
+is `disconnect()`-ed first so we don't leak listeners.
+
+---
+
+## Non-goals
+
+- **No syntax highlighting on `<pre><code>` blocks.** The existing
+  markdown renderer doesn't ship highlight.js; adding it is a larger
+  scope. Block code is monospaced on `--bg-light` with a border and the
+  user reads it as code through layout cues, not color.
+- **No print stylesheet.** Out of scope.
+- **No front-matter parsing.** YAML-style front matter (if any) renders
+  as ordinary markdown. Adding a `<div class="front-matter">` wrapper
+  needs a renderer change; deferred.
+- **No collapsible H2 sections.** Considered, rejected — collapsing
+  hides content the reader explicitly opened a doc to see.
+
+---
+
+## Verification
+
+Validated on an isolated dev instance (`/ctm-dev`, random port 4464),
+loading a real markdown spec
+(`wall-e/docs/superpowers/specs/2026-04-15-mempalace-gap-analysis-v2.md`,
+22 headings, 64 blocks):
+
+**Dark mode, light mode**, both verified via `getComputedStyle`:
+
+| Check | Result |
+|---|---|
+| TOC `#` glyph removed | `iconText: ""`, `display: none` |
+| TOC indentation by level | 8px → 14px → 28px |
+| Article width | 800px |
+| Workspace bg | `--bg` resolves correctly per theme |
+| H1 | 28px / 700 |
+| H2 | 22px + 1px `--border` bottom |
+| Line-gutter (rendered) | opacity 0, off-screen |
+| Comment `+` (default) | opacity 0 (revealed on hover/active/focus) |
+| Inline code | accent-soft bg + `--fg` text (no amber) |
+| Segmented "active" | accent-soft fill (not solid accent) |
+
+---
+
+## Related
+
+- [CTM light-mode contrast redesign](https://github.com/Student ExampleLi/tools/commit/0ce352b)
+  — established the `--fg-dim` / `--fg-muted` / `--accent-soft` tokens
+  this work depends on.
+- [xterm.js minimumContrastRatio](https://github.com/Student ExampleLi/tools/commit/28576de)
+  — same "don't fight the theme palette, fix the contrast at the edge"
+  principle applied to terminals.

package/template/docs/designs/2026-05-17-portkey-gateway-provider-ux.md

@@ -1,7 +1,8 @@
 # Portkey Gateway Provider UX
 
 Date: 2026-05-17
-Status: implemented
+Updated: 2026-05-20
+Status: revised and implemented
 
 ## Context
 
@@ -14,16 +15,49 @@ Wall-E already has two separate ideas that should not be collapsed:
 
 Portkey belongs on a third axis: **connection / transport**. A provider instance can be "OpenAI via Portkey" or "Anthropic via Portkey" while still using the OpenAI or Anthropic runtime adapter.
 
-## UX Model
+## Research Notes
+
+Portkey's current public docs support the implementation shape:
+
+- The OpenAI-compatible setup is still "change base URL to `https://api.portkey.ai/v1` and use a Portkey API key".
+- The universal API supports OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages against the gateway, so Portkey should be modeled as transport rather than as a standalone upstream provider.
+- The model listing endpoint is `GET /v1/models`, requires `x-portkey-api-key`, and can filter by `provider`/`ai_service`. Its response includes provider-qualified ids such as `@ai-provider-slug/gpt-5`, which CTM must preserve instead of filtering through the built-in catalog.
+- Portkey Models is also a public model/pricing catalog. Provider pricing JSON is available at `https://configs.portkey.ai/pricing/{provider}.json`, individual model pricing is available at `https://api.portkey.ai/model-configs/pricing/{provider}/{model}`, and the open catalog repository publishes the current provider list. This is provider-agnostic and must not be limited to provider families CTM already has direct keys for.
+
+## Revised UX Model
 
 The `#models` page should use this vocabulary:
 
-- **Provider**: upstream API/runtime family. Examples: OpenAI, Anthropic, Google Gemini.
+- **Provider**: upstream API/runtime family. Examples: OpenAI, Anthropic, Google Gemini. Provider cards are the primary overview because CTM has few provider families.
 - **Connection**: how requests reach the provider. Examples: Direct API key, Portkey gateway, Claude CLI subscription, Codex CLI subscription, OAuth proxy.
 - **Route**: a concrete model plus provider instance. Examples: `gpt-5.5 · OpenAI · Direct`, `gpt-5.5 · OpenAI · Portkey prod`.
+- **Gateway**: shared transport/account configuration that can be enabled per provider family. Portkey is the first gateway.
+- **Portkey Catalog Provider**: a provider family from Portkey's public model catalog, even when CTM has no direct adapter/key for that provider.
+- **Model Catalog**: the long model inventory underneath provider cards. It is collapsed by default because the provider view is the decision surface.
 
 This keeps the user from seeing Portkey as a competing "model provider" next to OpenAI and Anthropic. It also explains why a Claude model can be reachable through Portkey while Claude CLI remains a separate subscription-backed route.
 
+## 2026-05-20 Product Decision
+
+Portkey is enabled and disabled at the **provider** level, not the individual model level.
+
+The provider card owns the access policy:
+
+- `Auto`: prefer direct provider API when configured, otherwise use Portkey if the provider is gateway-only.
+- `Prefer Direct`: use direct provider API when available; fall back to Portkey only when direct access is absent.
+- `Prefer Portkey`: use the Portkey connection for that provider when available; fall back to direct only when no Portkey route exists.
+
+The Gateway section owns account-level operations:
+
+- connect/edit the Portkey gateway credential
+- sync the Portkey model catalog
+- apply Portkey to all providers verified by model sync
+- apply Portkey to all providers imported from Portkey's catalog
+- disable Portkey as the default by returning provider policies to `Auto`
+- remove all Portkey gateway connections
+
+The Model Catalog remains an inspection surface. It shows imported/discovered models, capabilities, pricing, source, and verification status, but the default access decision belongs on provider cards.
+
 ## `#models` Page Behavior
 
 ### Provider Cards
@@ -42,6 +76,8 @@ Provider cards remain grouped by upstream provider:
 - Google Gemini
   - Direct API key
   - Portkey gateway when supported by the configured route
+- Fireworks AI, Together AI, Mistral AI, and other Portkey-only providers
+  - Portkey gateway only unless CTM later adds a native direct adapter
 
 Each saved provider instance should display a compact connection chip:
 
@@ -53,14 +89,60 @@ Each saved provider instance should display a compact connection chip:
 
 The chip is metadata, not the provider type.
 
-### Add Provider Dialog
+Each cloud provider card also exposes an **Access Route** control:
+
+- `Use Portkey` when a Portkey route exists for that provider.
+- `Prefer Direct` for direct-first routing.
+- `Auto` for direct-first with gateway fallback.
+- `Enable Portkey` when the provider has no Portkey route yet.
+
+For a provider that exists only through Portkey's catalog, the card must not show a direct route control. It should render as Portkey-only. Unknown Portkey catalog provider families use the OpenAI-compatible runtime against the Portkey gateway and provider-qualified model ids such as `@fireworks-ai/mixtral-8x7b`.
+
+This gives users a discoverable per-provider control without forcing route choices across hundreds of model rows.
+
+### Gateway Section
+
+The Models page includes a first-class **Gateways** section above provider cards.
+
+The Portkey gateway card displays:
+
+- imported Portkey provider count
+- imported model count
+- last successful sync or last sync error
+- `Connect Portkey` / `Edit Gateway`
+- `Sync now`
+- `Apply to Portkey providers`
+- `Disable as default`
+- `Remove`
+
+Portkey model discovery runs hourly in the Wall-E daemon, runs on startup after the daemon is listening, and can be triggered manually from `Sync now`. Sync has two data sources:
+
+- The connected gateway `/models` response. This proves what the configured gateway route returns for the user's credential/header set.
+- The public Portkey Models catalog. This is used to import provider families and model/pricing rows that CTM does not know directly, such as Fireworks AI.
+
+Sync must not restrict Portkey provider imports to CTM's built-in provider list. It should fetch Portkey's current public catalog provider list, fall back to the documented provider list when the catalog index is unavailable, and import raw/provider-qualified Portkey model ids, including providers and model ids not present in CTM's built-in supported-model catalog.
+
+Corporate/devbox Portkey configurations can point at a company gateway host instead of public `api.portkey.ai`. CTM should preserve the gateway URL from local configuration/logs and should not assume that a valid Portkey header set works against the public Portkey host. CTM must not hardcode any company's gateway URL as a fallback.
 
-The dialog should ask for upstream first, then connection:
+### Add Provider And Gateway Dialogs
+
+The normal Add Provider dialog asks for upstream first, then connection:
 
 1. Provider: OpenAI, Anthropic, Google, DeepSeek, Ollama.
 2. Connection: Direct API key or Portkey gateway.
 3. For Direct: show the provider API key and optional base URL.
-4. For Portkey: show Portkey API key, optional virtual key, optional config id, optional provider slug, and default gateway URL.
+
+The Gateway section uses a different Portkey-specific dialog. It must not ask users to choose an upstream provider or provider slug. Portkey is connected once with:
+
+- Portkey API key
+- Gateway URL, defaulting to `https://api.portkey.ai/v1` for manual Portkey accounts, or the detected devbox/corporate gateway URL when CTM can read a local devbox Claude configuration
+- optional config id
+- optional virtual key
+- optional local label for the Portkey account/config
+
+After saving this single gateway config, CTM stores one gateway credential row. The next Portkey sync creates internal runtime routes for providers discovered from the configured gateway and from Portkey's public model catalog. Provider cards then control whether each discovered provider uses direct API access, Portkey, or automatic fallback. Providers with no direct CTM connection render as Portkey-only.
+
+If CTM detects a devbox Claude Portkey header file, the UI may offer a one-click "Use" action. That action stays server-side: the browser receives only masked metadata and booleans such as whether a virtual key exists; raw custom headers and API keys must never be returned by `/api/models/providers` or `/api/models/detect-keys`.
 
 Default labels should make the route obvious:
 
@@ -70,8 +152,14 @@ Default labels should make the route obvious:
 
 Advanced custom headers can still exist, but common Portkey fields should not require users to write JSON.
 
+### Model Provider Section
+
+The Model Providers section is collapsed by default. The page still shows the Gateways section first because gateway setup is the shared routing control. Searching provider cards expands the Model Providers section so matches are visible.
+
 ### Model List
 
+The Model Catalog section is collapsed by default. Searching models expands the catalog so search results remain visible.
+
 The model list should show duplicate model ids as separate routes only when necessary:
 
 - If a model exists once, show `GPT-5.5` with a subtle `OpenAI · Direct` chip.
@@ -81,13 +169,31 @@ The model list should show duplicate model ids as separate routes only when nece
 
 The saved value should prefer `model_registry.id`, not only the bare model id.
 
+Gateway-discovered model rows use:
+
+- `source = portkey`
+- `gateway_type = portkey`
+- `verification_status = verified` only when CTM's built-in catalog recognizes the model id; otherwise `unverified`
+- `last_seen_at` from the latest Portkey sync
+
+Public Portkey catalog model rows use:
+
+- `source = portkey_catalog`
+- `gateway_type = portkey`
+- `verification_status = catalog`
+- provider-qualified model ids such as `@fireworks-ai/mixtral-8x7b`
+- pricing converted from Portkey's cents-per-token values into CTM's dollars-per-1M-token fields
+
+Catalog pruning must not delete gateway-discovered or Portkey-catalog rows just because CTM's built-in catalog does not know the id yet.
+
 ## Conflict Rules
 
 1. Exact `model_registry.id` wins.
-2. Provider-instance defaults win over provider-type defaults.
-3. If a bare model id maps to exactly one enabled route, it is safe to resolve.
-4. If a bare model id maps to multiple enabled routes, use the explicit default route if one exists; otherwise return an ambiguity error that names the available routes.
-5. Never select the newest provider row as a silent tie-breaker when direct and Portkey routes share the same model id.
+2. Explicit task/model defaults win over provider route policy.
+3. Provider route policy resolves duplicate direct and Portkey rows for the same provider family.
+4. If a bare model id maps to exactly one enabled route, it is safe to resolve.
+5. If a bare model id maps to multiple enabled routes and provider route policy cannot disambiguate, return an ambiguity error that names the available routes.
+6. Never select the newest provider row as a silent tie-breaker when direct and Portkey routes share the same model id.
 
 ## Implementation Phases
 
@@ -99,6 +205,8 @@ Document the UX and routing model, including the `#models` page behavior and dup
 
 - Add OpenAI custom-header support so OpenAI-through-Portkey can send Portkey headers.
 - Add shared Portkey metadata helpers for naming, default base URLs, and route labels.
+- Add public Portkey Models catalog sync independent of CTM's existing provider list.
+- Allow unknown Portkey-only provider families to use the OpenAI-compatible runtime against the Portkey gateway.
 - Extend provider detection so `PORTKEY_API_KEY` is treated as a gateway credential, not as Anthropic-only auto-detection.
 - Add tests for OpenAI Portkey headers and duplicate route resolution.
 
@@ -117,38 +225,21 @@ Document the UX and routing model, including the `#models` page behavior and dup
 
 ## Verification Results
 
-Phase 4 used an isolated CTM instance instead of the existing primary server on port 3456:
-
-- CTM: `https://localhost:3466/?token=...#models`
-- Wall-E: `127.0.0.1:3467`
-- Data dir: `/tmp/ctm-portkey-test`
-- Mock Portkey gateway: `http://127.0.0.1:4577/v1`
-
-The seeded real-life scenario used two OpenAI connections with the same model id:
-
-- `openai-default:gpt-4o-mini` as direct OpenAI.
-- `openai-portkey-prod:gpt-4o-mini` as OpenAI via Portkey.
-
-The CTM `test-connection` route sent a live `GET /v1/models` request through Wall-E's OpenAI adapter to the mock gateway. The mock observed:
-
-- `Authorization: Bearer unit-portkey-key`
-- `x-portkey-config: cfg-prod`
-- `x-portkey-provider: openai`
-
-The browser verification captured desktop and mobile screenshots in `/tmp/portkey-models-desktop.png` and `/tmp/portkey-models-mobile.png`. It checked:
-
-- Duplicate direct and Portkey OpenAI routes render as separate connections.
-- Portkey route details show `config cfg-prod`.
-- Header `+ Add Provider` keeps the Provider selector visible.
-- Portkey mode exposes gateway fields and labels the key as `Portkey API Key`.
-- Anthropic defaults to `https://api.portkey.ai`; OpenAI defaults to `https://api.portkey.ai/v1`.
-- The Portkey provider-slug placeholder follows the selected provider.
-- The Portkey dialog itself fits a 390px mobile viewport.
+The implemented provider-level gateway path is covered by:
 
-The mobile pass also observed an existing `#models` page horizontal overflow before the dialog opens, caused by the top bar and tier matrix. That is separate from the Portkey dialog and should be handled as a follow-up page-wide mobile layout pass.
+- Portkey sync tests that import unknown gateway model ids, import Portkey-only catalog provider families such as Fireworks AI, mark CTM-known ids as `verified`, mark unknown gateway ids as `unverified`, and prove catalog pruning preserves gateway/catalog rows.
+- Provider route-policy tests that prefer Portkey or direct connections per provider and fall back when the requested route is unavailable.
+- Chat routing tests that resolve duplicate direct/Portkey bare model ids using the provider policy instead of raising avoidable ambiguity.
+- Model admin HTTP tests for gateway summaries and provider route policy updates.
+- Static UI tests for the providerless Portkey Gateway dialog, provider Access Route controls, collapsed-by-default Model Providers, and collapsed-by-default Model Catalog.
+- Playwright render tests for the Models page gateway card, provider route buttons, Portkey-only provider cards, collapsed provider/catalog expansion, and provider policy POST behavior.
+- Full CTM regression tests.
 
 ## References
 
 - https://portkey.ai/docs/integrations/libraries/openai-compatible
+- https://portkey.ai/docs/api-reference/inference-api/models/models
+- https://portkey.ai/docs/product/ai-gateway/universal-api
+- https://portkey.ai/docs/product/model-catalog/portkey-models
 - https://portkey.ai/docs/integrations/libraries/claude-code
 - https://portkey.ai/docs/integrations/libraries/codex