feat: init

README.md

@@ -0,0 +1,158 @@
+# Micronomicon
+
+A self-hosted web editor for writing Markdown and publishing `.mu` pages to a NomadNet node.
+
+Write in Markdown → preview as Micron → publish directly to `~/.nomadnetwork/storage/pages/`.
+
+---
+
+## Requirements
+
+- Docker + Docker Compose
+- Python 3.13+ (for local backend development only)
+- Node 20+ (for local frontend development only)
+- A running NomadNet container named `nomadnet` (for the restart button)
+
+---
+
+## Quick Start (Docker)
+
+```bash
+# 1. Build the frontend
+cd frontend
+npm install
+npm run build
+cd ..
+
+# 2. Create source directories
+mkdir -p ~/.nomadnetwork/storage/pages ~/.micron-editor/sources
+
+# 3. Start the stack
+docker compose up --build
+```
+
+App is available at `http://localhost:8080`.
+
+### Tailscale HTTPS
+
+```bash
+tailscale serve --bg https+insecure://localhost:8080
+```
+
+---
+
+## Local Development
+
+Run backend and frontend separately with hot reload.
+
+**Backend**
+
+```bash
+cd backend
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+
+PAGES_DIR=~/.nomadnetwork/storage/pages \
+SOURCES_DIR=~/.micron-editor/sources \
+uvicorn main:app --reload --port 8080
+```
+
+**Frontend**
+
+```bash
+cd frontend
+npm install
+npm run dev   # proxies /api → localhost:8080
+```
+
+Open `http://localhost:5173`.
+
+---
+
+## Environment Variables
+
+| Variable             | Default          | Description                          |
+|----------------------|------------------|--------------------------------------|
+| `PAGES_DIR`          | `/data/pages`    | NomadNet pages directory             |
+| `SOURCES_DIR`        | `/data/sources`  | Markdown source files directory      |
+| `NOMADNET_CONTAINER` | `nomadnet`       | Docker container name to restart     |
+
+---
+
+## API Reference
+
+| Method   | Path                | Description                                   |
+|----------|---------------------|-----------------------------------------------|
+| `GET`    | `/api/health`       | Health check                                  |
+| `POST`   | `/api/convert`      | Convert `{ markdown }` → `{ micron }`         |
+| `GET`    | `/api/pages`        | List all pages with metadata                  |
+| `GET`    | `/api/pages/{name}` | Read page (markdown source + micron output)   |
+| `POST`   | `/api/pages/{name}` | Save `{ markdown, publish }` — draft or live  |
+| `DELETE` | `/api/pages/{name}` | Delete source and/or `.mu` file               |
+| `GET`    | `/api/graph`        | Graph nodes + edges from parsed link sources  |
+| `POST`   | `/api/restart`      | Restart NomadNet Docker container             |
+
+---
+
+## Directory Layout
+
+```
+micronomicon/
+  Dockerfile
+  compose.yml
+  backend/
+    main.py           ← FastAPI app + static file serving
+    converter.py      ← md2txt wrapper (POST /api/convert)
+    pages.py          ← file management (CRUD /api/pages)
+    graph.py          ← link parser (GET /api/graph)
+    docker_utils.py   ← container restart (POST /api/restart)
+    requirements.txt
+  frontend/
+    src/
+      App.tsx
+      routes/         ← DashboardView, EditorView, GraphView
+      components/     ← dashboard/, editor/, shared/, ui/ (shadcn)
+      stores/         ← editorStore, pagesStore (Zustand)
+      hooks/          ← useConversion, useGraph, useUnsavedGuard
+      lib/            ← utils (cn)
+
+~/.nomadnetwork/storage/pages/   ← published .mu files (NomadNet serves these)
+~/.micron-editor/sources/        ← markdown sources (managed by this app)
+```
+
+---
+
+## Page Lifecycle
+
+```
+New Page  →  /editor/new  →  Save Draft  →  .md saved to sources/
+                          →  Publish     →  .md saved + .mu written to pages/
+```
+
+- **Draft** — `.md` exists, no `.mu`. Not visible on NomadNet.
+- **Published** — both `.md` and `.mu` exist.
+- **Orphan** — `.mu` exists but no `.md` source (e.g. pages created outside this tool).
+
+---
+
+## Tech Stack
+
+| Layer     | Technology                              |
+|-----------|-----------------------------------------|
+| Backend   | Python 3.13 + FastAPI + uvicorn         |
+| Converter | md2txt (micron renderer)                |
+| Frontend  | React 19 + Vite + TypeScript            |
+| UI        | shadcn/ui + Tailwind CSS v4             |
+| Editor    | CodeMirror 6                            |
+| Graph     | React Flow + dagre                      |
+| State     | Zustand                                 |
+| Container | Docker + Compose                        |
+
+---
+
+## Known Limitations (Phase 1)
+
+- Micron preview is plain text — full terminal rendering comes in a later phase (micron-parser-js iframe)
+- `[[` link autocomplete not yet implemented (Phase 2)
+- Graph view is read-only; click a node to open it in the editor
+- No metrics (Phase 4)