@flame0510/project-aether 1.5.2 → 1.6.0

package/app/gateway/ModelDetailsModal.tsx

@@ -0,0 +1,322 @@
+'use client';
+
+/**
+ * Everything known about one model: what it is, what it costs, what it can do and how it
+ * scores. Opened from the Gateway's model row and **fetched when it opens**
+ * (`GET /api/models/details`) — descriptions are long and one model is looked at at a
+ * time, so inlining them in `/api/models` would weigh down every page poll.
+ *
+ * Absent data is not shown at all: no "n/a" blocks, and no number without its source.
+ * Prices come from the owner of the model (`model-pricing.json`), specs, description and
+ * OpenRouter benchmarks from the generated `model-details.json`, and anything else from
+ * the catalogue's hand-written `info` block.
+ */
+import { useEffect, useState } from 'react';
+import { Button, LoadingSpinner, Metric, Modal, ModalityIcons, Pill, PropertyList } from '../components/ui';
+import { formatParams, formatPrice } from '../lib/model-format';
+
+/** Mirrors lib/model-details.ts: a client component cannot import a module that reads files. */
+interface DetailsView {
+  id: string;
+  name: string;
+  provider: string;
+  providerLabel: string;
+  modality?: string;
+  enabled: boolean;
+  deprecated: boolean;
+  price: { input: number; output: number; source: 'openrouter' | 'vendor' } | null;
+  details: {
+    description?: string;
+    created?: string;
+    context?: number;
+    providerContext?: number;
+    maxOutput?: number;
+    tokenizer?: string;
+    instructType?: string;
+    /** Total parameter count, from the model's Hugging Face card (open weights only). */
+    params?: number;
+    paramsSource?: string;
+    /** Architecture facts from the model card (Hugging Face); open weights only. */
+    hf?: {
+      id: string;
+      total?: number;
+      byDtype?: Record<string, number>;
+      family?: string;
+      modelType?: string;
+      moe?: { experts?: number; perToken?: number; shared?: number };
+      layers?: number;
+      hidden?: number;
+      heads?: number;
+      kvHeads?: number;
+      vocab?: number;
+      context?: number;
+      vision?: boolean;
+      quantization?: string;
+      task?: string;
+      languages?: string[];
+      license?: string;
+      licenseName?: string;
+      published?: string;
+      updated?: string;
+      weightsBytes?: number;
+      tags?: string[];
+      downloads?: number;
+      likes?: number;
+    };
+    knowledgeCutoff?: string;
+    huggingFaceId?: string;
+    canonicalSlug?: string;
+    url?: string;
+    reasoning?: { mandatory?: boolean; default_enabled?: boolean; supported_efforts?: string[]; default_effort?: string };
+    supportedParameters?: string[];
+    moderated?: boolean;
+    benchmarks?: {
+      design_arena?: { arena?: string; category?: string; elo?: number; win_rate?: number; rank?: number }[];
+      artificial_analysis?: Record<string, number>;
+    };
+  } | null;
+  info: {
+    params?: string;
+    released?: string;
+    docUrl?: string;
+    knowledgeCutoff?: string;
+    benchmarks?: { name: string; value: number; source: string; asOf?: string }[];
+    notes?: string;
+  } | null;
+  asOf: string | null;
+  detailsSource: 'openrouter' | 'none';
+}
+
+const count = (n?: number): string | undefined => (typeof n === 'number' ? n.toLocaleString('en-US') : undefined);
+
+/** "1,048,576" is unreadable in a small metric: 1.05M reads at a glance. */
+function compactCount(n: number): string {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(n >= 1e7 ? 0 : 2)}M`;
+  if (n >= 1e3) return `${Math.round(n / 1e3)}k`;
+  return String(n);
+}
+
+/** "BF16 6.9B · FP8 314.4B" — the weights' precision mix, biggest first. */
+function dtypeMix(byDtype: Record<string, number>): string {
+  return Object.entries(byDtype)
+    .filter(([, n]) => n > 1e6)
+    .sort((a, b) => b[1] - a[1])
+    .map(([k, n]) => `${k.replace('F8_E4M3', 'FP8').replace('F32', 'FP32')} ${formatParams(n)}`)
+    .join(' · ');
+}
+/** `parallel_tool_calls` reads better as words in a chip. */
+const human = (p: string): string => p.replace(/_/g, ' ');
+
+export default function ModelDetailsModal({ modelId, onClose }: { modelId: string; onClose: () => void }) {
+  const [view, setView] = useState<DetailsView | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [fullDescription, setFullDescription] = useState(false);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    setView(null);
+    setError(null);
+    fetch(`/api/models/details?id=${encodeURIComponent(modelId)}`, { signal: controller.signal })
+      .then(async (res) => {
+        const data = await res.json().catch(() => null);
+        if (!res.ok) throw new Error((data as { error?: string } | null)?.error || `HTTP ${res.status}`);
+        return data as DetailsView;
+      })
+      .then(setView)
+      .catch((e: unknown) => { if ((e as Error)?.name !== 'AbortError') setError((e as Error).message); });
+    return () => controller.abort();
+  }, [modelId]);
+
+  const d = view?.details ?? null;
+  const info = view?.info ?? null;
+  const hf = d?.hf ?? null;
+  const reasoning = d?.reasoning;
+  const arenas = d?.benchmarks?.design_arena ?? [];
+  const aa = d?.benchmarks?.artificial_analysis;
+  const released = info?.released ?? hf?.published ?? d?.created;
+
+  return (
+    <Modal open onClose={onClose} title={view ? view.name : modelId} maxWidth={720}>
+      {error ? (
+        <div style={{ fontSize: 12, color: 'var(--red)' }}>{error}</div>
+      ) : !view ? (
+        <LoadingSpinner label="Loading model details…" />
+      ) : (
+        <div style={{ display: 'grid', gap: 4, fontSize: 12 }}>
+          {/* Identity */}
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
+            <Pill>{view.provider}</Pill>
+            {view.deprecated && <Pill tone="warning">deprecated</Pill>}
+            {view.enabled ? <Pill tone="success">enabled</Pill> : <Pill>disabled</Pill>}
+            {view.modality && <ModalityIcons modality={view.modality} />}
+          </div>
+          <div style={{ fontFamily: 'var(--font-mono)', fontSize: 11, color: 'var(--text-dim)', overflowWrap: 'anywhere' }}>
+            {view.id}
+          </div>
+
+          {d?.description && (
+            <div style={{ margin: '8px 0 0' }}>
+              <p style={{
+                fontSize: 12, lineHeight: 1.5, color: 'var(--text)', margin: 0,
+                ...(fullDescription ? {} : { display: '-webkit-box', WebkitLineClamp: 4, WebkitBoxOrient: 'vertical' as const, overflow: 'hidden' }),
+              }}>{d.description}</p>
+              {d.description.length > 340 && (
+                <Button variant="ghost" size="sm" onClick={() => setFullDescription(!fullDescription)}>
+                  {fullDescription ? 'Show less' : 'Show more'}
+                </Button>
+              )}
+            </div>
+          )}
+
+          {(info?.notes || view.deprecated) && (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Status</div>
+              <div style={{ fontSize: 11, color: 'var(--yellow)' }}>
+                {info?.notes ?? 'Upstream has retired this id: it still answers, but is redirected.'}
+              </div>
+            </>
+          )}
+
+          {/* Price */}
+          <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Price</div>
+          <PropertyList rows={[
+            { label: 'Input / output', value: formatPrice(view.price) },
+            ...(view.price ? [{ label: 'Per 1M tokens, from', value: view.providerLabel, dim: true }] : []),
+          ]} />
+
+          {/* Architecture: the factory facts from the model card, open weights only */}
+          {hf && (hf.total || hf.moe || hf.layers) ? (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Architecture</div>
+              <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(108px, 1fr))', gap: 8, marginBottom: 8 }}>
+                {hf.total ? <Metric size="sm" title="Parameters" value={formatParams(hf.total)} /> : null}
+                {hf.moe ? <Metric size="sm" title="Experts" value={`${count(hf.moe.experts) ?? '?'}${hf.moe.perToken ? ` · ${hf.moe.perToken}/tok` : ''}`} /> : null}
+                {hf.layers ? <Metric size="sm" title="Layers" value={hf.layers} /> : null}
+                {hf.context ? <Metric size="sm" title="Max context" value={`${compactCount(hf.context)} tok`} /> : null}
+              </div>
+              <PropertyList rows={[
+                ...(hf.family ? [{ label: 'Family', value: hf.family }] : []),
+                ...(hf.modelType ? [{ label: 'Model type', value: hf.modelType, dim: true }] : []),
+                ...(hf.hidden ? [{ label: 'Hidden size', value: count(hf.hidden) ?? '' }] : []),
+                ...(hf.heads ? [{ label: 'Attention heads', value: `${hf.heads}${hf.kvHeads && hf.kvHeads !== hf.heads ? ` (${hf.kvHeads} KV)` : ''}` }] : []),
+                ...(hf.vocab ? [{ label: 'Vocabulary', value: count(hf.vocab) ?? '' }] : []),
+                ...(hf.vision ? [{ label: 'Vision encoder', value: 'yes (multimodal)' }] : []),
+                ...(hf.quantization ? [{ label: 'Precision', value: hf.quantization.toUpperCase() }] : []),
+                ...(hf.weightsBytes ? [{ label: 'Weights on disk', value: `~${hf.weightsBytes >= 1e12 ? `${(hf.weightsBytes / 1e12).toFixed(1)} TB` : `${Math.round(hf.weightsBytes / 1e9)} GB`}` }] : []),
+                ...(hf.license ? [{ label: 'Licence', value: hf.license === 'other' ? 'custom — see the model card' : `${hf.license.toUpperCase()}${hf.licenseName ? ` (${hf.licenseName})` : ''}` }] : []),
+                ...(hf.byDtype ? [{ label: 'Weights by dtype', value: dtypeMix(hf.byDtype), dim: true }] : []),
+                ...(hf.task ? [{ label: 'Task', value: human(hf.task) }] : []),
+                ...(hf.languages?.length ? [{ label: 'Languages', value: hf.languages.join(', ') }] : []),
+                ...(hf.downloads || hf.likes ? [{ label: 'Popularity', value: `${count(hf.downloads) ?? '—'} downloads · ${count(hf.likes) ?? '—'} likes`, dim: true }] : []),
+              ]} />
+              <div style={{ fontSize: 10, color: 'var(--text-dim)', marginTop: 4 }}>
+                From the model card on Hugging Face ({hf.id}).
+              </div>
+            </>
+          ) : null}
+
+          {/* Specs */}
+          <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Specs</div>
+          <PropertyList rows={[
+            ...(released ? [{ label: 'Released', value: released }] : []),
+            ...(hf?.updated && hf.updated !== released ? [{ label: 'Card updated', value: hf.updated, dim: true }] : []),
+            ...(count(d?.context) ? [{ label: 'Context', value: `${count(d?.context)} tokens` }] : []),
+            ...(d?.providerContext && d.providerContext !== d.context ? [{ label: 'Provider limit', value: `${count(d.providerContext)} tokens`, dim: true }] : []),
+            ...(count(d?.maxOutput) ? [{ label: 'Max output', value: `${count(d?.maxOutput)} tokens` }] : []),
+            // The curated value can be more precise than the card (MoE total vs active);
+            // when there is none, the Hugging Face count is the honest number we have.
+            ...(info?.params
+              // The vendor's own framing (total/active), next to the card's total below:
+              // labelled, or the two numbers read as a contradiction.
+              ? [{ label: 'Parameters (vendor)', value: info.params }]
+              : []),
+            ...(info?.knowledgeCutoff || d?.knowledgeCutoff ? [{ label: 'Knowledge cutoff', value: info?.knowledgeCutoff ?? d?.knowledgeCutoff ?? '' }] : []),
+            ...(d?.tokenizer ? [{ label: 'Tokenizer', value: d.tokenizer, dim: true }] : []),
+            ...(d?.instructType ? [{ label: 'Instruct type', value: d.instructType, dim: true }] : []),
+            ...(d?.moderated ? [{ label: 'Moderated', value: 'yes' }] : []),
+          ]} />
+
+          {/* Reasoning */}
+          {reasoning && (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 4px' }}>Reasoning</div>
+              <PropertyList rows={[
+                { label: 'Mode', value: reasoning.mandatory ? 'always reasons' : reasoning.default_enabled ? 'on by default' : 'optional' },
+                ...(reasoning.default_effort ? [{ label: 'Default effort', value: reasoning.default_effort }] : []),
+                ...(reasoning.supported_efforts?.length ? [{ label: 'Efforts', value: reasoning.supported_efforts.join(', ') }] : []),
+              ]} />
+            </>
+          )}
+
+          {/* Capabilities */}
+          {(d?.supportedParameters?.length || hf?.tags?.length) ? (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '12px 0 6px' }}>Capabilities</div>
+              <div style={{ display: 'flex', flexWrap: 'wrap', gap: 4 }}>
+                {[...new Set([...(d?.supportedParameters ?? []), ...(hf?.tags ?? [])])].map((c) => <Pill key={c}>{human(c)}</Pill>)}
+              </div>
+            </>
+          ) : null}
+
+          {/* Benchmarks: OpenRouter's, then the curated ones */}
+          {aa || arenas.length > 0 || info?.benchmarks?.length ? (
+            <>
+              <div style={{ fontSize: 10, color: 'var(--violet)', textTransform: 'uppercase', letterSpacing: '0.08em', margin: '14px 0 6px' }}>Benchmarks</div>
+              {aa && (
+                <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(120px, 1fr))', gap: 8, marginBottom: 8 }}>
+                  {Object.entries(aa).map(([k, v]) => <Metric key={k} title={human(k)} value={v} />)}
+                </div>
+              )}
+              {arenas.length > 0 && (
+                <div style={{ display: 'grid', gap: 2 }}>
+                  <div style={{ display: 'grid', gridTemplateColumns: '1fr 60px 50px 60px', gap: 6, fontSize: 10, color: 'var(--text-dim)', textTransform: 'uppercase', letterSpacing: '0.06em' }}>
+                    <span>Design arena</span><span style={{ textAlign: 'right' }}>Elo</span><span style={{ textAlign: 'right' }}>Rank</span><span style={{ textAlign: 'right' }}>Win rate</span>
+                  </div>
+                  {arenas.map((a, i) => (
+                    <div key={`${a.category ?? i}`} style={{ display: 'grid', gridTemplateColumns: '1fr 60px 50px 60px', gap: 6, fontSize: 11 }}>
+                      <span>{human(String(a.category ?? a.arena ?? '—'))}</span>
+                      <span style={{ textAlign: 'right', fontFamily: 'var(--font-mono)' }}>{a.elo ?? '—'}</span>
+                      <span style={{ textAlign: 'right', fontFamily: 'var(--font-mono)' }}>{a.rank ? `#${a.rank}` : '—'}</span>
+                      <span style={{ textAlign: 'right', fontFamily: 'var(--font-mono)' }}>{a.win_rate !== undefined ? `${a.win_rate}%` : '—'}</span>
+                    </div>
+                  ))}
+                  <div style={{ fontSize: 10, color: 'var(--text-dim)', marginTop: 2 }}>OpenRouter arenas (community votes), as of the file's date below.</div>
+                </div>
+              )}
+              {info?.benchmarks?.length ? (
+                <div style={{ display: 'grid', gap: 3, marginTop: 8 }}>
+                  {info.benchmarks.map((b) => (
+                    <div key={b.name} style={{ fontSize: 11 }}>
+                      <span style={{ fontFamily: 'var(--font-mono)' }}>{b.value}</span>
+                      <span style={{ marginLeft: 6 }}>{b.name}</span>
+                      <a href={b.source} target="_blank" rel="noreferrer" style={{ marginLeft: 6, color: 'var(--violet)', fontSize: 10 }}>source</a>
+                      {b.asOf && <span style={{ marginLeft: 6, color: 'var(--text-dim)', fontSize: 10 }}>({b.asOf})</span>}
+                    </div>
+                  ))}
+                </div>
+              ) : null}
+            </>
+          ) : null}
+
+          {/* Links + provenance */}
+          <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', alignItems: 'center', marginTop: 14, fontSize: 10, color: 'var(--text-dim)' }}>
+            {d?.url && <a href={d.url} target="_blank" rel="noreferrer" style={{ color: 'var(--violet)' }}>OpenRouter page</a>}
+            {d?.huggingFaceId && <span>HF: {d.huggingFaceId}</span>}
+            {info?.docUrl && <a href={info.docUrl} target="_blank" rel="noreferrer" style={{ color: 'var(--violet)' }}>Vendor docs</a>}
+          </div>
+          <div style={{ marginTop: 6, fontSize: 10, color: 'var(--text-dim)' }}>
+            {view.detailsSource === 'openrouter'
+              ? `Specs and benchmarks via OpenRouter${d?.paramsSource === 'huggingface' ? ', size via Hugging Face' : ''}`
+              : 'No generated details for this model'}
+            {view.asOf ? ` · data as of ${view.asOf.slice(0, 10)}` : ''}
+          </div>
+
+          <div style={{ display: 'flex', justifyContent: 'flex-end', marginTop: 12 }}>
+            <Button variant="secondary" size="sm" onClick={onClose}>Close</Button>
+          </div>
+        </div>
+      )}
+    </Modal>
+  );
+}

package/app/gateway/PageClient.tsx

@@ -2,6 +2,8 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { Button, ConfirmModal, Input, LoadingSpinner, Metric, ModalityIcons, Page, PageHeader, Pill, Surface } from '../components/ui';
+import ModelDetailsModal from './ModelDetailsModal';
+import { formatParams, formatPrice } from '../lib/model-format';
 import PasswordInput from '../components/PasswordInput';
 import { Skeleton } from '../components/Skeleton';
 import { useModels } from '../lib/models-context';
@@ -19,6 +21,8 @@ interface ModelInfo {
   pricingLive?: boolean;
   /** e.g. "text+image+file->text" — curated, matches what sync.ts provisions. */
   modality?: string;
+  /** Total parameters, when the model's card publishes them (open weights only). */
+  params?: number;
 }
 
 interface GatewayProvider {
@@ -89,6 +93,8 @@ export default function GatewayPageClient() {
 
   // Balance fetch state (per provider)
   const [balances, setBalances] = useState<Record<string, { balance: string; label?: string; loading?: boolean; error?: string; unsupported?: boolean } | null>>({});
+  /** Model whose details modal is open, null when none. */
+  const [detailsId, setDetailsId] = useState<string | null>(null);
   const [fetchingBalance, setFetchingBalance] = useState<Record<string, boolean>>({});
 
   // Accordion state — which provider cards are expanded
@@ -155,14 +161,8 @@ export default function GatewayPageClient() {
 
   useEffect(() => { void loadAll(); }, [loadAll]);
 
-  /** Format pricing for display: "$0.44 / $0.87" or "Free" or "Dynamic" or "—" */
-  function fmtPrice(p: { input: number; output: number } | null | undefined): string {
-    if (!p) return '—';
-    if (p.input === -1 && p.output === -1) return 'Dynamic';
-    if (p.input === 0 && p.output === 0) return 'Free';
-    const f = (n: number) => n < 0.01 ? `$${n.toFixed(3)}` : `$${n.toFixed(2)}`;
-    return `${f(p.input)} / ${f(p.output)}`;
-  }
+  /** Format pricing for display — shared with the details modal (app/lib/model-format.ts). */
+  const fmtPrice = formatPrice;
 
   /**
    * Local model filter. Matches against both the display name and the id,
@@ -430,7 +430,7 @@ export default function GatewayPageClient() {
       </section>
 
       {/* =========================================================== */}
-      {/*  REV4A API KEY — sezione speciale                         */}
+      {/*  REV4A API KEY — special section                         */}
       {/* =========================================================== */}
       <div style={{ marginBottom: 20 }}>
       <Surface variant="panel">
@@ -658,6 +658,14 @@ export default function GatewayPageClient() {
                                   <span style={{ marginLeft: 8, color: 'var(--violet)', fontWeight: 500 }}>
                                     {fmtPrice(pricing)}
                                   </span>
+                                  {typeof m.params === 'number' && (
+                                    <span
+                                      style={{ marginLeft: 8, color: 'var(--text-dim)' }}
+                                      title={`${m.params.toLocaleString('en-US')} parameters (Hugging Face)`}
+                                    >
+                                      {formatParams(m.params)}
+                                    </span>
+                                  )}
                                   {m.pricingLive && (
                                     <span
                                       title="Live price from the OpenRouter API"
@@ -668,6 +676,15 @@ export default function GatewayPageClient() {
                                   )}
                                 </div>
                               </div>
+                              <Button
+                                variant="ghost"
+                                size="sm"
+                                aria-label={`Details for ${m.name}`}
+                                title="Details"
+                                onClick={() => setDetailsId(m.id)}
+                              >
+                                ⋯
+                              </Button>
                               {modelMsg && (
                                 // Its own full-width line under the name, not a third column. As an
                                 // unconstrained flex item a long sync summary took its natural width
@@ -710,6 +727,7 @@ export default function GatewayPageClient() {
         cancelLabel="Cancel"
         tone="danger"
       />
-    </Page>
+          {detailsId && <ModelDetailsModal modelId={detailsId} onClose={() => setDetailsId(null)} />}
+</Page>
   );
 }

package/app/globals.css

@@ -615,6 +615,9 @@ html, body { height: 100%; height: 100dvh; background: var(--bg); color: var(--t
 .ui-tone--danger { border-color: #7f1d1d; }
 .ui-muted { color: var(--text-dim); }
 .ui-metric-value { margin-top: 14px; font-size: 26px; font-weight: 800; color: var(--text); }
+/* Compact metric: for grids inside dialogs, where the card value would wrap. */
+.ui-metric--sm .ui-metric-value { margin-top: 6px; font-size: 15px; font-weight: 700; line-height: 1.25; word-break: break-word; }
+.ui-metric--sm .ui-kicker { font-size: 9px; }
 .ui-tone--danger .ui-metric-value { color: var(--red); }
 .ui-metric-subtitle { margin-top: 8px; font-size: 11px; }
 .ui-card-head { display: flex; justify-content: space-between; gap: 10px; margin-bottom: 12px; }
@@ -1386,7 +1389,7 @@ html, body { height: 100%; height: 100dvh; background: var(--bg); color: var(--t
 
   /* Padding bottom per non coprire contenuti — handled by .app-shell__content */
 
-  /* Chat button alzato sopra la bottom navbar */
+  /* Chat button raised above the bottom navbar */
   .ochat__trigger {
     bottom: 70px !important;
   }

package/app/lib/model-format.ts

@@ -0,0 +1,21 @@
+/**
+ * Formatting shared by the Gateway model row and the details modal, so the same number
+ * never reads two ways in the same page.
+ */
+
+/** "1.60T", "321.3B", "9.7B", "300M" — the size people actually ask about. */
+export function formatParams(n: number): string {
+  if (n >= 1e12) return `${(n / 1e12).toFixed(2)}T`;
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(0)}M`;
+  return String(n);
+}
+
+/** USD per 1M tokens: "$0.15 / $0.50", or "Free", "Dynamic", "—". */
+export function formatPrice(p: { input: number; output: number } | null | undefined): string {
+  if (!p) return '—';
+  if (p.input === -1 && p.output === -1) return 'Dynamic';
+  if (p.input === 0 && p.output === 0) return 'Free';
+  const f = (n: number) => (n < 0.01 ? `$${n.toFixed(3)}` : `$${n.toFixed(2)}`);
+  return `${f(p.input)} / ${f(p.output)}`;
+}

package/docs/FRONTEND-ARCHITECTURE.md

@@ -36,7 +36,7 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `TemplateOption` | `TemplateOption.tsx` | Agent template selection card with avatar, description, optional badge. Centralises create-agent card styling. |
 | `Pill` | `Pill.tsx` | Small status/attribute label. Variants: `default`, `accent`. |
 | `ModalityIcons` | `ModalityIcons.tsx` | Capability badges parsed from a model's `modality` string (`"text+image->text"`). Input types render as icons; a non-text **output** is called out separately, since reading an image and generating one are different capabilities. Pass `dynamic` for router models, which advertise the union of everything they might route to and so show "varies" instead. |
-| `Metric` | `Metric.tsx` | Metric card with title, value, subtitle, tone. |
+| `Metric` | `Metric.tsx` | Metric card with title, value, subtitle, tone, and a `size` (`md` default, `sm` for a grid inside a dialog: smaller value, tighter spacing). |
 | `StatusCard` | `StatusCard.tsx` | Health/status report card. |
 | `Surface` | `Surface.tsx` | Shared panel/card surface, variant prop. |
 | `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
@@ -51,6 +51,7 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `ChannelManager` / `ChannelSection` | `app/agents/ChannelManager.tsx`, `ChannelSection` inline in `app/agents/PageClient.tsx` | Telegram, in the agent detail panel (`ChannelSection` is the card that opens the modal; the modal title is the agent's display name). Reads `GET /channels`; lists pending pairing requests with **Approve** (`POST /channels/pairing`) and approved senders with **Revoke** after a confirm (`DELETE /channels/pairing?senderId=`). Pending comes from `openclaw pairing list`, approved from OpenClaw's pairing store (`lib/channelManager.ts`). When that store cannot be read the panel shows the reason instead of "No approved senders" (`PairingState.error`), so an empty list is never a guess. Polls pairings every 5 s while open; one keyed busy state per action. |
 | `EditAgentModal` / `EditBanner` | `app/agents/PageClient.tsx` | Rename/ports editing. The modal has **Display Name** and **Host Port** (same input and validation messages as the create wizard, from `lib/agent-ports.ts`), sends `PATCH /api/agents/[id]` and closes on `202`; `EditBanner` (top of the agent detail) polls `GET /api/agents/[id]` every 2 s while an edit is `rebuilding`, resumes on mount, and refetches the agent once it finishes, so a reload or a navigation shows the running edit instead of allowing a second (the server answers 409). No backup is taken: the volume is untouched. The port range is validated **as it is typed**: the modal fetches `GET /api/agents/ports` when it opens (the same set the create form uses, every container, running or stopped) and excludes the agent's own block, so an occupied range shows the API's message inline and the Save button stays disabled — the create wizard does the same with the same endpoint. |
 | `ModelSection` | `app/agents/ModelSection.tsx` | Primary model and fallbacks for one agent, in its detail panel. Explicit save, no restart. The model is a property of the agent, not of the gateway. Tags models the catalogue marks `deprecated`. |
+| `ModelDetailsModal` | `app/gateway/ModelDetailsModal.tsx` | Details for one model, opened by the `⋯` button on a Gateway model row (`aria-label="Details for <name>"`). Fetches `GET /api/models/details?id=` **when it opens** (AbortController, shared spinner, error text) instead of inlining descriptions in the polled list. Sections appear only when their source has data: identity (provider, modality through the shared `ModalityIcons`, enabled and deprecated chips, the id), price with its origin (the provider's display label, from `lib/provider-labels.ts`), specs (release date, context and the provider's own limit when it differs, max output, knowledge cutoff, tokenizer, instruct type, moderation, **Architecture** (a metric row — parameters, experts, layers, max context — over the facts from the model card: family, model type, hidden size, attention heads with KV heads, vocabulary, vision encoder, precision and the weight mix by dtype, task, languages, popularity, attributed to Hugging Face), the description truncated to four lines with a **Show more** toggle, reasoning (mode, default effort, efforts), capabilities as `Pill`s, benchmarks (Artificial Analysis indices as `Metric`s, the design-arena table, then the curated ones with source and date), status (deprecated + notes) and a footer with the generated part's date. Never shows "n/a": an absent field is an absent block. |
 | `ModelsProvider` / `useModels` | `app/lib/models-context.tsx` | The client's single model list, from `/api/models`. Whatever changes what is offered calls `refresh()`: the Gateway page after a toggle, a key save or removal, or a sync, and the first-run wizard after saving keys. Everything else only reads, PulseChat included. |
 | `WizardPageClient` + step components | `app/wizard/PageClient.tsx` | Multi-step first-run wizard plus its frame shell, with mobile-first CSS. |
 | `useWizard` | `app/wizard/useWizard.ts` | Shared hook: wizard state, step transitions, provider save, restart. Receives server-side initial state to avoid a loading flash. |

package/docs/dev/API-REFERENCE.md

@@ -316,6 +316,38 @@ Rev4a Provider Gateway — proxy chat completions to the correct upstream.
 
 ---
 
+### `GET /api/models/details?id=<model id>`
+Everything the details modal shows for one model, and nothing more: fields the sources do
+not have are **absent**, never `null` and never a guess.
+
+**Auth:** browser cookie or bearer token
+
+**Response:**
+```json
+{
+  "id": "glm/glm-5.3-flash", "name": "GLM-5.3 Flash", "provider": "glm",
+  "modality": "text+image+video->text", "enabled": false, "deprecated": false,
+  "price": { "input": 0.15, "output": 0.5, "source": "vendor" },
+  "details": { "description": "…", "created": "2026-08-26", "context": 1310720,
+               "providerContext": 1048576, "maxOutput": 943718,
+               "reasoning": { "mandatory": true, "default_effort": "max", "supported_efforts": ["max","high","low"] },
+               "supportedParameters": ["tools","reasoning","…"],
+               "benchmarks": { "design_arena": [ … ], "artificial_analysis": { … } },
+               "huggingFaceId": "zai-org/GLM-5.3-Flash", "url": "https://openrouter.ai/…" },
+  "info": null,
+  "asOf": "2026-09-23T14:02:40.271Z",
+  "detailsSource": "openrouter"
+}
+```
+
+`price.source` is `openrouter` for an `openrouter/*` entry and `vendor` for a direct one,
+which keeps prices honest: the refresh script never writes a vendor price. `details` comes
+from the generated `model-details.json` (`npm run refresh:pricing`, see
+`docs/dev/GATEWAY.md`), `info` from the catalogue's hand-written block, and `asOf` is when
+the generated part was produced. An id the catalogue does not carry answers `404`.
+
+**Errors:** `400` missing `id`, `404` unknown model.
+
 ### `GET /api/models`
 Models eligible to be used: the catalogue filtered down to models that are enabled
 (after overrides) and whose provider has a key configured, grouped by provider. Feeds the model pickers in the agent's
@@ -2564,8 +2596,11 @@ from local state only.
 
 **Response:** `{ "installed": "1.4.2", "latest": "1.5.0", "updateAvailable": true, "package": "@flame0510/project-aether", "log": "update.log" }`
 
-`log` is the file name, in the Rev4a data directory, where the update's output is
-written.
+`installed` is `null` when `package.json` cannot be read — during an update npm rewrites
+it, and a transient failure must not look like a version. With `installed` unknown there
+is nothing to compare, so `latest` is `null` and `updateAvailable` false. `installed` is
+never a placeholder like `0.0.0`. `log` is the file name, in the Rev4a data directory,
+where the update's output is written.
 
 ### `POST /api/update-check`
 Run `rev4a update` as a detached background process. Nothing here restarts anything:

package/docs/dev/GATEWAY.md

@@ -148,6 +148,64 @@ for anyone cloning the project. It defines all known models across all providers
 Only enabled models for providers with a configured API key are synced to agent
 containers.
 
+Provider display names come from `lib/provider-labels.ts`: the Gateway's cards and the
+details modal read the same map, so a provider is never called two things in one page.
+
+### Model details (the details modal)
+
+The Gateway model row has a **⋯ Details** button opening `ModelDetailsModal`
+(`app/gateway/ModelDetailsModal.tsx`), fed by `GET /api/models/details?id=`. Three
+sources, each one labelled in the modal:
+
+| Source | File | Nature |
+|---|---|---|
+| Identity, enabled, modality, deprecation | `models.config.json` | curated by hand |
+| Price | `model-pricing.json` | refreshed for `openrouter/*`, hand for direct vendors |
+| Description, specs, benchmarks | `model-details.json` | **generated**, never hand-edited |
+
+`npm run refresh:pricing` (script `scripts/refresh-model-pricing.mjs`) fetches the
+OpenRouter catalogue once and writes both the prices and `model-details.json`:
+description, release date (`created`), context and the provider's own limit, max output,
+tokenizer, instruct type, knowledge cutoff, Hugging Face id, reasoning (mandatory, default
+and supported efforts), supported parameters, and the benchmarks OpenRouter publishes
+(design arenas with elo/rank/win-rate, Artificial Analysis indices).
+
+**Size and architecture** come from a second source: for every entry with a
+`hugging_face_id` the script asks the Hugging Face API (`safetensors.total` and the
+per-dtype breakdown, the task, the languages, downloads and likes) **and the model's
+`config.json`** — the API's summary config is reduced, the raw file is what carries the
+architecture. That covers the **open-weight** models (DeepSeek, GLM, Kimi, Qwen, Llama,
+StepFun…); a closed model has no card, so it gets no `params` and no `hf` block, and the
+modal hides those rows rather than estimating. `--no-hf` skips the lookups.
+
+Stored per model in an `hf` object: the architecture class and type, the mixture of
+experts (`experts`, per token, shared), layers, hidden size, attention heads (and KV
+heads, since MQA/GQA change what serving costs), vocabulary, the model's own max context,
+whether it has a **vision encoder** (multimodal models nest their language model under
+`text_config` and the encoder under `vision_config`), the precision (`fp8`,
+`compressed-tensors`…) and the weight mix by dtype, the task, the languages and the
+popularity. For a mixture-of-experts model the card's number is the **total**; an *active*
+count is a derivation, so the modal shows the facts (experts, per token) and the curated
+`info.params` free text can add the vendor's own "355B total, ~32B active". A direct entry is
+matched through the vendor alias map (`glm` → `z-ai`, `kimi` → `moonshotai`) for the data
+only — **its price stays the vendor's own**, and the modal says which is which.
+
+Anything OpenRouter does not publish is curated in the catalogue as an optional `info`
+block, and every number there carries its source:
+
+```json
+"info": {
+  "params": "~1.8T MoE (active ~40B)",
+  "docUrl": "https://docs.z.ai/guides/vlm/glm-5.3-flash",
+  "knowledgeCutoff": "2026-03",
+  "benchmarks": [ { "name": "SWE-bench Verified", "value": 78.4, "source": "https://…", "asOf": "2026-08-26" } ],
+  "notes": "Native multimodal; 3x the coding-plan quota."
+}
+```
+
+No generated field ever replaces a curated one silently: prices are separate files, and the
+modal shows the generated part's date (`asOf`).
+
 ---
 
 ## Per-agent model assignment

package/lib/memory-context.ts

@@ -124,7 +124,7 @@ function formatBytesForWarning(value: number): string {
 function applyBootstrapSizeWarnings(file: FileSummary): void {
   const limit = BOOTSTRAP_FILE_WARN_BYTES[file.key as BootstrapFileName];
   if (!limit || file.size === null || file.size <= limit) return;
-  file.warnings.push(`${file.key} sopra soglia: ${formatBytesForWarning(file.size)} / ${formatBytesForWarning(limit)}`);
+  file.warnings.push(`${file.key} above threshold: ${formatBytesForWarning(file.size)} / ${formatBytesForWarning(limit)}`);
 }
 
 export function inspectFile(filePath: string, key: string): FileSummary {
@@ -334,7 +334,7 @@ function inspectAgent(seed: AgentSeed): AgentMemorySummary {
 
   summary.strategy = classifyAgent(summary);
   if (bootstrapBytes > WORKSPACE_TOTAL_WARN_BYTES) {
-    summary.warnings.push(`Bootstrap totale sopra budget: ${formatBytesForWarning(bootstrapBytes)} / ${formatBytesForWarning(WORKSPACE_TOTAL_WARN_BYTES)}`);
+    summary.warnings.push(`Bootstrap total above budget: ${formatBytesForWarning(bootstrapBytes)} / ${formatBytesForWarning(WORKSPACE_TOTAL_WARN_BYTES)}`);
   }
   summary.warnings = uniqueStrings(summary.warnings.concat(...Object.values(files).map((file) => file.warnings)));
   return summary;