@cratis/pi 0.0.1

package/skills/cratis-components-toolbar/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: cratis-components-toolbar
+description: Build a canvas-style icon toolbar with the Cratis Components Toolbar family — Toolbar, ToolbarButton, ToolbarSeparator, ToolbarGroup, ToolbarSection, ToolbarContext, ToolbarFanOutItem, ToolbarFolder, and the slot components that let a distant part of the tree contribute buttons. Use when building a drawing or diagram tool palette, a zoom or mode control strip, or any icon-button group with active state, context switching, or fan-out sub-panels. Do not use for a page action menu over a data table.
+license: MIT
+---
+
+# Cratis Components toolbars
+
+The `Toolbar` family builds **canvas-style tool palettes** — the pill-shaped bar
+of icon buttons you find in a drawing or diagram editor. For a page action menu
+over a list, use `DataPage.MenuItems` instead (see the
+**cratis-arc-react-page** skill).
+
+## Verified product sources
+
+| Package | Version | Verified from |
+| --- | --- | --- |
+| `@cratis/components` | `3.0.0` | its package manifest and `Toolbar` component sources |
+| `primeicons` | `^8.0.0` | peer of `@cratis/components@3.0.0` |
+| `react` | `^19.0.0` | peer of `@cratis/components@3.0.0` |
+
+## Import from the subpath
+
+Every toolbar export is a flat sibling — there are **no compound members**. It
+is `<ToolbarGroup>`, never `<Toolbar.Group>`.
+
+```tsx
+import {
+    Toolbar, ToolbarButton, ToolbarSeparator, ToolbarGroup,
+    ToolbarSection, ToolbarContext, ToolbarFanOutItem, ToolbarFolder,
+    ToolbarSlot, ToolbarSlotProvider, ToolbarLayout, useToolbarSlot,
+} from '@cratis/components/Toolbar';
+```
+
+## The pieces
+
+| Component | Purpose |
+| --- | --- |
+| `Toolbar` | the pill-shaped container |
+| `ToolbarButton` | icon or text button with a tooltip and optional active state |
+| `ToolbarSeparator` | divider between groups |
+| `ToolbarGroup` | a sub-group inside a toolbar, optionally filled from a slot |
+| `ToolbarSection` | animated section that morphs between named contexts |
+| `ToolbarContext` | a named set of buttons inside a `ToolbarSection` |
+| `ToolbarFanOutItem` | button that slides out a sub-panel of buttons |
+| `ToolbarFolder` | button that opens a grid or list of buttons |
+| `ToolbarSlotProvider` / `ToolbarSlot` / `useToolbarSlot` | contribute buttons from elsewhere in the tree |
+| `ToolbarLayout` | a named region rendered from slot content |
+
+## Step 1 — A basic toolbar
+
+Buttons default to a vertical layout. **`title` is the required prop and it is
+what appears in the tooltip** — there is no `tooltip` prop on `ToolbarButton`.
+
+```tsx
+import { Toolbar, ToolbarButton } from '@cratis/components/Toolbar';
+
+export const DrawingToolbar = () => (
+    <Toolbar>
+        <ToolbarButton icon='pi pi-arrow-up-left' title='Select' />
+        <ToolbarButton icon='pi pi-pencil' title='Draw' />
+        <ToolbarButton icon='pi pi-stop' title='Rectangle' />
+    </Toolbar>
+);
+```
+
+`icon` accepts either a PrimeIcons class string or a React node, so a custom SVG
+component works directly: `<ToolbarButton icon={<CircleIcon />} title='Circle' />`.
+
+## Step 2 — Active state
+
+```tsx
+const [activeTool, setActiveTool] = useState('select');
+
+<Toolbar>
+    <ToolbarButton icon='pi pi-pencil' title='Draw'
+        active={activeTool === 'draw'} onClick={() => setActiveTool('draw')} />
+    <ToolbarButton icon='pi pi-stop' title='Rectangle'
+        active={activeTool === 'rect'} onClick={() => setActiveTool('rect')} />
+</Toolbar>
+```
+
+## Step 3 — Separators and horizontal layout
+
+Give `ToolbarSeparator` the same `orientation` as its `Toolbar`, and move
+tooltips out of the bar's way on a horizontal toolbar:
+
+```tsx
+<Toolbar orientation='horizontal'>
+    <ToolbarButton icon='pi pi-minus' title='Zoom out' tooltipPosition='bottom' onClick={() => setZoom(z => z - 10)} />
+    <ToolbarButton text={`${zoom}%`} title='Reset zoom' tooltipPosition='bottom' onClick={() => setZoom(100)} />
+    <ToolbarButton icon='pi pi-plus' title='Zoom in' tooltipPosition='bottom' onClick={() => setZoom(z => z + 10)} />
+    <ToolbarSeparator orientation='horizontal' />
+    <ToolbarButton icon='pi pi-question-circle' title='Help' tooltipPosition='bottom' />
+</Toolbar>
+```
+
+Use `text` for a button that displays a value, such as a zoom percentage.
+
+## Step 4 — Animated context switching
+
+`ToolbarSection` shows one `ToolbarContext` at a time. When `activeContext`
+changes the buttons fade out, the section morphs to the new size, and the new
+buttons fade in. Only the section transitions; buttons outside it are
+unaffected.
+
+```tsx
+const [mode, setMode] = useState<'drawing' | 'text'>('drawing');
+
+<Toolbar>
+    <ToolbarButton icon='pi pi-arrow-up-left' title='Select' />
+    <ToolbarSection activeContext={mode}>
+        <ToolbarContext name='drawing'>
+            <ToolbarButton icon='pi pi-pencil' title='Draw' />
+            <ToolbarButton icon='pi pi-stop' title='Rectangle' />
+        </ToolbarContext>
+        <ToolbarContext name='text'>
+            <ToolbarButton icon='pi pi-align-left' title='Align left' />
+            <ToolbarButton icon='pi pi-align-center' title='Align center' />
+        </ToolbarContext>
+    </ToolbarSection>
+    <ToolbarButton icon='pi pi-undo' title='Undo' />
+</Toolbar>
+```
+
+## Step 5 — Fan-out and folders
+
+`ToolbarFanOutItem` slides a strip of extra buttons out of its trigger. It is
+the one component whose label prop **is** called `tooltip`, and both `icon` and
+`tooltip` are required.
+
+```tsx
+<ToolbarFanOutItem icon='pi pi-th-large' tooltip='Shapes' fanOutDirection='left'>
+    <ToolbarButton icon='pi pi-stop' title='Rectangle' />
+    <ToolbarButton icon='pi pi-circle' title='Circle' />
+</ToolbarFanOutItem>
+```
+
+`fanOutDirection` is `'right'` (default), `'left'`, `'up'`, or `'down'` — fan
+away from the screen edge the toolbar sits against.
+
+`ToolbarFolder` opens a larger panel of buttons as a grid or a list:
+
+```tsx
+<ToolbarFolder icon='pi pi-th-large' title='Tools' mode='list'>
+    <ToolbarButton icon='pi pi-pencil' title='Draw' />
+    <ToolbarButton icon='pi pi-eraser' title='Erase' />
+</ToolbarFolder>
+```
+
+`mode` is `'grid'` (default) or `'list'`; `maxColumns` (default `5`) applies to
+grid mode only, and `folderDirection` is `'right'` or `'left'`.
+
+## Step 6 — Contributing buttons from elsewhere
+
+A slot lets a component far from the toolbar contribute buttons without prop
+drilling. Wrap the region in `ToolbarSlotProvider`, publish content with
+`ToolbarSlot`, and consume it either by giving a `ToolbarGroup` a `slotName` or
+by rendering a named `ToolbarLayout`.
+
+```tsx
+<ToolbarSlotProvider>
+    {mode === 'draw' && <ToolbarSlot slotName='tool-options' order={10}>{drawTools}</ToolbarSlot>}
+    <Toolbar>
+        <ToolbarGroup>
+            <ToolbarButton icon='pi pi-arrow-up-left' title='Select' />
+        </ToolbarGroup>
+        <ToolbarGroup slotName='tool-options' />
+    </Toolbar>
+</ToolbarSlotProvider>
+```
+
+`ToolbarSlot` renders nothing where it sits; its children appear in the matching
+consumer, ordered ascending by `order` (default `0`). `useToolbarSlot(slotName)`
+returns the current content for a custom consumer. `ToolbarContext` also accepts
+a `slotName`.
+
+## Props
+
+### `Toolbar`
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `children` | `ReactNode` | required |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` |
+| `draggable` | `boolean` | `false` — makes child buttons draggable |
+| `onItemDragStart` | `(data: unknown, event: React.DragEvent) => void` | — |
+
+### `ToolbarButton`
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `title` | `string` | **required** — the accessible name and the tooltip text |
+| `icon` | `string \| ReactNode` | — |
+| `text` | `string` | — |
+| `active` | `boolean` | `false` |
+| `onClick` | `() => void` | — |
+| `tooltipPosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
+| `draggable` | `boolean` | inherited from the enclosing `Toolbar` |
+| `data` | `unknown` | payload handed to the drag handler |
+| `onDragStart` | `(data: unknown, event: React.DragEvent<HTMLButtonElement>) => void` | — |
+
+### `ToolbarSeparator`
+
+`orientation`: `'vertical' \| 'horizontal'`, default `'vertical'`.
+
+### `ToolbarGroup`
+
+`children?: ReactNode` · `slotName?: string` · `orientation?: 'vertical' | 'horizontal'` (default `'vertical'`).
+
+### `ToolbarSection`
+
+`activeContext?: string` · `children: ReactNode` · `orientation?: 'vertical' | 'horizontal'` (default `'vertical'`).
+
+### `ToolbarContext`
+
+`name: string` (**required**) · `children: ReactNode` · `slotName?: string`.
+Renders nothing itself — it is a marker `ToolbarSection` reads.
+
+### `ToolbarFanOutItem`
+
+`icon: string | ReactNode` (**required**) · `tooltip: string` (**required**) ·
+`tooltipPosition?` (default `'right'`) ·
+`fanOutDirection?: 'right' | 'left' | 'up' | 'down'` (default `'right'`) ·
+`children: ReactNode`.
+
+### `ToolbarFolder`
+
+`icon: string | ReactNode` (**required**) · `title: string` (**required**) ·
+`tooltipPosition?` (default `'right'`) ·
+`folderDirection?: 'right' | 'left'` (default `'right'`) ·
+`mode?: 'grid' | 'list'` (default `'grid'`) · `maxColumns?: number` (default `5`) ·
+`children: ReactNode`.
+
+### `ToolbarSlot` / `ToolbarSlotProvider` / `ToolbarLayout`
+
+`ToolbarSlot`: `slotName: string` · `order?: number` (default `0`) · `children: ReactNode`.
+`ToolbarSlotProvider`: `children: ReactNode`.
+`ToolbarLayout`: `name: string` · `children?: ReactNode` (the fallback when the
+slot is empty) · `orientation?: 'vertical' | 'horizontal'` (default `'vertical'`).
+
+## Multiple groups
+
+Render separate `Toolbar` instances for visually distinct bars, or use
+`ToolbarGroup` inside one bar when the groups belong together.
+
+## Verify
+
+- Every import comes from `@cratis/components/Toolbar`, not the root barrel.
+- Every `ToolbarButton` has a `title` — it is required and it is the accessible
+  name, not decoration.
+- `ToolbarSeparator` orientation matches its `Toolbar`.
+- Horizontal toolbars set `tooltipPosition` to `'top'` or `'bottom'`.
+- Each `ToolbarContext` inside a `ToolbarSection` has a unique `name` and the
+  section's `activeContext` matches one of them.
+- `ToolbarFanOutItem` and `ToolbarFolder` fan away from the nearest screen edge.
+- Slot names match between the `ToolbarSlot` and its consumer, and both sit
+  inside the same `ToolbarSlotProvider`.
+- Lint and the TypeScript build pass.

package/skills/cratis-documentation-writing/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-documentation-writing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: cratis-documentation-writing
+description: Write and structure documentation using the Diátaxis framework — decide whether a page is a Tutorial, a How-to guide, Reference, or Explanation, then draft it in that style with complete runnable examples. Use when creating or reworking documentation pages for a Cratis-based project, its product, or its samples. Do not use for code generation, release operations, or inventing API facts the code does not show.
+license: MIT
+---
+
+# Documentation writing
+
+Documentation fails when it is written for the writer instead of the reader.
+The [Diátaxis framework](https://diataxis.fr/) fixes that by separating
+documentation into four types, each serving one distinct user need — and by
+refusing to mix them. A page that teaches, instructs, describes, and explains
+at once serves none of those needs well.
+
+This skill is documentation-system-agnostic: it applies to a docs site, a
+`docs/` folder in a repository, a wiki, or README files. Where a page goes and
+how navigation is wired is your project's own convention; this skill governs
+the *classification*, *structure*, and *prose* of what you write.
+
+## Classify before writing
+
+Determine which quadrant the page belongs to before drafting:
+
+| Type | Orientation | Analogy | When to use |
+| --- | --- | --- | --- |
+| **Tutorial** | Learning | A lesson | Guide a newcomer step-by-step to a successful first outcome |
+| **How-to guide** | Problem-solving | A recipe | Show an experienced user how to accomplish a specific task |
+| **Reference** | Information | A dictionary | Describe the technical machinery — APIs, attributes, configuration |
+| **Explanation** | Understanding | A discussion | Clarify *why* something works the way it does, trade-offs, architecture |
+
+Rules per type:
+
+- **Tutorial** — never explain *why*; focus on *do this, then this*. Each step
+  must produce a visible, verifiable result. The reader must succeed even
+  while not yet understanding the concepts.
+- **How-to guide** — assume competence. State the goal, list prerequisites,
+  give the steps, done. No teaching.
+- **Reference** — exhaustive and terse. Tables, signatures, attribute lists.
+  No narrative.
+- **Explanation** — no steps. Discuss concepts, trade-offs, and design
+  decisions. Diagrams are welcome here.
+
+If a request seems to need two types at once, that is two pages linked to each
+other. If the type cannot be determined from the request, ask before writing.
+
+## Workflow
+
+1. **Clarify** — decide the document type, the target audience (newcomer,
+   experienced contributor, framework consumer, operator), the reader's goal,
+   and the scope: what to include *and* what to exclude.
+2. **Propose structure** — present an outline (headings plus a one-line
+   description each) before writing full content.
+3. **Write** — produce the full page in well-formatted Markdown, following the
+   style rules below.
+4. **Verify** — run the completion checklist at the end of this skill.
+
+## Writing style
+
+The voice is **direct, practical, and opinionated** — an experienced colleague
+explaining something to a capable developer, confident but never condescending.
+
+- **Active voice, present tense.** "Chronicle appends the event", not "The
+  event is appended by Chronicle."
+- **Second person.** "You configure…", not "One configures…" or "It is
+  possible to configure…".
+- **Lead with the most important information.** Do not bury the key point
+  after three paragraphs of context.
+- Use headings, lists, and code blocks to organize content; dense paragraphs
+  lose readers.
+- Focus on public APIs and features, never internal implementation.
+- Do not document third-party libraries; link to their own docs instead.
+- **American English only**: `color` not `colour`, `behavior` not `behaviour`,
+  `organize` not `organise`, `initialize` not `initialise`.
+
+## Code examples
+
+Examples are where documentation credibility is won or lost.
+
+- Every example must be **complete, correct, and runnable** — no pseudo-code,
+  no `// ...` elisions. If it cannot be shown complete, show a smaller thing
+  that can.
+- Never copy code verbatim from a repository — APIs change under copied
+  examples. Write purpose-built examples that demonstrate the documented
+  behavior.
+- Prefer the framework's canonical shapes. In a Cratis context that means
+  `record` types for commands, events, and read models; attributes as the
+  framework applies them; and the vertical-slice layout the project already
+  uses.
+- Show the outcome: expected output, the state change, or the query result an
+  example produces, so the reader can verify their attempt.
+
+## Diagrams
+
+Use [Mermaid](https://mermaid-js.github.io/mermaid/#/) for architecture
+(`graph TD` / `graph LR`), sequence flows (`sequenceDiagram`), and state
+transitions (`stateDiagram-v2`). A diagram replaces a paragraph of topology
+prose; it does not decorate one.
+
+## Contextual awareness
+
+- Read the existing documentation around the page you are writing first, and
+  match its tone, style, and terminology. If it is "event source" there, it is
+  "event source" everywhere.
+- Do not copy content from existing pages unless explicitly asked; link
+  instead.
+- Do not fabricate URLs or version numbers — link only to resources you can
+  verify exist.
+
+## Completion checklist
+
+A page is done when:
+
+- The Diátaxis type is chosen deliberately and the page holds to that one
+  type, linking out to the other types instead of drifting into them.
+- The audience and their goal were identified before writing, and the first
+  screen serves that goal.
+- Every code example is complete, runnable, and purpose-built.
+- Terminology is consistent with the surrounding documentation.
+- All internal links resolve; all external links are real.
+- Mermaid blocks are syntactically valid.
+- The file ends with a single trailing newline.

package/skills/cratis-event-model-diagram/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-event-model-diagram/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: cratis-event-model-diagram
+description: Create and maintain Mermaid eventmodeling diagrams for a Cratis module or feature, and keep them in sync with the code. Use when adding, renaming, moving, or deleting a module, feature, behavior, command, event, read model, automation, translation, or cross-module flow. Do not use to decide the event vocabulary or stream boundaries - settle the model first, then render it here.
+license: MIT
+---
+
+# Event model diagrams
+
+Render an already-decided event model as a Mermaid `eventmodeling` diagram that
+lives beside the code and is updated in the same change. If the event vocabulary
+or the stream boundaries are not yet decided, model first; this skill draws a
+chosen model, it does not choose one.
+
+## Source authority
+
+Diagrams use **Mermaid's native `eventmodeling` diagram type** (Mermaid v11.15
+and later). The grammar is owned by Mermaid, and
+<https://mermaid.js.org/syntax/eventmodeling.html> is the authority whenever this
+file and Mermaid disagree. Confirm the Mermaid version available to the renderer
+before relying on a construct.
+
+The Cratis artifacts a diagram refers to are verified against `Cratis.Chronicle`
+`16.45.2` and the Arc query and command surface it is used with.
+
+## What an event model is
+
+It arranges a module's commands, events, read models, and automations on a
+left-to-right business-flow timeline, answering *"what happens in this module,
+and in what order?"*.
+
+One file per module or feature, alongside the code, with the diagram in a fenced
+`mermaid` block. A system-overview file at the source root shows only
+cross-module flows.
+
+## Grammar cheat sheet
+
+**Frame prefix:** `tf` (timeframe — auto-connects to the previous frame) and
+`rf` (resetframe — breaks the chain; start each independent flow with it). `rf`
+*replaces* `tf`; `tf N rf Name` is invalid.
+
+**Frame:** `<prefix> <number> <type> <EntityName>`. The number is unique;
+declaration order does not matter because frames position by reference.
+
+| Type | Swimlane | Represents |
+| --- | --- | --- |
+| `ui` | UI / Automation | the persona interacting — a persona name, never a screen name |
+| `pcr` | UI / Automation | a reactor or automation processor |
+| `cmd` | Command / Read Model | a command |
+| `rmo` | Command / Read Model | a read model |
+| `evt` | Events | an event type, using the exact self-describing type name |
+
+**Multiple sources (`->>`).** A read model or fan-in reactor fed by several
+frames references them by frame number:
+
+```text
+tf 10 rmo <ReadModelName> ->> 03 ->> 06 ->> 09
+```
+
+**Namespaces.** A `Module.` prefix creates a sub-swimlane. Use it for
+cross-module entities and throughout the system overview.
+
+**Comments.** `%% -- Section --`. A section header is a comment, never a frame.
+
+## Behavior type to pattern
+
+```text
+%% -- State change: <CommandName> --------------------
+rf 01 ui <Persona>
+tf 02 cmd <CommandName>
+tf 03 evt <EntityName><PastTenseVerb>
+
+%% -- State view: <ReadModelName> (consumed by <Persona>) --
+rf 04 rmo <ReadModelName> ->> 03
+tf 05 ui <Persona>
+
+%% -- Automation: <ReactorName> (external side effect only) --
+rf 06 evt <EntityName><PastTenseVerb>
+tf 07 pcr <ReactorName>
+
+%% -- Translation: <Source>.<Event> -> <Target>.<Reactor> --
+rf 08 evt <SourceModule>.<EventName>
+tf 09 pcr <TargetModule>.<ReactorName>
+tf 10 evt <TargetModule>.<EventName>
+```
+
+- A state view's `rmo` references the event frames it projects from by number;
+  its consumer `ui` frame auto-chains after it. A passive read model has no
+  consumer UI — emit only the `rmo ... ->>` line with a `%% passive` comment.
+- Translation flows are reactor-only: `evt` to `pcr` to `evt`, with no
+  intermediate `cmd`. If you draw a `cmd` between the `pcr` and the resulting
+  event, it is an **automation**, not a translation — reclassify it.
+- Several consumers of one read model: declare each consumer `ui` as its own
+  `rf` frame with an explicit `->>` back to the `rmo`.
+
+## The command rules table
+
+Mermaid's eventmodeling grammar has no shape for validation or guards. After the
+diagram, add a `## Command rules` section: a table with **Command**, **Rules**,
+and **Emits / result**, summarizing validator, value-invariant, provider,
+concurrency, and authorization rules plus no-op and diff behavior, in human
+language. Include commands that emit no event.
+
+## Process
+
+1. **Discover** the behaviors by scanning the module for the artifacts that
+   define them: command records for state changes, read models without a command
+   handler for state views, `IReactor` implementations that call out of the
+   system for automations, and `IReactor` implementations that return events for
+   translations. Use the exact type names.
+2. **Order** frames by domain causality — what must happen before what. Put state
+   views after the events they project from. Use `rf` only between independent
+   flows, never between sibling events of one flow, or the diagram becomes a
+   tall tower one event wide.
+3. **Write** the diagram and the command-rules table.
+4. **Verify** it renders without a syntax-error banner, then reconcile it against
+   the source: every behavior appears, classified by the marker it actually
+   contains. A clean render proves valid Mermaid, not completeness — close the
+   gaps against the code, never from memory.
+
+## Common mistakes
+
+- **A command that emits several events** chains them with consecutive
+  `tf ... evt ...` frames. Do not fight the auto-chain with `rf`.
+- **The same event emitted from several commands** gets its own `tf evt` frame at
+  each emit point. Do not merge them into one.
+- **Several consumers of one read model** — the first auto-chains; each
+  additional consumer needs an explicit `rf <n> ui <Persona> ->> <rmo-number>`.
+- **A screen name in the `ui` lane.** The `ui` lane is the persona.
+- **A section header written as a frame.** Section headers are `%%` comments.
+- **A cross-module flow updated in one place.** It needs three: the overview
+  diagram, the source module's outputs, and the target module's inputs.
+
+## Verify
+
+- The diagram renders with no syntax-error banner.
+- Every behavior in the module appears, with the type its code actually has.
+- Every event frame uses the exact event type name from the source.
+- Independent flows start with `rf`; sibling events within a flow do not.
+- Passive read models have no consumer `ui` frame.
+- The command-rules table covers every command, including those that emit
+  nothing.
+- Cross-module flows are reflected in all three places.

package/skills/cratis-fundamentals-concept/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.