feat: bootstrap design kit and vaporwave demo baseline

kit/patterns/controls-selection/README.md

@@ -0,0 +1,13 @@
+# Controls + Selection Pattern
+
+Canonical interactive controls for server-rendered admin/list pages:
+
+- button hierarchy (primary / secondary / danger / quiet / disabled)
+- segmented filters
+- row checkboxes + select-all-visible semantics
+- bulk-action bar with explicit preview/confirm steps
+- status badges for list rows and workflow state
+
+This pattern standardizes control language and interaction shape while leaving branding and
+domain terminology to the host project.
+

kit/patterns/controls-selection/contract.md

@@ -0,0 +1,39 @@
+# Contract: Controls + Selection
+
+## Buttons
+
+- Use a small stable button taxonomy: `primary`, `secondary`, `ghost`, `danger`, `disabled`.
+- The canonical visual baseline for demo/scaffold examples is the active dual baseline used in the
+  demo/scaffold (`Vapor Soft` / `Vapor Night`, system-selected). A frozen Aqua snapshot bundle may
+  be kept for archival reference, but examples should follow the active baseline.
+- Destructive actions (`archive`, `delete`, `remove`) must use danger styling and explicit labels.
+- Button text should describe the action outcome, not implementation detail.
+- Buttons are text-first; icons are optional and must not replace labels on primary/danger actions.
+- Base examples must show both `disabled` and `loading` states.
+
+## Checkbox Selection
+
+- Row checkboxes support bulk actions from a shared action bar.
+- Header checkbox semantics must be explicit:
+  - select visible rows only, or
+  - select all rows in query scope (must be clearly labeled)
+- Selection summary must show count (`N selected`) near bulk actions.
+- In paginated views, the UI should distinguish selection on the current page from selection across the filtered/query scope.
+- Selection state should survive pagination/filter navigation via explicit state (query params, server session, or another deterministic mechanism).
+- Same-page interactions should preserve reading position (module anchor pattern is preferred in canonical server-rendered flows).
+
+## Segmented Filters
+
+- Segment/toggle filters are allowed for small enumerations (status, active/archived).
+- Segmented controls are grouped joined-buttons:
+  - one shared outer shell,
+  - rounded corners only on the first/last segment,
+  - straight internal separators between middle segments.
+- Active segment color may vary by context (for example blue preset selector vs dark status scope tabs), but geometry must remain consistent.
+- Segment changes should preserve other active filters where possible.
+
+## Bulk Action Safety
+
+- Bulk action click should preview count and target scope before execution.
+- Destructive bulk actions require confirmation.
+- Dense bulk action bars may move rare actions into an explicit overflow menu (`More actions`) while keeping primary actions visible.

kit/patterns/forms-validation/README.md

@@ -0,0 +1,12 @@
+# Forms + Validation Pattern
+
+Canonical patterns for server-rendered form workflows in Go web applications:
+
+- tabbed / mode-switched forms
+- datalist/autocomplete suggestions
+- inline validation messages
+- review / confirm step before submit
+- explicit reset and error handling states
+
+This pattern standardizes interaction flow and validation UX, not domain-specific field sets.
+

kit/patterns/forms-validation/contract.md

@@ -0,0 +1,34 @@
+# Contract: Forms + Validation + Suggestions
+
+## Form Structure
+
+- Group fields semantically and keep labels explicit.
+- Inputs requiring suggestions may use `datalist` or equivalent autocomplete UI.
+- Suggestion sources must represent the full relevant scope (not only visible rows from paginated tables).
+
+## Validation
+
+- Surface validation errors inline near fields and in a form-level summary when helpful.
+- Validation messages must be human-readable and action-oriented.
+- Do not hide required-field errors behind generic submit failures.
+
+## Multi-Step Flow
+
+Recommended stages:
+
+1. `edit`
+2. `review`
+3. `confirm/submit`
+4. `result`
+
+Rules:
+
+- Users must be able to return from review to edit without losing entered values.
+- Destructive or irreversible actions require explicit confirmation.
+- Query- or state-driven step transitions should be deterministic and testable.
+
+## File Inputs in Forms
+
+- If a workflow includes upload, the file control should be clearly labeled and the supported formats explicit.
+- Import parsing/preview may be delegated to a dedicated import/export pattern, but the form contract must remain clear.
+

kit/patterns/import-export/README.md

@@ -0,0 +1,13 @@
+# Import / Export Pattern
+
+Canonical file transfer UX patterns for Go web applications:
+
+- file import forms (CSV/JSON and similar)
+- validation preview tables before confirm
+- confirm step with human-readable summary
+- export controls (format + scope + options)
+- predictable file download behavior and filenames
+
+This pattern covers UI and UX contracts. Business-specific validation and file schemas remain in
+the host project's own architecture docs.
+

kit/patterns/import-export/contract.md

@@ -0,0 +1,32 @@
+# Contract: Import / Export Workflows
+
+## Import Workflow
+
+Recommended stages:
+
+1. `Upload`
+2. `Preview / Validate`
+3. `Confirm`
+4. `Execute`
+5. `Result summary`
+
+Rules:
+
+- Validation preview must be human-readable (table/list), not raw JSON only.
+- Warnings and errors should be shown per row and in aggregate summary.
+- Confirm step should clearly communicate scope and side effects.
+
+## Export Workflow
+
+- User must explicitly choose export scope (`selected`, `filtered`, `all`) when ambiguity exists.
+- Export format should be explicit (`csv`, `json`, etc.).
+- Download response should set:
+  - `Content-Type`
+  - `Content-Disposition`
+- If CSV targets spreadsheet users, document delimiter and BOM policy.
+
+## Error Handling
+
+- Import errors should map to clear user-facing messages.
+- Export errors after streaming starts must degrade gracefully (human-readable fallback).
+

kit/patterns/modal-workflows/README.md

@@ -0,0 +1,9 @@
+# Modal Workflow Pattern
+
+This pattern package captures modal-based create/edit/remove workflows for server-rendered Go
+web UIs.
+
+Synthesis sources:
+
+- detailed enterprise UI interaction contracts
+- operational admin workflows in Go web apps

kit/patterns/modal-workflows/contract.md

@@ -0,0 +1,9 @@
+# Contract: Modal Workflows
+
+## Shared Rules
+
+- Destructive actions require explicit confirmation.
+- Validation and backend errors are rendered in human-readable form.
+- UI state transitions are explicit (`open` / `submit` / `success` / `error` / `cancel`).
+- API contracts and UI copy should be documented in the host project's Bible.
+

kit/patterns/operator-tools/README.md

@@ -0,0 +1,13 @@
+# Operator Tools Pattern
+
+Universal pattern for complex operator/admin dashboards in Go web applications.
+
+This pattern standardizes:
+
+- scope tabs and queue/status filters
+- operations queue tables with row actions
+- batch actions with explicit selection
+- import/export shortcuts near operator workflows
+- safety checklists and confirmation routing
+
+See `contract.md` for behavior rules.

kit/patterns/operator-tools/contract.md

@@ -0,0 +1,36 @@
+# Contract: Operator Tools Dashboard
+
+## Purpose
+
+Provide a canonical structure for high-density operator/admin screens without encoding
+domain-specific terminology or business rules.
+
+## Required UI Regions
+
+- Scope tabs (or equivalent segmented navigation)
+- Queue/status filters
+- Batch action bar with explicit selection count
+- Primary queue table/list with stable row actions
+- Safety/guardrail region (checklist, warnings, runbook notes)
+
+## Selection and Batch Actions
+
+- Batch actions must require explicit selection; never infer hidden rows by default.
+- The UI must display selection counts for the current view and, if applicable, outside the current view/filter.
+- Destructive or high-impact actions must route through an explicit confirmation step (modal or dedicated confirm state).
+
+## Status and Queue Semantics
+
+- Queue/status labels must be consistent across filters, row badges, and summaries.
+- Failed items must remain easy to filter and retry without losing current scope context.
+- Running/queued states should be visually distinct from done/failed states.
+
+## Import / Export Placement
+
+- Import preview and export actions should be discoverable near operator workflows.
+- Export scope must remain explicit (`selected`, `filtered`, `all`) when ambiguity exists.
+
+## Reuse Boundary
+
+- Keep the pattern generic: host projects provide their own tool names, domain fields, and backend execution logic.
+- This contract standardizes interaction semantics and layout zones, not business workflows.

kit/patterns/status-indicators/README.md

@@ -0,0 +1,4 @@
+# Status Indicators Pattern (Planned)
+
+Reserved for health badges, sync status indicators, and severity labels.
+

kit/patterns/table-pagination/README.md

@@ -0,0 +1,7 @@
+# Table + Pagination Pattern
+
+This pattern package captures a shared contract for table-based UI pages with server-side
+filters and pagination.
+
+It is derived from mature server-rendered admin UIs and list-page conventions across multiple
+Go web codebases.

kit/patterns/table-pagination/backend/list_pagination.go.tmpl

@@ -0,0 +1,3 @@
+// Placeholder template for pagination helpers.
+// Adapt from existing host codebase conventions (net/http or Gin).
+

kit/patterns/table-pagination/contract.md

@@ -0,0 +1,27 @@
+# Contract: Table + Server-Side Filters + Pagination
+
+## Required Behavior
+
+- Filters apply to the full query scope before pagination (not page-local filtering).
+- Pagination state is controlled by URL query parameters.
+- Changing a filter resets the page parameter to page `1`.
+- UI shows a summary (`Showing X–Y of N`) and an explicit active page state in pagination controls.
+- Canonical demo visual style uses a centered dot pager while preserving page semantics via URL parameters and accessible labels.
+- Demo/base contract includes a `rows per page` control.
+- Status badge columns should be centered when the column semantics are status-only values.
+- Small modules (no internal scroll, no more than 2 actions) should place actions in the module header row.
+- Shared table/filter controls should inherit the repository baseline component theme
+  (currently Vapor Soft / Vapor Night in the canonical demo/scaffold) rather than redefining
+  per-pattern primitives.
+
+## Recommended Query Parameters
+
+- `page` for single-list pages
+- `per_page` when the page-size control is user-visible
+- section-specific params (for example `active_page`, `chronology_page`) for multi-list pages
+
+## Interaction Guardrails
+
+- Same-page filter/pagination interactions should preserve user reading position (for example via module anchors such as `#table-filters` / `#table-list`).
+- Table status badges should remain readable under the shared theme baseline (including tinted badge variants when a host project opts into a legacy or alternate visual preset).
+- Dot pager interactions should remain keyboard accessible and expose page meaning via labels/`aria-current`, even if numbers are visually hidden.

kit/patterns/table-pagination/static/table.css

@@ -0,0 +1,2 @@
+/* Placeholder styles for table pagination pattern. */
+

kit/patterns/table-pagination/templates/table_with_pager.html

@@ -0,0 +1,2 @@
+<!-- Placeholder table + pager partial. -->
+

kit/patterns/theme-aqua-legacy/README.md

@@ -0,0 +1,14 @@
+# macOS Aqua Theme Snapshot (Legacy)
+
+Status: legacy reference only (not active baseline)
+
+This directory preserves the Aqua-style visual exploration snapshot that was developed during demo
+refinement. It is stored as a reusable archive bundle so it can be referenced later without
+driving the active baseline.
+
+Active visual baseline for the demo/scaffold is Aqua-first. This package is a frozen snapshot for archival/reference use.
+
+Contents:
+
+- `demo-aqua-freeze.css` — frozen snapshot of the demo stylesheet at the time of the freeze
+- `notes.md` — summary of what was explored and how to treat the snapshot

kit/patterns/theme-aqua-legacy/notes.md

@@ -0,0 +1,22 @@
+# Aqua Legacy Snapshot Notes
+
+This snapshot is kept for historical reference and selective reuse.
+
+## What it captures
+
+- Aqua-style control surfaces and button hierarchy
+- segmented controls and tab-like grouped buttons
+- modal window chrome experiments (titlebar + close button)
+- table/filter visual refinements and dot-pager styling
+- style-playground Aqua preset refinements
+
+## What it is not
+
+- Not a required dependency for host projects
+- Not the live source of truth for the current Aqua baseline (the live baseline is in demo/scaffold CSS)
+- Not the target for normal iterative styling work unless explicitly requested
+
+## Current policy
+
+- Active baseline styling remains Aqua-first in the live demo/scaffold assets.
+- Use this snapshot only when explicitly needed for archival comparison or extraction.

kit/patterns/timeline-cards/README.md

@@ -0,0 +1,12 @@
+# Timeline Cards Pattern
+
+Canonical timeline UX for operational history views:
+
+- cards grouped by day
+- summary chips for aggregated actions
+- source labels (`ingest`, `manual`, `system`, etc.)
+- single drilldown modal (no nested modals)
+- in-card search/filtering for event lists
+
+This pattern is intended for history/audit/timeline surfaces in server-rendered Go web UIs.
+

kit/patterns/timeline-cards/contract.md

@@ -0,0 +1,29 @@
+# Contract: Timeline Cards + Drilldown
+
+## Card Grouping
+
+- Render timeline as grouped cards (typically by day), not raw event rows.
+- Correlated or visually equivalent events may be collapsed into one card with counts.
+- Card summaries should be human-readable and avoid repeating page-scope identity labels.
+
+## Filters
+
+- Timeline filters are server-side when timeline is paginated or large.
+- Filters should preserve grouping semantics and timezone behavior.
+- Scope-invariant filters may be hidden on entity detail pages.
+
+## Drilldown
+
+- One card opens one drilldown modal/panel.
+- Drilldown contains:
+  - event list (left/top)
+  - selected event details (right/bottom)
+- No nested modal inside drilldown.
+- Card-local search/filter may be applied within the drilldown.
+
+## UX Rules
+
+- Use human-readable source labels.
+- Prefer action-oriented card titles (`Installed N components`, `Removed N components`).
+- Empty states must explain whether filters removed all results.
+