# Zodiac Sky

> A tropical / Hellenistic star map connecting the visible sky to the zodiac coordinate
> system. It is designed to be **driven by an AI assistant** — there is no built-in chatbot;
> the user brings their own. If you are an LLM, you can read and control this app directly.

## How to drive it

You can drive Zodiac Sky two ways; you never need to know a URL hash in advance.

- **In-browser JS** — call the global `window.zodiac`:
  - `state()` → the current view as a plain object (the *same shape* `apply()` accepts).
  - `apply(partial)` → set state synchronously; only the fields you pass change.
  - `goto(partial)` → async; like `apply()` but a `place` (or natal `place`) may be a NAME
    string, which is geocoded for you. Resolves to the new state.
  - `geocode(query)` → async `{lat, lon, name}`.
  - Read `state()`, change what you care about, write it back. The URL updates itself.
- **URL hash** — every state is encoded in the `#...` hash, so any view is a shareable link
  you can construct directly from the schema in the driving guide.

## Docs

- [Driving guide](/DRIVING.md): full state shape, the `window.zodiac` API, the complete
  URL-hash schema (every key, type, default), and worked JS + URL examples.