Implement deterministic website build engine

README.md

@@ -1,20 +1,56 @@
-<div align="center">
-<img width="1200" height="475" alt="GHBanner" src="https://ai.google.dev/static/site-assets/images/share-ais-513315318.png" />
-</div>
+# Labyricorn Website Engine Control Plane
 
-# Run and deploy your AI Studio app
+A React control plane and Express backend for discovering Git-hosted Markdown, validating canonical site configuration, and producing deterministic static website releases.
 
-This contains everything you need to run your app locally.
+## Engine capabilities
 
-View your app in AI Studio: https://ai.studio/apps/941c018f-56b5-4bf6-afbf-444c3f0a351f
+The build engine now:
 
-## Run Locally
+- validates routes, route collisions, content state, raw-HTML policy, and media references;
+- renders published content and navigation indexes into static HTML;
+- escapes source HTML and renders a safe CommonMark-style subset;
+- emits deterministic `build-manifest.json` and `checksums.json` files;
+- calculates an artifact checksum from generated file checksums;
+- writes releases atomically beneath the configured build root;
+- activates releases through an atomic `current` symlink/junction;
+- survives process restarts without reusing existing build numbers; and
+- serves the active generated release through the live-preview endpoint.
 
-**Prerequisites:**  Node.js
+## Development
 
+Requires Node.js 22 or later.
 
-1. Install dependencies:
-   `npm install`
-2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
-3. Run the app:
-   `npm run dev`
+```bash
+npm install
+npm test
+npm run lint
+npm run dev
+```
+
+Create a production bundle with:
+
+```bash
+npm run build
+npm start
+```
+
+The control plane listens on port `3000`.
+
+## Build artifacts
+
+By default, releases are written to the platform temporary directory under `labyricorn-builds/`. Set `LABYRICORN_BUILD_ROOT` to use a persistent release directory in production.
+
+Each successful release contains:
+
+- generated route directories with `index.html`;
+- `404.html`;
+- `build-manifest.json`; and
+- `checksums.json`.
+
+Validation failures produce a failed build record but never publish a partial release directory.
+
+## Current boundaries
+
+- The built-in renderer is used until repository-provided theme templates are implemented.
+- Git source synchronization supports HTTP(S), SSH-style Git URLs, and local paths; other source types remain unavailable.
+- Remote rsync deployment is still represented by the existing control-plane simulation and must not be treated as a completed production deploy path.