@cratis/pi 7.34.1 → 7.36.0

package/package/corpus/skills/cratis-components-styling/SKILL.md

@@ -11,13 +11,13 @@ third-party theme engine, preset or provider underneath it: what a Cratis
 application looks like is decided by three Cratis-owned stylesheet entries and
 the `--cratis-*` custom properties they read. Getting the setup wrong shows up as
 components rendering completely unstyled, which is the single most common
-first-run problem — and it is fixed with two `import` lines.
+first-run problem — start by checking the CSS entry.
 
 ## Verified product sources
 
 | Package | Version | Verified from |
 | --- | --- | --- |
-| `@cratis/components` | `4.6.0` | its package manifest (`exports`, no vendor UI dependency or peer), `Source/tokens.css`, `Source/MIGRATION.md`, `Documentation/Styling/*`, `Documentation/Common/cratis-components-provider.md`, `Documentation/renderers/*` |
+| `@cratis/components` | `4.26.4` | its package manifest (`exports`, no vendor UI dependency or peer), `Source/tokens.css`, `Source/MIGRATION.md`, `Documentation/Styling/*`, `Documentation/Common/cratis-components-provider.md`, `Documentation/renderers/*` |
 
 Components declares **no** PrimeReact, PrimeIcons or PrimeUI dependency or peer.
 React Aria supplies focus, overlay, collection and date behavior *internally* —
@@ -31,23 +31,39 @@ license are the application's.
 
 Two things, or the components render unstyled:
 
-1. **Import the stylesheets, in this order**, once, at the entry point:
+1. **Import the stylesheets, in this order**, in `index.css`; the entry point
+   imports that file with `import './index.css'`:
 
-   ```ts
-   import '@cratis/components/tokens';   // the semantic --cratis-* seam, with conservative light defaults on :root
-   import '@cratis/components/styles';   // structural rules for every component, in low-priority Cratis layers
-   import '@cratis/components/theme';    // optional: the maintained baseline look, dark mode, forced colors
+   ```css
+   @import '@cratis/components/tokens';
+   @import '@cratis/components/styles';
+   @import '@cratis/components/theme'; /* optional baseline */
    ```
 
+   Direct CSS subpath imports from TypeScript need ambient declarations on
+   TypeScript 6, otherwise TS2882. To avoid the roughly 32 KiB gzip aggregate,
+   replace `styles` with `styles/base` and the needed `<subpath>/styles` entries
+   (for example `Dialogs/styles`, `DataTables/styles`). Area order does not matter.
+
    `tokens` first — `styles` and `theme` both read it. `styles` also carries the
-   split-pane CSS the `DataPage` details pane needs, so it is not optional even
-   in a fully custom-styled app. `styles` contains **no** Tailwind Preflight, no
+   split-pane CSS the `DataPage` details pane needs; use the aggregate or the
+   corresponding area sheets even in a fully custom-styled app. `styles` contains **no** Tailwind Preflight, no
    global reset and no copy of the token values.
 
 2. **Mount `CratisComponentsProvider`** (from the package root,
    `@cratis/components`) above every Cratis component. It carries `locale` and
    the Components-owned `messages`, and mounts the toast region with `toaster`;
-   it carries **no** styling. The Components 3 renderer keys — `license`, `theme`,
+   it carries **no** theme. `toaster` accepts `boolean | ToasterProps`: without
+   it or a standalone `<Toaster />`, no toast appears; mount one, never both.
+   Message groups are `paginator`, `datePicker`, `dropdown`, `dialog`, `stepper`,
+   `notifications`, `dataTable`, `filter`, `columnFilter`, `toolbar`. `locales`
+   is deprecated. `value.icons` replaces `close`, `remove`, `expand`,
+   `sortAscending`, `sortDescending`, `previous`, `next`, `clear`; a component
+   prop wins over the provider, then the built-in glyph (`null` draws none).
+   `useCratisIcon()` resolves that vocabulary. Provider props also include
+   `overlayEnvironment`, `rendererSetup` (non-secret booleans), experimental
+   `libraryMode` (`strict` / `degrade`) and `rendererFallback` (`core` / `throw`).
+   The Components 3 renderer keys — `license`, `theme`,
    `defaults`, global `pt`, `ptOptions`, `ripple`, `unstyled`, z-index — are a
    type error on purpose, so a migrated app cannot compile a provider whose
    visual configuration silently does nothing.
@@ -72,8 +88,10 @@ A theme is **CSS**. No JavaScript preset, provider option or wrapper class is
 required for the normal whole-application setup. The product's CSS is written
 *outside* a cascade layer, so it wins over all three Components layers
 (`cratis-theme`, `cratis-components`, `cratis-utilities`) without specificity
-tricks; if the product uses its own layers, declare their order explicitly after
-the Components imports.
+tricks for structural rules. Tokens and theme are unlayered: their overrides
+still need the correct specificity. If the product uses layers, name the
+`cratis-*` layers in its **first** layer-order statement, before any stylesheet
+(see Tailwind below).
 
 ### Baseline theme and dark mode
 
@@ -91,7 +109,14 @@ document.documentElement.classList.toggle('cratis-dark', darkMode);
   wins over an ambient root `cratis-dark`.
 - An independently themed island puts `cratis-theme` on the subtree and adds
   `cratis-dark` or `cratis-light` there (on the same element, or on an ancestor).
-- Override any `--cratis-*` variable *after* the theme import to adapt it.
+- A plain `:root` override after `theme` loses to dark selectors such as
+  `:root.cratis-dark`, `.cratis-theme.cratis-dark`, and the system-dark
+  `:root:not(.cratis-light)`. Match the scheme selectors' specificity and place
+  overrides after the import, including subtree selectors when using islands.
+  Or omit `theme` and use the product-theme setup below.
+- Components 4.22.1+ maps Arc's `--color-error` / `--color-error-bg` in both dark
+  schemes. A product theme omitting `theme` must define those variables itself;
+  do not carry forward the old dark-error contrast workaround.
 
 ### Product theme
 
@@ -188,7 +213,8 @@ The typed part families: `ButtonParts`/`IconButtonParts` (`root`, `icon`,
 (`root`, `trigger`, `value`, `clear`, `indicator`, `popover`, `listbox`, `option`,
 `filter`, `multiple`); `DataTableParts` (`root`, `search`, `searchInput`,
 `tableContainer`, `table`, `head`, `headerRow`, `headerCell`, `body`, `row`,
-`cell`, `emptyRow`, `emptyCell`); `TablePaginatorParts` (`root`, `range`, `info`,
+`cell`, `emptyRow`, `emptyCell`, `loadingRow`, `loadingCell`, `failureRow`,
+`failureCell`); `TablePaginatorParts` (`root`, `range`, `info`,
 `first`, `previous`, `next`, `last`); `StepperParts` (`root`, `list`, `step`,
 `header`, `number`, `title`, `separator`, `panels`, `panel`);
 `ToasterPassThrough` (`region`, `toast`, `icon`, `content`, `title`,
@@ -218,7 +244,11 @@ The default renderer is built in; omit `library` on the provider. Three optional
 adapter packages exist — `@cratis/components.mui` (MUI 9),
 `@cratis/components.primereact` (PrimeReact 11), `@cratis/components.primereact10`
 — and each adapts exactly **nine primitive slots**: button, icon-button, text
-input, text area, checkbox, radio, switch, progress bar, surface. Pass the
+input, text area, checkbox, radio, switch, progress bar (`common.progress`, not
+`common.progressBar`), surface. Install and upgrade each adapter at **exactly
+the same version** as `@cratis/components`; Node >=22 is required. The broader
+renderer contract also has an atomic `common.tooltip` slot accepting any React
+node, but it is not one of the nine stable presentation slots. Pass the
 adapter's manifest to the provider's `library` prop. Dialogs, dropdowns, tables,
 date pickers, tooltips, paginators, toasts and steppers stay Components-owned
 regardless; an adapter never restores a vendor's public API, and the vendor's
@@ -232,16 +262,23 @@ Tailwind is **one supported way to write the CSS above, not the Cratis default.*
 It is a fine tool for authoring the token mapping and part rules; it is not a
 substitute for them. Components' own internal utilities are prefixed (`cratis:*`)
 and are not public styling hooks. `styles` ships no Preflight and no reset of its
-own; if the application uses Tailwind's Preflight or its own cascade layers,
-declare the layer order explicitly after the Components imports (Components says
-nothing more specific than that — verify the result in the running app).
+own. A host with layers must put this order in its **first** `@layer` statement,
+parsed before any stylesheet (for example an inline `<style>` in the host):
+
+```css
+@layer properties, theme, base, cratis-theme, cratis-components, cratis-utilities, components, utilities;
+```
+
+Components layers belong above the product reset and below product utilities.
+Declaring them after the imports cannot reorder layers already established;
+otherwise component rules beat product utilities and `pt` classes lose.
 
 ## Verify
 
 - No PrimeReact / PrimeIcons / PrimeUI package remains in the manifest unless the
   application itself imports it directly — and then it has its own provider.
-- `CratisComponentsProvider` (root import) wraps the tree and carries only
-  `locale`, `messages` and `toaster`.
+- `CratisComponentsProvider` (root import) wraps the tree with locale/messages;
+  exactly one toaster is mounted when notifications are used.
 - `@cratis/components/tokens` and `@cratis/components/styles` are imported once
   at the entry point, tokens first; `theme` is imported or deliberately omitted;
   product CSS comes after.

package/package/corpus/skills/cratis-components-styling/verification.json

@@ -0,0 +1,13 @@
+{
+  "skill": "cratis-components-styling",
+  "input": "Set up Components styles under host cascade layers and customize dark mode without breaking notifications.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "@import '@cratis/components/tokens'" },
+    { "kind": "skill-contains", "value": "first** `@layer` statement" },
+    { "kind": "skill-contains", "value": "plain `:root` override after `theme` loses" },
+    { "kind": "skill-contains", "value": "--color-error-bg" },
+    { "kind": "skill-contains", "value": "mount one, never both" },
+    { "kind": "skill-contains", "value": "common.progress`" }
+  ]
+}

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

@@ -9,15 +9,16 @@ license: MIT
 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).
+**cratis-arc-react-page** skill). `ActionMenubar` (`Common`) shares the toolbar's
+`focusMode` contract when building an action bar outside DataPage.
 
 ## Verified product sources
 
 | Package | Version | Verified from |
 | --- | --- | --- |
-| `@cratis/components` | `4.6.0` | its package manifest, `Source/Toolbar/*` (exports and props), `Documentation/Toolbar/*`, `Documentation/Common/icon.md` |
-| `react-icons` | `5.7.0` | dependency of `@cratis/components@4.6.0` — the icon source the examples use |
-| `react` | `^19.0.0` | peer of `@cratis/components@4.6.0` |
+| `@cratis/components` | `4.26.4` | its package manifest, `Source/Toolbar/*` (exports and props), `Documentation/Toolbar/*`, `Documentation/Common/icon.md` |
+| `react-icons` | `5.7.0` | dependency of `@cratis/components@4.26.4` — the icon source the examples use |
+| `react` | `^19.0.0` | peer of `@cratis/components@4.26.4` |
 
 ## Import from the subpath
 
@@ -28,7 +29,7 @@ is `<ToolbarGroup>`, never `<Toolbar.Group>`.
 import {
     Toolbar, ToolbarButton, ToolbarSeparator, ToolbarGroup,
     ToolbarSection, ToolbarContext, ToolbarFanOutItem, ToolbarFolder,
-    ToolbarSlot, ToolbarSlotProvider, ToolbarLayout, useToolbarSlot,
+    ToolbarSlot, ToolbarSlotProvider, ToolbarLayout, useToolbarSlot, ToolbarFocusMode,
 } from '@cratis/components/Toolbar';
 ```
 
@@ -86,6 +87,13 @@ const [activeTool, setActiveTool] = useState('select');
 </Toolbar>
 ```
 
+When `active` is supplied, `ToolbarButton` sets `aria-pressed`; omission keeps
+it an ordinary button. `ToolbarFocusMode.Arrows` (default) enables arrows and
+Home/End while keeping each tool's Tab stop. `SingleTabStop` uses the WAI-ARIA
+pattern (returns to the last focused tool); custom widgets and explicit tab
+indices retain their own behavior. `None` disables toolbar keyboard handling.
+Name the toolbar with `aria-label` or `aria-labelledby`.
+
 ## Step 3 — Separators and horizontal layout
 
 Give `ToolbarSeparator` the same `orientation` as its `Toolbar`, and move
@@ -157,6 +165,21 @@ away from the screen edge the toolbar sits against.
 `mode` is `'grid'` (default) or `'list'`; `maxColumns` (default `5`) applies to
 grid mode only, and `folderDirection` is `'right'` or `'left'`.
 
+For a headed catalog use `presentation='drawer'` and `items` (children optional):
+
+```tsx
+<ToolbarFolder icon={<FaShapes />} title='Shapes' presentation='drawer'
+    items={[{ id: 'rect', title: 'Rectangle', icon: <FaVectorSquare />, payload: 'rect' }]}
+    onActivate={item => insertShape(item.payload)} />
+```
+
+This excerpt assumes the host's `insertShape` and icons. Each `ToolbarDrawerItem`
+has `id`, `title`, `icon`, `payload`, optional `disabled` and `disabledReason`.
+`heading` defaults to `title`; `closeLabel` falls back to
+`messages.toolbar.closeDrawer`, then English. `onItemDragStart/End` receive the
+item and drag event; drawer tiles are `draggable` by default. `closeOnInsert`
+(default false) closes on activation or successful drop, never cancelled drag.
+
 ## Step 6 — Contributing buttons from elsewhere
 
 A slot lets a component far from the toolbar contribute buttons without prop
@@ -189,6 +212,9 @@ a `slotName`.
 | --- | --- | --- |
 | `children` | `ReactNode` | required |
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` |
+| `focusMode` | `ToolbarFocusMode` (also exported by `Common`) | `Arrows` |
+| `aria-label` / `aria-labelledby` | `string` | provider `messages.toolbar.label` fallback |
+| `className` / `pt` | class / `ToolbarParts` | root presentation |
 | `draggable` | `boolean` | `false` — makes child buttons draggable |
 | `onItemDragStart` | `(data: unknown, event: React.DragEvent) => void` | — |
 
@@ -199,7 +225,8 @@ a `slotName`.
 | `title` | `string` | **required** — the accessible name and the tooltip text |
 | `icon` | `string \| ReactNode` | — |
 | `text` | `string` | — |
-| `active` | `boolean` | `false` |
+| `active` | `boolean` | when supplied, sets `aria-pressed` |
+| `className` / `pt` | class / `ToolbarButtonParts` | per-instance presentation |
 | `onClick` | `() => void` | — |
 | `tooltipPosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
 | `draggable` | `boolean` | inherited from the enclosing `Toolbar` |
@@ -236,7 +263,10 @@ Renders nothing itself — it is a marker `ToolbarSection` reads.
 `tooltipPosition?` (default `'right'`) ·
 `folderDirection?: 'right' | 'left'` (default `'right'`) ·
 `mode?: 'grid' | 'list'` (default `'grid'`) · `maxColumns?: number` (default `5`) ·
-`children: ReactNode`.
+`children?: ReactNode` · `className?: string` · `pt?: ToolbarFolderParts`.
+`presentation?: 'compact' | 'drawer'` (default compact), `heading`, `closeLabel`,
+`items`, `onActivate`, `onItemDragStart/End`, `draggable`, `closeOnInsert` configure
+the drawer described above (default `maxColumns` is 3 there).
 
 ### `ToolbarSlot` / `ToolbarSlotProvider` / `ToolbarLayout`
 

package/package/corpus/skills/cratis-components-toolbar/verification.json

@@ -0,0 +1,12 @@
+{
+  "skill": "cratis-components-toolbar",
+  "input": "Build a keyboard-navigable toolbar with a drawer catalog and pressed-state buttons.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "ToolbarFocusMode.Arrows" },
+    { "kind": "skill-contains", "value": "SingleTabStop" },
+    { "kind": "skill-contains", "value": "aria-pressed" },
+    { "kind": "skill-contains", "value": "presentation='drawer'" },
+    { "kind": "skill-contains", "value": "messages.toolbar.closeDrawer" }
+  ]
+}

package/package/corpus/skills/cratis-engineering-csharp-conventions/SKILL.md

@@ -11,6 +11,12 @@ repository. They are **conventions**, not framework contracts: nothing here is
 enforced by an analyzer unless this skill says so. Follow them for consistency;
 do not claim the framework requires them.
 
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Fundamentals` | `7.23.0` | DI lifetime attributes and `IInstancesOf<T>` instance resolution |
+
 ## Route near misses
 
 - The question is what a Cratis product API *does*: resolve it against the

package/package/corpus/skills/cratis-engineering-csharp-conventions/references/exceptions-logging-and-di.md

@@ -280,9 +280,11 @@ Rules:
 - Never register a type that exists to be discovered. Mark it `[Singleton]`, or
   rely on the `IFoo → Foo` convention for a transient, and delete the
   registration line.
-- `IInstancesOf<T>` resolves at the point of access, so an implementation added
-  later in the assembly becomes available without touching the consumer or any
-  composition root.
+- `IInstancesOf<T>` fixes its type set at construction and resolves instances on
+  each enumeration through the consumer's provider (Fundamentals 7.23.0). Late
+  assemblies do not update that set. A singleton captures the root provider;
+  never use it to enumerate scoped implementations. Resolve a scoped or
+  transient consumer inside a scope instead; follow `csharp.md`'s lifetime rule.
 - `IEnumerable<T>` remains the right type to **return** from a method that
   yields a sequence of values. The rule applies only to enumerating
   *implementations* of an abstraction.

package/package/corpus/skills/cratis-fundamentals-concept/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-fundamentals-concept
-description: Create strongly typed Cratis domain values with ConceptAs and Chronicle event-source identities with EventSourceId. Use when a C# domain value has meaning beyond its primitive or when an identity is actually used as a Chronicle event-source/stream ID. Do not use for enums, DTO-only transport values, arbitrary non-stream entity IDs, or event schema migration.
+description: Create strongly typed Cratis domain values with ConceptAs and Chronicle event-source identities with EventSourceId. Use when a C# or TypeScript domain value has meaning beyond its primitive or when an identity is actually used as a Chronicle event-source/stream ID. Do not use for enums, DTO-only transport values, arbitrary non-stream entity IDs, or event schema migration.
 license: MIT
 ---
 
@@ -17,6 +17,7 @@ This skill is verified against these exact public releases:
 | --- | --- | --- |
 | `Cratis.Fundamentals` | `7.23.0` | `Cratis.Concepts.ConceptAs<T>`, `IGeneratable<TSelf>` and `GenerateValue` |
 | `Cratis.Chronicle` | `18.3.0` | `Cratis.Chronicle.Events.EventSourceId` and `EventSourceId<T>` |
+| `@cratis/fundamentals` | `7.23.0` | TypeScript `ConceptAs<T>`, `field`, `Guid`, and JSON conversion |
 
 Reverify product sources before claiming support for another version.
 
@@ -81,7 +82,7 @@ Do not assume `string.Empty`, `0`, or `Guid.Empty` is universally invalid.
 Check the Cratis.Fundamentals version the project resolves first. Arc first
 pinned **7.23.0 in v22.66.0** (also verified at v22.68.0); the older-version
 caveat is not a reason to add a direct reference for Arc 22.66.0+ when it already
-resolves 7.23.0 or later. Chronicle **v19.43.0** still pins **7.22.0** in
+resolves 7.23.0 or later. Chronicle **v19.50.0** still pins **7.22.0** in
 `Directory.Packages.props`. For older Arc or Chronicle-only applications, when
 the resolved version is below 7.23.0, add a direct `Cratis.Fundamentals` 7.23.0
 or later package reference, or keep the existing `static New()` (without the
@@ -133,6 +134,14 @@ it; see `cratis-arc-command` for declaration and migration, and
 `cratis-specifications-csharp` for named scenario pins (Arc **22.67.0+**).
 Guide: `/fundamentals/csharp/generating-values/`.
 
+## Create a TypeScript value concept
+
+Read [typescript-concepts.md](references/typescript-concepts.md) when declaring
+TypeScript concepts, choosing union versus instance-only types, or converting
+Guid-backed values with `@field` and `JsonSerializer`. A union accepts the raw
+primitive too; it does not enforce nominal separation between domain values.
+C#'s `IComparable` and null-value constraints above are not TypeScript contracts.
+
 ## Create a Guid-backed Chronicle stream identity
 
 Use this shape only for an identity actually supplied to Chronicle append/read
@@ -203,10 +212,14 @@ untyped `EventSourceId`, and `EventSourceId<T>`. Those operators do not create
 your derived `<ConceptName>` from `T`, string, or untyped `EventSourceId`.
 Declare only the derived-type conversions your domain API needs.
 
-String and Guid are the safest round-trip primitives. Chronicle also supports
-constructible `ConceptAs<string>` and `ConceptAs<Guid>` values. Other comparable
-values rely on `Convert.ChangeType`; verify round-trip behavior before using
-them as stream IDs.
+String and Guid remain the safest stream-id primitives. At **Chronicle v19.50.0**
+(`Source/Clients/DotNET/Events/EventSourceId.cs:148-174`), numeric/date/time ids
+and concepts wrapping them convert with invariant culture (since 19.37.3).
+`DateTime`, `DateTimeOffset`, `DateOnly`, `TimeOnly` use `"O"`; `TimeSpan` uses
+`"c"`. Decimal `123.45` stays `"123.45"` even under nb-NO.
+**Existing streams may have different legacy ids** if written under date/time or
+decimal-comma formats: read/append them with their old untyped id, rather than
+silently opening a new stream under the new format.
 
 ### Unspecified and sensitive identities
 

package/package/corpus/skills/cratis-fundamentals-concept/references/typescript-concepts.md

@@ -0,0 +1,97 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# TypeScript value concepts
+
+## Contents
+
+- Declare a concept
+- Convert non-primitive values
+- Serialization boundaries
+- Other typed values
+
+Verified against `@cratis/fundamentals` 7.23.0: `ConceptAs.ts`,
+`JsonSerializer.ts`, and `Documentation/typescript/concept_as.md` in Fundamentals.
+
+## Declare a concept
+
+The convenient union pattern (7.13.0+) accepts either a concept instance or its
+underlying primitive. Supply the runtime class, not the union type, to `@field`:
+
+```typescript
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, field, JsonSerializer } from '@cratis/fundamentals';
+
+class UserIdConcept extends ConceptAs<string> {}
+export type UserId = UserIdConcept | string;
+
+class User {
+    @field(UserIdConcept)
+    id!: UserId;
+}
+
+const user = new User();
+user.id = 'user-123';
+const json = JsonSerializer.serialize(user);
+const restored = JsonSerializer.deserialize(User, json);
+```
+
+`json` is `{"id":"user-123"}` and `restored.id` is a `UserIdConcept` instance.
+The union is an assignment convenience, not nominal type safety: different
+string-backed concepts still accept the same string. When callers must use
+instances, export the class directly instead, as the Arc TypeScript validation
+skill does with `Name`. `static readonly valueType = String` is valid but optional
+for a string-backed concept; it does not require a different naming pattern.
+
+## Convert non-primitive values
+
+From 7.19.5, `valueType` tells deserialization to convert the inner payload before
+constructing the concept. Without it, a Guid wire value remains a string:
+
+```typescript
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, field, Guid } from '@cratis/fundamentals';
+
+class UserIdConcept extends ConceptAs<Guid> {
+    static readonly valueType = Guid;
+}
+export type UserId = UserIdConcept | Guid;
+
+class User {
+    @field(UserIdConcept)
+    id!: UserId;
+}
+```
+
+## Serialization boundaries
+
+Use `JsonSerializer.serialize(instance)` and
+`JsonSerializer.deserialize(Type, json)` for typed conversion. Concepts serialize
+to their inner value and deserialize to instances when their runtime class is
+supplied as metadata. Collections and maps unwrap concepts too (7.17.0+).
+
+Keep one resolved copy of `@cratis/fundamentals`: duplicate copies trigger a
+warning and can cause identity/`instanceof` problems. The 7.23.0 serializer uses
+stable type keys for concepts and converters, but that does not make all
+cross-copy identity checks safe.
+
+## Other typed values
+
+The root exports `Guid`, `DateOnly`, `TimeOnly`, `TimeSpan`, `ValueMap`, `field`,
+and `JsonSerializer`. Subpaths `/json`, `/geospatial`, and `/reflection` are
+exported too. The package declarations support NodeNext resolution (7.19.6+).
+Use `JsonSerializer.registerConverter(converter)` for a custom `JsonConverter`
+instance, rather than replacing the serializer.
+
+`@field` supports legacy and standard decorators (7.18.0+); standard fields need
+decorator metadata support. Load `@cratis/fundamentals/reflection` before defining
+metadata-dependent types. For arrays, declare the element constructor with
+`@field(Array, { genericArguments: [Item] })`, where `Item` is the model's runtime
+class, not a type alias (7.19.5+).
+
+Dependent Arc/Chronicle peer ranges are not feature guarantees: check the actual
+resolved Fundamentals version before relying on these version-qualified APIs.

package/package/corpus/skills/cratis-fundamentals-concept/verification.json

@@ -6,6 +6,9 @@
     { "kind": "skill-contains", "value": "ConceptAs<T>" },
     { "kind": "skill-contains", "value": "IGeneratable<TSelf>" },
     { "kind": "skill-contains", "value": "GenerateValue.Uuid()" },
-    { "kind": "skill-contains", "value": "not** monotonic within a" }
+    { "kind": "skill-contains", "value": "not** monotonic within a" },
+    { "kind": "skill-contains", "value": "@cratis/fundamentals" },
+    { "kind": "skill-contains", "value": "typescript-concepts.md" },
+    { "kind": "skill-contains", "value": "does not enforce nominal separation" }
   ]
 }

package/package/corpus/skills/cratis-fundamentals-concept-go/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: cratis-fundamentals-concept-go
+description: Define named Go domain values with Fundamentals.Go concepts, explicit UUID text and JSON codecs, and scalar recognition. Use when an identity or scalar must not be interchangeable with its primitive. Do not use for C# ConceptAs types, event migration or dependency-injection setup.
+license: MIT
+compatibility: Go 1.26 or later for Fundamentals.Go v0.3.2.
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Typed domain values in Go
+
+> **Experimental v0:** Fundamentals.Go **v0.3.2**. Companion product guidance
+> targets Chronicle.Go **v0.9.1** and Arc.Go **v0.1.1**; minor releases may break APIs.
+
+Use a defined type for each domain value, not a type alias that remains
+interchangeable with every UUID/string. Plain constructors are enough; adopting
+concepts does not require a dependency-injection container.
+
+## Verified product sources
+
+| Product | Tag | Source checked |
+| --- | --- | --- |
+| Fundamentals.Go (`github.com/cratis/fundamentals.go`) | `v0.3.2` | `concepts/concept.go`, `concepts/uuid.go`, `concepts/uuid_dotnet.go`, `concepts/underlying.go`, `concepts/check_json.go`, `documentation_examples_test.go` |
+
+[Source at v0.3.2](https://github.com/Cratis/Fundamentals.Go/tree/v0.3.2)
+is authoritative, not the getting-started page's older v0.3.0 installation pin.
+The root module is standard-library-only and requires Go 1.26.
+
+## Define and encode an identity
+
+Install `github.com/cratis/fundamentals.go@v0.3.2` into a consumer module.
+This complete package defines an author identity and its codecs:
+
+```go
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+package domain
+
+import "github.com/cratis/fundamentals.go/concepts"
+
+// AuthorID identifies an author in the domain.
+type AuthorID concepts.UUID
+
+var _ concepts.Concept[concepts.UUID] = AuthorID{}
+
+// ConceptValue exposes the declared scalar representation.
+func (id AuthorID) ConceptValue() concepts.UUID { return concepts.UUID(id) }
+
+// MarshalText encodes canonical dashed UUID text.
+func (id AuthorID) MarshalText() ([]byte, error) {
+	return concepts.UUID(id).MarshalText()
+}
+
+// MarshalJSON encodes a UUID string, not a byte array.
+func (id AuthorID) MarshalJSON() ([]byte, error) {
+	return concepts.UUID(id).MarshalJSON()
+}
+
+// UnmarshalText decodes UUID text without changing id on failure.
+func (id *AuthorID) UnmarshalText(data []byte) error {
+	return (*concepts.UUID)(id).UnmarshalText(data)
+}
+
+// UnmarshalJSON decodes a UUID string without changing id on failure.
+func (id *AuthorID) UnmarshalJSON(data []byte) error {
+	return (*concepts.UUID)(id).UnmarshalJSON(data)
+}
+
+// ParseAuthorID reads an identity in dashed UUID notation.
+func ParseAuthorID(text string) (AuthorID, error) {
+	id, err := concepts.ParseUUID(text)
+	return AuthorID(id), err
+}
+```
+
+Defined types do **not** inherit methods. Without these forwarding codecs, a
+UUID-derived value can serialize as an array. Value encoding receivers also work
+for unaddressable map entries; decoding needs a pointer receiver. Test text,
+JSON, map-key and invalid-input round trips, not just the marker assertion.
+
+`ParseUUID` accepts dashed 8-4-4-4-12 notation, including uppercase hex, and emits
+lowercase dashed text. UUID bytes are RFC/network order, not .NET
+`Guid.ToByteArray` order. Zero is `Guid.Empty`; UUID JSON decoding rejects `null`.
+Use an explicit nullable representation when absence is part of the contract.
+`NewUUID` returns a cryptographically random v4 UUID **and an error**.
+
+## Recognition is not business validation
+
+`Concept[T]` declares `ConceptValue() T`. A recognized declaration also needs
+value text/JSON encoders and pointer decoders representing that scalar. Supported
+representations are the built-in string/bool/numeric types and Fundamentals'
+`UUID`, `DateOnly`, `TimeOnly`, `TimeSpan`; arbitrary defined replacements are not
+accepted as scalar representations.
+
+`Underlying` checks declaration metadata without running application code.
+`CheckJSON` checks encoded scalar shape, not business invariants or equality to
+`ConceptValue`. Put domain rules in your constructor/validation boundary and test
+them; do not assume implementing a marker validates input everywhere.
+
+`ParseDotNetGUID` is an opt-in compatibility parser for broader .NET forms. It
+does not change `ParseUUID` or text/JSON/SQL codecs. Limit untrusted input and use
+it only when importing that compatibility contract, not for canonical admission.
+
+## Verify
+
+- Compile and round-trip the named value against the pinned module without local replacements.
+- Verify canonical wire bytes, zero/null policy and failure-atomic decoders.
+- Check domain invariants separately from scalar recognition.
+- Chronicle.Go v0.9.1 and Arc.Go v0.1.1 each require Fundamentals.Go v0.1.0;
+  this standalone v0.3.2 example is not a demand to upgrade their dependencies.