<!--
KHAELOR
File: website/README.md
Description: The KHAELOR documentation site (www.khaelor.sh) — local dev and deployment notes.
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# KHAELOR website — www.khaelor.sh

The documentation and distribution site for the KHAELOR CLI. Static,
hand-written, zero build step, zero npm dependencies.

```
website/
├── public/            # the static site
│   ├── index.html     # landing page
│   ├── docs/*.html    # documentation pages
│   ├── styles.css     # single stylesheet (dark default + light variant)
│   ├── site.js        # theme toggle, nav highlighting, copy buttons
│   └── install.sh     # hosted installer (served at /install.sh)
├── artifacts/         # khaelor.tgz is dropped here at deploy time (gitignored payload)
├── server.mjs         # zero-dependency Node static server
└── CONTENT_TODO.md    # content items to re-verify once the CLI is final
```

## Run locally

```sh
node server.mjs              # http://localhost:8790
PORT=9000 node server.mjs    # any port
```

No install step. Requires only Node (>= 18 works for the server; the KHAELOR
CLI itself requires >= 22).

## Routes

| Route | Source | Caching |
|---|---|---|
| `/` and `/docs/*.html` | `public/` | `no-cache` (revalidate) |
| `/styles.css`, `/site.js`, images | `public/` | `max-age=86400` |
| `/install.sh` | `public/install.sh` | `no-store` (always fresh) |
| `/khaelor.tgz` | `artifacts/khaelor.tgz` | `no-store`; **503** with a plain message if the tarball is absent |
| `/health` | — | `{"ok":true,"version":"..."}` |

Access log goes to stdout (PM2 captures it). Binds `0.0.0.0`, port from
`PORT` (default 8790). Extensionless doc URLs resolve (`/docs/usage` →
`/docs/usage.html`). Path traversal is rejected.

## Deploy (Mac Studio node + ngrok)

1. **Pick the node and deploy the app** using the standard cluster protocol
   (`pick-node.py` + `deploy-app.sh`), e.g.:

   ```sh
   ~/Desktop/cluster-skill/deploy-app.sh \
     --src ~/Desktop/khaelor/website --node <alias> \
     --name khaelor-website --port 8790 --domain www.khaelor.sh
   ```

   That handles rsync, PM2 (`node server.mjs`), the ngrok tunnel
   (`--url=www.khaelor.sh`), the healthcheck (`/health`), and the
   deployment registry entry.

2. **Drop the CLI tarball.** Build it from the khaelor repo root
   (`npm run build && npm pack`), then place it on the node:

   ```sh
   scp khaelor-*.tgz <node>:~/apps/khaelor-website/artifacts/khaelor.tgz
   ```

   Until the tarball is present, `/khaelor.tgz` returns 503 and the
   installer fails cleanly at the `npm install -g` step — the rest of the
   site works.

3. **Update content:** re-run the rsync/deploy; pages are served `no-cache`
   so changes appear immediately.

## Editing content

Every page is plain semantic HTML sharing the same header/sidebar markup —
edit directly, no build. Keep the aesthetic contract: minimal, calm, dark
default, monospace accents, no banners. All source files carry the mandatory
KHAELOR author header (Absolute Rule #0). Before publishing content that
documents CLI behavior, check `CONTENT_TODO.md`.

---

*Author: Simon-Pierre Boucher · contact@spboucher.ai*