[francoischalifour]

Context

Agents use this repository's documentation to build data apps. The docs should take them directly from the user's question to a working exploration and a story of its strongest findings.

Previously, that path required navigating overlapping guides and choosing between several equally presented implementation patterns. Entry points repeated instructions, examples used different names and input shapes, and app authoring guidance mixed with host integration and contributor details. Agents could spend unnecessary time reading files, reconstructing examples, and making decisions the starter or platform already resolved.

This change makes the documentation a concise playbook: follow the existing app or release-matched starter, use clear defaults, and consult another guide only when a requirement needs it.

Proposed solution

Establish one authoring path

docs/app-authoring.md becomes the main recipe:

1. Define the question and inspect the data.
2. Adapt the queries and operation.
3. Update context, datasets, and metrics.
4. Adapt the view and filters.
5. Compose the exploration.
6. Build the story from the displayed results.
7. Validate the app.

New apps start from the selected, release-matched starter. Existing apps keep their working structure and runtime wiring. AGENTS.md, the root README, and starter documentation route directly to this recipe. Broad reading lists become conditional lookups and exact-symbol searches in REFERENCE.md.

Give each choice a default and an exception

• Keep related results in one view; split views for independent requests.
• Use flat operation inputs matching variable names; add mappings and explicit bindings when an existing input shape requires them.
• Use generated controls and bound widgets; introduce custom UI when they cannot express the requirement.
• Use defineTimeView() for period-driven analysis and defineDataView() otherwise.
• Use source-backed dimensions for independent categorical filters, fixed options for constants, and facets when options depend on other selections.
• Use <Stack> and <Grid>, sections before navigation tabs, and default appearance unless customization is requested.

The recipe retains the analytical requirements: inspect population and grain, preserve missing-value semantics, and derive narrative, scope, stories, and exports from the same displayed snapshot, including during refresh or failure.

Align examples with the starter

Examples reuse the hosted starter's names and structure across queries, operations, context, views, datasets, widgets, and stories. App declarations consistently use dataApp, while public API properties retain their names, such as app: dataApp.

Snippets retain the enclosing declarations, callbacks, components, and JSX needed to understand their placement. Unrelated setup uses explicit // ... omissions instead of leaving isolated property fragments.

Separate authoring from integration

Normal authoring tasks retain the starter's transport and mounting setup. Host-specific concerns remain in integration documentation, including iframe messaging, server authorization, and custom delivery.

Standard themes, responsive layout, and SDK control behavior belong to platform verification. Authors verify their data, interactions, and content, with additional appearance and interaction checks when custom UI, CSS, colors, or unusual content introduce those concerns.

Apply the same principles to contributor documentation

Contributor guidance follows a direct sequence: locate the owning source, update affected consumers, run focused checks, complete required verification, and create a coherent commit. Implementation, packaging, CSS, public API, and release guidance remain available when those changes require them.

Repeated explanations, internal narratives, and prop inventories already covered by TypeScript and JSDoc are removed. The generated API reference opens with a short search example and the notation needed to interpret results. This preserves the authoring-only API reference introduced in #105.

Scope and tradeoffs

This branch primarily changes documentation and generated reference text. Small source changes standardize starter variable names and JSDoc examples; public APIs and runtime behavior are unchanged.

Authored Markdown, excluding the generated reference, is approximately 36% shorter. The intended benefit is fewer decisions and file reads; agent execution speed has not been benchmarked. Supporting guides remain available for requirements beyond the starter.

Validation

Rechecked after incorporating current main:

• Package build and generated API reference consistency.
• Markdown lint, local documentation links, formatting, and diff checks.
• Package boundaries and source lint.
• Isolated package-consumer validation and local starter checks.

Earlier authoring validation also parsed all 44 documentation JavaScript/TypeScript snippets and type-checked the main public-API patterns with explicitly omitted prerequisites restored.

The complete browser workflow suite was not rerun for this documentation-focused change.

[robinvrd]

Lots of MD edits 😅 trusting you on this