agent-docs

kevin-wiki / ui/scripts

Purpose

Build- and check-time scripts for the viewer: bundle the wiki/ markdown into a form the Next app serves, and enforce the wiki's quality invariants (inline citations, gate passwords) so broken content can't ship.

Mental model & key files

  • bundle-wiki.mjs — packages wiki content plus referenced public image/video assets for the app to render and emits the public-only static search index; private-page-only data and assets stay out of public deployment artifacts.
  • export-okf.mjs + lib/okf-export.mjs — deterministically project the same public corpus into an OKF v0.2 Markdown tree served at /api/okf.
  • enforce-citations.ts + lib/citation-scan.ts — fail the build when facts lack [Source: ...] citations; test-citations.ts covers the scanner.
  • test-gate-passwords.ts — validates gated-content password config.
  • test-privacy-gating.ts — locks regression cases for people, career, finance, Dedalus, generated packs, the mail and cloud tool pages, operational logs, and the public stable objects on /system.
  • test-public-search-index.ts — proves the CDN search artifact includes every public entry, excludes every private entry, and contains no privacy metadata.
  • test-vercel-upload.mjs + lib/trace-reads.mjs — runs the build scripts that read outside ui/, records every file they open, and fails when .vercelignore would leave one out of the upload. Like a build, it rewrites ui/.content and the public search index and assets.

Patterns to follow / invariants

  • ESM; .mjs for plain Node scripts, .ts run via tsx.
  • Keep scan/validation logic in lib/ (pure) and the entrypoints thin + testable.
  • A failing citation/gate check should block the build — these are guardrails.

Common tasks → first action

  • Re-bundle after wiki edits → run bundle-wiki.mjs.
  • Add a content guardrail → put the predicate in lib/, call it from an enforce-*.ts entry, add a test-*.ts.
  • Verify the portable agent bundle → pnpm test:okf and node scripts/export-okf.mjs --check.

Gotchas

  • These run in the ui/ pnpm workspace, not the repo-root tsx environment.
  • Citation enforcement mirrors wiki/ conventions — keep it in sync with conventions-quality if the citation format changes.