feat: backend MVP

.agents/skills/hyperbug-development/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: hyperbug-development
+description: "Implement or fix HyperBug product features, backend contracts and adapters, or frontend workflows according to the repository plan. Use for feature development and application behavior changes; use hyperbug-maintenance for dependency upgrades, migrations, releases, and operational recovery."
+---
+
+# HyperBug Development
+
+Develop the requested HyperBug capability within its accepted architecture and delivery gates. This is repository-specific guidance; it does not authorize unrelated features or deployment.
+
+## Begin with the current state
+
+Read [root guidance](../../../AGENTS.md), [master progress](../../../docs/plan/PROGRESS.md), and [session handoffs](references/session-handoffs.md). Identify the owning module and read its plan and latest progress entry before editing. Source policies and their refinements are indexed in [SOURCES](../../../docs/plan/SOURCES.md).
+
+G0 must pass before application work. Complete the backend acceptance gate in module 10 before starting the product SPA; each post-MVP feature also accepts its backend before its UI. Backend-owned authorization pages and minimal protocol test fixtures are distinct from product SPA work.
+
+Use the selected checklist IDs to bound the change. Inspect existing package scripts and implementation rather than treating planned paths, command names, or source version snapshots as installed facts.
+
+## Read only the relevant references
+
+| Work | Reference |
+| --- | --- |
+| Endpoints, domain/application services, persistence adapters, queues, or plugins | [Backend development](references/backend.md) |
+| Static SPA, browser auth, forms, components, or backend-owned HTML | [Frontend development](references/frontend.md) |
+| Authentication, permissions, credentials, content, uploads, trust boundaries, or review/ADR decisions | [Security and review boundaries](references/security.md) |
+| Selecting verification or deciding acceptance | [Testing and evidence](references/testing.md) |
+| Any session start, checkpoint, or finish | [Session handoffs](references/session-handoffs.md) |
+| A feature needs a schema/data migration | [Database changes](../hyperbug-maintenance/references/database-migrations.md) |
+
+## Implement and close the batch
+
+Keep domain/public contracts independent of runtime infrastructure. Share product, authorization, and consistency semantics across both production profiles; allow optimized adapter implementations. Backend writes need server validation, object permissions, required audit/timeline events, and bounded work from their first implementation.
+
+Fetch current library documentation and relevant web guidance using the rules in root guidance. Record unresolved assumptions instead of silently weakening a baseline or changing the chosen stack.
+
+Verify the changed behavior and affected contracts using the testing reference. Update relevant specifications and guidance in English. Complete only evidence-backed checklist items, then record progress, changed files, verification, next actions, and next-session cautions in every affected progress record. Follow the session reference even when the batch only investigated a failure.

.agents/skills/hyperbug-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HyperBug Development"
+  short_description: "Develop HyperBug within its architecture and plan"
+  default_prompt: "Use $hyperbug-development to implement the next eligible HyperBug checklist item and record the session handoff."

.agents/skills/hyperbug-development/references/backend.md

@@ -0,0 +1,32 @@
+# Backend development
+
+Read for backend features, API contracts, repositories, queues, and plugins. Use [SOURCES](../../../../docs/plan/SOURCES.md) to locate TECH-STACK §§3–30, 38–54, the relevant PRODUCT scope, and the owning [module](../../../../docs/plan/README.md#module-index).
+
+## Boundaries that determine implementation
+
+- Domain entities and public schemas have no infrastructure dependencies. Application services use repository/security/blob/queue/workflow ports. Adapters implement the ports; runtime composition roots supply them.
+- Share Elysia routes and middleware in the server package. Runtime startup belongs in the Workers/Node entry points; D1 bindings, PostgreSQL pools, R2 buckets, S3 clients, and workflow objects must not leak into the domain.
+- Publish versioned REST/OpenAPI and framework-independent DTOs. Clients do not import server implementation types or require Elysia to consume the contract.
+- Keep Cloudflare and self-host behavior equivalent while allowing separate SQL, FTS, indexes, transactions, and infrastructure integrations. Resolve package/API details through current documentation; do not assume Node tooling capabilities exist in Workers.
+- Preserve User/Staff separation, project-local Issue numbers, simple Open/Closed state, and optional provider integrations. Core is usable without an email, SSO, or CAPTCHA plugin.
+
+## Complete a backend capability
+
+Choose the owning checklist and define the request/response/error contract, object permissions, invariant, transaction intent, event/audit requirements, and resource bounds before exposing the route.
+
+Implement domain/application behavior, each required repository adapter, route validation/error mapping, and contract evidence as one coherent feature. Where a mutation needs timeline/audit/outbox records, prove the intended atomic outcome. A zero-row conditional update is not automatically an exception or rollback.
+
+Use [database changes](../../hyperbug-maintenance/references/database-migrations.md) for schema work and [security](security.md) for credentials, permissions, content, or trust boundaries.
+
+## Query and side-effect decisions
+
+Use bounded keyset/cursor pagination with stable unique tie-breakers and indexes matched to filter/sort/join patterns. Batch hydration rather than querying relations per result. Keep the structured search AST independent of FTS5 and PostgreSQL syntax and enforce current authorization even with stale indexes.
+
+Record non-critical effects through the outbox/queue path. Assume at-least-once execution; bound fan-out/retries/concurrency and retain recoverable failures. Workflow steps need bounded checkpoints and replay-safe writes. See modules 08–09 for index dispatch and workflow handoffs.
+
+Use upload intents, direct object-store upload, and verified finalization; do not buffer ordinary uploads through the API. Check object identity/immutability as well as declared metadata. Native plugins are trusted application code; declared permissions are not a sandbox.
+
+## Acceptance
+
+Use [testing](testing.md) to select both-runtime contract, authorization, concurrency, migration, and resource-bound checks. Record real versus emulated results and unresolved profile differences. Update public specifications/client contracts where affected and finish the [session handoff](session-handoffs.md).
+

.agents/skills/hyperbug-development/references/frontend.md

@@ -0,0 +1,36 @@
+# Frontend development
+
+Read for product SPA work and backend-owned HTML/auth fixtures. First inspect G1 in [master progress](../../../../docs/plan/PROGRESS.md). Before G1 passes, work on the relevant backend contract/test fixture; do not scaffold the product SPA. A post-MVP feature needs its own backend acceptance before UI work.
+
+## Research and compatibility
+
+Follow root Context7 rules for the selected React/TanStack/Vite/UI APIs. Use the available modern-web-guidance skill before relevant HTML/CSS/client-side work: action-oriented search, relevant guide retrieval, then implementation/fallback review. Use its current instructions rather than hard-coding an old skill-version command here.
+
+Record guide IDs, lookup date, feature status, and fallback in the owning progress entry or linked design record. If guidance is unavailable, record the gap; do not claim compliance based on a remembered guide.
+
+The project baseline is Baseline Widely Available and WCAG 2.2 AA. Newly Available features require detection and usable fallback; Limited Availability cannot become a core dependency without the specified decision/review. Avoid blanket polyfills. Browser support does not replace keyboard, screen-reader, touch, zoom, contrast, and reduced-motion checks.
+
+## Static application and state
+
+The build must run on generic static hosting and Cloudflare Pages without SSR, Pages Functions, or a mandatory proxy. Runtime configuration contains public values only and can change the API origin without recompilation. Align deployment CSP with configured API/auth/media origins.
+
+Use Router for URL/navigation state, Query for remote state, Form for form state, and React for local UI. Preserve shareable filters/sort/search, back/forward behavior, request cancellation, and bounded cache/page accumulation. Invalidate or partition user-specific state on identity changes.
+
+Browser access tokens remain in memory; no localStorage, sessionStorage, IndexedDB, or persistent refresh token. Use top-level PKCE recovery and business API requests with omitted credentials. Short-lived one-shot redirect state/verifiers are distinct from access tokens and follow module 11's policy. Cookie-backed authorization pages retain their own CSRF defenses.
+
+## Forms, content, and interaction
+
+Use semantic controls, visible labels, associated help/errors, server-error mapping, and deliberate focus management. Coordinate visual/ARIA validation after interaction, handle IME composition, and keep drafts recoverable without leaking them across principals. Browser validation does not replace backend validation.
+
+Render Markdown through the shared versioned sanitizer after raw HTML parsing; never introduce a separate feature allowlist. Upload directly through the accepted intent/finalize protocol and show safe retry/expiry/quota outcomes.
+
+Native dialogs or established accessible primitives must provide focus placement/restoration, Escape where appropriate, and explicit close/cancel. Additional platform dismissal gestures are progressive enhancements.
+
+Profile long timelines before optimizing. If applying content-visibility to confirmed offscreen content, reserve intrinsic size, verify sequential keyboard/find-in-page behavior, and retain ordinary rendering without support. Keep optional provider/admin resources out of the initial bundle when practical.
+
+## Adapt guidance to HyperBug
+
+Do not copy guide examples that add SSR fallback, cookie-based business authentication, inline script handlers, relaxed CSP, or a second sanitizer. Reviewed provider SDK origins differ from arbitrary remote plugin JavaScript. Native plugin UI is build-time composition.
+
+Sources: ARCHITECTURE §§7–21, SECURITY §§7–20, 40–61, and PERFORMANCE §§25–34 via [SOURCES](../../../../docs/plan/SOURCES.md). Apply [testing](testing.md) and [session handoffs](session-handoffs.md) to close the work.
+

.agents/skills/hyperbug-development/references/security.md

@@ -0,0 +1,29 @@
+# Security and review boundaries
+
+Read when work changes security behavior or when deciding review/ADR scope. Authoritative requirements are in SECURITY and PERFORMANCE through [SOURCES](../../../../docs/plan/SOURCES.md); this reference routes decisions rather than replacing those baselines.
+
+## Core policy checks
+
+| Change surface | Invariants and source sections |
+| --- | --- |
+| Identity/auth | User and Staff are distinct; email matching grants no Staff privilege. PKCE S256, exact redirects, one-use codes, short-lived opaque tokens, immediate revocation, and first-party authorization sessions. SECURITY §§7–44. |
+| Authorization | Check object/project permissions on the server, including searches and delayed jobs. Fail closed on verification errors; require assurance/recent authentication where specified. SECURITY §§35–39, 141, 158–159. |
+| Credentials/keys | Hash non-recoverable credentials; use mature crypto and AES-256-GCM envelope encryption for recoverable secrets, contextual AAD, unique nonces, key IDs/rotation. Do not lower memory-hard password parameters to fit a runtime. SECURITY §§28–34, 67–91, 148–150. |
+| Content/uploads | Final tree sanitization after raw HTML parse; centralized versioned policy. Reauthorize uploads/finalization, verify actual objects, isolate dangerous media, and prevent post-validation overwrite. SECURITY §§53–66, 99–105. |
+| Cross-origin/cache | Explicit origins; no ambient cookies for business APIs; CSRF protection for cookie flows. Never reuse private responses through shared caches or weaken CSP for an ordinary plugin. SECURITY §§40–52, 132–136. |
+| External/plugin | Central SSRF/redirect/size/timeout limits; scoped secret/capability access. Native code is trusted, not sandboxed; plugins cannot disable Core policy. SECURITY §§92–98, 106–123. |
+| Audit/retention | Redact logs/errors; required security actions get append-only audit records. Bound and document retention without silently deleting audit history. SECURITY §§110–116, 139–149. |
+
+CORS is not authentication, CAPTCHA is not authorization, and a cache hit is not a permission check. Provider failure cannot mean successful security verification. Do not claim uploads were scanned without a scanner or full PQ authentication from hosting alone.
+
+## Review and decision routing
+
+- Apply focused security review to authentication/authorization, crypto/password/token storage, sanitization, CSP/CORS, uploads, plugin runtime, outbound fetch, SSO/CAPTCHA, and KMS changes (SECURITY §154). Ordinary feature work does not automatically require a separate exhaustive repository audit.
+- Write a security ADR for a new auth flow, persistent browser credential, cipher/password algorithm/key provider, plugin execution model, weaker CSP, raw HTML capability, cross-origin trust, or public-key signature algorithm (SECURITY §155).
+- Deviations from SECURITY MUST/MUST NOT require both an ADR and security review (§2). Resolve uncertainty explicitly before embedding a weaker behavior.
+- Review hot queries/indexes, list/search/pagination, bulk/cache/fan-out, plugin hooks, uploads/import/export, auth cost, and large dependencies for performance (PERFORMANCE §75).
+- Record an ADR for pagination/cache/search/replication/denormalization architecture, sync-to-async shifts, coordination objects, changed queue delivery semantics, or a large persistent frontend dependency (PERFORMANCE §76); core framework/database/service/browser-baseline changes also follow ARCHITECTURE §49.
+- Record review evidence and rationale in the owning module's progress entry or linked decision file. A review requirement is not automatically a new user-approval requirement for routine authorized implementation.
+
+Use [testing](testing.md) for adversarial acceptance evidence and the maintenance [deployment reference](../../hyperbug-maintenance/references/deployment.md) for operational key/incident work.
+

.agents/skills/hyperbug-development/references/session-handoffs.md

@@ -0,0 +1,27 @@
+# Session handoffs
+
+This is the shared session reference for both project skills. The canonical checklist, status definitions, and entry template are in [EXECUTION](../../../../docs/plan/EXECUTION.md); read it instead of creating a competing log format.
+
+## Start
+
+Read [master progress](../../../../docs/plan/PROGRESS.md), the owning [module plan](../../../../docs/plan/README.md#module-index), its same-named file under `docs/plan/progress/`, and affected prerequisite records. Inspect actual files/versions/uncommitted changes. Record the intended stable checklist IDs and verify gates before dependent work.
+
+For maintenance, use the module that owns the changed artifact: foundation/dependencies 01, persistence 02, security 03–04, content 07, async 09, deployment/recovery 13, or the relevant feature/integration module. A multi-module change updates every affected record. Use [COVERAGE](../../../../docs/plan/COVERAGE.md) for ownership; do not execute unrelated future modules just to obtain a log owner.
+
+## Checkpoint
+
+Update the current status and append or update the current session entry after a meaningful batch, a decision/failure/blocker, or before handing off context. Record partial completion honestly and leave unfinished checkboxes unchecked. Preserve earlier session history.
+
+## Finish every session
+
+Append a concise English entry with the [required template](../../../../docs/plan/EXECUTION.md#required-session-entry-template):
+
+- Scope/checklist IDs, actual progress, and a summary of what changed.
+- Changed paths/artifacts and commands/checks with environments, results, and evidence; state explicitly when a check was not run.
+- Decisions/deviations and blockers with concrete resolution steps.
+- Ordered next actions and next-session cautions: unfinished migrations, version uncertainty, uncommitted work, missing environment access, or invariants that must not be lost.
+
+This applies even to planning, investigation, review, failed attempts, and no-code work. A session that only answers a user question and changes no repository state is exempt unless the user asks for a record. Mark plan items complete only when their stated outcome and verification are complete. Update master/gate status when it changes; an initialized log or proposed procedure is not implementation evidence.
+
+Never put secrets, private payloads, live credentials, or signed capabilities into handoffs. Link long reports instead of copying them. Keep records usable without chat history; do not claim commits, tests, deployments, or compatibility that did not happen.
+