aw-spec-cli 0.1.3 → 0.1.4

package/assets/docs/domainspecs/UIVisualization/component-contracts.domain.md

@@ -0,0 +1,67 @@
+# Component Contracts (Adapters) — UI Visualization Domain
+
+> The props-driven contract and the adapter pattern. NON-NEGOTIABLE.
+> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Props-driven, domain-agnostic
+
+Every generic chart is **fully data-driven**: the caller supplies data, labels, colours, axis
+types, and thresholds. A generic chart has **no** knowledge of the domain — the same `BubbleChart`
+serves drug potency, portfolio risk, and product effort/impact.
+
+Contract for a generic chart's props:
+- **Data first** — required positional-feel props (`matrix`, `series`, `curves`, `arms`,
+  `points`, `panels`, `nodes`/`edges`, `groups`, `dimensions`/`traces`).
+- **Labels explicit** — axis/legend/unit labels are required where the chart can't sensibly
+  default them; never hard-code a domain word.
+- **Colours optional** — default from the shared palette; accept overrides per series.
+- **`height?` optional** — omit for responsive fill (see [[charting-standards.domain]]).
+- **`meta`/`metadata`** — open `Record<string,…>` for tooltip enrichment, never typed to a domain.
+
+## The adapter pattern
+
+A **thin adapter** is the only place domain types meet a chart. It maps a project type into the
+generic chart's props and adds domain labels/colours. Adapters live in `components/charts/`
+(NOT in `generic/`).
+
+```tsx
+// Adapter: domain TrialArm[] → SurvivalCurveChart
+'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 (%)" medianLabel="mOS"
+      curveType="OS" pValue="< 0.001" showCI height={height}
+    />
+  )
+}
+```
+
+## When to skip the adapter
+
+If a page already holds data in a generic shape (or the project is itself generic), call the
+generic chart directly from the page with inline props — no adapter needed. Adapters exist to
+keep **domain vocabulary out of pages** and **out of the generic ring**.
+
+## Rules
+
+- One adapter per (domain-type → chart) pairing; name it for the domain concept
+  (`CompoundScatterPlot`, `BiomarkerHeatmap`), not the chart.
+- Adapters are **pure mapping** — no data fetching, no store mutation; they receive data as props.
+- Never widen a generic chart's props with a domain field — add the field to `meta`/`metadata`
+  instead, or map it to an existing generic prop.
+- Keep generic props **serialisable** (numbers, strings, arrays) so re-render diffing stays cheap
+  (see [[charting-standards.domain]]).
+
+## Related
+- [[charting-standards.domain]] — the base every chart builds on
+- [[clean-architecture.domain]] — adapter is the dependency seam
+- All `chart-*` files specify each chart's exact prop contract.

package/assets/docs/domainspecs/UIVisualization/data-source.domain.md

@@ -0,0 +1,68 @@
+# Data Source Abstraction — UI Visualization Domain
+
+> How chart data enters the app. NON-NEGOTIABLE.
+> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Three source modes, one contract
+
+The same dataset shape feeds the charts regardless of origin — the **repository/specification**
+analog for the front-end:
+
+| Mode | Phase | Origin | Wiring |
+|---|---|---|---|
+| `sample` | 1 | hard-coded `lib/sample-data` | default; renders on first paint |
+| `excel`  | 1 | client-side `.xlsx` upload (SheetJS) | `ExcelDropZone` → parser → `loadExcel` command |
+| `api`    | 2 | REST endpoint | `ApiDataSource` → `loadExcel`-shaped result |
+
+Charts never know the source — they consume the store dataset. Swapping `sample`→`excel`→`api`
+changes **no chart code** (see [[clean-architecture.domain]], [[state-management.domain]]).
+
+## Excel ingest
+
+- Parsing is **client-side only** (no server) via dynamic `import('xlsx')`.
+- A generic parser returns raw rows per sheet (`Record<string, ParsedWorkbook>`); a
+  **project parser** maps those rows into the domain dataset and dispatches `loadExcel`.
+- The drop-zone validates extension (`.xlsx/.xls`), shows parse state, and reports row counts.
+- Sheet/column names are a **documented contract** shipped with the template
+  (`public/sample-data.xlsx` is the canonical example).
+
+## Canonical example (agent reference)
+
+```ts
+// lib/excel/parse-excel.ts — generic: workbook → rows per sheet
+import type { ExcelRow } from '@/lib/types'
+export type ParsedWorkbook = Record<string, ExcelRow[]>
+
+export async function parseExcelFile(file: File): Promise<ParsedWorkbook> {
+  const XLSX = await import('xlsx')
+  const wb = XLSX.read(await file.arrayBuffer(), { type: 'array' })
+  return Object.fromEntries(
+    wb.SheetNames.map(n => [n, XLSX.utils.sheet_to_json<ExcelRow>(wb.Sheets[n], { defval: null })]),
+  )
+}
+```
+
+```tsx
+// ExcelDropZone wires parse → command
+const wb = await parseExcelFile(file)          // generic rows
+const dataset = mapWorkbookToDomain(wb)        // project mapping
+loadExcel(dataset)                             // store command (see [[state-management.domain]])
+```
+
+## Phase-2 API source (forward contract)
+
+- Add `lib/data-source/ApiDataSource.ts` that fetches and returns the **same dataset shape** the
+  Excel mapper produces, then calls `loadExcel` (or `setSourceMode('api', …)`).
+- Set `NEXT_PUBLIC_API_URL`; no chart or adapter changes.
+
+## Rules
+
+- No server-side Excel handling in Phase 1; keep ingest in the browser.
+- The dataset shape is the single contract between source and charts — version it deliberately.
+- Never parse domain meaning inside `components/charts/generic/` — mapping lives in the project
+  parser / adapter (see [[component-contracts.domain]]).
+
+## Related
+- [[state-management.domain]] — `loadExcel` command
+- [[component-contracts.domain]] — adapters consume the dataset
+- [[clean-architecture.domain]]

package/assets/docs/domainspecs/UIVisualization/domain-requirements.md

@@ -0,0 +1,110 @@
+# DOMAIN REQUIREMENTS (project-specific)
+
+> Project-specific input for the **UI Data-Visualization** domain, **updated independently per
+> project**. The engineering constitution stays domain-agnostic and supreme; this file holds the
+> per-project chart enumeration and the headline tech profile. Detailed charting *rules* are
+> expanded in the sibling files in this folder.
+>
+> This domain targets a **Next.js / React / Plotly** front-end (not the .NET backend). It composes
+> with the technology base where applicable and overrides the runtime/stack sections below.
+>
+> Replace `<SampleProjectName>` and trim the **Chart Selection** list to the charts the project
+> actually needs.
+
+=====================================================================
+[DOMAIN: Chart Catalog / Features]
+=====================================================================
+The visualization domain is organised as **one feature per chart type**. Each chart is a
+**domain-agnostic, props-driven component** in the generic library, optionally wrapped by a thin
+**adapter** that maps project data into its props (see [[clean-architecture.domain]],
+[[component-contracts.domain]]). The 10 built-in charts:
+
+- **Heatmap** — value matrix, colour-mapped by intensity. See [[chart-heatmap]].
+- **BubbleChart** — multi-dimensional scatter (x · y · size · colour). See [[chart-bubble]].
+- **SCurveChart** — sigmoidal / logistic growth with inflection markers. See [[chart-scurve]].
+- **SurvivalCurveChart** — Kaplan-Meier step curves with CI shading. See [[chart-survival]].
+- **VolcanoPlot** — magnitude vs. significance with threshold quadrants. See [[chart-volcano]].
+- **DimRedPlot** — 2-D scatter of PCA / t-SNE / UMAP coordinates. See [[chart-dimred]].
+- **ParallelCoordinatesPlot** — multi-axis polylines, one per observation. See [[chart-parallel]].
+- **ViolinPlot** — KDE distribution + box per group. See [[chart-violin]].
+- **NetworkGraph** — node-edge graph with built-in spring layout. See [[chart-network]].
+- **TrellisGrid** — small multiples, same chart type per panel. See [[chart-trellis]].
+
+=====================================================================
+[DOMAIN: Chart Selection — REQUIRED INPUT]
+=====================================================================
+> **The developer specifies which charts the project needs when giving the requirement.**
+
+- The requirement names a **subset** of the catalog (e.g. *"Heatmap, Volcano and Survival"*) or
+  says **"all plots"** to include every chart.
+- A skill reads the selection and loads **only** the matching `chart-*` rule files
+  (see [[comandrulemap]]). Unselected charts are **not** scaffolded — their page route, adapter,
+  nav entry, and example data are omitted.
+- Selection keywords are case-insensitive and accept either the **component name**
+  (`BubbleChart`) or the **friendly name** (`Bubble`, `bubble chart`). "all" / "all plots" /
+  "all charts" select the full catalog.
+- Default when unspecified: **ask the developer**; do not assume "all".
+
+| Selection token (any) | Rule file | Component |
+|---|---|---|
+| heatmap | [[chart-heatmap]] | `Heatmap` |
+| bubble · bubble chart | [[chart-bubble]] | `BubbleChart` |
+| s-curve · scurve · sigmoid · dose-response | [[chart-scurve]] | `SCurveChart` |
+| survival · kaplan-meier · km · retention | [[chart-survival]] | `SurvivalCurveChart` |
+| volcano | [[chart-volcano]] | `VolcanoPlot` |
+| dimred · pca · tsne · umap · dimensionality | [[chart-dimred]] | `DimRedPlot` |
+| parallel · parallel-coords · parcoords | [[chart-parallel]] | `ParallelCoordinatesPlot` |
+| violin · distribution | [[chart-violin]] | `ViolinPlot` |
+| network · graph · node-edge | [[chart-network]] | `NetworkGraph` |
+| trellis · facet · small-multiples | [[chart-trellis]] | `TrellisGrid` |
+
+=====================================================================
+[DOMAIN: subsection pointers]
+=====================================================================
+[DOMAIN: Folder Structure Profile]        -> docs/domainspecs/UIVisualization/folder-structure.domain.md
+[DOMAIN: Clean Architecture / Layering]   -> docs/domainspecs/UIVisualization/clean-architecture.domain.md
+[DOMAIN: State / Data Flow (CQRS analog)] -> docs/domainspecs/UIVisualization/state-management.domain.md
+[DOMAIN: Data Source Abstraction]         -> docs/domainspecs/UIVisualization/data-source.domain.md
+[DOMAIN: Charting Standards (base wrap)]  -> docs/domainspecs/UIVisualization/charting-standards.domain.md
+[DOMAIN: Component Contracts (adapters)]  -> docs/domainspecs/UIVisualization/component-contracts.domain.md
+[DOMAIN: Coding Standards Profile]        -> docs/domainspecs/UIVisualization/coding-standards.domain.md
+[DOMAIN: Testing Profile]                 -> docs/domainspecs/UIVisualization/testing.domain.md
+[DOMAIN: Ubiquitous Language]             -> docs/domainspecs/UIVisualization/ui-viz-terms.md
+[DOMAIN: Per-chart rules]                 -> docs/domainspecs/UIVisualization/chart-<name>.md (load per selection)
+
+=====================================================================
+[DOMAIN: Tech Profile (overrides technology stack section)]
+=====================================================================
+- **Framework:** Next.js 16 (App Router, Turbopack); React 19; TypeScript 5 strict.
+- **Charting:** Plotly.js (`plotly.js-dist-min`) loaded via a single SSR-safe base wrapper
+  (`PlotlyChart`) using dynamic import (see [[charting-standards.domain]]).
+- **State:** Zustand 5 (see [[state-management.domain]]).
+- **Data ingest:** SheetJS (`xlsx`) client-side; optional REST `ApiDataSource` for Phase 2
+  (see [[data-source.domain]]).
+- **Styling:** Tailwind CSS 3 + dark "glass" theme (see [[charting-standards.domain]]).
+- **Scaffold source:** `templates/AppWeaver.UI.Visualization` (generic) and
+  `templates/features/UIVisualization.PharmaReference` (reference); packed under
+  `docs/UI.Visualization/` (see PACKAGING.md there).
+
+=====================================================================
+[DOMAIN: Platform Topology]
+=====================================================================
+- Target runtime: static-export or Node SSR (Vercel, container, or any static host). No backend
+  required for Phase 1 — charts render from sample/Excel data fully client-side.
+- Phase 2 wires a REST API behind the `data-source` abstraction with **zero chart changes**
+  (see [[data-source.domain]]).
+- Performance targets: first chart interactive < 1.5 s on a warm cache; a single Plotly chart
+  re-render < 100 ms for typical (≤ 5k-point) datasets.
+
+=====================================================================
+[DOMAIN: Governance Overrides]
+=====================================================================
+- The **generic chart library is closed for domain logic** — additions/edits there require review
+  by a UI Principal Engineer (no project- or domain-specific code in `components/charts/generic/`).
+- New chart types beyond the 10-chart catalog require a constitution amendment + a new
+  `chart-<name>.md` rule file authored to the same contract.
+
+## Related
+- [[folder-structure.domain]] · [[clean-architecture.domain]] · [[state-management.domain]] ·
+  [[data-source.domain]] · [[charting-standards.domain]] · [[component-contracts.domain]] ·
+  [[coding-standards.domain]] · [[testing.domain]] · [[ui-viz-terms]] · [[comandrulemap]]

package/assets/docs/domainspecs/UIVisualization/folder-structure.domain.md

@@ -0,0 +1,55 @@
+# Folder Structure — UI Visualization Domain
+
+> Next.js App-Router layout for the visualization front-end. NON-NEGOTIABLE.
+> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`. Replace `<SampleProjectName>`.
+
+## Layout
+
+```
+<SampleProjectName>/                         (sentinel: AppWeaver.UI.Visualization)
+  package.json · tsconfig.json · next.config.ts · tailwind.config.ts
+  public/                                     static assets + sample-data.xlsx
+  scripts/                                    generate-sample-excel.mjs (optional)
+  src/
+    app/                                      App Router — one route folder per SELECTED chart
+      layout.tsx                              root layout: <TopNav/> + bg-mesh
+      globals.css                             theme tokens, glass/gradient classes, animations
+      page.tsx                                catalog/dashboard landing
+      <chart-route>/page.tsx                  e.g. heatmap/ bubble/ volcano/ … (only selected)
+    components/
+      charts/
+        PlotlyChart.tsx                       SSR-safe Plotly base wrapper  (see [[charting-standards.domain]])
+        generic/                              ← DOMAIN-AGNOSTIC chart library (closed to domain logic)
+          index.ts                            barrel export
+          Heatmap.tsx · BubbleChart.tsx · SCurveChart.tsx · SurvivalCurveChart.tsx
+          VolcanoPlot.tsx · DimRedPlot.tsx · ParallelCoordinatesPlot.tsx
+          ViolinPlot.tsx · NetworkGraph.tsx · TrellisGrid.tsx
+        <DomainAdapter>.tsx                   thin adapters (project-specific)  (see [[component-contracts.domain]])
+      layout/TopNav.tsx                       horizontal tab nav (one tab per selected chart)
+      excel-loader/ExcelDropZone.tsx          drag-drop ingest  (see [[data-source.domain]])
+      data-table/ · ui/                       optional supporting components
+    lib/
+      types/                                  shared + domain data types
+      utils.ts                                cn(), formatters, curve generators
+      excel/                                  workbook parser  (see [[data-source.domain]])
+    store/
+      data-store.ts                           Zustand store  (see [[state-management.domain]])
+```
+
+## Rules
+
+- The **generic chart library** lives only in `components/charts/generic/` and is
+  **domain-agnostic** — no project types, no business logic, no hard-coded labels
+  (see [[clean-architecture.domain]], [[component-contracts.domain]]).
+- **One route folder per selected chart** under `src/app/`; unselected charts have **no**
+  route, no nav tab, no example data (see [[domain-requirements]] chart-selection).
+- Domain **adapters** sit in `components/charts/` (NOT inside `generic/`) and map project data
+  to generic props.
+- Cross-cutting files (`PlotlyChart.tsx`, `globals.css`, `TopNav.tsx`, `data-store.ts`,
+  the base config files) MUST stay where the AppWeaver template places them.
+- `@/*` path alias maps to `./src/*` — import charts as
+  `@/components/charts/generic`.
+
+## Related
+- [[clean-architecture.domain]] · [[component-contracts.domain]] · [[charting-standards.domain]] ·
+  [[state-management.domain]] · [[data-source.domain]]

package/assets/docs/domainspecs/UIVisualization/state-management.domain.md

@@ -0,0 +1,67 @@
+# State Management (CQRS analog) — UI Visualization Domain
+
+> The front-end read/write separation. NON-NEGOTIABLE.
+> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Read / write separation
+
+CQRS maps to the client store as **queries = selectors** and **commands = actions**:
+
+- **Queries (reads)** — components read slices of the Zustand store via the hook
+  (`const { compounds } = useDataStore()`). Reads are pure; no side effects in render.
+- **Commands (writes)** — every mutation is a **named store action**, never a raw `set` from a
+  component. Actions: `loadExcel(partial)`, `resetToSample()`, `toggleCurve(id)`,
+  `setSourceMode(mode, fileName)`.
+
+A component MUST NOT mutate store state directly — it dispatches an action, exactly as a backend
+endpoint dispatches a command via the mediator instead of touching the `DbContext`.
+
+## Store shape
+
+- A single `useDataStore` (Zustand) holds: the active **dataset** (the project's chart data), the
+  **source mode** (`'sample' | 'excel' | 'api'`), and any **view state** (e.g. selected series ids).
+- The store seeds from **sample data** so charts render on first paint with zero backend
+  (see [[data-source.domain]]).
+- Loading new data is a single command that swaps the dataset and flips `sourceMode` — charts
+  re-render reactively with no per-chart wiring.
+
+## Canonical example (agent reference)
+
+```ts
+// store/data-store.ts
+'use client'
+import { create } from 'zustand'
+import { SAMPLE } from '@/lib/sample-data'
+
+type SourceMode = 'sample' | 'excel' | 'api'
+
+interface DataStore {
+  dataset: typeof SAMPLE
+  sourceMode: SourceMode
+  // commands (writes) — the ONLY way to mutate
+  loadExcel: (partial: Partial<typeof SAMPLE>) => void
+  resetToSample: () => void
+}
+
+export const useDataStore = create<DataStore>((set) => ({
+  dataset: SAMPLE,
+  sourceMode: 'sample',
+  loadExcel: (partial) =>
+    set(s => ({ dataset: { ...s.dataset, ...partial }, sourceMode: 'excel' })),
+  resetToSample: () => set({ dataset: SAMPLE, sourceMode: 'sample' }),
+}))
+```
+
+## Rules
+
+- One store module (`store/data-store.ts`). Split into slices only when it exceeds ~150 lines.
+- Actions are the command surface — name them as verbs; keep them pure-ish (compute → `set`).
+- Cross-component data load may also broadcast a `window` `CustomEvent`
+  (`appweaver:excel-loaded`) — the front-end analog of a **domain event**.
+- No data fetching inside the store for Phase 1; the **data-source** layer owns ingest and hands
+  the result to a command (see [[data-source.domain]]).
+
+## Related
+- [[data-source.domain]] — where datasets come from
+- [[clean-architecture.domain]] — the data layer feeds pages, never imports charts
+- [[component-contracts.domain]]

package/assets/docs/domainspecs/UIVisualization/testing.domain.md

@@ -0,0 +1,52 @@
+# Testing — UI Visualization Domain
+
+> Test profile for the viz front-end. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## What to test (priority order)
+
+1. **Adapters** (highest value) — pure mapping functions: domain type → generic props. Assert the
+   produced `series`/`arms`/`curves`/`matrix` and labels match the input. No DOM needed.
+2. **Data layer** — the Excel parser and any workbook→domain mapper: given a fixture workbook (or
+   row array), assert the parsed dataset (counts, fields, null handling, derived curves).
+3. **Store actions** — `loadExcel`, `resetToSample`, `toggleCurve` change state as specified
+   (see [[state-management.domain]]).
+4. **Smoke render** — each selected chart renders without throwing when given representative data
+   (mock `plotly.js-dist-min` so no real canvas is needed).
+
+## How
+
+- **Vitest** (or Jest) + **@testing-library/react** for component smoke tests.
+- **Mock Plotly**: `vi.mock('plotly.js-dist-min', () => ({ react: vi.fn(), purge: vi.fn() }))` —
+  assert the wrapper called `react` with the expected trace count, not pixels.
+- Adapters and parsers are plain functions — unit-test them directly, no mocks.
+- A `build` (type-check + `next build`) is the compile-time gate; keep it green.
+
+## Example (agent reference)
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { compoundsToBubbleSeries } from '@/components/charts/CompoundScatterPlot'
+
+it('groups compounds by target into series with log-scaled y', () => {
+  const series = compoundsToBubbleSeries([
+    { name: 'A', target: 'EGFR', molecularWeight: 393, ic50_nM: 10, selectivityRatio: 40 },
+  ])
+  expect(series).toHaveLength(1)
+  expect(series[0].seriesLabel).toBe('EGFR')
+  expect(series[0].points[0].y).toBeCloseTo(1) // log10(10)
+})
+```
+
+> Tip: export the mapping function from the adapter (e.g. `compoundsToBubbleSeries`) so it is
+> unit-testable without rendering.
+
+## Rules
+
+- Don't assert on Plotly's internal DOM — assert on the **inputs** you hand Plotly.
+- One fixture workbook per project lives beside the parser tests; mirror the shipped
+  `public/sample-data.xlsx` columns.
+- Only test charts that are **selected** for the project (see [[domain-requirements]]).
+
+## Related
+- [[component-contracts.domain]] · [[state-management.domain]] · [[data-source.domain]] ·
+  [[coding-standards.domain]]

package/assets/docs/domainspecs/UIVisualization/ui-viz-terms.md

@@ -0,0 +1,39 @@
+# Ubiquitous Language — UI Visualization Domain
+
+> Shared vocabulary for the visualization front-end. Commands: `/aw-spec-specify`, `/aw-spec-clarify`.
+
+## Core terms
+
+- **Generic chart** — a domain-agnostic, props-driven Plotly component in
+  `components/charts/generic/`. Knows nothing about any project domain. The 10 in the catalog.
+- **Adapter** — a thin component mapping a project/domain type into a generic chart's props; lives
+  in `components/charts/` (not `generic/`). The only place domain vocabulary meets a chart.
+- **Base wrapper** — `PlotlyChart`; the single SSR-safe Plotly mount every chart renders through.
+- **Data source** — origin of chart data: `sample` (hard-coded), `excel` (client upload), or
+  `api` (Phase-2 REST). The store's `sourceMode`.
+- **Dataset** — the project's chart-ready data held in the store; the contract between data source
+  and charts.
+- **Command (action)** — a named store mutation (`loadExcel`, `resetToSample`, `toggleCurve`).
+- **Query (selector)** — a read of store state from a component via `useDataStore`.
+- **Chart selection** — the developer-specified subset of the catalog to scaffold (or "all plots").
+- **Fill-height** — responsive sizing: a chart with no `height` fills its flex parent.
+- **Series / arm / curve / panel / trace** — per-chart data groupings (see each `chart-*` file).
+- **meta / metadata** — open key/value bag for tooltip enrichment; never a typed domain field.
+
+## Chart friendly-name ↔ component
+
+| Friendly name(s) | Component |
+|---|---|
+| Heatmap | `Heatmap` |
+| Bubble / Bubble chart | `BubbleChart` |
+| S-Curve / Sigmoid / Dose-Response | `SCurveChart` |
+| Survival / Kaplan-Meier / KM / Retention | `SurvivalCurveChart` |
+| Volcano | `VolcanoPlot` |
+| Dim. Reduction / PCA / t-SNE / UMAP | `DimRedPlot` |
+| Parallel Coords / parcoords | `ParallelCoordinatesPlot` |
+| Violin / Distribution | `ViolinPlot` |
+| Network / Graph / Node-Edge | `NetworkGraph` |
+| Trellis / Facet / Small-multiples | `TrellisGrid` |
+
+## Related
+- [[domain-requirements]] · [[component-contracts.domain]] · [[charting-standards.domain]]

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,eAAO,MAAM,WAAW,SA2DpB,CAAC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,eAAO,MAAM,WAAW,SAwGpB,CAAC"}

package/dist/commands/init.js

@@ -1,7 +1,13 @@
 import { Command } from 'commander';
 import inquirer from 'inquirer';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
 import { copyAssets } from '../utils/copy-assets.js';
 import { resolveAssetsPath } from '../utils/paths.js';
+import { createManifest } from '../utils/manifest.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const initCommand = new Command('init')
     .description('Initialize a new AppWeaver Spec project in the current directory')
     .argument('[directory]', 'Target directory (default: current directory)', '.')
@@ -10,7 +16,41 @@ export const initCommand = new Command('init')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (directory, options) => {
     const targetDir = directory === '.' ? process.cwd() : directory;
-    console.log(`\n🔧 Initializing AppWeaver Spec project in: ${targetDir}\n`);
+    const manifestPath = path.join(targetDir, '.aw-spec', 'manifest.json');
+    // Check for existing project
+    const existingManifest = await fs.pathExists(manifestPath);
+    if (existingManifest && !options.dryRun) {
+        console.log(chalk.yellow('\n\u26A0\uFE0F  Existing AppWeaver Spec project detected.'));
+        console.log(chalk.gray(`  Manifest found at: ${manifestPath}`));
+        if (options.yes) {
+            console.log(chalk.yellow('  Use `aw-spec update` to update this project.'));
+            process.exit(0);
+        }
+        const { action } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'action',
+                message: 'What would you like to do?',
+                choices: [
+                    { name: 'Update existing project (recommended)', value: 'update' },
+                    { name: 'Re-initialize (overwrite with fresh copy)', value: 'reinit' },
+                    { name: 'Cancel', value: 'cancel' },
+                ],
+                default: 'update',
+            },
+        ]);
+        if (action === 'update') {
+            console.log(chalk.gray('  Run `aw-spec update` to update this project.'));
+            process.exit(0);
+        }
+        else if (action === 'cancel') {
+            console.log(chalk.gray('\nInitialization cancelled.'));
+            process.exit(0);
+        }
+        // action === 'reinit' continues below
+        console.log(chalk.yellow('\n  Re-initializing (will overwrite existing files)...\n'));
+    }
+    console.log(`\n\uD83D\uDD27 Initializing AppWeaver Spec project in: ${targetDir}\n`);
     // Determine agent
     let agent = options.agent;
     // If --yes flag and no explicit agent, use default (claude) without prompting
@@ -38,11 +78,11 @@ export const initCommand = new Command('init')
     const assetsPath = await resolveAssetsPath();
     const agentFolder = agent === 'claude' ? '.claude' : agent === 'kilocode' ? '.kilocode' : '.agents';
     if (options.dryRun) {
-        console.log('📋 Dry run - would copy the following:');
-        console.log(`   ✓ ${assetsPath}/.aw-spec -> ${targetDir}/.aw-spec`);
-        console.log(`   ✓ ${assetsPath}/docs -> ${targetDir}/docs`);
-        console.log(`   ✓ ${assetsPath}/${agentFolder} -> ${targetDir}/${agentFolder}`);
-        console.log(`   ✓ ${assetsPath}/docs/VerticalSlice -> ${targetDir}/docs/VerticalSlice`);
+        console.log('\uD83D\uDCCB Dry run - would copy the following:');
+        console.log(`   \u2713 ${assetsPath}/.aw-spec -> ${targetDir}/.aw-spec`);
+        console.log(`   \u2713 ${assetsPath}/docs -> ${targetDir}/docs`);
+        console.log(`   \u2713 ${assetsPath}/${agentFolder} -> ${targetDir}/${agentFolder}`);
+        console.log(`   \u2713 ${assetsPath}/docs/VerticalSlice -> ${targetDir}/docs/VerticalSlice`);
         return;
     }
     // Copy assets
@@ -52,7 +92,14 @@ export const initCommand = new Command('init')
         agent: agent,
         overwrite: options.yes,
     });
-    console.log('\n✅ Project initialized successfully!');
+    // Create manifest after successful copy
+    console.log('\n\uD83D\uDD0D Creating manifest...');
+    const packageJson = await fs.readJSON(path.resolve(__dirname, '../../package.json'));
+    const manifest = await createManifest(assetsPath, targetDir, packageJson.version);
+    await fs.ensureDir(path.dirname(manifestPath));
+    await fs.writeJSON(manifestPath, manifest, { spaces: 2 });
+    console.log(chalk.green(`  \u2713 Manifest created (${Object.keys(manifest.files).length} files tracked)`));
+    console.log('\n\u2705 Project initialized successfully!');
     console.log('\nNext steps:');
     console.log('  aw-spec doctor    # Verify the installation');
     console.log('  aw-spec specify "Your feature description"  # Start spec-driven development');

package/dist/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/commands/update.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const updateCommand: Command;
+//# sourceMappingURL=update.d.ts.map

package/dist/commands/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,eAAO,MAAM,aAAa,SA6ItB,CAAC"}