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).
  • Ingestion/sync: ingest.ts, sync-*.ts (calendar, email, meetings, google-takeout), enrich-x-bookmarks.ts.
  • 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.
  • 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.
  • 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.
  • 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.