Add comprehensive documentation structure for user success journeys

[Copilot]

ChartSpec lacked structured documentation for key workflows: quick browser trials, dataset integration, schema understanding, and deployment. Users had to piece together information from scattered README sections.

Changes

Documentation Hub (docs/index.md)

• UI comparison matrix (Classic vs Workbench)
• Operating mode decision tree (LLM/Smart/Local)
• User journey quick-start paths
• Failure mode troubleshooting index

Schema Reference (docs/schema.md)

• Complete ChartSpec field documentation with types and constraints
• Examples for all 9 chart types (bar, line, scatter, pie, histogram, box, heatmap, table, facet)
• Filter types (array, equality, operator) with validation rules
• Common patterns: Top-N sorting, grouped aggregations, faceted charts

Architecture Guide (docs/architecture.md)

• Pipeline stages: prompt parsing → data transformation → rendering
• Renderer abstraction with BaseRenderer interface
• Step-by-step: adding new renderers (with code examples)
• Extension points: LLM providers, aggregation functions, filter types

Dataset Management (docs/datasets.md)

• Storage strategies: localStorage limits vs IndexedDB for large data
• Demo gallery mechanics (Socrata integration, caching, TTL)
• Sampling strategies: random, stratified, top-N
• Paging patterns for datasets >10MB

Testing Guide (docs/testing.md)

• Playwright test infrastructure and __TEST_MODE__ flag usage
• Local development loop with dev server
• Test patterns: element waiting, dialog handling, error capture
• Debugging techniques for flaky tests

Deployment Guide (docs/deployment.md)

• GitHub Pages: root vs /docs deployment options
• Link hygiene: relative URLs for subdirectory compatibility
• Common failures: 404s, missing styles, CORS, out-of-sync files
• Custom domain DNS setup

README Updates

• Quick Start: 2-minute browser trial path
• Enhanced security section: localStorage-only API keys, never commit
• Mode comparison table with use cases
• Links to new documentation structure

Example: ChartSpec with Filters and Aggregation

{
  "chartType": "bar",
  "x": "Region",
  "y": "Revenue",
  "filters": [
    { "type": "array", "column": "Region", "values": ["North", "South"] },
    { "type": "op", "column": "Revenue", "operator": ">", "value": 1000 }
  ],
  "groupBy": {
    "columns": ["Region"],
    "aggregations": { "Revenue": { "func": "sum" } }
  },
  "sort": { "column": "Revenue", "order": "desc" },
  "limit": 10
}

All documentation uses relative URLs for GitHub Pages compatibility and includes failure mode sections.

Original prompt

You are the repo documentation agent for a browser-based charting tool that generates a structured chart specification from natural language and renders it.

Goal: make users successful in these journeys:

• “Try it in-browser in 2 minutes”
• “Add my dataset and get a chart”
• “Understand the ChartSpec schema and extend renderers”
• “Run tests and ship to GitHub Pages”

Rules:

• Use the existing UI modes and file structure; do not rename components in docs.
• Every doc page should include a short “What you’ll learn” section.
• Keep the ChartSpec JSON schema as the single source of truth; document it carefully.

Deliverables:

1. README.md improvements

   • Clear 3-mode explanation (LLM mode / Smart mode / Local mode)
   • Security note: API keys stay in browser storage; never commit keys
   • Link to schema docs, renderer docs, dataset docs

2. docs/index.md

   • UI map (classic vs workbench)
   • Link hub: schema, renderers, datasets, storage, testing, deployment

3. docs/schema.md

   • Fully documented ChartSpec fields: filters, groupBy, sort, limit, chartType, encodings, facet
   • Include valid JSON examples for each chart type

4. docs/architecture.md

   • Pipeline diagram: prompt → spec → transform → render
   • Renderer abstraction: how to add a new renderer safely

5. docs/datasets.md

   • Dataset registration, limits, caching strategy, demo gallery mechanics
   • Guidance for large datasets (sampling, paging)

6. docs/testing.md

   • How Playwright tests run; test mode flags; local dev loop

7. docs/deployment.md

   • GitHub Pages publishing (root vs /docs) and link hygiene

Quality checks:

• All examples use relative URLs where possible (Pages-safe).
• Document “failure modes”: invalid spec, missing columns, storage quota, renderer load failure.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.