astrolabe/SOUL.md

# Astrolabe — What This Project Is About

## The Problem

People who work with [Vega-Lite](https://vega.github.io/vega-lite/) directly — analysts,
educators, chart authors — don't have a fast, private place to _keep_ their charts. The
official Vega-Lite editor is great for a single spec in a tab, but it forgets everything
when you close it. Notebooks bury charts in code. BI tools hide the spec behind a GUI and
lock you into an account.

Astrolabe fills this gap: **a local-first workspace where you author Vega-Lite specs as
JSON, see them render live, and keep a personal, searchable library of them — with no
account, no server, and full offline use.**

## The Core Idea

The central artifact is the **snippet**: a saved Vega-Lite specification plus metadata.
Everything else — the editor, the live preview, the dataset library, the chart builder —
exists to author, organize, and reuse snippets. Astrolabe does not abstract Vega-Lite
away; a snippet _is_ a Vega-Lite spec. The chart builder offers a no-JSON on-ramp, but the
JSON is always the source of truth and always editable.

Reusable **datasets** are stored once and referenced by name from many snippets, so the
data lives in one place and the specs stay lean.

## Core Values

### 1. Local-Only by Default

Everything runs in the browser. Snippets, datasets, and settings never leave the machine.
No accounts, no uploads, no tracking, and the app contacts no third party on its own —
including an AI model. The only outbound requests are user-created URL-dataset fetches.
Because your work stays on the machine, confidential and work data are safe in Astrolabe
from the first chart.

### 2. Vega-Lite Native, Not Vega-Lite Hidden

The product domain _is_ Vega-Lite. We validate, render, and reason about specs as
Vega-Lite, and we surface its real vocabulary (marks, encodings, field types). We don't
invent a parallel chart abstraction. The chart builder is an on-ramp, not a replacement
for the spec.

### 3. Experiment Safely

A snippet carries a stable **published** spec and an editable **draft**. You can tinker
freely without losing a known-good version. Auto-save protects in-progress work; publish
promotes it deliberately.

### 4. Beginner On-Ramp, Power-User Ceiling

The chart builder lets someone produce a chart without writing JSON. The editor — with
schema-aware autocomplete and live validation — lets a power user do anything Vega-Lite
can. Neither caps the other.

### 5. Own Your Data

Fully local and offline-capable, with import/export for backup and transfer. Your library
is a file you control, not a row in someone's database.

### 6. Predictable, Not Clever

When a behavior could go several ways, pick the one closest to the user's existing mental
model (the Vega-Lite editor, JSON tooling, file-based apps). Least surprise beats most
clever.

## What We're Not

- **Not a BI/dashboarding tool.** A snippet is _one_ visualization, not a composed report
  with cross-filters and layout. Dashboards are a different product.
- **Not a data-wrangling tool.** Datasets are stored and referenced, not cleaned or
  transformed. (That's [Syto](https://github.com/) territory — Astrolabe's sibling in
  architecture and quality bar, but a separate product with separate goals.)
- **Not a collaboration platform.** No multi-user, no sync, no comments. Import/export
  moves data between machines.
- **Not a server app.** No backend, no rendering service, no account system.
- **Not an AI tool.** No model authors, edits, or critiques charts, and nothing is sent to
  one. The chart builder's recommendations are deterministic and rule-based, computed
  locally — chosen over an LLM so results are explainable and nothing leaves the machine.

## Technical Philosophy

### Spec-Recorded, Clean Implementation

The behavioral record lives in `docs/spec/`. Astrolabe is a deliberate rebuild on a
robust architecture (adapted from Syto): behavior is designed deliberately and recorded
in the spec, not ported from old code. The code leads; the spec is rewritten to match
what ships — never silent drift.

### Portable Core, Thin Browser Shell

`src/core/` is pure and portable — no browser APIs, no UI framework. Spec operations
(detection, profiling, reference resolution, fit transforms, validation, import
normalization) live there and are tested hardest. The UI is a thin, replaceable shell over
that core.

### Leverage Existing Libraries

Vega-Lite renders. Monaco edits. vega-embed mounts charts. React + Zustand drive the UI.
We wrap these with thin integration layers rather than reinventing them. Custom code
focuses on what's unique to Astrolabe: the snippet/dataset model, the rendering contract,
and the workspace that ties it together.

### No Parallel Systems

Each fact lives in one place. A snippet↔dataset link, a setting, a schema — one source of
truth, others derived. If you're writing the same logic twice, one should import or be
generated from the other.

### Test the Core, Trust the UI

High coverage on the portable engine (where a bug corrupts data or breaks rendering);
lighter coverage on components (where a bug is a cosmetic annoyance).

## The Name

An **astrolabe** is an ancient instrument for locating and predicting the positions of
stars — a tool for finding your way by the sky. The app helps you find your way through a
library of visualizations: keep them, locate them, and see where each one points.