@regardio/dev 1.24.0 → 2.0.2

package/docs/en/standards/sql.md

@@ -0,0 +1,258 @@
+---
+
+title: "SQL"
+description: "PostgreSQL file organisation, formatting, naming, functions, and access control for Regardio schemas."
+publishedAt: 2026-04-17
+order: 7
+language: "en"
+status: "published"
+kind: "reference"
+area: "dev"
+---
+
+All SQL in Regardio is lowercase, schemas are organised by numbered files, SQLFluff enforces formatting, and RLS is on for every public table. This page catalogues the conventions. The reasoning behind the access pattern lives with the schema it protects — the standards here describe the form.
+
+## Formatting
+
+Keywords, identifiers, data types, function names, and casts are lowercase.
+
+```sql
+create table public.task (
+  id uuid primary key default gen_random_uuid(),
+  title text not null,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz null
+);
+```
+
+- 2-space indentation
+- Leading binary operators (`and`, `or`)
+- Trailing commas
+- Single quotes for string literals
+- Shorthand casting (`::type`)
+- `!=` for not-equal (`<>` is not used)
+- Line length capped at 100
+- One statement per semicolon
+
+## Linting
+
+SQLFluff is the linter. Configuration lives in `.sqlfluff` at the project root. A blueprint ships with `@regardio/dev/sqlfluff/setup.cfg` — projects copy it and adjust (SQLFluff does not support config inheritance).
+
+Key settings:
+
+```ini
+[sqlfluff]
+dialect = postgres
+max_line_length = 100
+
+[sqlfluff:rules:capitalisation.keywords]
+capitalisation_policy = lower
+
+[sqlfluff:rules:capitalisation.identifiers]
+extended_capitalisation_policy = lower
+```
+
+```bash
+sqlfluff lint schemas/
+sqlfluff fix schemas/
+```
+
+## File organisation
+
+Schema files live in `schemas/` and are numbered to control load order. Each file owns one domain or object group.
+
+### Naming pattern
+
+```text
+{nn}_{category}_{name}.sql
+```
+
+Examples: `00_schema_setup.sql`, `15_function_util.sql`, `30_core_task.sql`.
+
+### Number ranges
+
+- `00–09` — schema setup, enums
+- `10–19` — functions (auth, jsonb, model, storage)
+- `20–29` — reference tables (locale, timezone, country)
+- `30–39` — core tables (member, task, tag)
+- `40+` — domain tables
+
+A file with a lower number does not depend on a file with a higher number.
+
+### File header
+
+Every file opens with a banner naming its number, title, purpose, and sections:
+
+```sql
+--------------------------------------------------------------------------------
+-- {nn}. {Title}
+--
+-- {One-line purpose description.}
+--
+-- Provides:
+-- 1. {First section}
+-- 2. {Second section}
+--------------------------------------------------------------------------------
+```
+
+### Section dividers
+
+Within a file, sections separate by labelled dividers in a fixed order:
+
+```sql
+--[ 1. Table ]------------------------------------------------------------------
+
+--[ 2. Indexes ]----------------------------------------------------------------
+
+--[ 3. Functions ]--------------------------------------------------------------
+
+--[ 4. Constraints ]------------------------------------------------------------
+
+--[ 5. Triggers ]---------------------------------------------------------------
+
+--[ 6. Permissions ]------------------------------------------------------------
+```
+
+## Schema structure
+
+- `public` — user-facing tables, views, and API functions (exposed to PostgREST)
+- `private` — server-internal tables and helpers (not exposed to PostgREST)
+- `extensions` — third-party PostgreSQL extensions
+- `auth` — Supabase auth schema; not modified
+
+## Naming
+
+Every identifier is `snake_case`.
+
+### Tables
+
+Singular: `member`, `task`, `project` — not `members`, `tasks`.
+
+### Columns
+
+- `id uuid` — primary key
+- `{referenced_table}_id` — foreign key
+- `{field}_intl jsonb` — internationalised content
+- `created_at`, `updated_at`, `deleted_at`, `{event}_at` — timestamps
+- `deleted_at timestamptz null` — soft-delete marker
+
+Active-record queries use partial indexes filtered by `deleted_at is null`.
+
+### Column grouping
+
+Inline `--- SECTION` markers group related columns:
+
+```sql
+create table public.task (
+  id uuid primary key default gen_random_uuid(),
+  project_id uuid not null references public.project (id),
+
+  --- CONTENT
+  title text not null,
+  description text null,
+
+  --- STATUS
+  status public.task_status not null,
+  due_at timestamptz null,
+  deleted_at timestamptz null,
+
+  created_at timestamptz not null default now(),
+  updated_at timestamptz null
+);
+```
+
+### Functions
+
+Pattern: `{domain}_{verb}` or `{domain}_{verb}_{target}`.
+
+- `util_generate_slug`, `util_generate_code`
+- `jsonb_is_boolean`, `jsonb_deep_merge`
+- `task_get_status`, `task_check_ownership`
+- `access_check_permissions`, `user_get_role`
+
+Parameters are prefixed `_` (`_input`, `_task_id`); local variables are prefixed `v_` (`v_result`, `v_count`).
+
+Standard verbs: `get`, `list`, `create`, `update`, `delete`, `check`, `is`, `has`, `set`, `generate`.
+
+### 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}`
+
+## Functions
+
+Every function declares volatility, security context, language, and a pinned empty search path:
+
+```sql
+create or replace function public.util_generate_slug(
+  _input text
+) returns text
+language plpgsql
+immutable
+security invoker
+set search_path = ''
+as $func$
+  declare
+    v_result text;
+  begin
+    -- body
+    return v_result;
+  end;
+$func$;
+```
+
+- `security invoker` is the default
+- `security definer` is chosen only when the function needs to act beyond the caller's grants
+- `set search_path = ''` always; schema-qualified names are used throughout
+
+## Documentation
+
+Tables, columns, and functions carry `comment on` entries using dollar-quoted `$doc$` strings, placed immediately after the definition. The comment describes what the object is and what callers can assume about it — not how it is implemented.
+
+```sql
+comment on table public.task is $doc$A unit of work within a project.$doc$;
+
+comment on column public.task.title is $doc$Short description of the task.$doc$;
+
+comment on function public.util_generate_slug is $doc$
+Converts a text input into a URL-safe slug.
+
+Parameters:
+- _input text: Source text to slugify
+
+Returns text: Lowercase hyphenated slug.
+$doc$;
+```
+
+## Access control
+
+RLS is on and forced for every table in `public`. Grants revoke everything first, then grant only what is needed. Write paths prefer `security definer` functions over direct table grants.
+
+```sql
+alter table public.task enable row level security;
+alter table public.task force row level security;
+
+revoke all on table public.task from anon, authenticated;
+grant select on table public.task to authenticated;
+
+create policy pol_task_select on public.task
+  for select using (owner_id = (select auth.uid()));
+
+create policy pol_task_update on public.task
+  for update using (owner_id = (select auth.uid()))
+  with check (owner_id = (select auth.uid()));
+```
+
+## Related
+
+- [Naming](./naming.md) — Names across languages
+- [API](./api.md) — How the schema is consumed
+- [Principles](./principles.md) — Shared principles
+- [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/testing.md

@@ -0,0 +1,139 @@
+---
+
+title: "Testing"
+description: "How Regardio tests its code — layered, behaviour-first, and written as specification."
+publishedAt: 2026-04-17
+order: 9
+language: "en"
+status: "published"
+kind: "reference"
+area: "dev"
+---
+
+Tests are the bridge between the prose that describes behaviour and the code that produces it. A test quotes what the docs say the system does and checks that the code holds to it. When the bridge stays honest, refactors are safe because tests describe behaviour rather than shape; when it slips, tests break on every refactor and pass through every regression that preserves the shape they pinned.
+
+## Core principles
+
+- Test what the caller observes, not how the code achieves it
+- Fast feedback on the lowest layer that can verify a behaviour
+- Deterministic runs; no reliance on time-of-day, order, or shared state
+- Readable as specifications in their own right
+- Cover the success path, the edges, and the errors
+
+## Layers
+
+| Level | Share | Purpose | Tool |
+|-------|-------|---------|------|
+| **Unit** | ~70% | Functions, components, small pieces of business logic | Vitest |
+| **Integration** | ~20% | Modules together, API contracts, database behaviour | Vitest |
+| **End-to-end** | ~10% | Critical user flows across the stack | Playwright |
+
+The distribution follows cost and signal. Unit tests give the fastest feedback and the clearest error; integration tests catch contract mistakes between modules; end-to-end tests protect the flows users actually feel, and are too expensive to carry for everything else.
+
+## Writing tests
+
+### Arrange, Act, Assert
+
+```typescript
+it('calculates total with discount', () => {
+  // Arrange
+  const items = [{ price: 100 }, { price: 50 }];
+  const discount = 0.1;
+  // Act
+  const total = calculateTotal(items, discount);
+  // Assert
+  expect(total).toBe(135);
+});
+```
+
+### Names describe behaviour
+
+```typescript
+// Good
+it('returns an empty array when no items match the filter', () => {});
+it('throws ValidationError when the email is invalid', () => {});
+
+// Not good
+it('test1', () => {});
+it('sets isError to true', () => {});
+```
+
+### Independence
+
+- Each test sets up its own state
+- No dependency on the order other tests ran in
+- Cleanup leaves nothing behind
+
+## Frontend testing
+
+Components are tested through the interface a user reaches — roles, labels, visible text, keyboard:
+
+```typescript
+it('displays an error when submission fails', async () => {
+  render(<ContactForm />);
+  await user.click(screen.getByRole('button', { name: /submit/i }));
+  expect(screen.getByRole('alert')).toHaveTextContent(/failed/i);
+});
+```
+
+Implementation-detail assertions (`isError` flags, render counts, private method calls) do not appear.
+
+### Accessibility
+
+- Keyboard navigation verified
+- Screen-reader access through roles and labels
+- Colour contrast checked where it matters
+- Focus management correct on interactive flows
+
+## Database testing
+
+Schema tests run against a real Postgres so policies and triggers behave as they do in production:
+
+- Business rules held
+- RLS boundaries enforced
+- Validation errors return the expected shape
+- Queries use the indexes they are meant to
+- Error paths are reached and handled
+
+## Coverage
+
+Library packages hold a floor around 80% for statements, branches, functions, and lines. The floor is a minimum, not a target — the goal is meaningful tests, not arithmetic.
+
+Enforced at:
+
+- Local development — `pnpm test`
+- Release preparation — `ship-staging`
+- CI — GitHub Actions
+
+## Quality gates
+
+Before a package publishes:
+
+1. Build succeeds
+2. Type check passes
+3. Coverage meets the floor
+4. Tests pass — no skipped or failing
+
+## Continuous integration
+
+- Pre-commit hooks run linting (Biome)
+- CI runs build, typecheck, and the test suite with coverage
+- Release workflow blocks publishing on any failure
+
+## Test maintenance
+
+- Tests that no longer describe current behaviour are updated or deleted
+- Tests are refactored alongside the production code they accompany
+- A suite with failing or skipped tests is a broken suite
+
+## Related
+
+- [Principles](./principles.md) — Shared principles, including specification-led workflow
+- [React](./react.md) — How components are shaped to be testable
+- [API](./api.md) — Testing API endpoints and contracts
+- [Vitest](../tools/vitest.md) — Unit and integration testing
+- [Playwright](../tools/playwright.md) — End-to-end testing
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/docs/en/standards/writing.md

@@ -0,0 +1,119 @@
+---
+
+title: "Writing"
+description: "Voice, tone, and language Regardio content carries, in English and German."
+publishedAt: 2026-04-17
+order: 2
+language: "en"
+status: "published"
+kind: "concept"
+area: "dev"
+---
+
+The voice in which Regardio writes about itself and its tools.
+
+## What you are doing
+
+You write *from within* the System, not *about* it. Your aim is to trigger recognition. The reader you are writing for should be able to think *Yes, that's how it is.*
+
+Two trains of thought carry everything the System does — and everything you write about it.
+
+**Any one object can be observed from two sides.** Front and back, inside and outside, past and future, still and moving, question and answer, start and finish. A thing that looks complete from one angle shows something new from the other. Writing that only shows one side flattens what it describes. Writing that acknowledges both gives the reader room to stand where they already stand.
+
+**A whole becomes graspable when it is cut into a few distinct parts.** Six is the number to return to: enough variety to cover what matters, few enough to hold in the head at once, clear enough to name and locate each piece. A pie cut into six slices is something anyone can picture. When a subject resists clarity, the move is not more words — it is better cuts.
+
+These two habits are the grammar underneath the System. Carry them quietly. You rarely name them. They are just the shape of the thinking.
+
+## How to meet the reader
+
+Every reader comes with their own life and their own pursuit. Assume they notice things for themselves. Trust them to do their own connecting. Address them directly, without talking up or down.
+
+The ground under the writing is careful observation of how people actually feel, think, and act — not advice about how they should. When an idea becomes personally recognizable while staying broadly true, it has landed. When it only flatters or only instructs, it hasn't.
+
+## Stance
+
+Six movements carry every piece.
+
+1. **Derive, don't declare.** One thought leads to the next. "The System recognizes…" speaks from above. Better: the observation that leads to the structure. Readers follow a line of thought, not an instruction.
+2. **Observe, don't instruct.** Write like someone who has listened carefully and is sharing an observation, not like someone explaining a method.
+3. **Structure offers freedom, not rules.** The cuts exist to widen a view that has become too narrow, not to discipline one that is already broad.
+4. **Suggest possibilities to choose from.** Offer angles, not answers. Let the reader decide what fits. Suggest questions that people have, not riddles to solve.
+5. **Turned toward what could be, without promises.** Warm, attentive, spacious. Curious about people rather than diagnostic. No salvation talk, no coaching register.
+6. **Good humor makes the deepest thought approachable.** Lightness when it fits. Not forced, not absent. When the moment is right, a small wink can carry weight without claiming it.
+
+## Before and after
+
+**Instead of:** *"Apply this framework to align your team."*
+**Try:** *"What does the decision we made last week have to do with what's slowing us down now?"*
+
+**Instead of:** *"The System helps you gain clarity."*
+**Try:** *"A few angles worth looking at, whatever the pursuit."*
+
+**Instead of:** *"Pursuits flourish with a clear core."*
+**Try:** *"How will we know when we've arrived?"*
+
+The System's questions are not headers. They are real questions, worth sitting with.
+
+## Language
+
+Language that leaves room lets readers think. Language that pushes does the thinking for them. Given the choice, choose room.
+
+**Favor:** notice, explore, find, might, could, pattern, rhythm, carry, hold — words that leave room.
+
+**Avoid:** must, potential, resources, values, purpose, sustainability, growth, leverage, empower, ownership, good, bad. These either push or have been worn down to noise.
+
+**No method jargon.** Not from business, not from coaching, not from therapy, not from spirituality. If a term has a clear everyday word behind it, use the everyday word.
+
+**People are not categories.** Describe what people do and bring about, not what they are. This is also how gendered forms are handled — name actions, not groups.
+
+**The System is humane.** Equal, free cooperation is built in. Avoid connotations of hierarchy, ownership, dominance, control, or force. Reflect that without announcing it.
+
+**Complexity earns its place or goes.** Make hard ideas reachable without flattening them. If a sentence has to be read twice, shorten it. If an idea has been reduced past recognition, let it breathe again.
+
+## System terms
+
+System terms carry precisely defined concepts. Use them as they are; don't swap in synonyms for variety. When tempted to reach for a buzzword, reach for a System term instead — if it fits. If no System term fits, the buzzword probably isn't earning its place either.
+
+In every language the System is written in, the terms are chosen to capture the spirit of each concept in that language — not to translate literally from another. Don't import words from other languages into the prose. Let each language stand on its own.
+
+## Roots, kept in the background
+
+The System draws from many traditions of thought. Reference intents and ideas, not names or schools. The sources show themselves in the structure, not in citation. This is working craft carried by collective intelligence, not an elaborate treatise.
+
+## Format and craft
+
+**Headers** for orientation. **Prose** for connected thought. **Bold** for System terms at first introduction. *Italics* for genuine emphasis. No emojis. Lists only when the content is genuinely a list — bullets never replace a thought.
+
+## Language-specific caveats
+
+### German
+
+- Address the reader with *du* unless the context clearly calls for *Sie* (formal contracts, legal notices). Keep it direct, without affectation.
+- No gendering artifacts: no *:innen*, no asterisks, no *(m/w/d)*. Prefer action-based descriptions over group labels: *wer etwas vorhat*, *ein Mensch, der …*, *die Person, die …*, *Mitwirkende*, *Beteiligte*.
+- Quotation marks: German low-high („…") in body text.
+
+### English
+
+- American English: *organize*, *color*, *toward*, *behavior*, *center*. Periods and commas inside quotation marks.
+- No gendered forms. Name actions: *the person pursuing this*, *contributors*, *those involved*. Singular *they* is fine where a pronoun is unavoidable.
+- Quotation marks: straight double quotes (") in Markdown source; typographic quotes ("…") in rendered prose.
+
+## Check before publishing
+
+- Does it sound like a conversation the reader would want to be in?
+- Does the text derive rather than declare?
+- Are abstract thoughts grounded in concrete examples?
+- Are System terms used consistently, in their precise meaning?
+- Is it free of coaching register, pigeonholing, and tired buzzwords?
+- Could the honest response be *"Yes, that's how it is"*?
+
+*This guide is itself a living text. When in doubt: would you enjoy reading this?*
+
+## Related
+
+- [Documentation Standard](./documentation.md) — How Regardio shapes its 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/tools/biome.md

@@ -0,0 +1,89 @@
+---
+
+title: Biome
+type: guide
+status: published
+summary: Fast, unified linting and formatting for JavaScript and TypeScript
+related: [typescript, markdownlint]
+locale: en-US
+---
+
+# Biome
+
+Fast, unified linting and formatting for JavaScript and TypeScript. Single tool replacing ESLint + Prettier. Configuration is centralized through `@regardio/dev`; use wrapper commands so all packages behave consistently.
+
+## Configuration
+
+Create `biome.jsonc` in your package root:
+
+```jsonc
+{
+  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+  "extends": ["@regardio/dev/biome"]
+}
+```
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "fix": "exec-s fix:pkg fix:md fix:biome",
+    "fix:biome": "lint-biome check --write --unsafe .",
+    "lint": "exec-s lint:md lint:biome",
+    "lint:biome": "lint-biome check ."
+  }
+}
+```
+
+## CLI Wrapper
+
+Use `lint-biome` instead of `biome` directly. This wrapper ensures consistent behavior across the monorepo.
+
+```bash
+lint-biome check .           # Check for issues
+lint-biome check --write .   # Fix auto-fixable issues
+lint-biome format .          # Format only
+```
+
+## Package.json Handling
+
+The Biome preset excludes `package.json` files from processing. Instead, use `lint-package` which:
+
+1. Sorts package.json using the well-known field order
+2. Fixes exports condition order (`types` before `default` for TypeScript)
+
+```bash
+lint-package              # Sort package.json in current directory
+lint-package path/to/pkg  # Sort specific package.json
+```
+
+This is automatically run as part of `pnpm fix`.
+
+## Rule Categories
+
+The preset enables rules across categories:
+
+- **Correctness** - Catch bugs and incorrect code
+- **Style** - Consistent code formatting
+- **Complexity** - Prevent overly complex code
+- **Performance** - Identify performance issues
+- **Security** - Flag potential security vulnerabilities
+
+## Ignoring Rules
+
+When a rule genuinely doesn't apply, use inline comments:
+
+```typescript
+// biome-ignore lint/complexity/noForEach: forEach is clearer here for side effects
+items.forEach(item => process(item));
+```
+
+Always include a reason explaining why the exception is necessary.
+
+## Editor Setup
+
+- **VS Code**: [Biome extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
+- **JetBrains**: Built-in support via settings
+
+Resources: [Biome Documentation](https://biomejs.dev/) · [Rules Reference](https://biomejs.dev/linter/rules/)

package/docs/en/tools/commitlint.md

@@ -0,0 +1,92 @@
+---
+
+title: Commitlint
+type: guide
+status: published
+summary: Enforce conventional commit messages
+related: [husky]
+locale: en-US
+---
+
+# Commitlint
+
+Validates commit messages against the conventional format via Git hooks. Rules are centralized in `@regardio/dev`.
+
+## Configuration
+
+At the workspace root, create `.commitlintrc.json`:
+
+```json
+{
+  "extends": ["@regardio/dev/commitlint"]
+}
+```
+
+Or use a JavaScript config:
+
+```javascript
+// commitlint.config.cjs
+module.exports = require('@regardio/dev/commitlint');
+```
+
+## Commit Format
+
+```text
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, no code change |
+| `refactor` | Code change that neither fixes nor adds |
+| `perf` | Performance improvement |
+| `test` | Adding or updating tests |
+| `build` | Build system or dependencies |
+| `ci` | CI configuration |
+| `chore` | Other changes (tooling, etc.) |
+| `revert` | Revert a previous commit |
+
+### Examples
+
+```bash
+feat: add user authentication
+fix: resolve login redirect loop
+docs: update API documentation
+refactor: simplify payment processing
+test: add unit tests for date utilities
+chore: update dependencies
+feat(auth): implement OAuth2 flow
+fix(api): handle null response gracefully
+```
+
+## Rules
+
+The preset enforces:
+
+- **Header max length**: 100 characters
+- **Body leading blank**: Blank line before body
+- **Footer leading blank**: Blank line before footer
+- **Type enum**: Must be one of the allowed types
+
+## Git Hooks
+
+Commitlint runs automatically via Husky on commit. See [Husky](./husky.md) for setup.
+
+Related documents:
+
+- [Commit Conventions](../standards/commits.md) — Conventional commits and changelog generation
+- [Husky](./husky.md) — Git hooks for quality gates
+
+### Resources
+
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Commitlint Documentation](https://commitlint.js.org/)