Punk Docs - Development

Development

This guide is for contributors working inside the Punk monorepo.

Setup

bun install
bun run dev
bun run demo

Validation:

bun test
bun run typecheck

macOS menu bar app:

bun run menubar
open apps/menubar/dist/Punk.app

Workspace Layout

apps/
  api/       gateway, REST API, dashboard, router, providers
  worker/    durable job worker
  demo/      narrated demo agent
  mcp/       Runtime Engine MCP server and prompt ingest hook
  menubar/   native macOS companion

packages/
  trace-schema/
  database/
  cache-core/
  fingerprint/
  governance-core/
  web-core/
  workflow-core/
  mcp-client/
  artifact-core/
  replay-core/
  synthesis/
  learning/
  jobs/
  sdk/

Development Rules

Keep Contracts Central

Runtime entity types belong in @punk/trace-schema.

Do not invent parallel run, artifact, approval, policy, SOM, or route types in app code unless they are strict view models.

Keep Storage Behind `PunkStore`

No raw SQL outside packages/database.

If a feature needs storage, add a named method to PunkStore, then implement it in:

SQLite adapter.
Memory adapter.
Postgres adapter.
Conformance tests where relevant.

Keep App Packages Thin

App packages wire process lifecycle, Hono routes, provider IO, static assets, and CLI/demo UX. Core logic should live in packages.

Prefer Evidence Over Magic

Any optimization feature should produce:

Trace events.
Route explanation.
Evaluation evidence where relevant.
Audit event when governance/operator decision is involved.
Fallback behavior.

Update Docs With Behavior

When changing:

Endpoint behavior: update API.
Env vars/settings: update Configuration.
Runtime flow/package boundaries: update Architecture.
Policies/side effects/approvals: update Governance.
SOM/web behavior: update Semantic Web.
Setup/deploy behavior: update Operations or Troubleshooting.

Testing Map

Area	Tests
API integration/security/streaming/approvals	`apps/api/test/*.test.ts`
Cache	`packages/cache-core/test/*.test.ts`
Database	`packages/database/test/*.test.ts`
Fingerprints	`packages/fingerprint/test/*.test.ts`
Governance	`packages/governance-core/test/*.test.ts`
Learning	`packages/learning/test/*.test.ts`
Replay	`packages/replay-core/src/*.test.ts`
SDK	`packages/sdk/test/*.test.ts`
Synthesis	`packages/synthesis/test/*.test.ts`
Web runtime	`packages/web-core/test/*.test.ts`
Workflow runtime	`packages/workflow-core/test/*.test.ts`, `apps/api/test/workflows.test.ts`
MCP client and registry	`apps/api/test/mcp.test.ts`
Worker	`packages/jobs/test/*.test.ts`

Adding An Endpoint

Add the route in apps/api/src/api.ts.
Reuse existing auth context and tenant scoping.
Add storage methods to PunkStore if needed.
Add tests in apps/api/test/.
Update API.
Add dashboard/SDK support only after the route contract is stable.

Adding A Package

Add packages/<name>/package.json.
Keep exports explicit.
Depend on @punk/trace-schema for shared contracts.
Avoid app-level imports from packages.
Add tests.
Add it to Architecture.

Active Development Expectations

Punk moves quickly. Before starting a large change:

git pull --ff-only origin main
git status --short

While working, assume files may change. Before finalizing docs or code, re-read the specific files you touched and run targeted validation.

//DOCS Development