@regardio/dev 1.24.0 → 2.0.2

package/docs/en/standards/documentation.md

@@ -0,0 +1,173 @@
+---
+
+title: "Documentation Standard"
+description: "How Regardio documents its work — for agents to navigate, for humans to reason with, for tests to build on."
+publishedAt: 2026-04-17
+order: 1
+language: "en"
+status: "published"
+---
+
+## Context
+
+Regardio documentation is read by three audiences at once. Agents use it to answer questions about the system and to write code against a known contract. Humans use it to build a judgement of their own about what the project does and why. Tests use it as the specification the implementation is measured against.
+
+Those audiences do not all need the same shape on every page. An architectural decision reads best as a short chain of reasoning — context, alternatives, what was chosen and why. A naming reference reads best as a catalogue. A quick introduction to a tool reads best as a few paragraphs and a short example. Forcing every document into one template serves the template rather than the content, and what the reader comes away with is ceremony instead of understanding.
+
+What the documentation needs is enough predictability for tooling to rely on — a consistent frontmatter, a recognisable title, a place to find related reading — and enough freedom for each document to take the shape its content asks for.
+
+## Decision
+
+Every Regardio document carries a small shared surface. Underneath, it takes whichever of a few shapes fits the content it carries.
+
+### Shared surface
+
+Every document has the same top:
+
+- **Frontmatter** that identifies the document and lets tooling index it
+- **A title** as a heading or implicit from frontmatter
+- **An opening that names what the document is for** — one or two sentences, before any sub-headings, so that a reader landing cold knows where they are
+
+Every document has the same bottom:
+
+- **Cross-references** to documents the reader is likely to want next, either inline in the prose or collected under `## Related` at the end
+
+Between the top and the bottom, the document takes the shape its content asks for.
+
+### Shapes the body takes
+
+A few shapes recur. Pick the one the content fits; do not pad the content into a shape it resists.
+
+**Decision record.** When the document captures a choice with real trade-offs, the ADR shape carries the reasoning well: *Status → Context → Decision → Alternatives Considered → Operational Rules → Consequences*. Operational Rules are the part tests bind to. The shape is an option for decision-heavy documents, not a requirement for every document.
+
+**Reference catalogue.** When the content is a set of rules, names, or mappings that readers look up rather than read end-to-end, a catalogue of short sections with examples is the honest form. Naming conventions, file-layout rules, linter settings, and configuration tables read this way.
+
+**Concept or entity note.** When the document describes a thing in the domain — a Channel, a Piece, a Plan — a short run of paragraphs that names the thing, its role, and its relations is usually enough. Two or three headings if the thing has parts worth naming separately.
+
+**Quick introduction.** When the document introduces a tool or a workflow, a few paragraphs and a small example are enough. The reader needs to know what the thing is, when to reach for it, and where to go next. No ADR skeleton is required for a tool page.
+
+**Warm reasoning.** When the document is working something out — a use case, a walkthrough, an explanation of why a piece of the domain behaves the way it does — prose that follows the thought is the right form. Headings appear where they help the reader keep their place, not because structure is owed.
+
+A document can borrow from more than one shape. An architectural document might open with warm reasoning and close with Operational Rules. An entity note might include a short alternatives paragraph when the entity's shape had genuine contenders. The shapes are orientation, not slots.
+
+### Frontmatter
+
+Frontmatter is the part tooling reads. Keep it stable.
+
+| Field | Required | Notes |
+|---|---|---|
+| `title` | yes | Noun phrase naming the document. Decision records may prefix `"ADR: "`. |
+| `description` | yes | One sentence. What this document is for, without hedging. |
+| `publishedAt` | yes | ISO date (`YYYY-MM-DD`) the document was first accepted. |
+| `status` | yes | `"draft"`, `"published"`, `"superseded"`. |
+| `language` | yes | `"en"`, `"de"`. |
+| `order` | no | Integer, when a sibling set has a meaningful reading order. |
+| `kind` | no | `"adr"`, `"entity"`, `"concept"`, `"architecture"`, `"guide"`, `"use-case"`, `"reference"`. Lets agents and renderers pick the right treatment. |
+| `area` | no | `"ensemble"`, `"supabase"`, `"connect"`, `"instrument"`, `"dev"`. Names the implementation the document belongs to. |
+| `supersedes` | no | Filename (without extension) of the document this one replaces. |
+| `supersededBy` | no | Filename of the document that replaced this one. |
+
+### Tense and stance
+
+Documents describe what the system does, in the present tense, observed rather than advertised. "The publication function returns pieces ordered by `sort_order`." Not "The publication function will return…" and not "We should implement…". The tense holds whether the behaviour is currently built or still being specified; the `status` frontmatter carries the difference.
+
+The stance is observational. A Regardio document is not a pitch. It notices how the system fits together and what follows from that. Reliability, safety, transparency, usefulness, and care for the people the software serves show up through how the reasoning is laid out, not by being claimed. A reader who finishes a document should be able to make their own judgement about whether the system is sound — that is what the prose is for.
+
+### What shows up where
+
+- **Code snippets** appear where they clarify a contract, a data shape, or a naming pattern. Reference catalogues quite properly carry several; decision records rarely need any. A snippet never stands in for the reasoning around it.
+- **Names** (files, functions, columns, handles) appear where they are contracts readers rely on. They do not appear as a substitute for describing what something does.
+- **Procedural steps** belong in runbooks and READMEs. A domain spec does not read like a cookbook.
+
+### Cross-references
+
+Links carry a short descriptor of what the link leads to, not just a filename:
+
+```markdown
+The [Channel](../entities/channel.md) is the publication destination;
+the [Publishing Architecture](../architecture/publishing-architecture.md)
+describes how callers reach it.
+```
+
+`## Related` at the end of a document lists the next pages a reader is likely to want.
+
+### Voice
+
+The [Writing](./writing.md) standard covers voice, tone, and language. This document relies on it rather than repeating it.
+
+## Alternatives Considered
+
+### A single ADR skeleton for every document
+
+**Dismissed because** it presses reference catalogues and tool introductions into a shape that does not suit them. The skeleton adds ceremony where the content is already clear, and readers learn to skim past sections that carry no weight. The skeleton remains available for documents whose content earns it.
+
+### No shared shape at all
+
+**Dismissed because** agents and tooling need something predictable to index against, and readers benefit from landing on any document and knowing roughly where to look. A thin shared surface — frontmatter, opening line, closing references — is enough.
+
+### Separate templates per document kind
+
+**Dismissed because** the kinds blur at the edges. An entity note sometimes carries a decision; a use case sometimes carries a catalogue. A small set of recognisable shapes that documents can borrow from works better than a closed list of templates.
+
+## Operational Rules
+
+### Frontmatter is complete
+
+Every document carries `title`, `description`, `publishedAt`, `status`, and `language`. Tooling that indexes or lists documents relies on these five.
+
+### Opening names the subject
+
+Before the first sub-heading, a reader can tell what the document is for. If the opening does not make this clear, the document is not ready.
+
+### Shape follows content
+
+The body takes the shape the content asks for. A decision record uses the ADR skeleton if that skeleton helps the reasoning; a reference uses a catalogue; an introduction stays short. Where a document borrows from more than one shape, it does so in service of the reader, not in service of the template.
+
+### Tense is present, stance is observational
+
+Documents describe the system as it is, in the present tense. Not-yet-built behaviour is flagged through `status`, not through hedged tense. The prose observes rather than promotes.
+
+### Reasoning is preserved, not rewritten
+
+When a decision is revisited, the existing document is superseded. The old reasoning stays readable so that future readers can see what was known at the time. An in-place rewrite that changes direction without supersession loses the history.
+
+### Code and names earn their place
+
+A snippet appears because it clarifies a contract the prose cannot carry alone. A specific name appears because callers rely on it. Both are tools for the reader, not decoration.
+
+### Tests can point at a document
+
+A behaviour worth testing has a place in a document that names it. The document does not need a section labelled "Operational Rules" for this — it needs prose clear enough that a test can quote it and both the test author and the reviewer know what is being verified.
+
+### One subject per document
+
+A document names one entity, one concept, one decision, one scenario. When a draft sprawls across several, the move is to split it.
+
+## Consequences
+
+### Positive
+
+- Documents read naturally for their content. ADRs feel like ADRs; reference catalogues feel like reference catalogues; introductions stay short.
+- Agents and humans find a predictable frontmatter and opening, and the body of each document carries its reasoning in the form that fits.
+- The docs stay honest. Observational prose about what the system does leaves room for the reader to form a judgement, rather than prescribing one.
+- Tests bind to the prose that describes behaviour, wherever in the document that prose lives.
+
+### Negative
+
+- "Shape follows content" asks for judgement. Contributors unsure of the right shape need a reference document to look at; the existing documents serve that role.
+- Without a single template, reviewers sometimes have to say "this would read better as a catalogue" or "this would read better as an ADR". That conversation is part of the standard, not a cost around it.
+
+### Mitigations
+
+- New documents are often patterned on a nearby existing one. A contributor writing a new entity note copies the shape of an adjacent entity note; a contributor writing an ADR copies an adjacent ADR.
+- Reviewers point at this document when a draft has picked a shape that resists its content, and help the author find the form the content already has.
+
+## Related
+
+- [Writing](./writing.md) — Voice, tone, language
+- [AI Agent Guidelines](../agents.md) — How agents use these documents
+- [Principles](./principles.md) — Shared development principles
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/docs/en/standards/naming.md

@@ -0,0 +1,180 @@
+---
+
+title: "Naming"
+description: "Naming patterns across TypeScript, SQL, CSS, Git, and configuration — each language in its own idiom, aligned across the seams."
+publishedAt: 2026-04-17
+order: 4
+language: "en"
+status: "published"
+kind: "reference"
+area: "dev"
+---
+
+A name is the shortest documentation a thing gets. The same concept can appear in TypeScript, a SQL column, a CSS class, and a branch; when the words line up across those surfaces, the concept stays recognisable. The convention is to match each language's native idiom and keep the words in the same order across languages.
+
+## General
+
+- Names carry their purpose — `getUserById` not `getUsrByID`
+- Consistent patterns within each language
+- Abbreviations only when they are genuinely universal (`id`, `url`, `http`)
+- Domain language where domain words exist
+
+## TypeScript and JavaScript
+
+### Variables and functions
+
+`camelCase`:
+
+```typescript
+const userName = 'alice';
+function calculateTotal(items: Item[]): number { }
+async function fetchUserProfile(userId: string): Promise<User> { }
+```
+
+### Types, interfaces, classes
+
+`PascalCase`:
+
+```typescript
+interface UserProfile { id: string; displayName: string; createdAt: Date; }
+type RequestStatus = 'pending' | 'success' | 'error';
+class PaymentProcessor { }
+```
+
+### Constants
+
+`UPPER_SNAKE_CASE`:
+
+```typescript
+const MAX_RETRY_ATTEMPTS = 3;
+const API_BASE_URL = 'https://api.example.com';
+```
+
+### React components
+
+`PascalCase` for components, `camelCase` for props:
+
+```typescript
+interface ButtonProps { variant: 'primary' | 'secondary'; onClick: () => void; }
+function ActionButton({ variant, onClick }: ButtonProps) { }
+```
+
+### Files and directories
+
+- Lowercase `kebab-case`
+- Tests end in `.test.ts`
+- File names match the concept they export
+
+## SQL
+
+### Tables and columns
+
+`snake_case`, tables in the singular:
+
+```sql
+create table member (
+  id uuid primary key,
+  display_name text not null,
+  created_at timestamptz default now()
+);
+```
+
+Column suffixes:
+
+- `id` — primary key
+- `{referenced_table}_id` — foreign key
+- `{field}_intl` — internationalised text (`jsonb`, keys are locale codes)
+- `{event}_at` — timestamps
+- `deleted_at` — soft-delete marker
+
+### Functions
+
+Pattern: `{domain}_{verb}` or `{domain}_{verb}_{target}`
+
+```sql
+create function util_generate_slug(_input text) ...
+create function task_get_status(_task_id uuid) ...
+```
+
+Standard verbs: `get`, `list`, `create`, `update`, `delete`, `check`, `is`, `has`, `set`, `generate`.
+
+### Parameters and variables
+
+Prefix `_` for parameters, `v_` for local variables:
+
+```sql
+create function process_order(_order_id uuid)
+returns void
+language plpgsql
+as $func$
+  declare
+    v_total numeric;
+  begin
+    -- body
+  end;
+$func$;
+```
+
+### Objects bound to a table
+
+- Check constraints — `chk_{table}_{field}_{purpose}`
+- Unique constraints — `uq_{table}_{field}`
+- Indexes — `idx_{table}_{field}`; unique as `idx_unique_{table}_{field}`
+- Triggers — `trg_{table}_{purpose}`
+- RLS policies — `pol_{table}_{operation}`
+
+## CSS
+
+`kebab-case`; BEM-style modifiers where useful:
+
+```css
+.user-profile { }
+.action-button--primary { }
+
+:root {
+  --color-primary: #007bff;
+  --spacing-md: 1rem;
+}
+```
+
+## Git
+
+### Branches
+
+`kebab-case` with a type prefix:
+
+```bash
+feature/user-authentication
+fix/login-redirect-loop
+docs/api-documentation
+```
+
+### Commit subjects
+
+Conventional Commits, imperative mood — see [Commits](./commits.md).
+
+## Configuration
+
+- JSON / JSONC keys — `camelCase`
+- Environment variables — `UPPER_SNAKE_CASE`
+- Package names — scoped, `kebab-case` (`@regardio/react`, `@regardio/ensemble-supabase`)
+
+```json
+{ "compilerOptions": { "strictNullChecks": true } }
+```
+
+```bash
+DATABASE_URL=postgres://localhost:5432/mydb
+NODE_ENV=production
+```
+
+## Related
+
+- [Coding](./coding.md) — TypeScript and general patterns
+- [SQL](./sql.md) — PostgreSQL naming, structure, and access
+- [Commits](./commits.md) — Branch and commit naming
+- [Writing](./writing.md) — Voice, tone, language
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/docs/en/standards/principles.md

@@ -0,0 +1,84 @@
+---
+
+title: "Principles"
+description: "The shared ground Regardio projects stand on — six clusters of principles that carry across languages and repos."
+publishedAt: 2026-04-17
+order: 3
+language: "en"
+status: "published"
+kind: "reference"
+area: "dev"
+---
+
+Regardio spans several codebases and several languages. What keeps them legible to each other is a short list of principles held in common — enough shared ground that a contributor moving between projects finds the same habits in force, and enough room left for each codebase to speak its own idiom.
+
+Six clusters, a handful of items each.
+
+## Code quality
+
+- Readable code over clever code
+- Consistent naming within each language — `camelCase` in TypeScript, `snake_case` in SQL
+- Small functions with a single responsibility
+- Explicit choices over implicit defaults
+
+## Architecture
+
+- Modules decouple from each other; dependencies are deliberate
+- Duplication resolves into an abstraction only when the pattern is clear
+- Interfaces describe what a module does, not how it does it
+- Concerns separate along the seams the domain suggests
+
+## Error handling
+
+- Input is validated early; failures surface with a clear message
+- Validation covers correctness and security in the same pass
+- Logic stays separated from side effects so it remains testable
+- Dependencies can fail; the code degrades gracefully when they do
+
+## Performance
+
+- Data structures match the shape of the work
+- Measurement comes before optimisation
+- Resources — memory, connections, file handles — are released on the path that acquired them
+- Scale is considered at design time, not retrofitted
+
+## Security
+
+- Client data is untrusted by default; server-side validation is the line
+- Privileges stay narrow; access is opened deliberately
+- Defence is layered; a single check never stands alone
+- Openness is an opt-in, not the default posture
+
+## Maintainability
+
+- Patterns repeat across the codebase so that reading one teaches reading the rest
+- Commits are atomic and speak to one change at a time
+- Refactoring is continuous; debt is paid down rather than accumulated
+
+## Implementation workflow
+
+Non-trivial work tends to follow this sequence — not as a ritual, but because skipping a step usually costs more later than it saves now:
+
+1. **Understand the business logic first.** The deepest defects come from misunderstood requirements. Read the relevant domain document; know what is needed now rather than what might be needed later.
+2. **Look for existing solutions.** Well-maintained libraries are evaluated before custom code is written. Dependencies are vetted for design quality, test coverage, and recent activity.
+3. **Write the tests as specification.** The behaviour a change produces is described as tests before the change is written. Tests are the contract; the code is measured against them.
+4. **Implement with reusability in mind, not reusability as the goal.** Duplicate until the pattern is clear, then extract. Wrong abstractions cost more than duplication.
+5. **Stop and reconsider when complexity grows.** Difficulty that keeps growing despite good preparation is a signal. Back out, simplify, or question the approach.
+6. **Document intent, not mechanics.** Comments explain *why*; the code explains *what*. Existing context is checked before new prose is added.
+
+## Collaboration
+
+- Every change passes through review
+- Code quality is shared, not owned
+- Decisions that involve a real trade-off leave a trace in the project's `docs/en` tree
+
+## Related
+
+- [Coding](./coding.md) — TypeScript and general patterns
+- [Testing](./testing.md) — Testing philosophy
+- [Documentation Standard](./documentation.md) — How documents are shaped
+- [Writing](./writing.md) — Voice, tone, language
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/docs/en/standards/react.md

@@ -0,0 +1,246 @@
+---
+
+title: "React"
+description: "Component, hook, state, and performance patterns the Regardio React apps hold to."
+publishedAt: 2026-04-17
+order: 6
+language: "en"
+status: "published"
+kind: "reference"
+area: "dev"
+---
+
+Regardio's user-facing surfaces — the Instrument app, the channel apps, the Storybook-hosted component packages — are all React. They share a design system through `@regardio/react` and styling through `@regardio/tailwind`. A contributor moving between them finds the same component shapes and the same decisions about where state lives. This page names those shared patterns.
+
+## TypeScript in React
+
+### Types
+
+- Explicit types on function parameters and public return values
+- `interface` for object shapes; `type` for unions
+- Generic constraints when a type carries across boundaries
+
+```typescript
+interface UserData {
+  id: string;
+  email: string;
+  displayName: string;
+}
+
+interface Repository<T extends { id: string }> {
+  findById(id: string): Promise<T | null>;
+  create(data: Pick<T, Exclude<keyof T, 'id'>>): Promise<T>;
+}
+```
+
+### Naming
+
+- `camelCase` — variables, functions, methods
+- `PascalCase` — types, interfaces, classes, components
+- `UPPER_SNAKE_CASE` — constants
+
+### Error handling
+
+Result types at API boundaries; specific error types for known failure modes:
+
+```typescript
+type Result<T, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+async function fetchUser(id: string): Promise<Result<User>> {
+  try {
+    const data = await api.getUser(id);
+    return { success: true, data };
+  } catch (error) {
+    return { success: false, error: error as Error };
+  }
+}
+```
+
+## Components
+
+### Structure
+
+- Functional components with hooks
+- One responsibility per component
+- Composition over inheritance
+- Explicit props interface
+
+```typescript
+interface CardProps {
+  title: string;
+  description: string;
+  onSelect: (id: string) => void;
+  isSelected?: boolean;
+}
+
+export function Card({ title, description, onSelect, isSelected = false }: CardProps) {
+  const handleClick = useCallback(() => onSelect(title), [title, onSelect]);
+  return (
+    <div className={cn('card', { selected: isSelected })} onClick={handleClick}>
+      <h3>{title}</h3>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+### Categories
+
+- **UI components** — pure, reusable, no business logic
+- **Feature components** — domain logic, backend integration
+- **Page components** — route-level; compose features
+
+### File layout
+
+- `components/ui/` — reusable UI components
+- `components/features/` — feature-specific components
+- `hooks/` — custom hooks
+- `types/` — shared types
+- `utils/` — framework-agnostic helpers
+
+### Props
+
+- Pass only what the component uses
+- `useCallback` for function props that cross memoised boundaries
+- Sensible defaults; undefined handled gracefully
+
+## Hooks
+
+- Dependencies declared in full for `useEffect`, `useMemo`, `useCallback`
+- Reusable logic extracts into a custom hook, name prefixed `use`
+- Cleanup releases whatever the hook set up
+
+```typescript
+function useWebSocket(url: string) {
+  const [data, setData] = useState<unknown>(null);
+  const [status, setStatus] = useState<'connecting' | 'connected' | 'disconnected'>('connecting');
+
+  useEffect(() => {
+    const ws = new WebSocket(url);
+    ws.onopen = () => setStatus('connected');
+    ws.onmessage = (event) => setData(JSON.parse(event.data));
+    ws.onclose = () => setStatus('disconnected');
+    return () => ws.close();
+  }, [url]);
+
+  return { data, status };
+}
+```
+
+### Event handling
+
+- Typed with the React event they receive
+- Forms prevent default and read values from controlled inputs
+- Keyboard handlers accompany mouse handlers
+
+```typescript
+function SearchForm({ onSubmit }: { onSubmit: (query: string) => void }) {
+  const [query, setQuery] = useState('');
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    onSubmit(query);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        onKeyDown={(e) => e.key === 'Escape' && setQuery('')}
+        aria-label="Search"
+      />
+      <button type="submit">Search</button>
+    </form>
+  );
+}
+```
+
+## State
+
+### Local
+
+- `useState` for simple component state
+- `useReducer` when the shape grows beyond two or three related pieces
+- Custom hooks for reusable state logic
+
+```typescript
+type State = { items: Item[]; filter: string; sortBy: 'name' | 'date'; loading: boolean };
+type Action =
+  | { type: 'SET_ITEMS'; items: Item[] }
+  | { type: 'SET_FILTER'; filter: string }
+  | { type: 'SET_SORT'; sortBy: 'name' | 'date' }
+  | { type: 'SET_LOADING'; loading: boolean };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'SET_ITEMS': return { ...state, items: action.items };
+    case 'SET_FILTER': return { ...state, filter: action.filter };
+    case 'SET_SORT': return { ...state, sortBy: action.sortBy };
+    case 'SET_LOADING': return { ...state, loading: action.loading };
+  }
+}
+```
+
+### Global
+
+- Context for theme, session, user preferences
+- A dedicated store for application state that genuinely spans the app
+- React Query (or equivalent) for server state
+
+## Performance
+
+- Code-split by route and feature; lazy-load what isn't needed yet
+- `React.memo`, `useMemo`, `useCallback` where profiling points at a win — not as defensive decoration
+- Bundle size monitored
+
+```typescript
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+
+function App() {
+  return (
+    <Suspense fallback={<LoadingSpinner />}>
+      <Routes>
+        <Route path="/dashboard" element={<Dashboard />} />
+      </Routes>
+    </Suspense>
+  );
+}
+```
+
+## Testing
+
+Components are tested through the interface a user reaches — roles, labels, visible text, keyboard. Implementation-detail assertions (internal state, render counts) do not appear.
+
+```typescript
+describe('SearchForm', () => {
+  it('calls onSubmit with query when form is submitted', async () => {
+    const mockOnSubmit = vi.fn();
+    render(<SearchForm onSubmit={mockOnSubmit} />);
+    const input = screen.getByRole('textbox', { name: /search/i });
+    await user.type(input, 'test query');
+    await user.click(screen.getByRole('button', { name: /search/i }));
+    expect(mockOnSubmit).toHaveBeenCalledWith('test query');
+  });
+});
+```
+
+### Accessibility
+
+- Keyboard navigation verified
+- Screen-reader access through roles and labels
+- Focus management checked on interactive flows
+- ARIA attributes correct where they carry meaning
+
+## Related
+
+- [Coding](./coding.md) — TypeScript patterns React code builds on
+- [Testing](./testing.md) — Testing philosophy and layers
+- [Principles](./principles.md) — Shared principles across the stack
+- [Naming](./naming.md) — Names across languages
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio