@plannotator/ui 0.46.1 → 0.47.0

package/HANDOFF.md

@@ -192,7 +192,7 @@ We deliberately did **not** restructure the exports map in this PR (move-don't-r
 | `components/BlockRenderer` + the block components it renders (`TableBlock`, `HtmlBlock`, `Callout`, `MermaidBlock`, `MathBlock`, …) | Pure rendering. |
 | `components/InlineMarkdown` | Code-file hover previews route through the `docPreviewFetcher` seam. Wiki-link rendering takes the sync `resolveLinkedDoc` prop (live labels + deleted-doc treatment; see "Wiki-link seams (0.27.0)"). |
 | `components/Viewer` | The full annotatable document. Required props: `markdown` and `taterMode` (pass `false`). **Pass `disableCodePathValidation` unless you implement `/api/doc/exists`** — code-path validation is a prop-level opt-out, not a `configure` seam. `annotationHeader={{ onInputMethodChange, onModeChange, hideQuickLabel? }}` opts into one Viewer-owned, in-flow header containing the compact annotation controls and existing document actions. It reserves its measured responsive height, preserves all document badges, and follows `stickyActions` as one unit; omit it for the legacy action bar. Compact mode contains no help link. `hideQuickLabel` still requires the host to clamp restored mode state away from `'quickLabel'`. A host-owned scroll element must be supplied through `ScrollViewportProvider` (`hooks/useScrollViewport`) so stuck chrome and anchor clearance use the real scroller. |
-| `components/MarkdownEditor` | Theme-bridging wrapper over `@plannotator/markdown-editor`. Takes CM6 extensions via the `extensions` prop (captured ONCE per `documentId` — see "Wiki-link seams (0.27.0)") and re-exports `wikiLinks`, `embedPicker`, `embedSlashItem`, `planEmbedInsert`, and their public types. |
+| `components/MarkdownEditor` | Theme-bridging wrapper over `@plannotator/markdown-editor`. Takes CM6 extensions via the `extensions` prop (captured ONCE per `documentId` — see "Wiki-link seams (0.27.0)") and re-exports `wikiLinks`, `linkWidgets`, `refreshLinkWidgets` (0.47.0), `embedPicker`, `embedSlashItem`, `planEmbedInsert`, and their public types. |
 | `components/MarkdownDiff` | Theme-bridging wrapper over `@plannotator/markdown-editor`'s frozen two-revision diff. Same shim pattern as `components/MarkdownEditor` (ThemeProvider bridge, `extensions` passthrough, grid card chrome); never editable. See "Frozen markdown diff (0.28.0)". |
 | `components/CommentPopover` | Anchor capture + comment entry. Ask-AI UI renders only if you pass `onAskAI`. |
 | `components/AnnotationPanel` | Renders from your annotation state; no fetches of its own. |
@@ -1511,11 +1511,11 @@ Behaviour changes a host may notice:
 - `useAgentSettings(catalogs?)` takes the catalogs and returns EFFECTIVE (resolved) model/effort values; called without catalogs it returns the saved values unchanged, as before.
 - `AIProviderModel` is now an alias of `CatalogModel` (adds optional `resolvedId`, `fastMode`); `resolveAIModelForProvider` uses the shared resolver, so a stale pinned id keeps its model family instead of snapping to the provider default.
 
-## Forge-aware `#123` / `@user` links (unreleased, additive; #1596)
+## Forge-aware `#123` / `@user` links (additive; #1596; published in core 0.25.6 / ui 0.46.x)
 
 Bare `#123` and `@user` in a document used to link to github.com whenever `githubRepo` held a slash, so GitLab and GitHub Enterprise repos got links to the wrong forge. `InlineMarkdown` (and every block component that forwards `githubRepo`: `BlockRenderer`, `RenderedMarkdown`, `TableBlock`, `TablePopout`, `AlertBlock`, `Callout`, `proseBody`) gains an optional `repoHost?: string` beside it; `Viewer` passes `repoInfo.host`. The rule is the new `@plannotator/core/forge-refs` subpath (`forgeRefLinks`, `classifyForgeHost`, `normalizeForgeHost`). The host is normalized first: lowercased, port dropped, `www.github.com` / `ssh.github.com` / SSH aliases starting `github.com-` folded to `github.com` and `altssh.gitlab.com` to `gitlab.com`; a host that is not a plausible DNS name (no dot, brackets, `@`, a dotless SSH alias) counts as absent. Then a github host (`github.com`, `github.*`) links to `https://<host>/<path>/issues/N`, a gitlab host (`gitlab.com`, `gitlab.*`, `*.gitlab.*`) to `https://<host>/<path>/-/issues/N`, users to `https://<host>/<user>`, and any other host renders the ref as an unlinked span. **A host that passes no `repoHost` (or an implausible one) keeps the old github.com links**, so nothing changes until it opts in. Because ui imports a new core subpath and `@plannotator/ui` pins `@plannotator/core` EXACTLY (currently `"0.25.6"`), the core version bump and ui's pin must move together in the same release: bump core, set ui's `@plannotator/core` dependency to that same version, `bun install`, then publish `core` first and `ui` second. A ui built against this code on the old core pin would import a `forge-refs` subpath the pinned core does not ship.
 
-## Guided Review generation in core (core 0.25.6, unreleased, additive)
+## Guided Review generation in core (core 0.25.6, published, additive)
 
 Core-only; `@plannotator/ui` imports none of it, so ui's exact `0.25.6` pin is unchanged. The pure half of Guided Review generation moved verbatim from the private `@plannotator/server` (`packages/server/guide/guide-review.ts`, which re-exports every name) so a host such as Workspaces generates guides with Plannotator's exact prompt and holds the output to the same coverage rule. All three subpaths are browser-safe and zero-dependency:
 
@@ -1525,8 +1525,40 @@ Core-only; `@plannotator/ui` imports none of it, so ui's exact `0.25.6` pin is u
 
 The guide chain's engine plumbing (Claude/Codex/marker commands, output parsing, `composeGuideMethodology`, sessions) stays in the server. It ships in core 0.25.6 alongside what that unpublished version already carries; ui needs no change for it.
 
+## Host link widgets (0.47.0, core 0.25.7)
+
+Additive. `components/MarkdownEditor` re-exports the engine's new link seam beside `wikiLinks`: `linkWidgets(...specs: LinkWidgetSpec[]): Extension`, `refreshLinkWidgets: StateEffectType<null>`, and the types `LinkWidgetSpec` (`{ match(link: LinkWidgetLink): WidgetType | null }`) and `LinkWidgetLink` (`{ url; text; title?; from; to }`). They are the engine's own objects (identity pinned by `MarkdownEditor.linkWidgets.test.tsx`); hosts import them from `@plannotator/ui/components/MarkdownEditor`, never from `@plannotator/atomic-editor`.
+
+- **What it does.** For a single-line `[text](url)` link the inline preview would draw with its syntax hidden, the engine asks each registered spec in order; the first non-null widget replaces the whole link range (no link mark, no hidden `[` / `](url)` replaces, no open-in-new-tab icon beside it). `null` keeps the engine's link. Revealed links, multi-line links, reference / autolinks / wiki links, links inside tables and links wrapping an image are never offered. A spec that throws is logged once and skipped.
+- **The reveal rule stays the engine's.** Caret inside, overlapping selection, focus, the pointer-press freeze and `MarkdownDiff` changed ranges decide when the raw bytes show, exactly as for a normal link, so a widget comes and goes when the hidden syntax would. The source text is never changed.
+- **`match` runs on every rebuild** (selection, focus, document change): synchronous, no side effects, and implement `eq` on the widget so an unchanged widget keeps its DOM. Do not `preventDefault` on `mousedown` in the widget: it blocks a drag selection that starts on it.
+- **Refreshing.** When a spec's answer changes without a document edit (a record arrives after mount), dispatch `view.dispatch({ effects: refreshLinkWidgets.of(null) })`. It changes no text, adds no history entry and sends nothing through collab bindings; during a held pointer press the rebuild waits for the release.
+- **Composition.** `linkWidgets(spec)` goes in the same stable `extensions` array as `wikiLinks`, captured once per `documentId`. Several `linkWidgets(...)` extensions concatenate in extension order.
+
+**Dependency note:** 0.47.0 requires `@plannotator/atomic-editor ^0.9.0` (adds the seam) and `@plannotator/markdown-editor ^0.5.0` (widens its engine peer to `^0.8.0 || ^0.9.0`). A host that pins either exactly (e.g. through package-manager overrides) must move both pins with the ui bump. Plannotator's own apps pass no `linkWidgets`, so their editor is unchanged.
+
+Also new in 0.47.0 (all additive, all no-op for a host that passes nothing):
+
+- **`useCodeAnnotationDraft` `persistViewedFiles?: boolean`** (default `true`, #1632). `false` leaves viewed-file state out of the draft: autosave omits `viewedFiles` / `autoViewSuppressed`, an empty-annotations session with only viewed files counts as empty, the restore banner ignores viewed counts, and `restoreDraft()` returns empty viewed lists. For hosts that persist review progress on their own (Plannotator's review app now does, server-side).
+- **Model source hint** (#1616). New module `components/ModelSourceHint` (`ModelSourceHint`, `modelSourceHint`, `modelSourceToolForProvider`, types `ModelSourceTool` / `ModelSourceInfo`): a muted line under a Claude/Codex model picker ("From your installed Codex 0.155.1", or the built-in-list variant). `ModelCatalog` (`hooks/useModelCatalogs`) and `AIProviderConfig` (`utils/aiProvider`) gain optional `modelsSource` and `toolVersion`, read from `/api/ai/capabilities`; the hint renders only when the server sends `toolVersion`, so a host whose backend omits it sees no change. `AgentsTab`, `AISettingsTab` and `AIProviderBar` render it.
+- **Guided Review Codex default** (#1616): `PREFERRED_GUIDE_CODEX_MODEL` (`'gpt-6-luna'`) from `hooks/useAgentSettings`; an unset guide Codex pick resolves to it when the catalog offers it, else to Codex's own default. Never written to the cookie.
+- **Agent job warnings** (#1627): `AgentsTab` shows `AgentJobInfo.warning` under a job row when present.
+- **Request changes on PR reviews** (#1611): `buildDecisionSpec`'s platform input takes optional `requestChangesSupported`. Absent keeps the previous copy; `false` says request-changes posts as a comment; `true` with `selfAuthored` mutes Request changes and adds a live `Comment…` row.
+
+### `@plannotator/core` 0.25.7
+
+Required by ui 0.47.0 (`components/ModelSourceHint` and `hooks/useModelCatalogs` import the new `ModelsSource` type). Changes since the published 0.25.6, all additive:
+
+- `@plannotator/core/model-catalog`: new `ModelsSource` type (`'fallback' | 'discovered'`) and `cliVersionFrom(text, toolLine?)` (reads a CLI's version out of `claude --version` or the codex app-server `userAgent`). `CODEX_FALLBACK_MODELS` refreshed to what codex 0.155.1 reports (GPT-6 Sol / Astra / Luna, GPT-5.6 Sol / Terra / Luna, GPT-5.5; efforts up to `max` / `ultra`). `claudeCatalogFromSdk` names a model from `displayName` when the SDK `description` is only a tagline (no ` · `), which Claude Code 2.1.282+ emits (#1615).
+- `@plannotator/core/agent-jobs`: optional `AgentJobInfo.warning` (#1627).
+- `@plannotator/core/agents`: the `mistral-vibe` origin in `AGENT_CONFIG` (#1480, merged just after 0.25.6 was published).
+- `@plannotator/core/review-prompt`: workspace review context lines now tell the model the inline diff is the complete combined changeset and to read files by folder-prefixed path, instead of suggesting `git -C` (#1629). Prompt text only.
+
+Minor rather than patch because of the new exports (`cliVersionFrom`, `ModelsSource`).
+
 ## Publishing & versioning
 
+- **core 0.25.7 / ui 0.47.0 (host link widgets + model source hint + `persistViewedFiles`): both packages change, and both need unpublished upstream packages first.** Order: `@plannotator/atomic-editor` 0.9.0, then `@plannotator/markdown-editor` 0.5.0, then `bun install` here to refresh `bun.lock`, then publish `core` 0.25.7, then `ui` 0.47.0. ui pins core `0.25.7` exactly, `@plannotator/atomic-editor` `^0.9.0` and `@plannotator/markdown-editor` `^0.5.0`. See "Host link widgets (0.47.0, core 0.25.7)".
 - **ui 0.46.1 (fix, ui only, core pin unchanged at `0.25.6`):** `useVimSelection` (mounted by every `Viewer`) now only clears a page selection whose anchor or focus lies inside the viewer's own container; with vim off it used to clear the WHOLE page's selection on every mount and `contentVersion` change, so a selection in another host panel vanished whenever the document behind it loaded or changed.
 - **ui 0.45.0 (annotation card header slot + mentions on the card's edit box): `@plannotator/ui` only — `@plannotator/core` is UNCHANGED at `0.25.5`, so this publishes alone** (core 0.25.5 must already be published). Purely additive over 0.44.0, both props on `AnnotationPanel`: `renderCardHeader` (the header-row twin of `renderCardFooter`, wrapper `[data-annotation-card-header]`, renders under `readOnly`, open-document cards only in the All-files view) and `mentionSource` (the 0.43.0 type, applied to the card's EDIT box, saving `onEdit(id, { text, mentions })` only when a source was supplied and a pick survived). Nothing is removed, no new supported imports (`components/MentionAutocomplete` is internal glue), no export-, share- or archive-visible change, and Plannotator passes neither — `packages/editor` and `packages/review-editor` have zero source diff, and the panel is byte-identical to 0.44.0. Known difference from `CommentPopover`: no chips in the card's edit box (follow-up named in the section). See "Annotation card header slot and mentions on the edit box (0.45.0)".
 - **ui 0.44.0 (mention token chips in the composer): `@plannotator/ui` only — `@plannotator/core` is UNCHANGED at `0.25.5`, so this publishes alone** (core 0.25.5 must already be published). Purely additive over 0.43.2: the `@Label` tokens a `mentionSource` composer inserted render as chips in the composer's existing highlight overlay, `MentionSource.tokenClassName?` lets a host restyle them (under the metric rule), `useMentionAutocomplete` also returns the surviving `mentions`, and `utils/composerTokens` joins the supported-import list. Nothing is removed, no export-, share- or archive-visible change, and Plannotator passes none of it — with neither `mentionSource` nor `skillReferences` the composer is byte-identical to 0.43.2. See "Mention token chips in the composer (0.44.0)".

package/README.md

@@ -75,9 +75,16 @@ Plannotator's own entries import the eager math and identity modules (`math-eage
   <MarkdownEditor markdown={md} documentId={docId} editorHandleRef={ref} extensions={editorExtensions} />
   ```
 - **`embedPicker(config)` and `embedSlashItem()` are re-exported from the same surface.** Compose the static item into `slashCommands({ items: [...] })` and pass the picker beside it in the stable `extensions` array. `getTargets`, `buildInsertLine`, optional `uploadTarget`, and optional `getNotice` stay live through callbacks. Optional `labels` (`upload`, `empty`, `noMatch(query)`) reword the three rows that say "HTML"; absent keys keep the built-in text. The host owns embed grammar and upload error UI; the package owns filtering, async anchor mapping, single-flight upload state, and paragraph-safe insertion through the re-exported `planEmbedInsert()`.
+- **`linkWidgets(...specs)` and `refreshLinkWidgets` are re-exported from the same surface** (since 0.47.0, engine `@plannotator/atomic-editor` ^0.9.0), with the types `LinkWidgetSpec` and `LinkWidgetLink`. A spec's `match(link)` gets `{ url, text, title?, from, to }` for a single-line `[text](url)` link whose syntax the engine would hide, and returns a CM6 `WidgetType` to draw in the link's place (first non-null spec wins) or `null` for the engine's normal link. The reveal rule (caret, focus, pointer-press freeze, diff ranges) stays the engine's, so the widget comes and goes exactly when the hidden syntax would; `match` is never asked about table-cell links or links wrapping an image. `match` runs on every rebuild: keep it synchronous and side-effect free and implement `eq` on the widget. When the answer changes without a document edit (data arrived after mount), dispatch `view.dispatch({ effects: refreshLinkWidgets.of(null) })`; it changes no text and adds no history entry.
+  ```tsx
+  import { linkWidgets, refreshLinkWidgets, type LinkWidgetSpec } from "@plannotator/ui/components/MarkdownEditor";
+
+  const spec: LinkWidgetSpec = { match: (link) => (isMine(link.url) ? new MyChip(link) : null) };
+  const editorExtensions = [linkWidgets(spec)]; // stable reference!
+  ```
 - **The viewer resolves wiki-links synchronously.** `InlineMarkdown` takes `resolveLinkedDoc?: (target) => { label?; status?: 'active' | 'deleted' } | null` — called with the raw stored target (opaque ids like `doc_01XYZ`, no `.md` normalization). Return a `label` to display live titles (stored label is the fallback, target the last resort); return `status: 'deleted'` for a muted non-link ("Document deleted") instead of a live link. Absent or `null` → rendering is unchanged. Sync-only by design: back it with an in-memory cache.
 
-Requires `@plannotator/markdown-editor ^0.3.2` and `@plannotator/atomic-editor ^0.7.0`. See HANDOFF.md § "Wiki-link seams (0.27.0)".
+Wiki links require `@plannotator/markdown-editor ^0.3.2` and `@plannotator/atomic-editor ^0.7.0` (see HANDOFF.md § "Wiki-link seams (0.27.0)"); link widgets require `@plannotator/markdown-editor ^0.5.0` and `@plannotator/atomic-editor ^0.9.0`, which is what 0.47.0 declares (see HANDOFF.md § "Host link widgets (0.47.0)").
 
 ### Frozen markdown diff (`MarkdownDiff`)
 
@@ -367,7 +374,7 @@ npm install @plannotator/ui @plannotator/core
 - `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
 - `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on an exact published `@plannotator/core` version. Published.
 - `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
-- Currently `@plannotator/ui` 0.46.1 depends exactly on `@plannotator/core` 0.25.6. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
+- Currently `@plannotator/ui` 0.47.0 depends exactly on `@plannotator/core` 0.25.7. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
 
 ## The one rule
 

package/components/AISettingsTab.tsx

@@ -1,5 +1,6 @@
 import type React from 'react';
 import { getProviderMeta } from './ProviderIcons';
+import { ModelSourceHint, modelSourceToolForProvider } from './ModelSourceHint';
 import {
   getAIProviderSettings,
   resolveAIProviderSelection,
@@ -121,6 +122,11 @@ export const AISettingsTab: React.FC<AISettingsTabProps> = ({
                       ))}
                     </select>
                   </label>
+                  <ModelSourceHint
+                    tool={modelSourceToolForProvider(p.name)}
+                    info={p}
+                    className="mt-1.5 text-[10px] text-muted-foreground/60"
+                  />
                 </div>
               )}
 

package/components/AgentsTab.tsx

@@ -23,6 +23,7 @@ import { useAgentSettings } from '../hooks/useAgentSettings';
 import type { AgentEngine, AgentMode, ReviewEngine } from '../hooks/useAgentSettings';
 import type { AgentLaunchParams } from '../hooks/useAgentJobs';
 import { ConfigRow, SegmentedPicker, Toggle, SelectMenu } from './AgentControls';
+import { ModelSourceHint } from './ModelSourceHint';
 import {
   CLAUDE_FALLBACK_MODELS,
   CODEX_FALLBACK_MODELS,
@@ -429,6 +430,12 @@ function JobCard({
         </button>
       )}
 
+      {job.warning && (
+        <p role="status" data-agent-job-warning className="mt-1.5 ml-4 text-[10px] leading-snug text-warning">
+          {job.warning}
+        </p>
+      )}
+
       {/* Error details — fallback for when the dockview detail panel is not available */}
       {!onViewDetails && job.status === 'failed' && job.error && expanded && (
         <div className="mt-2 rounded bg-destructive/5 border border-destructive/20 p-2">
@@ -1015,7 +1022,10 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
   ) => (
     <ConfigRow label="Model" stacked>
       {catalogs[engine].settled ? (
-        <SelectMenu value={value} options={modelSelectOptions(catalogs[engine].models, value)} onChange={onChange} />
+        <>
+          <SelectMenu value={value} options={modelSelectOptions(catalogs[engine].models, value)} onChange={onChange} />
+          <ModelSourceHint tool={engine} info={catalogs[engine]} className="text-[10px] text-muted-foreground/50" />
+        </>
       ) : (
         renderStaticChoice('Loading models…', <Loader2 className="animate-spin text-muted-foreground" size={11} />)
       )}

package/components/MarkdownEditor.tsx

@@ -34,6 +34,15 @@ export type { SlashCommandItem, SlashCommandsConfig } from '@plannotator/atomic-
 export { selectionToolbar } from '@plannotator/atomic-editor';
 export type { SelectionToolbarConfig, InlineFormat } from '@plannotator/atomic-editor';
 
+/* Host link widgets (engine ≥0.9.0), re-exported for the same reason as
+   wikiLinks. linkWidgets(...specs) lets a host swap an inline markdown link
+   for its own WidgetType when a spec's match(link) returns one (null keeps
+   the engine's normal link rendering). Compose it through the `extensions`
+   prop; dispatch refreshLinkWidgets.of(null) on the view to re-run every
+   spec's match after host state the specs read has changed. */
+export { linkWidgets, refreshLinkWidgets } from '@plannotator/atomic-editor';
+export type { LinkWidgetSpec, LinkWidgetLink } from '@plannotator/atomic-editor';
+
 /* Host-configured embed media authoring. The picker is per editor mount so its
    callbacks can close over live route state; nothing enters configurePlannotatorUI.
    The package owns paragraph-safe splicing while the host owns embed grammar. */

package/components/ModelSourceHint.tsx

@@ -0,0 +1,49 @@
+import type React from 'react';
+import type { ModelsSource } from '@plannotator/core/model-catalog';
+
+/** The tools whose model lists are discovered from the installed CLI. */
+export type ModelSourceTool = 'claude' | 'codex';
+
+export interface ModelSourceInfo {
+  modelsSource?: ModelsSource;
+  toolVersion?: string;
+}
+
+const TOOL_NAME: Record<ModelSourceTool, string> = {
+  claude: 'Claude Code',
+  codex: 'Codex',
+};
+
+/** The hint tool for an Ask AI provider type (`claude-agent-sdk`, `codex-sdk`); null for the rest. */
+export function modelSourceToolForProvider(providerType: string | null | undefined): ModelSourceTool | null {
+  if (providerType === 'claude-agent-sdk') return 'claude';
+  if (providerType === 'codex-sdk') return 'codex';
+  return null;
+}
+
+/**
+ * Where the model list under a picker came from. Only when the server reports
+ * the tool's version: a host that does not send it gets no hint.
+ */
+export function modelSourceHint(tool: ModelSourceTool | null | undefined, info: ModelSourceInfo | null | undefined): string | null {
+  if (!tool || !info?.toolVersion) return null;
+  const name = TOOL_NAME[tool];
+  if (info.modelsSource === 'discovered') return `From your installed ${name} ${info.toolVersion}`;
+  if (info.modelsSource === 'fallback') return `Using the built-in list — update or sign in to ${name} to see its latest models`;
+  return null;
+}
+
+/** A muted line under a model picker; renders nothing when there is no hint. */
+export const ModelSourceHint: React.FC<{
+  tool: ModelSourceTool | null | undefined;
+  info: ModelSourceInfo | null | undefined;
+  className?: string;
+}> = ({ tool, info, className }) => {
+  const text = modelSourceHint(tool, info);
+  if (!text) return null;
+  return (
+    <p data-model-source-hint={info?.modelsSource} className={className}>
+      {text}
+    </p>
+  );
+};

package/components/ai/AIProviderBar.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import { getProviderMeta } from '../ProviderIcons';
 import { type AIProviderOption } from '../../utils/aiProvider';
+import { ModelSourceHint, modelSourceToolForProvider } from '../ModelSourceHint';
 
 interface AIProviderBarProps {
   providers: AIProviderOption[];
@@ -42,6 +43,7 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
   const showReasoningEffort = !!onReasoningEffortChange && reasoningEfforts.length > 0;
 
   return (
+    <>
     <div className="border-t border-border/50 px-2 py-1.5 flex items-center gap-1.5 text-[11px] text-muted-foreground">
       <Icon className="w-3.5 h-3.5 flex-shrink-0" />
       <select
@@ -91,5 +93,11 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
         </select>
       )}
     </div>
+    <ModelSourceHint
+      tool={modelSourceToolForProvider(currentProvider?.name)}
+      info={currentProvider}
+      className="-mt-1 px-2 pb-1.5 text-[10px] text-muted-foreground/50"
+    />
+    </>
   );
 };

package/hooks/useAgentSettings.ts

@@ -36,6 +36,13 @@ export const DEFAULT_GUIDE_CLAUDE_MODEL = 'sonnet';
 // low effort chapter a diff well. Guide-scoped only — tour/review keep medium.
 export const DEFAULT_GUIDE_CLAUDE_EFFORT = 'low';
 export const DEFAULT_GUIDE_CODEX_MODEL = '';
+/**
+ * The Codex model a guide uses for a user who has not picked one (saved ''),
+ * when the resolved catalog offers it; otherwise Codex's own marked default.
+ * A resolution preference only, never written to the cookie, so a saved pick
+ * always wins. Guide-scoped: review and tour keep Codex's default.
+ */
+export const PREFERRED_GUIDE_CODEX_MODEL = 'gpt-6-luna';
 export const DEFAULT_GUIDE_CODEX_REASONING = 'low';
 // No DEFAULT_GUIDE_CODEX_FAST: fast mode is deliberately not offered for
 // guide (product decision — see AgentsTab's guide codex config block), so
@@ -463,7 +470,7 @@ export function useAgentSettings(catalogs?: ModelCatalogs) {
   const tourCodexFast = effectiveFast(codexCatalog, state.tourCodex.model, tourCodexModel, state.tourCodex.perModel[state.tourCodex.model]?.fast ?? DEFAULT_TOUR_CODEX_FAST);
   const guideClaudeModel = effectiveModel(claudeCatalog, state.guideClaude.model, DEFAULT_GUIDE_CLAUDE_MODEL);
   const guideClaudeEffort = effectiveEffort(claudeCatalog, guideClaudeModel, state.guideClaude.perModel[state.guideClaude.model]?.effort ?? DEFAULT_GUIDE_CLAUDE_EFFORT);
-  const guideCodexModel = effectiveModel(codexCatalog, state.guideCodex.model, DEFAULT_GUIDE_CODEX_MODEL);
+  const guideCodexModel = effectiveModel(codexCatalog, state.guideCodex.model, PREFERRED_GUIDE_CODEX_MODEL);
   const guideCodexReasoning = effectiveEffort(codexCatalog, guideCodexModel, state.guideCodex.perModel[state.guideCodex.model]?.reasoning ?? DEFAULT_GUIDE_CODEX_REASONING);
   // Guide offers no fast toggle; a re-key carries whatever is stored.
   const guideCodexFast = state.guideCodex.perModel[state.guideCodex.model]?.fast ?? DEFAULT_CODEX_FAST;

package/hooks/useCodeAnnotationDraft.ts

@@ -72,6 +72,8 @@ interface UseCodeAnnotationDraftOptions {
   autoViewSuppressed?: Set<string>;
   isApiMode: boolean;
   submitted: boolean;
+  /** Hosts with independent review-progress storage omit viewed state from drafts. */
+  persistViewedFiles?: boolean;
   /** Receives the unsent items found on a target the session switched onto
    *  in place (#1590), already filtered to ids the session neither holds nor
    *  deleted. The host adds them to its state; autosave then saves the merge.
@@ -125,12 +127,15 @@ export function useCodeAnnotationDraft({
   submitted,
   onDraftTargetMerge,
   targetLoadTimeoutMs = TARGET_LOAD_TIMEOUT_MS,
+  persistViewedFiles = true,
 }: UseCodeAnnotationDraftOptions): UseCodeAnnotationDraftResult {
   const [draftBanner, setDraftBanner] = useState<{ count: number; viewedCount: number; timeAgo: string } | null>(null);
   const draftDataRef = useRef<DraftData | null>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hasMountedRef = useRef(false);
   const draftGenerationRef = useRef(0);
+  const persistViewedRef = useRef(persistViewedFiles);
+  persistViewedRef.current = persistViewedFiles;
   // True once the user has actually had annotations this session. Used to decide
   // whether an empty state is a real "cleared everything" edit (persist it) vs a
   // fresh/unengaged session (leave the server alone). Keyed on annotations only —
@@ -186,6 +191,9 @@ export function useCodeAnnotationDraft({
         return data as DraftData | null;
       })
       .then((data: DraftData | null) => {
+        // Keep even a viewed-only draft while independent progress support is
+        // unresolved; a failed/unsupported load may need to offer it later.
+        draftDataRef.current = data;
         const generation = readDraftGeneration(data?.draftGeneration);
         if (generation !== null) {
           draftGenerationRef.current = Math.max(draftGenerationRef.current, generation);
@@ -193,7 +201,7 @@ export function useCodeAnnotationDraft({
         const annotationCount = (Array.isArray(data?.codeAnnotations) ? data.codeAnnotations.length : 0)
           + (Array.isArray(data?.descriptionAnnotations) ? data.descriptionAnnotations.length : 0)
           + (Array.isArray(data?.commentAnnotations) ? data.commentAnnotations.length : 0);
-        const viewedCount = Array.isArray(data?.viewedFiles) ? data.viewedFiles.length : 0;
+        const viewedCount = persistViewedRef.current && Array.isArray(data?.viewedFiles) ? data.viewedFiles.length : 0;
         if (annotationCount > 0 || viewedCount > 0) {
           draftDataRef.current = data;
           setDraftBanner({
@@ -209,6 +217,15 @@ export function useCodeAnnotationDraft({
       });
   }, [isApiMode]);
 
+  useEffect(() => {
+    const data = draftDataRef.current;
+    if (!data) return;
+    const count = (data.codeAnnotations?.length ?? 0)
+      + (data.descriptionAnnotations?.length ?? 0) + (data.commentAnnotations?.length ?? 0);
+    const viewedCount = persistViewedFiles ? data.viewedFiles?.length ?? 0 : 0;
+    setDraftBanner(count || viewedCount ? { count, viewedCount, timeAgo: formatTimeAgo(data.ts || 0) } : null);
+  }, [persistViewedFiles]);
+
   // Debounced auto-save on annotation/viewed changes
   useEffect(() => {
     if (!isApiMode || submitted) return;
@@ -223,7 +240,7 @@ export function useCodeAnnotationDraft({
     //     via `allAnnotations` and have their own lifecycle, separate from the draft.
     if (annotations.some((a) => !a.source) || descriptionAnnotations.length > 0 || commentAnnotations.length > 0) hasHadAnnotationsRef.current = true;
 
-    const isEmpty = annotations.length === 0 && descriptionAnnotations.length === 0 && commentAnnotations.length === 0 && viewedFiles.size === 0;
+    const isEmpty = annotations.length === 0 && descriptionAnnotations.length === 0 && commentAnnotations.length === 0 && (!persistViewedFiles || viewedFiles.size === 0);
     // Leave the server alone for an empty state until the user has actually had
     // annotations this session. This preserves an unrestored draft sitting on disk
     // at mount (the draft-recovery banner can still offer it).
@@ -259,8 +276,8 @@ export function useCodeAnnotationDraft({
         codeAnnotations: annotations,
         descriptionAnnotations,
         commentAnnotations,
-        viewedFiles: [...viewedFiles],
-        ...(autoViewSuppressed && autoViewSuppressed.size > 0
+        ...(persistViewedFiles ? { viewedFiles: [...viewedFiles] } : {}),
+        ...(persistViewedFiles && autoViewSuppressed && autoViewSuppressed.size > 0
           ? { autoViewSuppressed: [...autoViewSuppressed] }
           : {}),
         draftGeneration,
@@ -273,7 +290,7 @@ export function useCodeAnnotationDraft({
     return () => {
       if (timerRef.current) clearTimeout(timerRef.current);
     };
-  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted, saveNudge]);
+  }, [annotations, descriptionAnnotations, commentAnnotations, viewedFiles, autoViewSuppressed, isApiMode, submitted, saveNudge, persistViewedFiles]);
 
   const restoreDraft = useCallback(() => {
     // Cancel any pending autosave so it can't fire with pre-restore state and
@@ -286,9 +303,9 @@ export function useCodeAnnotationDraft({
       annotations: data?.codeAnnotations ?? [],
       descriptionAnnotations: data?.descriptionAnnotations ?? [],
       commentAnnotations: data?.commentAnnotations ?? [],
-      viewedFiles: data?.viewedFiles ?? [],
-      autoViewSuppressed: data?.autoViewSuppressed ?? [],
       patchChanged: data?.patchChanged === true,
+      viewedFiles: persistViewedRef.current ? data?.viewedFiles ?? [] : [],
+      autoViewSuppressed: persistViewedRef.current ? data?.autoViewSuppressed ?? [] : [],
     };
   }, []);
 

package/hooks/useModelCatalogs.ts

@@ -3,6 +3,7 @@ import {
   CLAUDE_FALLBACK_MODELS,
   CODEX_FALLBACK_MODELS,
   type CatalogModel,
+  type ModelsSource,
 } from '@plannotator/core/model-catalog';
 import type { AgentCapabilities } from '../types';
 
@@ -26,8 +27,14 @@ export type CatalogEngine = 'claude' | 'codex';
 export interface ModelCatalog {
   models: CatalogModel[];
   settled: boolean;
+  /** Where the server says the list came from; absent when it did not say. */
+  modelsSource?: ModelsSource;
+  /** The installed CLI's version, when the server reports it. */
+  toolVersion?: string;
 }
 
+type LoadedCatalog = Pick<ModelCatalog, 'models' | 'modelsSource' | 'toolVersion'>;
+
 export interface ModelCatalogs extends Record<CatalogEngine, ModelCatalog> {
   /** Fetch one engine's catalog (no-op for other engines or when not installed). */
   load: (engine: string | null | undefined) => void;
@@ -47,19 +54,19 @@ const isCatalogEngine = (engine: unknown): engine is CatalogEngine => engine ===
 
 // One request per engine per page: every launcher surface shares the answer.
 // A failed request is forgotten so the next load retries it.
-const loads = new Map<CatalogEngine, Promise<CatalogModel[]>>();
+const loads = new Map<CatalogEngine, Promise<LoadedCatalog>>();
 
-export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]> {
+function loadCatalogEntry(engine: CatalogEngine): Promise<LoadedCatalog> {
   let load = loads.get(engine);
   if (!load) {
     const id = AI_PROVIDER_ID[engine];
-    const failed = () => {
+    const failed = (): LoadedCatalog => {
       loads.delete(engine);
-      return FALLBACK_MODELS[engine];
+      return { models: FALLBACK_MODELS[engine] };
     };
     load = fetch(`/api/ai/capabilities?activate=${encodeURIComponent(id)}`)
       .then((res) => (res.ok ? res.json() : null))
-      .then((data) => {
+      .then((data): LoadedCatalog => {
         const provider = data?.providers?.find((p: { id?: string; name?: string }) => p.id === id || p.name === id);
         const models = provider?.models;
         if (!Array.isArray(models) || models.length === 0) return failed();
@@ -67,7 +74,13 @@ export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]>
         // failed; show it, but forget it so the next load retries (the
         // server's own cooldown bounds how often that spawns the CLI).
         if (provider.modelsSource === 'fallback') loads.delete(engine);
-        return models as CatalogModel[];
+        return {
+          models: models as CatalogModel[],
+          ...(provider.modelsSource === 'fallback' || provider.modelsSource === 'discovered'
+            ? { modelsSource: provider.modelsSource as ModelsSource }
+            : {}),
+          ...(typeof provider.toolVersion === 'string' && provider.toolVersion ? { toolVersion: provider.toolVersion } : {}),
+        };
       })
       .catch(failed);
     loads.set(engine, load);
@@ -75,6 +88,10 @@ export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]>
   return load;
 }
 
+export function loadModelCatalog(engine: CatalogEngine): Promise<CatalogModel[]> {
+  return loadCatalogEntry(engine).then((entry) => entry.models);
+}
+
 /** Test seam: forget cached catalogs. */
 export function __resetModelCatalogsForTests(): void {
   loads.clear();
@@ -85,7 +102,7 @@ export function useModelCatalogs(capabilities: AgentCapabilities | null): ModelC
     capabilities?.providers.some((p) => p.id === id && p.available) ?? false;
   const claudeOn = available('claude');
   const codexOn = available('codex');
-  const [loaded, setLoaded] = useState<Partial<Record<CatalogEngine, CatalogModel[]>>>({});
+  const [loaded, setLoaded] = useState<Partial<Record<CatalogEngine, LoadedCatalog>>>({});
   const mounted = useRef(true);
   useEffect(() => {
     mounted.current = true;
@@ -98,8 +115,8 @@ export function useModelCatalogs(capabilities: AgentCapabilities | null): ModelC
     (engine: string | null | undefined) => {
       if (!isCatalogEngine(engine)) return;
       if (!(engine === 'claude' ? claudeOn : codexOn)) return;
-      void loadModelCatalog(engine).then((models) => {
-        if (mounted.current) setLoaded((prev) => (prev[engine] === models ? prev : { ...prev, [engine]: models }));
+      void loadCatalogEntry(engine).then((entry) => {
+        if (mounted.current) setLoaded((prev) => (prev[engine] === entry ? prev : { ...prev, [engine]: entry }));
       });
     },
     [claudeOn, codexOn],
@@ -107,8 +124,8 @@ export function useModelCatalogs(capabilities: AgentCapabilities | null): ModelC
 
   return useMemo(
     () => ({
-      claude: { models: loaded.claude ?? FALLBACK_MODELS.claude, settled: !!loaded.claude },
-      codex: { models: loaded.codex ?? FALLBACK_MODELS.codex, settled: !!loaded.codex },
+      claude: loaded.claude ? { ...loaded.claude, settled: true } : { models: FALLBACK_MODELS.claude, settled: false },
+      codex: loaded.codex ? { ...loaded.codex, settled: true } : { models: FALLBACK_MODELS.codex, settled: false },
       load,
     }),
     [loaded, load],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -75,9 +75,9 @@
     "@lezer/common": "^1.5.2",
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.6",
-    "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.25.6",
-    "@plannotator/markdown-editor": "^0.4.0",
+    "@plannotator/atomic-editor": "^0.9.0",
+    "@plannotator/core": "0.25.7",
+    "@plannotator/markdown-editor": "^0.5.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
     "@viz-js/viz": "3.30.0",