aw-spec-cli 0.1.3 → 0.1.4

package/assets/docs/UI.Visualization/unpack-reference-foundation.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+#
+# unpack-reference-foundation.sh — bash/macOS port of unpack-reference-foundation.ps1
+#
+# SYNOPSIS
+#   Unpack an AW-Spec reference pack file into a target project, renaming the
+#   sentinel app name to the caller's app name.
+#
+# DESCRIPTION
+#   Reads --pack-file (produced by pack-reference-foundation.sh/.ps1), takes the sentinel
+#   from its header (override with --sentinel), derives four case forms of the target app
+#   name, and writes every file block to --out-dir with the sentinel rewritten in both file
+#   CONTENTS and file/dir PATHS. Text blocks are rewritten and written as UTF-8; base64
+#   blocks are decoded as-is. Refuses to overwrite existing files unless --force.
+#
+# EXAMPLE
+#   ./unpack-reference-foundation.sh \
+#       --pack-file ./UI.Visualization.Reference.pack.txt \
+#       --target-app-name MyApp \
+#       --out-dir ../../
+#
+set -euo pipefail
+
+# ------------------------------------------------------------------ defaults ---
+PACK_FILE=''
+TARGET_APP_NAME=''
+OUT_DIR='.'
+SENTINEL=''
+FORCE=0
+DRYRUN=0
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: unpack-reference-foundation.sh --pack-file <file> --target-app-name <name>
+                                      [--out-dir <dir>] [--sentinel <name>]
+                                      [--force] [--dry-run]
+
+  -p, --pack-file <file>        Reference pack file to unpack               (required)
+  -t, --target-app-name <name>  New app name to rename the sentinel into    (required)
+  -o, --out-dir <dir>           Output root                   (default: .)
+      --sentinel <name>         Override the sentinel from the pack header
+      --force                   Overwrite files that already exist
+      --dry-run                 List what would be written, write nothing
+  -h, --help                    Show this help
+
+Positional fallback: unpack-reference-foundation.sh <pack-file> <target-app-name> [out-dir]
+EOF
+}
+
+# -------------------------------------------------------------- arg parsing ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -p|--pack-file)        PACK_FILE="${2:?--pack-file needs a value}";             shift 2 ;;
+    -t|--target-app-name)  TARGET_APP_NAME="${2:?--target-app-name needs a value}"; shift 2 ;;
+    -o|--out-dir)          OUT_DIR="${2:?--out-dir needs a value}";                 shift 2 ;;
+    --sentinel)            SENTINEL="${2:?--sentinel needs a value}";               shift 2 ;;
+    --force)               FORCE=1; shift ;;
+    --dry-run)             DRYRUN=1; shift ;;
+    -h|--help)             usage; exit 0 ;;
+    --)                    shift; break ;;
+    -*)                    echo "Error: unknown option: $1" >&2; usage; exit 2 ;;
+    *)
+      if   [ -z "$PACK_FILE" ];       then PACK_FILE="$1"
+      elif [ -z "$TARGET_APP_NAME" ]; then TARGET_APP_NAME="$1"
+      else OUT_DIR="$1"
+      fi
+      shift ;;
+  esac
+done
+
+[ -n "$PACK_FILE" ]       || { echo "Error: --pack-file is required." >&2; usage; exit 2; }
+[ -n "$TARGET_APP_NAME" ] || { echo "Error: --target-app-name is required." >&2; usage; exit 2; }
+[ -f "$PACK_FILE" ]       || { echo "Error: pack file not found: $PACK_FILE" >&2; exit 1; }
+
+case "$TARGET_APP_NAME" in
+  *[!A-Za-z0-9._-]*)
+    echo "Error: --target-app-name may contain only letters, digits, '.', '_' or '-': $TARGET_APP_NAME" >&2
+    exit 2 ;;
+esac
+
+# ------------------------------------------------ sentinel from header --------
+if [ -z "$SENTINEL" ]; then
+  SENTINEL="$(LC_ALL=C sed -n 's/^#[[:space:]]*sentinel:[[:space:]]*\(.*[^[:space:]]\)[[:space:]]*$/\1/p' "$PACK_FILE" | head -n1)"
+fi
+[ -n "$SENTINEL" ] || { echo "Error: Sentinel not found in pack header; supply it with --sentinel." >&2; exit 1; }
+
+# ------------------------------------------------ derive case forms -----------
+to_lower() { printf '%s' "$1" | LC_ALL=C tr '[:upper:]' '[:lower:]'; }
+
+S_DOT="$SENTINEL";               T_DOT="$TARGET_APP_NAME"
+S_UND="${SENTINEL//./_}";        T_UND="${TARGET_APP_NAME//./_}"
+s_low="$(to_lower "$SENTINEL")"; t_low="$(to_lower "$TARGET_APP_NAME")"
+S_HYP="${s_low//./-}";           T_HYP="${t_low//./-}"
+S_LDOT="$s_low";                 T_LDOT="$t_low"
+
+FROM=(); TO=()
+add_form() {
+  local from="$1" to="$2" e
+  [ -n "$from" ] || return 0
+  [ "$from" = "$to" ] && return 0
+  if [ "${#FROM[@]}" -gt 0 ]; then
+    for e in "${FROM[@]}"; do [ "$e" = "$from" ] && return 0; done
+  fi
+  FROM+=("$from"); TO+=("$to")
+}
+add_form "$S_DOT"  "$T_DOT"
+add_form "$S_UND"  "$T_UND"
+add_form "$S_HYP"  "$T_HYP"
+add_form "$S_LDOT" "$T_LDOT"
+
+# Sort indices by FROM length descending
+ORDER=()
+{
+  local_n="${#FROM[@]}"
+  used=(); for ((k = 0; k < local_n; k++)); do used[$k]=0; done
+  for ((pass = 0; pass < local_n; pass++)); do
+    best=-1; bestlen=-1
+    for ((j = 0; j < local_n; j++)); do
+      if [ "${used[$j]}" -eq 0 ] && [ "${#FROM[$j]}" -gt "$bestlen" ]; then
+        bestlen="${#FROM[$j]}"; best="$j"
+      fi
+    done
+    used[$best]=1; ORDER+=("$best")
+  done
+}
+
+REPL_OUT=''
+apply_repl() {
+  local text="$1" idx from to
+  if [ "${#ORDER[@]}" -gt 0 ]; then
+    for idx in "${ORDER[@]}"; do
+      from="${FROM[$idx]}"; to="${TO[$idx]}"
+      text="${text//"$from"/$to}"
+    done
+  fi
+  REPL_OUT="$text"
+}
+
+# ------------------------------------------------ output root ----------------
+[ -d "$OUT_DIR" ] || mkdir -p "$OUT_DIR"
+OUT_ROOT="$(cd "$OUT_DIR" && pwd -P)"
+
+# ------------------------------------------------ base64 decoder (portable) --
+B64D=()
+if   printf 'aGk=' | base64 -d        >/dev/null 2>&1; then B64D=(base64 -d)
+elif printf 'aGk=' | base64 -D        >/dev/null 2>&1; then B64D=(base64 -D)
+elif printf 'aGk=' | base64 --decode  >/dev/null 2>&1; then B64D=(base64 --decode)
+else                                                        B64D=(openssl base64 -d -A)
+fi
+
+# ------------------------------------------------ parse file blocks ----------
+rels=(); encs=(); contents=()
+in_block=0; cur_rel=''; cur_enc=''; cur_content=''; first_line=1
+file_re='^<<<FILE path="([^"]+)"( encoding="([^"]+)")?>>>[[:space:]]*$'
+
+while IFS= read -r line || [ -n "$line" ]; do
+  line="${line%$'\r'}"
+  if [ "$in_block" -eq 0 ]; then
+    if [[ "$line" =~ $file_re ]]; then
+      cur_rel="${BASH_REMATCH[1]}"
+      cur_enc="${BASH_REMATCH[3]:-}"
+      in_block=1; first_line=1; cur_content=''
+    fi
+  else
+    if [ "$line" = '<<<ENDFILE>>>' ]; then
+      rels+=("$cur_rel"); encs+=("$cur_enc"); contents+=("$cur_content")
+      in_block=0
+    elif [ "$first_line" -eq 1 ]; then
+      cur_content="$line"; first_line=0
+    else
+      cur_content="$cur_content"$'\n'"$line"
+    fi
+  fi
+done < "$PACK_FILE"
+
+[ "${#rels[@]}" -gt 0 ] || { echo "Error: No <<<FILE>>> blocks found in pack: $PACK_FILE" >&2; exit 1; }
+
+# ------------------------------------------------ resolve destinations -------
+dests=()
+for ((i = 0; i < ${#rels[@]}; i++)); do
+  apply_repl "${rels[$i]}"
+  dests+=("$OUT_ROOT/$REPL_OUT")
+done
+
+# ------------------------------------------------ conflict guard -------------
+if [ "$FORCE" -eq 0 ] && [ "$DRYRUN" -eq 0 ]; then
+  conflicts=()
+  for d in "${dests[@]}"; do [ -e "$d" ] && conflicts+=("$d"); done
+  if [ "${#conflicts[@]}" -gt 0 ]; then
+    echo "Error: Refusing to overwrite existing files (re-run with --force):" >&2
+    printf '  %s\n' "${conflicts[@]}" >&2
+    exit 1
+  fi
+fi
+
+# ------------------------------------------------ write ----------------------
+written=0
+for ((i = 0; i < ${#rels[@]}; i++)); do
+  rel="${rels[$i]}"; enc="${encs[$i]}"; dest="${dests[$i]}"
+  if [ "$DRYRUN" -eq 1 ]; then
+    echo "WOULD WRITE  $rel  ->  $dest"
+    continue
+  fi
+  mkdir -p "$(dirname "$dest")"
+  if [ "$enc" = 'base64' ]; then
+    printf '%s' "${contents[$i]}" | tr -d '[:space:]' | "${B64D[@]}" > "$dest"
+  else
+    apply_repl "${contents[$i]}"
+    printf '%s' "$REPL_OUT" > "$dest"
+  fi
+  written=$((written + 1))
+done
+
+if [ "$DRYRUN" -eq 1 ]; then
+  echo "DryRun: ${#rels[@]} file(s) would be written to $OUT_ROOT (sentinel '$SENTINEL' -> '$TARGET_APP_NAME')."
+else
+  echo "Unpacked $written file(s) to $OUT_ROOT (sentinel '$SENTINEL' -> '$TARGET_APP_NAME')."
+fi

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]]