[codex] Add devkit scaffold

.context/architecture/repository-layout.md

@@ -0,0 +1,12 @@
+# Repository Layout
+
+This repository uses an app/package split:
+
+- `apps/api`: minimal Python app/shared-package wiring.
+- `apps/web`: framework-neutral TypeScript conventions.
+- `packages/shared`: shared settings, clients, schemas, queue helpers, and pure business logic.
+- `scripts`: deterministic project entrypoints used by humans, CI, and agents.
+- `docs`: durable user-facing or contributor-facing documentation.
+- `.context`: operational memory for humans and agents.
+
+Treat `apps/*` here as reference wiring, not product code. Keep service-specific behavior in its service when applying the devkit to a real repo. Put shared contracts and pure helpers in `packages/shared`.

.context/decisions/tooling.md

@@ -0,0 +1,34 @@
+# Tooling Decisions
+
+## Python
+
+Use `uv` for installs and execution. Keep Python configuration in `pyproject.toml`.
+
+Required checks:
+
+- `uv run ruff check`
+- `uv run ruff format --check`
+- `uv run mypy`
+- `uv run pytest`
+
+## JavaScript and TypeScript
+
+Use Bun for new projects. It matches the preferred default for greenfield work and keeps scripts fast and direct.
+
+Use pnpm only when a workspace grows large enough that its monorepo tooling, workspace controls, or ecosystem compatibility clearly outweigh the simplicity of Bun.
+
+Required checks:
+
+- `bun run lint`
+- `bun run format:check`
+- `bun run typecheck`
+- `bun run test`
+
+## Dependency Safety
+
+Use dependency cooldowns and frozen installs:
+
+- `uv`: `exclude-newer = "7 days"`.
+- Bun: `bunfig.toml` sets `minimumReleaseAge = 604800` seconds.
+- pnpm: `pnpm-workspace.yaml` should set `minimumReleaseAge: 10080` minutes.
+- CI should use locked or frozen installs.

.context/failures/.gitkeep

@@ -0,0 +1 @@
+

.context/failures/README.md

@@ -0,0 +1,5 @@
+# Failures
+
+Record confirmed failed approaches, recurring error patterns, and known bad paths.
+
+Keep entries concise and include enough context for future agents to avoid repeating the same work.

.context/runbooks/local-dev.md

@@ -0,0 +1,11 @@
+# Local Development Runbook
+
+1. Copy `.env.example` to `.env` and fill required secrets.
+2. Run `./scripts/worktree-ports.py env` to inspect derived ports.
+3. Start local infrastructure with `./scripts/docker-compose.sh up -d`.
+4. Start host services with `./scripts/dev.sh`.
+
+When creating sibling worktrees, use `.worktreeinclude` to copy only ignored local config such as `.env` and `.sops.yaml`. Docker build contexts should use `.dockerignore` to exclude secrets, dependencies, caches, and `.context/` scratch state.
+5. Run checks with `./scripts/check-all.sh`.
+
+App services should run on the host for reload speed and easier debugging. Docker Compose should own infrastructure such as Postgres, Redis, and optional object storage.

.context/summaries/.gitkeep

@@ -0,0 +1 @@
+

.context/summaries/README.md

@@ -0,0 +1,5 @@
+# Summaries
+
+Record high-signal project evolution summaries and recurring lessons.
+
+Prefer short synthesized notes over raw transcripts, logs, or generated artifacts.

.cursor/rules/repo-conventions.mdc

@@ -0,0 +1,6 @@
+---
+description: Repository conventions for agent edits
+alwaysApply: true
+---
+
+Read `AGENTS.md` before changing files. Prefer repo scripts over ad hoc commands. Keep edits small, update `.env.example` when adding config, and update `.context/` only for durable operational knowledge.

.dockerignore

@@ -0,0 +1,33 @@
+.git
+.github
+.context
+.cursor
+
+.env
+.env.*
+!.env.example
+.sops.yaml
+
+.venv
+node_modules
+**/node_modules
+
+__pycache__
+*.py[cod]
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.coverage
+coverage.xml
+htmlcov
+
+dist
+build
+apps/web/dist
+
+.DS_Store
+*.log
+tmp
+temp
+.tmp
+.temp

.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

.env.example

@@ -0,0 +1,53 @@
+# Runtime
+ENVIRONMENT=local
+LOG_LEVEL=INFO
+API_SHARED_SECRET=
+
+# Host-run service ports. Leave unset locally to use deterministic worktree ports.
+API_HOST=127.0.0.1
+# API_PORT=8720
+WEB_HOST=127.0.0.1
+# WEB_PORT=8730
+# WORKER_HEALTH_PORT=8735
+
+# Docker-published infra ports. Leave unset locally to use deterministic worktree ports.
+POSTGRES_HOST_BIND=127.0.0.1
+# POSTGRES_HOST_PORT=8740
+REDIS_HOST_BIND=127.0.0.1
+# REDIS_HOST_PORT=8750
+MINIO_HOST_BIND=127.0.0.1
+# MINIO_API_HOST_PORT=8760
+# MINIO_CONSOLE_HOST_PORT=8761
+
+# Postgres
+POSTGRES_DB=app
+POSTGRES_USER=app
+POSTGRES_PASSWORD=app
+POSTGRES_URL=postgresql://app:app@127.0.0.1:8740/app
+DATABASE_URL=postgresql://app:app@127.0.0.1:8740/app
+
+# Redis
+REDIS_URL=redis://127.0.0.1:8750/0
+REDIS_QUEUE_NAME=jobs.default
+
+# Optional object storage
+MINIO_ENDPOINT=http://127.0.0.1:8760
+MINIO_ROOT_USER=internal
+MINIO_ROOT_PASSWORD=change-me
+MINIO_INTERNAL_BUCKET=internal-transfers
+
+# Observability
+SENTRY_DSN=
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_SERVICE_NAME=508-devkit
+LANGFUSE_BASE_URL=
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+
+# LLM provider defaults
+OPENAI_API_KEY=
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-4.1-mini
+
+# Web
+WEB_API_BASE_URL=http://127.0.0.1:8720

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug Report
+description: Report a reproducible problem.
+title: "[Bug] "
+labels:
+  - bug
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps To Reproduce
+      description: Include the smallest reliable reproduction you have.
+      placeholder: |
+        1. Run ...
+        2. Open ...
+        3. See ...
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, browser, runtime versions, commit SHA, deployment environment, or other relevant context.
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs Or Screenshots
+      description: Paste short logs or attach screenshots. Do not include secrets.
+      render: text
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+
+# If the repository uses GitHub Discussions, add a project-specific contact link:
+#
+# contact_links:
+#   - name: Questions and support
+#     url: https://github.com/OWNER/REPO/discussions
+#     about: Ask usage questions and discuss ideas here.

.github/ISSUE_TEMPLATE/docs_request.yml

@@ -0,0 +1,29 @@
+name: Documentation Request
+description: Request new or improved documentation.
+title: "[Docs] "
+labels:
+  - documentation
+body:
+  - type: textarea
+    id: gap
+    attributes:
+      label: Documentation Gap
+      description: What is missing, unclear, stale, or hard to find?
+    validations:
+      required: true
+  - type: textarea
+    id: audience
+    attributes:
+      label: Audience
+      description: Who needs this documentation?
+      placeholder: New contributors, operators, API consumers, support, sales, agents, etc.
+    validations:
+      required: false
+  - type: textarea
+    id: suggested-location
+    attributes:
+      label: Suggested Location
+      description: Where should this live?
+      placeholder: README.md, docs/development.md, docs/runbooks/..., API docs, etc.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,34 @@
+name: Feature Request
+description: Propose a new capability or workflow.
+title: "[Feature] "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user or business problem should this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution
+      description: What should change?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What other approaches are available?
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Links, screenshots, examples, constraints, or non-goals.
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Summary
+
+-
+
+## Validation
+
+- [ ] Ran the narrowest relevant checks.
+- [ ] Updated docs or examples when behavior changed.
+
+## Risk
+
+- [ ] Low risk, isolated change.
+- [ ] Needs reviewer attention for migrations, deploy behavior, permissions, secrets, or user-facing flows.
+
+## Screenshots
+
+Add screenshots or recordings for UI changes.