agent-docs

kevin-wiki / scripts

Purpose

The maintenance and integration layer: standalone TypeScript CLIs (run via npx tsx) that build the index, lint and health-check the wiki, ingest and sync external sources into raw/, run automations, and serve the MCP/voice servers. Every script updates state.json so freshness tracking stays accurate.

Mental model & key files

  • Wiki maintenance: build-index.ts (rebuilds _index.md + _backlinks.json + README stats), lint.ts, wiki-status.ts, wiki-breakdown.ts, doctor.ts (5-doctor health check), section-quality-audit.ts (section-level editorial triage), wiki-quality-audit.ts (read-first/router/source/skill-load quality audit), audit-agent-pack-corpus.ts (page-by-page pack/capsule decision ledger), generate-agent-packs.ts (deterministic portable workflow pack generator that enriches packs from current wiki markdown/frontmatter), check-freshness.ts (session-start staleness), and brain.ts (query the graph-backed operating system).
  • Ingestion/sync: ingest.ts, sync-*.ts (calendar, email, meetings, google-takeout), enrich-x-bookmarks.ts, freeze-discord-attachments.ts (freeze signed attachment bytes with hashes), correlate-discord-x.ts (message-ID-to-bookmark correlation), harvest-awesome-mac.ts (macOS app discovery; never an install manifest), and harvest-fmhy.ts (guarded file manifest; never bulk candidate projection or recommendation authority). Google Takeout preserves source-relative paths and hash-verifies every copy; Gmail and Calendar require exact service scopes, account-qualified cursors, account-scoped outputs, and complete-run receipts before freshness advances. Voice-call import is local-export-only: it requires a private consent manifest plus an explicit attestation, preserves all regular files, rejects symlinks, and creates an immutable snapshot receipt without transcribing or synthesizing. Circleback collection uses the pinned official CLI: search discovers identities, detail plus full-transcript reads complete each cohort, and transcript edits create new content-addressed revisions before the source clock can advance. Slack collection uses only read/list/history/file Web API routes, cursor-pages complete conversations and threads, freezes private attachment bytes, and keeps browser inspection outside the scheduled source clock.
  • Source-review accounting: migrate-agent-session-message-identity.ts upgrades trace-level analyses to stable message identities plus content-bound session snapshots; build-source-review-unit-audit.ts emits exact digest-bound review units; build-message-corpus-review-decisions.ts produces the deterministic integrated/held decision inputs that the ordinary batch compiler validates.
  • Servers: serve-mcp.ts, voice-server.ts. Automations: run-automation.ts and audit-automation-readiness.ts (non-secret CLI/auth/session/scheduler readiness).
  • lib/ — shared helpers (see scripts/lib/SKILL.md).
  • agent-docs/ — the Agent-Docs Mesh kit (see scripts/agent-docs/SKILL.md).

Patterns to follow / invariants

  • ESM ("type": "module"): local relative imports use a .js extension.
  • Tests use the Node built-in runner: node --import tsx --test <file>.
  • Pure, testable functions live in lib/; CLIs are thin wrappers over them.
  • npm run skill-registry owns skill registry/family/source/runtime projections and the legacy redirect index. Existing retired root skill redirects must follow the registry's current family; never create a redirect for an unredirected slug because a tool or concept may own it.
  • Scripts call updateState(...) after meaningful work; never hand-edit state.json.
  • Use rg, never grep.

Common tasks → first action

  • Add a maintenance command → write scripts/<name>.ts, factor logic into lib/, add an npm script, add a lib/__tests__/*.test.ts.
  • Debug freshness → npx tsx scripts/check-freshness.ts.
  • Prove Google/source connector contracts → npm run sync:connectors:test.
  • Audit automation tools, credentials, and live scheduler drift → npm run audit:automations.
  • Audit wiki agent-load/source quality → npx tsx scripts/wiki-quality-audit.ts (add --network --limit 40 for sampled live source checks).
  • Audit every wiki page for pack/capsule routing → npm run agent-packs:audit; refresh audit-fed packs with npm run agent-packs:refresh.
  • Regenerate portable workflow packs → npm run agent-packs; verify drift with npm run agent-packs:check.
  • Index local Codex, Cursor, and Claude conversations → npm run brain -- sessions index; add an authorized export with --path <path> --provider <provider> and list it with npm run brain -- sessions list. These are the only brain subcommands left.
  • Prove the installed portable-memory writer without exposing its token → npm run memory:conformance; this exercises scope isolation, public-write denial, idempotent remember/recall/retire, retained history, and Daily Brief review projection.
  • Validate or export the public portable knowledge tree → npm run okf:check or npm run okf:export (implementation lives under ui/scripts/).
  • Validate capability routing → npm run routing-doctor.
  • Rebuild everything → npx tsx scripts/build-index.ts.

Gotchas

  • These scripts read/write repo files directly — guard statSync/readdirSync against symlinks and missing paths (see the mesh's lib/repo-walk.ts).
  • build-index.ts owns the <!-- ...auto... --> regions in README.md/_index.md.