fix(cli): tell the user when meaning search cannot see the catalog

The on-device index was fetched once and never revalidated: the only
freshness check was two existsSync calls. A move added after that fetch was
invisible to meaning search permanently, not down-ranked but absent from the
candidate set. The registry manifest on the same command carries a 24h TTL,
so the two halves of one feature disagreed about staleness.

The dropped count reported over-coverage only, names the index has that the
registry lacks. Under-coverage was never computed, so the harmless direction
was instrumented and the costly one was silent. Reproduced with an index
truncated to 120 of 168 moves: dropped read 0, perfect health, while 48
moves were unreachable.

Counts under-coverage from the name list the artifact already carries, so no
extra request. Warns only when non-zero, and names the remedy.

The remedy had to be made true: --on-device could not refresh a stale index
because hasLocalVectors short-circuited the fetch. That flag now refetches
when the index is absent or no longer covering.

Two defects the reproduction surfaced. A failed refresh reported the tier
unavailable while the old vectors were still on disk and still ranking. And
the fetch wrote its two files one at a time, so failing between them paired
a new name list with an old matrix, a hard load error rather than stale
data. It now writes both or neither, which matters more once refresh runs on
staleness.

top_score returns, scoped to the on-device tier and set to the score of the
best result actually shown rather than the ranking head, which can describe
a row the caller never received.

Also: scripts/ is now typechecked. It never was, which is how a build script
that crashes after the paid embedding call, and two scripts whose imports do
not resolve at all, went unnoticed. 43 errors fixed, no suppressions.

And the docs stop describing a --smart hosted tier that was deleted, an
item that does not exist, and a registry refresh that cannot fix a stale
vector index.

scripts/backfill-block-previews.ts

@@ -10,7 +10,7 @@
  *   npx tsx scripts/backfill-block-previews.ts --dry-run  # preview changes only
  */
 
-import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readdirSync, readFileSync, writeFileSync, type Dirent } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -44,7 +44,7 @@ function writeManifest(manifestPath: string, manifest: Record<string, unknown>):
 
 function backfillBlocks() {
   const blocksDir = join(registryDir, "blocks");
-  let entries: ReturnType<typeof readdirSync<string>>;
+  let entries: Dirent[];
   try {
     entries = readdirSync(blocksDir, { withFileTypes: true });
   } catch {
@@ -81,7 +81,7 @@ function backfillBlocks() {
 
 function normalizeComponents() {
   const componentsDir = join(registryDir, "components");
-  let entries: ReturnType<typeof readdirSync<string>>;
+  let entries: Dirent[];
   try {
     entries = readdirSync(componentsDir, { withFileTypes: true });
   } catch {

scripts/catalog/build-catalog-artifact.ts

@@ -16,6 +16,7 @@ import {
   buildArtifact,
   manifestBytes,
   movesMissingFromRegistry,
+  parseShelf,
   verifyArtifact,
   type Embedder,
 } from "./catalog-artifact.js";
@@ -112,17 +113,17 @@ async function main(): Promise<void> {
   // the burden of discovering it on the consumer at request time.
   verifyArtifact(built);
 
-  // A move the registry cannot serve ranks well and then cannot be installed,
-  // which looks like a bad search rather than a bad build. Reported, not
-  // fatal: the shelf legitimately leads the registry while moves land.
-  const known = registryNames(arg("registry-index") ?? DEFAULT_REGISTRY_INDEX);
-  if (known === undefined) {
-    console.warn("warning   registry index unreadable; coverage not checked");
+  // What is left to report is the gap, not a defect in the artifact: buildArtifact
+  // already dropped these, so the published catalog never contains a move the
+  // registry cannot serve. Reported, not fatal, because the shelf legitimately
+  // leads the registry while moves land.
+  if (installableNames === undefined) {
+    console.warn("warning   registry index unreadable; published every shelf move unchecked");
   } else {
-    const missing = movesMissingFromRegistry(Object.keys(built.catalog), known);
-    if (missing.length > 0) {
+    const dropped = movesMissingFromRegistry([...parseShelf(shelfText).keys()], installableNames);
+    if (dropped.length > 0) {
       console.warn(
-        `warning   ${missing.length} shelf moves have no registry item: ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ", ..." : ""}`,
+        `warning   ${dropped.length} shelf moves dropped, no registry item: ${dropped.slice(0, 5).join(", ")}${dropped.length > 5 ? ", ..." : ""}`,
       );
     }
   }

scripts/changelog-weekly.ts

@@ -531,7 +531,7 @@ function capitalize(value: string) {
   if (!value) {
     return value;
   }
-  return value[0].toUpperCase() + value.slice(1);
+  return value.charAt(0).toUpperCase() + value.slice(1);
 }
 
 function git(args: string[]) {

scripts/cli-options.ts

@@ -27,7 +27,7 @@ export function parseMappedArgument<
   parsed: Parsed,
   config: ParserConfig<Parsed, ValueKey, BooleanKey>,
 ) {
-  const arg = args[index];
+  const arg = args[index] ?? config.fail(`No argument at index ${index}`);
 
   if (applyInlineValueOption(arg, parsed, config.inlineValueOptions)) {
     return index;

scripts/draft-changelog.ts

@@ -273,12 +273,8 @@ export function parseConventionalSubject(subject: string): ParsedSubject {
     };
   }
 
-  return {
-    type: match[1],
-    scope: match[2],
-    summary: match[4],
-    breaking: match[3] === "!",
-  };
+  const [, type = "other", scope, breaking, summary = subject] = match;
+  return { type, scope, summary, breaking: breaking === "!" };
 }
 
 function extractPrNumber(subject: string) {
@@ -444,7 +440,7 @@ function capitalize(value: string) {
   if (!value) {
     return value;
   }
-  return value[0].toUpperCase() + value.slice(1);
+  return value.charAt(0).toUpperCase() + value.slice(1);
 }
 
 function renderTagsLiteral(tags: string[]) {

scripts/generate-catalog-pages.ts

@@ -234,7 +234,7 @@ function textureGroupsFor(manifest: RegistryItem): TextureGroup[] {
     if (!group || typeof group !== "object") return false;
     if (!("title" in group) || typeof group.title !== "string") return false;
     if (!("items" in group) || !Array.isArray(group.items)) return false;
-    return group.items.every((item) => typeof item === "string");
+    return group.items.every((item: unknown) => typeof item === "string");
   });
 }
 
@@ -403,7 +403,7 @@ function generateTextureAnimationExample(
 function generateTexturePreview(manifest: RegistryItem, textureGroups: TextureGroup[]): string[] {
   const sampleItems = textureGroups
     .map((group) => group.items[0])
-    .filter(Boolean)
+    .filter((item): item is string => Boolean(item))
     .slice(0, 6);
   const lines: string[] = ['<div className="hf-texture-preview-panel">'];
 
@@ -411,8 +411,8 @@ function generateTexturePreview(manifest: RegistryItem, textureGroups: TextureGr
     const maskPath = textureMaskUrlFor(manifest, item);
     lines.push(
       `  <div className="hf-texture-preview-card" style={{ "--mask-url": "url('${maskPath}')" }}>`,
-      `    <div className="hf-texture-preview-label">${textureLabel(item!)}</div>`,
-      `    <div className="hf-texture-preview-shadow"><div className="hf-texture-preview-word">${textureSampleWord(item!)}</div></div>`,
+      `    <div className="hf-texture-preview-label">${textureLabel(item)}</div>`,
+      `    <div className="hf-texture-preview-shadow"><div className="hf-texture-preview-word">${textureSampleWord(item)}</div></div>`,
       "  </div>",
     );
   }

scripts/generate-catalog-previews.ts

@@ -277,20 +277,21 @@ async function prepareProjectDir(item: CatalogItem): Promise<string> {
   return tmpDir;
 }
 
+/** Pull a `data-<attr>` pixel value out of the wrapper markup, or fall back. */
+function wrapperDimension(html: string, attr: "width" | "height", fallback: number): number {
+  const match = html.match(new RegExp(`data-${attr}="(\\d+)"`))?.[1];
+  return match ? parseInt(match, 10) : fallback;
+}
+
 async function generateThumbnail(item: CatalogItem, projectDir: string): Promise<void> {
   const outDir = outputDir(item.kind);
   mkdirSync(outDir, { recursive: true });
 
   // Read dimensions from the wrapper index.html (which may differ from native
   // dimensions for portrait overlays that are scaled to fit landscape).
-  let width = 1920;
-  let height = 1080;
-  const wrapperPath = join(projectDir, "index.html");
-  const wrapperHtml = readFileSync(wrapperPath, "utf-8");
-  const wMatch = wrapperHtml.match(/data-width="(\d+)"/);
-  const hMatch = wrapperHtml.match(/data-height="(\d+)"/);
-  if (wMatch) width = parseInt(wMatch[1], 10);
-  if (hMatch) height = parseInt(hMatch[1], 10);
+  const wrapperHtml = readFileSync(join(projectDir, "index.html"), "utf-8");
+  const width = wrapperDimension(wrapperHtml, "width", 1920);
+  const height = wrapperDimension(wrapperHtml, "height", 1080);
 
   const framesDir = join(projectDir, "_thumb_frames");
   mkdirSync(framesDir, { recursive: true });

scripts/lint-skills.ts

@@ -225,7 +225,7 @@ export function lintFrontmatter(content: string): LineViolation[] {
       violation(1, `Missing SKILL.md YAML frontmatter (must start with '---').`, "<top of file>"),
     ];
   }
-  const parsed = parseFrontmatterYaml(match[1]);
+  const parsed = parseFrontmatterYaml(match[1] ?? "");
   const preflightError = parsedDataError(parsed);
   if (preflightError) return [preflightError];
   return validateShape(parsed.data as Record<string, unknown>);

scripts/set-version.ts

@@ -226,7 +226,9 @@ function assertTagMonotonicity(version: string) {
   process.exit(1);
 }
 
-export function releaseRequiresChangelog(options: ReleaseOptions) {
+export function releaseRequiresChangelog(
+  options: Pick<ReleaseOptions, "version" | "skipTag" | "skipChangelogCheck">,
+) {
   return !options.skipTag && !options.skipChangelogCheck && !isPrerelease(options.version);
 }
 
@@ -267,7 +269,7 @@ export function unreviewedChangelogArtifacts(version: string) {
 }
 
 function artifactExists(artifact: string) {
-  const [path, marker] = artifact.split("#");
+  const [path = artifact, marker] = artifact.split("#");
   const absolutePath = join(ROOT, path);
 
   if (!existsSync(absolutePath)) {
@@ -277,7 +279,7 @@ function artifactExists(artifact: string) {
 }
 
 function artifactHasGeneratedTodo(artifact: string) {
-  const [path, marker] = artifact.split("#");
+  const [path = artifact, marker] = artifact.split("#");
   const content = readFileSync(join(ROOT, path), "utf-8");
   if (!marker) {
     return hasGeneratedChangelogTodo(content);

scripts/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowJs": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}