<!-- Canonical: https://programkit.dev/docs/developers -->
<!-- Markdown: https://programkit.dev/docs/developers.md -->

# Developer guide

ProgramKit is both an application and an open-source starter. The repository is designed to be
changed, but it is opinionated about where business rules, authorization, projections, hosting,
and agent behavior belong.

## Set up the repository

Prerequisites: Git and Node.js 24 or newer. No global pnpm or Corepack installation is required.

```bash
git clone https://forge.smol.ai/andheller/programkit.git
cd programkit
npm run setup
npm start
```

Local development starts the React client, Worker, and local SQLite-backed Durable Objects at
`http://localhost:4173`. No Cloudflare login or external service is required for the deterministic
sample.

## Repository shape

| Path              | Owns                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------ |
| `packages/core`   | Records, operations, validation, authorization, events, selectors, and repositories  |
| `packages/web`    | React interface, typed routes, server state, portals, and public views               |
| `packages/agent`  | MCP transport, tools, resources, portable plugin, and operational skills             |
| `apps/cloudflare` | Worker composition, identity, Durable Objects, R2, mail, static assets, and profiles |
| `tests`           | Domain, HTTP, host, security, projection, API, plugin, and integration behavior      |
| `docs`            | Product, user, self-hosting, developer, agent, API, and operations documentation     |

Read the [repository tour](/docs/developers/repository-tour.md) for request flow and boundaries.

## The central rule

Every mutation—whether initiated by a person, REST client, import, or agent—must execute a named
operation from `packages/core`. The host supplies a trusted actor and event scope after verifying
the credential. A route handler, React component, MCP tool, or integration must not recreate a
domain transition.

This gives every surface the same:

- authorization and operation policy;
- validation and atomicity;
- expected-version conflict handling;
- idempotency;
- audit events; and
- proposal/dry-run behavior where supported.

## Common development paths

- Add a product workflow: [Extending ProgramKit](/docs/developers/extending-programkit.md#add-a-domain-workflow).
- Add an organizer page: [Extending ProgramKit](/docs/developers/extending-programkit.md#add-a-web-surface).
- Add a participant or public view: define its minimized projection and operation allowlist first.
- Add an API endpoint: prefer a resource read or generated named-operation path.
- Add an agent capability: expose a task-shaped tool that is narrower than the raw operation list.
- Add an integration: keep provider SDKs and credentials at the host boundary.
- Change persistence: preserve the repository and transactional operation contract.
- Rebrand or customize the starter: use the [customization map](/docs/developers/customizing.md) and replace only
  assets you own or may redistribute.

## Generated files

Do not hand-edit:

- `packages/web/src/routeTree.gen.ts` — generated by TanStack Router;
- `docs/api/openapi.json` — generated from the core operation manifest; or
- `apps/cloudflare/src/agent-plugin-source.generated.ts` — generated from the portable plugin.

Use:

```bash
pnpm openapi:generate
pnpm agent-plugin-source:generate
```

## Verification

Run focused tests while iterating, then the complete gate:

```bash
pnpm check
```

The gate covers tests, lint, formatting, generated artifacts, type checking, package builds,
production Worker build, OpenAPI validation, and plugin validation.

## Before a large extension

Read [Roadmap](https://forge.smol.ai/andheller/programkit/blob/main/ROADMAP.md), [Architecture](https://forge.smol.ai/andheller/programkit/blob/main/ARCHITECTURE.md),
[Storage and integrations](/docs/architecture/storage-and-integrations.md), and
[Interface craft](/docs/developers/interface-craft.md). Then describe the user outcome, trust boundary,
new invariant, and smallest complete vertical slice before adding code.

See [Contributing](https://forge.smol.ai/andheller/programkit/blob/main/CONTRIBUTING.md) for repository policy, the
[contribution playbook](/docs/agents/contribution-playbook.md) for the implementation sequence, and
[Contributing documentation](/docs/contributing-documentation.md) for audience routing and page
standards.