Publish DevRunbook source

adr/ADR-001-git-first-content.md

@@ -0,0 +1,29 @@
+# ADR-001 — Git-first canonical playbook content
+
+## Status
+
+Accepted
+
+## Context
+
+Built-in playbooks need human review, semantic versioning, reproducible releases, package export and transparent diffs. Storing only opaque database rows would weaken these workflows.
+
+## Decision
+
+Canonical built-in content is stored as YAML/Markdown packages in Git. The application validates, canonicalizes and indexes immutable versions into PostgreSQL. Private authoring may use database drafts but exports the same package format.
+
+## Consequences
+
+Positive:
+
+- ordinary Git review and history;
+- portable packages;
+- reproducible catalog builds;
+- CI validation;
+- no database lock-in for authored content.
+
+Negative:
+
+- import/index synchronization required;
+- file and database lifecycle must be clearly separated;
+- package migrations need tooling.

adr/ADR-002-modular-monolith.md

@@ -0,0 +1,21 @@
+# ADR-002 — Modular monolith for MVP
+
+## Status
+
+Accepted
+
+## Context
+
+The product has several domains and background work but must remain easy to self-host on Docker and Unraid.
+
+## Decision
+
+Use one repository and one application codebase with explicit domain packages. Deploy separate web and worker process roles backed by one PostgreSQL database.
+
+## Consequences
+
+- simpler deployment, transactions and development;
+- domain boundaries remain testable;
+- no network overhead between premature services;
+- future extraction remains possible through defined ports;
+- discipline is required to avoid framework/domain coupling.

adr/ADR-003-no-direct-code-execution-mvp.md

@@ -0,0 +1,20 @@
+# ADR-003 — No direct code execution in MVP
+
+## Status
+
+Accepted
+
+## Context
+
+Direct Codex or shell execution introduces local-repository access, command approval, sandboxing, worktrees, credentials, streaming, cancellation and audit complexity.
+
+## Decision
+
+The MVP generates prompts and Run Packs only. It does not clone repositories, execute package scripts or launch Codex. A future local companion or controlled bridge requires a separate threat model and ADR.
+
+## Consequences
+
+- smaller security boundary;
+- immediate usefulness across Codex app, CLI and IDE;
+- execution evidence remains user-imported initially;
+- future bridge can evolve independently.

adr/ADR-004-postgres-search-first.md

@@ -0,0 +1,21 @@
+# ADR-004 — PostgreSQL search before semantic infrastructure
+
+## Status
+
+Accepted
+
+## Context
+
+The library requires fast title, tag, category and intent search with filters. A vector database adds operational complexity and less explainable ranking.
+
+## Decision
+
+Use PostgreSQL full-text search plus structured filters and optional trigram matching. Add semantic search only after measured unmet discovery needs.
+
+## Consequences
+
+- one datastore and simple self-hosting;
+- explainable matching;
+- adequate scale for initial catalog and private content;
+- synonyms and curated intent terms need content governance;
+- future embedding index remains possible behind a search port.

adr/ADR-005-integration-secrets.md

@@ -0,0 +1,20 @@
+# ADR-005 — Versioned application-level encryption for integration secrets
+
+## Status
+
+Accepted
+
+## Context
+
+Gitea tokens must be stored for background synchronization but must not appear in prompts, logs or ordinary backups.
+
+## Decision
+
+Encrypt integration secrets with an externally supplied versioned master key. Store encrypted values and safe metadata in PostgreSQL. Return only write-only/rotatable secret controls to the UI.
+
+## Consequences
+
+- database compromise alone does not reveal tokens;
+- key backup and rotation become operator responsibilities;
+- losing the key makes stored tokens unrecoverable;
+- future external secret-provider adapters can implement the same port.

adr/ADR-006-better-auth-adapter-boundary.md

@@ -0,0 +1,44 @@
+# ADR-006 — Application-owned Better Auth persistence adapter
+
+## Status
+
+Accepted for Milestone 0 on 2026-07-27.
+
+## Context
+
+DevRunbook requires database-backed revocable sessions, hashed bearer tokens at rest, simultaneous 12-hour idle and 30-day absolute expiry, explicit revocation records, operator-issued password-reset links, first-run ownership in one transaction, and application-owned workspace authorization.
+
+Better Auth 1.6.25 is compatible with Next.js 16 and Drizzle/PostgreSQL, but its stock database model stores the session bearer value directly, removes sessions during ordinary revocation, stores credential passwords on an account row, and exposes one rolling session expiry. Applying its generated schema unchanged would conflict with the security and lifecycle contracts in documents 26, 31, and the reference database model.
+
+## Decision
+
+Keep Better Auth 1.6.25 as the authentication protocol, credential-workflow, cookie, origin/CSRF, and request-handler engine. DevRunbook owns:
+
+- Drizzle schema and migrations;
+- a Better Auth custom database adapter that transforms high-entropy session tokens before persistence;
+- idle, absolute-expiry, revocation, and disabled-user checks;
+- first-run ownership and package import transaction;
+- invitations, operator reset tokens, audit events, and session revocation use cases;
+- a versioned envelope around the selected Better Auth-compatible scrypt parameters, plus transparent successful-login migration from Better Auth 1.6's unversioned `salt:key` format;
+- every instance-role and workspace authorization decision.
+
+The stock `drizzleAdapter()` and Better Auth migration command are not production migration paths. Better Auth schema generation may be used only as a compatibility check. Cookie caching remains disabled so revocation is visible on the next request. Next.js proxy logic may improve routing but is never an authorization boundary.
+
+## Consequences
+
+- Authentication integration is more work than the stock adapter, but no raw session bearer value is retained in PostgreSQL and the product contracts remain enforceable.
+- New password hashes record their algorithm version and work factors. A future parameter change must retain verification for the preceding envelope version and mark it for successful-login rehash; malformed or unknown formats fail closed.
+- Adapter conformance, token-at-rest, expiry, revocation, CSRF, cookie, first-run concurrency, reset replay, and cross-workspace tests become mandatory Milestone 0 evidence.
+- If Better Auth's adapter API cannot support these transformations without security or correctness gaps, implementation must stop for a blocker-level replacement ADR rather than silently weakening the requirements.
+
+## Evidence
+
+Implemented conformance evidence in Milestone 0 includes generic credential failures, secure cookie attributes, same-origin mutation rejection, HMAC-only session persistence, simultaneous idle/absolute expiry, disabled-user denial, logout-to-`revoked_at` mapping, versioned scrypt hashes and successful-login legacy rehash. The credential account is a virtual adapter model over `users.password_hash`; the only compatibility columns added to `users` are `email_verified` and nullable `image`.
+
+Live PostgreSQL adapter evidence remains required because the current workstation has no Docker-compatible runtime or standalone PostgreSQL service.
+
+- Better Auth custom adapter API: <https://better-auth.com/docs/guides/create-a-db-adapter>
+- Better Auth custom password hashing: <https://better-auth.com/docs/authentication/email-password#password>
+- Better Auth database schema: <https://better-auth.com/docs/concepts/database>
+- Better Auth session management: <https://better-auth.com/docs/concepts/session-management>
+- Better Auth security model: <https://better-auth.com/docs/reference/security>