@regardio/dev 2.0.2 → 2.1.0

package/docs/en/agents.md

@@ -1,57 +0,0 @@
----
-
-title: AI Agent Guidelines
-type: guide
-status: published
-summary: Instructions for AI coding assistants working with Regardio projects
-related: [coding-standards, react-standards, development-principles]
-locale: en-US
----
-
-# AI Agent Guidelines
-
-Baseline expectations for AI coding assistants working in Regardio projects. Follow the linked standards — they apply equally to agent and human contributions.
-
-## How Agents Should Work
-
-- **Scope changes tightly** - Only change what the task requires. Do not refactor adjacent code, add features, or reorganize files unless asked.
-- **Read before writing** - Understand existing patterns in the file and its neighbors before editing. Match the style you find.
-- **Avoid unnecessary complexity** - Only implement what is explicitly required. Do not introduce abstractions, helpers, or utilities speculatively.
-- **No emojis** - Unless explicitly requested.
-- **Preserve comments and documentation** - Do not add or remove comments unless the task calls for it.
-- **Explain uncertainty** - If something is ambiguous, say so rather than guessing.
-
-## Implementation Workflow
-
-When working on any non-trivial task, follow this sequence:
-
-1. **Understand the business logic** — Gather context before writing code. Read relevant domain documents. Know what is actually needed; do not implement what was not asked for.
-2. **Evaluate existing solutions** — Check for well-maintained libraries or utilities before writing custom code. Do not reinvent; do not introduce a dependency without verifying it exists and is actively maintained.
-3. **Define tests first** — Identify what tests describe the expected behavior before implementing. Tests are a contract. Do not modify tests to make them pass.
-4. **Implement with reusability in mind** — Prefer simple, readable code. Duplicate until a clear pattern emerges, then extract. Avoid speculative abstractions.
-5. **Stop if it gets complicated** — Growing complexity despite good preparation is a signal. Surface the difficulty, reconsider the approach, and back out rather than pushing through.
-6. **Document intent, stay lean** — Comments explain *why*, not *what*. Check existing documentation and business logic context before starting work.
-
-## Standards
-
-- [Coding Standards](./standards/coding.md) — TypeScript, React, and general coding patterns
-- [React and TypeScript Standards](./standards/react.md) — Component, hook, and state patterns
-- [SQL Schema Standards](./standards/sql.md) — PostgreSQL naming, structure, and access control
-- [Development Principles](./standards/principles.md) — Code quality, architecture, security
-- [API Standards](./standards/api.md) — API design and implementation
-- [Naming Conventions](./standards/naming.md) — Naming across TypeScript, SQL, CSS, Git
-- [Testing Approach](./standards/testing.md) — Testing philosophy and patterns
-- [Commit Conventions](./standards/commits.md) — Conventional commits and changelog generation
-- [Documentation Standard](./standards/documentation.md) — Document structure and conventions
-- [Writing](./standards/writing.md) — Voice, tone, and language
-
-## Commands
-
-```bash
-pnpm fix        # Fix and lint everything
-pnpm lint       # Lint only
-pnpm test       # Run tests
-pnpm typecheck  # Type check
-```
-
-Run `typecheck` and `lint` before marking a task complete.

package/docs/en/standards/documentation.md

@@ -1,173 +0,0 @@
----
-
-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/principles.md

@@ -1,84 +0,0 @@
----
-
-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/writing.md

@@ -1,119 +0,0 @@
----
-
-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