docs: document model list runtime comments

src/commands/models/list.model-row.ts

@@ -1,7 +1,9 @@
+/** Converts registry/catalog models into printable model-list rows. */
 import { modelKey } from "../../agents/model-ref-shared.js";
 import { isLocalBaseUrl } from "./list.local-url.js";
 import type { ModelRow } from "./list.types.js";
 
+/** Minimal model shape needed to render a model-list row. */
 export type ListRowModel = {
   id: string;
   name: string;
@@ -12,8 +14,10 @@ export type ListRowModel = {
   contextTokens?: number | null;
 };
 
+/** Provider-auth predicate used when model-level availability is unavailable. */
 export type ModelAuthAvailabilityResolver = (provider: string) => boolean;
 
+/** Builds a display row, preserving configured tags and alias metadata. */
 export function toModelRow(params: {
   model?: ListRowModel;
   key: string;

src/commands/models/list.probe.ts

@@ -1,3 +1,4 @@
+/** Auth probe planning and execution helpers for model diagnostics. */
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
@@ -46,6 +47,7 @@ function loadEmbeddedRunnerModule() {
   return embeddedRunnerModuleLoader.load();
 }
 
+/** Normalized probe status bucket for auth/model diagnostics. */
 export type AuthProbeStatus =
   | "ok"
   | "auth"
@@ -56,6 +58,7 @@ export type AuthProbeStatus =
   | "unknown"
   | "no_model";
 
+/** Reason code for probes that never reached a model call. */
 export type AuthProbeReasonCode =
   | "excluded_by_auth_order"
   | "missing_credential"
@@ -65,6 +68,7 @@ export type AuthProbeReasonCode =
   | "ineligible_profile"
   | "no_model";
 
+/** Result for one profile/env/models.json auth probe target. */
 export type AuthProbeResult = {
   provider: string;
   model?: string;
@@ -87,6 +91,7 @@ type AuthProbeTarget = {
   mode?: string;
 };
 
+/** Summary for a full auth probe run. */
 export type AuthProbeSummary = {
   startedAt: number;
   finishedAt: number;
@@ -102,6 +107,7 @@ export type AuthProbeSummary = {
   results: AuthProbeResult[];
 };
 
+/** Runtime options controlling provider/profile filtering and probe cost. */
 export type AuthProbeOptions = {
   provider?: string;
   profileIds?: string[];
@@ -110,6 +116,7 @@ export type AuthProbeOptions = {
   maxTokens: number;
 };
 
+/** Maps runtime failover reasons into stable auth probe status buckets. */
 export function mapFailoverReasonToProbeStatus(reason?: string | null): AuthProbeStatus {
   if (!reason) {
     return "unknown";
@@ -285,6 +292,7 @@ async function maybeResolveUnresolvedRefIssue(params: {
   }
 }
 
+/** Builds probe targets plus preflight failures for missing/invalid credentials. */
 export async function buildProbeTargets(params: {
   cfg: OpenClawConfig;
   agentDir?: string;
@@ -334,6 +342,8 @@ export async function buildProbeTargets(params: {
       explicitOrder && explicitOrder.length > 0
         ? new Set(resolveAuthProfileOrder({ cfg, store, provider: providerKey }))
         : null;
+    // Explicit auth.order both selects and documents profile eligibility; report
+    // excluded profiles instead of silently skipping them.
     const filteredProfiles = profileFilter.size
       ? profileIds.filter((id) => profileFilter.has(id))
       : profileIds;
@@ -605,6 +615,7 @@ async function runTargetsWithConcurrency(params: {
   return results.filter((entry): entry is AuthProbeResult => Boolean(entry));
 }
 
+/** Runs all auth probes with bounded concurrency and returns a summary. */
 export async function runAuthProbes(params: {
   cfg: OpenClawConfig;
   agentId?: string;
@@ -654,6 +665,7 @@ export async function runAuthProbes(params: {
   };
 }
 
+/** Formats probe latency for table output. */
 export function formatProbeLatency(latencyMs?: number | null) {
   if (!latencyMs && latencyMs !== 0) {
     return "-";
@@ -661,6 +673,7 @@ export function formatProbeLatency(latencyMs?: number | null) {
   return formatMs(latencyMs);
 }
 
+/** Groups probe results by provider. */
 export function groupProbeResults(results: AuthProbeResult[]): Map<string, AuthProbeResult[]> {
   const map = new Map<string, AuthProbeResult[]>();
   for (const result of results) {
@@ -671,6 +684,7 @@ export function groupProbeResults(results: AuthProbeResult[]): Map<string, AuthP
   return map;
 }
 
+/** Sorts probe results by provider and display label. */
 export function sortProbeResults(results: AuthProbeResult[]): AuthProbeResult[] {
   return results.slice().toSorted((a, b) => {
     const provider = a.provider.localeCompare(b.provider);
@@ -683,6 +697,7 @@ export function sortProbeResults(results: AuthProbeResult[]): AuthProbeResult[]
   });
 }
 
+/** Produces the terse completion line for auth probe output. */
 export function describeProbeSummary(summary: AuthProbeSummary): string {
   if (summary.totalTargets === 0) {
     return "No probe targets.";

src/commands/models/list.provider-catalog.ts

@@ -1,3 +1,4 @@
+/** Provider plugin catalog loading for model-list output. */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { loadAuthProfileStoreWithoutExternalProfiles } from "../../agents/auth-profiles/store.js";
@@ -106,6 +107,7 @@ function resolveInstalledIndexPluginIdsForProviderFilter(params: {
   return disabledPluginIds.length > 0 ? [] : undefined;
 }
 
+/** Resolves plugin ids that can provide catalog rows for a provider filter. */
 export async function resolveProviderCatalogPluginIdsForFilter(params: {
   cfg: OpenClawConfig;
   env?: NodeJS.ProcessEnv;
@@ -124,6 +126,8 @@ export async function resolveProviderCatalogPluginIdsForFilter(params: {
     registryIndex: params.metadataSnapshot?.index ?? params.registryIndex,
   });
   if (installedIndexPluginIds) {
+    // Installed registry metadata is process-stable and knows disabled plugins,
+    // so it wins over broader manifest/contract alias fallbacks.
     return installedIndexPluginIds;
   }
   const manifestPluginIds = resolveOwningPluginIdsForProviderRef({
@@ -144,6 +148,7 @@ export async function resolveProviderCatalogPluginIdsForFilter(params: {
   return undefined;
 }
 
+/** Returns true when a provider filter can be satisfied by a static bundled catalog. */
 export async function hasProviderStaticCatalogForFilter(params: {
   cfg: OpenClawConfig;
   env?: NodeJS.ProcessEnv;
@@ -212,6 +217,7 @@ function modelFromProviderCatalog(params: {
   } as Model;
 }
 
+/** Loads model rows from provider static/runtime catalog hooks for model-list output. */
 export async function loadProviderCatalogModelsForList(params: {
   cfg: OpenClawConfig;
   agentDir: string;

src/commands/models/list.provider-index-catalog.ts

@@ -1,3 +1,4 @@
+/** Provider-index-backed model catalog rows for bundled model-list output. */
 import { normalizeModelCatalogProviderId } from "@openclaw/model-catalog-core/model-catalog-refs";
 import type { NormalizedModelCatalogRow } from "@openclaw/model-catalog-core/model-catalog-types";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
@@ -7,6 +8,7 @@ import {
 } from "../../model-catalog/index.js";
 import { normalizePluginsConfig, resolveEffectiveEnableState } from "../../plugins/config-state.js";
 
+/** Loads enabled bundled provider-index catalog rows, optionally scoped by provider. */
 export function loadProviderIndexCatalogRowsForList(params: {
   providerFilter?: string;
   cfg: OpenClawConfig;

src/commands/models/list.registry-load.ts

@@ -1,3 +1,4 @@
+/** Registry-loading adapters for model-list row construction. */
 import { loadAgentModelRegistry } from "../../agents/model-registry-loader.js";
 import { shouldSuppressBuiltInModel } from "../../agents/model-suppression.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
@@ -7,6 +8,7 @@ import { loadModelRegistry } from "./list.registry.js";
 import type { ConfiguredEntry } from "./list.types.js";
 import { modelKey } from "./shared.js";
 
+/** Loads the full model registry and tracks discovered provider/model keys. */
 export async function loadListModelRegistry(
   cfg: OpenClawConfig,
   opts?: {
@@ -45,6 +47,7 @@ function findConfiguredRegistryModel(params: {
   return model;
 }
 
+/** Loads only configured registry entries and their auth availability. */
 export function loadConfiguredListModelRegistry(
   cfg: OpenClawConfig,
   entries: ConfiguredEntry[],

src/commands/models/list.registry.ts

@@ -1,3 +1,4 @@
+/** Model registry access helpers for `openclaw models list`. */
 import { loadAgentModelRegistry } from "../../agents/model-registry-loader.js";
 import {
   shouldSuppressBuiltInModel,
@@ -84,6 +85,7 @@ function loadAvailableModels(
   }
 }
 
+/** Loads registry models and optional availability keys with suppression applied. */
 export async function loadModelRegistry(
   cfg: OpenClawConfig,
   opts?: {
@@ -137,6 +139,7 @@ export async function loadModelRegistry(
   return { registry, models, availableKeys, availabilityErrorMessage };
 }
 
+/** Compatibility wrapper around the shared model-row builder. */
 export function toModelRow(params: Parameters<typeof toModelRowBase>[0]): ModelRow {
   return toModelRowBase(params);
 }