From f9a47b51925b2758c19f3dc171b97bc201331830 Mon Sep 17 00:00:00 2001 From: Puma Date: Thu, 15 Oct 2026 11:40:43 -0700 Subject: [PATCH 1/2] docs: make the README clearer and easier to run --- README.md | 56 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 79ffb70b..5960f166 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,55 @@ # 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 +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 +``` + +The preparation script clones Pumas at the required sibling path 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). From 3e209934439f410dee039c7fcb1895db1295425b Mon Sep 17 00:00:00 2001 From: Puma Date: Wed, 21 Oct 2026 13:58:52 -0700 Subject: [PATCH 2/2] docs: establish the required writable Pumas checkout layout --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5960f166..8ccdde61 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ The current Tauri desktop workspace brings together a timeline, screenplay edito 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 @@ -23,7 +25,7 @@ EIDETIC_FETCH_PUMAS=1 scripts/prepare-pumas-dependency.sh ./launcher.sh --run ``` -The preparation script clones Pumas at the required sibling path if it is missing and verifies the expected revision. See [dependency setup](docs/dependency-governance.md#external-pumas-dependency) before using an existing checkout. +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.