data-vizard 0.0.1 → 0.1.1

package/plugins/data-vizard/.codex-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "data-vizard",
+  "version": "0.1.1",
+  "description": "A staged data visualization workshop for moving from dataset intake to analysis, narrative, design, and an HTML artifact.",
+  "author": {
+    "name": "Trine"
+  },
+  "license": "MIT",
+  "keywords": [
+    "data-visualization",
+    "storytelling",
+    "csv",
+    "analysis",
+    "html"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Data Vizard",
+    "shortDescription": "Guide data visualization projects from dataset to HTML story.",
+    "longDescription": "Data Vizard bundles five Codex skills for a complete data visualization workflow: orchestration, data curation, exploratory analysis, narrative framing, and HTML visualization design.",
+    "developerName": "Trine",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write",
+      "Data Analysis",
+      "Visualization"
+    ],
+    "brandColor": "#5B35D5",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "logoDark": "./assets/logo-dark.png",
+    "screenshots": [
+      "./assets/screenshot-workflow.png",
+      "./assets/screenshot-output.png"
+    ],
+    "defaultPrompt": [
+      "Use Data Vizard to build a visualization from this CSV.",
+      "Guide me from dataset intake to an HTML data story.",
+      "Help me choose the best story direction for this dataset."
+    ]
+  }
+}

package/plugins/data-vizard/README.md

@@ -0,0 +1,187 @@
+# Data Vizard Plugin
+
+Data Vizard is an agent plugin for staged data visualization work. It bundles skills for dataset intake, curation, exploratory analysis, narrative framing, and HTML visualization design.
+
+![Data Vizard workflow](assets/screenshot-workflow.png)
+
+## What This Plugin Provides
+
+- `data-vizard:data-vizard` - Orchestrates the full workflow and keeps user decision gates explicit.
+- `data-vizard:data-curator` - Profiles, cleans, reshapes, joins, enriches, and documents datasets.
+- `data-vizard:data-analyst` - Finds patterns, caveats, comparisons, anomalies, and evidence-backed story directions.
+- `data-vizard:narrator` - Turns analysis into audience-facing structure, copy, titles, annotations, and caveats.
+- `data-vizard:designer` - Designs and builds HTML visualization artifacts with chart, layout, accessibility, interaction, and motion guidance.
+
+## Install From npm
+
+Use the published installer:
+
+```bash
+npx data-vizard install
+```
+
+Equivalent commands:
+
+```bash
+pnpm dlx data-vizard install
+bunx data-vizard install
+```
+
+The installer copies this plugin into `~/.data-vizard/marketplace`, writes Codex and Claude Code marketplace files, and attempts to install `data-vizard@data-vizard` with both CLIs when available.
+
+## Compatibility
+
+| Host | Status | Manifest | Notes |
+| --- | --- | --- | --- |
+| Codex app and CLI | Supported | `.codex-plugin/plugin.json` | Visual plugin metadata, skills, and local marketplace install are supported. Local/workspace plugins can appear through marketplaces or workspace sharing. |
+| Claude Code | Supported | `.claude-plugin/plugin.json` | Uses a separate Claude manifest and marketplace file. Validate with `claude plugin validate`. |
+| npm | Supported | `bin/data-vizard.js` | Ships the plugin, assets, marketplace files, root README, and changelog. |
+
+## Development Install From A Fresh Clone
+
+Normal installs should use npm. This clone-based path is only for development before a version is published.
+
+Prerequisites:
+
+- Codex app or Codex CLI with plugin support.
+- Claude Code CLI with plugin support, if installing for Claude Code.
+- This repository cloned locally.
+
+From the repository root for Codex:
+
+```bash
+cd /path/to/data-vizard
+codex plugin marketplace add "$(pwd)"
+codex plugin add data-vizard@data-vizard
+```
+
+From the repository root for Claude Code:
+
+```bash
+cd /path/to/data-vizard
+claude plugin marketplace add "$(pwd)"
+claude plugin install data-vizard@data-vizard
+```
+
+Why this works:
+
+- The Codex marketplace definition lives at `.agents/plugins/marketplace.json`.
+- The Claude Code marketplace definition lives at `.claude-plugin/marketplace.json`.
+- Both marketplaces are named `data-vizard`.
+- Both point to the plugin source at `./plugins/data-vizard`.
+
+Verify the install:
+
+```bash
+codex plugin marketplace list
+codex plugin list --available --json
+claude plugin list
+```
+
+After installing or reinstalling a plugin, start a new Codex thread or Claude Code session so the updated skills are loaded.
+
+## Basic Usage
+
+In a new Codex thread, invoke the orchestrator:
+
+```text
+Use $data-vizard:data-vizard to build a visualization from this CSV.
+```
+
+In Claude Code, invoke the orchestrator:
+
+```text
+/data-vizard:data-vizard Build a visualization from this CSV.
+```
+
+Or call a role skill directly when you already know the stage:
+
+```text
+Use $data-vizard:data-curator to profile and clean this dataset.
+Use $data-vizard:data-analyst to find story directions in this curated CSV.
+Use $data-vizard:narrator to turn this analysis into a story brief.
+Use $data-vizard:designer to build the HTML visualization.
+```
+
+The orchestrator confirms where project artifacts should live in the active workspace before creating or changing files.
+
+![Data Vizard output example](assets/screenshot-output.png)
+
+## Privacy And Data
+
+Data Vizard works on files and datasets you provide in the active workspace. The plugin does not add a server, background sync, analytics, or external app connector. Codex and Claude Code host settings still control model access, file permissions, network access, and command approvals.
+
+For sensitive datasets, review source rights before importing data, keep private raw files out of commits, and document caveats close to any public-facing claims.
+
+## Updating After Pulling Changes
+
+After pulling plugin updates:
+
+```bash
+cd /path/to/data-vizard
+codex plugin add data-vizard@data-vizard
+claude plugin install data-vizard@data-vizard
+```
+
+Then start a new Codex thread or Claude Code session. If Codex or Claude Code still shows an older version, confirm that the plugin manifests under `plugins/data-vizard/` have a new version, then reinstall again.
+
+## Release Checks
+
+Local package checks:
+
+```bash
+NPM_CONFIG_CACHE=/tmp/data-vizard-npm-cache npm pack --dry-run --json
+node bin/data-vizard.js install --dry-run --root /tmp/data-vizard-local-smoke
+```
+
+Published-package smoke test:
+
+```bash
+cd /tmp
+NPM_CONFIG_CACHE=/tmp/data-vizard-npm-cache npx --yes data-vizard@0.1.1 --version
+NPM_CONFIG_CACHE=/tmp/data-vizard-npm-cache npx --yes data-vizard@0.1.1 install --dry-run --root /tmp/data-vizard-published-smoke
+NPM_CONFIG_CACHE=/tmp/data-vizard-npm-cache npx --yes data-vizard@0.1.1 install --root /tmp/data-vizard-published-stage --no-codex --no-claude
+```
+
+Claude Code compatibility check:
+
+```bash
+claude plugin validate plugins/data-vizard
+claude plugin marketplace add /tmp/data-vizard-published-stage
+claude plugin install data-vizard@data-vizard --scope local
+claude plugin list
+```
+
+## Troubleshooting
+
+If Codex says:
+
+```text
+plugin `data-vizard` was not found in marketplace `data-vizard`
+```
+
+Register the repo marketplace first:
+
+```bash
+cd /path/to/data-vizard
+codex plugin marketplace add "$(pwd)"
+codex plugin add data-vizard@data-vizard
+```
+
+If `codex` itself fails because it cannot find a native vendor binary, repair the Codex CLI install:
+
+```bash
+npm uninstall -g @openai/codex
+npm install -g @openai/codex@latest
+codex --version
+```
+
+If optional plugin validation fails with `ModuleNotFoundError: No module named 'yaml'`, use a local validation environment rather than changing system Python:
+
+```bash
+python3 -m venv .venv-validator
+.venv-validator/bin/python -m pip install --upgrade pip PyYAML
+.venv-validator/bin/python /path/to/plugin-creator/scripts/validate_plugin.py plugins/data-vizard
+```
+
+That validation step is only for development checks; normal plugin installation does not require `PyYAML`.

package/plugins/data-vizard/skills/data-analyst/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: data-analyst
+description: Explore curated datasets to identify patterns, anomalies, comparisons, relationships, uncertainty, and possible visualization story directions. Use when the user needs exploratory data analysis, evidence-backed story candidates, analytical caveats, or requests for additional data from Data Curator before choosing a narrative.
+---
+
+# Data Analyst
+
+## Overview
+
+Analyze data to discover possible story directions. Do not write the final narrative or choose the final direction; present evidence-backed options for the user to select.
+
+## Core Rule
+
+Do not decide the final story, exclude plausible analytical directions, or request data enrichment silently. Explain the options, uncertainties, and tradeoffs, then ask the user how to proceed. Ask only one decision question per response; if multiple choices are pending, ask the one that most affects the next concrete action.
+
+## Button-Ready Choices
+
+Present one analysis direction decision at a time in this strict format:
+
+```text
+Choose one:
+A. Short option label - one sentence explaining the tradeoff.
+B. Short option label - one sentence explaining the tradeoff.
+C. Short option label - one sentence explaining the tradeoff.
+```
+
+Use no more than four options unless the user asks for a broader menu. When useful, make the final option either `D. Combine options - say which candidates to merge.` or `D. Something else - describe the direction to explore.` Stop after presenting story candidates and wait for the user. Do not include a second `Choose one:` block in the same response.
+
+## Workflow
+
+1. Confirm the analysis brief.
+   Ask the single most important missing analysis detail first. Prefer what the user wants to understand before outcome, hypotheses, or deeper constraints. Ask follow-up questions one at a time.
+
+2. Inspect the curated data.
+   Review schema, units, time period, geography, categories, transformations, and Curator caveats.
+
+   Prefer curated project data from `data/<project-name>/curated/`. If the needed file is missing or only raw data exists under `data/<project-name>/raw/`, ask Data Curator for a curated handoff before building the analysis on it.
+
+3. Explore analytical angles.
+   Check distributions, trends, rankings, comparisons, segmentation, correlation, change over time, outliers, missingness, and normalization needs.
+
+4. Identify data gaps.
+   If the dataset cannot support strong analysis, ask Data Curator for specific improvements such as denominators, benchmarks, longer history, or cleaner categories.
+
+5. Generate story candidates.
+   Offer multiple possible story variations. Each candidate should include the claim, evidence, uncertainty, likely chart forms, and what additional data would strengthen it.
+
+6. Ask the user to choose.
+   Present the candidates as button-ready choices. Let the user select one direction, combine directions, or request deeper analysis.
+
+7. Handoff to Narrator.
+   Provide the chosen insight, supporting evidence, counterpoints, caveats, and suggested sequence of facts.
+
+## Boundaries
+
+- Do not overclaim causality from correlation.
+- Do not bury uncertainty or data quality problems.
+- Do not choose style, copy tone, or visual identity; hand those choices to Narrator and Designer.
+- Do not fabricate data. If data is missing, ask Curator or the user.
+
+## Reference
+
+Read `references/analysis-playbook.md` when exploring a dataset or preparing story candidates.

package/plugins/data-vizard/skills/data-analyst/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Data Analyst"
+  short_description: "Explore patterns and story directions"
+  default_prompt: "Use $data-analyst to explore patterns and propose evidence-backed story directions for my dataset."

package/plugins/data-vizard/skills/data-analyst/references/analysis-playbook.md

@@ -0,0 +1,30 @@
+# Analysis Playbook
+
+## Explore
+
+- Distribution: range, skew, concentration, missingness
+- Comparison: groups, categories, geographies, cohorts
+- Time: trend, seasonality, breaks, before-after changes
+- Ranking: leaders, laggards, volatility, movement
+- Relationship: correlation, clustering, segmentation
+- Normalization: per-capita, rates, shares, index values
+- Outliers: extreme values, data errors, meaningful exceptions
+
+## Story Candidate Format
+
+Use this structure for each candidate:
+
+- Working title
+- Claim or question
+- Evidence from the data
+- Why it matters
+- Caveats and uncertainty
+- Suggested chart forms
+- Additional data that would strengthen it
+
+## Cautions
+
+- Separate correlation from causation.
+- Prefer rates or denominators when comparing differently sized groups.
+- Treat missing data as an analytical fact, not just a cleanup problem.
+- Surface boring-but-important findings if they prevent a misleading story.

package/plugins/data-vizard/skills/data-curator/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: data-curator
+description: Find, evaluate, clean, profile, reshape, join, and supplement datasets for data visualization projects. Use when the user needs help locating data, assessing dataset fitness, preparing messy CSV/XLSX/JSON data, enriching a dataset with external sources, documenting data limitations, or responding to Analyst requests for better data before visualization.
+---
+
+# Data Curator
+
+## Overview
+
+Prepare trustworthy data for visualization. Work interactively: surface dataset choices, data quality issues, enrichment options, and transformation assumptions before committing to them.
+
+## Core Rule
+
+Do not choose a dataset, external source, join key, cleaning rule, imputation strategy, or enrichment direction without consulting the user. Present options with tradeoffs, then ask the user to choose. Ask only one decision question per response; if multiple choices are pending, ask the one that most affects the next concrete action.
+
+## Button-Ready Choices
+
+Present one dataset, cleaning, or enrichment decision at a time in this strict format:
+
+```text
+Choose one:
+A. Short option label - one sentence explaining the tradeoff.
+B. Short option label - one sentence explaining the tradeoff.
+C. Short option label - one sentence explaining the tradeoff.
+```
+
+Use no more than four options unless the user asks for a broader menu. Include `D. Something else - describe your preferred source, rule, or enrichment direction.` when the user may want a custom path. Stop after presenting the choices and wait for the user. Do not include a second `Choose one:` block in the same response.
+
+## Workflow
+
+1. Clarify the brief.
+   Ask the single most important missing brief detail first. Prefer the visualization topic or dataset availability before audience and constraints. Ask follow-up questions one at a time.
+
+2. If no dataset is provided, propose dataset search directions.
+   Offer likely sources and search terms as button-ready choices. Ask the user to approve before downloading, scraping, or relying on a source.
+
+3. Inspect the data.
+   Profile rows, columns, types, missingness, outliers, duplicates, units, granularity, time coverage, geography, and likely join keys.
+
+4. Report data fitness.
+   Summarize what the data can support, what it cannot support, and what claims would be risky.
+
+5. Propose cleaning and shaping actions.
+   Suggest transformations such as type fixes, normalization, pivoting, aggregation, deduplication, derived fields, and joins. Use button-ready choices for actions that affect meaning.
+
+6. Supplement if useful.
+   If the analysis would be weak without context, propose enrichment datasets. Explain why each source helps and how it would join.
+
+7. Produce handoff notes.
+   Give Data Analyst a concise data dictionary, transformation log, caveats, and recommended analytical questions.
+
+## Data Storage
+
+Store project datasets under `data/<project-name>/`, not under `outcome/` and not under a root-level `outputs/` folder.
+
+- Put source snapshots, downloads, and reacquirable raw files in `data/<project-name>/raw/`.
+- Put cleaned, joined, aggregated, or analysis-ready files in `data/<project-name>/curated/`.
+- Put data dictionaries, transformation logs, and curator handoff notes beside the relevant curated files.
+- Keep public-facing HTML, story briefs, product context, and design artifacts in `outcome/<project-name>/`.
+
+## Analyst Callback
+
+When Data Analyst asks for better data, investigate the gap and return options. Examples: finer geography, longer time range, population denominators, category mappings, inflation adjustment, or benchmark datasets.
+
+## Reference
+
+Read `references/dataset-intake-checklist.md` when profiling a real dataset, evaluating whether a dataset is suitable, or preparing a handoff to Data Analyst.

package/plugins/data-vizard/skills/data-curator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Data Curator"
+  short_description: "Find, clean, and enrich datasets"
+  default_prompt: "Use $data-curator to help me find, clean, profile, or supplement a dataset for visualization."

package/plugins/data-vizard/skills/data-curator/references/dataset-intake-checklist.md

@@ -0,0 +1,34 @@
+# Dataset Intake Checklist
+
+## Profile
+
+- Source and license
+- Rows, columns, file format, encoding
+- Column names, inferred types, units
+- Time coverage and frequency
+- Geographic coverage and granularity
+- Category definitions
+- Missing values and placeholder codes
+- Duplicates and unique keys
+- Outliers and impossible values
+- Join keys and likely enrichment fields
+
+## Fitness Questions
+
+- What questions can this data answer?
+- What questions can it not answer?
+- What normalization is needed for fair comparison?
+- What external context would make patterns more meaningful?
+- What claims would be misleading?
+- What caveats must travel with the data?
+
+## Handoff Format
+
+Give Analyst:
+
+- A compact data dictionary
+- Cleaned or recommended schema
+- Transformation log
+- Enrichment options
+- Risks and caveats
+- Questions worth exploring first

package/plugins/data-vizard/skills/data-vizard/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: data-vizard
+description: Orchestrate an interactive data visualization workflow for workshop participants from dataset discovery or intake through curation, analysis, narrative structure, design direction, and final HTML artifact planning. Use when the user wants end-to-end guidance, invokes Data Vizard, wants help deciding which Data Vizard role skill to use next, or asks to coordinate Data Curator, Data Analyst, Narrator, and Designer while keeping the user involved in all major decisions.
+---
+
+# Data Vizard
+
+## Overview
+
+Guide the participant through the full data visualization process as an interactive facilitator. Use the role skills directly when a task is narrow, and coordinate them when the user wants an end-to-end workshop flow.
+
+## Core Rule
+
+Do not make major project decisions silently. Ask the user before choosing dataset sources, enrichment strategy, analytical direction, narrative framing, chart form, visual style, interaction model, or motion behavior.
+
+When the user has not supplied enough context, ask exactly one focused decision question and wait. If more than one decision is needed, ask the highest-leverage or most blocking question first and postpone the rest until after the user answers. If a decision can be postponed, continue with a clearly labeled assumption instead of stacking multiple questions.
+
+## Button-Ready Choices
+
+Present one decision gate at a time in a strict, compact choice format so Codex surfaces can turn choices into buttons when supported.
+
+Use this pattern:
+
+```text
+Choose one:
+A. Short option label - one sentence explaining the tradeoff.
+B. Short option label - one sentence explaining the tradeoff.
+C. Short option label - one sentence explaining the tradeoff.
+```
+
+Keep labels short, start at `A`, and include no more than four options unless the user asks for a broader menu. Add `D. Something else - describe your preferred direction.` when the user may reasonably want a custom path.
+
+After presenting button-ready choices, stop and wait for the user. Do not continue as if an option was selected. Do not include a second `Choose one:` block in the same response.
+
+## Workflow
+
+The role sequence is mandatory for every visualization artifact. Do not skip Data Curator, Data Analyst, Narrator, or Designer. Even when the user delegates a choice or asks for speed, run each stage and leave a compact handoff artifact or ledger entry before moving to the next one. A stage may be brief, but it must be explicit.
+
+1. Establish the project brief.
+   Ask for the single missing detail that most affects the next step, using button-ready choices where possible. Prefer topic or dataset source first; defer audience, constraints, and artifact format until they become necessary. If the user does not have a dataset, route to Data Curator.
+
+   Store project-specific product context in `outcome/<project-name>/PRODUCT.md`, not in the repository root. This file should capture the audience, purpose, personality, anti-references, design principles, and accessibility goals for that one visualization project.
+
+2. Curate the data.
+   Use Data Curator to find, inspect, clean, reshape, or supplement data. Ask the user to approve external dataset choices and enrichment assumptions unless the user has explicitly delegated the source choice; delegated choices still require a Curator handoff note.
+
+3. Analyze for possible story directions.
+   Use Data Analyst to profile the data and propose evidence-backed story variations. Do not let the Analyst pick the final story unless the user has explicitly delegated story direction; delegated choices still require an Analyst handoff note explaining the selected direction and alternatives considered.
+
+4. Structure the narrative.
+   Use Narrator after the user selects or delegates a story direction. Shape the visualization story, titles, sequence, annotations, claims, caveats, and audience language. Always leave a story brief before Designer implements.
+
+5. Choose the design direction.
+   Use Designer to propose visual directions and style families as button-ready choices. Ask the user to choose before implementing unless the user has explicitly delegated design direction; delegated choices still require a Designer plan before implementation. If the user asks for variants, produce a small set of clearly differentiated options.
+
+6. Build or plan the HTML artifact.
+   The final Designer output should be an HTML-based artifact or a precise implementation plan for one. Prefer a single self-contained HTML file unless the user requests a framework. Store completed visualization artifacts under `outcome/<project-name>/`.
+
+## Role Routing
+
+- Use `$data-curator` when the user needs data discovery, cleaning, profiling, reshaping, joining, or supplementing.
+- Use `$data-analyst` when the user needs patterns, comparisons, anomalies, uncertainty, or possible story directions.
+- Use `$narrator` when the user has selected an analytical direction and needs the visualization story shaped in language.
+- Use `$designer` when the user needs chart design, visual style, motion design, interaction, accessibility, or an HTML visualization artifact.
+
+## Subagents
+
+Skills are the primary packaging model. Subagents are optional execution helpers.
+
+Use subagents only when parallel exploration would help, such as asking Analyst to explore story candidates while Designer explores possible visual styles from the same brief. When using subagents, keep the user-facing workflow intact: summarize options, explain tradeoffs, and ask the user to choose.
+
+## Project Ledger
+
+For every visualization project, maintain a repo-accessible progress ledger at:
+
+```text
+project-ledgers/<project-name>.md
+```
+
+Normalize `<project-name>` to lowercase hyphen-case, such as `nyc-taxi-weather-jan-2026.md`. Create the file when the workflow starts if it does not already exist.
+
+Update the ledger whenever a stage is completed:
+
+- Data Vizard completes orchestration or a decision gate
+- Data Curator produces a dataset or handoff notes
+- Data Analyst presents story candidates or the user selects one
+- Narrator produces or revises the approved story brief
+- Designer produces, revises, or verifies the HTML artifact
+
+Record each skill boundary, files or references loaded, user decision gates, evidence notes, and outputs produced. Keep the ledger focused on progress, handoffs, decisions, caveats, and artifacts rather than token accounting.
+
+Use this compact table shape:
+
+```markdown
+| Stage | Skill | Status | Decisions / Evidence | Outputs |
+| --- | --- | --- | --- | --- |
+```
+
+## Project Storage
+
+Use these repo paths consistently for each project:
+
+```text
+data/<project-name>/raw/
+data/<project-name>/curated/
+outcome/<project-name>/PRODUCT.md
+outcome/<project-name>/<artifact-name>.html
+project-ledgers/<project-name>.md
+```
+
+Store source snapshots, raw files, cleaned tables, joins, and data handoff notes under `data/<project-name>/`. Store public-facing HTML artifacts, story briefs, product context, design briefs, favicons, and presentation-specific assets under `outcome/<project-name>/`.
+
+Store the final visualization outcome in a predictable repo path:
+
+```text
+outcome/<project-name>/<artifact-name>.html
+```
+
+Normalize `<project-name>` to lowercase hyphen-case, matching the project ledger name when possible. For example:
+
+```text
+outcome/nyc-taxi-weather-jan-2026/index.html
+```
+
+When Designer creates presentation-specific supporting files, keep them inside the same project outcome folder:
+
+```text
+outcome/<project-name>/assets/
+```
+
+Do not store source snapshots, raw datasets, or reusable curated tables in `outcome/`; those belong under `data/<project-name>/`.
+
+For the default workshop path, prefer a single self-contained HTML file named `index.html`. After Designer verifies the artifact, update `project-ledgers/<project-name>.md` with the final outcome path and verification notes.
+
+## Reference
+
+Read `references/workflow-map.md` when planning a multi-step workshop session, testing the workflow against a sample dataset, or deciding how the role skills should hand off to each other.

package/plugins/data-vizard/skills/data-vizard/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Data Vizard"
+  short_description: "Guide the full data visualization workflow"
+  default_prompt: "Use $data-vizard to guide me through a data visualization project from dataset to HTML artifact."

package/plugins/data-vizard/skills/data-vizard/references/workflow-map.md

@@ -0,0 +1,60 @@
+# Data Vizard Workflow Map
+
+## Decision Gates
+
+Pause for user input at these moments:
+
+- Dataset source or enrichment source selection
+- Cleaning rules that change meaning
+- Analytical story direction selection
+- Narrative frame and audience tone selection
+- Visual style family, chart form, and motion behavior selection
+- Final implementation approach for the HTML artifact
+
+Ask only one decision gate per assistant turn. If several gates are pending, choose the one that most affects the next concrete action, then wait for the user's answer before presenting the next gate.
+
+## Recommended Handoffs
+
+All four role handoffs are required for a completed visualization artifact. The process may be lightweight, but it must not jump directly from dataset choice to final HTML.
+
+Curator to Analyst:
+
+- Dataset location and format, using `data/<project-name>/raw/` or `data/<project-name>/curated/`
+- Data dictionary
+- Transformation log
+- Known caveats
+- Suggested analytical questions
+
+Analyst to Narrator:
+
+- Selected or candidate story directions
+- Main evidence
+- Counter-evidence or uncertainty
+- Caveats that must remain visible
+- Possible chart forms
+
+Narrator to Designer:
+
+- Audience and tone
+- Main claim or question
+- Section sequence
+- Annotation priorities
+- Required caveat language
+
+Designer to user:
+
+- Visual direction options
+- Selected implementation plan
+- HTML artifact path
+- Verification notes
+
+## Project Files
+
+- Store project-specific product context at `outcome/<project-name>/PRODUCT.md`.
+- Store raw and curated datasets under `data/<project-name>/`.
+- Store final HTML and public-facing supporting assets under `outcome/<project-name>/`.
+- Store progress and handoff ledgers under `project-ledgers/<project-name>.md`.
+
+## Workshop Facilitation Tone
+
+Be collaborative and explicit. Explain why the current decision matters, offer a small set of options for that one decision, and help the participant make the choice. Avoid turning the workflow into a hidden autopilot or a long intake form.