DevRunbook-Public/README.md

# DevRunbook

DevRunbook is a self-hosted platform for turning development intent into
structured, reusable and verifiable tasks for coding agents such as Codex. It
combines a reviewed playbook, repository context, risk controls and validation
requirements into a deterministic prompt or multi-file Run Pack.

The platform helps developers stop rewriting the same instructions while
keeping scope, provenance and evidence visible. It does **not** execute
repository commands or write to your Git forge.

## What users can do

- Browse and search 28 built-in, versioned development playbooks.
- Create reusable repository profiles with commands, protected paths and policies.
- Compose tasks in a guided Simple flow or a detailed Expert flow.
- Inspect compatibility, provenance, guardrails and prompt-lint results before generation.
- Save immutable generated tasks and export exact Markdown or verified Run Pack archives.
- Connect Gitea read-only to import bounded repository evidence while retaining useful local state during an outage.
- Author and review private playbooks in Prompt Lab without making draft claims look validated.

The interface supports Dutch and English presentation, keyboard navigation,
reduced motion, light/dark themes and responsive desktop/mobile layouts.

## Quick start with Docker Compose

Requirements:

- Docker Engine with Docker Compose 2.40 or newer;
- a release checkout of this repository;
- four independently generated secrets.

```sh
cp .env.example .env
chmod 600 .env

openssl rand -hex 24       # POSTGRES_PASSWORD
openssl rand -hex 32       # SESSION_SECRET
openssl rand -base64 32    # INTEGRATION_ENCRYPTION_KEY
openssl rand -hex 24       # BOOTSTRAP_TOKEN
```

Place those values in `.env`, set `PUBLIC_BASE_URL`, then start the stack:

```sh
docker compose -p devrunbook --env-file .env build
docker compose -p devrunbook --env-file .env up -d
docker compose -p devrunbook --env-file .env ps
```

Open `PUBLIC_BASE_URL/setup`, enter the bootstrap token and create the first
owner. The setup route closes after successful initialization. Keep public
registration closed unless you deliberately configure an invitation workflow.

Health endpoints:

```sh
curl --fail http://127.0.0.1:3000/health/live
curl --fail http://127.0.0.1:3000/health/ready
```

For production upgrades, backups, restores, Unraid and reverse-proxy guidance,
read the [operator guide](docs/operator-guide.md). Do not publish PostgreSQL,
mount the Docker socket or weaken the default Gitea network policy. The
reference stack binds its HTTP port to host loopback; terminate public HTTPS at
a maintained reverse proxy on the same host or adjust the binding deliberately.

## Local development

DevRunbook requires Node.js 24, pnpm 10.33.0 and Python 3 for the specification
contracts. PostgreSQL is required for integration tests and a complete local
application flow.

```sh
corepack enable
pnpm install --frozen-lockfile
python3 scripts/validate_pack.py
python3 scripts/reference_compose.py --check
pnpm verify
pnpm test:security
```

`pnpm verify` runs formatting, linting, strict type checks, unit tests,
specification/golden-fixture validation and production builds. See
[`docs/15-test-strategy.md`](docs/15-test-strategy.md) for integration,
Playwright, clean-room and release gates.

## Architecture and safety

DevRunbook is a TypeScript modular monolith with separate web and worker roles
and PostgreSQL as its only required data service. Important boundaries include:

- generated runs and published playbook versions are immutable snapshots;
- imported repository text is untrusted evidence, never governing instruction;
- templates and conditions use restricted, non-executable data models;
- archives are bounded, inventoried and verified without unsafe extraction;
- workspace authorization is enforced server-side for every private resource;
- Gitea tokens are encrypted at rest and the first integration is read-only;
- default containers run non-root with read-only roots, dropped capabilities and no Docker socket.

Start with the [product vision](docs/00-product-vision.md),
[technical architecture](docs/06-technical-architecture.md) and
[security threat model](docs/13-security-privacy-threat-model.md). Contributors
should also read [`AGENTS.md`](AGENTS.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Project status

The implemented release candidate covers the core library, repository profiles,
deterministic composition, exports, read-only Gitea intelligence, Prompt Lab,
operations, localization and accessibility hardening. Detailed evidence is in
[`CURRENT_STATE.md`](CURRENT_STATE.md) and
[`docs/19-acceptance-criteria.md`](docs/19-acceptance-criteria.md).

Direct code execution, forge writes, a public marketplace, billing, Kubernetes
as a required deployment and vector search remain deliberately out of scope.

The application and Unraid icons were created for this project; their source
and licensing are recorded in [the asset notice](docs/ASSET_PROVENANCE.md).

`BUILD_PACK.json`, `FILE_INDEX.txt`, `PACK_MANIFEST.sha256` and the version 1.2
documents describe the historical implementation-contract pack from which the
0.1 application was built. They are not the current application version or a
release manifest. See [publication readiness](docs/PUBLICATION_READINESS.md)
for the remaining owner-controlled launch decisions.

## License and security

DevRunbook is available under the [MIT License](LICENSE). Please report
vulnerabilities through the private channel described in
[`SECURITY.md`](SECURITY.md); do not post tokens, private repository contents or
exploit details in a public issue.