Quickstart | BotHarness

Environment

pnpm 12.4.2 · Node ≥22 · TypeScript 7 · oxlint / oxfmt · vitest · tsdown.

pnpm install
pnpm lint && pnpm format:check && pnpm typecheck && pnpm test
pnpm build

Directory layout (monorepo)

packages/core        @botharness/core   # PersonaBot registry / state (memory lands in M2)
packages/client      @botharness/client # React: roster / details / delegation entry (M3)
packages/im          @botharness/im     # IM adapters (M5)
packages/deepseekbot deepseekbot        # bundle + app (later)
apps/docs            docs site (Nimbus / Astro, deployed to Cloudflare Workers)
docs/                specs, ADRs, architecture, and changelog (the docs site's single content source)

Docs site

Most of apps/docs’s content is generated by scripts/sync-docs.mjs from the repository root (specs / PRD / glossary / ADRs / architecture / changelog) — change the repository source files, not the generated output.

pnpm dev           # recommended: via portless → https://docs.botharness.localhost (generates a local CA and asks for trust on first run)
PORTLESS_PORT=8788 PORTLESS_HTTPS=0 pnpm dev   # no-sudo variant → http://docs.botharness.localhost:8788
pnpm docs:dev      # direct → http://localhost:4321 (reachable from both WSL and the Windows host)
pnpm docs:build    # sync + build
pnpm docs:deploy   # build + wrangler deploy

Syncing is built into astro.config.ts (syncDocs()), so running astro dev / astro build directly also generates the content first; portless is pinned as a root devDependency (no global install needed) and started from this package so it injects --port correctly.