diff --git a/readme.md b/readme.md
index ee4fafd..4e5cb02 100644
--- a/readme.md
+++ b/readme.md
@@ -1,6 +1,106 @@
-things don't work:
+# hakysidian
 
-1. equation labels & paragraph labels
-2. pandoc does not support mathtools: <https://github.com/jgm/texmath/issues/249>
-3. cross document refs
-4. 
\ No newline at end of file
+`hakysidian` is a static site generator for note projects.
+
+It is built on Hakyll, but packaged as a reusable CLI so you can run the same site generator across multiple note repositories without copying shared assets around. The executable bundles its shared `css/`, `fonts/`, `templates/`, `favicon.ico`, and `bib_style.csl` files with Cabal, then reads project-specific content from the current working directory.
+
+## What It Expects
+
+Run `hakysidian` inside a project directory with this layout:
+
+```text
+your-project/
+├── notes/
+│   ├── first-note.md
+│   └── another-note.md
+├── reference.bib
+├── math-macros.md
+└── images/              # optional
+```
+
+Required inputs:
+
+- `notes/`: markdown notes to compile.
+- `reference.bib`: bibliography used by Pandoc citeproc.
+- `math-macros.md`: math macro definitions prepended before note parsing.
+
+Optional inputs:
+
+- `images/`: copied into the generated site as-is.
+
+Shared assets are not required in each project. They come from the installed `hakysidian` package.
+
+## Output
+
+By default, `hakysidian` writes:
+
+- `_site/`: generated site output.
+- `_cache/`: Hakyll cache and temporary files.
+
+Note pages use clean URLs. For example:
+
+```text
+notes/graph.md -> _site/notes/graph/index.html
+```
+
+## Install
+
+From this repository:
+
+```bash
+cabal build exe:hakysidian
+cabal install exe:hakysidian
+```
+
+## Commands
+
+The CLI mirrors the common Hakyll workflow:
+
+```bash
+hakysidian build
+hakysidian clean
+hakysidian rebuild
+hakysidian watch
+```
+
+`watch` also supports:
+
+```bash
+hakysidian watch --host 127.0.0.1 --port 8000
+hakysidian watch --no-server
+```
+
+What each command does:
+
+- `build`: incremental site build.
+- `clean`: removes generated output and cache.
+- `rebuild`: clears output/cache and builds from scratch.
+- `watch`: shows an in-place terminal dashboard, watches project inputs, and rebuilds automatically on change.
+
+## Watch Mode
+
+`watch` tracks:
+
+- `notes/**`
+- `reference.bib`
+- `math-macros.md`
+- `images/**`
+
+The watch UI:
+
+- uses the terminal’s current size to keep the dashboard within the visible screen,
+- keeps recent build output in a bounded activity pane,
+- avoids scrolling raw Hakyll logs through the terminal,
+- can start a local preview server unless `--no-server` is passed.
+
+## Notes Format
+
+This generator is opinionated toward the current note pipeline in this repository:
+
+- Markdown is parsed with Pandoc and custom theorem/callout handling.
+    - math is rendered with MathML. looks good in firefox
+    - sidenotes are supported
+    - spacing between CJK chars and ascii is automatically handled by a filter.
+- Citations are processed through `reference.bib` and the bundled `bib_style.csl`.
+- `math-macros.md` is injected before parsing so note content and theorem titles can use the same macros.
+- Notes are rendered with the bundled templates and stylesheet set.