Punk Documentation
Punk is the adaptive runtime for production AI agents. These docs are organized by what you are trying to do, not by the package layout.
Punk is in active development. When implementation and docs drift, treat the code as the source of truth and update the relevant doc in the same change. The most useful docs here are short on narrative and specific about commands, routes, contracts, and operating behavior.
Start Here
| Reader | Start with | Then read |
|---|---|---|
| Evaluating Punk | Concepts | Onboarding, Architecture |
| App developer | Onboarding | SDK, API, Examples |
| Agent/tool developer | SDK | Governance, Semantic Web |
| Platform/operator | Configuration | Operations, Troubleshooting |
| Security/GRC reviewer | Governance | API, Operations |
| Contributor | Development | Architecture, package tests |
| Product/strategy reader | README | Concepts |
Documentation Map
- Concepts: the runtime loop, routes, traces, policies, SOM, artifacts, and approvals.
- Onboarding: a 30-minute local walkthrough from gateway startup to a promoted artifact.
- SDK: TypeScript client reference.
- API: HTTP endpoints, auth, identity headers, and response conventions.
- Architecture: current repo shape, request flow, package responsibilities, and persistence.
- Configuration: environment variables, gateway modes, auth, databases, and settings.
- Governance: policies, trust tiers, side-effect levels, approvals, observe mode, and audit.
- Semantic Web: SOM fetch, cache, diffs, Plasmate-compatible AWP integration, and safety.
- Operations: local, production, worker, database, retention, security, and health practices.
- Development: working in the monorepo, tests, package boundaries, and doc update rules.
- Troubleshooting: common symptoms and fixes.
- PunkBar: macOS menu bar companion for live savings and approvals.
Current Product Surface
The repository currently includes:
- OpenAI-compatible gateway at
/v1/chat/completions. - Static dashboard at
/. - REST API under
/api/v1/*. - TypeScript SDK in
packages/sdk. - Semantic web runtime in
packages/web-core. - Governance runtime in
packages/governance-core. - Trace schema in
packages/trace-schema. - Persistence adapters in
packages/database. - Cache, replay, learning, synthesis, and durable job packages.
- Demo agent in
apps/demo. - Worker in
apps/worker. - macOS menu bar app in
apps/menubar.
Documentation Standards
When changing behavior:
- Update the closest doc in the same commit.
- Prefer tables, examples, and exact routes over broad prose.
- Call out defaults, failure modes, and security posture.
- If behavior is intentionally temporary, label it as current behavior.
- Keep root README strategic; keep operational detail in
docs/.