aw-spec-cli 0.1.2 → 0.1.4

package/assets/docs/components/QrGenerator/integration.md

@@ -10,8 +10,12 @@
 ## Agent workflow — execute in order
 
 1. **Load context.** Read [README.md](./README.md) and this file.
-2. **Locate target projects** (see [[folder-structure]]): `…Application` (injects `IQRGenerator`),
-   `…Infrastructure` (does the registration), `…Service` (API endpoints).
+2. **Resolve the host project** `<HostProject>` (see [[folder-structure]], [[components-readme]] R0.2):
+   the single startup project that owns **`Program.cs`** + the ASP.NET Core web SDK —
+   `<SampleProjectName>.Service` (Vertical Slice foundation), `<SampleProjectName>.API` (Modular
+   Monolith foundation), or another name in a future template. **Find it by locating `Program.cs`, not
+   by assuming the name.** There is **no** separate `…Application` / `…Infrastructure` project in these
+   foundations; `<HostProject>` is the target for C1–C3 below and holds the API endpoints.
 3. **Present the implementation catalog (below) as a selection list and ASK the user which
    implementation(s) to integrate.** Use a multi-select prompt (`AskUserQuestion`,
    `multiSelect: true`) for consistency with the other components.
@@ -21,7 +25,10 @@
 5. **For each selected implementation, apply its block** (§Implementation blocks).
 6. **Set the provider:** `configureOptions: options => options.Provider = "<selected key>"`.
 7. **(Optional) Build the feature slice** (§Usage) — DTO + Command + Handler + Endpoint.
-8. **Verify** (§Verification) and report what was added.
+8. **Offer the bundled sample endpoint (ASK).** After the wiring above, ask the user (single-select
+   yes/no via `AskUserQuestion`) whether to add the ready-made sample endpoint. If **yes**, copy it
+   into the host project — see §Sample reference endpoint. If **no**, skip silently.
+9. **Verify** (§Verification) and report what was added.
 
 > **Guardrail — namespace casing.** Package IDs use `QrGenerator` (lower `r`); **namespaces/types
 > use `QRGenerator` (upper `R`)**. `using AppWeaver.QRGenerator;` is correct — getting this wrong is
@@ -53,8 +60,8 @@
 
 ### C2 — Project references (no `Version=`)
 
-**File:** `src/<SampleProjectName>.Application/<SampleProjectName>.Application.csproj`
-**File:** `src/<SampleProjectName>.Infrastructure/<SampleProjectName>.Infrastructure.csproj`
+**File:** `src/<HostProject>/<HostProject>.csproj` (the host project resolved in step 2 — single
+project, no separate Application/Infrastructure).
 
 ```xml
 <ItemGroup>
@@ -65,7 +72,10 @@
 
 ### C3 — Registration scaffold
 
-**File:** `src/<SampleProjectName>.Infrastructure/Extensions/InfrastructureServiceRegistration.cs`
+**File:** the host project `<HostProject>` (step 2) — register in its
+`Extensions/InfrastructureServiceRegistration.cs` (`AddInfrastructure`) when that file exists (it does
+in the Vertical Slice / Modular Monolith foundations), otherwise directly in `Program.cs` **before**
+`builder.Build()`.
 
 ```csharp
 using AppWeaver.QRGenerator.Extensions;   // AddQRGenerator  (capital R)
@@ -78,6 +88,12 @@ services.AddQRGenerator(
     configureOptions: options => options.Provider = "<selected key>");   // step 6
 ```
 
+> **Dual local/Aspire startup ([[components-readme]] R0.2a).** If the host project also has an
+> `AddAspireInfrastructure` method (`Extensions/AspireInfrastructureExtensions.cs`) selected by
+> `if (isAspire) … else …` in `Program.cs`, add this **same** `AddQRGenerator(...)` block to **both**
+> `AddInfrastructure` and `AddAspireInfrastructure` (it is DB-agnostic — identical in both), or
+> `IQRGenerator` is unresolvable when the app runs under Aspire.
+
 No `appsettings.json` entry is required — there is nothing to configure.
 
 ---
@@ -169,6 +185,32 @@ public class GenerateQrRequest { public string Content { get; set; } = string.Em
 
 ---
 
+## Sample reference endpoint
+
+The §Usage slice above routes through a command + handler. For a quick, self-contained sample there
+is also a ready-to-run FastEndpoint bundled in this component folder at
+[`ReferenceEndpoints/GenerateQrEndpoint.cs`](./ReferenceEndpoints/GenerateQrEndpoint.cs). It injects
+`IQRGenerator` directly and does the **full sequence inline** — no command/handler/mediator. It is
+**not** wired automatically; it is offered in workflow step 8.
+
+**When the user opts in (step 8) — copy procedure:**
+
+1. Confirm `docs/components/QrGenerator/ReferenceEndpoints/GenerateQrEndpoint.cs` exists. If it is
+   missing, tell the user and skip (do not hand-write a replacement).
+2. Create `src/<HostProject>/ReferenceEndpoints/` if it does not exist (`<HostProject>` = the project
+   resolved in step 2).
+3. Copy the file to `src/<HostProject>/ReferenceEndpoints/GenerateQrEndpoint.cs`, replacing the
+   namespace token `__HOSTPROJECT__` with `<HostProject>`'s root namespace (e.g.
+   `AppWeaver.Health.Service`). Keep the `using AppWeaver.QRGenerator;` (capital R) — do not "fix" it
+   to match the package id. Change nothing else.
+4. Do **not** touch the C1–C3 wiring. FastEndpoints auto-discovers the endpoint by assembly scan, so
+   no extra registration is required.
+
+**Endpoint:** `POST /reference/qr-codes` — body `{ "content" }` — returns an `image/png` body.
+An empty `content` string is valid (returns a small PNG); `null` is rejected with 400.
+
+---
+
 ## Verification
 
 1. **Builds** — `dotnet build` succeeds; `using` directives use `AppWeaver.QRGenerator…`; no
@@ -178,6 +220,9 @@ public class GenerateQrRequest { public string Content { get; set; } = string.Em
 4. **Generates** — `GenerateQR("test")` returns a non-empty `byte[]`; `POST /qr-codes` returns an
    `image/png` body that opens as a scannable QR image. (`null` content throws; empty string is
    valid and returns a PNG.)
+5. **Sample endpoint (only if copied in step 8)** — the build still succeeds with
+   `ReferenceEndpoints/GenerateQrEndpoint.cs` added, the `__HOSTPROJECT__` token was replaced, and
+   `POST /reference/qr-codes` returns an `image/png`.
 
 ## Related
 

package/assets/docs/components/README.md

@@ -42,8 +42,25 @@ Every folder contains two independent, agent-readable files:
 
 - **R0.1** — NuGet versions live in `Directory.Packages.props` only (`<PackageVersion>`); project
   files reference the package **without** a `Version=` attribute (see [[dependency-policy]]).
-- **R0.2** — Register the component in the **Infrastructure** registration extension, never in a
-  feature slice or domain code (see [[clean-architecture]]).
+- **R0.2** — Register the component in the **startup/host project** — the one project that owns
+  `Program.cs` + the ASP.NET Core web SDK. Its name is template-dependent: `<App>.Service` (Vertical
+  Slice foundation), `<App>.API` (Modular Monolith foundation), and possibly other names as templates
+  are added — so **resolve it by locating `Program.cs`, never by assuming a fixed project name**.
+  These foundations have **no** separate `…Application` / `…Infrastructure` project. Put the
+  `AddXxx(...)` registration in that project's `Extensions/InfrastructureServiceRegistration.cs`
+  (`AddInfrastructure`) when that extension exists, otherwise directly in `Program.cs` before
+  `builder.Build()`. Never register in a feature slice or domain code (see [[clean-architecture]]).
+- **R0.2a** — *(dual local/Aspire startup)* Some foundations split infrastructure registration across
+  **two** methods that `Program.cs` selects at runtime — `if (isAspire) AddAspireInfrastructure(...)`
+  (the Aspire path: `Extensions/AspireInfrastructureExtensions.cs`, typically PostgreSQL + Redis)
+  `else AddInfrastructure(...)` (the local/dev path:
+  `Extensions/InfrastructureServiceRegistration.cs`, typically SQLite + in-memory cache). When
+  **both** methods exist, add the component registration to **both**, or the abstraction is
+  unresolvable in whichever run mode you skipped (e.g. `IEmailService` throws at runtime under
+  Aspire). The registration block is **identical** in both — copy it verbatim — *except*
+  provider-specific calls (connection strings, `UseSqlite(...)` vs `UseNpgsql(...)`, cache provider),
+  which must match each method's existing provider. If only `AddInfrastructure` (or only `Program.cs`)
+  exists, register once as in R0.2.
 - **R0.3** — Inject the **abstraction** (`IEmailService`, `IQRGenerator`, `IJobScheduler`) into
   handlers — never the concrete provider type (see [[cqrs]]).
 - **R0.4** — Always set `options.Provider = "<Key>"` explicitly. Do not rely on the implicit

package/assets/docs/domainspecs/UIVisualization/chart-bubble.md

@@ -0,0 +1,70 @@
+# BubbleChart — Chart Rule
+
+> Load **only when "Bubble" (or "all plots") is in the selection** (see [[domain-requirements]]).
+> Component: `BubbleChart` in `components/charts/generic/BubbleChart.tsx`. Built on [[charting-standards.domain]].
+
+## Purpose
+Multi-dimensional scatter — each point encodes **x, y, size, colour, label** (up to 5 dimensions).
+Use for potency vs MW, portfolio risk/return, effort vs impact, market mapping.
+
+## Props contract
+```ts
+interface BubblePoint { x: number; y: number; size: number; label: string; meta?: Record<string, string|number> }
+interface BubbleSeries { seriesLabel: string; color?: string; points: BubblePoint[] }
+
+interface BubbleChartProps {
+  series: BubbleSeries[]        // REQUIRED — one series per colour/category
+  xLabel: string               // REQUIRED
+  yLabel: string               // REQUIRED
+  sizeLabel?: string           // shown as "Bubble size ∝ …" annotation
+  title?: string
+  xAxisType?: 'linear' | 'log'
+  yAxisType?: 'linear' | 'log'
+  sizeRange?: [number, number] // [minPx, maxPx] bubble diameter (default [8,40])
+  xRefLine?: number; xRefLabel?: string   // optional vertical reference line
+  yRefLine?: number; yRefLabel?: string   // optional horizontal reference line
+  height?: number
+  showLabels?: boolean         // annotate points with their label
+}
+```
+
+## Rules
+- Bubble sizes are **normalised across the whole dataset** to `sizeRange` — pass raw magnitudes;
+  the chart scales them. Don't pre-scale to pixels.
+- Group points into **series by the categorical dimension** (target, region, product line) so
+  colour + legend come for free.
+- Use `xAxisType="log"` / `yAxisType="log"` or pre-`log10` the value (e.g. IC₅₀) — pick one,
+  document it in the axis label.
+
+## Adapter example (agent reference)
+```tsx
+'use client'
+import { BubbleChart } from '@/components/charts/generic'
+import type { Compound } from '@/lib/types/pharma'
+
+export function compoundsToBubbleSeries(compounds: Compound[]) {
+  const targets = [...new Set(compounds.map(c => c.target))]
+  return targets.map(t => ({
+    seriesLabel: t,
+    points: compounds.filter(c => c.target === t).map(c => ({
+      x: c.molecularWeight, y: Math.log10(c.ic50_nM),
+      size: c.selectivityRatio, label: c.name,
+      meta: { Status: c.status, 'IC₅₀': `${c.ic50_nM} nM` },
+    })),
+  }))
+}
+
+export default function CompoundScatterPlot({ compounds, height }: { compounds: Compound[]; height?: number }) {
+  return (
+    <BubbleChart series={compoundsToBubbleSeries(compounds)}
+      xLabel="Molecular Weight (Da)" yLabel="log₁₀(IC₅₀, nM)" sizeLabel="Selectivity Ratio"
+      xRefLine={500} xRefLabel="Ro5 MW limit" sizeRange={[7, 28]} height={height} />
+  )
+}
+```
+
+## Scaffolds when selected
+- generic `BubbleChart` + `app/bubble/page.tsx` + nav tab + optional adapter.
+
+## Related
+- [[charting-standards.domain]] · [[component-contracts.domain]] · [[clean-architecture.domain]]

package/assets/docs/domainspecs/UIVisualization/chart-dimred.md

@@ -0,0 +1,58 @@
+# DimRedPlot — Chart Rule
+
+> Load **only when "Dim. Reduction / PCA / t-SNE / UMAP" (or "all plots") is selected** (see [[domain-requirements]]).
+> Component: `DimRedPlot` in `components/charts/generic/DimRedPlot.tsx`. Built on [[charting-standards.domain]].
+
+## Purpose
+2-D scatter of **pre-computed** dimensionality-reduction coordinates, coloured by group, with
+optional cluster-centroid labels and density contours. Use for single-cell clustering, customer
+segments, NLP embeddings, chemical-space maps, anomaly scatter.
+
+## Props contract
+```ts
+interface DimRedPoint {
+  x: number; y: number         // reduced coordinates (caller ran PCA/t-SNE/UMAP)
+  label: string
+  group: string                // category → colour + legend entry
+  meta?: Record<string, string|number>
+}
+interface DimRedPlotProps {
+  points: DimRedPoint[]        // REQUIRED
+  method?: string              // badge: "PCA", "t-SNE", "UMAP" (default "DR")
+  xLabel?: string; yLabel?: string   // e.g. "PC1 (34.2% var)", "UMAP 1"
+  colorByLabel?: string        // legend header / tooltip ("Cell type", "Segment")
+  showClusterLabels?: boolean  // centroid label per group (default true)
+  showDensityContours?: boolean // KDE contour per group (default false)
+  markerSize?: number          // default 5
+  title?: string; height?: number
+}
+```
+
+## Rules
+- The chart **does not run** PCA/t-SNE/UMAP — coordinates are computed upstream (Python,
+  backend, or a JS lib) and passed in. Document the method in `method` + axis labels.
+- `group` drives colour and the legend; keep group count modest (≤ ~12) for distinct colours.
+- Turn on `showDensityContours` for large, overlapping point clouds; off for small datasets.
+
+## Page/adapter example (agent reference)
+```tsx
+'use client'
+import { DimRedPlot } from '@/components/charts/generic'
+
+// cells already have umap1/umap2 + cellType from the pipeline
+export default function CellUmap({ cells }: { cells: { id: string; umap1: number; umap2: number; cellType: string }[] }) {
+  return (
+    <DimRedPlot
+      points={cells.map(c => ({ x: c.umap1, y: c.umap2, label: c.id, group: c.cellType }))}
+      method="UMAP" xLabel="UMAP 1" yLabel="UMAP 2" colorByLabel="Cell type" showClusterLabels
+    />
+  )
+}
+```
+
+## Scaffolds when selected
+- generic `DimRedPlot` + `app/dimred/page.tsx` + nav tab + optional adapter (+ a place to compute
+  or fetch coordinates).
+
+## Related
+- [[charting-standards.domain]] · [[component-contracts.domain]] · [[clean-architecture.domain]]

package/assets/docs/domainspecs/UIVisualization/chart-heatmap.md

@@ -0,0 +1,62 @@
+# Heatmap — Chart Rule
+
+> Load **only when "Heatmap" (or "all plots") is in the selection** (see [[domain-requirements]]).
+> Component: `Heatmap` in `components/charts/generic/Heatmap.tsx`. Built on [[charting-standards.domain]].
+
+## Purpose
+Colour-encoded grid for a 2-D value matrix. Use for correlation matrices, expression grids
+(log₂FC), confusion matrices, risk tables, cross-asset return grids.
+
+## Props contract
+```ts
+type ColourPreset = 'diverging-purple-red' | 'sequential-teal' | 'sequential-heat' | 'diverging-blue-red'
+
+interface HeatmapProps {
+  matrix: number[][]            // matrix[row][col] — REQUIRED
+  rowLabels: string[]           // y-axis — REQUIRED
+  colLabels: string[]           // x-axis — REQUIRED
+  title?: string
+  unit?: string                 // colour-bar title + tooltip unit (e.g. "log₂FC", "r")
+  colorscale?: ColourPreset | [number, string][]   // default 'diverging-purple-red'
+  zMid?: number                 // centre of a diverging scale (use 0 for FC / correlation)
+  zMin?: number; zMax?: number  // override colour range (defaults to matrix min/max)
+  showCellValues?: boolean      // annotate each cell (default true)
+  cellValuePrecision?: number   // decimals in annotations (default 2)
+  cellValueContrastThreshold?: number  // |value| above → white text (default 1.0)
+  height?: number               // omit for responsive fill
+  reverseRows?: boolean
+}
+```
+
+## Rules
+- `matrix.length === rowLabels.length`; every row length `=== colLabels.length`. Validate in the
+  adapter, not the chart.
+- For **diverging** data (fold-change, correlation) set `zMid={0}` so zero maps to the neutral
+  midpoint; for **sequential** data (counts, intensity) use a `sequential-*` preset and omit `zMid`.
+- Keep cell annotations on for ≤ ~12×12 grids; turn `showCellValues` off for dense matrices.
+
+## Adapter example (agent reference)
+```tsx
+'use client'
+import { Heatmap } from '@/components/charts/generic'
+import type { BiomarkerData } from '@/lib/types/pharma'
+
+export default function BiomarkerHeatmap({ data, height }: { data: BiomarkerData; height?: number }) {
+  return (
+    <Heatmap
+      matrix={data.matrix} rowLabels={data.treatments} colLabels={data.markers}
+      unit="log₂FC" colorscale="diverging-purple-red" zMid={0}
+      showCellValues cellValuePrecision={2} cellValueContrastThreshold={1.5}
+      height={height}
+    />
+  )
+}
+```
+
+## Scaffolds when selected
+- `components/charts/generic/Heatmap.tsx` (from the generic library — always present)
+- `app/heatmap/page.tsx` (example route) + nav tab
+- optional adapter `components/charts/<Domain>Heatmap.tsx`
+
+## Related
+- [[charting-standards.domain]] · [[component-contracts.domain]] · [[clean-architecture.domain]]

package/assets/docs/domainspecs/UIVisualization/chart-network.md

@@ -0,0 +1,69 @@
+# NetworkGraph — Chart Rule
+
+> Load **only when "Network / graph / node-edge" (or "all plots") is selected** (see [[domain-requirements]]).
+> Component: `NetworkGraph` in `components/charts/generic/NetworkGraph.tsx`. Built on [[charting-standards.domain]].
+
+## Purpose
+Force-directed **node-edge** graph rendered with Plotly scatter+line traces; layout is computed
+in-component (Fruchterman-Reingold spring or circular) so **no extra graph library** is needed.
+Use for PPI/pathway networks, microservice/dependency maps, knowledge graphs, org/social graphs.
+
+## Props contract
+```ts
+interface NetworkNode {
+  id: string                   // referenced by edges
+  label: string
+  group?: string               // colour + legend
+  size?: number                // marker size (importance, default 10)
+  meta?: Record<string, string|number>
+}
+interface NetworkEdge {
+  source: string; target: string   // node ids
+  weight?: number              // line thickness (default 1)
+  label?: string               // hover label
+}
+interface NetworkGraphProps {
+  nodes: NetworkNode[]; edges: NetworkEdge[]   // REQUIRED
+  layout?: 'spring' | 'circular'   // default 'spring'
+  springIterations?: number    // default 120 (higher = better layout, slower)
+  showEdgeLabels?: boolean      // default true
+  directed?: boolean            // arrowheads (default false)
+  title?: string; height?: number
+}
+```
+
+## Rules
+- Every edge `source`/`target` MUST reference an existing node `id`. Validate in the adapter;
+  dangling edges are dropped silently.
+- Layout is **deterministic per dataset** (warm-started from a circle) but recomputes when the
+  node/edge set changes — memoise `nodes`/`edges` so it doesn't recompute each render.
+- Keep graphs modest (≲ ~150 nodes) for readable spring layout; above that, pre-cluster or paginate.
+- Set `directed` for DAGs / signalling cascades; leave off for undirected association graphs.
+
+## Page/adapter example (agent reference)
+```tsx
+'use client'
+import { NetworkGraph } from '@/components/charts/generic'
+import type { NetworkNode, NetworkEdge } from '@/components/charts/generic'
+
+const NODES: NetworkNode[] = [
+  { id: 'EGFR', label: 'EGFR', group: 'Receptor', size: 26 },
+  { id: 'RAS',  label: 'RAS',  group: 'GTPase',   size: 22 },
+  { id: 'RAF',  label: 'BRAF', group: 'Kinase',   size: 20 },
+]
+const EDGES: NetworkEdge[] = [
+  { source: 'EGFR', target: 'RAS', weight: 2.5, label: 'activates' },
+  { source: 'RAS',  target: 'RAF', weight: 2,   label: 'activates' },
+]
+
+export default function PathwayNetwork() {
+  return <NetworkGraph nodes={NODES} edges={EDGES} layout="spring" springIterations={150} directed showEdgeLabels />
+}
+```
+
+## Scaffolds when selected
+- generic `NetworkGraph` + `app/network/page.tsx` + nav tab + optional adapter; type the node/edge
+  arrays with `NetworkNode[]` / `NetworkEdge[]` to avoid `meta` literal-type errors.
+
+## Related
+- [[charting-standards.domain]] · [[component-contracts.domain]] · [[clean-architecture.domain]]

package/assets/docs/domainspecs/UIVisualization/chart-parallel.md

@@ -0,0 +1,75 @@
+# ParallelCoordinatesPlot — Chart Rule
+
+> Load **only when "Parallel Coords / parcoords" (or "all plots") is selected** (see [[domain-requirements]]).
+> Component: `ParallelCoordinatesPlot` in `components/charts/generic/ParallelCoordinatesPlot.tsx`.
+> Built on [[charting-standards.domain]]; uses Plotly's native `parcoords` (interactive axis brushing).
+
+## Purpose
+Multi-dimensional data as **polylines crossing parallel vertical axes** — one line per observation.
+Use for multi-parameter optimisation (MPO), ADMET profiles, hyperparameter sweeps, KPI dashboards,
+portfolio metrics.
+
+## Props contract
+```ts
+interface PCDimension {
+  key: string                  // matches a key in each trace's `values`
+  label: string
+  range?: [number, number]     // axis range (auto if omitted)
+  tickFormat?: string          // d3 format, e.g. ".2f", ".0f"
+  invertAxis?: boolean         // for "lower is better" metrics (IC₅₀, p-value)
+}
+interface PCTrace {
+  id: string; label: string
+  colorValue: number           // drives the line colour (continuous)
+  values: Record<string, number>   // one value per dimension key
+  group?: string
+}
+type PCColorscale = 'teal-purple' | 'blue-red' | 'viridis' | 'plasma' | [number, string][]
+
+interface ParallelCoordinatesPlotProps {
+  dimensions: PCDimension[]    // REQUIRED — the axes
+  traces: PCTrace[]            // REQUIRED — one per observation
+  colorLabel?: string          // colour-bar title
+  colorscale?: PCColorscale    // default 'teal-purple'
+  lineOpacity?: number; lineWidth?: number
+  title?: string; height?: number
+}
+```
+
+## Rules
+- `dimensions[].key` must exist in **every** trace's `values`. Validate in the adapter.
+- Use `invertAxis` for metrics where **lower is better** so "good" lines trend the same way.
+- `colorValue` is a single continuous dimension (often the headline metric, e.g. IC₅₀ or score);
+  it maps onto `colorscale`. Brushing on any axis filters interactively — no extra wiring.
+
+## Page/adapter example (agent reference)
+```tsx
+'use client'
+import { ParallelCoordinatesPlot } from '@/components/charts/generic'
+import type { Compound } from '@/lib/types/pharma'
+
+const DIMS = [
+  { key: 'mw',   label: 'MW (Da)',   range: [300, 560] as [number, number], tickFormat: '.0f' },
+  { key: 'logP', label: 'LogP',      range: [1.5, 5.5] as [number, number], tickFormat: '.1f' },
+  { key: 'ic50', label: 'IC₅₀ (nM)', range: [0, 800]   as [number, number], tickFormat: '.0f', invertAxis: true },
+]
+
+export default function MpoParallel({ compounds }: { compounds: Compound[] }) {
+  return (
+    <ParallelCoordinatesPlot
+      dimensions={DIMS}
+      traces={compounds.filter(c => c.ic50_nM <= 800).map(c => ({
+        id: c.id, label: c.name, group: c.status, colorValue: c.ic50_nM,
+        values: { mw: c.molecularWeight, logP: c.logP, ic50: c.ic50_nM },
+      }))}
+      colorLabel="IC₅₀ (nM)" colorscale="teal-purple"
+    />
+  )
+}
+```
+
+## Scaffolds when selected
+- generic `ParallelCoordinatesPlot` + `app/parallel/page.tsx` + nav tab + optional adapter.
+
+## Related
+- [[charting-standards.domain]] · [[component-contracts.domain]] · [[clean-architecture.domain]]

package/assets/docs/domainspecs/UIVisualization/chart-scurve.md

@@ -0,0 +1,66 @@
+# SCurveChart — Chart Rule
+
+> Load **only when "S-Curve / dose-response / sigmoid" (or "all plots") is selected** (see [[domain-requirements]]).
+> Component: `SCurveChart` in `components/charts/generic/SCurveChart.tsx`. Built on [[charting-standards.domain]].
+
+## Purpose
+One or more **sigmoidal (S-shaped)** curves with optional inflection markers. Use for
+dose-response (4-PL / Hill), technology adoption, market penetration, enzyme kinetics, SaaS ramp.
+
+## Props contract
+```ts
+interface SCurvePoint { x: number; y: number }
+interface SCurve {
+  id: string; label: string; color?: string
+  points: SCurvePoint[]        // PRE-COMPUTED by the caller (model runs outside the chart)
+  inflectionX?: number         // e.g. IC₅₀ / midpoint — draws a marker + dashed line
+  inflectionLabel?: string     // "IC₅₀", "EC₅₀", "Midpoint", "Tipping point"
+  metadata?: Record<string, string>  // tooltip enrichment
+}
+interface SCurveChartProps {
+  curves: SCurve[]             // REQUIRED
+  xLabel: string; yLabel: string   // REQUIRED
+  xAxisType?: 'linear' | 'log'
+  referenceY?: number          // horizontal reference (default 50)
+  referenceYLabel?: string
+  yRange?: [number, number]    // default [-5, 108]
+  title?: string; height?: number
+}
+```
+
+## Rules
+- The chart **plots points, it does not fit models** — the caller generates curve points (4-PL,
+  logistic, etc.) and passes them. Provide generators in `lib/utils.ts`
+  (`generate4PLCurve`, `generateLogisticPoints`).
+- `inflectionX` is in the **same x-units** as the points (e.g. `log10(ic50_nM)` if x is log-conc).
+- Use `referenceY={50}` for "50% response/adoption"; set to `undefined` to hide.
+
+## Adapter example (agent reference)
+```tsx
+'use client'
+import { SCurveChart } from '@/components/charts/generic'
+import { PHARMA_COLORS } from '@/components/charts/PlotlyChart'
+import type { DoseResponseCurve } from '@/lib/types/pharma'
+
+export default function DoseResponseChart({ curves, height }: { curves: DoseResponseCurve[]; height?: number }) {
+  return (
+    <SCurveChart
+      curves={curves.map((c, i) => ({
+        id: c.compoundId, label: c.compoundName, color: PHARMA_COLORS[i % PHARMA_COLORS.length],
+        points: c.points.map(p => ({ x: p.logConc, y: p.response })),
+        inflectionX: Math.log10(c.ic50_nM), inflectionLabel: 'IC₅₀',
+        metadata: { Target: c.target, 'Hill slope': c.hillSlope.toFixed(2) },
+      }))}
+      xLabel="log₁₀[Concentration (nM)]" yLabel="% Inhibition"
+      referenceY={50} referenceYLabel="50% Inhibition" height={height}
+    />
+  )
+}
+```
+
+## Scaffolds when selected
+- generic `SCurveChart` + curve generators in `lib/utils.ts` + `app/scurve/` (or `dose-response/`)
+  route + nav tab + optional adapter.
+
+## Related
+- [[charting-standards.domain]] · [[component-contracts.domain]] · [[clean-architecture.domain]]

package/assets/docs/domainspecs/UIVisualization/chart-survival.md

@@ -0,0 +1,69 @@
+# SurvivalCurveChart — Chart Rule
+
+> Load **only when "Survival / Kaplan-Meier / retention" (or "all plots") is selected** (see [[domain-requirements]]).
+> Component: `SurvivalCurveChart` in `components/charts/generic/SurvivalCurveChart.tsx`. Built on [[charting-standards.domain]].
+
+## Purpose
+Kaplan-Meier–style **step-function** curves with optional CI shading, median markers, and a
+significance annotation. Use for clinical OS/PFS, user-cohort retention, component MTTF, churn.
+
+## Props contract
+```ts
+interface SurvivalPoint {
+  time: number
+  survival: number             // 0–1 (×100 applied) or 0–100
+  ciLower?: number; ciUpper?: number   // same scale as survival
+  nAtRisk?: number
+}
+interface SurvivalArm {
+  label: string; color: string        // colour REQUIRED — distinguishes arms
+  points: SurvivalPoint[]
+  medianTime?: number | null          // null = not reached
+}
+interface SurvivalCurveChartProps {
+  arms: SurvivalArm[]          // REQUIRED
+  timeLabel?: string           // default "Time"
+  survivalLabel?: string       // default "Survival Probability (%)"
+  eventLabel?: string          // "Death", "Churn", "Failure" …
+  medianLabel?: string         // "mOS", "mPFS", "Median retention"
+  curveType?: string           // corner badge: "OS", "KM", "Retention"
+  pValue?: string              // "< 0.001", "n.s."
+  showCI?: boolean             // default true (needs ciLower/ciUpper)
+  xMax?: number; height?: number
+}
+```
+
+## Rules
+- Curve is a **step function** (`shape: 'hv'`) — survival is constant between events. Pass points
+  at event/censor times; the chart draws the steps.
+- `survival` accepts either 0–1 or 0–100 — the chart normalises; be consistent within an arm.
+- CI shading requires `ciLower`/`ciUpper` on the points and `showCI` (default on).
+- `medianTime: null` renders "Not reached" — use it, don't fake a value.
+
+## Adapter example (agent reference)
+```tsx
+'use client'
+import { SurvivalCurveChart } from '@/components/charts/generic'
+import type { TrialArm } from '@/lib/types/pharma'
+
+export default function KaplanMeierChart({ arms, height }: { arms: TrialArm[]; height?: number }) {
+  return (
+    <SurvivalCurveChart
+      arms={arms.map(a => ({
+        label: a.name, color: a.color, medianTime: a.medianSurvival,
+        points: a.points.map(p => ({ time: p.time, survival: p.survival,
+          ciLower: p.ciLower, ciUpper: p.ciUpper, nAtRisk: p.nAtRisk })),
+      }))}
+      timeLabel="Days" survivalLabel="Survival Probability (%)" medianLabel="mOS"
+      curveType="OS" pValue="< 0.001" showCI height={height}
+    />
+  )
+}
+```
+
+## Scaffolds when selected
+- generic `SurvivalCurveChart` + `app/survival/` (or `trials/`) route + nav tab + optional adapter;
+  an optional number-at-risk table consumes `nAtRisk`.
+
+## Related
+- [[charting-standards.domain]] · [[component-contracts.domain]] · [[clean-architecture.domain]]