omp-llm-role 1.0.0 → 1.2.0

package/src/explorer/explain.ts

@@ -6,10 +6,16 @@
  * No I/O: the server (src/explorer/server.ts) owns the HTTP surface and the
  * export write; this module only computes. All ranking math is delegated to
  * src/engine.ts so the numbers on screen are exactly the plugin's numbers.
+ *
+ * The keyed-catalog availability annotation (`key` on rank rows and the eligible
+ * explanation) is a pure overlay computed from an injected `KeyAvailability`
+ * value — no I/O here; the caller owns the fetch.
  */
 
-import { sourceForMetric, type SourceDeclaration } from "../benchmark-sources.ts";
-import { CAPABILITY_FILL, cardinalMetric, paretoFrontier, rankRole, roleLambda, type Model, type Ranked, type RoleDef, type SuffixLevel } from "../engine.ts";
+import { assessFocusMetric, type FocusMetricAssessment } from "../agent-create.ts";
+import { type KeyAvailability } from "../availability.ts";
+import { cachedSourceInfo, sourceForMetric, type SourceDeclaration } from "../benchmark-sources.ts";
+import { autoPinApplies, BENCHMARK_CHANCE, CAPABILITY_FILL, cardinalMetric, endpointFilteredModel, paretoFrontier, pinnedRoute, rankRole, roleLambda, roleMetricValue, roleRoute, routeEffectivePrice, thinkingAdjustedPrice, type Model, type Ranked, type RoleDef, type SuffixLevel } from "../engine.ts";
 import { KNOWN_METRICS } from "../settings.ts";
 
 // ---------------------------------------------------------------------------
@@ -39,6 +45,10 @@ export const METRIC_META: Record<string, MetricMeta> = {
   vision: { label: "Vision index", kind: "index", unit: "index pts", formula: "(v+20)/80", anchors: INDEX_ANCHORS },
   tool_calling: { label: "Tool-calling index", kind: "index", unit: "index pts", formula: "(v+20)/80", anchors: INDEX_ANCHORS },
   long_context: { label: "Long-context index", kind: "index", unit: "index pts", formula: "(v+20)/80", anchors: INDEX_ANCHORS },
+  index_communication: { label: "Communication index", kind: "index", unit: "index pts", formula: "(v+20)/80", anchors: INDEX_ANCHORS },
+  index_finance: { label: "Finance index", kind: "index", unit: "index pts", formula: "(v+20)/80", anchors: INDEX_ANCHORS },
+  index_healthcare: { label: "Healthcare index", kind: "index", unit: "index pts", formula: "(v+20)/80", anchors: INDEX_ANCHORS },
+  index_legal: { label: "Legal index", kind: "index", unit: "index pts", formula: "(v+20)/80", anchors: INDEX_ANCHORS },
   mrcr: { label: "MRCR v2", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
   gpqa: { label: "GPQA", kind: "benchmark", unit: "pass rate", formula: "(v−0.25)/0.75", anchors: "4-way multiple choice, chance 0.25" },
   aime: { label: "AIME 2025", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
@@ -46,6 +56,21 @@ export const METRIC_META: Record<string, MetricMeta> = {
   arc_agi: { label: "ARC-AGI v2", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
   terminal_bench: { label: "Terminal-Bench", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
   tau_bench: { label: "τ-bench (retail)", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  simpleqa_score: { label: "SimpleQA", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  hle_score: { label: "Humanity's Last Exam", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  mmmu_score: { label: "MMMU", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  mmmu_pro_score: { label: "MMMU-Pro", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  mmmlu_score: { label: "MMMLU", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  browsecomp_score: { label: "BrowseComp", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  swe_bench_pro_score: { label: "SWE-bench Pro", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  mcp_atlas_score: { label: "MCP Atlas", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  apex_agents_score: { label: "APEX Agents", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  osworld_score: { label: "OSWorld", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  scicode_score: { label: "SciCode", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  screenspot_pro_score: { label: "ScreenSpot-Pro", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  charxiv_r_score: { label: "CharXiv-R", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  frontiermath_score: { label: "FrontierMath", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
+  toolathlon_score: { label: "Toolathlon", kind: "benchmark", unit: "pass rate", formula: "raw 0-1", anchors: "chance ≈ 0" },
   website: { label: "Design Arena (website)", kind: "percentile", unit: "percentile", formula: "identity (already 0-1)", anchors: "percentile within the design-covered field; models without Design Arena data get the capability fill 0.195" },
   writing: { label: "WritingBench", kind: "percentile", unit: "score 0-1", formula: "identity (already 0-1)", anchors: "WritingBench normalized score (writing leaderboard); models outside the ranking get the capability fill 0.195" },
   price: { label: "Price", kind: "price", unit: "$/M", formula: "billed blend 3:1 in:out, ×(3ρ+1+T)/(3ρ+1) at the role's thinking level", anchors: "OpenRouter standard route" },
@@ -79,6 +104,28 @@ export function metricMetaFor(metrics: readonly string[], declared: readonly Sou
   return out;
 }
 
+/** A role's focus metrics: the weighted benchmarks (kind `benchmark`/`percentile`),
+ * i.e. the metrics a role was ranked on beyond the index/price/throughput
+ * backbone. Shipped roles weight index metrics, so they carry none. */
+export function focusMetricsOf(def: RoleDef, declared: readonly SourceDeclaration[] = []): string[] {
+  return Object.keys(def.weights).filter((metric) => {
+    const kind = metricMeta(metric, declared).kind;
+    return kind === "benchmark" || kind === "percentile";
+  });
+}
+
+/** Nine-axis assessment of each of a role's focus metrics, over the loaded pool
+ * (the same dataset the updater ranks on), with the cached source inputs. */
+export function focusAssessments(
+  models: readonly Model[],
+  def: RoleDef,
+  declared: readonly SourceDeclaration[] = [],
+): Record<string, FocusMetricAssessment> {
+  const out: Record<string, FocusMetricAssessment> = {};
+  for (const metric of focusMetricsOf(def, declared)) out[metric] = assessFocusMetric(models, metric, declared, cachedSourceInfo(metric, declared));
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Rank rows (table data with baseline deltas)
 // ---------------------------------------------------------------------------
@@ -99,6 +146,11 @@ export type RankRow = {
   parts: Record<string, number>;
   /** weighted non-price metrics whose raw value is null (they contribute 0) */
   missing: string[];
+  /** keyed-catalog availability overlay: whether the user's OpenRouter key can
+   * run this model. Orthogonal to `missing` (weighted metrics with no value) and
+   * to the eligibility gates `rankRole` applies; `"unknown"` when the keyed
+   * catalog is inactive or the model is in neither catalog. */
+  key: "usable" | "blocked" | "unknown";
   frontier: boolean;
   rank: number;
   baselineRank: number | null;
@@ -106,9 +158,22 @@ export type RankRow = {
   delta: number | null;
 };
 
+/** The availability overlay verdict for one model id: `"usable"` when the keyed
+ * catalog allows it, `"blocked"` when the public catalog has it but the keyed
+ * one does not, `"unknown"` when the keyed catalog is inactive or the model is
+ * in neither catalog. Pure; no I/O. */
+function keyVerdict(availability: KeyAvailability | undefined, id: string): "usable" | "blocked" | "unknown" {
+  if (availability?.active !== true) return "unknown";
+  if (availability.allowed.has(id)) return "usable";
+  if (availability.blocked.has(id)) return "blocked";
+  return "unknown";
+}
+
 /** Rank `models` under `def`, annotating each row with its rank delta against
- * `baseline` (the effective role's ranking, i.e. what the plugin does today). */
-export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[]): RankRow[] {
+ * `baseline` (the effective role's ranking, i.e. what the plugin does today) and
+ * its keyed-catalog availability overlay. Ranking order, deltas, and every other
+ * field are unaffected by `availability`. */
+export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[], availability?: KeyAvailability): RankRow[] {
   const ranked = rankRole(def, models);
   const frontier = paretoFrontier(ranked);
   const baselineRank = new Map<string, number>();
@@ -123,13 +188,14 @@ export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[]): Ran
       org: r.model.org,
       price: r.model.price,
       priceEff: r.priceEff,
-      throughput: r.model.throughput,
+      throughput: roleMetricValue(r.model, "throughput", roleRoute(r.model, def)),
       context: r.model.context,
       multimodal: r.model.multimodal,
       value: r.value,
       q: r.q,
       parts: r.parts,
       missing: weightedNonPrice.filter((k) => r.model.metrics[k] == null),
+      key: keyVerdict(availability, r.model.id),
       frontier: frontier.has(r.model.id),
       rank,
       baselineRank: b,
@@ -151,6 +217,8 @@ export function inverseCardinal(metric: string, t: number): number | null {
     if (t < 0 || t > 1) return null; // forward clamps to [0,1]; outside is unreachable
     return 10 * 30 ** t;
   }
+  const chance = BENCHMARK_CHANCE[metric];
+  if (chance !== undefined) return t * (1 - chance) + chance;
   return t; // benchmark (mrcr), percentile (website) and price: identity
 }
 
@@ -186,12 +254,25 @@ export type Explanation =
   | {
       eligible: true;
       model: { id: string; name: string; org: string };
+      /** keyed-catalog availability overlay (see `RankRow.key`) */
+      key: "usable" | "blocked" | "unknown";
+      /** why the overlay reads as it does: the injected availability reason, or
+       * `"unavailable"` when no availability value was supplied */
+      keyReason: KeyAvailability["reason"];
       rank: number;
       total: number;
       value: number;
       q: number;
       priceEff: number;
-      role: { name: string; lambda: number; derivedLambda: number; wPrice: number; qW: number; thinking: SuffixLevel | undefined };
+      /** true when the model was priced on the soft best route (the
+       * `preferOwnProvider` preference, no hard pin) rather than the 1/price²
+       * blend — the panel shows WHY the price is what it is. */
+      ownProvider: boolean;
+      /** the automatic pin: the model's best route's provider slug when the role
+       * prefers a bound route and carries no manual pin, else null. Read-only in
+       * the UI; a manual `providerPin` overrides it. */
+      autoPin: string | null;
+      role: { name: string; lambda: number; derivedLambda: number; wPrice: number; qW: number; thinking: SuffixLevel | undefined; cacheHitRate: number };
       contributions: Contribution[];
       cost: { priceEff: number; billedPrice: number; lambda: number; penalty: number; q: number; value: number };
       gapAbove: number | null;
@@ -202,16 +283,46 @@ export type Explanation =
     };
 
 /** Full decomposition of one model's rank for a role, or the eligibility gates it
- * failed (same gates `rankRole` applies, listed in the same order). */
-export function explainModel(def: RoleDef, models: Model[], modelId: string, roleName = ""): Explanation {
+ * failed (same gates `rankRole` applies, listed in the same order). The eligible
+ * branch also carries the keyed-catalog availability overlay (`key`/`keyReason`). */
+export function explainModel(def: RoleDef, models: Model[], modelId: string, roleName = "", availability?: KeyAvailability): Explanation {
   const model = models.find((m) => m.id === modelId);
   if (!model) return { eligible: false, reasons: ["model not found in today's dataset"] };
 
   const reasons: string[] = [];
-  const missingRequired = def.required.filter((k) => model.metrics[k] == null);
+  // A pinned role prices and gates on the model's matching route (mirrors rankRole).
+  const pinRoute = pinnedRoute(model, def.providerPin);
+  // A role with endpoint filters is priced on the blend over the routes that survive
+  // them, with its cache-hit rate blended into each route's billed price: `em` is the
+  // model with that effective price/throughput, or null when no route survives.
+  const cacheHitRate = def.cacheHitRate ?? 0;
+  const em = endpointFilteredModel(model, def.filters, cacheHitRate);
+  const eff = em ?? model;
+  // Soft best-route preference (mirrors rankRole): with no hard pin, a role that
+  // prefers a bound route is priced on the model's best route by the role's own
+  // value, else on the blend. Never a gate — a model with no candidate route keeps
+  // the blend.
+  const route = roleRoute(model, def);
+  // The model is priced on the soft best route (not a hard pin, not the blend).
+  const ownProvider = pinRoute === null && route !== null;
+  // The automatic pin the updater would write: the model's best route's slug,
+  // only when the role prefers a bound route and carries no manual pin. Reuses the
+  // already-computed `route` (the same best route) instead of recomputing it.
+  const autoPin = autoPinApplies(def) ? route?.providerSlug ?? null : null;
+  const missingRequired = def.required.filter((k) => roleMetricValue(eff, k, pinRoute, cacheHitRate) == null);
   if (missingRequired.length > 0) reasons.push(`missing required metric(s): ${missingRequired.join(", ")}`);
   if (def.filters?.image && !model.multimodal) reasons.push("role requires image input; model is text-only");
-  if (model.price == null) reasons.push("no billed OpenRouter route");
+  if (def.providerPin !== undefined && pinRoute === null) reasons.push("no route matches the role's provider pin");
+  if (em === null) reasons.push("no standard-tier route satisfies the role's endpoint filters");
+  if (eff.price == null) reasons.push("no billed OpenRouter route");
+  // maxPriceUsdPerM caps the model's own price basis, never the soft best-route
+  // basis (mirrors rankRole): with no hard pin the gate uses the blend price, so
+  // the soft basis cannot change eligibility; a hard pin gates its route price.
+  const cap = def.filters?.maxPriceUsdPerM ?? 0;
+  if (cap > 0) {
+    const capBase = pinRoute !== null ? routeEffectivePrice(pinRoute, cacheHitRate) : eff.price;
+    if (capBase != null && thinkingAdjustedPrice(eff, def, capBase) > cap) reasons.push(`price exceeds the role's maxPriceUsdPerM cap (${cap})`);
+  }
   if (reasons.length > 0) return { eligible: false, reasons };
 
   const ranked = rankRole(def, models);
@@ -228,7 +339,7 @@ export function explainModel(def: RoleDef, models: Model[], modelId: string, rol
   const contributions: Contribution[] = [];
   for (const [metric, w] of Object.entries(def.weights)) {
     if (metric === "price") continue; // cost enters as the λ·$ penalty, not the blend
-    const stored = model.metrics[metric] ?? null;
+    const stored = roleMetricValue(eff, metric, route, cacheHitRate) ?? null;
     // Mirror rankRole: a sparse capability metric with no data scores at
     // CAPABILITY_FILL *as a cardinal value* (no transform), not 0 — otherwise
     // the parts would not sum to q.
@@ -301,14 +412,18 @@ export function explainModel(def: RoleDef, models: Model[], modelId: string, rol
   return {
     eligible: true,
     model: { id: model.id, name: model.name, org: model.org },
+    key: keyVerdict(availability, model.id),
+    keyReason: availability?.reason ?? "unavailable",
     rank,
     total,
     value: self.value,
     q: self.q,
     priceEff: self.priceEff,
-    role: { name: roleName, lambda, derivedLambda, wPrice, qW, thinking: def.thinking },
+    ownProvider,
+    autoPin,
+    role: { name: roleName, lambda, derivedLambda, wPrice, qW, thinking: def.thinking, cacheHitRate },
     contributions,
-    cost: { priceEff: self.priceEff, billedPrice: model.price, lambda, penalty: lambda * self.priceEff, q: self.q, value: self.value },
+    cost: { priceEff: self.priceEff, billedPrice: route !== null ? routeEffectivePrice(route, cacheHitRate) ?? eff.price : eff.price, lambda, penalty: lambda * self.priceEff, q: self.q, value: self.value },
     gapAbove,
     gapToTop,
     above,

package/src/explorer/scopes.ts

@@ -0,0 +1,110 @@
+/**
+ * Explorer scopes: a scope is a role-config source — the user-level lock file,
+ * or one project where `/project-roles` was used. Resolution lives here (not in
+ * the HTTP layer) so the boot path and the dataset union cannot drift, and the
+ * per-scope read mirrors the updater's exactly (project lock merged over the
+ * user-level lock), so the explorer and the plugin agree.
+ */
+
+import { existsSync } from "node:fs";
+import type { RoleDef } from "../engine.ts";
+import { readProjectRegistry } from "../project-registry.ts";
+import { PLUGIN_SETTINGS_PATH, projectLockPath, readPluginSettingsMap, resolveSettings, roleUniverse, type UniverseEntry } from "../settings.ts";
+
+export type ScopeKind = "user" | "project";
+
+export type Scope = {
+  /** Stable across requests: `user`, or `project:<root>`. */
+  id: string;
+  /** Human label: `user-level`, or the project root path. */
+  label: string;
+  kind: ScopeKind;
+  /** The lock file this scope reads and Export writes. */
+  lockPath: string;
+  /** Whether the lock file exists (the user scope is always available). */
+  present: boolean;
+  /** Project root (project scopes only). */
+  root?: string;
+};
+
+export type ScopeInputs = {
+  /** The user-level lock file (the user scope's read/export target). */
+  userLockPath?: string;
+  /** Session cwd; its project joins the list when it has a project role config. */
+  cwd: string;
+  /** Agent dir holding the project registry (default: `agentDir()`). */
+  registryDir?: string;
+};
+
+function projectScope(root: string): Scope {
+  const lockPath = projectLockPath(root);
+  return { id: `project:${root}`, label: root, kind: "project", lockPath, present: existsSync(lockPath), root };
+}
+
+/**
+ * Every known scope: the user-level scope, the registry's projects (most
+ * recently used first), and the session's project when it has a project role
+ * config — included immediately, before the registry has recorded it.
+ *
+ * The session-project test is the updater's own `resolveProjectDir` test (a
+ * project lock with a non-empty `omp-llm-role` settings entry), so the
+ * explorer's "session project" and the updater's project mode agree.
+ */
+export function resolveScopes(inputs: ScopeInputs): Scope[] {
+  const userLockPath = inputs.userLockPath ?? PLUGIN_SETTINGS_PATH;
+  const byId = new Map<string, Scope>();
+  // The user-level scope is always available: Export creates the lock file.
+  byId.set("user", { id: "user", label: "user-level", kind: "user", lockPath: userLockPath, present: true });
+  const entries = [...readProjectRegistry(inputs.registryDir)].sort((a, b) => (a.lastUsed < b.lastUsed ? 1 : a.lastUsed > b.lastUsed ? -1 : 0));
+  for (const entry of entries) {
+    const scope = projectScope(entry.root);
+    if (!byId.has(scope.id)) byId.set(scope.id, scope);
+  }
+  if (Object.keys(readPluginSettingsMap({ global: projectLockPath(inputs.cwd), project: null })).length > 0) {
+    const scope = projectScope(inputs.cwd);
+    if (!byId.has(scope.id)) byId.set(scope.id, scope);
+  }
+  return [...byId.values()];
+}
+
+/** The default active scope: the session's project when present, else user-level. */
+export function defaultScopeId(scopes: Scope[], cwd: string): string {
+  const project = scopes.find((s) => s.kind === "project" && s.root === cwd && s.present);
+  if (project) return project.id;
+  return scopes.find((s) => s.kind === "user")?.id ?? scopes[0]?.id ?? "user";
+}
+
+/** The scope a request should use: the requested id when known and present,
+ * else the default. */
+export function resolveScope(scopes: Scope[], requestedId: string | null, cwd: string): Scope {
+  const found = requestedId === null ? undefined : scopes.find((s) => s.id === requestedId && s.present);
+  if (found) return found;
+  const fallback = defaultScopeId(scopes, cwd);
+  return scopes.find((s) => s.id === fallback) ?? scopes[0];
+}
+
+/** Read one scope's roles and universe. A project scope merges the project lock
+ * over the user-level lock — the exact read the updater performs.
+ *
+ * `roles` is the EFFECTIVE def (the authored def with the enabled capability
+ * flags' recommended knobs filled in); `universe[role].def` is the AUTHORED def
+ * (flags + explicit keys only) — the def the explorer edits and exports.
+ * `features` is the scope's GLOBAL capability flags (`features.<id>`), which the
+ * explorer's rank/explain handlers expand a posted def with so the preview
+ * matches the resolved baseline. */
+export function readScopeRoles(scope: Scope, userLockPath: string): { roles: Record<string, RoleDef>; universe: Record<string, UniverseEntry>; features: Record<string, boolean>; errors: string[] } {
+  const raw = scope.kind === "user"
+    ? readPluginSettingsMap({ global: scope.lockPath, project: null })
+    : readPluginSettingsMap({ global: userLockPath, project: scope.lockPath });
+  const { settings, errors } = resolveSettings(raw);
+  return { roles: settings.roles, universe: roleUniverse(raw, settings.roles), features: settings.features, errors };
+}
+
+/** The union of every known scope's resolved roles — the roles map the ranking
+ * loader must receive so a metric only one scope weights (e.g. a project-only
+ * declared `bench:<id>`) is fetched, keeping a scope switch free. */
+export function unionRoles(scopes: Scope[], userLockPath: string): Record<string, RoleDef> {
+  const out: Record<string, RoleDef> = {};
+  for (const scope of scopes) Object.assign(out, readScopeRoles(scope, userLockPath).roles);
+  return out;
+}

package/src/explorer/server.ts

@@ -4,10 +4,17 @@
  *
  *   GET  /                 -> web/index.html
  *   GET  /app.js /style.css -> static assets (traversal-guarded)
- *   GET  /api/bootstrap    -> roles, defaults, metric universe, dataset counts
- *   POST /api/rank         -> { role, def } -> rows with baseline deltas
+ *   GET  /api/bootstrap    -> the scope list + the active scope's roles,
+ *                             defaults, metric universe, dataset counts, the
+ *                             key-availability summary, the scope's global
+ *                             capability flags, and the feature registry
+ *   POST /api/scope        -> { scope } -> switch the active scope, return the
+ *                             new bootstrap payload
+ *   POST /api/rank         -> { role, def } -> rows with baseline deltas and a
+ *                             per-row `key` badge (usable/blocked/unknown)
  *   POST /api/explain      -> { role, def, modelId } -> full decomposition
- *   POST /api/export       -> { roles } -> validated, backed-up lock-file write
+ *   POST /api/export       -> { roles } -> validated, backed-up write of the
+ *                             active scope's lock file
  *   POST /api/refresh      -> refetch the dataset, return the bootstrap payload
  *
  * Bound to loopback by the caller; no auth. Every handler is
@@ -17,32 +24,50 @@
 import { readFileSync } from "node:fs";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { extname, resolve, sep } from "node:path";
+import type { KeyAvailability } from "../availability.ts";
 import { loadDeclaredSources } from "../benchmark-sources.ts";
-import { SUFFIX_LEVELS, rankRole, roleLambda, thinkingPriceFactor, type RankData, type RoleDef, type SuffixLevel } from "../engine.ts";
+import { pinnedRoute, SUFFIX_LEVELS, rankRole, roleLambda, thinkingPriceFactor, type RankData, type RoleDef, type SuffixLevel } from "../engine.ts";
+import { expandFeatures, FEATURES } from "../features.ts";
 import { isRecord } from "../guards.ts";
 import { validateRole, writeRoleSettings } from "../role-settings.ts";
 import { KNOWN_METRICS, type UniverseEntry } from "../settings.ts";
-import { explainModel, metricMetaFor, rankRows, weightableMetrics } from "./explain.ts";
+import { explainModel, focusAssessments, metricMetaFor, rankRows, weightableMetrics } from "./explain.ts";
+import type { Scope } from "./scopes.ts";
 
 export type ExplorerOpts = {
   webDir: string;
-  lockPath: string;
+  /** All known scopes, re-resolved per call so a project registered by another
+   *  session appears without a restart. */
+  listScopes(): Scope[];
+  /** The scope a request should use: the requested id when known and present,
+   *  else the default (session project when present, else user-level). */
+  resolveScope(requestedId: string | null): Scope;
   /**
-   * Fresh state per call: `rank` (swapped by `refresh`) plus `roles`/`universe`
-   * re-read from the lock file, so a page reload after Export reflects the write
-   * instead of a boot-time snapshot.
+   * Fresh state for one scope: `rank` (swapped by `refresh`) plus
+   * `roles`/`universe` re-read from that scope's lock file, so a page reload
+   * after Export reflects the write instead of a boot-time snapshot.
+   * `availability` is the key-usable/key-blocked overlay derived from the
+   * OpenRouter keyed catalog (re-derived on refresh).
    */
-  getState(): {
+  getState(scope: Scope): {
     rank: RankData;
     roles: Record<string, RoleDef>;
     /** Every known role (disabled included) with kind/enabled/locked + effective def. */
     universe: Record<string, UniverseEntry>;
     defaults: Record<string, RoleDef>;
+    availability: KeyAvailability;
+    /** The scope's GLOBAL capability flags (`features.<id>`); a posted def is
+     *  expanded with these before ranking so the preview matches the resolved
+     *  baseline. Defaults to `{}` when a host omits it. */
+    features: Record<string, boolean>;
   };
   /** Re-runs loadRankData({ refresh: true }) and swaps the snapshot. */
   refresh(): Promise<void>;
 };
 
+/** Per-server mutable state: the active scope id (null = the default scope). */
+type ExplorerSession = { activeScopeId: string | null };
+
 const MIME: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -124,8 +149,16 @@ function thinkingFactors(): Record<string, number> {
   return out;
 }
 
-function bootstrapPayload(opts: ExplorerOpts): object {
-  const state = opts.getState();
+/** The scope a request should use, persisting the fallback so a scope that
+ * became unavailable does not keep re-resolving to the default. */
+function activeScope(opts: ExplorerOpts, session: ExplorerSession): Scope {
+  const scope = opts.resolveScope(session.activeScopeId);
+  session.activeScopeId = scope.id;
+  return scope;
+}
+
+function bootstrapPayload(opts: ExplorerOpts, scope: Scope): object {
+  const state = opts.getState(scope);
   // The metric universe the UI may weight: the shipped keys plus any external
   // metric a resolved role weights, with a derived metadata entry for each.
   const external = new Set<string>();
@@ -133,64 +166,119 @@ function bootstrapPayload(opts: ExplorerOpts): object {
     for (const metric of Object.keys(def.weights)) if (!(metric in KNOWN_METRICS)) external.add(metric);
   }
   const metrics = weightableMetrics([...external]);
+  const declared = loadDeclaredSources();
+  // Five-axis assessment of each role's focus metrics, over the same resolved
+  // dataset the updater ranks on (so the explorer and the updater agree).
+  const focus = Object.fromEntries(
+    Object.entries(state.roles).map(([role, def]) => [role, focusAssessments(state.rank.models, def, declared)]),
+  );
   return {
     roles: state.roles,
     defaults: state.defaults,
     universe: state.universe,
+    // The scope's global capability flags + the registry, so the SPA renders the
+    // Features panel and the recommended bundles without duplicating them.
+    features: state.features ?? {},
+    featureRegistry: FEATURES.map((f) => ({ id: f.id, label: f.label, description: f.description, buys: f.buys, recommended: f.recommended })),
     metrics,
-    metricMeta: metricMetaFor(metrics, loadDeclaredSources()),
+    metricMeta: metricMetaFor(metrics, declared),
+    focusAssessments: focus,
     levels: Object.keys(SUFFIX_LEVELS),
     thinkingFactors: thinkingFactors(),
     fetchedAt: state.rank.fetchedAt,
     modelCount: state.rank.models.length,
     orMatched: state.rank.orMatched,
     orPriced: state.rank.orPriced,
-    lockPath: opts.lockPath,
+    availability: {
+      active: state.availability.active,
+      reason: state.availability.reason,
+      publicCount: state.availability.publicCount,
+      keyedCount: state.availability.keyedCount,
+      blockedCount: state.availability.blocked.size,
+      fetchedAt: state.availability.fetchedAt,
+    },
+    lockPath: scope.lockPath,
+    scopes: opts.listScopes().map((s) => ({ id: s.id, label: s.label, kind: s.kind, present: s.present })),
+    activeScope: scope.id,
   };
 }
 
-async function handleRank(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts): Promise<void> {
+async function handleScope(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts, session: ExplorerSession): Promise<void> {
+  const body = await readJson(req);
+  if (!isRecord(body) || typeof body.scope !== "string") throw new HttpError(400, "expected { scope: string }");
+  const scope = opts.listScopes().find((s) => s.id === body.scope);
+  if (scope === undefined) throw new HttpError(404, `unknown scope: ${body.scope}`);
+  if (!scope.present) throw new HttpError(409, `scope unavailable: ${body.scope}`);
+  session.activeScopeId = scope.id;
+  sendJson(res, 200, bootstrapPayload(opts, scope));
+}
+
+async function handleRank(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts, session: ExplorerSession): Promise<void> {
   const body = await readJson(req);
   if (!isRecord(body) || typeof body.role !== "string" || !isRecord(body.def)) {
     throw new HttpError(400, "expected { role: string, def: object }");
   }
   const role = body.role;
-  const def = body.def as unknown as RoleDef;
-  const state = opts.getState();
+  const authored = body.def as unknown as RoleDef;
+  const state = opts.getState(activeScope(opts, session));
+  // The posted def is AUTHORED (flags + explicit keys); expand it with the
+  // scope's global flags so the preview matches the resolved baseline
+  // (`state.roles[role]`) — otherwise every row's Δ would be a lie.
+  const def = expandFeatures(authored, state.features ?? {});
   // Enabled roles baseline against their resolved def; a disabled or lock-file-only
   // role against its effective def (shipped defaults merged with its overrides) so
   // selecting it still shows deltas, not an empty baseline.
   const baselineDef = state.roles[role] ?? state.universe[role]?.def ?? state.defaults[role];
   const baseline = baselineDef ? rankRole(baselineDef, state.rank.models) : [];
-  const rows = rankRows(def, state.rank.models, baseline);
+  const rows = rankRows(def, state.rank.models, baseline, state.availability);
   sendJson(res, 200, {
     eligible: rows.length,
     lambda: roleLambda(def),
     derivedLambda: roleLambda({ ...def, lambda: undefined }),
     rows,
-    errors: validateRole(role, def),
+    // Validate the AUTHORED def: an unknown feature id must surface here, and
+    // `expandFeatures` strips `features` (validating the expanded def would hide it).
+    errors: validateRole(role, authored),
   });
 }
 
-async function handleExplain(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts): Promise<void> {
+async function handleExplain(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts, session: ExplorerSession): Promise<void> {
   const body = await readJson(req);
   if (!isRecord(body) || typeof body.role !== "string" || !isRecord(body.def) || typeof body.modelId !== "string") {
     throw new HttpError(400, "expected { role: string, def: object, modelId: string }");
   }
-  const def = body.def as unknown as RoleDef;
-  const explanation = explainModel(def, opts.getState().rank.models, body.modelId, body.role);
-  sendJson(res, 200, { ...explanation, errors: validateRole(body.role, def) });
+  const authored = body.def as unknown as RoleDef;
+  const state = opts.getState(activeScope(opts, session));
+  // Same expansion as handleRank: the posted def is authored, the baseline is
+  // resolved, so the preview must apply the scope's global flags first.
+  const def = expandFeatures(authored, state.features ?? {});
+  const explanation = explainModel(def, state.rank.models, body.modelId, body.role, state.availability);
+  sendJson(res, 200, { ...explanation, errors: validateRole(body.role, authored) });
 }
 
-async function handleExport(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts): Promise<void> {
+async function handleExport(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts, session: ExplorerSession): Promise<void> {
   const body = await readJson(req);
   if (!isRecord(body) || !isRecord(body.roles)) throw new HttpError(400, "expected { roles: object }");
-  const result = writeRoleSettings(opts.lockPath, body.roles as unknown as Record<string, RoleDef>);
+  const scope = activeScope(opts, session);
+  const dirty = body.roles as unknown as Record<string, RoleDef>;
+  // A manual provider pin must name a route the loaded dataset actually has, or
+  // the exported role would be unroutable. Validate before any write; the
+  // plugin's own validator (empty/@/:) still runs, so both error sets surface.
+  const state = opts.getState(scope);
+  const errors: string[] = [];
+  for (const [name, def] of Object.entries(dirty)) {
+    errors.push(...validateRole(name, def));
+    if (def.providerPin === undefined) continue;
+    const known = state.rank.models.some((m) => pinnedRoute(m, def.providerPin) !== null);
+    if (!known) errors.push(`role "${name}": provider pin "${def.providerPin}" matches no route in the loaded dataset`);
+  }
+  if (errors.length > 0) return sendJson(res, 200, { ok: false, errors });
+  const result = writeRoleSettings(scope.lockPath, dirty);
   if (!result.ok) return sendJson(res, 200, { ok: false, errors: result.errors });
-  sendJson(res, 200, { ok: true, backupPath: result.backupPath, roles: result.roles });
+  sendJson(res, 200, { ok: true, backupPath: result.backupPath, roles: result.roles, lockPath: scope.lockPath });
 }
 
-async function handle(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts): Promise<void> {
+async function handle(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts, session: ExplorerSession): Promise<void> {
   const url = new URL(req.url ?? "/", "http://127.0.0.1");
   const path = url.pathname;
   const method = req.method ?? "GET";
@@ -198,24 +286,28 @@ async function handle(req: IncomingMessage, res: ServerResponse, opts: ExplorerO
   if (path.startsWith("/api/")) {
     if (path === "/api/bootstrap") {
       if (method !== "GET") return sendText(res, 405, "method not allowed");
-      return sendJson(res, 200, bootstrapPayload(opts));
+      return sendJson(res, 200, bootstrapPayload(opts, activeScope(opts, session)));
+    }
+    if (path === "/api/scope") {
+      if (method !== "POST") return sendText(res, 405, "method not allowed");
+      return handleScope(req, res, opts, session);
     }
     if (path === "/api/rank") {
       if (method !== "POST") return sendText(res, 405, "method not allowed");
-      return handleRank(req, res, opts);
+      return handleRank(req, res, opts, session);
     }
     if (path === "/api/explain") {
       if (method !== "POST") return sendText(res, 405, "method not allowed");
-      return handleExplain(req, res, opts);
+      return handleExplain(req, res, opts, session);
     }
     if (path === "/api/export") {
       if (method !== "POST") return sendText(res, 405, "method not allowed");
-      return handleExport(req, res, opts);
+      return handleExport(req, res, opts, session);
     }
     if (path === "/api/refresh") {
       if (method !== "POST") return sendText(res, 405, "method not allowed");
       await opts.refresh();
-      return sendJson(res, 200, bootstrapPayload(opts));
+      return sendJson(res, 200, bootstrapPayload(opts, activeScope(opts, session)));
     }
     return sendText(res, 404, "not found");
   }
@@ -225,8 +317,9 @@ async function handle(req: IncomingMessage, res: ServerResponse, opts: ExplorerO
 }
 
 export function createExplorerServer(opts: ExplorerOpts): Server {
+  const session: ExplorerSession = { activeScopeId: null };
   return createServer((req, res) => {
-    handle(req, res, opts).catch((err: unknown) => {
+    handle(req, res, opts, session).catch((err: unknown) => {
       if (res.headersSent) {
         res.end();
         return;