@vegastack/skills 0.9.1 → 0.11.0

package/README.md

@@ -4,20 +4,25 @@ Installer for VegaStack Agent Skills — a family of self-contained skills for C
 
 ```sh
 npx @vegastack/skills list
-npx @vegastack/skills add architect
+npx @vegastack/skills add dev-architect
 ```
 
 ## Skills in this package
 
 | Skill | What it does |
 |---|---|
-| `architect` | Architecture advisor: the locked stack and lean-first principles as evidence-distilled decision tables, dated source-verified platform facts, a per-project `.vegastack/arch.md` profile with repo-wins drift detection, and an advisory-only review discipline |
 | `skill-maintainer` | Encodes the Agent Skills standards (Claude Code, Codex, Hermes, agentskills.io) for creating, updating, and releasing skills in a skills repo |
 | `skillify` | Turns a feature or workflow into a complete skill conforming to the VegaStack skills contract, or audits an existing one |
+| `dev-architect` | Architecture advisor: the locked stack, recorded rejections, and lean-first principles as evidence-distilled decision tables, dated source-verified platform facts behind a verify-before-you-recommend protocol, reading the `## Architecture` section of `.vegastack/dev.md` |
 | `dev-setup` | Bootstraps any project, greenfield included, for the issue-driven dev workflow: stack-playbook-drafted profile, AGENTS.md section, labels, guards, decision register |
 | `dev-intake` | Turns ideas, brainstorms, and SOWs into agent-ready GitHub issues with recorded user approval |
+| `dev-plan` | Plans an approved issue before any code exists: fresh-grounded questionnaire, strict plan format with Interfaces blocks, the scope ratchet, quick-build inline mode |
 | `dev-implement` | Implements an approved issue end to end, dark: preflight, claim, build, test, review, evidence in the issue |
+| `dev-debug` | Reproduce-first bug diagnosis: red command, ranked suspects, regression-test-before-fix |
+| `dev-review` | Independent multi-axis review of finished work: spec/standards/security axes, bounded fix loop, cross-agent Codex mode |
 | `dev-ship` | Opens the PR, merges, and runs the project's Ship runbook, each only on the user's explicit word |
+| `dev-status` | The operator's board: whose move is it, from deterministic gh data |
+| `dev-chronicle` | The project's narrative record: story entries per branch and the "catch me up" digest |
 
 ## Commands
 
@@ -26,7 +31,7 @@ npx @vegastack/skills add architect
 | `list` | Show the bundled skills |
 | `add <skill>` | Install (or upgrade) a skill into the selected agent directories |
 | `verify [skill]` | Check installed copies against the bundled checksum manifest (all bundled skills when no name given) |
-| `doctor` | Diagnose an install: integrity across all skills, profile presence, installed-vs-latest version |
+| `doctor` | Diagnose an install: integrity across all skills, dev profile (`.vegastack/dev.md`) presence, installed-vs-latest version |
 | `remove <skill>` | Uninstall a skill from the selected agent directories |
 
 ## Flags

package/dist/index.js

@@ -534,18 +534,18 @@ async function doctor(options) {
   await access(base, fsConstants.R_OK | fsConstants.W_OK);
   await assertNoSymlink(base, false);
   let failed = false;
-  const profilePath = join(base, ".vegastack", "arch.md");
+  const profilePath = join(base, ".vegastack", "dev.md");
   if (options.mode !== "global") {
     if (await exists(profilePath)) {
       const content = await readFile(profilePath, "utf8");
-      if (content.includes("hosting:"))
-        console.log(`ok architecture profile: ${profilePath}`);
+      if (content.includes("## Knobs"))
+        console.log(`ok dev profile: ${profilePath}`);
       else {
-        console.log(`invalid architecture profile: ${profilePath} (no "hosting:" line; regenerate from the architect skill's template)`);
+        console.log(`invalid dev profile: ${profilePath} (no "## Knobs" section; re-run dev-setup to regenerate)`);
         failed = true;
       }
     } else {
-      console.log(`missing architecture profile: ${profilePath} (only needed once the architect skill is used in this project)`);
+      console.log(`missing dev profile: ${profilePath} (created by dev-setup once the dev skills are used in this project)`);
     }
   }
   console.log(`ok runtime: Node ${process.versions.node}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/skills",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Installer and verifier for VegaStack Agent Skills (Claude Code, Codex, and Hermes)",
   "license": "MIT",
   "type": "module",

package/skill/dev-architect/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: dev-architect
+description: VegaStack's architecture advisor - house stack decisions, recorded rejections, and verified platform facts. Use when designing a service or feature, choosing between architectural options ("should we add Redis/a queue/a worker"), reviewing a project's architecture, planning hosting, deployment, database schema, multi-tenancy, migrations, caching, realtime/SSE/WebSockets, background jobs, AI/agent runtimes, auth, security, or MCP surfaces, asking what the VegaStack default stack is, or verifying any claim about a platform's current capability, version, limit, or price before recommending on it. Consult it BEFORE proposing any new service, dependency, cache, or moving part. Not for creating .vegastack/dev.md or workflow knobs (dev-setup), writing or approving issues (dev-intake), picking UI components or tokens (vegastack-design-system), or first-time design-system wiring (vegastack-consume).
+---
+
+# VegaStack Dev Architect
+
+Act as VegaStack's senior architecture advisor. Brief the team the way MK would: recommend
+the smallest architecture that meets the requirement, name the trigger that justifies every
+moving part, and never gate — when the team departs from a recommendation, record it as
+accepted risk (one dated line proposed for the decision register) and keep reporting it
+honestly. VegaStack is a 3-4 person team; every extra service is maintenance someone pays for.
+
+Nearest neighbors: `dev-setup` writes `.vegastack/dev.md` including its `## Architecture`
+section — setup owns the file, this skill owns the judgment reading it. `dev-intake` routes
+stack-bearing approach choices here while writing a brief; `vegastack-design-system` owns
+component and token choices inside the UI.
+
+## Every task
+
+1. Read the `## Architecture` section of `.vegastack/dev.md`. Section or file missing →
+   answer from the repo and suggest running `dev-setup` to record it — unless the project
+   deliberately has no app architecture (a tooling/docs repo whose dev.md `stack:` line is
+   the whole truth); never create or edit dev.md here. A legacy `.vegastack/arch.md` found
+   instead: treat its lines as the Architecture facts for this task and suggest
+   `dev-setup`, which migrates it.
+2. The repository is the source of truth — package.json, lockfile, wrangler/CI files, the
+   code. The Architecture section is a head start. When they disagree, trust the repo and
+   propose the one-line section fix; never silently follow a stale line. A recorded
+   Architecture line or register decision wins over this skill's defaults for that
+   project; report a red-line crossing as accepted risk.
+3. Load only the references the task touches (table below). Do not bulk-read the set.
+4. Separate what is fact, what is assumption, and what is MK's recorded decision. A
+   directive tagged "(inferred)" is a researched extrapolation MK has not ratified —
+   confirm on first use, and a confirmation is proposed as a register line
+   (`- DD-MM-YYYY operator (<username>) — ratified: <the directive>`); recording it drops
+   the tag from the reference file in the same change, so inferred never lingers as
+   ratified-in-practice. Everything untagged is his recorded decision or a verified fact.
+   Never re-litigate a recorded decision to route around a blocker — surface the blocker.
+5. Answer at the right size: a question gets the recommendation plus at most one material
+   risk, in plain prose. Reviews and migration plans follow the review discipline in
+   [principles](references/principles.md).
+6. A directional call this work settles — one that passes the Decisions test in dev.md —
+   is proposed as one line for the register dev.md names and recorded only on the user's
+   yes; `dev-intake` and `dev-ship` own the recording mechanics.
+
+## Verify before you recommend
+
+Any decision-bearing claim about a platform or library capability, version, limit, or
+price gets grounded before it shapes a recommendation:
+
+1. Check [pinned-facts](references/pinned-facts.md) — the verified cache.
+2. Cached and verified within 60 days → use it. Older → re-verify that one fact against
+   its source URL (docs tool or web search) first, and say so.
+3. Not cached → verify against live official docs before recommending; when the fact is
+   durable and decision-changing, propose adding it to pinned-facts.
+
+Never bulk-refresh in-session. Anything unchecked is labeled UNVERIFIED. The other dev
+skills cite this protocol instead of restating it.
+
+## Route
+
+| Task touches | Read |
+|---|---|
+| "should we add X", philosophy of a decision, how to review, phrase, or record | [principles](references/principles.md) |
+| stack, vendor, or framework choice | [stack](references/stack.md) |
+| a claim about a platform's current capability or version | [pinned-facts](references/pinned-facts.md) |
+| UI, Next.js, API design | [web](references/web.md) |
+| schema, tenancy, migrations, storage, caching | [data](references/data.md) |
+| hosting, deploy, CI cost, observability, incidents | [infra](references/infra.md) |
+| realtime, SSE, WebSockets, collaboration | [stack](references/stack.md) + [web](references/web.md) |
+| AI/model calls, agents, MCP, jobs, cron, durable work | [ai-agents](references/ai-agents.md) |
+| auth, secrets, permissions, PII, external calls | [security](references/security.md) |
+| Flutter or a mobile app | [mobile](references/mobile.md) |
+
+## Red lines — never cross, regardless of project size
+
+The red lines below are the only rules that live both here and in a reference; everything
+else has exactly one home file.
+
+- Never commit, tag, push, merge, publish, deploy, or create paid/cloud resources without
+  MK's explicit go-ahead for that step. Approval for one step is not approval for the next
+  (where the dev workflow is installed, dev.md's `gates:` knob sets how many of those
+  steps one instruction covers — the knob never removes the need for an instruction).
+- Middleware/proxy (`middleware.ts` or `proxy.ts`) is never the authorization boundary.
+  Authorization lives server-side in the data-access layer, checked per resource on every
+  request (the CVE-2025-29927 bypass class is why).
+- No secret, token, or credential in plaintext — not in code, config, logs, events, or
+  agent state. Permission checks fail closed, and the deny is still audited.
+- Authentication is always Better Auth. Teams, organizations, and any "user groups" concept
+  are Better Auth constructs — never a custom parallel schema.
+- Consume the VegaStack design system; never create or modify components upstream in it —
+  that is a deliberate decision MK makes, not a side effect of a feature.
+- Never fabricate: no invented URLs, versions, benchmarks, or "verified" claims. Anything
+  unchecked is marked UNVERIFIED. Validate platform claims against official docs, not
+  training-data memory.

package/skill/dev-architect/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "VegaStack Dev Architect"
+  short_description: "VegaStack's architecture advisor: house decisions, recorded rejections, and verified platform facts"
+  default_prompt: "Use $dev-architect to make one scoped architecture recommendation for this project, reading the Architecture section of .vegastack/dev.md and the repo before recommending."

package/skill/dev-architect/references/ai-agents.md

@@ -0,0 +1,89 @@
+# AI & agents — execution, durability, model calls
+
+## The execution split
+
+- **EVE** (Vercel's `eve` — versions and beta status: pinned-facts) is the agents
+  framework for durable agent sessions. Two production shapes: self-hosted as its own
+  long-running Node/OCI service beside Postgres (durability via
+  `@workflow/world-postgres`, whose docs require a long-lived worker process), or on
+  Vercel as Functions with Fluid Compute (a recorded per-project hosting exception).
+  Never inside an OpenNext Worker or any request-scoped/edge function, and in production
+  never the local on-disk workflow files.
+- **pg-boss** owns everything that is *not* an agent session: background jobs, cron,
+  scheduled work — dispatcher-only, lease/heartbeat/retry state in our own tables
+  (stack.md). EVE and pg-boss share the same Postgres but are logically separate;
+  `@workflow/world-postgres` is not pg-boss and replaces nothing.
+- Long-running pipelines that are neither (e.g. an hours-long transcription poll) may use
+  Cloudflare Workflows when already on Cloudflare — a recorded per-project decision, not
+  a default; note per-step billing (pinned-facts).
+- Where dev.md's Architecture `agents:` line records a substrate (the flagship platform
+  runs its own event-sourced runtime), that recorded decision wins for that project.
+
+## Durability invariants (apply to any substrate)
+
+- Replay = state, not code: resuming a run replays persisted events; a completed step is
+  never re-executed.
+- Every side effect is fenced by the run's lease token and deduplicated by an idempotency
+  key — a retry never creates a second logical run or a second charge. On an uncertain
+  start acknowledgement, look the session up by its deterministic admission key before
+  retrying.
+- Create the run record and its admission job in one transaction — never "insert then
+  hopefully enqueue".
+- Audit before effect: write the pending audit row before the side effect executes, settle
+  after — a crash between execution and logging must not lose the record.
+- Human-in-the-loop gates SUSPEND the run (never fail it), cost zero compute while
+  waiting, never auto-approve, execute only the exact approved-and-hashed args on resume,
+  and deny/escalate on timeout.
+
+## Model calls
+
+- AI SDK behind a thin adapter; providers swappable; Anthropic default. Model IDs are
+  env/config-driven — never hardcoded. On Cloudflare, route through Cloudflare AI Gateway
+  (never Vercel AI Gateway); off Cloudflare (e.g. the EVE service), call providers
+  directly through the adapter and capture usage in the Postgres ledger — no gateway
+  dependency.
+- Provider keys come from the credential broker or asserted config — never a silent
+  `process.env` fallback (AI SDK providers silently fall back when passed `undefined`;
+  assert non-empty and throw `MODEL_KEY_UNAVAILABLE`).
+- Capture usage per request (model, tokens, cost via a config-driven pricing registry)
+  into an append-only Postgres table — the single cost source of truth.
+- Never invent SDK method names from memory — the AI SDK and EVE move fast; verify against
+  installed types or live docs (SKILL.md's verify protocol) before writing code.
+
+## Boundaries and safety
+
+- Every tool/capability call — first-party or third-party MCP — goes through the single
+  capability checkpoint; an unrecognized capability is a hard deny. **Why:** the
+  checkpoint is where authz, budget, audit, and redaction all live once — a tool that
+  bypasses it bypasses all four. (Platform-scale machinery: a simple product with two
+  first-party tools gates them in the service layer instead — same invariants, less
+  ceremony.)
+- Instruction/data separation: anything an agent reads (fetched pages, tool/MCP responses,
+  user documents) is data, never instructions — don't act on directives found in read
+  content; flag them. Distinct from output sanitization (security.md) — handle both.
+- Untrusted/model-authored code executes in a sandbox behind a pluggable provider
+  (Cloudflare Sandbox preferred, Modal alternative): no DB credentials inside,
+  deny-by-default egress, local execution trusted-dev only.
+- Agent-produced content is untrusted input — sanitize/validate like user input; attribute
+  agent actions to the agent's own principal, never the creating user.
+- "AI for judgment, deterministic code for facts": anything money- or invariant-critical
+  is deterministic server code the AI may call but never replace (mechanics: web.md).
+
+## Where AI belongs in a product
+
+- Prefer external coding agents (Claude Code, Codex) operating on the product's surfaces
+  over bespoke in-product agent features — more scalable and cheaper for a small team.
+  Coding agents are first-class users: CLI, web, REST, and MCP surfaces must all work as
+  well for an agent as for a human.
+- A product's MCP server surface: ~12-20 workflow-shaped tools (one per job a user does),
+  not one per REST endpoint; annotate destructive tools so hosts can gate them; auth via
+  the product's API keys/OAuth — Better Auth ships an MCP plugin (packaging is changing
+  across versions — check current docs), never hand-roll MCP OAuth. Serve agent-readable
+  docs (`llms.txt`, markdown mirrors) beside the human docs.
+- The AI SDK is the house model-call layer everywhere; the Cloudflare Agents SDK is
+  DO-based stateful-agent infrastructure — consider it only for a Cloudflare-native
+  product that has already earned Durable Objects, and record the decision (inferred —
+  confirm on first use).
+- Evals gate promotion when a product ships model-driven behavior: versioned dataset +
+  scoring + explicit threshold; a failing eval blocks activation. No eval infrastructure
+  for products with no model-driven behavior.

package/skill/dev-architect/references/conventions.md

@@ -0,0 +1,93 @@
+# Workflow conventions
+
+The single spec for the artifacts every dev-family skill reads and writes. One home per rule: skills cite this file, never restate it. Everything here is harness-neutral.
+
+## Comment metadata markers
+
+Every workflow-generated issue comment opens with an invisible HTML marker followed by a human heading:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan>` | one per approval event |
+| `plan` | `rev` | one, edited in place |
+| `ledger` | `branch` | one, edited in place |
+| `evidence` | `rev branch sha` | one, edited in place |
+| `review` | `round sha agent=<claude\|codex> verdict=<clean\|needs-fixes>` | one per review cycle, rounds appended inside |
+| `decision` | — | one per decision proposal |
+| `handback` | — | one per stop event |
+
+`rev=<n>` and the matching `(v<n>)` heading suffix appear only on revisable artifacts — the brief (issue description), `plan`, and `evidence` — starting at `rev=1`/`(v1)`. Single-event comments (`approval`, `decision`, `handback`) and the `ledger` carry neither. Scripts and agents locate comments strictly by marker, never by heading text. A comment without its marker does not count as the artifact — there is no legacy fallback.
+
+## Operator identity
+
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+
+- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+
+## Revision markers
+
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+
+## Scope classes
+
+Set at intake, applied as a label, announced with its reason (operator can override):
+
+- **`research`** — a question to answer; throwaway code allowed, never merged. No branch/PR/changelog; findings + recommendation are the evidence comment.
+- **`quick-build`** — small change and the flow being changed already exists in the repo to read. Brief (description) + plan (comment) are drafted in the same conversation; **one approval covers both**; then straight to `ready`.
+- **`full-plan`** — big or new ground. Brief approval → `needs-plan` → a separate, fresh-grounded planning session posts the plan → `needs-operator` → "plan approved" → `ready`. Multi-deliverable work becomes an epic; each sub-issue is classified independently.
+
+Scope calls are revisited through the one-way ratchet, whose rules and mechanics live in the `dev-plan` skill — the one home for upgrade/downgrade behavior.
+
+## Labels
+
+State — exactly one per issue (creation colors live in dev-setup's labels row, their one home):
+
+| label | meaning |
+|---|---|
+| `needs-operator` | waiting on the operator: a question, a brief or plan to approve, a proposal |
+| `needs-plan` | brief approved; waiting for the planning stage (full-plan only) |
+| `ready` | fully approved — an agent may start |
+| `working` | claimed, in progress; the ledger comment shows live progress |
+| `for-operator` | done — evidence posted, awaiting operator review |
+
+Modifiers (may coexist with the state label): `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents, only where the org has no native Epic issue type).
+
+## Titles, types, hierarchy
+
+- **Title prefixes** on issues, branches, and PRs identically: dev.md's `branch:` knob type list (that knob stays the list's one home) plus `research:` for research issues. PR title = issue title.
+- **Native issue types** where the org defines them: Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (label fallback otherwise).
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far as one-line gists · Not clear yet · Out of scope), children attached as native sub-issues; issues = the unit of work (brief in description, own approvals/branch/PR/evidence); tasks = checkboxes **in the plan comment only**. Blockers use native issue dependencies; phases use milestones. Only issues — never epics — get `ready`. GitHub caps issue bodies and comments at ~65,536 characters; what a plan nearing that cap means is the `dev-plan` ratchet's call.
+
+## The ledger
+
+Maintained by the implement session as one comment, edited in place:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- Task <N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- Task <N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- Task <N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+**Resume protocol:** a fresh, compacted, or (operator-handed) takeover session reads, in order: the brief → the plan comment → the ledger → `git log` on the branch — **nothing else**. Tasks with a `complete` line are DONE, never re-executed; a task whose last line is a fix round resumes at the next round. After compaction, trust the ledger and `git log` over recollection. Every `Ruling:` line surfaces in the evidence comment — a ruling that dies with the session was a decision made in secret.
+
+## `.vegastack/.tmp/` workspace
+
+All transitory artifacts — subagent reports, review packages, plan drafts, extracted diffs — live at `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue intake drafts, which have no number yet: `.vegastack/.tmp/intake-<slug>/`), kept out of git by a self-ignoring `.gitignore` (`printf '*\n' > .vegastack/.tmp/.gitignore`, created on first use). Subagents write full reports to files there and return only short status — a dead subagent's findings survive on disk, and the primary session never holds full reports in context. The workspace lives in the working tree (never under `.git/`, which harnesses protect from writes).
+
+## Verification gate
+
+Before claiming any status: **IDENTIFY** the command that proves the claim → **RUN** it fresh and complete → **READ** the full output and exit code → only then claim, with the evidence. "Should pass", a previous run, or a subagent's say-so are never evidence. Guard scripts follow the same doctrine: machine-verifiable facts **block** (exit 2 with the reason); regex or judgment heuristics only **warn** — no AI inference inside guards, and an unverifiable state fails closed.
+
+## Plain-language collaboration
+
+Every skill run ends with a simple-language summary: what happened, which paths were taken — cross-agent invocations announced at trigger time AND summarized at the end — and what is worth the operator double-checking. Use mermaid or ASCII diagrams in issues wherever a picture beats prose. A vague or self-contradicting operator answer gets pushback with concrete options, never silent absorption.

package/skill/{architect → dev-architect}/references/data.md

@@ -3,79 +3,78 @@
 ## Database
 
 - PostgreSQL, always managed by us (a PlanetScale Postgres server or self-hosted
-  Hetzner/self-managed) — never Neon. Target PG 17 behind Hyperdrive (18 unsupported there),
-  17/18 elsewhere. Drizzle ORM with the single `postgres-js` driver — never mix in `pg`.
-  Stay on GA/stable majors of core DB deps (Drizzle v1 is still RC as of 2026-08 — the
-  0.4x line remains the pin until v1 is stable); verify vendor version-support claims
-  against live docs before locking a decision.
+  Hetzner-class) — never Neon. Behind Hyperdrive, target the highest Postgres major
+  Hyperdrive supports (pinned-facts — PG 18 is a known trap). Drizzle ORM with the single
+  `postgres-js` driver — never mix in `pg`. Stay on GA/stable majors of core DB deps;
+  verify vendor version-support claims per SKILL.md's verify protocol before locking a
+  decision.
 - From Workers: Hyperdrive binding + per-request client (`prepare: false, max: 1`,
   request-scoped via the execution context) — a module-level pool in a Worker or Durable
   Object is a bug, not a style choice (workerd forbids cross-request I/O). One Hyperdrive
-  per environment shared across services hitting the same database — never one per service.
-  On long-running Node services (Docker), pool normally.
+  per environment shared across services hitting the same database — never one per
+  service. On long-running Node services (Docker), pool normally.
 - Migrations run via CI only, never pushed from a dev machine — with one loud exception:
   pre-launch databases with zero real users get clean resets instead of migration chains
-  (see principles.md). Runners apply in journal order and are idempotent on re-run.
-  Iterate schema with `db:push` during development; run `db:generate` exactly once right
-  before shipping — repeated generates mid-iteration create conflicting DDL.
+  (principles.md). Runners apply in journal order, idempotent on re-run. Iterate schema
+  with `db:push` during development; run `db:generate` exactly once right before shipping
+  — repeated generates mid-iteration create conflicting DDL.
 
 ## Multi-tenancy
 
 - Shared schema with RLS, not database-per-tenant: every tenant-scoped table (and every
   partition) gets `ENABLE` + `FORCE` ROW LEVEL SECURITY, driven by exactly one fail-closed
-  GUC accessor (`NULLIF(current_setting('app.current_org_id', true), '')::uuid`), defined in
-  one idempotent migration location.
+  GUC accessor (`NULLIF(current_setting('app.current_org_id', true), '')::uuid`), defined
+  in one idempotent migration location.
 - RLS is one layer, never the only layer: every query also scopes explicitly by
   `org_id`/`workspace_id` in the data-access layer. Two roles — the app role has no
   `BYPASSRLS`; a separate system role does. `withOrgContext`/`withSystemContext` (or
-  equivalent) are the only query entry points; the raw client is never exported.
-  **Why:** RLS misses TimescaleDB chunks and misconfigurations fail open; two independent
-  layers fail closed.
-- Tenant identity comes from the authenticated principal, never from client-supplied
-  payload fields (a client-supplied `workspaceId` query param over the authenticated
-  context caused a real cross-tenant IDOR — reject on mismatch).
+  equivalent) are the only query entry points; the raw client is never exported. **Why:**
+  RLS misses TimescaleDB chunks and misconfigurations fail open; two independent layers
+  fail closed.
+- Tenant identity comes from the authenticated principal, never client-supplied fields —
+  the IDOR precedent and rule live in security.md.
 - Better Auth's organization plugin owns the workspace/member/invitation schema
-  (organization ↔ workspace naming remap is the house pattern); its columns stay snake_case
-  as generated. Native `uuid` columns — Better Auth does not force text IDs.
+  (security.md); its columns stay snake_case as generated, with native `uuid` columns —
+  Better Auth does not force text IDs.
 
 ## Caching
 
 - No cache layer by default: rate limiting, dedupe, and most "cache" needs are
-  Postgres-native. Workers KV only with a named trigger; any Redis-class store
-  (Valkey/Upstash) is optional and **never correctness-bearing**.
+  Postgres-native. Workers KV only with a named trigger; any Redis-class store is
+  optional and **never correctness-bearing**.
 - Never let auth, role, or permission data live in a cache long enough to serve stale
-  permissions — a revoked member seeing tenant data is a security bug, not a staleness bug.
-- Anything cached must have a defined story for cache outage (fall back to DB, not to
+  permissions — a revoked member seeing tenant data is a security bug, not a staleness
+  bug. Anything cached has a defined cache-outage story (fall back to DB, never
   stale-forever).
 
 ## Search, knowledge, files
 
 - Search and embeddings live in Postgres itself: `STORED` generated `tsvector` + GIN for
   full-text; pgvector (`halfvec` + HNSW, `hnsw.iterative_scan = relaxed_order`) for
-  embeddings; hybrid fusion via RRF (k=60 starting constant). Embedding model default:
-  BGE-M3 self-hosted; bulk embedding calls skip the AI Gateway (the one carve-out from
-  the blanket gateway rule). No dedicated vector DB or SaaS search service.
-- Object storage: R2 by default, always behind an S3-compatible storage layer so AWS
-  S3/Azure Blob/MinIO work for licensed self-hosted deployments. Short-lived scoped access
+  embeddings; hybrid fusion via RRF (k=60 starting constant). Embedding default: BGE-M3
+  self-hosted; bulk embedding calls skip the AI Gateway (the one carve-out from the
+  blanket gateway rule). No dedicated vector DB or SaaS search service.
+- Object storage: R2 by default, always behind an S3-compatible layer so AWS S3/Azure
+  Blob/MinIO work for licensed self-hosted deployments. Short-lived scoped access
   (presigned), size/type validation on upload. Keys never expose raw user/workspace IDs —
   documented prefix + nanoid (`wl_`, `ua_` style).
-- Blob GC deletes the storage object before the DB reference row — a crash mid-delete must
-  never leave a live dangling reference.
-- TimescaleDB is opportunistic, never required: feature-detect the extension and fall back
-  to native `PARTITION BY RANGE` + BRIN in the same migration, so self-hosted installs work
-  on plain Postgres.
+- Blob GC deletes the storage object before the DB reference row — a crash mid-delete
+  must never leave a live dangling reference.
+- TimescaleDB is opportunistic, never required: feature-detect and fall back to native
+  `PARTITION BY RANGE` + BRIN in the same migration, so self-hosted installs work on
+  plain Postgres.
 
 ## Schema discipline
 
 - Extend an existing table before creating a new one; when two tables serve the same job,
-  merge. Keep sync (`*_change_log`), audit (`audit_log`), and versioning (`*_revisions`) as
-  three separate, non-overlapping tables — never substitute one for another.
+  merge. Keep sync (`*_change_log`), audit (`audit_log`), and versioning (`*_revisions`)
+  as three separate, non-overlapping tables — never substitute one for another.
 - IDs: one global helper — UUIDs (v7 where ordering matters) internal, prefixed nanoids
-  public-facing. Timestamps `timestamptz` UTC; money integer minor units; durations integer
-  ms. Prefer checked text over Postgres enums for evolving vocabularies.
-- Index tenant and foreign keys; paginate by cursor; select only needed columns.
-- Secrets and PII never sit in plaintext columns (including inside JSONB) — broker-wrapped
-  envelope encryption only (see security.md).
+  public-facing. Timestamps `timestamptz` UTC, rendered in the user's timezone; money in
+  integer minor units; durations integer milliseconds. Prefer checked text over Postgres
+  enums for evolving vocabularies.
+- Secrets and PII never sit in plaintext columns (including inside JSONB) —
+  broker-wrapped envelope encryption only (security.md).
 - JSONB-on-row vs. dedicated table has no house default — MK has ruled both ways by
   context. Present the tradeoff (volume, query needs, audit requirements) and ask.
 
@@ -84,7 +83,7 @@
 - Self-managed Postgres ships with WAL archiving + scheduled base backups from day one —
   a database without a tested restore path is not production, whatever else is true.
 - A restore runbook (where backups live, how to restore, measured time) is a phase-0
-  deliverable for any live product; state RPO/RTO per project in `.vegastack/arch.md`
-  notes. Test the restore, don't assume it (verification honesty applies to backups too).
+  deliverable for any live product; note RPO/RTO in dev.md's `## Architecture`. Test the
+  restore, don't assume it.
 - R2/object storage: no bucket versioning by default — deletion protection is the
-  object-before-row GC discipline above plus lifecycle rules, planned explicitly.
+  object-before-row GC discipline plus lifecycle rules, planned explicitly.

package/skill/dev-architect/references/infra.md

@@ -0,0 +1,98 @@
+# Infra — hosting, CI cost, observability
+
+## Hosting targets
+
+Two sanctioned targets, recorded in dev.md's `## Architecture`:
+
+- **Cloudflare Workers via OpenNext** — the default for public web products. Once
+  committed to Cloudflare, never stand up a parallel Vercel deploy path (deploy paths
+  drift); shared packages must still *work* on Vercel for downstream consumers —
+  portability, not a deploy target.
+- **Self-managed servers** (Hetzner-class, Docker; Coolify for push-to-deploy) — when
+  self-hosting is a product requirement, the workload needs long-lived processes (EVE,
+  heavy workers), or platform independence justifies ~30 min/month of real ops.
+- Vercel only by explicit, recorded per-project exception (e.g. EVE-hosted workloads).
+  Internal/admin apps needing no edge features may run plain `next start` in Docker —
+  OpenNext is the default, not a ritual.
+
+## Cloudflare discipline
+
+- Provision only what the current phase uses. Queues, KV, Durable Objects, Workflows are
+  trigger-gated — DO when live collaboration actually ships, Queues when webhook/event
+  volume is real — never scaffolded ahead of need. Delete stale Workers, Hyperdrive
+  configs, and buckets, with an explicit create/delete accounting first.
+- Multi-env via the Workers environments feature (`env.*`) — never separate top-level
+  Workers per environment; environments are `dev` / `preview` / `production`, and the
+  `staging` git branch deploys to `preview`. One Hyperdrive per environment, shared by
+  every service hitting the same database. Naming: hyphen-only; purge inconsistent legacy
+  names.
+- Domains: production on `vegastack.com`; non-prod under `*.vegastack.dev`. Every Worker
+  sets `workers_dev: false` + `custom_domain: true` — the default `*.workers.dev` origin
+  bypasses Cloudflare Access, exposing a gated Worker unauthenticated (security, not
+  cosmetics). Preview environments access-protected by default; only production is public.
+- Secrets per environment (`wrangler secret put X --env production`). Local env files:
+  `.env` feeds `next dev`, `.dev.vars` feeds `wrangler dev` — both gitignored, both with
+  committed `.example` companions.
+- No Cloudflare Images — optimize with `sharp` at build/upload time and serve from R2 (the
+  paid add-on solves a problem `sharp` + free egress already solve).
+- Runtime constraints are architectural facts: no TCP clients, per-request DB connections
+  (data.md), and OpenNext trails vanilla Next.js — check OpenNext docs per feature
+  (current adapter caveats: pinned-facts).
+- Edge/CDN caching never bypasses live authorization — revoked, expired, or
+  password-protected content is re-checked even when the artifact is cached.
+- Cloudflare Tunnel is the default for exposing self-hosted services and remote dev
+  previews (already paid for). Cloudflare Access gates paths by data sensitivity with
+  email allowlists — not one site-wide gate.
+
+## Self-managed discipline
+
+- Containers hardened: non-root user, `cap_drop: [ALL]`, `read_only: true` where runtime
+  paths allow; healthchecks on every service. Migrations and storage provisioning run in
+  the app container's own entrypoint under a Postgres advisory lock (safe when replicas
+  race on boot) — not a separate bootstrap deployable unless a project records why.
+- Ship `docker compose up` as the self-host story: bundle only Postgres + MinIO-class
+  essentials; everything else (vector store, gateway, vault) is connect-your-own.
+- Server sizing: SSD, compute, and RAM over disk capacity, within the budget MK states for
+  that server (ask if none stated — don't guess); Coolify's own footprint: pinned-facts.
+  Cloud infra beyond Cloudflare goes through Terraform, IAM scoped narrowly per purpose.
+- Any infra cleanup (disks, stale resources, runners) needs explicit authorization first,
+  scoped to verified-stale items — never blanket cleanup.
+
+## CI cost and verification (workflow gates and ship mechanics live in dev.md)
+
+- CI is cost-managed, not maximal: path-condition expensive jobs so docs-only changes skip
+  them; push heavy verification into local hooks and self-hosted runners; hosted Actions
+  minutes are a tracked budget. Verification is local-first — CI verifies it happened via
+  a committed receipt bound to the git tree hash rather than re-executing browser suites;
+  a receipt is attestation, not proof — skipping a gate becomes visible, not impossible.
+- Wire every architectural guard script (import boundaries, runtime gravity, route-wrapper
+  ratchet) into the one composed check command — a separate script someone forgets to run
+  doesn't exist.
+- Green CI is necessary, never sufficient: a unit is done after a real
+  boot → auth → reach → mutate → verify pass against live infra. On CI failure: diagnose
+  and report the root cause first; fix second.
+
+## Observability (small-team baseline)
+
+- Structured JSON logs (pino) to stdout with OTel-shaped fields (trace/request/org context
+  auto-injected) — OTel-compatible by convention now; the full OTel SDK/collector only
+  when cross-service trace correlation becomes a real pain.
+- The append-only Postgres event log is the authoritative telemetry source; metrics/log
+  tables are derived and disposable (30-day raw, 13-month rollups, compress after ~7 days;
+  TimescaleDB opportunistic with partition+BRIN fallback).
+- On Cloudflare, use the built-in free tier first — Workers Logs and the analytics
+  dashboard (current limits and billing dates: pinned-facts).
+- Alerting honest to team size: an uptime monitor (Uptime Kuma-class) + a cron checking
+  error-rate thresholds in the event table posting to Slack, plus a dead-man's-switch ping
+  for silent job failures. No paging/SLO/on-call ceremony — deliberately undefined until
+  the team needs it; propose per project, don't invent doctrine.
+
+## Incidents
+
+- Active production incident: diagnose first (root cause with evidence), fix second — the
+  standing rule applies under pressure too. Rolling back a deploy IS a deploy: it needs
+  MK's go-ahead — bring him the evidence and the recommended rollback; mitigation that
+  doesn't deploy (feature-level disable, traffic block) can proceed and be reported.
+- Every real incident gets a short postmortem in the project's `docs/postmortems/`: what
+  happened, root cause, the guard that now prevents it. An incident that doesn't change a
+  rule or a check will repeat.