docs: clarify the README and getting started

README.md

@@ -1,31 +1,57 @@
 # Eidetic
 
-Eidetic is a local-first, AI-assisted scriptwriting workspace built as a Tauri desktop app with a Rust backend runtime and a Svelte projection UI. The product model is timeline-first: the backend owns project state, persistence, and realtime synchronization, while the frontend renders editing, timeline, relationship, and story-bible workflows over those contracts.
+Shape knowledge and context with clips you can move, resize and split.
 
-## Workspace Layout
+Eidetic is a local-first, clip-based knowledge graph. Clips place information and relationships in time, letting you shape what a selected moment draws on and what it produces. Scriptwriting is one application of that model.
 
-- `crates/core/` contains the domain model, timeline/story logic, screenplay helpers, and AI prompt/context assembly.
-- `crates/server/` owns backend services, persistence, event production, and AI backend adapters consumed by the Tauri desktop shell.
-- `src-tauri/` contains the desktop shell and Tauri command/event adapters over backend-owned services.
-- `ui/` contains the Svelte application, shared client contracts, state stores, and frontend verification tooling.
-- `docs/` holds product research and architecture/decomposition records.
+The current Tauri desktop workspace brings together a timeline, screenplay editor and story bible. Its Rust backend owns project state, persistence and context assembly.
 
-## Canonical Workflows
+![Eidetic screenplay editor and six-scene timeline](docs/reports/native-workflow-acceptance/screenplay-timeline.png)
+
+*Screenplay and timeline in the native app. [More views](docs/reports/native-workflow-acceptance/README.md).*
+
+## Run from source
+
+Use Node.js 24.12.0, Rust 1.92.0 and your platform's Tauri native prerequisites. The build also requires Eidetic's pinned sibling Pumas checkout:
 
 ```bash
+mkdir -p "$HOME/eidetic-workspace/creative-media"
+cd "$HOME/eidetic-workspace/creative-media"
+git clone https://github.com/MrScripty/Eidetic.git
+cd Eidetic
+EIDETIC_FETCH_PUMAS=1 scripts/prepare-pumas-dependency.sh
 ./launcher.sh --install
 ./launcher.sh --build
-./launcher.sh --release-smoke
 ./launcher.sh --run
+```
+
+This layout puts Eidetic at `eidetic-workspace/creative-media/Eidetic` and Pumas at `eidetic-workspace/ai-systems/Pumas-Library`, matching Cargo's required relative path. The preparation script clones Pumas there if it is missing and verifies the expected revision. See [dependency setup](docs/dependency-governance.md#external-pumas-dependency) before using an existing checkout.
+
+The launcher installs frontend dependencies and Git hooks. It keeps application state under `.launcher-state/` by default, and `--run` starts the frontend server for the desktop webview. It does not start the old browser application.
+
+For a release binary:
+
+```bash
+./launcher.sh --build-release
+./launcher.sh --release-smoke
+./launcher.sh --run-release
+```
+
+The smoke checks backend startup without opening a window. It requires the release build above.
+
+## Current scope
+
+Local project editing, screenplay and story-bible saves, and timeline placement have native acceptance evidence. Real-model generation, embedding retrieval and model lifecycle remain separate integration work.
+
+The main editor timeline remains usable, but the separate native graph and timeline renderers cannot both be started in one process. Restart the app before switching native renderer owners. See [the renderer limitation](docs/reports/native-workflow-acceptance/README.md#native-renderer-limit).
+
+## Develop
+
+```bash
 ./launcher.sh --test
 ```
 
-The launcher isolates state by default under `.launcher-state/`. Set `EIDETIC_LAUNCHER_ISOLATE_STATE=0` only when intentionally using host state directories.
-`--run` starts the Vite dev server for the Tauri webview and opens the desktop app; it no longer starts the legacy Axum browser server.
-`--release-smoke` runs the release desktop binary with `--smoke`, initializes the backend runtime, reports JSON health, and exits without opening a window.
+This runs Rust tests and frontend lint, formatting, type checks and tests. See the [documentation index](docs/README.md), [frontend scripts](ui/package.json) and [decomposition baseline](docs/adr/ADR-001-decomposition-baseline.md).
 
-## Verification
+[MIT License](LICENSE).
 
-- `./launcher.sh --test` is the canonical repo verification command.
-- The frontend also exposes `npm run lint`, `npm run format:check`, `npm run check`, and `npm run test` from [`ui/package.json`](/media/jeremy/OrangeCream/Linux%20Software/repos/owned/creative-media/Eidetic/ui/package.json).
-- Oversized-module decomposition posture is recorded in [`ADR-001`](/media/jeremy/OrangeCream/Linux%20Software/repos/owned/creative-media/Eidetic/docs/adr/ADR-001-decomposition-baseline.md).