fix: improvements

ARCHITECTURE.md

@@ -0,0 +1,216 @@
+# Architecture Overview
+
+## 1. Executive Summary
+
+Zui is a node-based visual editor for composing configs, templates, variables, and AI-generated content. The frontend is a React 18 SPA backed by a thin Express API for AI agent calls. All graph data is persisted in `localStorage`; the backend is stateless.
+
+---
+
+## 2. Technology Stack
+
+| Layer | Technology |
+| --- | --- |
+| Frontend framework | React 18, TypeScript (strict), Vite 7 |
+| Graph canvas | `@xyflow/react` v12 (React Flow) |
+| State management | Zustand 5 (command/reducer pattern) |
+| Styling | Tailwind CSS + Shadcn UI (`@radix-ui/*`) |
+| Rich text | BlockNote 0.36 with custom blocks |
+| Templating | Nunjucks |
+| Graph traversal | `graphology` + `graphology-traversal` |
+| Routing | React Router v6 |
+| Backend | Node.js 20+, TypeScript, Express 4 |
+| AI SDK | Vercel AI SDK v4 + `@ai-sdk/openai` |
+| Testing | Vitest, React Testing Library |
+
+---
+
+## 3. Project Structure
+
+```text
+frontend/src/
+├── main.tsx                    # Entry: registers node types & config types, mounts app
+├── app/
+│   ├── canvas/                 # CanvasPage, canvasStore (Zustand), canvasStore.test.ts
+│   ├── kosmos/                 # KosmosPage, sidebar, AI settings, KosmosContext
+│   └── recollections/
+│       ├── RecollectionsPage   # Workspace list
+│       ├── RecollectionLayout  # Shared layout (sidebar + outlet)
+│       ├── flux/               # Flux view (graph canvas)
+│       ├── logos/              # Logos view (BlockNote rich text)
+│       └── katalogos/          # Katalogos view (artifact gallery)
+├── components/
+│   ├── graph/                  # AnimatedEdge, BaseNode, handles, keyboard shortcuts
+│   ├── nodes/                  # One folder per node type
+│   └── ui/                     # Shadcn primitives
+├── hooks/                      # useGraphStateWithHistory, useResizeHeight, …
+└── lib/
+    └── graph/
+        ├── nodeRegistry.ts     # Mutable plugin registry
+        ├── registerBuiltinNodes.tsx
+        ├── nodeTypeBuilder.ts  # Fluent builder for node descriptors
+        ├── configTypes.ts      # Output type registry (plantuml, markdown, wireframe)
+        ├── rendering.ts        # 3-step rendering pipeline contract
+        ├── state.ts            # Graph state types
+        └── canvasStore/        # Reducer + selectors
+
+backend/src/
+├── index.ts                    # Express app, CORS, routes, error handler
+├── routes/agentRoutes.ts       # POST /api/agent, POST /api/agent/stream
+├── services/agentService.ts    # LLM call logic (Vercel AI SDK)
+├── repositories/cacheRepository.ts
+├── models/index.ts
+└── middleware/rateLimiter.ts
+```
+
+---
+
+## 4. Key Architectural Patterns
+
+### 4.1 Command / Reducer Store (canvasStore)
+
+The Zustand canvas store uses a pure reducer (`canvasStoreReducer`) with a discriminated union of `CanvasCommand` types. All mutations go through `dispatch(command)`. In dev mode every command is logged to the console.
+
+The store has three slices:
+
+- **`graph`** — nodes and edges (the React Flow state)
+- **`path`** — trigger pulse for edge animation
+- **`ui`** — renaming state, fullscreen node, pending connection
+
+### 4.2 Delta-based Undo / Redo
+
+`useGraphStateWithHistory` computes *inverse deltas* (only the nodes/edges that changed) rather than snapshotting the full graph. Maximum 100 history entries. Drag operations commit a pre-drag snapshot on `onNodeDragStop`.
+
+### 4.3 Node Plugin Registry
+
+Node types are registered via a mutable registry in `nodeRegistry.ts`. The built-ins are registered at app init from `registerBuiltinNodes.tsx`. Adding a new node type requires:
+
+1. Implement a React component for the node.
+2. Create a descriptor using `NodeTypeBuilder`.
+3. Call `registerNodeType(descriptor)` — no edits to core code.
+
+### 4.4 Fluent Builder for Node Descriptors
+
+`NodeTypeBuilder` provides a type-safe method-chaining API (`idPrefix`, `withInputOutput`, `classification`, `allowedSourceTypes`, `help`, `menu`, `withFullscreen`, `sourceRenderingLogic`, …). Required fields are validated at `.build()`.
+
+### 4.5 Three-Step Rendering Pipeline
+
+Defined as an explicit contract in `rendering.ts`:
+
+1. **Resolve** — source node (Config/Agent) produces `{ resolved, outputTypeId, reasoning? }`
+2. **Render** — output type handler converts the resolved string (PlantUML → Kroki SVG, Markdown → HTML, Wireframe → SVG)
+3. **Display** — the Rendering node shows an image viewport or scrollable HTML
+
+### 4.6 Node Classification System
+
+Four metaphorical classes drive the create menu grouping:
+
+| Class | Node type | Metaphor |
+| --- | --- | --- |
+| `psyche` | Variable | source / input |
+| `physis` | Data (CSV) | physical data |
+| `pneuma` | Config / Render | transformation |
+| `archon` | Agent | AI / LLM |
+
+### 4.7 Recollections (Workspaces)
+
+Each workspace (recollection) is stored in `localStorage`:
+
+| Key | Content |
+| --- | --- |
+| `zui_platform_recollections` | Metadata index (id, name, icon, timestamps) |
+| `zui_graph_<id>` | Flux graph (nodes + edges) |
+| `zui_logos_<id>` | BlockNote rich text document |
+| `zui_render_cache_<id>` | Rendered artifact cache |
+
+Legacy key prefix `emanations` is migrated to `recollections` on first load.
+
+### 4.8 User-configurable AI Connection
+
+`KosmosContext` persists `aiConnection` (provider, baseURL, model, apiKey) in `localStorage` under `zui_ai_connection`. The Agent node forwards this to the backend with each request, so users can switch between OpenAI and local LLMs (LM Studio, Ollama) from the UI without env variable changes.
+
+### 4.9 Diagram Rendering via Kroki
+
+PlantUML diagrams are rendered by proxying to `https://kroki.io` via `/api/kroki/plantuml/svg`. This proxy is configured in both the Vite dev server and Nginx production config. Timeout: 15 seconds.
+
+---
+
+## 5. Data Flow
+
+```text
+User interaction
+  → dispatch(CanvasCommand)              [canvasStore reducer]
+  → Zustand state update                 [graph / path / ui slices]
+  → React re-render                      [React Flow nodes/edges]
+
+Rendering node triggered
+  → Resolve source node                  [Config/Agent → resolved string]
+  → Render output type                   [plantuml/markdown/wireframe]
+    → Kroki proxy  (PlantUML)            [GET /api/kroki/plantuml/svg]
+    → Agent backend  (AI)               [POST /api/agent or /api/agent/stream]
+  → Display artifact                     [image / HTML / SVG viewport]
+
+Agent node (streaming)
+  → POST /api/agent/stream               [Express → agentService]
+  → Vercel AI SDK streams SSE            [backend → frontend]
+  → useStreamingContent hook consumes    [updates node data]
+```
+
+---
+
+## 6. Backend Architecture
+
+The backend is intentionally thin and stateless. It has three responsibilities:
+
+1. **Proxy AI calls** — forwards prompts to the configured LLM (OpenAI or OpenAI-compatible).
+2. **Stream responses** — `POST /api/agent/stream` uses `pipeTextStreamToResponse` from the Vercel AI SDK.
+3. **Health check** — `GET /health` for Docker/orchestration readiness probes.
+
+The `InMemoryCache` and `rateLimiter` middleware are implemented but not yet wired into the agent routes.
+
+---
+
+## 7. Contribution Workflow
+
+1. Fork the repository and clone locally.
+2. Install dependencies: `cd frontend && npm install` and `cd backend && npm install`.
+3. Run the dev servers (see README).
+4. Create a feature branch: `git checkout -b feat/your-feature`.
+5. Follow the Coding Standards (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+6. Submit a Pull Request with a descriptive title, linked issue(s), updated tests, and documentation changes if relevant.
+
+### PR Review Checklist
+
+- [ ] Readability: clear naming, minimal nesting
+- [ ] TypeScript: no `any`, strict types throughout
+- [ ] Performance: no unnecessary re-renders, proper memoization
+- [ ] Accessibility: semantic HTML, ARIA attributes where needed
+- [ ] Security: no hardcoded secrets, input validated at boundaries
+
+---
+
+## 8. Coding Standards
+
+- **TypeScript**: strict mode (`strict`, `noImplicitAny`, `noUnusedLocals`).
+- **Naming**: PascalCase for components, camelCase for functions/variables, UPPER_SNAKE_CASE for constants.
+- **File structure**: domain-grouped under `src/app/<domain>/` and `src/components/<category>/`.
+- **Formatting**: Prettier via `frontend/prettier.config.cjs`; line length ≤ 120.
+- **Comments**: JSDoc for public APIs; inline only where logic is non-obvious.
+
+---
+
+## 9. Quick Reference for AI Agents
+
+| Topic | Location |
+| --- | --- |
+| Entry point | `frontend/src/main.tsx` |
+| Canvas store | `frontend/src/app/canvas/canvasStore.ts` |
+| Store reducer | `frontend/src/app/canvas/canvasStoreReducer.ts` |
+| Node registry | `frontend/src/lib/graph/nodeRegistry.ts` |
+| Node builder | `frontend/src/lib/graph/nodeTypeBuilder.ts` |
+| Rendering pipeline | `frontend/src/lib/graph/rendering.ts` |
+| Built-in node registration | `frontend/src/lib/graph/registerBuiltinNodes.tsx` |
+| AI settings context | `frontend/src/app/kosmos/KosmosContext.tsx` |
+| Backend entry | `backend/src/index.ts` |
+| Agent service | `backend/src/services/agentService.ts` |
+
+*This document is a living reference; update it when architectural decisions change.*

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contribution Guide
+
+## 1. Coding Standards
+
+- Use TypeScript with `strict` mode enabled; no `any` types.
+- Import order: core libs → third-party → project aliases (`@/`) → relative.
+- Naming: PascalCase for components, camelCase for functions/variables, UPPER_SNAKE_CASE for constants.
+- Add JSDoc comments for all public APIs and exported types.
+- Line length ≤ 120 characters; use Prettier for formatting (`frontend/prettier.config.cjs`).
+- Run `npm run lint` and fix all warnings before opening a PR.
+
+## 2. Branch Workflow
+
+- Create a feature branch: `git checkout -b feat/<short-description>`
+- Keep branches up to date with `main` via `git rebase`.
+- Submit a Pull Request with a clear title and description.
+- Ensure the PR passes CI (tests, lint, type-check).
+- Address review comments promptly.
+
+## 3. Running Tests
+
+```bash
+# Install dependencies
+cd frontend && npm install
+
+# Run tests in watch mode
+npm run test
+
+# Run tests once (CI)
+npm run test:run
+
+# Type-check
+npx tsc --noEmit
+```
+
+## 4. Making Your First Contribution
+
+1. Pick a beginner-friendly issue labeled `good first issue`.
+2. Read [ARCHITECTURE.md](ARCHITECTURE.md) to understand the relevant module.
+3. Make a small, focused change; avoid refactoring unrelated code.
+4. Run the relevant tests and confirm they pass.
+5. Commit and push, then open a PR with a clear description of what and why.
+
+## 5. Where to Extend
+
+| Goal | Where to look |
+| --- | --- |
+| Add a new node type | `src/lib/graph/nodeTypeBuilder.ts` + `registerBuiltinNodes.tsx` |
+| Add a new output/render type | `src/lib/graph/configTypes.ts` + `rendering.ts` |
+| Change canvas state shape | `src/app/canvas/canvasStore.ts` + reducer + tests |
+| Add a new Logos block | `src/app/recollections/logos/logosSchema.ts` |
+| Add a backend endpoint | `backend/src/routes/` → `services/` → `index.ts` |
+
+## 6. Useful Links
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — architecture overview, key patterns, module map
+- [PERFORMANCE_IMPROVEMENTS.md](PERFORMANCE_IMPROVEMENTS.md) — bottleneck analysis and improvement plan
+- [docs/CODE_REVIEW_CHECKLIST.md](docs/CODE_REVIEW_CHECKLIST.md) — PR review checklist
+- [docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md](docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md) — node plugin system design
+
+*Thank you for contributing!*

PERFORMANCE_IMPROVEMENTS.md

@@ -0,0 +1,108 @@
+# Performance Improvements Plan
+
+## 1. Current State
+
+The core rendering and state management architecture is already well-structured for performance:
+
+- **Command/reducer store** — all mutations go through a pure reducer; individual selectors can prevent unnecessary re-renders.
+- **Delta-based undo/redo** — only diffs are stored, not full graph snapshots (max 100 entries).
+- **Plugin node registry** — node types are loaded once at app init, not dynamically on each render.
+- **Streaming AI responses** — `POST /api/agent/stream` uses SSE so the UI updates incrementally.
+
+The sections below identify remaining bottlenecks and concrete next steps.
+
+---
+
+## 2. Known Bottlenecks
+
+| # | Issue | Location | Impact | Root Cause |
+| --- | --- | --- | --- | --- |
+| 1 | Unguarded re-renders on canvas | `CanvasPage.tsx` | Frame drops on large graphs | Components not subscribed to granular store slices |
+| 2 | Nunjucks template resolution on every render | `rendering.ts` resolve step | Slow Config node updates | No memoization of template output keyed to input hash |
+| 3 | Kroki SVG requests not deduplicated | `rendering.ts` render step | Redundant network calls | No in-flight request deduplication or client-side cache |
+| 4 | Sidebar tree renders all items | `KosmosPage` recollection tree | Scrolling lag with many workspaces | No list virtualization |
+| 5 | Backend cache not wired to agent routes | `agentRoutes.ts` | Repeated identical LLM calls | `InMemoryCache` and `rateLimiter` exist but are unused |
+| 6 | Full graph serialized to localStorage on every change | `useGraphStateWithHistory` | Storage I/O on every keypress | No debounce on the persistence write |
+| 7 | Initial bundle size | Vite build | Slow first load | Heavy deps (BlockNote, React Flow, Nunjucks) loaded eagerly |
+
+---
+
+## 3. Recommended Improvements
+
+### 3.1 Granular Store Subscriptions
+
+Zustand supports slice-level subscriptions. Node components should select only their own data slice:
+
+```ts
+// Instead of subscribing to the entire graph:
+const node = useCanvasStore(s => s.graph.nodes.find(n => n.id === id))
+```
+
+This prevents all nodes from re-rendering when a single node changes.
+
+### 3.2 Memoize Template Resolution
+
+Cache the Nunjucks resolution output keyed to a hash of the template source plus variable inputs. Invalidate only when those inputs change:
+
+```ts
+const resolved = useMemo(
+  () => resolveTemplate(template, variables),
+  [templateHash, variableHash]
+)
+```
+
+### 3.3 Deduplicate Kroki Requests
+
+Add a simple in-flight map in the render step: if a request for the same PlantUML source is already pending, reuse its promise. Cache successful responses keyed to the source string with a short TTL (e.g. 5 minutes).
+
+### 3.4 Wire Backend Cache and Rate Limiter
+
+`InMemoryCache` and `rateLimiter` middleware are implemented in `backend/src/`. Connect them to `agentRoutes.ts`:
+
+1. Add cache lookup before calling the AI service.
+2. Store the response on cache miss.
+3. Apply rate limiting per IP to prevent abuse.
+
+### 3.5 Debounce localStorage Writes
+
+Wrap the graph persistence call in a debounce (e.g., 300 ms) to avoid a write on every keystroke or node drag. The delta-based history already computes minimal diffs; the bottleneck is the frequency of writes.
+
+### 3.6 Virtualize the Sidebar Tree
+
+Integrate `react-arborist` (already installed) with virtualization enabled for the recollection sidebar when item count exceeds a threshold (~50).
+
+### 3.7 Code Split Heavy Routes
+
+Add lazy imports for the three heavy route components so the initial bundle only loads what the user navigates to:
+
+```ts
+const FluxRoute    = lazy(() => import('./app/recollections/flux/FluxRoute'))
+const LogosPage    = lazy(() => import('./app/recollections/logos/LogosPage'))
+const KatalogosPage = lazy(() => import('./app/recollections/katalogos/KatalogosPage'))
+```
+
+### 3.8 Enable Brotli Compression in Nginx
+
+Add brotli/gzip compression to `frontend/nginx.conf` for JS, CSS, and SVG assets. This can cut transfer size by 60–70% for the JS bundle.
+
+---
+
+## 4. Success Metrics
+
+| Metric | Current (estimated) | Target |
+| --- | --- | --- |
+| Frame time on 50-node canvas | ~16 ms | < 10 ms |
+| Initial JS bundle (gzipped) | ~800 KB | < 600 KB |
+| Repeated identical LLM calls | uncached | 0 network round-trips |
+| localStorage write frequency | every change | debounced 300 ms |
+
+---
+
+## 5. Contribution Path
+
+1. Read [ARCHITECTURE.md](ARCHITECTURE.md) to understand the module you're optimizing.
+2. Pick one item from section 2.
+3. Add a Vitest benchmark (`performance.now()` before/after) alongside your change.
+4. Submit a PR with the benchmark results in the description and update this file's "Current" column.
+
+*This plan is a living document; update the metrics table when improvements land.*

README.md

@@ -1,42 +1,61 @@
 # Zui
 
-Node-based editor (React Flow) for configs, variables, and rendering (PlantUML, Markdown, etc.). Optional Node.js backend API for demos or future features (e.g. todos CRUD).
+Node-based visual editor (React Flow) for composing configs, variables, templates, and AI-generated content. Three views per workspace: **Flux** (graph canvas), **Logos** (rich text), and **Katalogos** (artifact gallery). Optional Node.js backend for AI agent calls.
 
 ## Project layout
 
-```
-my-app/
-├── frontend/           # React app (Vite, TypeScript)
-│   ├── Dockerfile      # Multi-stage for prod (build → Nginx)
-│   ├── Dockerfile.dev  # Dev with hot reload
+```text
+zui/
+├── frontend/               # React SPA (Vite, TypeScript)
 │   ├── src/
-│   ├── public/
+│   │   ├── main.tsx            # Entry point: registers node/config types, mounts React
+│   │   ├── app/
+│   │   │   ├── canvas/         # Core graph editor (React Flow + Zustand)
+│   │   │   ├── kosmos/         # Platform shell: sidebar, recollection list, AI settings
+│   │   │   └── recollections/  # Logos (rich text), Flux (canvas), Katalogos (gallery)
+│   │   ├── components/
+│   │   │   ├── graph/          # AnimatedEdge, BaseNode, handles, keyboard shortcuts
+│   │   │   ├── nodes/          # One folder per node type (agent, config, variable, …)
+│   │   │   └── ui/             # Shadcn-based primitives
+│   │   ├── hooks/              # Custom React hooks
+│   │   └── lib/
+│   │       └── graph/          # Registry, types, state, rendering pipeline, Nunjucks utils
+│   ├── Dockerfile              # Multi-stage: Vite build → Nginx
+│   ├── Dockerfile.dev          # Dev with hot reload
 │   ├── nginx.conf
 │   └── package.json
-├── backend/            # Node.js/Express API
-│   ├── Dockerfile
+├── backend/                # Node.js/Express API
 │   ├── src/
-│   │   └── index.js
+│   │   ├── index.ts            # Express entry: registers routes, CORS, error handler
+│   │   ├── routes/agentRoutes.ts
+│   │   ├── services/agentService.ts
+│   │   ├── repositories/cacheRepository.ts
+│   │   ├── models/index.ts
+│   │   └── middleware/rateLimiter.ts
 │   └── package.json
+├── docs/
+│   ├── ARCHITECTURE.md
+│   ├── PERFORMANCE.md
+│   ├── NODE_TYPE_EXTENSIBILITY_PROPOSAL.md
+│   └── CODE_REVIEW_CHECKLIST.md
 ├── docker-compose.yml
-├── .dockerignore
 └── .gitignore
 ```
 
-Ignored by git: `node_modules`, `dist`, `.env`, `.env.*` (see [.gitignore](.gitignore)). Local Docker overrides: `docker-compose.override.yml` (optional, not committed).
+Ignored by git: `node_modules`, `dist`, `.env`, `.env.*`. Local Docker overrides: `docker-compose.override.yml` (optional, not committed).
 
 ---
 
 ## Run locally (dev)
 
-**Frontend only:**
+**Frontend only** (no AI agent):
 
 ```bash
 cd frontend && npm install && npm run dev
 # → http://localhost:3000
 ```
 
-**Frontend + backend** (for AI agent and health):
+**Frontend + backend** (for AI agent and health check):
 
 ```bash
 # Terminal 1 – backend
@@ -45,7 +64,7 @@ cd backend && npm install && npm run dev
 
 # Terminal 2 – frontend
 cd frontend && npm install && npm run dev
-# → http://localhost:3000 (Vite proxies /api/* and /health to backend)
+# → http://localhost:3000  (Vite proxies /api/* and /health to backend)
 ```
 
 ---
@@ -56,70 +75,79 @@ cd frontend && npm install && npm run dev
 docker compose up --build
 ```
 
-- **Frontend**: http://localhost:3000 (Nginx; `/api/*` proxied to backend).
-- **Backend**: http://localhost:8080 (Express).
+- **Frontend**: <http://localhost:3000> (Nginx; `/api/*` proxied to backend).
+- **Backend**: <http://localhost:8080> (Express).
 
 Environment variables (backend service):
 
-| Variable     | Default                    | Description |
-|-------------|----------------------------|-------------|
-| `PORT`      | `8080`                     | Backend listen port. |
-| `CORS_ORIGIN` | `http://localhost:3000`  | Allowed origin for CORS. |
+| Variable         | Default                   | Description                                |
+|------------------|---------------------------|--------------------------------------------|
+| `PORT`           | `8080`                    | Backend listen port.                       |
+| `CORS_ORIGIN`    | `http://localhost:3000`   | Allowed origin for CORS.                   |
+| `AI_BASE_URL`    | *(unset)*                 | OpenAI-compatible base URL (local LLMs).   |
+| `AI_MODEL`       | `gpt-4o-mini`             | Model ID for the AI agent.                 |
+| `OPENAI_API_KEY` | *(unset)*                 | Required when using OpenAI directly.       |
 
-For self-hosting (e.g. Tailscale/HTTPS): set `CORS_ORIGIN` to your frontend URL; put Caddy or Nginx in front for TLS if needed.
-
-**Dev with Docker (frontend hot reload):** use `frontend/Dockerfile.dev` and mount `./frontend` as a volume, or run `cd frontend && npm run dev` locally.
+For self-hosting (e.g., Tailscale/HTTPS): set `CORS_ORIGIN` to your frontend URL and put Caddy or Nginx in front for TLS.
 
 ---
 
 ## Scripts
 
-| Command | Description |
-|--------|-------------|
-| `cd frontend && npm run dev` | Vite dev server. |
-| `cd frontend && npm run build` | Build frontend for production. |
-| `cd frontend && npm run preview` | Preview production build. |
-| `cd backend && npm run dev` | Backend with `--watch`. |
-| `cd backend && npm start` | Backend production run. |
-| `docker compose up --build` | Run frontend + backend in Docker. |
+| Command                              | Description                            |
+|--------------------------------------|----------------------------------------|
+| `cd frontend && npm run dev`         | Vite dev server (port 3000).           |
+| `cd frontend && npm run build`       | Build frontend for production.         |
+| `cd frontend && npm run preview`     | Preview production build.              |
+| `cd frontend && npm run test`        | Run tests in watch mode (Vitest).      |
+| `cd frontend && npm run test:run`    | Run tests once (CI).                   |
+| `cd backend && npm run dev`          | Backend with `tsx --watch`.            |
+| `cd backend && npm start`            | Backend production run.                |
+| `docker compose up --build`          | Run full stack in Docker.              |
 
 ---
 
-## Backend API (no DB)
+## Backend API
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET    | `/health`        | Health check (e.g. for Docker). |
-| POST   | `/api/agent`     | Run AI agent; body `{ "prompt", "context?", "contextNodes?" }` → `{ "markdown" }`. |
+| Method | Path                  | Body / Response                                                                 |
+|--------|-----------------------|---------------------------------------------------------------------------------|
+| GET    | `/health`             | `{ ok: true, timestamp: number }` — health check for Docker/orchestration.      |
+| POST   | `/api/agent`          | Body `{ prompt, context?, contextNodes? }` → `{ markdown }` (one-shot).         |
+| POST   | `/api/agent/stream`   | Body `{ prompt, context?, contextNodes? }` → SSE text stream (streaming).       |
 
 ---
 
 ## Agent node (local LLM or OpenAI)
 
-The **Agent** node uses an OpenAI-compatible API. You can use:
+AI connection settings are configured **directly in the UI** — open the sidebar and go to **AI Settings**. You can switch between providers without restarting the server.
 
-**1. Local LLM (e.g. LM Studio)**
+The backend reads its AI config from environment variables as a fallback:
 
-1. Install [LM Studio](https://lmstudio.ai/) and load a model.
-2. Start the local server: in LM Studio open the **Developer** tab and run the **Local Server** (default: `http://localhost:1234`).
-3. In the project root or `backend/`, set:
+### Local LLM (e.g. LM Studio)
+
+1. Install [LM Studio](https://lmstudio.ai/), load a model, and start the local server (default: `http://localhost:1234`).
+2. Set env vars (backend):
 
    ```bash
    export AI_BASE_URL=http://localhost:1234/v1
-   # Optional: set to the model name shown in LM Studio (e.g. the loaded model id). Default is "local-model".
-   export AI_MODEL=your-model-name
+   export AI_MODEL=your-model-name   # optional; matches the name shown in LM Studio
    ```
 
-4. Start the backend (`cd backend && npm run dev`). The Agent node will use your local model.
+### OpenAI
 
-**2. OpenAI**
+```bash
+export OPENAI_API_KEY=sk-...
+export AI_MODEL=gpt-4o-mini   # optional; defaults to gpt-4o-mini
+```
 
-Set `OPENAI_API_KEY` to your API key. The backend will use `gpt-4o-mini` unless you set `AI_MODEL`.
+---
 
-**Env summary (backend)**
+## Contribute
 
-| Variable | When to use | Description |
-|----------|--------------|-------------|
-| `AI_BASE_URL` | Local LLM (LM Studio, Ollama, etc.) | OpenAI-compatible base URL, e.g. `http://localhost:1234/v1`. |
-| `AI_MODEL` | Optional | Model id (for local: use the name shown in LM Studio; for OpenAI: e.g. `gpt-4o-mini`). |
-| `OPENAI_API_KEY` | OpenAI only | Your OpenAI API key. Not required when using `AI_BASE_URL` only. |
+- [ARCHITECTURE.md](ARCHITECTURE.md) — architecture overview, key patterns, module map
+- [CONTRIBUTING.md](CONTRIBUTING.md) — coding standards, branch workflow, test commands
+- [PERFORMANCE_IMPROVEMENTS.md](PERFORMANCE_IMPROVEMENTS.md) — bottleneck analysis and improvement plan
+- [docs/CODE_REVIEW_CHECKLIST.md](docs/CODE_REVIEW_CHECKLIST.md) — PR review checklist
+- [docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md](docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md) — node plugin system design
+
+*Thank you for contributing!*

backend/package-lock.json

@@ -13,6 +13,13 @@
         "cors": "^2.8.5",
         "express": "^4.21.0"
       },
+      "devDependencies": {
+        "@types/cors": "^2.8.17",
+        "@types/express": "^5.0.0",
+        "@types/node": "^22.0.0",
+        "tsx": "^4.0.0",
+        "typescript": "^5.0.0"
+      },
       "engines": {
         "node": ">=20"
       }
@@ -103,6 +110,448 @@
         "zod": "^3.23.8"
       }
     },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.4.tgz",
+      "integrity": "sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.4.tgz",
+      "integrity": "sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.4.tgz",
+      "integrity": "sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.4.tgz",
+      "integrity": "sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.4.tgz",
+      "integrity": "sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.4.tgz",
+      "integrity": "sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.4.tgz",
+      "integrity": "sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.4.tgz",
+      "integrity": "sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.4.tgz",
+      "integrity": "sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.4.tgz",
+      "integrity": "sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.4.tgz",
+      "integrity": "sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.4.tgz",
+      "integrity": "sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.4.tgz",
+      "integrity": "sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.4.tgz",
+      "integrity": "sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.4.tgz",
+      "integrity": "sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.4.tgz",
+      "integrity": "sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.4.tgz",
+      "integrity": "sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.4.tgz",
+      "integrity": "sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.4.tgz",
+      "integrity": "sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.4.tgz",
+      "integrity": "sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.4.tgz",
+      "integrity": "sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.4.tgz",
+      "integrity": "sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.4.tgz",
+      "integrity": "sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.4.tgz",
+      "integrity": "sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@opentelemetry/api": {
       "version": "1.9.0",
       "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz",
@@ -112,12 +561,120 @@
         "node": ">=8.0.0"
       }
     },
+    "node_modules/@types/body-parser": {
+      "version": "1.19.6",
+      "resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.6.tgz",
+      "integrity": "sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/connect": "*",
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/connect": {
+      "version": "3.4.38",
+      "resolved": "https://registry.npmjs.org/@types/connect/-/connect-3.4.38.tgz",
+      "integrity": "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/cors": {
+      "version": "2.8.19",
+      "resolved": "https://registry.npmjs.org/@types/cors/-/cors-2.8.19.tgz",
+      "integrity": "sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/diff-match-patch": {
       "version": "1.0.36",
       "resolved": "https://registry.npmjs.org/@types/diff-match-patch/-/diff-match-patch-1.0.36.tgz",
       "integrity": "sha512-xFdR6tkm0MWvBfO8xXCSsinYxHcqkQUlcHeSpMC2ukzOb6lwQAfDmW+Qt0AvlGd8HpsS28qKsB+oPeJn9I39jg==",
       "license": "MIT"
     },
+    "node_modules/@types/express": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@types/express/-/express-5.0.6.tgz",
+      "integrity": "sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/body-parser": "*",
+        "@types/express-serve-static-core": "^5.0.0",
+        "@types/serve-static": "^2"
+      }
+    },
+    "node_modules/@types/express-serve-static-core": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-5.1.1.tgz",
+      "integrity": "sha512-v4zIMr/cX7/d2BpAEX3KNKL/JrT1s43s96lLvvdTmza1oEvDudCqK9aF/djc/SWgy8Yh0h30TZx5VpzqFCxk5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "@types/qs": "*",
+        "@types/range-parser": "*",
+        "@types/send": "*"
+      }
+    },
+    "node_modules/@types/http-errors": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz",
+      "integrity": "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "22.19.15",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.15.tgz",
+      "integrity": "sha512-F0R/h2+dsy5wJAUe3tAU6oqa2qbWY5TpNfL/RGmo1y38hiyO1w3x2jPtt76wmuaJI4DQnOBu21cNXQ2STIUUWg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/@types/qs": {
+      "version": "6.15.0",
+      "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.0.tgz",
+      "integrity": "sha512-JawvT8iBVWpzTrz3EGw9BTQFg3BQNmwERdKE22vlTxawwtbyUSlMppvZYKLZzB5zgACXdXxbD3m1bXaMqP/9ow==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/range-parser": {
+      "version": "1.2.7",
+      "resolved": "https://registry.npmjs.org/@types/range-parser/-/range-parser-1.2.7.tgz",
+      "integrity": "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/send": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@types/send/-/send-1.2.1.tgz",
+      "integrity": "sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/serve-static": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@types/serve-static/-/serve-static-2.2.0.tgz",
+      "integrity": "sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/http-errors": "*",
+        "@types/node": "*"
+      }
+    },
     "node_modules/accepts": {
       "version": "1.3.8",
       "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz",
@@ -392,6 +949,48 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/esbuild": {
+      "version": "0.27.4",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.4.tgz",
+      "integrity": "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.4",
+        "@esbuild/android-arm": "0.27.4",
+        "@esbuild/android-arm64": "0.27.4",
+        "@esbuild/android-x64": "0.27.4",
+        "@esbuild/darwin-arm64": "0.27.4",
+        "@esbuild/darwin-x64": "0.27.4",
+        "@esbuild/freebsd-arm64": "0.27.4",
+        "@esbuild/freebsd-x64": "0.27.4",
+        "@esbuild/linux-arm": "0.27.4",
+        "@esbuild/linux-arm64": "0.27.4",
+        "@esbuild/linux-ia32": "0.27.4",
+        "@esbuild/linux-loong64": "0.27.4",
+        "@esbuild/linux-mips64el": "0.27.4",
+        "@esbuild/linux-ppc64": "0.27.4",
+        "@esbuild/linux-riscv64": "0.27.4",
+        "@esbuild/linux-s390x": "0.27.4",
+        "@esbuild/linux-x64": "0.27.4",
+        "@esbuild/netbsd-arm64": "0.27.4",
+        "@esbuild/netbsd-x64": "0.27.4",
+        "@esbuild/openbsd-arm64": "0.27.4",
+        "@esbuild/openbsd-x64": "0.27.4",
+        "@esbuild/openharmony-arm64": "0.27.4",
+        "@esbuild/sunos-x64": "0.27.4",
+        "@esbuild/win32-arm64": "0.27.4",
+        "@esbuild/win32-ia32": "0.27.4",
+        "@esbuild/win32-x64": "0.27.4"
+      }
+    },
     "node_modules/escape-html": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
@@ -489,6 +1088,21 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/function-bind": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
@@ -535,6 +1149,19 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/get-tsconfig": {
+      "version": "4.13.6",
+      "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.13.6.tgz",
+      "integrity": "sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "resolve-pkg-maps": "^1.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
+      }
+    },
     "node_modules/gopd": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
@@ -853,6 +1480,16 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/resolve-pkg-maps": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
+      "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
+      }
+    },
     "node_modules/safe-buffer": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
@@ -1051,6 +1688,26 @@
         "node": ">=0.6"
       }
     },
+    "node_modules/tsx": {
+      "version": "4.21.0",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.21.0.tgz",
+      "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.27.0",
+        "get-tsconfig": "^4.7.5"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
     "node_modules/type-is": {
       "version": "1.6.18",
       "resolved": "https://registry.npmjs.org/type-is/-/type-is-1.6.18.tgz",
@@ -1064,6 +1721,27 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/unpipe": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",

backend/package.json

@@ -3,10 +3,12 @@
   "version": "1.0.0",
   "private": true,
   "description": "Minimal Express API for Zui (agent, health; no DB)",
-  "main": "src/index.js",
+  "type": "module",
+  "main": "src/index.ts",
   "scripts": {
-    "start": "node src/index.js",
-    "dev": "node --watch src/index.js"
+    "start": "node src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc"
   },
   "engines": {
     "node": ">=20"
@@ -16,5 +18,12 @@
     "@ai-sdk/openai": "^1.0.0",
     "cors": "^2.8.5",
     "express": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
   }
 }

backend/src/index.js

@@ -1,101 +0,0 @@
-/**
- * Minimal Express API: /api/agent, /health.
- * No DB, no auth. CORS allowed for frontend. Production-ready env (PORT, CORS_ORIGIN).
- */
-
-const express = require('express')
-const cors = require('cors')
-
-const PORT = Number(process.env.PORT) || 8080
-const CORS_ORIGIN = process.env.CORS_ORIGIN || 'http://localhost:3000'
-
-const app = express()
-
-app.use(cors({ origin: CORS_ORIGIN }))
-app.use(express.json())
-
-/** Build OpenAI client and full prompt from request body. Returns { openai, modelId, fullPrompt } or { error }. */
-function buildAgentRequest(body) {
-  const { prompt, context, contextNodes, connection: conn, reasoning } = body ?? {}
-  const reasoningEnabled = Boolean(reasoning)
-  let baseURL = process.env.AI_BASE_URL?.trim() || null
-  let apiKey = process.env.OPENAI_API_KEY?.trim() || null
-  let modelId = process.env.AI_MODEL?.trim() || (baseURL ? 'local-model' : 'gpt-4o-mini')
-  if (conn && typeof conn === 'object') {
-    const c = conn
-    const provider = c.provider === 'openai' ? 'openai' : 'local'
-    if (provider === 'local') {
-      baseURL = (typeof c.baseURL === 'string' && c.baseURL.trim()) ? c.baseURL.trim() : baseURL
-      apiKey = (typeof c.apiKey === 'string' && c.apiKey.trim()) ? c.apiKey.trim() : (apiKey || 'lm-studio')
-    } else {
-      baseURL = null
-      apiKey = (typeof c.apiKey === 'string' && c.apiKey.trim()) ? c.apiKey.trim() : apiKey
-    }
-    if (typeof c.model === 'string' && c.model.trim()) modelId = c.model.trim()
-  }
-  if (!baseURL && !apiKey) {
-    return { error: 'No AI configured. Set connection in Settings (AI) or env: OPENAI_API_KEY or AI_BASE_URL.' }
-  }
-  const basePrompt = [
-    typeof prompt === 'string' ? prompt : 'No prompt provided.',
-    context && typeof context === 'string' ? `\n\nAdditional context:\n${context}` : '',
-    Array.isArray(contextNodes) && contextNodes.length > 0
-      ? `\n\nContext from connected nodes:\n${contextNodes.map((n) => (n.content != null ? n.content : `${n.id}: (no content)`)).join('\n\n')}`
-      : '',
-  ].join('')
-  const fullPrompt = reasoningEnabled
-    ? basePrompt + '\n\nRespond in exactly two markdown sections. First: "## Reasoning" with your step-by-step reasoning. Then: "## Output" with only the final answer. No preamble.'
-    : basePrompt + '\n\nRespond with structured markdown only. No preamble.'
-  const { createOpenAI } = require('@ai-sdk/openai')
-  const openai = createOpenAI({
-    apiKey: apiKey || 'lm-studio',
-    ...(baseURL && { baseURL, compatibility: 'compatible' }),
-  })
-  return { openai, modelId, fullPrompt }
-}
-
-/** POST /api/agent — run AI agent; body: { prompt, context?, contextNodes?, connection? }; returns { markdown }. */
-app.post('/api/agent', async (req, res) => {
-  try {
-    const built = buildAgentRequest(req.body)
-    if (built.error) return res.status(503).json({ error: built.error })
-    const { generateText } = await import('ai')
-    const result = await generateText({
-      model: built.openai(built.modelId),
-      prompt: built.fullPrompt,
-    })
-    const markdown = result?.text ?? ''
-    res.json({ markdown })
-  } catch (err) {
-    console.error('Agent error:', err)
-    res.status(500).json({ error: err?.message ?? 'Agent request failed' })
-  }
-})
-
-/** POST /api/agent/stream — same as /api/agent but streams plain text (markdown) chunks. */
-app.post('/api/agent/stream', async (req, res) => {
-  try {
-    const built = buildAgentRequest(req.body)
-    if (built.error) return res.status(503).json({ error: built.error })
-    const { streamText } = await import('ai')
-    const result = streamText({
-      model: built.openai(built.modelId),
-      prompt: built.fullPrompt,
-    })
-    res.setHeader('Content-Type', 'text/plain; charset=utf-8')
-    res.setHeader('Transfer-Encoding', 'chunked')
-    result.pipeTextStreamToResponse(res)
-  } catch (err) {
-    console.error('Agent stream error:', err)
-    res.status(500).json({ error: err?.message ?? 'Agent request failed' })
-  }
-})
-
-/** Health check for Docker / orchestration */
-app.get('/health', (req, res) => {
-  res.status(200).json({ ok: true })
-})
-
-app.listen(PORT, '0.0.0.0', () => {
-  console.log(`Backend listening on port ${PORT} (CORS: ${CORS_ORIGIN})`)
-})

backend/src/index.ts

@@ -0,0 +1,102 @@
+/**
+ * Backend API: Layered architecture for scalability and maintainability.
+ * 
+ * ## Architecture Layers
+ * 
+ * ### Controllers (routes/)
+ * - Handle HTTP requests and responses
+ * - Validate input and format output
+ * - Call services for business logic
+ * 
+ * ### Services (services/)
+ * - Implement business logic
+ * - Coordinate between controllers and repositories
+ * - Handle validation and transformation
+ * 
+ * ### Repositories (repositories/)
+ * - Data access layer
+ * - Interact with databases or external APIs
+ * - Return domain models
+ * 
+ * ### Models (models/)
+ * - Data structures and types
+ * - Validation schemas
+ * 
+ * ### Middleware (middleware/)
+ * - Request validation
+ * - Authentication/authorization
+ * - Rate limiting
+ * - Error handling
+ * 
+ * ## Adding New Endpoints
+ * 
+ * 1. Define the model in `models/`
+ * 2. Implement repository logic in `repositories/`
+ * 3. Implement service logic in `services/`
+ * 4. Create controller in `routes/`
+ * 5. Register route in `index.ts`
+ */
+
+import express from 'express'
+import cors from 'cors'
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const PORT = Number(process.env.PORT) || 8080
+const CORS_ORIGIN = process.env.CORS_ORIGIN || 'http://localhost:3000'
+
+// ---------------------------------------------------------------------------
+// Express App Setup
+// ---------------------------------------------------------------------------
+
+const app = express()
+
+app.use(cors({ origin: CORS_ORIGIN }))
+app.use(express.json())
+
+// ---------------------------------------------------------------------------
+// Agent Routes
+// ---------------------------------------------------------------------------
+
+import { handleAgentRequest, handleAgentStreamRequest } from './routes/agentRoutes.js'
+
+/** POST /api/agent - Run AI agent */
+app.post('/api/agent', handleAgentRequest)
+
+/** POST /api/agent/stream - Stream AI agent response */
+app.post('/api/agent/stream', handleAgentStreamRequest)
+
+// ---------------------------------------------------------------------------
+// Health Check Endpoint
+// ---------------------------------------------------------------------------
+
+/** GET /health - Health check for Docker / orchestration */
+app.get('/health', (req, res) => {
+  res.status(200).json({ ok: true, timestamp: Date.now() })
+})
+
+// ---------------------------------------------------------------------------
+// Error Handling Middleware
+// ---------------------------------------------------------------------------
+
+/** Global error handler for consistent error responses */
+app.use((err: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
+  console.error('Error:', err)
+  res.status(500).json({ error: err.message ?? 'Internal server error' })
+})
+
+// ---------------------------------------------------------------------------
+// Start Server
+// ---------------------------------------------------------------------------
+
+app.listen(PORT, '0.0.0.0', () => {
+  console.log(`Backend listening on port ${PORT} (CORS: ${CORS_ORIGIN})`)
+})
+
+// ---------------------------------------------------------------------------
+// Export for testing
+// ---------------------------------------------------------------------------
+
+export default app

backend/src/middleware/rateLimiter.ts

@@ -0,0 +1,88 @@
+/**
+ * Middleware: Rate limiting for API endpoints.
+ * 
+ * This module provides rate limiting middleware to protect the API
+ * from abuse and ensure fair usage.
+ */
+
+/**
+ * Rate limit configuration
+ */
+export type RateLimitConfig = {
+  /** Maximum number of requests allowed in the window */
+  max: number
+  /** Window size in milliseconds */
+  windowMs: number
+  /** Error message to return when rate limited */
+  message?: string
+}
+
+/**
+ * Default rate limit configuration
+ */
+export const DEFAULT_RATE_LIMIT_CONFIG: RateLimitConfig = {
+  max: 100,
+  windowMs: 60 * 1000, // 1 minute
+  message: 'Too many requests, please try again later.',
+}
+
+/**
+ * In-memory store for rate limiting
+ */
+const rateLimitStore = new Map<string, { count: number; resetTime: number }>()
+
+/**
+ * Rate limiting middleware
+ * 
+ * @param config - Rate limit configuration
+ * @returns Express middleware function
+ */
+export function rateLimit(config: RateLimitConfig = DEFAULT_RATE_LIMIT_CONFIG) {
+  return (req: { ip?: string; socket?: { remoteAddress?: string } }, res: { status: (code: number) => { json: (body: { error: string }) => void }, locals: Record<string, unknown> }, next: () => void): void => {
+    const ip = req.ip || req.socket?.remoteAddress || 'unknown'
+    const now = Date.now()
+    
+    let entry = rateLimitStore.get(ip)
+    
+    if (!entry || now > entry.resetTime) {
+      // Reset the counter for a new window
+      entry = { count: 1, resetTime: now + config.windowMs }
+      rateLimitStore.set(ip, entry)
+      next()
+      return
+    }
+    
+    entry.count++
+    
+    if (entry.count > config.max) {
+      res.status(429).json({ error: config.message ?? 'Too many requests' })
+      return
+    }
+    
+    next()
+  }
+}
+
+/**
+ * Clean up expired entries from the rate limit store
+ */
+export function cleanupRateLimitStore(): void {
+  const now = Date.now()
+  for (const [ip, entry] of rateLimitStore.entries()) {
+    if (now > entry.resetTime) {
+      rateLimitStore.delete(ip)
+    }
+  }
+}
+
+/**
+ * Get rate limit status for an IP
+ */
+export function getRateLimitStatus(ip: string): { remaining: number; resetTime: number } | null {
+  const entry = rateLimitStore.get(ip)
+  if (!entry) return null
+  return {
+    remaining: Math.max(0, DEFAULT_RATE_LIMIT_CONFIG.max - entry.count),
+    resetTime: entry.resetTime,
+  }
+}

backend/src/models/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Models: Data structures and validation schemas.
+ * 
+ * This module defines the domain models used throughout the application.
+ */
+
+/**
+ * Agent request payload
+ */
+export type AgentRequest = {
+  prompt: string
+  context?: string
+  contextNodes?: AgentContextNode[]
+  connection?: AgentConnection
+  reasoning?: boolean
+}
+
+/**
+ * Context node for agent requests
+ */
+export type AgentContextNode = {
+  id: string
+  content?: string
+}
+
+/**
+ * AI connection configuration
+ */
+export type AgentConnection = {
+  provider: 'openai' | 'local'
+  baseURL?: string
+  apiKey?: string
+  model?: string
+}
+
+/**
+ * Agent response
+ */
+export type AgentResponse = {
+  markdown: string
+}
+
+/**
+ * Agent stream response
+ */
+export type AgentStreamResponse = {
+  markdown: string
+}
+
+/**
+ * Health check response
+ */
+export type HealthResponse = {
+  ok: boolean
+  timestamp: number
+}
+
+/**
+ * Error response
+ */
+export type ErrorResponse = {
+  error: string
+}

backend/src/repositories/cacheRepository.ts

@@ -0,0 +1,103 @@
+/**
+ * Repositories: Data access layer.
+ * 
+ * This module handles data persistence and retrieval.
+ * It abstracts the underlying storage mechanism.
+ */
+
+/**
+ * Cache entry for expensive computations
+ */
+export type CacheEntry<T> = {
+  /** Unique key for the cache entry */
+  key: string
+  /** Cached data */
+  data: T
+  /** Timestamp (ms) when this entry was created */
+  createdAt: number
+  /** Time-to-live in milliseconds */
+  ttl?: number
+}
+
+/**
+ * In-memory cache implementation
+ */
+export class InMemoryCache {
+  private cache = new Map<string, CacheEntry<unknown>>()
+  private defaultTtl = 5 * 60 * 1000 // 5 minutes
+
+  /**
+   * Get a value from the cache
+   * 
+   * @param key - Cache key
+   * @returns Cached value or null if not found or expired
+   */
+  get<T>(key: string): T | null {
+    const entry = this.cache.get(key) as CacheEntry<T> | undefined
+    if (!entry) return null
+    
+    // Check if entry has expired
+    if (entry.ttl && Date.now() - entry.createdAt > entry.ttl) {
+      this.cache.delete(key)
+      return null
+    }
+    
+    return entry.data
+  }
+
+  /**
+   * Set a value in the cache
+   * 
+   * @param key - Cache key
+   * @param data - Data to cache
+   * @param ttl - Optional time-to-live in milliseconds (uses default if not specified)
+   */
+  set<T>(key: string, data: T, ttl?: number): void {
+    this.cache.set(key, {
+      key,
+      data,
+      createdAt: Date.now(),
+      ttl: ttl ?? this.defaultTtl,
+    })
+  }
+
+  /**
+   * Delete a value from the cache
+   * 
+   * @param key - Cache key
+   */
+  delete(key: string): void {
+    this.cache.delete(key)
+  }
+
+  /**
+   * Clear all entries from the cache
+   */
+  clear(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Clean up expired entries
+   */
+  cleanup(): void {
+    const now = Date.now()
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.ttl && now - entry.createdAt > entry.ttl) {
+        this.cache.delete(key)
+      }
+    }
+  }
+
+  /**
+   * Get the number of entries in the cache
+   */
+  size(): number {
+    return this.cache.size
+  }
+}
+
+/**
+ * Global cache instance
+ */
+export const cache = new InMemoryCache()

backend/src/routes/agentRoutes.ts

@@ -0,0 +1,72 @@
+/**
+ * Routes: HTTP request handlers.
+ * 
+ * This module contains the route handlers for the API.
+ * Routes validate input and format output, then call services for business logic.
+ */
+
+import type { AgentRequest, AgentResponse, ErrorResponse } from '../models'
+
+/**
+ * POST /api/agent - Run AI agent
+ * 
+ * Request body: { prompt, context?, contextNodes?, connection? }
+ * Response: { markdown }
+ */
+export async function handleAgentRequest(req: any, res: any): Promise<void> {
+  try {
+    const body = req.body
+    const { buildAgentRequest } = await import('../services/agentService')
+    
+    const built = buildAgentRequest(body)
+    if ('error' in built) {
+      res.status(503).json({ error: built.error } as ErrorResponse)
+      return
+    }
+    
+    const { generateText } = await import('ai')
+    const result = await generateText({
+      model: built.openai as any,
+      prompt: built.fullPrompt,
+    })
+    
+    const { processAgentResponse } = await import('../services/agentService')
+    const response = processAgentResponse(result)
+    res.json(response)
+  } catch (err) {
+    console.error('Agent error:', err)
+    res.status(500).json({ error: (err as Error).message ?? 'Agent request failed' } as ErrorResponse)
+  }
+}
+
+/**
+ * POST /api/agent/stream - Stream AI agent response
+ * 
+ * Request body: { prompt, context?, contextNodes?, connection? }
+ * Response: plain text (markdown) chunks
+ */
+export async function handleAgentStreamRequest(req: any, res: any): Promise<void> {
+  try {
+    const body = req.body
+    const { buildAgentRequest } = await import('../services/agentService')
+    
+    const built = buildAgentRequest(body)
+    if ('error' in built) {
+      res.status(503).json({ error: built.error } as ErrorResponse)
+      return
+    }
+    
+    const { streamText } = await import('ai')
+    const result = streamText({
+      model: built.openai as any,
+      prompt: built.fullPrompt,
+    })
+    
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+    res.setHeader('Transfer-Encoding', 'chunked')
+    result.pipeTextStreamToResponse(res)
+  } catch (err) {
+    console.error('Agent stream error:', err)
+    res.status(500).json({ error: (err as Error).message ?? 'Agent request failed' } as ErrorResponse)
+  }
+}

backend/src/services/agentService.ts

@@ -0,0 +1,65 @@
+/**
+ * Services: Business logic layer.
+ * 
+ * This module contains the business logic for the application.
+ * Services coordinate between controllers and repositories.
+ */
+
+import type { AgentRequest, AgentResponse, AgentConnection } from '../models'
+
+/**
+ * Build OpenAI client and full prompt from request body.
+ * Returns { openai, modelId, fullPrompt } or { error }.
+ */
+export function buildAgentRequest(body: AgentRequest): { openai: unknown; modelId: string; fullPrompt: string } | { error: string } {
+  const { prompt, context, contextNodes, connection: conn, reasoning } = body ?? {}
+  const reasoningEnabled = Boolean(reasoning)
+  let baseURL = process.env.AI_BASE_URL?.trim() || null
+  let apiKey = process.env.OPENAI_API_KEY?.trim() || null
+  let modelId = process.env.AI_MODEL?.trim() || (baseURL ? 'local-model' : 'gpt-4o-mini')
+  
+  if (conn && typeof conn === 'object') {
+    const c = conn as AgentConnection
+    const provider = c.provider === 'openai' ? 'openai' : 'local'
+    if (provider === 'local') {
+      baseURL = (typeof c.baseURL === 'string' && c.baseURL.trim()) ? c.baseURL.trim() : baseURL
+      apiKey = (typeof c.apiKey === 'string' && c.apiKey.trim()) ? c.apiKey.trim() : (apiKey || 'lm-studio')
+    } else {
+      baseURL = null
+      apiKey = (typeof c.apiKey === 'string' && c.apiKey.trim()) ? c.apiKey.trim() : apiKey
+    }
+    if (typeof c.model === 'string' && c.model.trim()) modelId = c.model.trim()
+  }
+  
+  if (!baseURL && !apiKey) {
+    return { error: 'No AI configured. Set connection in Settings (AI) or env: OPENAI_API_KEY or AI_BASE_URL.' }
+  }
+  
+  const basePrompt = [
+    typeof prompt === 'string' ? prompt : 'No prompt provided.',
+    context && typeof context === 'string' ? `\n\nAdditional context:\n${context}` : '',
+    Array.isArray(contextNodes) && contextNodes.length > 0
+      ? `\n\nContext from connected nodes:\n${contextNodes.map((n) => (n.content != null ? n.content : `${n.id}: (no content)`)).join('\n\n')}`
+      : '',
+  ].join('')
+  
+  const fullPrompt = reasoningEnabled
+    ? basePrompt + '\n\nRespond in exactly two markdown sections. First: "## Reasoning" with your step-by-step reasoning. Then: "## Output" with only the final answer. No preamble.'
+    : basePrompt + '\n\nRespond with structured markdown only. No preamble.'
+  
+  const { createOpenAI } = require('@ai-sdk/openai')
+  const openai = createOpenAI({
+    apiKey: apiKey || 'lm-studio',
+    ...(baseURL && { baseURL, compatibility: 'compatible' }),
+  })
+  
+  return { openai, modelId, fullPrompt }
+}
+
+/**
+ * Process agent response
+ */
+export function processAgentResponse(result: { text?: string }): AgentResponse {
+  const markdown = result?.text ?? ''
+  return { markdown }
+}

backend/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

docs/CODE_REVIEW_CHECKLIST.md

@@ -0,0 +1,48 @@
+# Code Review Checklist
+
+Use this checklist during code reviews to ensure high standards of readability, maintainability, and performance.
+
+## 1. Readability
+
+- [ ] **Naming**: Variables, functions, and components use descriptive, consistent names (camelCase for functions/variables, PascalCase for components).
+- [ ] **JSDoc**: All public APIs have complete JSDoc comments with `@param`, `@returns`, and `@example` tags.
+- [ ] **Line Length**: No line exceeds 120 characters; wrap long lines for readability.
+- [ ] **Comments**: Explain *why* something is done, not just *what* is done. Avoid redundant comments.
+- [ ] **Whitespace**: Consistent spacing and indentation (2 spaces for TypeScript/JSX).
+
+## 2. Maintainability
+
+- [ ] **Component Structure**: Large components are split into smaller, focused sub‑components.
+- [ ] **Hooks**: Custom hooks encapsulate reusable logic and are named with `use` prefix.
+- [ ] **Utility Functions**: Pure functions live in `src/lib/` and are exported for reuse.
+- [ ] **Type Safety**: All function signatures include explicit TypeScript types; no `any` usage.
+- [ ] **Import Order**: Core → Library → Project → Relative imports; alphabetical within groups.
+
+## 3. Performance
+
+- [ ] **Memoization**: Expensive calculations use `useMemo`; event handlers use `useCallback`.
+- [ ] **Lazy Loading**: Heavy modules are loaded via `import()`; code splitting is configured in Vite.
+- [ ] **Virtualization**: Large lists use `react-window` or similar for efficient rendering.
+- [ ] **State Granularity**: State updates target only the minimal portion of state; avoid unnecessary re‑renders.
+- [ ] **Bundle Size**: No unused dependencies; assets are compressed (gzip/brotli) in production.
+
+## 4. Accessibility & Security
+
+- [ ] **ARIA**: Semantic HTML and ARIA attributes are present for interactive elements.
+- [ ] **Input Validation**: User inputs are validated before processing; no hard‑coded secrets.
+- [ ] **Error Handling**: Errors are caught and logged appropriately; user‑friendly messages are shown.
+
+## 5. Testing
+
+- [ ] **Unit Tests**: Cover all new logic with tests; aim for ≥ 80 % coverage on critical paths.
+- [ ] **Integration Tests**: Verify that components interact correctly with state/store.
+- [ ] **Test Naming**: Test files end with `.test.tsx` and describe the behavior being tested.
+
+## 6. Documentation Links
+
+- [ ] Architecture Overview: [[ARCHITECTURE.md](ARCHITECTURE.md)]
+- [ ] Performance Plan: [[PERFORMANCE_IMPROVEMENTS.md](PERFORMANCE_IMPROVEMENTS.md)]
+- [ ] Junior Developer Quickstart: [[QUICKSTART_FOR_JUNIORS.md](QUICKSTART_FOR_JUNIORS.md)]
+- [ ] Contribution Guide: [[CONTRIBUTING.md](CONTRIBUTING.md)]
+
+*Reviewers should mark any failing items as **[ ]** and request changes before approving.*

frontend/docs/IMPROVEMENTS.md

@@ -57,7 +57,7 @@ This doc summarizes recent improvements and suggested next steps for readability
   - **StoredGraphState** – shape for save/load (version + nodes + edges).
 - **FlowContext**: Module doc splits value into (1) Graph state, (2) Connection path state, (3) UI state. Same flat props, clearer sections.
 - **useGraphStateWithHistory**: JSDoc explains history (past/future), setNodes vs setNodesSilent, setStateImmediate.
-- **projectGraphStorage**: Uses **StoredGraphState** from state.ts; re-exports type. Doc references state flow.
+- **recollectionGraphStorage**: Uses **StoredGraphState** from state.ts; re-exports type. Doc references state flow.
 - **useRenderingNodeState**: Returns **displayStatus** (for NodeStatusIndicator/empty/error UI) and **lifecycle** (updating/error/paused for useSyncConnectionStatus). Hook calls useSyncConnectionStatus(id, state.lifecycle). Type includes RenderingNodeLifecycle.
 - **RenderingNode**: Uses **state.displayStatus** for NodeStatusIndicator instead of computing status locally.
 - **nodeLifecycle** and **connectionStatus**: Docs reference state.ts for overall state flow.

frontend/docs/QUICKSTART_FOR_JUNIORS.md

@@ -0,0 +1,99 @@
+# Junior Developer Quickstart
+
+## 1. Overview
+
+This guide explains how to set up the development environment, run the application, and make your first contribution.
+
+## 2. Prerequisites
+
+- **Node.js** (v18 or later)
+- **pnpm** (package manager)
+- **Docker** (for backend services, optional)
+- **Git** (version control)
+
+## 3. Repository Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/zui.git
+cd zui
+
+# Install dependencies
+pnpm install
+```
+
+## 4. Running the Application
+
+### Frontend
+
+```bash
+pnpm dev
+```
+
+Open <http://localhost:3000> to see the app.
+
+### Backend
+
+```bash
+pnpm start
+```
+
+The backend API will be available at <http://localhost:5000>.
+
+## 5. Making Your First Contribution
+
+1. **Create a feature branch**:
+
+   ```bash
+   git checkout -b feat/your-first-contribution
+   ```
+
+2. **Make a small change**:
+   - Improve a README typo.
+   - Add a missing JSDoc comment.
+   - Fix a minor bug.
+3. **Run the appropriate tests** to ensure your change doesn't break anything:
+
+   ```bash
+   pnpm test
+   ```
+
+4. **Commit your changes** with a clear message:
+
+   ```bash
+   git commit -am "feat: brief description of change"
+   ```
+
+5. **Push the branch** to GitHub:
+
+   ```bash
+   git push origin feat/your-first-contribution
+   ```
+
+6. **Open a Pull Request** on GitHub, linking the relevant issue.
+
+## 6. Coding Standards
+
+- Follow the patterns in **ARCHITECTURE.md** and **CONTRIBUTING.md**.
+- Use TypeScript with strict mode.
+- Add JSDoc for all public APIs.
+- Keep changes small and focused.
+
+## 7. Helpful Links
+
+- **ARCHITECTURE.md** - High-level architecture overview.
+- **PERFORMANCE_IMPROVEMENTS.md** - Performance improvement plan.
+- **CODE_REVIEW_CHECKLIST.md** - Checklist for reviewers.
+
+## 8. FAQ
+
+**Q:** Do I need to write tests?  
+**A:** For bug fixes and new features, yes. Unit tests and integration tests are located under `frontend/src/app/**/*.test.tsx`.
+
+**Q:** How do I run the linter?  
+**A:** `pnpm lint`.
+
+**Q:** Where can I find more documentation?  
+**A:** See the `docs/` directory and the repository wiki.
+
+---\n*Happy coding!*

frontend/index.html

@@ -1,13 +1,16 @@
 <!doctype html>
 <html>
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="icon" href="/app-icon.svg" type="image/svg+xml" />
-    <title>React Flow + shadcn Canvas</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
+
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <link rel="icon" href="/app-icon.svg" type="image/svg+xml" />
+  <title>ZOË | Kosmos</title>
+</head>
+
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+
 </html>

frontend/package.json

@@ -10,6 +10,9 @@
     "test:run": "vitest run"
   },
   "dependencies": {
+    "@blocknote/core": "0.36.1",
+    "@blocknote/react": "0.36.1",
+    "@blocknote/shadcn": "0.36.1",
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-context-menu": "^2.2.16",
@@ -40,6 +43,7 @@
     "prism-react-renderer": "^2.4.1",
     "prismjs": "^1.30.0",
     "react": "18.2.0",
+    "react-arborist": "^3.4.3",
     "react-dom": "18.2.0",
     "react-router-dom": "^6.28.0",
     "react-simple-code-editor": "^0.14.1",

frontend/src/app/NotFoundPage.tsx

@@ -0,0 +1,21 @@
+/**
+ * 404 page for unknown routes. Shown when no route matches.
+ */
+
+import React from 'react'
+import { Link } from 'react-router-dom'
+import { Button } from '@/components/ui/button'
+
+export function NotFoundPage() {
+  return (
+    <div className="flex min-h-dvh flex-col items-center justify-center gap-6 bg-background p-8">
+      <h1 className="text-2xl font-semibold text-foreground">Page not found</h1>
+      <p className="text-sm text-muted-foreground">
+        The page you’re looking for doesn’t exist or has been moved.
+      </p>
+      <Button asChild variant="default">
+        <Link to="/recollections">Back to Recollections</Link>
+      </Button>
+    </div>
+  )
+}

frontend/src/app/canvas/CanvasMenubar.tsx

@@ -1,353 +0,0 @@
-/**
- * Menubar for the canvas page: Project (Import/Export), Edit (Undo/Redo, Duplicate/Copy/Paste, Rename), View (Fit View, Minimap).
- */
-
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Link, useParams } from 'react-router-dom'
-import {
-  Menubar,
-  MenubarContent,
-  MenubarItem,
-  MenubarMenu,
-  MenubarSeparator,
-  MenubarTrigger
-} from '@/components/ui/menubar'
-import { Kbd, KbdGroup } from '@/components/ui/kbd'
-import { usePlatform } from '@/app/kosmos/KosmosContext'
-import { ArrowLeft, CheckCircle2, CircleDot, ClipboardPaste, Copy, CopyPlus, Download, FolderOpen, Loader2, Pencil, Redo2, Save, Undo2 } from 'lucide-react'
-import { Input } from '@/components/ui/input'
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
-import type { SaveStatus } from '@/app/canvas/useCanvasGraph'
-
-export type CanvasMenubarProps = {
-  onImport: () => void
-  onExport: () => void
-  onSave?: () => void
-  canSave?: boolean
-  /** Shown next to project title: unsaved | saving | saved */
-  saveStatus?: SaveStatus
-  undo: () => void
-  redo: () => void
-  canUndo: boolean
-  canRedo: boolean
-  onDuplicate?: () => void
-  onCopy?: () => void
-  onPaste?: () => void
-  canDuplicate?: boolean
-  canCopy?: boolean
-  onFitView?: () => void
-}
-
-const UNDO_KEYS = { key: 'z', shiftKey: false }
-const REDO_KEYS = { key: 'z', shiftKey: true }
-const SAVE_KEYS = { key: 's', shiftKey: false }
-
-function matchKey(ev: KeyboardEvent, want: { key: string; shiftKey: boolean }) {
-  const mod = ev.ctrlKey || ev.metaKey
-  return ev.key.toLowerCase() === want.key && !!mod && !!ev.shiftKey === want.shiftKey
-}
-
-export function CanvasMenubar({
-  onImport,
-  onExport,
-  onSave,
-  canSave = true,
-  saveStatus = 'saved',
-  undo,
-  redo,
-  canUndo,
-  canRedo,
-  onDuplicate,
-  onCopy,
-  onPaste,
-  canDuplicate = false,
-  canCopy = false,
-  onFitView,
-}: CanvasMenubarProps) {
-  const { projectId } = useParams<{ projectId: string }>()
-  const { projects, renameProject } = usePlatform()
-  const projectName = useMemo(
-    () => (projectId ? projects.find((p) => p.id === projectId)?.name ?? null : null),
-    [projectId, projects]
-  )
-
-  const [isRenamingProject, setIsRenamingProject] = useState(false)
-  const [renameValue, setRenameValue] = useState('')
-  const [showSavedBriefly, setShowSavedBriefly] = useState(false)
-  const renameInputRef = useRef<HTMLInputElement>(null)
-  const ignoreNextBlurRef = useRef(false)
-  const savedBrieflyTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-  const prevSaveStatusRef = useRef<SaveStatus>(saveStatus)
-
-  useEffect(() => {
-    if (prevSaveStatusRef.current === 'saving' && saveStatus === 'saved') {
-      setShowSavedBriefly(true)
-      if (savedBrieflyTimerRef.current) clearTimeout(savedBrieflyTimerRef.current)
-      savedBrieflyTimerRef.current = setTimeout(() => {
-        savedBrieflyTimerRef.current = null
-        setShowSavedBriefly(false)
-      }, 2500)
-    }
-    prevSaveStatusRef.current = saveStatus
-  }, [saveStatus])
-
-  useEffect(() => {
-    return () => {
-      if (savedBrieflyTimerRef.current) {
-        clearTimeout(savedBrieflyTimerRef.current)
-        savedBrieflyTimerRef.current = null
-      }
-    }
-  }, [])
-
-  useEffect(() => {
-    if (isRenamingProject) {
-      setRenameValue(projectName ?? '')
-      ignoreNextBlurRef.current = true
-      // Delay focus so the Project dropdown can close first and not steal focus back (which would trigger blur)
-      const t = setTimeout(() => {
-        renameInputRef.current?.focus()
-        renameInputRef.current?.select()
-      }, 100)
-      return () => clearTimeout(t)
-    }
-  }, [isRenamingProject, projectName])
-
-  const applyRename = useCallback(() => {
-    if (!projectId || !renameProject) return
-    const trimmed = renameValue.trim()
-    if (trimmed) renameProject(projectId, trimmed)
-    setIsRenamingProject(false)
-  }, [projectId, renameProject, renameValue])
-
-  const cancelRename = useCallback(() => {
-    setIsRenamingProject(false)
-  }, [])
-
-  const handleRenameBlur = useCallback(() => {
-    if (ignoreNextBlurRef.current) {
-      ignoreNextBlurRef.current = false
-      return
-    }
-    applyRename()
-  }, [applyRename])
-
-  useEffect(() => {
-    const onKeyDown = (ev: KeyboardEvent) => {
-      if (matchKey(ev, UNDO_KEYS)) {
-        if (canUndo) {
-          ev.preventDefault()
-          ev.stopPropagation()
-          undo()
-        }
-        return
-      }
-      if (matchKey(ev, REDO_KEYS)) {
-        if (canRedo) {
-          ev.preventDefault()
-          ev.stopPropagation()
-          redo()
-        }
-        return
-      }
-      if (matchKey(ev, SAVE_KEYS)) {
-        if (onSave && canSave) {
-          ev.preventDefault()
-          ev.stopPropagation()
-          onSave()
-        }
-      }
-    }
-    window.addEventListener('keydown', onKeyDown, true)
-    return () => window.removeEventListener('keydown', onKeyDown, true)
-  }, [undo, redo, canUndo, canRedo, onSave, canSave])
-
-  return (
-    <div className="relative flex h-9 w-full shrink-0 items-center border-b border-border/40 bg-background">
-      <Menubar className="flex-1 shrink-0 rounded-none border-0 border-b-0 bg-transparent p-0 shadow-none">
-        <Link
-          to="/projects"
-          aria-label="Back to projects"
-          className="flex shrink-0 items-center rounded-sm px-2 py-1 ml-1 text-sm outline-none focus:bg-accent focus:text-accent-foreground hover:bg-accent hover:text-accent-foreground"
-        >
-          <ArrowLeft className="size-4" />
-        </Link>
-        <MenubarMenu>
-          <MenubarTrigger className="font-normal text-muted-foreground">Project</MenubarTrigger>
-          <MenubarContent>
-                {projectId && (
-              <>
-                {onSave != null && (
-                  <>
-                    <MenubarItem onClick={onSave} disabled={!canSave} className="gap-2">
-                      <Save className="h-4 w-4" />
-                      Save
-                      <span className="ml-auto pl-4">
-                        <KbdGroup>
-                          <Kbd>⌘S</Kbd>
-                        </KbdGroup>
-                      </span>
-                    </MenubarItem>
-                    <MenubarSeparator />
-                  </>
-                )}
-                <MenubarItem
-                  onClick={() => setIsRenamingProject(true)}
-                  className="gap-2"
-                >
-                  <Pencil className="h-4 w-4" />
-                  Rename
-                </MenubarItem>
-                <MenubarSeparator />
-              </>
-            )}
-            <MenubarItem onClick={onImport} className="gap-2">
-              <FolderOpen className="h-4 w-4" />
-              Import…
-            </MenubarItem>
-            <MenubarItem onClick={onExport} className="gap-2">
-              <Download className="h-4 w-4" />
-              Export…
-            </MenubarItem>
-          </MenubarContent>
-        </MenubarMenu>
-        <MenubarMenu>
-          <MenubarTrigger className="font-normal text-muted-foreground">Edit</MenubarTrigger>
-          <MenubarContent>
-            <MenubarItem onClick={undo} disabled={!canUndo} className="gap-2">
-              <Undo2 className="h-4 w-4" />
-              Undo
-              <span className="ml-auto pl-4">
-                <KbdGroup>
-                  <Kbd>⌘ + Z</Kbd>
-                </KbdGroup>
-              </span>
-            </MenubarItem>
-            <MenubarItem onClick={redo} disabled={!canRedo} className="gap-2">
-              <Redo2 className="h-4 w-4" />
-              Redo
-              <span className="ml-auto pl-4">
-                <KbdGroup>
-                  <Kbd>⌘ + ⇧ + Z</Kbd>
-                </KbdGroup>
-              </span>
-            </MenubarItem>
-            {(onDuplicate != null || onCopy != null || onPaste != null) && <MenubarSeparator />}
-            {onDuplicate != null && (
-              <MenubarItem onClick={onDuplicate} disabled={!canDuplicate} className="gap-2">
-                <CopyPlus className="h-4 w-4" />
-                Duplicate
-                <span className="ml-auto pl-4">
-                  <KbdGroup>
-                    <Kbd>⌘D</Kbd>
-                  </KbdGroup>
-                </span>
-              </MenubarItem>
-            )}
-            {onCopy != null && (
-              <MenubarItem onClick={onCopy} disabled={!canCopy} className="gap-2">
-                <Copy className="h-4 w-4" />
-                Copy
-                <span className="ml-auto pl-4">
-                  <KbdGroup>
-                    <Kbd>⌘C</Kbd>
-                  </KbdGroup>
-                </span>
-              </MenubarItem>
-            )}
-            {onPaste != null && (
-              <MenubarItem onClick={onPaste} className="gap-2">
-                <ClipboardPaste className="h-4 w-4" />
-                Paste
-                <span className="ml-auto pl-4">
-                  <KbdGroup>
-                    <Kbd>⌘V</Kbd>
-                  </KbdGroup>
-                </span>
-              </MenubarItem>
-            )}
-          </MenubarContent>
-        </MenubarMenu>
-        <MenubarMenu>
-          <MenubarTrigger className="font-normal text-muted-foreground">View</MenubarTrigger>
-          <MenubarContent>
-            {onFitView && (
-              <MenubarItem onClick={onFitView} className="gap-2">
-                Fit View
-                <span className="ml-auto pl-4">
-                  <KbdGroup>
-                    <Kbd>⌘0</Kbd>
-                  </KbdGroup>
-                </span>
-              </MenubarItem>
-            )}
-          </MenubarContent>
-        </MenubarMenu>
-      </Menubar>
-      {projectId && (
-        <div className="absolute left-1/2 -translate-x-1/2 flex items-center justify-center gap-2 max-w-[50%] min-w-[120px]">
-          {isRenamingProject ? (
-            <Input
-              ref={renameInputRef}
-              type="text"
-              value={renameValue}
-              onChange={(e) => setRenameValue(e.target.value)}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter') {
-                  e.preventDefault()
-                  applyRename()
-                } else if (e.key === 'Escape') {
-                  e.preventDefault()
-                  cancelRename()
-                }
-              }}
-              onBlur={handleRenameBlur}
-              className="h-7 text-sm font-medium text-center font-serif"
-              aria-label="Project name"
-            />
-          ) : (
-            <>
-              <span className="pointer-events-none truncate text-sm font-medium text-foreground font-serif">
-                {projectName ?? 'Untitled'}
-              </span>
-              <TooltipProvider delayDuration={300}>
-                <Tooltip>
-                  <TooltipTrigger asChild>
-                    <span
-                      className="shrink-0 flex items-center text-muted-foreground cursor-default"
-                      aria-live="polite"
-                      aria-label={
-                        saveStatus === 'saving'
-                          ? 'Saving'
-                          : saveStatus === 'unsaved'
-                            ? 'Unsaved changes'
-                            : 'All changes saved'
-                      }
-                    >
-                      {saveStatus === 'saving' && (
-                        <Loader2 className="size-3.5 animate-spin" aria-hidden />
-                      )}
-                      {saveStatus === 'unsaved' && (
-                        <CircleDot className="size-3.5" aria-hidden />
-                      )}
-                      {(saveStatus === 'saved' || showSavedBriefly) && (
-                        <CheckCircle2 className="size-3.5 text-muted-foreground/70" aria-hidden />
-                      )}
-                    </span>
-                  </TooltipTrigger>
-                  <TooltipContent side="bottom">
-                    {saveStatus === 'saving'
-                      ? 'Saving…'
-                      : saveStatus === 'unsaved'
-                        ? 'Unsaved changes'
-                        : 'All changes saved'}
-                  </TooltipContent>
-                </Tooltip>
-              </TooltipProvider>
-            </>
-          )}
-        </div>
-      )}
-    </div>
-  )
-}

frontend/src/app/canvas/CanvasPage.tsx

@@ -1,6 +1,6 @@
 /**
  * Canvas page: the graph editor (React Flow) with nodes, edges, context menu, import/export.
- * Rendered inside the platform when a project is selected.
+ * Rendered inside the platform when a recollection is selected.
  */
 
 import React, { useCallback, useEffect, useMemo, useRef } from 'react'
@@ -36,7 +36,8 @@ import { ContextMenu, ContextMenuTrigger } from '@/components/ui/context-menu'
 import { CanvasContextMenuContent } from '@/app/canvas/CanvasContextMenuContent'
 import { useCanvasConnectionPathFromStore } from '@/app/canvas/useCanvasConnectionPathFromStore'
 import { dispatchCanvasCommand } from '@/app/canvas/canvasStore'
-import { CanvasMenubar } from '@/app/canvas/CanvasMenubar'
+import { useRecollectionActions } from '@/app/recollections/layout/RecollectionActionsContext'
+import type { StoredGraphState } from '@/app/recollections/state/recollectionStore'
 import { createContextualNode } from '@/app/canvas/ContextualZoomNode'
 import { ViewportDisplayProvider } from '@/app/canvas/ViewportDisplayContext'
 import { FlowKeyboardShortcuts } from '@/components/graph/FlowKeyboardShortcuts'
@@ -66,7 +67,7 @@ import {
 } from '@/lib/graph/nodeRegistry'
 import type { AppNode, AppEdge } from '@/lib/graph/nodeTypes'
 import { toast } from 'sonner'
-import { PROJECT_FILE_EXT, PROJECT_VERSION } from '@/app/pleroma/projectGraphStorage'
+import { RECOLLECTION_VERSION } from '@/app/recollections/state/recollectionGraphStorage'
 
 const SNAP_GRID: [number, number] = [15, 15]
 const DUPLICATE_OFFSET = { x: 30, y: 30 }
@@ -75,12 +76,60 @@ const snapToGrid = (x: number, y: number): { x: number; y: number } => ({
   y: Math.round(y / SNAP_GRID[1]) * SNAP_GRID[1],
 })
 
-function FlowFitViewOnLoad() {
+function FlowFitViewOnLoad({ disabled }: { disabled?: boolean }) {
   const nodesInitialized = useNodesInitialized()
   const { fitView } = useReactFlow()
   React.useEffect(() => {
-    if (nodesInitialized) fitView?.({ duration: 200 })
-  }, [nodesInitialized, fitView])
+    if (disabled || !nodesInitialized) return
+    fitView?.({ duration: 200 })
+  }, [disabled, nodesInitialized, fitView])
+  return null
+}
+
+function FocusNodeOnLoad({ focusNodeId }: { focusNodeId?: string }) {
+  const nodesInitialized = useNodesInitialized()
+  const { getNodes, setCenter, screenToFlowPosition, project } = useReactFlow()
+
+  React.useEffect(() => {
+    if (!focusNodeId || !nodesInitialized) return
+    // Small delay so node DOM and layout are fully ready before centering/zooming.
+    const timer = setTimeout(() => {
+      const nodes = getNodes()
+      const node = nodes.find((n) => n.id === focusNodeId)
+      if (!node) return
+
+      const el = document.querySelector(
+        `.react-flow__node[data-id="${focusNodeId}"]`
+      ) as HTMLElement | null
+
+      if (el) {
+        const rect = el.getBoundingClientRect()
+        const screenCenter = { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 }
+        const toFlow = screenToFlowPosition ?? project
+        if (toFlow) {
+          const flowCenter = toFlow(screenCenter)
+          setCenter(flowCenter.x, flowCenter.y, { duration: 400, zoom: 1.8 })
+          return
+        }
+      }
+
+      // Fallback: center using node position + dimensions from React Flow state.
+      const anyNode = node as Node & {
+        positionAbsolute?: { x: number; y: number }
+        width?: number
+        height?: number
+      }
+      const basePos = anyNode.positionAbsolute ?? anyNode.position ?? { x: 0, y: 0 }
+      const width = anyNode.width ?? 0
+      const height = anyNode.height ?? 0
+      const centerX = basePos.x + width / 2
+      const centerY = basePos.y + height / 2
+      setCenter(centerX, centerY, { duration: 400, zoom: 1.8 })
+    }, 150)
+
+    return () => clearTimeout(timer)
+  }, [focusNodeId, nodesInitialized, getNodes, setCenter, screenToFlowPosition, project])
+
   return null
 }
 
@@ -149,11 +198,13 @@ function FullscreenNodeContent({ node }: { node: AppNode }) {
 }
 
 export type CanvasPageProps = {
-  /** Optional project id for future per-project graph loading */
-  projectId?: string
+  /** Optional recollection id for per-recollection graph loading */
+  recollectionId?: string
+  /** Optional node id to focus when the canvas loads (e.g. from Katalogos artifacts). */
+  focusNodeId?: string
 }
 
-export function CanvasPage({ projectId }: CanvasPageProps) {
+export function CanvasPage({ recollectionId, focusNodeId }: CanvasPageProps) {
   const { theme } = useTheme()
   const { showMinimap } = usePlatform()
   const {
@@ -172,9 +223,8 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
     setStateImmediate,
     save,
     saveStatus,
-  } = useCanvasGraph(projectId)
+  } = useCanvasGraph(recollectionId)
 
-  const importInputRef = useRef<HTMLInputElement | null>(null)
   const [rfInstance, setRfInstance] = React.useState<unknown>(null)
   const [renamingNodeId, setRenamingNodeId] = React.useState<string | null>(null)
   const [connectionFrom, setConnectionFrom] = React.useState<{ nodeId: string; sourceHandle?: string } | null>(null)
@@ -188,8 +238,21 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
   const [isSelecting, setIsSelecting] = React.useState(false)
   const [ariaAnnouncement, setAriaAnnouncement] = React.useState<string | null>(null)
   const [fullscreenNodeId, setFullscreenNodeId] = React.useState<string | null>(null)
+
+  const graphApplyTimeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null)
+  const GRAPH_APPLY_DEBOUNCE_MS = 300
   useEffect(() => {
-    dispatchCanvasCommand({ type: 'graph/apply', payload: { nodes, edges } })
+    if (graphApplyTimeoutRef.current) clearTimeout(graphApplyTimeoutRef.current)
+    graphApplyTimeoutRef.current = setTimeout(() => {
+      graphApplyTimeoutRef.current = null
+      dispatchCanvasCommand({ type: 'graph/apply', payload: { nodes, edges } })
+    }, GRAPH_APPLY_DEBOUNCE_MS)
+    return () => {
+      if (graphApplyTimeoutRef.current) {
+        clearTimeout(graphApplyTimeoutRef.current)
+        graphApplyTimeoutRef.current = null
+      }
+    }
   }, [nodes, edges])
 
   const connectionPath = useCanvasConnectionPathFromStore()
@@ -218,7 +281,22 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
         rafRef.current = requestAnimationFrame(() => {
           rafRef.current = null
           const toApply = pendingChangesRef.current.splice(0, pendingChangesRef.current.length)
-          if (toApply.length > 0) setNodesSilent((nds) => applyNodeChanges(toApply, nds))
+          if (toApply.length === 0) return
+          setNodesSilent((nds) => {
+            // Drop dimension-only changes that don't change the node (e.g. React Flow re-reporting on visibility).
+            // Avoids graph/apply and store churn when nodes become visible with onlyRenderVisibleElements.
+            const filtered = toApply.filter((c) => {
+              const ch = c as NodeChange<Node> & { type?: string; dimensions?: { width?: number; height?: number } }
+              if (ch.type !== 'dimensions' || ch.dimensions == null) return true
+              const node = nds.find((n) => n.id === (ch as { id?: string }).id)
+              if (!node) return true
+              const nw = (node as Node & { width?: number }).width
+              const nh = (node as Node & { height?: number }).height
+              return nw !== ch.dimensions.width || nh !== ch.dimensions.height
+            })
+            if (filtered.length === 0) return nds
+            return applyNodeChanges(filtered, nds)
+          })
         })
       }
     },
@@ -295,57 +373,12 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
   const onNodeDragStart = useCallback(() => saveForDragEnd(), [saveForDragEnd])
   const onNodeDragStop = useCallback(() => commitDragEnd(), [commitDragEnd])
 
-  const handleExportProject = useCallback(() => {
-    const state = { version: PROJECT_VERSION, nodes, edges }
-    const blob = new Blob([JSON.stringify(state, null, 2)], { type: 'application/json' })
-    const url = URL.createObjectURL(blob)
-    const a = document.createElement('a')
-    a.href = url
-    a.download = `project${PROJECT_FILE_EXT}`
-    a.click()
-    URL.revokeObjectURL(url)
-    toast.success('Project exported')
-  }, [nodes, edges])
-
-  const handleImportProject = useCallback(() => importInputRef.current?.click(), [])
-
   const handleLoadExample = useCallback(() => {
     const { nodes: exampleNodes, edges: exampleEdges } = getExampleGraph()
     setStateImmediate({ nodes: exampleNodes, edges: exampleEdges })
     toast.success('Example loaded')
   }, [setStateImmediate])
 
-  const onImportFileChange = useCallback(
-    (e: React.ChangeEvent<HTMLInputElement>) => {
-      const file = e.target.files?.[0]
-      e.target.value = ''
-      if (!file) return
-      const reader = new FileReader()
-      reader.onload = () => {
-        try {
-          const text = reader.result as string
-          const state = JSON.parse(text) as { version?: number; nodes?: unknown[]; edges?: unknown[] }
-          if (!state || !Array.isArray(state.nodes) || !Array.isArray(state.edges)) {
-            toast.error('Invalid file: expected nodes and edges arrays')
-            return
-          }
-          const nodes = state.nodes as AppNode[]
-          const edges = backfillEdgeTargetTypes(nodes, state.edges as AppEdge[])
-          setStateImmediate({ nodes, edges })
-          if (state.version != null && state.version > PROJECT_VERSION) {
-            toast.error('Project was created with a newer app version')
-          } else {
-            toast.success('Project loaded')
-          }
-        } catch {
-          toast.error('Invalid file: not valid JSON')
-        }
-      }
-      reader.readAsText(file)
-    },
-    [setStateImmediate]
-  )
-
   const selectedNodes = useMemo(
     () => nodes.filter((n) => (n as Node & { selected?: boolean }).selected),
     [nodes]
@@ -399,6 +432,57 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
     flowActionsRef.current?.pasteAtViewportCenter?.()
   }, [])
 
+  const { setFluxSlot, onImport } = useRecollectionActions()
+
+  const onRefreshFromStore = useCallback(
+    (graph: StoredGraphState) => {
+      const nodes = graph.nodes as AppNode[]
+      const edges = backfillEdgeTargetTypes(nodes, graph.edges as AppEdge[])
+      setStateImmediate({ nodes, edges })
+    },
+    [setStateImmediate]
+  )
+
+  useEffect(() => {
+    const slot = {
+      saveStatus,
+      onSave: recollectionId
+        ? () => {
+            save()
+            toast.success('Saved')
+          }
+        : () => {},
+      canSave: Boolean(recollectionId),
+      undo,
+      redo,
+      canUndo,
+      canRedo,
+      onRefreshFromStore,
+      onDuplicate: handleDuplicate,
+      onCopy: handleCopy,
+      onPaste: handlePaste,
+      canDuplicate: selectedNodes.length > 0,
+      canCopy: selectedNodes.length === 1,
+      onFitView: () => flowActionsRef.current?.fitView?.(),
+    }
+    setFluxSlot(slot)
+    return () => setFluxSlot(null)
+  }, [
+    setFluxSlot,
+    saveStatus,
+    recollectionId,
+    save,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    onRefreshFromStore,
+    handleDuplicate,
+    handleCopy,
+    handlePaste,
+    selectedNodes.length,
+  ])
+
   const graphContextValue = useMemo(
     () => ({ setNodes, setEdges, graphRef, edges }),
     [setNodes, setEdges, edges]
@@ -506,8 +590,9 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
     const clientX = click?.clientX ?? window.innerWidth / 2
     const clientY = click?.clientY ?? window.innerHeight / 2
     try {
-      const inst = rfInstance as { screenToFlowPosition?: (p: { x: number; y: number }) => { x: number; y: number }; project?: (p: { x: number; y: number }) => { x: number; y: number } }
-      const screenToFlow = inst.screenToFlowPosition ?? inst.project
+      type ScreenToFlow = (p: { x: number; y: number }) => { x: number; y: number }
+      const inst = rfInstance as { screenToFlowPosition?: ScreenToFlow; [k: string]: unknown }
+      const screenToFlow = inst.screenToFlowPosition ?? (inst['project'] as ScreenToFlow | undefined)
       const p = screenToFlow?.call(rfInstance, { x: clientX, y: clientY })
       return p ? snapToGrid(p.x, p.y) : null
     } catch {
@@ -609,38 +694,6 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
       <div role="status" aria-live="polite" aria-atomic className="sr-only">
         {ariaAnnouncement}
       </div>
-      <input
-        ref={importInputRef}
-        type="file"
-        accept=".json,.zui.json,application/json"
-        className="hidden"
-        onChange={onImportFileChange}
-        aria-hidden
-      />
-      <CanvasMenubar
-        onImport={handleImportProject}
-        onExport={handleExportProject}
-        onSave={
-          projectId
-            ? () => {
-                save()
-                toast.success('Saved')
-              }
-            : undefined
-        }
-        canSave={Boolean(projectId)}
-        saveStatus={saveStatus}
-        undo={undo}
-        redo={redo}
-        canUndo={canUndo}
-        canRedo={canRedo}
-        onDuplicate={handleDuplicate}
-        onCopy={handleCopy}
-        onPaste={handlePaste}
-        canDuplicate={selectedNodes.length > 0}
-        canCopy={selectedNodes.length === 1}
-        onFitView={() => flowActionsRef.current?.fitView?.()}
-      />
       <div className="flex-1 min-h-0 relative flex flex-col">
         <div className="flex-1 min-h-0 flex flex-col">
           <GraphContext.Provider value={graphContextValue}>
@@ -666,11 +719,11 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
                             <EmptyTitle>Start adding a new node!</EmptyTitle>
                             <EmptyDescription>
                               Right‑click to add nodes. <br />
-                              Import a project or paste a node.
+                              Import a recollection or paste a node.
                             </EmptyDescription>
                           </EmptyHeader>
                           <EmptyContent className="flex-row flex-wrap justify-center gap-2">
-                            <Button onClick={handleImportProject} variant="outline" size="sm">
+                            <Button onClick={onImport} variant="outline" size="sm">
                               <FolderOpen className="size-4" />
                               Import…
                             </Button>
@@ -685,7 +738,8 @@ export function CanvasPage({ projectId }: CanvasPageProps) {
                   )}
                   <ReactFlowProvider initialNodes={nodes} initialEdges={edges} fitView>
                     <ViewportDisplayProvider>
-                      <FlowFitViewOnLoad />
+                      <FlowFitViewOnLoad disabled={Boolean(focusNodeId)} />
+                      <FocusNodeOnLoad focusNodeId={focusNodeId} />
                       <FlowKeyboardShortcuts />
                       <ReactFlow
                       className={isPanning ? 'react-flow--panning' : isSelecting ? 'react-flow--selecting' : undefined}

frontend/src/app/canvas/CanvasRoute.tsx

@@ -1,36 +0,0 @@
-/**
- * Route wrapper for the canvas: resolves projectId from URL and updates lastEditedAt on open.
- */
-
-import React, { useEffect, useRef } from 'react'
-import { useParams } from 'react-router-dom'
-import { CanvasPage } from './CanvasPage'
-import { usePlatform } from '@/app/kosmos/KosmosContext'
-
-export function CanvasRoute() {
-  const { projectId } = useParams<{ projectId: string }>()
-  const { projects, updateLastEdited } = usePlatform()
-  const updateLastEditedRef = useRef(updateLastEdited)
-  updateLastEditedRef.current = updateLastEdited
-
-  const project = projects.find((p) => p.id === projectId)
-
-  useEffect(() => {
-    if (projectId) updateLastEditedRef.current(projectId)
-  }, [projectId])
-
-  if (!projectId) return null
-  if (!project) {
-    return (
-      <div className="flex flex-1 flex-col items-center justify-center gap-4 p-8">
-        <p className="text-sm text-muted-foreground">Project not found.</p>
-      </div>
-    )
-  }
-
-  return (
-    <div className="flex min-h-0 flex-1 flex-col">
-      <CanvasPage key={projectId} projectId={projectId} />
-    </div>
-  )
-}

frontend/src/app/canvas/canvasGraphUtils.ts

@@ -5,7 +5,7 @@
 
 import type { AppNode, AppEdge } from '@/lib/graph/nodeTypes'
 import { DEFAULT_NODE_STYLE } from '@/lib/graph/flowUtils'
-import { loadGraphFromStorage } from '@/app/pleroma/projectGraphStorage'
+import { loadGraphFromStorage } from '@/app/recollections/state/recollectionGraphStorage'
 
 /** Ensure each edge has data.targetType from the target node (for labels without depending on nodes in edgesForFlow). */
 export function backfillEdgeTargetTypes(
@@ -70,9 +70,9 @@ export function getExampleGraph(): { nodes: AppNode[]; edges: AppEdge[] } {
   return { nodes, edges }
 }
 
-export function getInitialGraph(projectId: string | undefined): { nodes: AppNode[]; edges: AppEdge[] } {
-  if (projectId) {
-    const stored = loadGraphFromStorage(projectId)
+export function getInitialGraph(recollectionId: string | undefined): { nodes: AppNode[]; edges: AppEdge[] } {
+  if (recollectionId) {
+    const stored = loadGraphFromStorage(recollectionId)
     if (stored && (stored.nodes.length > 0 || stored.edges.length > 0)) {
       const nodes = stored.nodes as AppNode[]
       const edges = backfillEdgeTargetTypes(nodes, stored.edges as AppEdge[])

frontend/src/app/canvas/canvasStore.index.ts

@@ -26,5 +26,19 @@ export {
   selectRenamingNodeId,
   selectFullscreenNodeId,
   selectConnectionFrom,
+  // Fine-grained selectors
+  selectNodeById,
+  selectNodesById,
+  selectNodesByType,
+  selectNodeIdsByType,
+  selectEdgesBySource,
+  selectEdgesByTarget,
+  selectEdgesForNode,
+  selectNodeCount,
+  selectEdgeCount,
+  selectHasNode,
+  selectHasEdge,
+  // SVG detection
+  isSvgContent,
 } from './canvasStore.selectors'
 export type { ConnectionPathRole } from './canvasStore.selectors'

frontend/src/app/canvas/canvasStore.selectors.ts

@@ -10,10 +10,19 @@ import {
 } from '@/lib/graph/graphologyPath'
 import { getConnectionStatus, type ConnectionStatus } from '@/lib/graph/connectionStatus'
 import type { CanvasStore } from './canvasStore.types'
-import type { AppNode } from '@/lib/graph/nodeTypes'
+import type { AppNode, AppEdge } from '@/lib/graph/nodeTypes'
 
 export type ConnectionPathRole = 'trigger' | 'on-path' | null
 
+// ---------------------------------------------------------------------------
+// SVG Detection - Centralized logic for detecting SVG content
+// ---------------------------------------------------------------------------
+
+/** Check if a string contains SVG content. */
+export function isSvgContent(content: string | null | undefined): boolean {
+  return Boolean(content?.trim() && /<svg[\s>]/i.test(content.trim()))
+}
+
 // ---------------------------------------------------------------------------
 // Raw slices
 // ---------------------------------------------------------------------------
@@ -38,6 +47,65 @@ export function selectEdges(state: CanvasStore) {
   return state.graph.edges
 }
 
+// ---------------------------------------------------------------------------
+// Fine-grained selectors for optimal re-rendering
+// ---------------------------------------------------------------------------
+
+/** Get a specific node by ID. */
+export function selectNodeById(state: CanvasStore, nodeId: string): AppNode | undefined {
+  return state.graph.nodes.find((n) => n.id === nodeId)
+}
+
+/** Get multiple nodes by IDs. */
+export function selectNodesById(state: CanvasStore, nodeIds: string[]): AppNode[] {
+  return state.graph.nodes.filter((n) => nodeIds.includes(n.id))
+}
+
+/** Get nodes by type. */
+export function selectNodesByType(state: CanvasStore, nodeType: string): AppNode[] {
+  return state.graph.nodes.filter((n) => n.type === nodeType)
+}
+
+/** Get node IDs by type. */
+export function selectNodeIdsByType(state: CanvasStore, nodeType: string): string[] {
+  return state.graph.nodes.filter((n) => n.type === nodeType).map((n) => n.id)
+}
+
+/** Get edges by source node ID. */
+export function selectEdgesBySource(state: CanvasStore, sourceId: string): AppEdge[] {
+  return state.graph.edges.filter((e) => e.source === sourceId)
+}
+
+/** Get edges by target node ID. */
+export function selectEdgesByTarget(state: CanvasStore, targetId: string): AppEdge[] {
+  return state.graph.edges.filter((e) => e.target === targetId)
+}
+
+/** Get all edges connected to a node (source or target). */
+export function selectEdgesForNode(state: CanvasStore, nodeId: string): AppEdge[] {
+  return state.graph.edges.filter((e) => e.source === nodeId || e.target === nodeId)
+}
+
+/** Get node count. */
+export function selectNodeCount(state: CanvasStore): number {
+  return state.graph.nodes.length
+}
+
+/** Get edge count. */
+export function selectEdgeCount(state: CanvasStore): number {
+  return state.graph.edges.length
+}
+
+/** Check if a node exists. */
+export function selectHasNode(state: CanvasStore, nodeId: string): boolean {
+  return state.graph.nodes.some((n) => n.id === nodeId)
+}
+
+/** Check if an edge exists. */
+export function selectHasEdge(state: CanvasStore, source: string, target: string): boolean {
+  return state.graph.edges.some((e) => e.source === source && e.target === target)
+}
+
 // ---------------------------------------------------------------------------
 // Derived path (Sets) – depend on graph.edges + path primitive arrays
 // ---------------------------------------------------------------------------

frontend/src/app/canvas/useCanvasGraph.ts

@@ -1,89 +1,74 @@
 /**
  * Hook for canvas graph state and persistence. Wraps useGraphStateWithHistory
- * with initial graph from project storage (or example). Save is explicit via save();
- * autosave runs on an interval (~10s) and saves when the graph has changed.
+ * with initial graph from recollection storage (or example). Save is explicit via save().
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useGraphStateWithHistory } from '@/hooks/useGraphStateWithHistory'
 import { getInitialGraph } from '@/app/canvas/canvasGraphUtils'
-import { useCanvasStore } from '@/app/canvas/canvasStore'
-import { saveGraphToStorage, PROJECT_VERSION } from '@/app/pleroma/projectGraphStorage'
+import { saveGraphToStorage, RECOLLECTION_VERSION } from '@/app/recollections/state/recollectionGraphStorage'
 import type { AppNode, AppEdge } from '@/lib/graph/nodeTypes'
 
 export type SaveStatus = 'saved' | 'unsaved' | 'saving'
 
 export type UseCanvasGraphResult = ReturnType<typeof useGraphStateWithHistory> & {
-  /** Persist current nodes/edges to storage. No-op when projectId is missing. */
+  /** Persist current nodes/edges to storage. No-op when recollectionId is missing. */
   save: () => void
   /** For menubar: show "Unsaved changes" | "Saving…" | "All changes saved". */
   saveStatus: SaveStatus
 }
 
-const AUTOSAVE_INTERVAL_MS = 10_000
-
-export function useCanvasGraph(projectId: string | undefined): UseCanvasGraphResult {
-  const initialGraph = useMemo(() => getInitialGraph(projectId), [projectId])
+export function useCanvasGraph(recollectionId: string | undefined): UseCanvasGraphResult {
+  const initialGraph = useMemo(() => getInitialGraph(recollectionId), [recollectionId])
   const result = useGraphStateWithHistory(initialGraph.nodes, initialGraph.edges)
   const { nodes, edges } = result
 
-  const storeNodes = useCanvasStore((s) => s.graph.nodes)
-  const storeEdges = useCanvasStore((s) => s.graph.edges)
-
   const nodesRef = useRef(nodes)
   const edgesRef = useRef(edges)
   nodesRef.current = nodes
   edgesRef.current = edges
 
   const [isSaving, setIsSaving] = useState(false)
-  const lastSavedSnapshotRef = useRef(
+  const [lastSavedSerialized, setLastSavedSerialized] = useState(() =>
     JSON.stringify({ nodes: initialGraph.nodes, edges: initialGraph.edges })
   )
 
-  const serializedFromStore = useMemo(
-    () => JSON.stringify({ nodes: storeNodes, edges: storeEdges }),
-    [storeNodes, storeEdges]
+  const currentSerialized = useMemo(
+    () => JSON.stringify({ nodes, edges }),
+    [nodes, edges]
   )
-  const isDirty = serializedFromStore !== lastSavedSnapshotRef.current
+  const isDirty = currentSerialized !== lastSavedSerialized
   const saveStatus: SaveStatus = isSaving ? 'saving' : isDirty ? 'unsaved' : 'saved'
 
-  const performSave = useCallback(() => {
-    if (!projectId) return
-    const current = JSON.stringify({
-      nodes: nodesRef.current,
-      edges: edgesRef.current,
-    })
-    if (current === lastSavedSnapshotRef.current) return
-    setIsSaving(true)
-    saveGraphToStorage(projectId, {
-      version: PROJECT_VERSION,
-      nodes: nodesRef.current,
-      edges: edgesRef.current,
-    })
-    lastSavedSnapshotRef.current = current
-    setIsSaving(false)
-  }, [projectId])
-
   const save = useCallback(() => {
-    if (!projectId) return
+    if (!recollectionId) return
+    const snapshot = JSON.stringify({
+      nodes: nodesRef.current,
+      edges: edgesRef.current,
+    })
     setIsSaving(true)
-    saveGraphToStorage(projectId, {
-      version: PROJECT_VERSION,
+    saveGraphToStorage(recollectionId, {
+      version: RECOLLECTION_VERSION,
       nodes: nodesRef.current,
       edges: edgesRef.current,
     })
-    lastSavedSnapshotRef.current = JSON.stringify({
-      nodes: nodesRef.current,
-      edges: edgesRef.current,
-    })
-    setIsSaving(false)
-  }, [projectId])
+    const SAVING_DISPLAY_MS = 360
+    setTimeout(() => {
+      setLastSavedSerialized(snapshot)
+      setIsSaving(false)
+    }, SAVING_DISPLAY_MS)
+  }, [recollectionId])
 
+  // Auto-save after 5 seconds of inactivity when there are unsaved changes.
+  // Prevents data loss if the user closes the tab without pressing Ctrl+S.
+  const AUTO_SAVE_DELAY_MS = 5000
+  const saveRef = useRef(save)
+  saveRef.current = save
   useEffect(() => {
-    if (!projectId) return
-    const id = setInterval(performSave, AUTOSAVE_INTERVAL_MS)
-    return () => clearInterval(id)
-  }, [projectId, performSave])
+    if (!isDirty || !recollectionId) return
+    const timer = setTimeout(() => saveRef.current(), AUTO_SAVE_DELAY_MS)
+    return () => clearTimeout(timer)
+  }, [isDirty, recollectionId, currentSerialized])
 
   return { ...result, save, saveStatus }
 }

frontend/src/app/keroma/KeromaPage.tsx

@@ -1,20 +0,0 @@
-/**
- * Keroma page. Rendered at /keroma.
- */
-
-import React from 'react'
-
-export function KeromaPage() {
-  return (
-    <div className="relative flex flex-1 flex-col min-h-0 p-4">
-      <div className="flex flex-wrap items-center gap-3">
-        <h1 className="p-3 scroll-m-20 text-4xl font-extrabold tracking-tight text-balance font-serif">
-          Keroma
-        </h1>
-      </div>
-      <div className="rounded-lg border bg-card p-4 text-card-foreground shadow-sm">
-        <p className="text-muted-foreground">Welcome to Keroma.</p>
-      </div>
-    </div>
-  )
-}

frontend/src/app/kosmos/KosmosContext.tsx

@@ -1,16 +1,19 @@
 /**
- * Platform context: projects list and handlers for create/delete/rename/updateLastEdited/reorder/restore.
- * Used by AppSidebar, ProjectsTablePage, and canvas route.
+ * Platform context: recollections list and handlers for create/delete/rename/updateLastEdited/reorder/restore.
+ * Used by AppSidebar, RecollectionsPage, and canvas route.
  */
 
 import React, { createContext, useCallback, useContext, useMemo, useState } from 'react'
-import type { Project } from './types'
-import { saveGraphToStorage } from '@/app/pleroma/projectGraphStorage'
-import { PROJECT_VERSION } from '@/app/pleroma/projectGraphStorage'
+import type { Recollection } from './types'
+import { saveGraphToStorage, RECOLLECTION_VERSION } from '@/app/recollections/state/recollectionGraphStorage'
 
-const STORAGE_KEY = 'zui_platform_projects'
-const ORDER_STORAGE_KEY = 'zui_platform_project_order'
-const RECENT_STORAGE_KEY = 'zui_platform_recent_project_ids'
+const STORAGE_KEY = 'zui_platform_recollections'
+const ORDER_STORAGE_KEY = 'zui_platform_recollection_order'
+const RECENT_STORAGE_KEY = 'zui_platform_recent_recollection_ids'
+
+const LEGACY_STORAGE_KEY = 'zui_platform_emanations'
+const LEGACY_ORDER_STORAGE_KEY = 'zui_platform_emanation_order'
+const LEGACY_RECENT_STORAGE_KEY = 'zui_platform_recent_emanation_ids'
 const CANVAS_MINIMAP_KEY = 'zui_canvas_show_minimap'
 const AI_CONNECTION_KEY = 'zui_ai_connection'
 const RECENT_MAX = 5
@@ -72,8 +75,15 @@ function saveShowMinimap(value: boolean) {
 
 function loadOrder(): string[] {
   try {
-    const raw = localStorage.getItem(ORDER_STORAGE_KEY)
-    if (!raw) return []
+    let raw = localStorage.getItem(ORDER_STORAGE_KEY)
+    if (!raw) {
+      const legacy = localStorage.getItem(LEGACY_ORDER_STORAGE_KEY)
+      if (legacy) {
+        localStorage.setItem(ORDER_STORAGE_KEY, legacy)
+        localStorage.removeItem(LEGACY_ORDER_STORAGE_KEY)
+        raw = legacy
+      } else return []
+    }
     const parsed = JSON.parse(raw) as unknown
     return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === 'string') : []
   } catch {
@@ -87,8 +97,15 @@ function saveOrder(ids: string[]) {
 
 function loadRecentIds(): string[] {
   try {
-    const raw = localStorage.getItem(RECENT_STORAGE_KEY)
-    if (!raw) return []
+    let raw = localStorage.getItem(RECENT_STORAGE_KEY)
+    if (!raw) {
+      const legacy = localStorage.getItem(LEGACY_RECENT_STORAGE_KEY)
+      if (legacy) {
+        localStorage.setItem(RECENT_STORAGE_KEY, legacy)
+        localStorage.removeItem(LEGACY_RECENT_STORAGE_KEY)
+        raw = legacy
+      } else return []
+    }
     const parsed = JSON.parse(raw) as unknown
     return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === 'string').slice(0, RECENT_MAX) : []
   } catch {
@@ -100,41 +117,48 @@ function saveRecentIds(ids: string[]) {
   localStorage.setItem(RECENT_STORAGE_KEY, JSON.stringify(ids))
 }
 
-function loadProjects(): Project[] {
+function loadRecollections(): Recollection[] {
   try {
-    const raw = localStorage.getItem(STORAGE_KEY)
-    if (!raw) return []
+    let raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) {
+      const legacy = localStorage.getItem(LEGACY_STORAGE_KEY)
+      if (legacy) {
+        localStorage.setItem(STORAGE_KEY, legacy)
+        localStorage.removeItem(LEGACY_STORAGE_KEY)
+        raw = legacy
+      } else return []
+    }
     const parsed = JSON.parse(raw) as unknown
     if (!Array.isArray(parsed)) return []
     return parsed
       .filter(
-        (p): p is Project =>
+        (p): p is Recollection =>
           p &&
           typeof p === 'object' &&
-          typeof (p as Project).id === 'string' &&
-          typeof (p as Project).name === 'string' &&
-          typeof (p as Project).iconId === 'string' &&
-          typeof (p as Project).createdAt === 'number'
+          typeof (p as Recollection).id === 'string' &&
+          typeof (p as Recollection).name === 'string' &&
+          typeof (p as Recollection).iconId === 'string' &&
+          typeof (p as Recollection).createdAt === 'number'
       )
       .map((p) => ({
         ...p,
-        lastEditedAt: typeof (p as Project).lastEditedAt === 'number' ? (p as Project).lastEditedAt : p.createdAt,
+        lastEditedAt: typeof (p as Recollection).lastEditedAt === 'number' ? (p as Recollection).lastEditedAt : p.createdAt,
       }))
   } catch {
     return []
   }
 }
 
-function saveProjects(projects: Project[]) {
-  localStorage.setItem(STORAGE_KEY, JSON.stringify(projects))
+function saveRecollections(recollections: Recollection[]) {
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(recollections))
 }
 
 export type GraphSnapshot = { nodes: unknown[]; edges: unknown[] }
 
-/** Projects sorted by projectOrder, then by lastEditedAt desc for any not in order */
-export function sortProjectsByOrder(projects: Project[], order: string[]): Project[] {
-  const byId = new Map(projects.map((p) => [p.id, p]))
-  const ordered: Project[] = []
+/** Recollections sorted by recollectionOrder, then by lastEditedAt desc for any not in order */
+export function sortRecollectionsByOrder(recollections: Recollection[], order: string[]): Recollection[] {
+  const byId = new Map(recollections.map((p) => [p.id, p]))
+  const ordered: Recollection[] = []
   const seen = new Set<string>()
   for (const id of order) {
     const p = byId.get(id)
@@ -143,27 +167,27 @@ export function sortProjectsByOrder(projects: Project[], order: string[]): Proje
       seen.add(id)
     }
   }
-  const rest = projects
+  const rest = recollections
     .filter((p) => !seen.has(p.id))
     .sort((a, b) => (b.lastEditedAt ?? b.createdAt) - (a.lastEditedAt ?? a.createdAt))
   return [...ordered, ...rest]
 }
 
 export type KosmosContextValue = {
-  projects: Project[]
-  projectOrder: string[]
-  /** Projects in display order (sidebar order, then lastEditedAt) */
-  orderedProjects: Project[]
-  /** Last RECENT_MAX accessed project IDs (most recent first) */
-  recentProjectIds: string[]
-  recordProjectAccess: (id: string) => void
-  persist: (next: Project[]) => void
-  createProject: (project: Project) => void
-  deleteProject: (id: string) => void
-  renameProject: (id: string, name: string) => void
+  recollections: Recollection[]
+  recollectionOrder: string[]
+  /** Recollections in display order (sidebar order, then lastEditedAt) */
+  orderedRecollections: Recollection[]
+  /** Last RECENT_MAX accessed recollection IDs (most recent first) */
+  recentRecollectionIds: string[]
+  recordRecollectionAccess: (id: string) => void
+  persist: (next: Recollection[]) => void
+  createRecollection: (recollection: Recollection) => void
+  deleteRecollection: (id: string) => void
+  renameRecollection: (id: string, name: string) => void
   updateLastEdited: (id: string) => void
-  reorderProjects: (orderedIds: string[]) => void
-  restoreProject: (project: Project, graphSnapshot: GraphSnapshot | null) => void
+  reorderRecollections: (orderedIds: string[]) => void
+  restoreRecollection: (recollection: Recollection, graphSnapshot: GraphSnapshot | null) => void
   /** Canvas: show React Flow minimap (persisted) */
   showMinimap: boolean
   setShowMinimap: (value: boolean) => void
@@ -175,9 +199,9 @@ export type KosmosContextValue = {
 const KosmosContext = createContext<KosmosContextValue | null>(null)
 
 export function KosmosProvider({ children }: { children: React.ReactNode }) {
-  const [projects, setProjects] = useState<Project[]>(loadProjects)
-  const [projectOrder, setProjectOrder] = useState<string[]>(loadOrder)
-  const [recentProjectIds, setRecentProjectIds] = useState<string[]>(loadRecentIds)
+  const [recollections, setRecollections] = useState<Recollection[]>(loadRecollections)
+  const [recollectionOrder, setRecollectionOrder] = useState<string[]>(loadOrder)
+  const [recentRecollectionIds, setRecentRecollectionIds] = useState<string[]>(loadRecentIds)
   const [showMinimap, setShowMinimapState] = useState<boolean>(loadShowMinimap)
   const [aiConnection, setAiConnectionState] = useState<AiConnection>(loadAiConnection)
 
@@ -191,128 +215,128 @@ export function KosmosProvider({ children }: { children: React.ReactNode }) {
     saveAiConnection(value)
   }, [])
 
-  const persist = useCallback((next: Project[]) => {
-    setProjects(next)
-    saveProjects(next)
+  const persist = useCallback((next: Recollection[]) => {
+    setRecollections(next)
+    saveRecollections(next)
   }, [])
 
-  const createProject = useCallback(
-    (project: Project) => {
-      const withEdited = { ...project, lastEditedAt: project.createdAt }
-      persist([...projects, withEdited])
-      setProjectOrder((prev) => {
-        const next = prev.includes(project.id) ? prev : [project.id, ...prev]
+  const createRecollection = useCallback(
+    (recollection: Recollection) => {
+      const withEdited = { ...recollection, lastEditedAt: recollection.createdAt }
+      persist([...recollections, withEdited])
+      setRecollectionOrder((prev) => {
+        const next = prev.includes(recollection.id) ? prev : [recollection.id, ...prev]
         saveOrder(next)
         return next
       })
     },
-    [projects, persist]
+    [recollections, persist]
   )
 
-  const deleteProject = useCallback(
+  const deleteRecollection = useCallback(
     (id: string) => {
-      const next = projects.filter((p) => p.id !== id)
+      const next = recollections.filter((p) => p.id !== id)
       persist(next)
-      setProjectOrder((prev) => {
+      setRecollectionOrder((prev) => {
         const nextOrder = prev.filter((oid) => oid !== id)
         saveOrder(nextOrder)
         return nextOrder
       })
-      setRecentProjectIds((prev) => {
+      setRecentRecollectionIds((prev) => {
         const next = prev.filter((oid) => oid !== id)
         saveRecentIds(next)
         return next
       })
     },
-    [projects, persist]
+    [recollections, persist]
   )
 
-  const renameProject = useCallback(
+  const renameRecollection = useCallback(
     (id: string, name: string) => {
-      const next = projects.map((p) => (p.id === id ? { ...p, name } : p))
+      const next = recollections.map((p) => (p.id === id ? { ...p, name } : p))
       persist(next)
     },
-    [projects, persist]
+    [recollections, persist]
   )
 
   const updateLastEdited = useCallback(
     (id: string) => {
       const now = Date.now()
-      const next = projects.map((p) => (p.id === id ? { ...p, lastEditedAt: now } : p))
+      const next = recollections.map((p) => (p.id === id ? { ...p, lastEditedAt: now } : p))
       persist(next)
     },
-    [projects, persist]
+    [recollections, persist]
   )
 
-  const reorderProjects = useCallback((orderedIds: string[]) => {
-    setProjectOrder(orderedIds)
+  const reorderRecollections = useCallback((orderedIds: string[]) => {
+    setRecollectionOrder(orderedIds)
     saveOrder(orderedIds)
   }, [])
 
-  const recordProjectAccess = useCallback((id: string) => {
-    setRecentProjectIds((prev) => {
+  const recordRecollectionAccess = useCallback((id: string) => {
+    setRecentRecollectionIds((prev) => {
       const next = [id, ...prev.filter((x) => x !== id)].slice(0, RECENT_MAX)
       saveRecentIds(next)
       return next
     })
   }, [])
 
-  const restoreProject = useCallback(
-    (project: Project, graphSnapshot: GraphSnapshot | null) => {
-      persist([...projects, project])
-      setProjectOrder((prev) => {
-        const next = prev.includes(project.id) ? prev : [project.id, ...prev]
+  const restoreRecollection = useCallback(
+    (recollection: Recollection, graphSnapshot: GraphSnapshot | null) => {
+      persist([...recollections, recollection])
+      setRecollectionOrder((prev) => {
+        const next = prev.includes(recollection.id) ? prev : [recollection.id, ...prev]
         saveOrder(next)
         return next
       })
       if (graphSnapshot) {
-        saveGraphToStorage(project.id, {
-          version: PROJECT_VERSION,
+        saveGraphToStorage(recollection.id, {
+          version: RECOLLECTION_VERSION,
           nodes: graphSnapshot.nodes,
           edges: graphSnapshot.edges,
         })
       }
     },
-    [projects, persist]
+    [recollections, persist]
   )
 
-  const orderedProjects = useMemo(
-    () => sortProjectsByOrder(projects, projectOrder),
-    [projects, projectOrder]
+  const orderedRecollections = useMemo(
+    () => sortRecollectionsByOrder(recollections, recollectionOrder),
+    [recollections, recollectionOrder]
   )
 
   const value: KosmosContextValue = useMemo(
     () => ({
-      projects,
-      projectOrder,
-      orderedProjects,
-      recentProjectIds,
-      recordProjectAccess,
+      recollections,
+      recollectionOrder,
+      orderedRecollections,
+      recentRecollectionIds,
+      recordRecollectionAccess,
       persist,
-      createProject,
-      deleteProject,
-      renameProject,
+      createRecollection,
+      deleteRecollection,
+      renameRecollection,
       updateLastEdited,
-      reorderProjects,
-      restoreProject,
+      reorderRecollections,
+      restoreRecollection,
       showMinimap,
       setShowMinimap,
       aiConnection,
       setAiConnection,
     }),
     [
-      projects,
-      projectOrder,
-      orderedProjects,
-      recentProjectIds,
-      recordProjectAccess,
+      recollections,
+      recollectionOrder,
+      orderedRecollections,
+      recentRecollectionIds,
+      recordRecollectionAccess,
       persist,
-      createProject,
-      deleteProject,
-      renameProject,
+      createRecollection,
+      deleteRecollection,
+      renameRecollection,
       updateLastEdited,
-      reorderProjects,
-      restoreProject,
+      reorderRecollections,
+      restoreRecollection,
       showMinimap,
       setShowMinimap,
       aiConnection,

frontend/src/app/kosmos/KosmosPage.tsx

@@ -1,5 +1,5 @@
 /**
- * Platform: main layout with sidebar and header. Renders child routes (projects list or canvas) via Outlet.
+ * Platform: main layout with sidebar and header. Renders child routes (recollections list or canvas) via Outlet.
  */
 
 import React, { useEffect, useState } from 'react'
@@ -9,17 +9,19 @@ import { KosmosProvider, usePlatform } from './KosmosContext'
 import { KosmosSidebar } from './KosmosSidebar'
 
 function KosmosLayoutInner() {
-  const { projectId } = useParams<{ projectId: string }>()
-  const { recordProjectAccess } = usePlatform()
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const { recordRecollectionAccess } = usePlatform()
   const [sidebarOpen, setSidebarOpen] = useState(true)
 
   useEffect(() => {
-    if (projectId) recordProjectAccess(projectId)
-  }, [projectId, recordProjectAccess])
+    if (recollectionId) recordRecollectionAccess(recollectionId)
+  }, [recollectionId, recordRecollectionAccess])
+
+  const showSidebar = !recollectionId
 
   return (
     <SidebarProvider open={sidebarOpen} onOpenChange={setSidebarOpen}>
-      <KosmosSidebar />
+      {showSidebar && <KosmosSidebar />}
       <div className="relative flex h-dvh min-h-0 w-full flex-1 flex-col overflow-hidden bg-background">
         <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
           <Outlet />

frontend/src/app/kosmos/KosmosSidebar.tsx

@@ -1,5 +1,5 @@
 /**
- * Platform sidebar: All projects, Recently used, New project.
+ * Platform sidebar: Recollections, Recently used, New recollection.
  */
 
 import React, { useCallback, useMemo } from 'react'
@@ -17,36 +17,34 @@ import {
   SidebarRail,
   SidebarTrigger,
 } from '@/components/ui/sidebar'
-import { Plus, Settings, Triangle } from 'lucide-react'
+import { Plus, Settings } from 'lucide-react'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { useSidebar } from '@/components/ui/sidebar'
 import { usePlatform } from './KosmosContext'
-import { getProjectIcon } from '@/lib/iconMap'
-import { NewProjectDialog } from './NewProjectDialog'
+import { getRecollectionIcon } from '@/lib/iconMap'
+import { RecollectionsIcon } from '@/lib/icons'
+import { NewRecollectionDialog } from './NewRecollectionDialog'
 import { SettingsDialog } from './SettingsDialog'
-import type { Project } from './types'
+import type { Recollection } from './types'
 
 export function KosmosSidebar() {
   const { state, setOpen } = useSidebar()
   const isCollapsed = state === 'collapsed'
-  const { orderedProjects, createProject, recentProjectIds } = usePlatform()
-  const recentProjects = useMemo(() => {
-    const byId = new Map(orderedProjects.map((p) => [p.id, p]))
-    return recentProjectIds.map((id) => byId.get(id)).filter((p): p is Project => p != null)
-  }, [orderedProjects, recentProjectIds])
+  const { orderedRecollections, createRecollection, recentRecollectionIds } = usePlatform()
+  const recentRecollections = useMemo(() => {
+    const byId = new Map(orderedRecollections.map((p) => [p.id, p]))
+    return recentRecollectionIds.map((id) => byId.get(id)).filter((p): p is Recollection => p != null)
+  }, [orderedRecollections, recentRecollectionIds])
   const navigate = useNavigate()
   const location = useLocation()
-  const { projectId: selectedProjectId } = useParams<{ projectId: string }>()
-  const isKeroma = location.pathname === '/keroma'
+  const { recollectionId: selectedRecollectionId } = useParams<{ recollectionId: string }>()
 
-  const handleSelectProject = useCallback((id: string) => navigate(`/projects/${id}`), [navigate])
-
-  const handleCreateProject = useCallback(
-    (project: Parameters<typeof createProject>[0]) => {
-      createProject(project)
-      navigate(`/projects/${project.id}`)
+  const handleCreateRecollection = useCallback(
+    (recollection: Parameters<typeof createRecollection>[0]) => {
+      createRecollection(recollection)
+      navigate(`/recollections/${recollection.id}`)
     },
-    [createProject, navigate]
+    [createRecollection, navigate]
   )
 
   return (
@@ -99,8 +97,8 @@ export function KosmosSidebar() {
                 </Tooltip>
               ) : (
                 <SidebarMenuButton asChild size="lg" tooltip="Zoë" className="font-semibold font-serif">
-                  <Link to="/projects">
-                    <span className="flex size-8 min-w-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground dark:bg-white dark:text-black">
+                  <Link to="/recollections">
+                    <span className="flex size-8 min-w-8 items-center justify-center rounded-lg dark:bg-white dark:text-black">
                       <span
                         className="size-6 shrink-0 rounded-[2px] opacity-90"
                         style={{
@@ -132,39 +130,29 @@ export function KosmosSidebar() {
           <SidebarGroup>
             <SidebarMenu>
               <SidebarMenuItem>
-                <SidebarMenuButton asChild tooltip="All projects" isActive={location.pathname === '/projects' && !selectedProjectId}>
-                  <Link to="/projects">
-                    <Triangle className="size-4" />
-                    <span>Pleroma</span>
-                  </Link>
-                </SidebarMenuButton>
-              </SidebarMenuItem>
-              <SidebarMenuItem>
-                <SidebarMenuButton asChild tooltip="Keroma" isActive={isKeroma}>
-                  <Link to="/keroma">
-                    <Triangle className="size-4 rotate-180" />
-                    <span>Keroma</span>
+                <SidebarMenuButton asChild tooltip="Recollections" isActive={location.pathname === '/recollections' && !selectedRecollectionId}>
+                  <Link to="/recollections">
+                    <RecollectionsIcon className="size-4 shrink-0" />
+                    <span>Recollections</span>
                   </Link>
                 </SidebarMenuButton>
               </SidebarMenuItem>
             </SidebarMenu>
           </SidebarGroup>
-          {recentProjects.length > 0 && (
+          {recentRecollections.length > 0 && (
             <SidebarGroup>
               <SidebarGroupLabel className="group-data-[collapsible=icon]:hidden">Recently used</SidebarGroupLabel>
               <SidebarMenu>
-                {recentProjects.map((project) => {
-                  const Icon = getProjectIcon(project.iconId)
-                  const isActive = selectedProjectId === project.id
+                {recentRecollections.map((recollection) => {
+                  const Icon = getRecollectionIcon(recollection.iconId)
+                  const isActive = selectedRecollectionId === recollection.id
                   return (
-                    <SidebarMenuItem key={project.id}>
-                      <SidebarMenuButton
-                        tooltip={project.name}
-                        isActive={isActive}
-                        onClick={() => handleSelectProject(project.id)}
-                      >
-                        <Icon className="size-4" />
-                        <span>{project.name}</span>
+                    <SidebarMenuItem key={recollection.id}>
+                      <SidebarMenuButton asChild tooltip={recollection.name} isActive={isActive}>
+                        <Link to={`/recollections/${recollection.id}`}>
+                          <Icon className="size-4" />
+                          <span>{recollection.name}</span>
+                        </Link>
                       </SidebarMenuButton>
                     </SidebarMenuItem>
                   )
@@ -175,13 +163,13 @@ export function KosmosSidebar() {
           <SidebarGroup>
             <SidebarMenu>
               <SidebarMenuItem>
-                <NewProjectDialog
-                  onCreate={handleCreateProject}
-                  existingNames={orderedProjects.map((p) => p.name)}
+                <NewRecollectionDialog
+                  onCreate={handleCreateRecollection}
+                  existingNames={orderedRecollections.map((p) => p.name)}
                   trigger={
                     <SidebarMenuButton className="text-sidebar-foreground/70 w-full cursor-pointer">
                       <Plus className="size-4" />
-                      <span>{orderedProjects.length === 0 ? 'Create your first project' : 'New project'}</span>
+                      <span>{orderedRecollections.length === 0 ? 'Create your first recollection' : 'New recollection'}</span>
                     </SidebarMenuButton>
                   }
                 />

frontend/src/app/kosmos/NewRecollectionDialog.tsx

@@ -1,5 +1,5 @@
 /**
- * Dialog to create a new project: name + icon.
+ * Dialog to create a new recollection: name + icon.
  */
 
 import React, { useState } from 'react'
@@ -16,20 +16,20 @@ import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
 import { Plus } from 'lucide-react'
-import { PROJECT_ICON_IDS, type Project, type ProjectIconId } from './types'
-import { getProjectIcon } from '@/lib/iconMap'
+import { RECOLLECTION_ICON_IDS, type Recollection, type RecollectionIconId } from './types'
+import { getRecollectionIcon } from '@/lib/iconMap'
 
-type NewProjectDialogProps = {
-  onCreate: (project: Project) => void
+type NewRecollectionDialogProps = {
+  onCreate: (recollection: Recollection) => void
   trigger?: React.ReactNode
-  /** Other project names to check for duplicates (case-insensitive warning only) */
+  /** Other recollection names to check for duplicates (case-insensitive warning only) */
   existingNames?: string[]
 }
 
-export function NewProjectDialog({ onCreate, trigger, existingNames = [] }: NewProjectDialogProps) {
+export function NewRecollectionDialog({ onCreate, trigger, existingNames = [] }: NewRecollectionDialogProps) {
   const [open, setOpen] = useState(false)
   const [name, setName] = useState('')
-  const [iconId, setIconId] = useState<ProjectIconId>('cat')
+  const [iconId, setIconId] = useState<RecollectionIconId>('cat')
 
   const trimmed = name.trim()
   const isDuplicate = trimmed.length > 0 && existingNames.some((n) => n.toLowerCase() === trimmed.toLowerCase())
@@ -37,13 +37,13 @@ export function NewProjectDialog({ onCreate, trigger, existingNames = [] }: NewP
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault()
     if (!trimmed) return
-    const project: Project = {
-      id: `proj_${Date.now()}`,
+    const recollection: Recollection = {
+      id: `recollection_${Date.now()}`,
       name: trimmed,
       iconId,
       createdAt: Date.now(),
     }
-    onCreate(project)
+    onCreate(recollection)
     setName('')
     setIconId('cat')
     setOpen(false)
@@ -55,41 +55,41 @@ export function NewProjectDialog({ onCreate, trigger, existingNames = [] }: NewP
         {trigger ?? (
           <Button variant="outline" size="sm" className="w-full justify-start gap-2">
             <Plus className="size-4" />
-            New project
+            New recollection
           </Button>
         )}
       </DialogTrigger>
       <DialogContent className="sm:max-w-md">
         <form onSubmit={handleSubmit}>
           <DialogHeader>
-            <DialogTitle>New project</DialogTitle>
-            <DialogDescription>Create a project to start editing a graph canvas.</DialogDescription>
+            <DialogTitle>New recollection</DialogTitle>
+            <DialogDescription>Create a recollection to start editing a graph canvas.</DialogDescription>
           </DialogHeader>
           <div className="grid gap-4 py-4">
             <div className="grid gap-2">
-              <label htmlFor="project-name" className="text-sm font-medium">
+              <label htmlFor="recollection-name" className="text-sm font-medium">
                 Name
               </label>
               <Input
-                id="project-name"
+                id="recollection-name"
                 value={name}
                 onChange={(e) => setName(e.target.value)}
-                placeholder="My project"
+                placeholder="My recollection"
                 autoFocus
               />
               {isDuplicate && (
-                <p className="text-xs text-amber-600 dark:text-amber-500">A project with this name already exists.</p>
+                <p className="text-xs text-amber-600 dark:text-amber-500">A recollection with this name already exists.</p>
               )}
             </div>
             <div className="grid gap-2">
               <label className="text-sm font-medium">Icon</label>
-              <Select value={iconId} onValueChange={(v) => setIconId(v as ProjectIconId)}>
+              <Select value={iconId} onValueChange={(v) => setIconId(v as RecollectionIconId)}>
                 <SelectTrigger>
                   <SelectValue />
                 </SelectTrigger>
                 <SelectContent>
-                  {PROJECT_ICON_IDS.map((id) => {
-                    const Icon = getProjectIcon(id)
+                  {RECOLLECTION_ICON_IDS.map((id) => {
+                    const Icon = getRecollectionIcon(id)
                     return (
                       <SelectItem key={id} value={id}>
                         <span className="flex items-center gap-2">

frontend/src/app/kosmos/types.ts

@@ -1,21 +1,21 @@
 /**
- * Platform types: projects and sidebar state.
+ * Platform types: recollections and sidebar state.
  */
 
 import type { LucideIcon } from 'lucide-react'
 
-export type Project = {
+export type Recollection = {
   id: string
   name: string
-  /** Icon identifier: key of PROJECT_ICONS map */
+  /** Icon identifier: key of RECOLLECTION_ICONS map */
   iconId: string
   createdAt: number
-  /** Last time the project was opened/edited; used for sorting. Defaults to createdAt if missing. */
+  /** Last time the recollection was opened/edited; used for sorting. Defaults to createdAt if missing. */
   lastEditedAt?: number
 }
 
-/** Project icon ids: Lucide "Animals" category only */
-export const PROJECT_ICON_IDS = [
+/** Recollection icon ids: Lucide "Animals" category only */
+export const RECOLLECTION_ICON_IDS = [
   'bird',
   'bug',
   'cat',
@@ -30,4 +30,4 @@ export const PROJECT_ICON_IDS = [
   'egg'
 ] as const
 
-export type ProjectIconId = (typeof PROJECT_ICON_IDS)[number]
+export type RecollectionIconId = (typeof RECOLLECTION_ICON_IDS)[number]

frontend/src/app/pleroma/projectGraphStorage.ts

@@ -1,37 +0,0 @@
-/**
- * Per-project graph persistence (localStorage).
- * Saves and loads StoredGraphState (version + nodes + edges). Used by useCanvasGraph and export.
- */
-
-import type { StoredGraphState } from '@/lib/graph/state'
-
-export type { StoredGraphState }
-export const PROJECT_FILE_EXT = '.zui.json'
-export const PROJECT_VERSION = 1
-
-const GRAPH_KEY_PREFIX = 'zui_graph_'
-
-export function getGraphStorageKey(projectId: string): string {
-  return `${GRAPH_KEY_PREFIX}${projectId}`
-}
-
-export function loadGraphFromStorage(projectId: string): StoredGraphState | null {
-  try {
-    const raw = localStorage.getItem(getGraphStorageKey(projectId))
-    if (!raw) return null
-    const data = JSON.parse(raw) as unknown
-    if (!data || typeof data !== 'object' || !Array.isArray((data as StoredGraphState).nodes) || !Array.isArray((data as StoredGraphState).edges))
-      return null
-    return data as StoredGraphState
-  } catch {
-    return null
-  }
-}
-
-export function saveGraphToStorage(projectId: string, state: StoredGraphState): void {
-  localStorage.setItem(getGraphStorageKey(projectId), JSON.stringify(state))
-}
-
-export function removeGraphFromStorage(projectId: string): void {
-  localStorage.removeItem(getGraphStorageKey(projectId))
-}

frontend/src/app/recollections/RecollectionLayout.tsx

@@ -0,0 +1,65 @@
+/**
+ * Layout for a single recollection: shared menubar and nested routes for Logos / Katalogos / Flux.
+ */
+
+import React, { useEffect } from 'react'
+import { Outlet, useParams, useNavigate } from 'react-router-dom'
+import { toast } from 'sonner'
+import { usePlatform } from '@/app/kosmos/KosmosContext'
+import { RecollectionActionsProvider } from './layout/RecollectionActionsContext'
+import { RecollectionSidebarProvider } from './layout/RecollectionSidebarContext'
+import { RecollectionMenubar } from './layout/RecollectionMenubar'
+import { RecollectionSidebar } from './layout/RecollectionSidebar'
+
+export function RecollectionLayout() {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const navigate = useNavigate()
+  const { recollections, recordRecollectionAccess } = usePlatform()
+
+  useEffect(() => {
+    if (recollectionId) recordRecollectionAccess(recollectionId)
+  }, [recollectionId, recordRecollectionAccess])
+
+  const recollection = recollectionId ? recollections.find((p) => p.id === recollectionId) : null
+
+  useEffect(() => {
+    if (!recollectionId) return
+    if (recollection) return
+    toast.error('Recollection not found')
+    navigate('/recollections', { replace: true })
+  }, [recollectionId, recollection, navigate])
+
+  // Keyboard shortcut: Escape to go back to recollections list
+  useEffect(() => {
+    if (!recollection) return
+    const onKeyDown = (ev: KeyboardEvent) => {
+      if (ev.key !== 'Escape') return
+      if ((ev.target as HTMLElement)?.closest('input, textarea, [contenteditable="true"]')) return
+      ev.preventDefault()
+      navigate('/recollections')
+    }
+    window.addEventListener('keydown', onKeyDown, true)
+    return () => window.removeEventListener('keydown', onKeyDown, true)
+  }, [recollection, navigate])
+
+  if (!recollectionId) return null
+  if (!recollection) {
+    return null
+  }
+
+  return (
+    <RecollectionActionsProvider>
+      <RecollectionSidebarProvider>
+        <div className="flex min-h-0 flex-1 flex-col">
+          <RecollectionMenubar />
+          <div className="flex min-h-0 flex-1 flex-row overflow-hidden">
+            <RecollectionSidebar />
+            <div className="flex min-w-0 flex-1 flex-col overflow-hidden">
+              <Outlet />
+            </div>
+          </div>
+        </div>
+      </RecollectionSidebarProvider>
+    </RecollectionActionsProvider>
+  )
+}

frontend/src/app/recollections/RecollectionsPage.tsx

@@ -1,5 +1,5 @@
 /**
- * Projects list page: table or cards view with search, sort, pagination, actions.
+ * Recollections list page: table or cards view with search, sort, pagination, actions.
  * Sort by last edited (default), name, or created; configurable page size; export toast; undo delete.
  */
 
@@ -56,18 +56,20 @@ import {
 } from 'lucide-react'
 import { Checkbox } from '@/components/ui/checkbox'
 import { usePlatform } from '@/app/kosmos/KosmosContext'
-import { getProjectIcon } from '@/lib/iconMap'
+import { getRecollectionIcon } from '@/lib/iconMap'
 import {
   loadGraphFromStorage,
   saveGraphToStorage,
   removeGraphFromStorage,
-  PROJECT_FILE_EXT,
-  PROJECT_VERSION,
-} from './projectGraphStorage'
+  RECOLLECTION_FILE_EXT,
+  RECOLLECTION_VERSION,
+} from './state/recollectionGraphStorage'
+import { getLogosContent, setLogosContent } from './state/recollectionStore'
 import { toast } from 'sonner'
-import { NewProjectDialog } from '@/app/kosmos/NewProjectDialog'
-import { ProjectsPageBackground } from './ProjectsPageBackground'
-import type { Project } from '@/app/kosmos/types'
+import { NewRecollectionDialog } from '@/app/kosmos/NewRecollectionDialog'
+import { RecollectionsPageBackground } from './layout/RecollectionsPageBackground'
+import { RenameRecollectionDialog } from './layout/RenameRecollectionDialog'
+import type { Recollection } from '@/app/kosmos/types'
 
 const PAGE_SIZE_OPTIONS = [10, 25, 50] as const
 type SortKey = 'lastEdited' | 'name' | 'created'
@@ -98,8 +100,8 @@ function getRelativeTime(ts: number): string {
   return 'Just now'
 }
 
-function getGraphCounts(projectId: string): { nodes: number; edges: number } {
-  const stored = loadGraphFromStorage(projectId)
+function getGraphCounts(recollectionId: string): { nodes: number; edges: number } {
+  const stored = loadGraphFromStorage(recollectionId)
   if (!stored) return { nodes: 0, edges: 0 }
   return {
     nodes: Array.isArray(stored.nodes) ? stored.nodes.length : 0,
@@ -110,7 +112,7 @@ function getGraphCounts(projectId: string): { nodes: number; edges: number } {
 type NodeLike = { id: string; position?: { x: number; y: number } }
 type EdgeLike = { id?: string; source: string; target: string }
 
-/** Shared grid style for empty thumbnail, non-empty thumbnail SVG, and New project placeholder. */
+/** Shared grid style for empty thumbnail, non-empty thumbnail SVG, and New recollection placeholder. */
 const THUMBNAIL_GRID = {
   baseFill: 'hsl(var(--muted) / 0.4)',
   dotFill: 'hsl(var(--muted-foreground) / 0.06)',
@@ -124,13 +126,13 @@ const thumbnailGridStyle: React.CSSProperties = {
 }
 
 /** Renders a minimal SVG preview of the graph from storage, or a placeholder. */
-function GraphThumbnail({ projectId, className }: { projectId: string; className?: string }) {
-  const stored = loadGraphFromStorage(projectId)
+function GraphThumbnail({ recollectionId, className }: { recollectionId: string; className?: string }) {
+  const stored = loadGraphFromStorage(recollectionId)
   const nodes = (stored?.nodes ?? []) as NodeLike[]
   const edges = (stored?.edges ?? []) as EdgeLike[]
   const withPos = nodes.filter((n) => n.position && typeof n.position.x === 'number' && typeof n.position.y === 'number')
 
-  const dotGridPatternId = `dotgrid-${projectId.replace(/\W/g, '-')}`
+  const dotGridPatternId = `dotgrid-${recollectionId.replace(/\W/g, '-')}`
 
   if (withPos.length === 0) {
     return (
@@ -207,47 +209,47 @@ function GraphThumbnail({ projectId, className }: { projectId: string; className
   )
 }
 
-type ProjectActionsMenuProps = {
-  project: Project
+type RecollectionActionsMenuProps = {
+  recollection: Recollection
   onOpen: (id: string) => void
-  onRenameOpen: (project: Project) => void
-  onDuplicateOpen: (project: Project) => void
-  onExport: (project: Project) => void
-  onDeleteOpen: (project: Project) => void
+  onRenameOpen: (recollection: Recollection) => void
+  onDuplicateOpen: (recollection: Recollection) => void
+  onExport: (recollection: Recollection) => void
+  onDeleteOpen: (recollection: Recollection) => void
   trigger: React.ReactNode
 }
 
-function ProjectActionsMenu({
-  project,
+function RecollectionActionsMenu({
+  recollection,
   onOpen,
   onRenameOpen,
   onDuplicateOpen,
   onExport,
   onDeleteOpen,
   trigger,
-}: ProjectActionsMenuProps) {
+}: RecollectionActionsMenuProps) {
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>{trigger}</DropdownMenuTrigger>
       <DropdownMenuContent align="end">
-        <DropdownMenuItem onClick={() => onOpen(project.id)}>
+        <DropdownMenuItem onClick={() => onOpen(recollection.id)}>
           <FolderOpen className="size-4" />
           Open
         </DropdownMenuItem>
-        <DropdownMenuItem onClick={() => onRenameOpen(project)}>
+        <DropdownMenuItem onClick={() => onRenameOpen(recollection)}>
           <Pencil className="size-4" />
           Rename
         </DropdownMenuItem>
-        <DropdownMenuItem onClick={() => onDuplicateOpen(project)}>
+        <DropdownMenuItem onClick={() => onDuplicateOpen(recollection)}>
           <Copy className="size-4" />
           Duplicate
         </DropdownMenuItem>
-        <DropdownMenuItem onClick={() => onExport(project)}>
+        <DropdownMenuItem onClick={() => onExport(recollection)}>
           <Download className="size-4" />
           Export
         </DropdownMenuItem>
         <DropdownMenuSeparator />
-        <DropdownMenuItem className="text-destructive focus:text-destructive" onClick={() => onDeleteOpen(project)}>
+        <DropdownMenuItem className="text-destructive focus:text-destructive" onClick={() => onDeleteOpen(recollection)}>
           <Trash2 className="size-4" />
           Delete
         </DropdownMenuItem>
@@ -258,8 +260,11 @@ function ProjectActionsMenu({
 
 export type ViewMode = 'table' | 'cards'
 
-export function ProjectsPage() {
-  const { orderedProjects, deleteProject, renameProject, createProject, restoreProject } = usePlatform()
+const RECOLLECTIONS_SCROLL_KEY = 'recollections-list-scroll'
+
+export function RecollectionsPage() {
+  const scrollContainerRef = React.useRef<HTMLDivElement>(null)
+  const { orderedRecollections, deleteRecollection, renameRecollection, createRecollection, restoreRecollection } = usePlatform()
   const navigate = useNavigate()
   const [viewMode, setViewMode] = useState<ViewMode>('cards')
   const [search, setSearch] = useState('')
@@ -267,21 +272,19 @@ export function ProjectsPage() {
   const [page, setPage] = useState(0)
   const [sortKey, setSortKey] = useState<SortKey>('lastEdited')
   const [sortDir, setSortDir] = useState<SortDir>('desc')
-  const [renameTarget, setRenameTarget] = useState<Project | null>(null)
-  const [renameValue, setRenameValue] = useState('')
-  const renameInputRef = React.useRef<HTMLInputElement>(null)
-  const [deleteTarget, setDeleteTarget] = useState<Project | null>(null)
-  const [duplicateTarget, setDuplicateTarget] = useState<Project | null>(null)
+  const [renameTarget, setRenameTarget] = useState<Recollection | null>(null)
+  const [deleteTarget, setDeleteTarget] = useState<Recollection | null>(null)
+  const [duplicateTarget, setDuplicateTarget] = useState<Recollection | null>(null)
   const [duplicateName, setDuplicateName] = useState('')
   const duplicateInputRef = React.useRef<HTMLInputElement>(null)
   const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())
-  const [bulkDeleteTargets, setBulkDeleteTargets] = useState<Project[] | null>(null)
+  const [bulkDeleteTargets, setBulkDeleteTargets] = useState<Recollection[] | null>(null)
 
   const filtered = useMemo(() => {
     const q = search.trim().toLowerCase()
-    if (!q) return orderedProjects
-    return orderedProjects.filter((p) => p.name.toLowerCase().includes(q))
-  }, [orderedProjects, search])
+    if (!q) return orderedRecollections
+    return orderedRecollections.filter((p) => p.name.toLowerCase().includes(q))
+  }, [orderedRecollections, search])
 
   const sorted = useMemo(() => {
     const arr = [...filtered]
@@ -312,24 +315,16 @@ export function ProjectsPage() {
   }
 
   const handleOpen = useCallback(
-    (projectId: string) => {
-      navigate(`/projects/${projectId}`)
+    (recollectionId: string) => {
+      navigate(`/recollections/${recollectionId}`)
     },
     [navigate]
   )
 
-  const handleRenameOpen = useCallback((project: Project) => {
-    setRenameTarget(project)
-    setRenameValue(project.name)
+  const handleRenameOpen = useCallback((recollection: Recollection) => {
+    setRenameTarget(recollection)
   }, [])
 
-  React.useEffect(() => {
-    if (renameTarget) {
-      const t = setTimeout(() => renameInputRef.current?.focus(), 0)
-      return () => clearTimeout(t)
-    }
-  }, [renameTarget])
-
   React.useEffect(() => {
     if (duplicateTarget) {
       const t = setTimeout(() => duplicateInputRef.current?.focus(), 0)
@@ -337,49 +332,63 @@ export function ProjectsPage() {
     }
   }, [duplicateTarget])
 
-  const handleRenameSubmit = useCallback(() => {
-    if (renameTarget && renameValue.trim()) {
-      renameProject(renameTarget.id, renameValue.trim())
-      setRenameTarget(null)
-      setRenameValue('')
+  // Restore scroll position when returning to the list
+  React.useEffect(() => {
+    const el = scrollContainerRef.current
+    if (!el) return
+    try {
+      const saved = sessionStorage.getItem(RECOLLECTIONS_SCROLL_KEY)
+      if (saved !== null) {
+        const top = parseInt(saved, 10)
+        if (Number.isFinite(top)) requestAnimationFrame(() => { el.scrollTop = top })
+      }
+    } catch {
+      /* ignore */
     }
-  }, [renameTarget, renameValue, renameProject])
+    return () => {
+      try {
+        sessionStorage.setItem(RECOLLECTIONS_SCROLL_KEY, String(el.scrollTop))
+      } catch {
+        /* ignore */
+      }
+    }
+  }, [])
 
-  const handleDeleteOpen = useCallback((project: Project) => {
-    setDeleteTarget(project)
+  const handleDeleteOpen = useCallback((recollection: Recollection) => {
+    setDeleteTarget(recollection)
   }, [])
 
   const handleDeleteConfirm = useCallback(() => {
     if (!deleteTarget) return
-    const project = deleteTarget
-    const graphSnapshot = loadGraphFromStorage(project.id)
+    const recollection = deleteTarget
+    const graphSnapshot = loadGraphFromStorage(recollection.id)
     const snapshot =
       graphSnapshot && (graphSnapshot.nodes.length > 0 || graphSnapshot.edges.length > 0)
         ? { nodes: graphSnapshot.nodes, edges: graphSnapshot.edges }
         : null
-    removeGraphFromStorage(project.id)
-    deleteProject(project.id)
+    removeGraphFromStorage(recollection.id)
+    deleteRecollection(recollection.id)
     setDeleteTarget(null)
-    navigate('/projects', { replace: true })
-    toast(`"${project.name}" deleted`, {
+    navigate('/recollections', { replace: true })
+    toast(`"${recollection.name}" deleted`, {
       action: {
         label: 'Undo',
-        onClick: () => restoreProject(project, snapshot),
+        onClick: () => restoreRecollection(recollection, snapshot),
       },
       duration: 8000,
     })
-  }, [deleteTarget, deleteProject, navigate, restoreProject])
+  }, [deleteTarget, deleteRecollection, navigate, restoreRecollection])
 
   const handleExport = useCallback(
-    (project: Project) => {
-      const stored = loadGraphFromStorage(project.id)
+    (recollection: Recollection) => {
+      const stored = loadGraphFromStorage(recollection.id)
       const state = stored
-        ? { version: PROJECT_VERSION, nodes: stored.nodes, edges: stored.edges }
-        : { version: PROJECT_VERSION, nodes: [], edges: [] }
+        ? { version: RECOLLECTION_VERSION, nodes: stored.nodes, edges: stored.edges }
+        : { version: RECOLLECTION_VERSION, nodes: [], edges: [] }
       const blob = new Blob([JSON.stringify(state, null, 2)], { type: 'application/json' })
       const url = URL.createObjectURL(blob)
       const a = document.createElement('a')
-      const filename = `${project.name.replace(/[^\w.-]/g, '_')}${PROJECT_FILE_EXT}`
+      const filename = `${recollection.name.replace(/[^\w.-]/g, '_')}${RECOLLECTION_FILE_EXT}`
       a.href = url
       a.download = filename
       a.click()
@@ -389,40 +398,44 @@ export function ProjectsPage() {
     []
   )
 
-  const handleCreateProject = useCallback(
-    (project: Project) => {
-      createProject(project)
-      navigate(`/projects/${project.id}`)
+  const handleCreateRecollection = useCallback(
+    (recollection: Recollection) => {
+      createRecollection(recollection)
+      navigate(`/recollections/${recollection.id}`)
     },
-    [createProject, navigate]
+    [createRecollection, navigate]
   )
 
-  const handleDuplicateOpen = useCallback((project: Project) => {
-    setDuplicateTarget(project)
-    setDuplicateName(`${project.name} (copy)`)
+  const handleDuplicateOpen = useCallback((recollection: Recollection) => {
+    setDuplicateTarget(recollection)
+    setDuplicateName(`${recollection.name} (copy)`)
   }, [])
 
   const handleDuplicateConfirm = useCallback(() => {
     if (!duplicateTarget || !duplicateName.trim()) return
     const name = duplicateName.trim()
-    const newId = `proj_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`
+    const newId = `recollection_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`
     const now = Date.now()
-    const newProject: Project = {
+    const newRecollection: Recollection = {
       id: newId,
       name,
       iconId: duplicateTarget.iconId,
       createdAt: now,
       lastEditedAt: now,
     }
-    createProject(newProject)
+    createRecollection(newRecollection)
     const graph = loadGraphFromStorage(duplicateTarget.id)
     if (graph && (graph.nodes.length > 0 || graph.edges.length > 0)) {
-      saveGraphToStorage(newId, { version: PROJECT_VERSION, nodes: graph.nodes, edges: graph.edges })
+      saveGraphToStorage(newId, { version: RECOLLECTION_VERSION, nodes: graph.nodes, edges: graph.edges })
     }
-    toast.success('Project duplicated')
+    const logosContent = getLogosContent(duplicateTarget.id)
+    if (logosContent && logosContent.length > 0) {
+      setLogosContent(newId, logosContent)
+    }
+    toast.success('Recollection duplicated')
     setDuplicateTarget(null)
     setDuplicateName('')
-  }, [duplicateTarget, duplicateName, createProject])
+  }, [duplicateTarget, duplicateName, createRecollection])
 
   const allOnPageSelected = pageItems.length > 0 && pageItems.every((p) => selectedIds.has(p.id))
   const someOnPageSelected = pageItems.some((p) => selectedIds.has(p.id))
@@ -462,33 +475,33 @@ export function ProjectsPage() {
   const handleBulkDeleteConfirm = useCallback(() => {
     if (!bulkDeleteTargets || bulkDeleteTargets.length === 0) return
     const count = bulkDeleteTargets.length
-    bulkDeleteTargets.forEach((project) => {
-      removeGraphFromStorage(project.id)
-      deleteProject(project.id)
+    bulkDeleteTargets.forEach((recollection) => {
+      removeGraphFromStorage(recollection.id)
+      deleteRecollection(recollection.id)
     })
     setBulkDeleteTargets(null)
     setSelectedIds(new Set())
-    navigate('/projects', { replace: true })
-    toast(`${count} project${count === 1 ? '' : 's'} deleted`)
-  }, [bulkDeleteTargets, deleteProject, navigate])
+    navigate('/recollections', { replace: true })
+    toast(`${count} recollection${count === 1 ? '' : 's'} deleted`)
+  }, [bulkDeleteTargets, deleteRecollection, navigate])
 
   const handleBulkExport = useCallback(() => {
     const toExport = sorted.filter((p) => selectedIds.has(p.id))
-    toExport.forEach((project) => {
-      const stored = loadGraphFromStorage(project.id)
+    toExport.forEach((recollection) => {
+      const stored = loadGraphFromStorage(recollection.id)
       const state = stored
-        ? { version: PROJECT_VERSION, nodes: stored.nodes, edges: stored.edges }
-        : { version: PROJECT_VERSION, nodes: [], edges: [] }
+        ? { version: RECOLLECTION_VERSION, nodes: stored.nodes, edges: stored.edges }
+        : { version: RECOLLECTION_VERSION, nodes: [], edges: [] }
       const blob = new Blob([JSON.stringify(state, null, 2)], { type: 'application/json' })
       const url = URL.createObjectURL(blob)
       const a = document.createElement('a')
-      const filename = `${project.name.replace(/[^\w.-]/g, '_')}${PROJECT_FILE_EXT}`
+      const filename = `${recollection.name.replace(/[^\w.-]/g, '_')}${RECOLLECTION_FILE_EXT}`
       a.href = url
       a.download = filename
       a.click()
       URL.revokeObjectURL(url)
     })
-    toast.success(`Exported ${toExport.length} project${toExport.length === 1 ? '' : 's'}`)
+    toast.success(`Exported ${toExport.length} recollection${toExport.length === 1 ? '' : 's'}`)
   }, [sorted, selectedIds])
 
   const SortIcon = ({ columnKey }: { columnKey: SortKey }) => {
@@ -498,8 +511,8 @@ export function ProjectsPage() {
 
   return (
     <div className="relative flex flex-1 flex-col min-h-0">
-      <ProjectsPageBackground className="absolute inset-0 pointer-events-none" />
-      <div className="relative flex min-h-0 flex-1 flex-col gap-4 p-4 overflow-auto">
+      <RecollectionsPageBackground className="absolute inset-0 pointer-events-none" />
+      <div ref={scrollContainerRef} className="relative flex min-h-0 flex-1 flex-col gap-4 p-4 overflow-auto">
       <TooltipProvider>
         <div className="flex flex-wrap items-center gap-3">
           <h1 className="p-3 scroll-m-20 text-4xl font-extrabold tracking-tight text-balance font-serif">
@@ -511,14 +524,14 @@ export function ProjectsPage() {
             <div className="relative w-64 shrink-0">
               <Search className="absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-muted-foreground pointer-events-none" />
               <Input
-                placeholder="Search projects"
+                placeholder="Search recollections"
                 value={search}
                 onChange={(e) => {
                   setSearch(e.target.value)
                   setPage(0)
                 }}
                 className="h-9 w-full pl-8"
-                aria-label="Search projects by name"
+                aria-label="Search recollections by name"
               />
             </div>
             <div className="ml-auto flex h-9 items-center gap-2">
@@ -562,9 +575,9 @@ export function ProjectsPage() {
 
           {sorted.length === 0 ? (
             <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
-              <NewProjectDialog
-                onCreate={handleCreateProject}
-                existingNames={orderedProjects.map((p) => p.name)}
+              <NewRecollectionDialog
+                onCreate={handleCreateRecollection}
+                existingNames={orderedRecollections.map((p) => p.name)}
                 trigger={
                   <div
                     className="flex cursor-pointer flex-col overflow-hidden rounded-lg border border-dashed border-muted-foreground/30 bg-muted/20 shadow-sm transition-colors hover:border-muted-foreground/50 hover:bg-muted/30"
@@ -576,15 +589,15 @@ export function ProjectsPage() {
                           ; (e.currentTarget as HTMLElement).click()
                       }
                     }}
-                    aria-label="Create new project"
+                    aria-label="Create new recollection"
                   >
                     <div className="flex aspect-video w-full shrink-0 items-center justify-center" style={thumbnailGridStyle}>
                       <Plus className="size-12 text-muted-foreground" />
                     </div>
                     <div className="flex flex-1 flex-col gap-1 p-3">
-                      <span className="font-medium text-muted-foreground">New project</span>
+                      <span className="font-medium text-muted-foreground">New recollection</span>
                       <span className="text-xs text-muted-foreground">
-                        {search.trim() ? 'No projects match your search.' : 'Create a new project'}
+                        {search.trim() ? 'No recollections match your search.' : 'Create a new recollection'}
                       </span>
                     </div>
                   </div>
@@ -663,42 +676,42 @@ export function ProjectsPage() {
                     </TableRow>
                   </TableHeader>
                   <TableBody className="text-xs">
-                    {pageItems.map((project) => {
-                      const Icon = getProjectIcon(project.iconId)
-                      const counts = getGraphCounts(project.id)
-                      const lastEdited = project.lastEditedAt ?? project.createdAt
-                      const isSelected = selectedIds.has(project.id)
+                    {pageItems.map((recollection) => {
+                      const Icon = getRecollectionIcon(recollection.iconId)
+                      const counts = getGraphCounts(recollection.id)
+                      const lastEdited = recollection.lastEditedAt ?? recollection.createdAt
+                      const isSelected = selectedIds.has(recollection.id)
                       return (
                         <TableRow
-                          key={project.id}
+                          key={recollection.id}
                           className={`group cursor-pointer hover:bg-muted/50 h-8 ${isSelected ? 'bg-muted/70' : ''}`}
-                          onClick={() => handleOpen(project.id)}
+                          onClick={() => handleOpen(recollection.id)}
                           onKeyDown={(e) => {
                             if (e.key === 'Enter' || e.key === ' ') {
                               e.preventDefault()
-                              handleOpen(project.id)
+                              handleOpen(recollection.id)
                             }
                           }}
                           tabIndex={0}
                           role="button"
-                          aria-label={`Open ${project.name}`}
+                          aria-label={`Open ${recollection.name}`}
                         >
                           <TableCell className="px-2 py-1.5 w-10 [&:has([role=checkbox])]:pr-0" onClick={(e) => e.stopPropagation()}>
                             <Checkbox
                               checked={isSelected}
-                              onCheckedChange={() => toggleSelection(project.id)}
-                              aria-label={`Select ${project.name}`}
+                              onCheckedChange={() => toggleSelection(recollection.id)}
+                              aria-label={`Select ${recollection.name}`}
                             />
                           </TableCell>
                           <TableCell className="px-2 py-1.5 min-w-0">
                             <div className="flex items-center gap-1.5 min-w-0">
                               <Icon className="size-3.5 shrink-0 text-muted-foreground" />
-                              <span className="font-medium truncate">{project.name}</span>
+                              <span className="font-medium truncate">{recollection.name}</span>
                             </div>
                           </TableCell>
                           <TableCell className="hidden sm:table-cell text-muted-foreground px-2 py-1.5 w-[120px] min-w-[100px]">
-                            <span className="truncate block" title={formatDate(project.createdAt)}>
-                              {formatDate(project.createdAt)}
+                            <span className="truncate block" title={formatDate(recollection.createdAt)}>
+                              {formatDate(recollection.createdAt)}
                             </span>
                           </TableCell>
                           <TableCell className="hidden md:table-cell text-muted-foreground px-2 py-1.5 w-[100px] min-w-[80px]" title={`${counts.nodes} nodes, ${counts.edges} edges`}>
@@ -716,15 +729,15 @@ export function ProjectsPage() {
                             className={`sticky right-0 w-12 min-w-12 px-1 py-1.5 ${isSelected ? 'bg-muted/70' : 'bg-card group-hover:bg-muted/50'}`}
                             onClick={(e) => e.stopPropagation()}
                           >
-                            <ProjectActionsMenu
-                              project={project}
+                            <RecollectionActionsMenu
+                              recollection={recollection}
                               onOpen={handleOpen}
                               onRenameOpen={handleRenameOpen}
                               onDuplicateOpen={handleDuplicateOpen}
                               onExport={handleExport}
                               onDeleteOpen={handleDeleteOpen}
                               trigger={
-                                <Button variant="ghost" size="icon" className="size-7" aria-label={`Actions for ${project.name}`}>
+                                <Button variant="ghost" size="icon" className="size-7" aria-label={`Actions for ${recollection.name}`}>
                                   <MoreHorizontal className="size-4" />
                                 </Button>
                               }
@@ -741,7 +754,7 @@ export function ProjectsPage() {
                 <div className="flex flex-wrap items-center justify-between gap-2 border-t pt-4">
                   <p className="text-sm text-muted-foreground">
                     Page {page + 1} of {totalPages}
-                    {pageSize !== -1 && ` · ${sorted.length} projects`}
+                    {pageSize !== -1 && ` · ${sorted.length} recollections`}
                   </p>
                   <div className="flex gap-1">
                     <Button
@@ -787,9 +800,9 @@ export function ProjectsPage() {
           ) : (
             <>
               <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
-                <NewProjectDialog
-                  onCreate={handleCreateProject}
-                  existingNames={orderedProjects.map((p) => p.name)}
+                <NewRecollectionDialog
+                  onCreate={handleCreateRecollection}
+                  existingNames={orderedRecollections.map((p) => p.name)}
                   trigger={
                     <div
                       className="flex cursor-pointer flex-col overflow-hidden rounded-lg border border-dashed border-muted-foreground/30 bg-muted/20 shadow-sm transition-colors hover:border-muted-foreground/50 hover:bg-muted/30"
@@ -801,44 +814,44 @@ export function ProjectsPage() {
                             ; (e.currentTarget as HTMLElement).click()
                         }
                       }}
-                      aria-label="Create new project"
+                      aria-label="Create new recollection"
                     >
                       <div className="flex aspect-video w-full shrink-0 items-center justify-center" style={thumbnailGridStyle}>
                         <Plus className="size-12 text-muted-foreground" />
                       </div>
                       <div className="flex flex-1 flex-col gap-1 p-3">
-                        <span className="font-medium text-muted-foreground">New project</span>
-                        <span className="text-xs text-muted-foreground">Create a new project</span>
+                        <span className="font-medium text-muted-foreground">New recollection</span>
+                        <span className="text-xs text-muted-foreground">Create a new recollection</span>
                       </div>
                     </div>
                   }
                 />
-                {pageItems.map((project) => {
-                  const Icon = getProjectIcon(project.iconId)
-                  const lastEdited = project.lastEditedAt ?? project.createdAt
+                {pageItems.map((recollection) => {
+                  const Icon = getRecollectionIcon(recollection.iconId)
+                  const lastEdited = recollection.lastEditedAt ?? recollection.createdAt
                   return (
                     <div
-                      key={project.id}
+                      key={recollection.id}
                       className="group flex cursor-pointer flex-col overflow-hidden rounded-lg border bg-card text-card-foreground shadow-sm transition-shadow hover:shadow-md"
-                      onClick={() => handleOpen(project.id)}
+                      onClick={() => handleOpen(recollection.id)}
                       onKeyDown={(e) => {
                         if (e.key === 'Enter' || e.key === ' ') {
                           e.preventDefault()
-                          handleOpen(project.id)
+                          handleOpen(recollection.id)
                         }
                       }}
                       role="button"
                       tabIndex={0}
-                      aria-label={`Open ${project.name}`}
+                      aria-label={`Open ${recollection.name}`}
                     >
                       <div className="relative aspect-video w-full shrink-0 overflow-hidden bg-muted">
-                        <GraphThumbnail projectId={project.id} className="h-full w-full object-cover" />
+                        <GraphThumbnail recollectionId={recollection.id} className="h-full w-full object-cover" />
                         <div
                           className="absolute right-1.5 top-1.5 z-10 opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100"
                           onClick={(e) => e.stopPropagation()}
                         >
-                          <ProjectActionsMenu
-                            project={project}
+                          <RecollectionActionsMenu
+                            recollection={recollection}
                             onOpen={handleOpen}
                             onRenameOpen={handleRenameOpen}
                             onDuplicateOpen={handleDuplicateOpen}
@@ -849,7 +862,7 @@ export function ProjectsPage() {
                                 variant="secondary"
                                 size="icon"
                                 className="size-7 rounded-full shadow-sm"
-                                aria-label={`Actions for ${project.name}`}
+                                aria-label={`Actions for ${recollection.name}`}
                                 onClick={(e) => e.stopPropagation()}
                               >
                                 <MoreHorizontal className="size-4" />
@@ -861,7 +874,7 @@ export function ProjectsPage() {
                       <div className="flex flex-1 flex-col gap-1 p-3">
                         <div className="flex items-center gap-2">
                           <Icon className="size-4 shrink-0 text-muted-foreground" />
-                          <span className="truncate font-medium font-serif">{project.name}</span>
+                          <span className="truncate font-medium font-serif">{recollection.name}</span>
                         </div>
                         <Tooltip>
                           <TooltipTrigger asChild>
@@ -878,7 +891,7 @@ export function ProjectsPage() {
                 <div className="flex flex-wrap items-center justify-between gap-2 border-t pt-4">
                   <p className="text-sm text-muted-foreground">
                     Page {page + 1} of {totalPages}
-                    {pageSize !== -1 && ` · ${sorted.length} projects`}
+                    {pageSize !== -1 && ` · ${sorted.length} recollections`}
                   </p>
                   <div className="flex gap-1">
                     <Button
@@ -924,44 +937,24 @@ export function ProjectsPage() {
           )}
         </div>
 
-        {/* Rename dialog */}
-        <Dialog open={!!renameTarget} onOpenChange={(open) => !open && setRenameTarget(null)}>
-          <DialogContent onCloseAutoFocus={(e) => e.preventDefault()}>
-            <DialogHeader>
-              <DialogTitle>Rename project</DialogTitle>
-              <DialogDescription>Enter a new name for this project.</DialogDescription>
-            </DialogHeader>
-            <Input
-              ref={renameInputRef}
-              value={renameValue}
-              onChange={(e) => setRenameValue(e.target.value)}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter') handleRenameSubmit()
-                if (e.key === 'Escape') setRenameTarget(null)
-              }}
-              placeholder="Project name"
-              aria-label="Project name"
-            />
-            {renameTarget && renameValue.trim() && sorted.some((p) => p.id !== renameTarget.id && p.name.toLowerCase() === renameValue.trim().toLowerCase()) && (
-              <p className="text-xs text-amber-600 dark:text-amber-500">A project with this name already exists.</p>
-            )}
-            <DialogFooter>
-              <Button variant="outline" onClick={() => setRenameTarget(null)}>
-                Cancel
-              </Button>
-              <Button onClick={handleRenameSubmit} disabled={!renameValue.trim()}>
-                Save
-              </Button>
-            </DialogFooter>
-          </DialogContent>
-        </Dialog>
+        <RenameRecollectionDialog
+          open={!!renameTarget}
+          onOpenChange={(open) => !open && setRenameTarget(null)}
+          recollectionId={renameTarget?.id ?? ''}
+          initialName={renameTarget?.name ?? ''}
+          recollections={sorted}
+          onRename={(id, newName) => {
+            renameRecollection(id, newName)
+            setRenameTarget(null)
+          }}
+        />
 
         {/* Duplicate dialog */}
         <Dialog open={!!duplicateTarget} onOpenChange={(open) => { if (!open) { setDuplicateTarget(null); setDuplicateName('') } }}>
           <DialogContent onCloseAutoFocus={(e) => e.preventDefault()}>
             <DialogHeader>
-              <DialogTitle>Duplicate project</DialogTitle>
-              <DialogDescription>Enter a name for the duplicate project.</DialogDescription>
+              <DialogTitle>Duplicate recollection</DialogTitle>
+              <DialogDescription>Enter a name for the duplicate recollection.</DialogDescription>
             </DialogHeader>
             <Input
               ref={duplicateInputRef}
@@ -971,11 +964,11 @@ export function ProjectsPage() {
                 if (e.key === 'Enter') handleDuplicateConfirm()
                 if (e.key === 'Escape') setDuplicateTarget(null)
               }}
-              placeholder="Project name"
-              aria-label="Duplicate project name"
+              placeholder="Recollection name"
+              aria-label="Duplicate recollection name"
             />
-            {duplicateTarget && duplicateName.trim() && orderedProjects.some((p) => p.name.toLowerCase() === duplicateName.trim().toLowerCase()) && (
-              <p className="text-xs text-amber-600 dark:text-amber-500">A project with this name already exists.</p>
+            {duplicateTarget && duplicateName.trim() && orderedRecollections.some((p) => p.name.toLowerCase() === duplicateName.trim().toLowerCase()) && (
+              <p className="text-xs text-amber-600 dark:text-amber-500">An recollection with this name already exists.</p>
             )}
             <DialogFooter>
               <Button variant="outline" onClick={() => { setDuplicateTarget(null); setDuplicateName('') }}>
@@ -992,7 +985,7 @@ export function ProjectsPage() {
         <Dialog open={!!deleteTarget} onOpenChange={(open) => !open && setDeleteTarget(null)}>
           <DialogContent>
             <DialogHeader>
-              <DialogTitle>Delete project</DialogTitle>
+              <DialogTitle>Delete recollection</DialogTitle>
               <DialogDescription>
                 {deleteTarget
                   ? `Are you sure you want to delete "${deleteTarget.name}"? You can undo this from the notification.`
@@ -1014,9 +1007,9 @@ export function ProjectsPage() {
         <Dialog open={bulkDeleteTargets !== null && bulkDeleteTargets.length > 0} onOpenChange={(open) => !open && setBulkDeleteTargets(null)}>
           <DialogContent>
             <DialogHeader>
-              <DialogTitle>Delete {bulkDeleteTargets?.length ?? 0} projects</DialogTitle>
+              <DialogTitle>Delete {bulkDeleteTargets?.length ?? 0} recollections</DialogTitle>
               <DialogDescription>
-                Are you sure you want to delete these projects? This cannot be undone.
+                Are you sure you want to delete these recollections? This cannot be undone.
               </DialogDescription>
             </DialogHeader>
             <DialogFooter>

frontend/src/app/recollections/flux/FluxRoute.tsx

@@ -0,0 +1,31 @@
+/**
+ * Flux route: renders the graph canvas (CanvasPage) for the current recollection.
+ * Supports optional focusNode query param to center on a specific node.
+ */
+
+import React, { useEffect, useRef } from 'react'
+import { useParams, useSearchParams } from 'react-router-dom'
+import { CanvasPage } from '@/app/canvas/CanvasPage'
+import { usePlatform } from '@/app/kosmos/KosmosContext'
+
+export function FluxRoute() {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const [searchParams] = useSearchParams()
+  const { updateLastEdited } = usePlatform()
+  const updateLastEditedRef = useRef(updateLastEdited)
+  updateLastEditedRef.current = updateLastEdited
+
+  useEffect(() => {
+    if (recollectionId) updateLastEditedRef.current(recollectionId)
+  }, [recollectionId])
+
+  const focusNodeId = searchParams.get('focusNode') ?? undefined
+
+  if (!recollectionId) return null
+
+  return (
+    <div className="flex h-full min-h-0 flex-1 flex-col overflow-hidden">
+      <CanvasPage key={recollectionId} recollectionId={recollectionId} focusNodeId={focusNodeId} />
+    </div>
+  )
+}

frontend/src/app/recollections/katalogos/KatalogosPage.tsx

@@ -0,0 +1,127 @@
+/**
+ * Katalogos page: third view for a recollection.
+ * Shows live \"Artifacts\" from Flux rendering nodes in a card grid.
+ */
+
+import React, { useMemo } from 'react'
+import { useNavigate, useParams } from 'react-router-dom'
+import { usePlatform } from '@/app/kosmos/KosmosContext'
+import { getRenderOutputCache, formatTimeSinceLastUpdate } from '../state/recollectionStore'
+import { Button } from '@/components/ui/button'
+
+export function KatalogosPage() {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const { recollections } = usePlatform()
+  const navigate = useNavigate()
+
+  const recollection = recollectionId ? recollections.find((p) => p.id === recollectionId) : null
+  const title = recollection?.name ?? 'Untitled'
+
+  const artifacts = useMemo(
+    () => (recollectionId ? getRenderOutputCache(recollectionId) : []),
+    [recollectionId]
+  )
+
+  const handleViewInFlux = (nodeId: string) => {
+    if (!recollectionId) return
+    navigate(`/recollections/${recollectionId}/flux?focusNode=${encodeURIComponent(nodeId)}`)
+  }
+
+  return (
+    <div className="flex h-full min-h-0 flex-1 flex-col overflow-auto bg-background">
+      <div className="mx-auto w-full max-w-5xl p-4">
+        <h1 className="mb-2 truncate font-serif text-2xl font-semibold tracking-tight text-foreground">
+          {title}
+        </h1>
+        <p className="mb-6 text-sm text-muted-foreground">
+          Katalogos · Live artifacts produced by Flux rendering nodes for this recollection.
+        </p>
+        {artifacts.length === 0 ? (
+          <div className="rounded-lg border border-dashed border-muted-foreground/30 bg-muted/10 p-4 text-sm text-muted-foreground">
+            No artifacts yet. In Flux, run a graph with a rendering node; its output will be cached as an artifact and
+            appear here, as well as in Logos blocks that insert artifacts.
+          </div>
+        ) : (
+          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+            {artifacts.map((artifact) => {
+              const label = artifact.label || artifact.nodeId
+              const isImage =
+                artifact.type === 'image' ||
+                Boolean(artifact.content?.trim() && /<svg[\\s>]/i.test(artifact.content.trim()))
+              const imageSrc =
+                isImage && artifact.content
+                  ? artifact.content.startsWith('data:')
+                    ? artifact.content
+                    : `data:image/svg+xml;utf8,${encodeURIComponent(artifact.content)}`
+                  : null
+
+              return (
+                <div
+                  key={artifact.nodeId}
+                  className="flex h-full flex-col rounded-lg border border-border bg-card text-card-foreground shadow-sm"
+                >
+                  <div className="flex items-center justify-between gap-2 border-b border-border/60 px-3 py-2">
+                    <div className="min-w-0">
+                      <p className="truncate text-sm font-medium">{label}</p>
+                      <p className="truncate text-xs text-muted-foreground">Node: {artifact.nodeId}</p>
+                    </div>
+                    <span className="inline-flex items-center gap-1 rounded-full bg-emerald-500/10 px-2 py-0.5 text-[11px] font-medium uppercase tracking-wide text-emerald-500">
+                      <span className="h-1.5 w-1.5 rounded-full bg-emerald-500" />
+                      Live
+                    </span>
+                  </div>
+                  <div className="flex flex-1 flex-col gap-2 px-3 py-3">
+                    {isImage && imageSrc ? (
+                      <div className="flex min-h-[120px] items-center justify-center overflow-hidden rounded-md border bg-muted">
+                        <img
+                          src={imageSrc}
+                          alt={label || 'Artifact image'}
+                          className="max-h-48 w-full max-w-full object-contain"
+                        />
+                      </div>
+                    ) : artifact.content ? (
+                      <div className="min-h-[120px] overflow-hidden rounded-md border border-border bg-background">
+                        <iframe
+                          title={label || 'Artifact HTML output'}
+                          srcDoc={artifact.content}
+                          className="h-40 w-full"
+                          sandbox="allow-same-origin"
+                        />
+                      </div>
+                    ) : (
+                      <div className="flex min-h-[80px] items-center justify-center rounded-md border border-dashed border-muted-foreground/40 bg-muted/40 px-3 text-xs text-muted-foreground">
+                        No preview available.
+                      </div>
+                    )}
+                  </div>
+                  <div className="flex flex-wrap items-center justify-between gap-2 border-t border-border/60 bg-card px-3 py-2">
+                    <div className="flex min-w-0 items-center gap-2">
+                      <p className="truncate text-xs text-muted-foreground">
+                        Type: <span className="font-medium">{artifact.type}</span>
+                      </p>
+                      {artifact.updatedAt != null && (
+                        <span className="text-[11px] text-muted-foreground">
+                          · {formatTimeSinceLastUpdate(artifact.updatedAt)}
+                        </span>
+                      )}
+                    </div>
+                    <Button
+                      type="button"
+                      variant="outline"
+                      size="xs"
+                      className="h-7 px-2 text-xs"
+                      onClick={() => handleViewInFlux(artifact.nodeId)}
+                    >
+                      View in Flux
+                    </Button>
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+

frontend/src/app/recollections/layout/RecollectionActionsContext.tsx

@@ -0,0 +1,259 @@
+/**
+ * Context for shared recollection actions: two slots (flux and logos) and layout-level import/export.
+ * Consumers use pathname to pick the active slot for title (save status, Save) and Edit/View menus (undo, redo, etc.).
+ */
+
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react'
+import { useLocation, useParams } from 'react-router-dom'
+import type { SaveStatus } from '@/app/canvas/useCanvasGraph'
+import {
+  getGraph,
+  setGraph,
+  getLogosContent,
+  setLogosContent,
+  upsertRenderOutputEntry,
+  RECOLLECTION_FILE_EXT,
+  RECOLLECTION_VERSION,
+  type StoredGraphState,
+  type StoredLogosContent,
+  type RenderOutputCacheEntry,
+} from '../state/recollectionStore'
+
+export type { RenderOutputCacheEntry }
+import type { AppNode, AppEdge } from '@/lib/graph/nodeTypes'
+import { backfillEdgeTargetTypes } from '@/app/canvas/canvasGraphUtils'
+import { toast } from 'sonner'
+
+export type { SaveStatus }
+
+/** Parsed recollection file format (import/export). */
+export type RecollectionFilePayload = {
+  version?: number
+  graph?: { nodes: unknown[]; edges: unknown[] }
+  logos?: StoredLogosContent
+}
+
+export type FluxSlot = {
+  saveStatus: SaveStatus
+  onSave: () => void
+  canSave: boolean
+  undo: () => void
+  redo: () => void
+  canUndo: boolean
+  canRedo: boolean
+  onRefreshFromStore: (graph: StoredGraphState) => void
+  onDuplicate?: () => void
+  onCopy?: () => void
+  onPaste?: () => void
+  canDuplicate?: boolean
+  canCopy?: boolean
+  onFitView?: () => void
+}
+
+export type LogosSlot = {
+  saveStatus: SaveStatus
+  onSave: () => void
+  canSave: boolean
+  undo: () => void
+  redo: () => void
+  canUndo: boolean
+  canRedo: boolean
+  onRefreshFromStore: () => void
+}
+
+export type RecollectionActionsContextValue = {
+  flux: FluxSlot | null
+  logos: LogosSlot | null
+  setFluxSlot: (slot: FluxSlot | null) => void
+  setLogosSlot: (slot: LogosSlot | null) => void
+  /** Whether the Flux view is active (pathname ends with /flux). */
+  isFluxActive: boolean
+  /** Whether the Logos view is active. */
+  isLogosActive: boolean
+  /** Active slot (flux or logos by pathname). */
+  activeSlot: FluxSlot | LogosSlot | null
+  onImport: () => void
+  onExport: () => void
+  /** Upsert a rendering node's output into the cache so Logos "Insert from Flux" block can show it. */
+  upsertRenderOutputToLogos: (entry: RenderOutputCacheEntry) => void
+}
+
+const RecollectionActionsContext = createContext<RecollectionActionsContextValue | null>(null)
+
+function validateAndWritePayload(
+  recollectionId: string,
+  payload: RecollectionFilePayload,
+  backfillEdges: (nodes: AppNode[], edges: AppEdge[]) => AppEdge[]
+): { graph?: StoredGraphState; logos?: StoredLogosContent } {
+  const result: { graph?: StoredGraphState; logos?: StoredLogosContent } = {}
+  if (payload.graph && Array.isArray(payload.graph.nodes) && Array.isArray(payload.graph.edges)) {
+    const nodes = payload.graph.nodes as AppNode[]
+    const edges = backfillEdges(nodes, payload.graph.edges as AppEdge[])
+    const graphState: StoredGraphState = {
+      version: payload.version ?? RECOLLECTION_VERSION,
+      nodes,
+      edges,
+    }
+    setGraph(recollectionId, graphState)
+    result.graph = graphState
+  }
+  if (payload.logos != null && Array.isArray(payload.logos)) {
+    if (payload.logos.every((item) => item != null && typeof item === 'object')) {
+      setLogosContent(recollectionId, payload.logos as StoredLogosContent)
+      result.logos = payload.logos as StoredLogosContent
+    }
+  }
+  return result
+}
+
+export function RecollectionActionsProvider({ children }: { children: React.ReactNode }) {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const { pathname } = useLocation()
+  const [flux, setFluxSlotState] = useState<FluxSlot | null>(null)
+  const [logos, setLogosSlotState] = useState<LogosSlot | null>(null)
+  const importInputRef = useRef<HTMLInputElement>(null)
+  const fluxRef = useRef<FluxSlot | null>(null)
+  const logosRef = useRef<LogosSlot | null>(null)
+  const pathnameRef = useRef(pathname)
+  fluxRef.current = flux
+  logosRef.current = logos
+  pathnameRef.current = pathname
+
+  const isFluxActive = pathname.endsWith('/flux')
+  const isLogosActive = pathname.includes('/logos') || /\/recollections\/[^/]+\/?$/.test(pathname)
+  const activeSlot = isFluxActive ? flux : isLogosActive ? logos : null
+
+  const setFluxSlot = useCallback((slot: FluxSlot | null) => {
+    setFluxSlotState(() => slot)
+  }, [])
+  const setLogosSlot = useCallback((slot: LogosSlot | null) => {
+    setLogosSlotState(() => slot)
+  }, [])
+
+  useEffect(() => {
+    const onKeyDown = (ev: KeyboardEvent) => {
+      const mod = ev.ctrlKey || ev.metaKey
+      if (mod && ev.key.toLowerCase() === 's') {
+        const slot = activeSlot
+        if (slot?.onSave && slot?.canSave) {
+          ev.preventDefault()
+          ev.stopPropagation()
+          slot.onSave()
+        }
+      }
+    }
+    window.addEventListener('keydown', onKeyDown, true)
+    return () => window.removeEventListener('keydown', onKeyDown, true)
+  }, [activeSlot])
+
+  const onExport = useCallback(() => {
+    if (!recollectionId) return
+    const graph = getGraph(recollectionId)
+    const logosContent = getLogosContent(recollectionId)
+    const payload: RecollectionFilePayload = {
+      version: RECOLLECTION_VERSION,
+      ...(graph && { graph: { nodes: graph.nodes, edges: graph.edges } }),
+      ...(logosContent && { logos: logosContent }),
+    }
+    const blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = `recollection${RECOLLECTION_FILE_EXT}`
+    a.click()
+    URL.revokeObjectURL(url)
+    toast.success('Recollection exported')
+  }, [recollectionId])
+
+  const onImport = useCallback(() => {
+    importInputRef.current?.click()
+  }, [])
+
+  const upsertRenderOutputToLogos = useCallback(
+    (entry: RenderOutputCacheEntry) => {
+      if (recollectionId) upsertRenderOutputEntry(recollectionId, entry)
+    },
+    [recollectionId]
+  )
+
+  const onImportFileChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const file = e.target.files?.[0]
+      e.target.value = ''
+      if (!file || !recollectionId) return
+      const reader = new FileReader()
+      reader.onload = () => {
+        try {
+          const text = reader.result as string
+          const payload = JSON.parse(text) as RecollectionFilePayload
+          if (!payload || typeof payload !== 'object') {
+            toast.error('Invalid file: not valid JSON')
+            return
+          }
+          const written = validateAndWritePayload(recollectionId, payload, (nodes, edges) =>
+            backfillEdgeTargetTypes(nodes, edges)
+          )
+          const currentPath = pathnameRef.current
+          const fluxActive = currentPath.endsWith('/flux')
+          const logosActive = currentPath.includes('/logos') || /\/recollections\/[^/]+\/?$/.test(currentPath)
+          if (written.graph && fluxActive && fluxRef.current?.onRefreshFromStore) {
+            fluxRef.current.onRefreshFromStore(written.graph)
+          }
+          if ((written.graph != null || written.logos != null) && logosActive && logosRef.current?.onRefreshFromStore) {
+            logosRef.current.onRefreshFromStore()
+          }
+          if (payload.version != null && payload.version > RECOLLECTION_VERSION) {
+            toast.error('Recollection was created with a newer app version')
+          } else {
+            toast.success('Recollection loaded')
+          }
+        } catch {
+          toast.error('Invalid file: not valid JSON')
+        }
+      }
+      reader.readAsText(file)
+    },
+    [recollectionId]
+  )
+
+  const value: RecollectionActionsContextValue = React.useMemo(
+    () => ({
+      flux,
+      logos,
+      setFluxSlot,
+      setLogosSlot,
+      isFluxActive,
+      isLogosActive,
+      activeSlot,
+      onImport,
+      onExport,
+      upsertRenderOutputToLogos,
+    }),
+    [flux, logos, setFluxSlot, setLogosSlot, isFluxActive, isLogosActive, activeSlot, onImport, onExport, upsertRenderOutputToLogos]
+  )
+
+  return (
+    <RecollectionActionsContext.Provider value={value}>
+      {children}
+      <input
+        ref={importInputRef}
+        type="file"
+        accept=".json,application/json"
+        className="hidden"
+        aria-hidden
+        onChange={onImportFileChange}
+      />
+    </RecollectionActionsContext.Provider>
+  )
+}
+
+export function useRecollectionActions(): RecollectionActionsContextValue {
+  const ctx = useContext(RecollectionActionsContext)
+  if (!ctx) throw new Error('useRecollectionActions must be used within RecollectionActionsProvider')
+  return ctx
+}
+
+/** Returns the context value or null when outside RecollectionActionsProvider. Use when the consumer may render outside recollection layout. */
+export function useOptionalRecollectionActions(): RecollectionActionsContextValue | null {
+  return useContext(RecollectionActionsContext)
+}

frontend/src/app/recollections/layout/RecollectionEditViewMenus.tsx

@@ -0,0 +1,154 @@
+/**
+ * Shared Edit and View menus for recollections. Always rendered in the menubar;
+ * uses the active slot (flux or logos by pathname) for undo, redo, and Flux-only actions.
+ */
+
+import React, { useEffect, useMemo } from 'react'
+import {
+  Menubar,
+  MenubarContent,
+  MenubarItem,
+  MenubarMenu,
+  MenubarSeparator,
+  MenubarTrigger,
+} from '@/components/ui/menubar'
+import { Kbd, KbdGroup } from '@/components/ui/kbd'
+import { useRecollectionActions } from './RecollectionActionsContext'
+import { ClipboardPaste, Copy, CopyPlus, Redo2, Undo2 } from 'lucide-react'
+
+const UNDO_KEYS = { key: 'z', shiftKey: false }
+const REDO_KEYS = { key: 'z', shiftKey: true }
+
+function matchKey(ev: KeyboardEvent, want: { key: string; shiftKey: boolean }) {
+  const mod = ev.ctrlKey || ev.metaKey
+  return ev.key.toLowerCase() === want.key && !!mod && !!ev.shiftKey === want.shiftKey
+}
+
+export function RecollectionEditViewMenus() {
+  const { activeSlot, flux, isFluxActive } = useRecollectionActions()
+
+  const fluxSlot = isFluxActive ? flux : null
+
+  useEffect(() => {
+    if (!activeSlot) return
+    const onKeyDown = (ev: KeyboardEvent) => {
+      if (matchKey(ev, UNDO_KEYS) && activeSlot.canUndo) {
+        ev.preventDefault()
+        ev.stopPropagation()
+        activeSlot.undo()
+      } else if (matchKey(ev, REDO_KEYS) && activeSlot.canRedo) {
+        ev.preventDefault()
+        ev.stopPropagation()
+        activeSlot.redo()
+      }
+    }
+    window.addEventListener('keydown', onKeyDown, true)
+    return () => window.removeEventListener('keydown', onKeyDown, true)
+  }, [activeSlot])
+
+  const hasFluxOnly =
+    fluxSlot &&
+    (fluxSlot.onDuplicate != null || fluxSlot.onCopy != null || fluxSlot.onPaste != null)
+
+  const menus = useMemo(
+    () => (
+      <Menubar className="h-9 shrink-0 rounded-none border-0 bg-transparent p-0 shadow-none">
+        <MenubarMenu>
+          <MenubarTrigger className="h-9 font-normal text-muted-foreground">Edit</MenubarTrigger>
+          <MenubarContent>
+            <MenubarItem
+              onClick={() => activeSlot?.undo()}
+              disabled={!activeSlot?.canUndo}
+              className="gap-2"
+            >
+              <Undo2 className="h-4 w-4" />
+              Undo
+              <span className="ml-auto pl-4">
+                <KbdGroup>
+                  <Kbd>⌘ + Z</Kbd>
+                </KbdGroup>
+              </span>
+            </MenubarItem>
+            <MenubarItem
+              onClick={() => activeSlot?.redo()}
+              disabled={!activeSlot?.canRedo}
+              className="gap-2"
+            >
+              <Redo2 className="h-4 w-4" />
+              Redo
+              <span className="ml-auto pl-4">
+                <KbdGroup>
+                  <Kbd>⌘ + ⇧ + Z</Kbd>
+                </KbdGroup>
+              </span>
+            </MenubarItem>
+            {hasFluxOnly && fluxSlot && (
+              <>
+                <MenubarSeparator />
+                {fluxSlot.onDuplicate != null && (
+                  <MenubarItem
+                    onClick={fluxSlot.onDuplicate}
+                    disabled={!fluxSlot.canDuplicate}
+                    className="gap-2"
+                  >
+                    <CopyPlus className="h-4 w-4" />
+                    Duplicate
+                    <span className="ml-auto pl-4">
+                      <KbdGroup>
+                        <Kbd>⌘D</Kbd>
+                      </KbdGroup>
+                    </span>
+                  </MenubarItem>
+                )}
+                {fluxSlot.onCopy != null && (
+                  <MenubarItem
+                    onClick={fluxSlot.onCopy}
+                    disabled={!fluxSlot.canCopy}
+                    className="gap-2"
+                  >
+                    <Copy className="h-4 w-4" />
+                    Copy
+                    <span className="ml-auto pl-4">
+                      <KbdGroup>
+                        <Kbd>⌘C</Kbd>
+                      </KbdGroup>
+                    </span>
+                  </MenubarItem>
+                )}
+                {fluxSlot.onPaste != null && (
+                  <MenubarItem onClick={fluxSlot.onPaste} className="gap-2">
+                    <ClipboardPaste className="h-4 w-4" />
+                    Paste
+                    <span className="ml-auto pl-4">
+                      <KbdGroup>
+                        <Kbd>⌘V</Kbd>
+                      </KbdGroup>
+                    </span>
+                  </MenubarItem>
+                )}
+              </>
+            )}
+          </MenubarContent>
+        </MenubarMenu>
+        <MenubarMenu>
+          <MenubarTrigger className="h-9 font-normal text-muted-foreground">View</MenubarTrigger>
+          <MenubarContent>
+            {fluxSlot?.onFitView && (
+              <MenubarItem onClick={fluxSlot.onFitView} className="gap-2">
+                Fit View
+                <span className="ml-auto pl-4">
+                  <KbdGroup>
+                    <Kbd>⌘0</Kbd>
+                  </KbdGroup>
+                </span>
+              </MenubarItem>
+            )}
+          </MenubarContent>
+        </MenubarMenu>
+      </Menubar>
+    ),
+    [activeSlot, fluxSlot, hasFluxOnly]
+  )
+
+  return menus
+}

frontend/src/app/recollections/layout/RecollectionFileMenu.tsx

@@ -0,0 +1,102 @@
+/**
+ * File menu for a recollection (emanation).
+ * Hosts Save, Rename, Import, Export that used to live under the title dropdown.
+ */
+
+import React, { useMemo, useState } from 'react'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuPortal,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { Kbd, KbdGroup } from '@/components/ui/kbd'
+import { useRecollectionActions } from './RecollectionActionsContext'
+import { usePlatform } from '@/app/kosmos/KosmosContext'
+import { RenameRecollectionDialog } from './RenameRecollectionDialog'
+import { Download, FolderOpen, Pencil, Save } from 'lucide-react'
+import { useParams } from 'react-router-dom'
+
+export function RecollectionFileMenu() {
+  const { activeSlot, onImport, onExport } = useRecollectionActions()
+  const { recollections, renameRecollection } = usePlatform()
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+
+  const [renameModalOpen, setRenameModalOpen] = useState(false)
+
+  const onSave = activeSlot?.onSave
+  const canSave = activeSlot?.canSave ?? false
+
+  const recollectionName = useMemo(
+    () => (recollectionId ? recollections.find((p) => p.id === recollectionId)?.name ?? '' : ''),
+    [recollectionId, recollections]
+  )
+
+  const menuItems = useMemo(
+    () => (
+      <>
+        {recollectionId && onSave != null && (
+          <>
+            <DropdownMenuItem onClick={onSave} disabled={!canSave} className="gap-2">
+              <Save className="h-4 w-4" />
+              Save
+              <span className="ml-auto pl-4">
+                <KbdGroup>
+                  <Kbd>⌘S</Kbd>
+                </KbdGroup>
+              </span>
+            </DropdownMenuItem>
+            <DropdownMenuSeparator />
+          </>
+        )}
+        {recollectionId && (
+          <>
+            <DropdownMenuItem onClick={() => setRenameModalOpen(true)} className="gap-2">
+              <Pencil className="h-4 w-4" />
+              Rename
+            </DropdownMenuItem>
+            <DropdownMenuSeparator />
+          </>
+        )}
+        <DropdownMenuItem onClick={onImport} className="gap-2">
+          <FolderOpen className="h-4 w-4" />
+          Import…
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={onExport} className="gap-2">
+          <Download className="h-4 w-4" />
+          Export…
+        </DropdownMenuItem>
+      </>
+    ),
+    [recollectionId, onSave, canSave, onImport, onExport]
+  )
+
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger className="flex h-9 shrink-0 items-center rounded-sm px-2 py-0 text-sm font-normal text-muted-foreground outline-none focus:bg-accent focus:text-accent-foreground hover:bg-accent hover:text-accent-foreground data-[state=open]:bg-accent">
+          File
+        </DropdownMenuTrigger>
+        <DropdownMenuPortal>
+          <DropdownMenuContent align="start" className="z-[200] min-w-[12rem]">
+            {menuItems}
+          </DropdownMenuContent>
+        </DropdownMenuPortal>
+      </DropdownMenu>
+      <RenameRecollectionDialog
+        open={renameModalOpen}
+        onOpenChange={setRenameModalOpen}
+        recollectionId={recollectionId ?? ''}
+        initialName={recollectionName}
+        recollections={recollections}
+        onRename={(id, newName) => {
+          renameRecollection(id, newName)
+          setRenameModalOpen(false)
+        }}
+      />
+    </>
+  )
+}
+

frontend/src/app/recollections/layout/RecollectionMenubar.tsx

@@ -0,0 +1,114 @@
+/**
+ * Recollection menubar: Back | breadcrumbs (left) | view switcher + File + Edit + save status (center).
+ */
+
+import React from 'react'
+import { Link, useLocation, useParams } from 'react-router-dom'
+import { usePlatform } from '@/app/kosmos/KosmosContext'
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@/components/ui/breadcrumb'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
+import { CheckCircle2, CircleDot, Loader2 } from 'lucide-react'
+import { RecollectionEditViewMenus } from './RecollectionEditViewMenus'
+import { RecollectionViewSwitcher } from './RecollectionViewSwitcher'
+import { RecollectionFileMenu } from './RecollectionFileMenu'
+import { useRecollectionActions } from './RecollectionActionsContext'
+import { getMode, viewLabel } from './recollectionNav'
+
+export function RecollectionMenubar() {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const { pathname } = useLocation()
+  const { recollections } = usePlatform()
+  const { activeSlot } = useRecollectionActions()
+  const saveStatus = activeSlot?.saveStatus ?? null
+
+  const recollection = recollectionId ? recollections.find((p) => p.id === recollectionId) : null
+  const mode = getMode(pathname)
+  const base = recollectionId ? `/recollections/${recollectionId}` : ''
+
+  return (
+    <div className="relative flex h-9 w-full shrink-0 items-center gap-2 overflow-visible border-b border-border/40 bg-background px-2">
+      <div className="flex items-center gap-2">
+        {base && (
+          <Breadcrumb>
+            <BreadcrumbList className="text-xs">
+              <BreadcrumbItem>
+                <BreadcrumbLink asChild>
+                  <Link
+                    to="/recollections"
+                    aria-label="Back to recollections"
+                    className="flex shrink-0 items-center rounded-sm px-2 py-1 text-sm outline-none focus:bg-accent focus:text-accent-foreground hover:bg-accent hover:text-accent-foreground"
+                  >
+                    <span
+                      className="size-4 shrink-0 rounded-[2px] opacity-90"
+                      style={{
+                        maskImage: 'url(/app-icon.svg)',
+                        maskRepeat: 'no-repeat',
+                        maskPosition: 'center',
+                        maskSize: 'contain',
+                        WebkitMaskImage: 'url(/app-icon.svg)',
+                        WebkitMaskRepeat: 'no-repeat',
+                        WebkitMaskPosition: 'center',
+                        WebkitMaskSize: 'contain',
+                        backgroundColor: 'currentColor',
+                      }}
+                      aria-hidden
+                    />
+                  </Link>
+                </BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbLink asChild>
+                  <Link to={base}>{recollection?.name ?? 'Recollection'}</Link>
+                </BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbPage>{viewLabel(mode)}</BreadcrumbPage>
+              </BreadcrumbItem>
+            </BreadcrumbList>
+          </Breadcrumb>
+        )}
+      </div>
+      <div className="pointer-events-none absolute left-1/2 top-1/2 flex min-w-0 -translate-x-1/2 -translate-y-1/2 items-center justify-center">
+        <div className="pointer-events-auto flex min-w-0 items-center gap-2">
+          <RecollectionViewSwitcher />
+          <RecollectionFileMenu />
+          <RecollectionEditViewMenus />
+          {/* Fixed-width slot so layout does not jump when saveStatus is null (e.g. on Katalogos) */}
+          <span
+            className="flex h-9 w-9 shrink-0 items-center justify-center text-muted-foreground"
+            aria-live="polite"
+            aria-label={
+              saveStatus === 'saving' ? 'Saving' : saveStatus === 'unsaved' ? 'Unsaved changes' : saveStatus === 'saved' ? 'All changes saved' : undefined
+            }
+          >
+            {saveStatus != null && (
+              <TooltipProvider delayDuration={300}>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <span className="flex size-5 items-center justify-center">
+                      {saveStatus === 'saving' && <Loader2 className="size-3.5 animate-spin" aria-hidden />}
+                      {saveStatus === 'unsaved' && <CircleDot className="size-3.5" aria-hidden />}
+                      {saveStatus === 'saved' && <CheckCircle2 className="size-3.5 text-muted-foreground/70" aria-hidden />}
+                    </span>
+                  </TooltipTrigger>
+                  <TooltipContent side="bottom">
+                    {saveStatus === 'saving' ? 'Saving…' : saveStatus === 'unsaved' ? 'Unsaved changes' : 'All changes saved'}
+                  </TooltipContent>
+                </Tooltip>
+              </TooltipProvider>
+            )}
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}

frontend/src/app/recollections/layout/RecollectionSidebar.tsx

@@ -0,0 +1,111 @@
+/**
+ * Recollection sidebar: Logos (pages), Katalogos, Flux. Shared by all recollection routes.
+ */
+
+import React, { useCallback } from 'react'
+import { useParams, useLocation, useNavigate } from 'react-router-dom'
+import { Button } from '@/components/ui/button'
+import { Plus, FileText } from 'lucide-react'
+import { FluxIcon } from '@/lib/icons'
+import { cn } from '@/lib/utils'
+import { useRecollectionSidebar } from './RecollectionSidebarContext'
+import { TreeBrowser } from './TreeBrowser'
+import {
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuItem,
+  sidebarMenuButtonVariants,
+} from '@/components/ui/sidebar'
+
+export function RecollectionSidebar() {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const { pathname } = useLocation()
+  const navigate = useNavigate()
+  const { tree, handleSelectPage, handleTreeChange } = useRecollectionSidebar()
+
+  const base = recollectionId ? `/recollections/${recollectionId}` : ''
+  const baseLogos = `${base}/logos`
+  const isKatalogosView = pathname.endsWith('/logos/katalogos')
+  const isFluxView = pathname.endsWith('/flux')
+
+  const handleAddPage = useCallback(() => {
+    // Add a new top-level page
+    const maxPos = Math.max(0, ...tree.filter((p) => p.parentId === null).map((p) => p.position), -1)
+    const newPage = {
+      id: `page-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+      title: 'Untitled',
+      parentId: null,
+      position: maxPos + 1,
+    }
+    handleTreeChange([...tree, newPage])
+    handleSelectPage(newPage.id)
+    navigate(`${baseLogos}?page=${encodeURIComponent(newPage.id)}`)
+  }, [tree, handleTreeChange, handleSelectPage, baseLogos, navigate])
+
+  return (
+    <div
+      className="flex h-full w-[var(--sidebar-width)] shrink-0 flex-col border-r border-sidebar-border bg-sidebar text-sidebar-foreground"
+      style={{ '--sidebar-width': '16rem' } as React.CSSProperties}
+    >
+      <SidebarContent className="flex-1 overflow-y-auto border-0 bg-transparent">
+        <SidebarGroup>
+          <div className="flex items-center justify-between gap-2 py-1.5">
+            <SidebarGroupLabel className="py-0">Logos</SidebarGroupLabel>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              className="h-6 gap-1 px-1.5 text-xs text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"
+              onClick={handleAddPage}
+            >
+              <Plus className="size-3.5" />
+              New page
+            </Button>
+          </div>
+          <SidebarGroupContent>
+            <TreeBrowser />
+          </SidebarGroupContent>
+        </SidebarGroup>
+        <SidebarGroup>
+          <SidebarGroupLabel>Katalogos</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              <SidebarMenuItem>
+                <button
+                  type="button"
+                  data-active={isKatalogosView}
+                  className={cn(sidebarMenuButtonVariants({ size: 'default' }), 'w-full')}
+                  onClick={() => navigate(`${base}/logos/katalogos`)}
+                >
+                  <FileText className="size-4 shrink-0 text-sidebar-foreground/70" />
+                  <span className="truncate">Artifacts</span>
+                </button>
+              </SidebarMenuItem>
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+        <SidebarGroup>
+          <SidebarGroupLabel>Flux</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              <SidebarMenuItem>
+                <button
+                  type="button"
+                  data-active={isFluxView}
+                  className={cn(sidebarMenuButtonVariants({ size: 'default' }), 'w-full')}
+                  onClick={() => navigate(`${base}/flux`)}
+                >
+                  <FluxIcon className="size-4 shrink-0 text-sidebar-foreground/70" />
+                  <span className="truncate">Canvas</span>
+                </button>
+              </SidebarMenuItem>
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      </SidebarContent>
+    </div>
+  )
+}

frontend/src/app/recollections/layout/RecollectionSidebarContext.tsx

@@ -0,0 +1,114 @@
+/**
+ * Context for the recollection sidebar: Logos page tree and active page, shared by
+ * RecollectionSidebar and LogosPage. Load/persist and URL sync live here.
+ */
+
+import React, { createContext, useCallback, useContext, useEffect, useState } from 'react'
+import { useParams, useSearchParams } from 'react-router-dom'
+import {
+  getLogosContent,
+  getLogosPageTree,
+  setLogosPageTree,
+  setLogosContentForPage,
+  removeLogosPageContent,
+  type LogosPageMeta,
+  type LogosPageId,
+} from '../state/recollectionStore'
+
+const MAIN_PAGE_ID: LogosPageId = 'main'
+
+export type RecollectionSidebarContextValue = {
+  tree: LogosPageMeta[]
+  activePageId: LogosPageId | null
+  setTree: React.Dispatch<React.SetStateAction<LogosPageMeta[]>>
+  handleSelectPage: (id: LogosPageId) => void
+  handleTreeChange: (tree: LogosPageMeta[]) => void
+  handleDeletePage: (pageId: LogosPageId) => void
+}
+
+const RecollectionSidebarContext = createContext<RecollectionSidebarContextValue | null>(null)
+
+export function useRecollectionSidebar(): RecollectionSidebarContextValue {
+  const ctx = useContext(RecollectionSidebarContext)
+  if (!ctx) throw new Error('useRecollectionSidebar must be used within RecollectionSidebarProvider')
+  return ctx
+}
+
+export function RecollectionSidebarProvider({ children }: { children: React.ReactNode }) {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const [searchParams, setSearchParams] = useSearchParams()
+  const [tree, setTree] = useState<LogosPageMeta[]>([])
+  const [activePageId, setActivePageId] = useState<LogosPageId | null>(null)
+
+  const baseLogosPath = recollectionId ? `/recollections/${recollectionId}/logos` : ''
+
+  const handleSelectPage = useCallback(
+    (id: LogosPageId) => {
+      setActivePageId(id)
+      if (recollectionId) {
+        setSearchParams({ page: id }, { replace: true })
+      }
+    },
+    [recollectionId, setSearchParams]
+  )
+
+  const handleTreeChange = useCallback((newTree: LogosPageMeta[]) => {
+    setTree(newTree)
+  }, [])
+
+  const handleDeletePage = useCallback(
+    (pageId: LogosPageId) => {
+      if (recollectionId) removeLogosPageContent(recollectionId, pageId)
+    },
+    [recollectionId]
+  )
+
+  // Load page tree from storage only when recollection changes (not on every searchParams change).
+  // Otherwise adding a new page would trigger searchParams change and this would overwrite tree before persist.
+  useEffect(() => {
+    if (!recollectionId) return
+    let t = getLogosPageTree(recollectionId)
+    if (t.length === 0) {
+      const legacy = getLogosContent(recollectionId)
+      const main: LogosPageMeta = { id: MAIN_PAGE_ID, title: 'Main', parentId: null, position: 0 }
+      setLogosContentForPage(recollectionId, MAIN_PAGE_ID, legacy ?? [])
+      setLogosPageTree(recollectionId, [main])
+      t = [main]
+    }
+    setTree(t)
+  }, [recollectionId])
+
+  // Sync activePageId from URL when searchParams or tree changes (e.g. after adding a page).
+  useEffect(() => {
+    if (!recollectionId) return
+    const pageFromUrl = searchParams.get('page')
+    setActivePageId((prev) => {
+      const validIdFromUrl = pageFromUrl && tree.some((p) => p.id === pageFromUrl) ? pageFromUrl : null
+      if (validIdFromUrl) return validIdFromUrl
+      const firstId = tree[0]?.id ?? null
+      if (prev != null && tree.some((p) => p.id === prev)) return prev
+      return firstId
+    })
+  }, [recollectionId, searchParams, tree])
+
+  // Persist tree when sidebar changes it.
+  useEffect(() => {
+    if (!recollectionId || tree.length === 0) return
+    setLogosPageTree(recollectionId, tree)
+  }, [recollectionId, tree])
+
+  const value: RecollectionSidebarContextValue = {
+    tree,
+    activePageId,
+    setTree,
+    handleSelectPage,
+    handleTreeChange,
+    handleDeletePage,
+  }
+
+  return (
+    <RecollectionSidebarContext.Provider value={value}>
+      {children}
+    </RecollectionSidebarContext.Provider>
+  )
+}

frontend/src/app/recollections/layout/RecollectionViewSwitcher.tsx

@@ -0,0 +1,94 @@
+/**
+ * View switcher: circle with current view icon; click cycles Logos → Katalogos → Flux.
+ * Keyboard shortcut: ⌘⇧↑ / ⌘⇧↓ to cycle view.
+ */
+
+import React, { useCallback, useEffect, useMemo } from 'react'
+import { useLocation, useNavigate, useParams } from 'react-router-dom'
+import { FluxIcon } from '@/lib/icons'
+import { FileText, LayoutGrid } from 'lucide-react'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
+import { getMode, pathForMode, RECOLLECTION_VIEW_MODES, viewLabel } from './recollectionNav'
+
+const ICON_SLOT_SIZE_REM = 2 // size-8 = 2rem
+
+function shortcutLabel() {
+  const isMac = typeof navigator !== 'undefined' && /Mac|iPod|iPhone|iPad/.test(navigator.platform)
+  return isMac ? '⌘⇧↑ / ⌘⇧↓' : 'Ctrl+Shift+↑ / Ctrl+Shift+↓'
+}
+
+export function RecollectionViewSwitcher() {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const { pathname } = useLocation()
+  const navigate = useNavigate()
+  const base = recollectionId ? `/recollections/${recollectionId}` : ''
+
+  const mode = useMemo(() => getMode(pathname), [pathname])
+  const modeIndex = RECOLLECTION_VIEW_MODES.indexOf(mode)
+
+  const goRelative = useCallback(
+    (delta: 1 | -1) => {
+      if (!base) return
+      const nextIndex = (modeIndex + delta + RECOLLECTION_VIEW_MODES.length) % RECOLLECTION_VIEW_MODES.length
+      navigate(pathForMode(base, RECOLLECTION_VIEW_MODES[nextIndex]))
+    },
+    [base, modeIndex, navigate]
+  )
+
+  const cycle = useCallback(() => {
+    goRelative(1)
+  }, [goRelative])
+
+  useEffect(() => {
+    const onKeyDown = (ev: KeyboardEvent) => {
+      const isMod = ev.ctrlKey || ev.metaKey
+      const isShortcut = isMod && ev.shiftKey && (ev.key === 'ArrowDown' || ev.key === 'ArrowUp')
+      if (!isShortcut) return
+      ev.preventDefault()
+      if (ev.key === 'ArrowDown') goRelative(1)
+      else if (ev.key === 'ArrowUp') goRelative(-1)
+    }
+    window.addEventListener('keydown', onKeyDown, true)
+    return () => window.removeEventListener('keydown', onKeyDown, true)
+  }, [goRelative])
+
+  if (!base) return null
+
+  const tooltipText = `${viewLabel(mode)} (${shortcutLabel()})`
+  const translateY = -modeIndex * ICON_SLOT_SIZE_REM
+
+  return (
+    <div className="flex h-9 shrink-0 items-center">
+      <TooltipProvider delayDuration={300}>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={cycle}
+              aria-label={tooltipText}
+              className="flex size-8 shrink-0 items-start justify-center overflow-hidden rounded-full transition-colors hover:bg-accent hover:text-accent-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:ring-offset-background"
+            >
+              <div
+                className="flex flex-col transition-transform duration-200 ease-out"
+                style={{ transform: `translateY(${translateY}rem)` }}
+              >
+                <div className="flex size-8 flex-shrink-0 items-center justify-center [&_svg]:shrink-0">
+                  <FileText className="size-3.5 text-muted-foreground" />
+                </div>
+                <div className="flex size-8 flex-shrink-0 items-center justify-center [&_svg]:shrink-0">
+                  <LayoutGrid className="size-3.5 text-muted-foreground" />
+                </div>
+                <div className="flex size-8 flex-shrink-0 items-center justify-center [&_svg]:shrink-0">
+                  <span className="inline-flex size-3.5 shrink-0 items-center justify-center">
+                    <FluxIcon className="size-full text-muted-foreground" />
+                  </span>
+                </div>
+              </div>
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">{tooltipText}</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    </div>
+  )
+}

frontend/src/app/recollections/layout/RecollectionsPageBackground.tsx

@@ -1,5 +1,5 @@
 /**
- * Subtle animated dot grid background for ProjectsPage.
+ * Subtle animated dot grid background for RecollectionsPage.
  * Matches canvas grid (20px gap), with gentle wave movement.
  */
 
@@ -17,7 +17,7 @@ function getDotColor(): string {
   return isDark ? 'rgba(255,255,255,0.18)' : 'rgba(0,0,0,0.12)'
 }
 
-export function ProjectsPageBackground({ className }: { className?: string }) {
+export function RecollectionsPageBackground({ className }: { className?: string }) {
   const canvasRef = useRef<HTMLCanvasElement>(null)
   const timeRef = useRef(0)
   const rafRef = useRef<number>(0)

frontend/src/app/recollections/layout/RenameRecollectionDialog.tsx

@@ -0,0 +1,94 @@
+/**
+ * Shared modal for renaming a recollection. Used by RecollectionsPage and RecollectionFileMenu.
+ */
+
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+
+export type RenameRecollectionDialogProps = {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  recollectionId: string
+  initialName: string
+  recollections: { id: string; name: string }[]
+  onRename: (id: string, newName: string) => void
+}
+
+export function RenameRecollectionDialog({
+  open,
+  onOpenChange,
+  recollectionId,
+  initialName,
+  recollections,
+  onRename,
+}: RenameRecollectionDialogProps) {
+  const [value, setValue] = useState(initialName)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    if (open) {
+      setValue(initialName)
+      const t = setTimeout(() => inputRef.current?.focus(), 0)
+      return () => clearTimeout(t)
+    }
+  }, [open, initialName])
+
+  const handleClose = useCallback(() => onOpenChange(false), [onOpenChange])
+
+  const handleSubmit = useCallback(() => {
+    const trimmed = value.trim()
+    if (!trimmed) return
+    onRename(recollectionId, trimmed)
+    onOpenChange(false)
+  }, [recollectionId, value, onRename, onOpenChange])
+
+  const isDuplicateName =
+    !!value.trim() &&
+    recollections.some(
+      (p) => p.id !== recollectionId && p.name.toLowerCase() === value.trim().toLowerCase()
+    )
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent onCloseAutoFocus={(e) => e.preventDefault()}>
+        <DialogHeader>
+          <DialogTitle>Rename recollection</DialogTitle>
+          <DialogDescription>Enter a new name for this recollection.</DialogDescription>
+        </DialogHeader>
+        <Input
+          ref={inputRef}
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') handleSubmit()
+            if (e.key === 'Escape') handleClose()
+          }}
+          placeholder="Recollection name"
+          aria-label="Recollection name"
+        />
+        {isDuplicateName && (
+          <p className="text-xs text-amber-600 dark:text-amber-500">
+            A recollection with this name already exists.
+          </p>
+        )}
+        <DialogFooter>
+          <Button variant="outline" onClick={handleClose}>
+            Cancel
+          </Button>
+          <Button onClick={handleSubmit} disabled={!value.trim()}>
+            Save
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

frontend/src/app/recollections/layout/TreeBrowser.tsx

@@ -0,0 +1,609 @@
+/**
+ * TreeBrowser: A tree browser component using react-arborist for managing
+ * Logos pages in a hierarchical folder structure.
+ * 
+ * Features:
+ * - Drag and drop reordering
+ * - Folder expansion/collapse
+ * - Context menu for actions
+ * - Shadcn theme integration
+ * - Inline editing for page titles
+ * - Smooth animations
+ * - Search functionality
+ * - Expand/collapse all
+ */
+
+import React, { useCallback, useMemo, useRef, useState } from 'react'
+import { useResizeHeight } from '@/hooks/useResizeHeight'
+import {
+  Tree,
+  NodeApi,
+  NodeRendererProps,
+  RowRendererProps,
+  TreeApi,
+  type CursorProps,
+} from 'react-arborist'
+import { cn } from '@/lib/utils'
+import {
+  FileText,
+  ChevronRight,
+  ChevronDown,
+  Plus,
+  MoreHorizontal,
+  Trash2,
+  Pencil,
+  Search,
+  ChevronsDownUp,
+  ChevronsUpDown,
+  X,
+  GripVertical,
+} from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { Input } from '@/components/ui/input'
+import { useRecollectionSidebar } from './RecollectionSidebarContext'
+import { useParams, useNavigate, useLocation } from 'react-router-dom'
+import type { LogosPageMeta } from '../state/recollectionStore'
+import { removeLogosPageContent } from '../state/recollectionStore'
+
+// Tree node: page metadata plus tree shape (react-arborist `node.data` is this whole object).
+type TreeNode = LogosPageMeta & {
+  children?: TreeNode[]
+  isFolder: boolean
+}
+
+// Convert flat tree to hierarchical structure
+function buildTree(pages: LogosPageMeta[]): TreeNode[] {
+  const pageMap = new Map<string, TreeNode>()
+  const rootNodes: TreeNode[] = []
+
+  // First pass: create all nodes
+  pages.forEach((page) => {
+    pageMap.set(page.id, {
+      ...page,
+      children: [],
+      isFolder: false,
+    })
+  })
+
+  // Second pass: build parent-child relationships
+  pages.forEach((page) => {
+    const node = pageMap.get(page.id)!
+    if (page.parentId === null) {
+      rootNodes.push(node)
+    } else {
+      const parent = pageMap.get(page.parentId)
+      if (parent) {
+        parent.children?.push(node)
+        parent.isFolder = true
+      }
+    }
+  })
+
+  // Sort children by position
+  function sortNodes(nodes: TreeNode[]) {
+    nodes.sort((a, b) => a.position - b.position)
+    nodes.forEach((node) => sortNodes(node.children || []))
+  }
+  sortNodes(rootNodes)
+
+  return rootNodes
+}
+
+// Memoize the buildTree result to avoid unnecessary re-creation
+function useTreeNodes(tree: LogosPageMeta[]) {
+  return useMemo(() => buildTree(tree), [tree])
+}
+
+// Inline editable title component
+function EditableTitle({
+  title,
+  onSave,
+  onCancel,
+}: {
+  title: string
+  onSave: (newTitle: string) => void
+  onCancel: () => void
+}) {
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  React.useEffect(() => {
+    inputRef.current?.focus()
+    inputRef.current?.select()
+  }, [])
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter') {
+      onSave(inputRef.current?.value || '')
+    } else if (e.key === 'Escape') {
+      onCancel()
+    }
+  }
+
+  return (
+    <input
+      ref={inputRef}
+      type="text"
+      defaultValue={title}
+      onBlur={(e) => onSave(e.currentTarget.value)}
+      onKeyDown={handleKeyDown}
+      className="w-full rounded px-1 py-0.5 text-sm outline-none ring-2 ring-ring focus:ring-2 transition-all duration-200 bg-background"
+      onClick={(e) => e.stopPropagation()}
+    />
+  )
+}
+
+const ROW_INDENT_PX = 20
+const ROW_GUTTER_PX = 8
+
+/**
+ * Line cursor = “insert as sibling at this indent” (not “drop into folder”).
+ * Triangle + dashed rail read as a slot between rows; matches sidebar theme.
+ */
+const LogosDropCursor = React.memo(function LogosDropCursor({ top, left, indent }: CursorProps) {
+  return (
+    <div
+      role="presentation"
+      aria-hidden
+      className="pointer-events-none absolute z-20 flex items-center gap-1.5"
+      style={{
+        top: top - 5,
+        left: left + ROW_GUTTER_PX,
+        right: Math.max(indent, ROW_GUTTER_PX),
+      }}
+    >
+      <span className="flex h-3 w-2.5 shrink-0 items-center justify-center text-primary drop-shadow-sm">
+        <svg width="9" height="10" viewBox="0 0 9 10" fill="currentColor" aria-hidden>
+          <path d="M0 5 L9 1.5 L9 8.5 Z" />
+        </svg>
+      </span>
+      <div className="flex h-3 min-w-[2rem] flex-1 items-center">
+        <div
+          className={cn(
+            'h-0 w-full border-t-2 border-dashed border-primary',
+            'shadow-[0_1px_0_0_hsl(var(--primary)/0.35)]',
+            'motion-safe:animate-[tree-drop-line-pulse_1.8s_ease-in-out_infinite]'
+          )}
+        />
+      </div>
+    </div>
+  )
+})
+
+/**
+ * Drag ref on a compact handle at the start of the row; handle is a floating pill shown on row hover
+ * (always visible on coarse pointers). Title/icon strip is click-to-navigate only.
+ */
+function LogosTreeNode({ node, dragHandle, style }: NodeRendererProps<TreeNode>) {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const navigate = useNavigate()
+  const { tree, handleSelectPage, handleTreeChange } = useRecollectionSidebar()
+
+  const base = recollectionId ? `/recollections/${recollectionId}` : ''
+  const baseLogos = `${base}/logos`
+
+  const handleToggle = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation()
+      node.toggle()
+    },
+    [node]
+  )
+
+  const handleSelect = useCallback(
+    (e: React.MouseEvent) => {
+      if (!node.state.isEditing && !node.state.isDragging) {
+        handleSelectPage(node.data.id)
+        navigate(`${baseLogos}?page=${encodeURIComponent(node.data.id)}`)
+      }
+    },
+    [handleSelectPage, node.data.id, baseLogos, navigate, node.state.isEditing, node.state.isDragging]
+  )
+
+  const handleRename = useCallback(() => {
+    node.edit()
+  }, [node])
+
+  const handleDelete = useCallback(() => {
+    const toDelete = new Set<string>()
+    function collectDescendants(id: string) {
+      toDelete.add(id)
+      tree.forEach((p) => {
+        if (p.parentId === id) collectDescendants(p.id)
+      })
+    }
+    collectDescendants(node.data.id)
+    if (recollectionId) {
+      toDelete.forEach((pageId) => {
+        removeLogosPageContent(recollectionId, pageId)
+      })
+    }
+    handleTreeChange(tree.filter((p) => !toDelete.has(p.id)))
+  }, [tree, handleTreeChange, node.data.id, recollectionId])
+
+  const handleAddChild = useCallback(() => {
+    const maxPos = Math.max(
+      0,
+      ...tree.filter((p) => p.parentId === node.data.id).map((p) => p.position),
+      -1
+    )
+    const newPage: LogosPageMeta = {
+      id: `page-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+      title: 'Untitled',
+      parentId: node.data.id,
+      position: maxPos + 1,
+    }
+    handleTreeChange([...tree, newPage])
+    if (!node.isOpen) node.open()
+  }, [tree, handleTreeChange, node])
+
+  const hasChildren = (node.children?.length || 0) > 0
+  const pageTitle = node.data.title || 'Untitled'
+
+  return (
+    <div className="flex min-w-0 flex-1 items-center gap-1">
+      {/* Floating drag pill: expands on row hover; coarse pointers keep it tappable */}
+      <div
+        className={cn(
+          'flex shrink-0 items-center justify-center overflow-hidden',
+          'transition-[width,opacity] duration-200 ease-out',
+          'w-0 opacity-0 group-hover:w-4 group-hover:opacity-100',
+          '[@media(pointer:coarse)]:w-5 [@media(pointer:coarse)]:opacity-100',
+          node.state.isDragging && 'w-4 opacity-100 [@media(pointer:coarse)]:w-5',
+          node.state.isEditing && 'pointer-events-none w-0 opacity-0'
+        )}
+      >
+        <div
+          ref={dragHandle}
+          style={{ ...style, paddingLeft: 0 }}
+          title={node.state.isEditing ? undefined : 'Drag to reorder'}
+          className={cn(
+            'logos-tree-drag-handle group/drag',
+            'relative flex h-6 w-4 shrink-0 touch-none items-center justify-center rounded-md',
+            '[@media(pointer:coarse)]:h-7 [@media(pointer:coarse)]:w-5',
+            'border border-sidebar-border/50 bg-sidebar-accent/40',
+            'text-sidebar-foreground/70',
+            'transition-[color,background-color,border-color,box-shadow,transform] duration-150 ease-out',
+            'hover:border-sidebar-border hover:bg-sidebar-accent hover:text-sidebar-accent-foreground',
+            'hover:shadow-sm',
+            'active:scale-[0.97] active:cursor-grabbing',
+            'cursor-grab outline-none',
+            'dark:border-sidebar-border/55 dark:bg-sidebar-accent/35 dark:text-sidebar-foreground/75',
+            'dark:hover:bg-sidebar-accent dark:hover:text-sidebar-accent-foreground',
+            node.state.isDragging &&
+              'cursor-grabbing border-primary/55 bg-primary/18 text-primary shadow-sm ring-1 ring-primary/30 dark:border-primary/50 dark:bg-primary/22 dark:text-primary'
+          )}
+          onClick={(e) => e.stopPropagation()}
+        >
+          <GripVertical
+            className={cn(
+              'size-3 shrink-0 text-current transition-opacity duration-150 opacity-85 group-hover/drag:opacity-100',
+              node.state.isDragging && 'opacity-100'
+            )}
+            strokeWidth={2}
+          />
+        </div>
+      </div>
+
+      {hasChildren ? (
+        <button
+          type="button"
+          className="shrink-0 p-0.5 hover:bg-sidebar-accent rounded transition-colors"
+          onClick={handleToggle}
+        >
+          {node.isOpen ? (
+            <ChevronDown className="size-3.5 text-sidebar-foreground/70" />
+          ) : (
+            <ChevronRight className="size-3.5 text-sidebar-foreground/70" />
+          )}
+        </button>
+      ) : (
+        <div className="w-4 shrink-0" />
+      )}
+
+      <div
+        className={cn(
+          'flex min-h-[28px] min-w-0 flex-1 items-center gap-1 rounded-md px-0.5 -mx-0.5',
+          node.state.isEditing ? 'cursor-text' : 'cursor-pointer hover:bg-sidebar-accent/40'
+        )}
+        onClick={handleSelect}
+      >
+        <FileText className="size-4 shrink-0 text-sidebar-foreground/70" />
+
+        <div className="min-w-0 flex-1">
+          {node.state.isEditing ? (
+            <EditableTitle
+              title={node.data.title}
+              onSave={(newTitle) => {
+                if (newTitle.trim()) {
+                  handleTreeChange(
+                    tree.map((p) => (p.id === node.data.id ? { ...p, title: newTitle.trim() } : p))
+                  )
+                }
+                node.submit(newTitle)
+              }}
+              onCancel={() => node.reset()}
+            />
+          ) : (
+            <span className="block truncate select-none">{pageTitle}</span>
+          )}
+        </div>
+      </div>
+
+      <div
+        className="flex shrink-0 items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100"
+        onPointerDown={(e) => e.stopPropagation()}
+      >
+        <button
+          type="button"
+          className="p-0.5 hover:bg-sidebar-accent rounded transition-colors"
+          onClick={(e) => {
+            e.stopPropagation()
+            handleAddChild()
+          }}
+          title="Add child page"
+        >
+          <Plus className="size-3.5 text-sidebar-foreground/70" />
+        </button>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <button
+              type="button"
+              className="p-0.5 hover:bg-sidebar-accent rounded transition-colors"
+              onClick={(e) => e.stopPropagation()}
+            >
+              <MoreHorizontal className="size-3.5 text-sidebar-foreground/70" />
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-40" onClick={(e) => e.stopPropagation()}>
+            <DropdownMenuItem onClick={handleRename}>
+              <Pencil className="mr-2 size-3.5" />
+              Rename
+            </DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem onClick={handleDelete} className="text-destructive focus:text-destructive">
+              <Trash2 className="mr-2 size-3.5" />
+              Delete
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+    </div>
+  )
+}
+
+/** Drop target + layout shell; `children` must be the Node renderer (drag layer). */
+function TreeRow({ node, innerRef, attrs, children }: RowRendererProps<TreeNode>) {
+  const { pathname } = useLocation()
+  const { activePageId } = useRecollectionSidebar()
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const base = recollectionId ? `/recollections/${recollectionId}` : ''
+  const baseLogos = `${base}/logos`
+  const isActive = pathname.startsWith(baseLogos) && activePageId === node.data.id
+  const level = node.level
+  const indentPx = ROW_GUTTER_PX + level * ROW_INDENT_PX
+
+  return (
+    <div
+      ref={innerRef}
+      {...attrs}
+      style={{
+        ...attrs.style,
+        paddingLeft: `${indentPx}px`,
+      }}
+      className={cn(
+        'group relative flex items-center gap-1 py-1 pr-2 text-sm rounded-md transition-[box-shadow,background-color,ring-color] duration-150',
+        'hover:bg-sidebar-accent hover:text-sidebar-accent-foreground',
+        isActive && 'bg-sidebar-accent text-sidebar-accent-foreground',
+        node.state.isDragging && 'cursor-grabbing opacity-45',
+        // Folder drop target: index === null in library — reads as “open container”, not a line between rows
+        node.state.willReceiveDrop &&
+          'cursor-copy bg-sidebar-accent/30 ring-2 ring-inset ring-dashed ring-sidebar-ring/80 shadow-[inset_0_0_0_1px_hsl(var(--sidebar-border))]'
+      )}
+      title={node.state.willReceiveDrop ? 'Release to drop inside this folder' : undefined}
+    >
+      {level > 0 && (
+        <div
+          className="pointer-events-none absolute bottom-0 top-0 border-l-2 border-sidebar-border/45"
+          style={{ left: `${ROW_GUTTER_PX + (level - 1) * ROW_INDENT_PX + ROW_INDENT_PX / 2}px` }}
+        />
+      )}
+      {children}
+    </div>
+  )
+}
+
+export function TreeBrowser() {
+  const { tree, handleTreeChange } = useRecollectionSidebar()
+  const [searchQuery, setSearchQuery] = useState('')
+  const treeRef = useRef<TreeApi<TreeNode> | null>(null)
+  const [treeContainerHeight, treeContainerRef] = useResizeHeight(600)
+
+  // Build tree from flat structure
+  const treeNodes = useTreeNodes(tree)
+
+  // Filter tree based on search query
+  const filteredTree = useMemo(() => {
+    if (!searchQuery.trim()) return treeNodes
+
+    const searchTerm = searchQuery.toLowerCase()
+
+    function filterNodes(nodes: TreeNode[]): TreeNode[] {
+      const result: TreeNode[] = []
+      for (const node of nodes) {
+        const matches = node.title.toLowerCase().includes(searchTerm)
+        const children = filterNodes(node.children || [])
+
+        if (matches || children.length > 0) {
+          result.push({
+            ...node,
+            children: children.length > 0 ? children : undefined,
+          })
+        }
+      }
+      return result
+    }
+
+    return filterNodes(treeNodes)
+  }, [treeNodes, searchQuery])
+
+  // Get all folder IDs for initial open state
+  const initialOpenState = useMemo(() => {
+    const folderIds: Record<string, boolean> = {}
+    function collectIds(nodes: TreeNode[]) {
+      nodes.forEach((node) => {
+        if (node.isFolder) {
+          folderIds[node.id] = true
+          collectIds(node.children || [])
+        }
+      })
+    }
+    collectIds(treeNodes)
+    return folderIds
+  }, [treeNodes])
+
+  // Handle drag and drop reordering (react-arborist onMove)
+  const handleMove = useCallback(
+    ({
+      dragIds,
+      parentId: newParentId,
+      index,
+    }: {
+      dragIds: string[]
+      parentId: string | null
+      index: number
+    }) => {
+      const dragId = dragIds[0]
+      if (!dragId) return
+
+      const dragged = tree.find((p) => p.id === dragId)
+      if (!dragged) return
+
+      const oldParentId = dragged.parentId
+      const moved: LogosPageMeta = { ...dragged, parentId: newParentId }
+
+      const newSiblings = tree
+        .filter((p) => p.parentId === newParentId && p.id !== dragId)
+        .sort((a, b) => a.position - b.position)
+      newSiblings.splice(index, 0, moved)
+
+      const updates = new Map<string, LogosPageMeta>()
+      newSiblings.forEach((p, i) => {
+        updates.set(p.id, { ...p, parentId: newParentId, position: i })
+      })
+
+      if (oldParentId !== newParentId) {
+        tree
+          .filter((p) => p.parentId === oldParentId && p.id !== dragId)
+          .sort((a, b) => a.position - b.position)
+          .forEach((p, i) => {
+            updates.set(p.id, { ...p, position: i })
+          })
+      }
+
+      handleTreeChange(tree.map((p) => updates.get(p.id) ?? p))
+    },
+    [tree, handleTreeChange]
+  )
+
+  // Expand all folders
+  const handleExpandAll = useCallback(() => {
+    treeRef.current?.openAll()
+  }, [])
+
+  // Collapse all folders
+  const handleCollapseAll = useCallback(() => {
+    treeRef.current?.closeAll()
+  }, [])
+
+  // Clear search
+  const handleClearSearch = useCallback(() => {
+    setSearchQuery('')
+  }, [])
+
+  // Fixed prop shape: react-arborist TreeProvider uses [...Object.values(treeProps), …] as useMemo deps;
+  // varying key counts on the props object trigger "dependency array changed size" warnings.
+  const arboristTreeProps = useMemo(
+    () => ({
+      data: filteredTree,
+      idAccessor: 'id' as const,
+      childrenAccessor: 'children' as const,
+      width: '100%' as const,
+      height: Math.max(treeContainerHeight, 100),
+      rowHeight: 32,
+      indent: ROW_INDENT_PX,
+      renderRow: TreeRow,
+      initialOpenState,
+      onMove: handleMove,
+      disableDrag: Boolean(searchQuery),
+      disableDrop: Boolean(searchQuery),
+      className: 'react-arborist-tree',
+      renderCursor: LogosDropCursor,
+      children: LogosTreeNode,
+    }),
+    [filteredTree, initialOpenState, handleMove, searchQuery, treeContainerHeight]
+  )
+
+  return (
+    <div className="flex flex-col gap-2 h-full">
+      {/* Search Toolbar */}
+      <div className="flex items-center gap-1.5">
+        <div className="relative flex-1">
+          <Search className="absolute left-2 top-1/2 -translate-y-1/2 size-3.5 text-sidebar-foreground/50 pointer-events-none" />
+          <Input
+            type="text"
+            placeholder="Search pages..."
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            className="pl-7 pr-7 h-7 text-xs bg-sidebar-accent/50 border-sidebar-border"
+          />
+          {searchQuery && (
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              className="absolute right-0 top-1/2 -translate-y-1/2 h-7 w-7"
+              onClick={handleClearSearch}
+            >
+              <X className="size-3" />
+            </Button>
+          )}
+        </div>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              className="h-7 w-7 shrink-0"
+              title="Expand/Collapse options"
+            >
+              <ChevronsUpDown className="size-3.5" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem onClick={handleExpandAll}>
+              <ChevronsDownUp className="mr-2 size-3.5" />
+              Expand all
+            </DropdownMenuItem>
+            <DropdownMenuItem onClick={handleCollapseAll}>
+              <ChevronsUpDown className="mr-2 size-3.5" />
+              Collapse all
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+
+      {/* Tree */}
+      <div ref={treeContainerRef} className="flex-1 min-h-0 overflow-hidden">
+        <Tree ref={treeRef} {...arboristTreeProps} />
+      </div>
+    </div>
+  )
+}

frontend/src/app/recollections/layout/recollectionNav.ts

@@ -0,0 +1,25 @@
+/**
+ * Recollection navigation helpers: current view mode from pathname, labels for breadcrumbs.
+ */
+
+export type RecollectionViewMode = 'logos' | 'katalogos' | 'flux'
+
+export function getMode(pathname: string): RecollectionViewMode {
+  if (pathname.endsWith('/flux')) return 'flux'
+  if (pathname.endsWith('/logos/katalogos')) return 'katalogos'
+  return 'logos'
+}
+
+export function viewLabel(mode: RecollectionViewMode): string {
+  if (mode === 'katalogos') return 'Katalogos'
+  if (mode === 'flux') return 'Flux'
+  return 'Logos'
+}
+
+export const RECOLLECTION_VIEW_MODES: RecollectionViewMode[] = ['logos', 'katalogos', 'flux']
+
+export function pathForMode(base: string, mode: RecollectionViewMode): string {
+  if (mode === 'flux') return `${base}/flux`
+  if (mode === 'katalogos') return `${base}/logos/katalogos`
+  return `${base}/logos`
+}

frontend/src/app/recollections/logos/LogosPage.tsx

@@ -0,0 +1,214 @@
+/**
+ * Logos page: BlockNote editor for the recollection. Content only; sidebar is at layout level.
+ * Content persisted in recollection store.
+ */
+
+import React, { useCallback, useEffect, useMemo, useRef, useState, forwardRef } from 'react'
+import { useParams, useLocation, useSearchParams } from 'react-router-dom'
+import { usePlatform } from '@/app/kosmos/KosmosContext'
+import { FluxIcon } from '@/lib/icons'
+import { useCreateBlockNote, getDefaultReactSlashMenuItems, SuggestionMenuController } from '@blocknote/react'
+import { BlockNoteView } from '@blocknote/shadcn'
+import { useTheme } from '@/lib/themeContext'
+import { useRecollectionActions } from '../layout/RecollectionActionsContext'
+import { useRecollectionSidebar } from '../layout/RecollectionSidebarContext'
+import {
+  getLogosContentForPage,
+  setLogosContentForPage,
+  type StoredLogosContent,
+} from '../state/recollectionStore'
+import { logosSchema } from './logosSchema'
+import { KatalogosPage } from '../katalogos/KatalogosPage'
+import { toast } from 'sonner'
+
+/** Wraps BlockNoteView so refs go to a div, not the function component (avoids ref warning). */
+const BlockNoteViewWrapper = forwardRef<HTMLDivElement, React.ComponentProps<typeof BlockNoteView>>(
+  function BlockNoteViewWrapper(props, ref) {
+    const { className, ref: _ref, ...rest } = props as React.ComponentProps<typeof BlockNoteView> & { ref?: unknown }
+    return (
+      <div ref={ref} className={`logos-blocknote ${className ?? ''}`} style={{ minHeight: '100%', width: '100%' }}>
+        <BlockNoteView {...rest} />
+      </div>
+    )
+  }
+)
+const SAVE_DEBOUNCE_MS = 400
+
+/** Known React ref warning from BlockNote/Radix internals; we can't fix it in our code. Suppress once at load so it's active before first BlockNote render. */
+function isBlockNoteRefWarning(args: unknown[]): boolean {
+  const s = args.map((a) => (typeof a === 'string' ? a : String(a))).join(' ')
+  return (
+    s.includes('Function components cannot be given refs') &&
+    s.includes('ForwardRef') &&
+    s.includes('blocknote')
+  )
+}
+let blockNoteRefWarningPatched = false
+function patchBlockNoteRefWarning() {
+  if (blockNoteRefWarningPatched) return
+  blockNoteRefWarningPatched = true
+  const orig = console.error
+  console.error = (...args: unknown[]) => {
+    if (isBlockNoteRefWarning(args)) return
+    orig.apply(console, args)
+  }
+}
+
+export function LogosPage() {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const { pathname } = useLocation()
+  const [searchParams, setSearchParams] = useSearchParams()
+  const { recollections } = usePlatform()
+  const { theme } = useTheme()
+  const { setLogosSlot } = useRecollectionActions()
+  const { tree, activePageId } = useRecollectionSidebar()
+  const recollection = recollectionId ? recollections.find((p) => p.id === recollectionId) : null
+  const [reloadKey, setReloadKey] = useState(0)
+  const saveTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const [saveStatus, setSaveStatus] = useState<'saved' | 'unsaved' | 'saving'>('saved')
+
+  const isKatalogosView = pathname.endsWith('/logos/katalogos')
+
+  // When on Logos (not Katalogos) with a selected page but no page param, sync URL so refresh keeps the page.
+  useEffect(() => {
+    if (isKatalogosView || !activePageId || searchParams.get('page') === activePageId) return
+    setSearchParams({ page: activePageId }, { replace: true })
+  }, [isKatalogosView, activePageId, searchParams, setSearchParams])
+
+  const initialContent = useMemo(() => {
+    if (!recollectionId || !activePageId) return undefined
+    const content = getLogosContentForPage(recollectionId, activePageId)
+    if (!content || !Array.isArray(content) || content.length === 0) return undefined
+    return content
+  }, [recollectionId, activePageId, reloadKey])
+
+  const editor = useCreateBlockNote(
+    { schema: logosSchema, initialContent },
+    [recollectionId, activePageId, reloadKey]
+  )
+
+  const persistContent = useCallback(() => {
+    if (!recollectionId || !activePageId || !editor) return
+    setSaveStatus('saving')
+    try {
+      const doc = editor.document
+      const serialized = JSON.parse(JSON.stringify(doc)) as StoredLogosContent
+      setLogosContentForPage(recollectionId, activePageId, serialized)
+      setSaveStatus('saved')
+    } catch {
+      setSaveStatus('unsaved')
+    }
+  }, [recollectionId, activePageId, editor])
+
+  const onSave = useCallback(() => {
+    persistContent()
+    toast.success('Saved')
+  }, [persistContent])
+
+  useEffect(() => {
+    if (!editor || !recollectionId || !activePageId) return
+    const handleChange = () => {
+      setSaveStatus('unsaved')
+      if (saveTimeoutRef.current) clearTimeout(saveTimeoutRef.current)
+      saveTimeoutRef.current = setTimeout(() => {
+        saveTimeoutRef.current = null
+        persistContent()
+      }, SAVE_DEBOUNCE_MS)
+    }
+    editor.onChange(handleChange)
+    return () => {
+      if (saveTimeoutRef.current) {
+        clearTimeout(saveTimeoutRef.current)
+        saveTimeoutRef.current = null
+      }
+    }
+  }, [editor, recollectionId, activePageId, persistContent])
+
+  useEffect(() => {
+    if (isKatalogosView || !editor || !recollectionId || !activePageId) {
+      if (isKatalogosView) setLogosSlot(null)
+      return
+    }
+    const slot = {
+      saveStatus,
+      onSave,
+      canSave: true,
+      undo: () => (editor as { undo?: () => void }).undo?.(),
+      redo: () => (editor as { redo?: () => void }).redo?.(),
+      canUndo: true,
+      canRedo: true,
+      onRefreshFromStore: () => setReloadKey((k) => k + 1),
+    }
+    setLogosSlot(slot)
+    return () => setLogosSlot(null)
+  }, [isKatalogosView, setLogosSlot, saveStatus, onSave, editor, recollectionId, activePageId])
+
+  const activePage = tree.find((p) => p.id === activePageId)
+
+  patchBlockNoteRefWarning()
+
+  const getSlashMenuItems = useCallback(
+    async (query: string) => {
+      const defaultItems = getDefaultReactSlashMenuItems(editor)
+      const fluxItem = {
+        title: 'Insert Artifact',
+        subtext: 'Insert an Artifact produced by a Flux rendering node',
+        icon: <FluxIcon className="size-4" />,
+        onItemClick: () => {
+          const pos = editor.getTextCursorPosition()
+          editor.replaceBlocks([pos.block.id], [{ type: 'fluxOutput', props: {} }])
+        },
+        aliases: ['artifact', 'flux', 'output', 'render'] as const,
+        group: 'Artifacts',
+      }
+      const all = [...defaultItems, fluxItem]
+      const q = query.trim().toLowerCase()
+      if (!q) return all
+      return all.filter(
+        (item) =>
+          item.title.toLowerCase().includes(q) ||
+          (item.aliases && item.aliases.some((a: string) => a.toLowerCase().includes(q)))
+      )
+    },
+    [editor]
+  )
+
+  if (!recollectionId) {
+    return (
+      <div className="flex h-full min-h-0 flex-1 flex-col items-center justify-center p-8 text-muted-foreground">
+        <p className="text-sm">No recollection selected.</p>
+      </div>
+    )
+  }
+
+  if (isKatalogosView) {
+    return (
+      <div className="flex h-full min-h-0 flex-1 flex-col overflow-auto bg-background">
+        <KatalogosPage />
+      </div>
+    )
+  }
+
+  if (activePageId == null || !editor) {
+    return (
+      <div className="flex h-full min-h-0 flex-1 flex-col items-center justify-center bg-background text-sm text-muted-foreground">
+        {tree.length === 0 ? 'Loading…' : 'Select a page'}
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex h-full min-h-0 flex-1 flex-col overflow-auto bg-background">
+      <div className="mx-auto w-full max-w-3xl p-4">
+        <BlockNoteViewWrapper
+          editor={editor as any}
+          theme={theme}
+          className="min-h-full w-full"
+          slashMenu={false}
+        >
+          <SuggestionMenuController triggerCharacter="/" getItems={getSlashMenuItems} />
+        </BlockNoteViewWrapper>
+      </div>
+    </div>
+  )
+}

frontend/src/app/recollections/logos/blocks/fluxOutputBlock.tsx

@@ -0,0 +1,200 @@
+/**
+ * BlockNote block "Flux output": insert Artifacts produced by Flux rendering nodes into Logos.
+ * Empty state: placeholder + picker over getRenderOutputCache(recollectionId).
+ * Filled state: when nodeId is set, display is live from the cache (updates when the rendering node changes in Flux);
+ * otherwise or when cache entry is missing, show stored content (static).
+ * Shows live/static status and time since last update.
+ */
+
+import React, { useCallback, useState } from 'react'
+import { useNavigate, useParams } from 'react-router-dom'
+import { createReactBlockSpec } from '@blocknote/react'
+import type { ReactCustomBlockRenderProps } from '@blocknote/react'
+import {
+  getRenderOutputCache,
+  formatTimeSinceLastUpdate,
+  type RenderOutputCacheEntry,
+} from '../../state/recollectionStore'
+import { Button } from '@/components/ui/button'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+
+const fluxOutputBlockConfig = {
+  type: 'fluxOutput' as const,
+  propSchema: {
+    nodeId: {
+      default: '',
+    },
+    contentType: {
+      default: 'image' as const,
+      values: ['image', 'html'] as const,
+    },
+    content: {
+      default: '',
+    },
+    label: {
+      default: '',
+    },
+  },
+  content: 'none' as const,
+}
+
+function FluxOutputBlockContent({
+  block,
+  editor,
+  contentRef,
+}: ReactCustomBlockRenderProps<'fluxOutput', typeof fluxOutputBlockConfig.propSchema, 'none'>) {
+  const { recollectionId } = useParams<{ recollectionId: string }>()
+  const navigate = useNavigate()
+  const [pickerOpen, setPickerOpen] = useState(false)
+  const nodeId = block.props.nodeId ?? ''
+  const storedContent = block.props.content ?? ''
+  const storedContentType = block.props.contentType ?? 'image'
+  const storedLabel = block.props.label ?? ''
+
+  const handleSelect = useCallback(
+    (entry: RenderOutputCacheEntry) => {
+      editor.updateBlock(block.id, {
+        props: {
+          nodeId: entry.nodeId,
+          contentType: entry.type,
+          content: entry.content,
+          label: entry.label,
+        },
+      })
+      setPickerOpen(false)
+    },
+    [editor, block.id]
+  )
+
+  const artifacts = recollectionId ? getRenderOutputCache(recollectionId) : []
+
+  // Resolve display from cache when block is tied to a node (live); otherwise use stored props (static).
+  const liveEntry = nodeId && recollectionId ? artifacts.find((e) => e.nodeId === nodeId) : null
+  const content = liveEntry ? liveEntry.content : storedContent
+  const rawContentType = liveEntry ? liveEntry.type : storedContentType
+  const label = liveEntry ? liveEntry.label : storedLabel
+  const isLive = Boolean(liveEntry)
+  const timeSince = liveEntry?.updatedAt != null ? formatTimeSinceLastUpdate(liveEntry.updatedAt) : ''
+  // If content is SVG but type was stored as html, show as image (fixes incorrect cache or legacy data).
+  const isSvgContent = Boolean(content?.trim() && /<svg[\s>]/i.test(content.trim()))
+  const contentType = rawContentType === 'image' || isSvgContent ? 'image' : 'html'
+
+  const handleViewInFlux = useCallback(() => {
+    if (recollectionId && nodeId) {
+      navigate(`/recollections/${recollectionId}/flux?focusNode=${encodeURIComponent(nodeId)}`)
+    }
+  }, [recollectionId, nodeId, navigate])
+
+  // Empty: show placeholder + picker when nothing inserted yet
+  if (!content) {
+    return (
+      <div
+        ref={contentRef}
+        className="min-h-[80px] rounded-lg border border-dashed border-muted-foreground/30 bg-muted/20 p-4"
+      >
+        <Popover open={pickerOpen} onOpenChange={setPickerOpen}>
+          <PopoverTrigger asChild>
+            <Button variant="outline" size="sm" className="gap-2">
+              Insert Artifact
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent className="w-80 p-0" align="start">
+            {artifacts.length === 0 ? (
+              <div className="p-4 text-sm text-muted-foreground">
+                No Artifacts yet. In Flux, run a graph with a rendering node; its output will be cached as an Artifact
+                and appear here and in Katalogos automatically.
+              </div>
+            ) : (
+              <ul className="max-h-64 overflow-auto py-2">
+                {artifacts.map((entry) => (
+                  <li key={entry.nodeId}>
+                    <button
+                      type="button"
+                      className="w-full px-4 py-2 text-left text-sm hover:bg-muted"
+                      onClick={() => handleSelect(entry)}
+                    >
+                      {entry.label || entry.nodeId}
+                      <span className="ml-2 text-muted-foreground">({entry.type})</span>
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </PopoverContent>
+        </Popover>
+      </div>
+    )
+  }
+
+  // Filled: card layout with header (label + live/static status + time) and content
+  const header = (
+    <div className="flex flex-wrap items-center justify-between gap-2 border-b border-border/60 bg-muted/30 px-3 py-1.5 rounded-t-lg">
+      <div className="flex min-w-0 items-center gap-2">
+        {label ? <span className="truncate text-xs font-medium text-foreground">{label}</span> : null}
+        <span
+          className={
+            isLive
+              ? 'inline-flex items-center gap-1 rounded-full bg-emerald-500/10 px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide text-emerald-600 dark:text-emerald-400'
+              : 'inline-flex items-center gap-1 rounded-full bg-muted px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground'
+          }
+        >
+          {isLive && <span className="h-1 w-1 shrink-0 rounded-full bg-emerald-500" aria-hidden />}
+          {isLive ? 'Live' : 'Static'}
+        </span>
+        {timeSince ? (
+          <span className="text-[10px] text-muted-foreground">{timeSince}</span>
+        ) : null}
+      </div>
+      {nodeId && recollectionId ? (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          className="h-6 px-2 text-[10px] text-muted-foreground hover:text-foreground"
+          onClick={handleViewInFlux}
+        >
+          View in Flux
+        </Button>
+      ) : null}
+    </div>
+  )
+
+  if (contentType === 'image') {
+    const src =
+      content.startsWith('data:') ? content : `data:image/svg+xml;utf8,${encodeURIComponent(content)}`
+    return (
+      <div
+        ref={contentRef}
+        className="min-h-[40px] overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-sm"
+      >
+        {header}
+        <div className="p-2">
+          <img src={src} alt={label || 'Artifact'} className="max-w-full rounded-md border border-border/60 object-contain" />
+        </div>
+      </div>
+    )
+  }
+
+  // HTML: render in iframe to limit script execution (XSS safety)
+  return (
+    <div
+      ref={contentRef}
+      className="min-h-[40px] overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-sm"
+    >
+      {header}
+      <div className="p-2">
+        <iframe
+          title={label || 'Artifact HTML'}
+          srcDoc={content}
+          className="min-h-[120px] w-full rounded-md border border-border/60 bg-background"
+          sandbox="allow-same-origin"
+        />
+      </div>
+    </div>
+  )
+}
+
+export const createFluxOutputBlock = () =>
+  createReactBlockSpec(fluxOutputBlockConfig, {
+    render: FluxOutputBlockContent,
+  })

frontend/src/app/recollections/logos/logosSchema.ts

@@ -0,0 +1,17 @@
+/**
+ * BlockNote schema for Logos: default blocks + Flux output block.
+ */
+
+import { BlockNoteSchema, defaultBlockSpecs } from '@blocknote/core'
+import { createFluxOutputBlock } from './blocks/fluxOutputBlock'
+
+const fluxOutputBlock = createFluxOutputBlock()
+
+export const logosSchema = BlockNoteSchema.create({
+  blockSpecs: {
+    ...defaultBlockSpecs,
+    fluxOutput: fluxOutputBlock,
+  },
+})
+
+export type LogosSchema = typeof logosSchema

frontend/src/app/recollections/state/recollectionGraphStorage.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-recollection graph persistence. Re-exports from recollectionStore for backward compatibility.
+ * New code should use recollectionStore (getGraph, setGraph, removeRecollectionData) directly.
+ */
+
+import {
+  getGraph,
+  setGraph,
+  removeRecollectionData,
+  RECOLLECTION_FILE_EXT,
+  RECOLLECTION_VERSION,
+  type StoredGraphState,
+} from './recollectionStore'
+
+export type { StoredGraphState }
+export { RECOLLECTION_FILE_EXT, RECOLLECTION_VERSION }
+
+export function getGraphStorageKey(recollectionId: string): string {
+  return `zui_graph_${recollectionId}`
+}
+
+export const loadGraphFromStorage = getGraph
+export const saveGraphToStorage = setGraph
+export const removeGraphFromStorage = removeRecollectionData

frontend/src/app/recollections/state/recollectionStore.ts

@@ -0,0 +1,283 @@
+/**
+ * Per-recollection persistence: graph (Flux) and logos (BlockNote) state.
+ * Single API for loading, saving, and removing all data for a recollection.
+ */
+
+import type { StoredGraphState } from '@/lib/graph/state'
+
+export type { StoredGraphState }
+
+/** BlockNote document: array of blocks (PartialBlock). Stored as JSON. */
+export type StoredLogosContent = Record<string, unknown>[]
+
+/** Id for a Logos page or subpage. */
+export type LogosPageId = string
+
+/** Metadata for one page or subpage in the Logos hierarchy (one level: page → subpages). */
+export type LogosPageMeta = {
+  id: LogosPageId
+  title: string
+  /** null = top-level page; non-null = subpage under that page. */
+  parentId: LogosPageId | null
+  /** Order among siblings (same parent). */
+  position: number
+}
+
+/** One entry in the render-output cache (one per rendering node, overwritten on each update). */
+export type RenderOutputCacheEntry = {
+  nodeId: string
+  label: string
+  type: 'image' | 'html'
+  content: string
+  /** Timestamp (ms) when this entry was last updated. */
+  updatedAt?: number
+}
+
+/** Returns a short "time since" string for display (e.g. "Just now", "2 min ago"). */
+export function formatTimeSinceLastUpdate(updatedAt: number | undefined): string {
+  if (updatedAt == null || typeof updatedAt !== 'number') return ''
+  const delta = Date.now() - updatedAt
+  if (delta < 15_000) return 'Just now'
+  if (delta < 60_000) return `${Math.round(delta / 1000)}s ago`
+  if (delta < 3600_000) return `${Math.round(delta / 60_000)} min ago`
+  if (delta < 86400_000) return `${Math.round(delta / 3600_000)}h ago`
+  return `${Math.round(delta / 86400_000)}d ago`
+}
+
+export const RECOLLECTION_FILE_EXT = '.zui.json'
+export const RECOLLECTION_VERSION = 1
+
+const GRAPH_KEY_PREFIX = 'zui_graph_'
+const LOGOS_KEY_PREFIX = 'zui_logos_'
+const LOGOS_PAGE_TREE_PREFIX = 'zui_logos_pagetree_'
+const LOGOS_PAGE_CONTENT_PREFIX = 'zui_logos_page_'
+const RENDER_CACHE_KEY_PREFIX = 'zui_render_cache_'
+
+function getGraphKey(recollectionId: string): string {
+  return `${GRAPH_KEY_PREFIX}${recollectionId}`
+}
+
+function getLogosKey(recollectionId: string): string {
+  return `${LOGOS_KEY_PREFIX}${recollectionId}`
+}
+
+function getLogosPageTreeKey(recollectionId: string): string {
+  return `${LOGOS_PAGE_TREE_PREFIX}${recollectionId}`
+}
+
+function getLogosPageContentKey(recollectionId: string, pageId: LogosPageId): string {
+  return `${LOGOS_PAGE_CONTENT_PREFIX}${recollectionId}_${pageId}`
+}
+
+function getRenderCacheKey(recollectionId: string): string {
+  return `${RENDER_CACHE_KEY_PREFIX}${recollectionId}`
+}
+
+// ---------------------------------------------------------------------------
+// Persisted State with Versioning
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrapper for persisted state with version tracking.
+ * Enables schema migrations when the version changes.
+ */
+export type PersistedState<T> = {
+  /** Current schema version. Increment when making breaking changes. */
+  version: number
+  /** The actual data being persisted. */
+  data: T
+  /** Timestamp (ms) when this data was last migrated. */
+  migratedAt?: number
+}
+
+/**
+ * Check if a persisted state has the expected version.
+ * @param state - The persisted state to check
+ * @param expectedVersion - The expected version number
+ * @returns true if versions match, false otherwise
+ */
+export function isVersionMatch<T>(state: PersistedState<T> | null, expectedVersion: number): boolean {
+  return state?.version === expectedVersion
+}
+
+/**
+ * Migrate persisted state to the latest version.
+ * Add migration logic here when changing the schema.
+ * 
+ * @param state - The persisted state to migrate
+ * @returns Migrated state with updated version
+ */
+export function migratePersistedState<T>(state: PersistedState<T>): PersistedState<T> {
+  if (state.version === RECOLLECTION_VERSION) {
+    return state
+  }
+
+  let migratedData = state.data
+  let migratedVersion = state.version
+
+  // Migration 0 -> 1: Initial version with version field
+  if (migratedVersion < 1) {
+    // Data from version 0 already has the correct structure
+    // Just add the version field
+    migratedVersion = 1
+  }
+
+  return {
+    version: migratedVersion,
+    data: migratedData,
+    migratedAt: Date.now(),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Graph Storage with Versioning
+// ---------------------------------------------------------------------------
+
+export function getGraph(recollectionId: string): StoredGraphState | null {
+  try {
+    const raw = localStorage.getItem(getGraphKey(recollectionId))
+    if (!raw) return null
+    const data = JSON.parse(raw) as unknown
+    if (
+      !data ||
+      typeof data !== 'object' ||
+      !Array.isArray((data as StoredGraphState).nodes) ||
+      !Array.isArray((data as StoredGraphState).edges)
+    )
+      return null
+    return data as StoredGraphState
+  } catch {
+    return null
+  }
+}
+
+export function setGraph(recollectionId: string, state: StoredGraphState): void {
+  localStorage.setItem(getGraphKey(recollectionId), JSON.stringify(state))
+}
+
+// ---------------------------------------------------------------------------
+// Logos Storage
+// ---------------------------------------------------------------------------
+
+export function getLogosContent(recollectionId: string): StoredLogosContent | null {
+  try {
+    const raw = localStorage.getItem(getLogosKey(recollectionId))
+    if (!raw) return null
+    const data = JSON.parse(raw) as unknown
+    if (!Array.isArray(data)) return null
+    if (!data.every((item) => item != null && typeof item === 'object')) return null
+    return data as StoredLogosContent
+  } catch {
+    return null
+  }
+}
+
+export function setLogosContent(recollectionId: string, content: StoredLogosContent): void {
+  localStorage.setItem(getLogosKey(recollectionId), JSON.stringify(content))
+}
+
+/** Logos page tree: ordered list of page metas (pages and subpages). */
+export function getLogosPageTree(recollectionId: string): LogosPageMeta[] {
+  try {
+    const raw = localStorage.getItem(getLogosPageTreeKey(recollectionId))
+    if (!raw) return []
+    const data = JSON.parse(raw) as unknown
+    if (!Array.isArray(data)) return []
+    return data.filter(
+      (item): item is LogosPageMeta =>
+        item != null &&
+        typeof item === 'object' &&
+        typeof (item as LogosPageMeta).id === 'string' &&
+        typeof (item as LogosPageMeta).title === 'string' &&
+        ((item as LogosPageMeta).parentId === null || typeof (item as LogosPageMeta).parentId === 'string') &&
+        typeof (item as LogosPageMeta).position === 'number'
+    ) as LogosPageMeta[]
+  } catch {
+    return []
+  }
+}
+
+export function setLogosPageTree(recollectionId: string, tree: LogosPageMeta[]): void {
+  localStorage.setItem(getLogosPageTreeKey(recollectionId), JSON.stringify(tree))
+}
+
+/** Per-page Logos content (for page/subpage hierarchy). */
+export function getLogosContentForPage(
+  recollectionId: string,
+  pageId: LogosPageId
+): StoredLogosContent | null {
+  try {
+    const raw = localStorage.getItem(getLogosPageContentKey(recollectionId, pageId))
+    if (!raw) return null
+    const data = JSON.parse(raw) as unknown
+    if (!Array.isArray(data)) return null
+    if (!data.every((item) => item != null && typeof item === 'object')) return null
+    return data as StoredLogosContent
+  } catch {
+    return null
+  }
+}
+
+export function setLogosContentForPage(
+  recollectionId: string,
+  pageId: LogosPageId,
+  content: StoredLogosContent
+): void {
+  localStorage.setItem(getLogosPageContentKey(recollectionId, pageId), JSON.stringify(content))
+}
+
+/** Remove stored content for a single page (e.g. when deleting that page). */
+export function removeLogosPageContent(recollectionId: string, pageId: LogosPageId): void {
+  localStorage.removeItem(getLogosPageContentKey(recollectionId, pageId))
+}
+
+// ---------------------------------------------------------------------------
+// Render Output Cache
+// ---------------------------------------------------------------------------
+
+/** Render output cache: one entry per rendering node (keyed by nodeId). Used by Logos "Insert from Flux" block. */
+export function getRenderOutputCache(recollectionId: string): RenderOutputCacheEntry[] {
+  try {
+    const raw = localStorage.getItem(getRenderCacheKey(recollectionId))
+    if (!raw) return []
+    const data = JSON.parse(raw) as unknown
+    if (!Array.isArray(data)) return []
+    return data.filter(
+      (item): item is RenderOutputCacheEntry =>
+        item != null &&
+        typeof item === 'object' &&
+        typeof (item as RenderOutputCacheEntry).nodeId === 'string' &&
+        typeof (item as RenderOutputCacheEntry).label === 'string' &&
+        ((item as RenderOutputCacheEntry).type === 'image' || (item as RenderOutputCacheEntry).type === 'html') &&
+        typeof (item as RenderOutputCacheEntry).content === 'string'
+    ) as RenderOutputCacheEntry[]
+  } catch {
+    return []
+  }
+}
+
+export function upsertRenderOutputEntry(recollectionId: string, entry: RenderOutputCacheEntry): void {
+  const entries = getRenderOutputCache(recollectionId)
+  const byNodeId = new Map(entries.map((e) => [e.nodeId, e]))
+  byNodeId.set(entry.nodeId, entry)
+  localStorage.setItem(
+    getRenderCacheKey(recollectionId),
+    JSON.stringify(Array.from(byNodeId.values()))
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Remove Recollection Data
+// ---------------------------------------------------------------------------
+
+/** Removes both graph, logos (legacy + page tree + all per-page content), and render cache for the recollection. */
+export function removeRecollectionData(recollectionId: string): void {
+  localStorage.removeItem(getGraphKey(recollectionId))
+  localStorage.removeItem(getLogosKey(recollectionId))
+  const tree = getLogosPageTree(recollectionId)
+  for (const page of tree) {
+    removeLogosPageContent(recollectionId, page.id)
+  }
+  localStorage.removeItem(getLogosPageTreeKey(recollectionId))
+  localStorage.removeItem(getRenderCacheKey(recollectionId))
+}

frontend/src/components/editor/CodeEditor.tsx

@@ -92,7 +92,7 @@ export function CodeEditor({
   }, [value, textareaId])
 
   return (
-    <div ref={containerRef} className="code-editor" style={{ minHeight: 0 }}>
+    <div ref={containerRef} className="code-editor min-h-0 h-full overflow-auto" style={{ minHeight: 0 }}>
       <Editor
         value={value}
         onValueChange={handleValueChange}

frontend/src/components/graph/BaseNode.tsx

@@ -75,11 +75,14 @@ export function BaseNode({
       data-selected={selected}
       data-path-role={connectionPathRole ?? undefined}
       style={appliedStyle}
-      tabIndex={0}
+      tabIndex={selected ? 0 : -1}
       {...props}
     >
       <div
-        className="min-h-0 flex-1 flex flex-col overflow-hidden"
+        className={cn(
+          "min-h-0 flex-1 flex flex-col overflow-hidden",
+          !selected && "pointer-events-none",
+        )}
         style={{ contain: "layout" }}
       >
         {children}
@@ -96,7 +99,9 @@ export function BaseNode({
           handleClassName="base-node-resize-handle nodrag nopan"
         />
       )}
-      {!isFullscreenInstance && handles}
+      {!isFullscreenInstance && (
+        <div className={cn(!selected && "pointer-events-none")}>{handles}</div>
+      )}
     </div>
   );
 }
@@ -198,7 +203,7 @@ export function BaseNodeContent({
   return (
     <div
       data-slot="base-node-content"
-      className={cn("min-h-0 flex-1 flex flex-col overflow-auto", className)}
+      className={cn("min-h-0 flex-1 flex flex-col", className)}
       {...props}
     />
   );

frontend/src/components/nodes/agent/descriptor.tsx

@@ -13,7 +13,7 @@ export function getAgentNodeDescriptor(): NodeTypeDescriptor {
     .idPrefix('agt_')
     .withInputOutput(true, true)
     .classification('archon')
-    .allowedSourceTypes(['config', 'variable', 'data'])
+    .allowedSourceTypes(['config', 'variable', 'data', 'render'])
     .allowedTargetTypes(['render'])
     .help(NODE_HELP.agent)
     .menu('Agent', <Bot className={ICON_CLASS} />)

frontend/src/components/nodes/config/ConfigNode.tsx

@@ -25,7 +25,7 @@ import {
     BaseNodeFooter,
     BaseNodeHeaderRow,
 } from '@/components/graph/BaseNode'
-import { Code2, Database, ScrollText, Variable } from 'lucide-react'
+import { Code2, Database, ScrollText, Sparkles, Variable } from 'lucide-react'
 import {
     MenubarItem,
     MenubarSeparator,
@@ -34,6 +34,7 @@ import {
     MenubarSubContent,
     MenubarSubTrigger,
 } from '@/components/ui/menubar'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
 import { Kbd } from '@/components/ui/kbd'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
 import { InputHandle, OutputHandle } from '@/components/graph/NodeHandles'
@@ -78,7 +79,16 @@ function ConfigNodeComponent({ id, data, width, height, selected }: Props) {
         () => getConnectedNodesByType(nodes, sourceIds, 'data'),
         [nodes, sourceIds]
     )
-    const hasDependencies = connectedConfigNodes.length > 0 || connectedVariableNodes.length > 0 || connectedFunctionNodes.length > 0 || connectedDataNodes.length > 0
+    const connectedRenderNodes = useMemo(
+        () => getConnectedNodesByType(nodes, sourceIds, 'render'),
+        [nodes, sourceIds]
+    )
+    const hasDependencies =
+        connectedConfigNodes.length > 0 ||
+        connectedVariableNodes.length > 0 ||
+        connectedFunctionNodes.length > 0 ||
+        connectedDataNodes.length > 0 ||
+        connectedRenderNodes.length > 0
 
     const setConfigType = useCallback(
         (newTypeId: ConfigTypeId) => {
@@ -133,6 +143,18 @@ function ConfigNodeComponent({ id, data, width, height, selected }: Props) {
         [insertAt]
     )
 
+    const insertRenderReference = useCallback(
+        (sourceNode: any, mode: 'prepend' | 'append' | 'cursor') => {
+            const isMarkdownImage =
+                configTypeId === 'markdown' && (sourceNode.data?.outputMode ?? 'image') === 'image'
+            const snippet = isMarkdownImage
+                ? `![Rendered]({{ ${sourceNode.id} }})`
+                : `{{ ${sourceNode.id} }}`
+            insertAt(snippet, mode)
+        },
+        [insertAt, configTypeId]
+    )
+
     const variableIds = useMemo(() => connectedVariableNodes.map((n: any) => n.id), [connectedVariableNodes])
     const functionIds = useMemo(() => connectedFunctionNodes.map((n: any) => n.id), [connectedFunctionNodes])
     const configTitles = useMemo(
@@ -296,6 +318,40 @@ function ConfigNodeComponent({ id, data, width, height, selected }: Props) {
                                             <MenubarShortcut className="opacity-0 group-hover:opacity-100 transition-opacity"><Kbd>Insert</Kbd></MenubarShortcut>
                                         </MenubarItem>
                                     ))}
+                                    {connectedRenderNodes.map((n: any) => {
+                                        const renderInputDisabled =
+                                            configTypeId === 'plantuml' || configTypeId === 'wireframe'
+                                        const item = (
+                                            <MenubarItem
+                                                key={n.id}
+                                                className="text-xs flex items-center gap-2 group"
+                                                disabled={renderInputDisabled}
+                                                onClick={() =>
+                                                    !renderInputDisabled && insertRenderReference(n, 'cursor')
+                                                }
+                                            >
+                                                <Sparkles className="size-3.5 shrink-0" />
+                                                {n.id}
+                                                <MenubarShortcut className="opacity-0 group-hover:opacity-100 transition-opacity">
+                                                    <Kbd>Insert</Kbd>
+                                                </MenubarShortcut>
+                                            </MenubarItem>
+                                        )
+                                        return renderInputDisabled ? (
+                                            <TooltipProvider key={n.id} delayDuration={300}>
+                                                <Tooltip>
+                                                    <TooltipTrigger asChild>{item}</TooltipTrigger>
+                                                    <TooltipContent side="right">
+                                                        Rendering output is not available for Diagram and
+                                                        Wireframe configs. Use a Markdown config to embed
+                                                        render output.
+                                                    </TooltipContent>
+                                                </Tooltip>
+                                            </TooltipProvider>
+                                        ) : (
+                                            item
+                                        )
+                                    })}
                                 </>
                             ) : (
                                 <span className="text-xs text-muted-foreground px-2 py-1">Connect nodes to insert references</span>
@@ -307,7 +363,7 @@ function ConfigNodeComponent({ id, data, width, height, selected }: Props) {
                     />
                 </div>
 
-                <div ref={editorContainerRef as React.RefObject<HTMLDivElement>} className="min-h-0 flex-1 w-full nodrag nopan overflow-auto border-t border-input" style={{ minHeight: editorHeight }}>
+                <div ref={editorContainerRef as React.RefObject<HTMLDivElement>} className="min-h-0 flex-1 w-full nodrag nopan overflow-hidden border-t border-input" style={{ minHeight: editorHeight }}>
                     <CodeEditor
                         textareaId={editorId}
                         value={content}

frontend/src/components/nodes/config/descriptor.tsx

@@ -68,7 +68,7 @@ export function getConfigNodeDescriptor(): NodeTypeDescriptor {
     .idPrefix('cfg_')
     .withInputOutput(true, true)
     .classification('psyche')
-    .allowedSourceTypes(['config', 'variable', 'function', 'data'])
+    .allowedSourceTypes(['config', 'variable', 'function', 'data', 'render'])
     .allowedTargetTypes(['config', 'render', 'agent'])
     .help(NODE_HELP.config)
     .menu('Config', <ScrollText className={ICON_CLASS} />)

frontend/src/components/nodes/config/renderingLogic.ts

@@ -9,6 +9,13 @@ import type { ResolvedContentResult, SourceRenderingLogicContext } from '@/lib/g
 import { getConfigContent, getConfigType, getConfigTypeId, type ConfigTypeId } from '@/lib/graph/rendering'
 import { isReachable, resolveExtendsRef, getTemplateRefs, type NodeLike } from '@/lib/graph/templateRefs'
 
+// Module-level cache for resolved Nunjucks output.
+// Keyed by a fingerprint of all inputs (template contents + variable/data values + function bodies).
+// Avoids re-running the Nunjucks environment when the same inputs are seen again (e.g. undo/redo,
+// multiple rendering nodes sharing the same config, rapid edits cycling back to a prior value).
+const MAX_RESOLVE_CACHE = 200
+const resolveCache = new Map<string, ResolvedContentResult>()
+
 export async function getResolvedContentForConfig(context: SourceRenderingLogicContext): Promise<ResolvedContentResult> {
   const { nodes, edges, sourceNodeId, renderNodeId } = context
   const srcId = sourceNodeId
@@ -74,6 +81,10 @@ export async function getResolvedContentForConfig(context: SourceRenderingLogicC
       })
       nunjucksContext[src.id] = filteredRows
     }
+    if (src?.type === 'render') {
+      nunjucksContext[src.id] =
+        ((src.data as Record<string, unknown>)?.cachedOutputValue as string | undefined) ?? ''
+    }
   }
 
   const functionIdsToRegister = new Set<string>()
@@ -103,6 +114,24 @@ export async function getResolvedContentForConfig(context: SourceRenderingLogicC
     }
   }
 
+  // Build cache key from all inputs that affect the resolved output.
+  const allTemplateContents = [...configIdsUsed]
+    .map((cid) => {
+      const node = nodes.find((n) => n.id === cid)
+      return getConfigContent((node?.data ?? undefined) as Record<string, unknown> | undefined)
+    })
+    .join('\x00')
+  const allFunctionBodies = [...functionIdsToRegister]
+    .map((fid) => {
+      const node = nodes.find((n) => n.id === fid)
+      return ((node?.data as Record<string, unknown>)?.body as string) ?? ''
+    })
+    .join('\x00')
+  const cacheKey = `${srcId}\x01${JSON.stringify(nunjucksContext)}\x01${allTemplateContents}\x01${allFunctionBodies}`
+
+  const cached = resolveCache.get(cacheKey)
+  if (cached) return cached
+
   const env = new nunjucks.Environment([configLoader], { autoescape: false })
 
   const formatFilterResult = (r: unknown): string => {
@@ -244,7 +273,13 @@ export async function getResolvedContentForConfig(context: SourceRenderingLogicC
         return
       }
       const resolved = afterNunjucks.replace(/(\r?\n)(\s*\r?\n)+/g, '$1').trim()
-      resolve({ resolved, outputTypeId })
+      const result: ResolvedContentResult = { resolved, outputTypeId }
+      // FIFO eviction when cache is full
+      if (resolveCache.size >= MAX_RESOLVE_CACHE) {
+        resolveCache.delete(resolveCache.keys().next().value as string)
+      }
+      resolveCache.set(cacheKey, result)
+      resolve(result)
     })
   })
 }

frontend/src/components/nodes/render/RenderingNode.tsx

@@ -23,7 +23,7 @@ import {
     MenubarSubTrigger,
 } from '@/components/ui/menubar'
 import { Sparkles, Play, ChevronDown, Loader2, RotateCw } from 'lucide-react'
-import { InputHandle } from '@/components/graph/NodeHandles'
+import { InputHandle, OutputHandle } from '@/components/graph/NodeHandles'
 import { Button } from '@/components/ui/button'
 import { ButtonGroup } from '@/components/ui/button-group'
 import {
@@ -50,16 +50,14 @@ export type { RenderingNodeData }
 
 type Props = AbstractNodeProps<RenderingNodeData>
 
-type ViewMode = 'preview' | 'raw'
-
 function RenderingNodeComponent({ id, data, width, height, selected }: Props) {
     const flowUIContext = useContext(FlowUIContext)
     const setFullscreenNodeId = flowUIContext?.setFullscreenNodeId
     const supportsFullscreen = getNodeType('render')?.supportsFullscreen
 
     const state = useRenderingNodeState(id, data)
+    const outputMode = state.outputMode
 
-    const [viewMode, setViewMode] = useState<ViewMode>('preview')
     const [viewportFocused, setViewportFocused] = useState(false)
 
     const dimensions =
@@ -68,7 +66,7 @@ function RenderingNodeComponent({ id, data, width, height, selected }: Props) {
             : undefined
 
     const { theme } = useTheme()
-    const [rawEditorHeight, rawEditorContainerRef] = useResizeHeight(180, [viewMode])
+    const [rawEditorHeight, rawEditorContainerRef] = useResizeHeight(180, [outputMode])
 
     const showEmpty =
         state.incomingIds.length === 0 &&
@@ -151,7 +149,12 @@ function RenderingNodeComponent({ id, data, width, height, selected }: Props) {
                 resizable
                 nodeId={id}
                 selected={selected}
-                handles={<InputHandle id="ain" nodeId={id} />}
+                handles={
+                    <>
+                        <InputHandle id="ain" nodeId={id} />
+                        <OutputHandle id="out" />
+                    </>
+                }
             >
                 <BaseNodeHeaderRow
                     icon={<Sparkles className="size-4" />}
@@ -264,17 +267,17 @@ function RenderingNodeComponent({ id, data, width, height, selected }: Props) {
                                 <>
                                     <MenubarCheckboxItem
                                         className="text-xs"
-                                        checked={viewMode === 'preview'}
-                                        onCheckedChange={(checked) => checked && setViewMode('preview')}
+                                        checked={outputMode === 'image'}
+                                        onCheckedChange={(checked) => checked && state.setOutputMode('image')}
                                     >
-                                        Preview
+                                        Image
                                     </MenubarCheckboxItem>
                                     <MenubarCheckboxItem
                                         className="text-xs"
-                                        checked={viewMode === 'raw'}
-                                        onCheckedChange={(checked) => checked && setViewMode('raw')}
+                                        checked={outputMode === 'string'}
+                                        onCheckedChange={(checked) => checked && state.setOutputMode('string')}
                                     >
-                                        Raw
+                                        String
                                     </MenubarCheckboxItem>
                                     {getNodeType(state.sourceNodeType ?? '')?.getOutputMenuContent?.(state.rawLanguage, { state, nodeId: id })}
                                 </>
@@ -306,7 +309,7 @@ function RenderingNodeComponent({ id, data, width, height, selected }: Props) {
                             </Empty>
                         ) : state.error ? (
                             errorUi
-                        ) : viewMode === 'raw' ? (
+                        ) : outputMode === 'string' ? (
                             <RawOutputView
                                 state={state}
                                 height={rawEditorHeight}
@@ -321,12 +324,12 @@ function RenderingNodeComponent({ id, data, width, height, selected }: Props) {
 
                 <BaseNodeFooter>
                     <NodeFooterEdgeIndicators nodeId={id} nodeType="render">
-                        {viewMode === 'raw'
+                        {outputMode === 'string'
                             ? state.rawDisplayContent
-                                ? `Raw · ${state.rawDisplayContent.length} chars`
+                                ? `String · ${state.rawDisplayContent.length} chars`
                                 : '—'
                             : state.renderedContent
-                              ? `${state.outputLabel} · ${state.renderedContent.length} chars`
+                              ? `Image · ${state.renderedContent.length} chars`
                               : state.error
                                 ? 'Error'
                                 : '—'}

frontend/src/components/nodes/render/descriptor.tsx

@@ -15,9 +15,10 @@ export function getRenderNodeDescriptor(): NodeTypeDescriptor {
     { viewportWidth: 1200, viewportHeight: 800 }
   )
     .idPrefix('rnd_')
-    .withInputOutput(true, false)
+    .withInputOutput(true, true)
     .classification('pneuma')
     .allowedSourceTypes(['config', 'agent'])
+    .allowedTargetTypes(['config', 'agent'])
     .help(NODE_HELP.render)
     .menu('Renderer', <Sparkles className={ICON_CLASS} />)
     .connectionLabelByStatus({ default: 'listening', updating: 'giving life', paused: 'pending', error: 'corrupted' })

frontend/src/components/nodes/render/useRenderingNodeState.ts

@@ -2,13 +2,66 @@
  * runs the resolve → render pipeline, manages streaming/cache,
  * and exposes derived state for the dumb UI. See lib/graph/rendering.ts for the
  * pipeline interface.
+ * 
+ * ## Auto vs Manual Mode Decision Tree
+ * 
+ * The hook supports two update modes: 'auto' and 'manual'. The mode is determined by:
+ * 
+ * 1. **Node data override**: Check `data?.updateMode` first
+ * 2. **Source logic default**: Fall back to `sourceLogic?.defaultUpdateMode`
+ * 3. **Hardcoded default**: Default to 'auto' if neither is set
+ * 
+ * ### Auto Mode Behavior
+ * - Runs automatically when upstream data changes (sourceSignature changes)
+ * - Debounces runs by 250ms to avoid excessive computation
+ * - Skips runs when node becomes visible with cache (visibility grace period: 400ms)
+ * - Updates path trigger on each run
+ * 
+ * ### Manual Mode Behavior
+ * - Only runs when `runTrigger` increments (user clicks "Run")
+ * - Requires explicit user action to update output
+ * - Caches last run signature to prevent re-runs on unrelated changes
+ * 
+ * ## Effect Dependencies
+ * 
+ * The main effect depends on:
+ * - `id`: Node ID (re-run when node changes)
+ * - `srcId`: Source node ID (re-run when connection changes)
+ * - `srcNode?.type`: Source node type (re-run when source type changes)
+ * - `effectiveUpdateMode`: Auto vs manual mode
+ * - `runTrigger`: Run trigger counter (for manual mode)
+ * - `sourceSignature`: Combined signature of all upstream nodes
+ * - `viewportWidth/Height`: Viewport dimensions (affects rendering)
+ * - `retryCount`: Retry counter (for error recovery)
+ * - `incomingIds.length`: Number of incoming connections
+ * 
+ * ## Rendering Pipeline
+ * 
+ * 1. **Resolve**: Source node (config/agent) produces resolved content
+ * 2. **Render**: Output type renderer (plantuml/markdown/wireframe) produces HTML/SVG
+ * 3. **Cache**: Results are cached in node data for persistence
+ * 4. **Display**: UI consumes the rendered content
+ * 
+ * ## Streaming Support
+ * 
+ * When the source node supports streaming (e.g., agent nodes):
+ * - `onStreamingStart`: Called when streaming begins
+ * - `onStreamingChunk`: Called for each chunk of markdown content
+ * - Streaming content is parsed with marked.js for preview
+ * 
+ * ## Error Handling
+ * 
+ * Errors during resolve or render are caught and stored in the `error` state.
+ * The error includes a `kind` (e.g., 'render', 'no-content') and `message`.
  */
 
 import { useCallback, useDeferredValue, useEffect, useMemo, useRef, useState } from 'react'
+import { useShallow } from 'zustand/react/shallow'
 import { useAbstractNode } from '@/lib/graph/abstractNode'
 import { useSyncConnectionStatus } from '@/lib/graph/nodeLifecycle'
 import { useCanvasStore, dispatchCanvasCommand } from '@/app/canvas/canvasStore'
 import { usePlatform } from '@/app/kosmos/KosmosContext'
+import { useOptionalRecollectionActions } from '@/app/recollections/layout/RecollectionActionsContext'
 import { getDefaultDataForType, getNextNodeId } from '@/lib/graph/flowUtils'
 import { getDefaultStyle } from '@/lib/graph/nodeRegistry'
 import {
@@ -24,20 +77,28 @@ import { buildSourceSignatures, type NodeLike, type EdgeLike } from '@/lib/graph
 import { getNodeDisplayStatus, type NodeDisplayStatus } from '@/lib/graph/state'
 import type { ConfigTypeId, SourceRenderingLogicContext } from '@/lib/graph/rendering'
 
+export type OutputMode = 'image' | 'string'
+
 export type RenderingNodeData = {
     viewportWidth?: number
     viewportHeight?: number
     updateMode?: 'auto' | 'manual'
     runTrigger?: number
     lastRunSourceSignature?: string
+    /** Controls which view is shown and what the node emits to downstream (Image = markdown embed, String = resolved text). */
+    outputMode?: OutputMode
     cachedRenderedContent?: string
     cachedResolvedContent?: string
     cachedReasoningContent?: string
+    /** Value exposed to config/agent when they reference this node (e.g. {{ renderId }}). Set on pipeline completion. */
+    cachedOutputValue?: string
 }
 
 const DEFAULT_VIEWPORT_WIDTH = 1200
 const DEFAULT_VIEWPORT_HEIGHT = 800
 const RENDER_DEBOUNCE_MS = 250
+/** Skip auto-run when we have cache and effect runs soon after mount (node became visible). */
+const VISIBILITY_GRACE_MS = 400
 
 /** Lifecycle state to pass to useSyncConnectionStatus so edge status (updating/error) stays in sync. */
 export type RenderingNodeLifecycle = {
@@ -94,6 +155,10 @@ export type RenderingNodeState = {
 
     /** Source node type id (e.g. 'config', 'agent') for Output menu from descriptor. */
     sourceNodeType: string | null
+
+    /** Output mode (Image vs String); controls view and emitted cachedOutputValue. */
+    outputMode: OutputMode
+    setOutputMode: (mode: OutputMode) => void
 }
 
 export function useRenderingNodeState(
@@ -111,8 +176,11 @@ export function useRenderingNodeState(
 
     // Subscribe to store graph so we re-render when any node/edge changes (e.g. ascendant data).
     // Context only exposes a ref, so we wouldn't re-render when another node updates otherwise.
-    const storeNodes = useCanvasStore((s) => s.graph.nodes)
-    const storeEdges = useCanvasStore((s) => s.graph.edges)
+    // Single combined subscription (vs two separate) halves listener overhead; useShallow prevents
+    // re-renders when non-graph slices (ui/path) change.
+    const { storeNodes, storeEdges } = useCanvasStore(
+      useShallow((s) => ({ storeNodes: s.graph.nodes, storeEdges: s.graph.edges }))
+    )
     const nodes = storeNodes.length > 0 ? storeNodes : contextNodes
     const edges = storeEdges.length > 0 ? storeEdges : contextEdges
 
@@ -120,6 +188,9 @@ export function useRenderingNodeState(
     nodesEdgesRef.current = { nodes, edges }
 
     const { aiConnection } = usePlatform()
+    const recollectionActions = useOptionalRecollectionActions()
+    const recollectionActionsRef = useRef(recollectionActions)
+    recollectionActionsRef.current = recollectionActions
 
     const viewportWidth = data?.viewportWidth ?? DEFAULT_VIEWPORT_WIDTH
     const viewportHeight = data?.viewportHeight ?? DEFAULT_VIEWPORT_HEIGHT
@@ -138,6 +209,11 @@ export function useRenderingNodeState(
     )
     const effectiveUpdateMode = (data?.updateMode ?? sourceLogic?.defaultUpdateMode ?? 'auto') as 'auto' | 'manual'
     const runTrigger = data?.runTrigger ?? 0
+    const outputMode: OutputMode = (data?.outputMode ?? 'image') as OutputMode
+    const setOutputMode = useCallback(
+        (mode: OutputMode) => updateData({ outputMode: mode }),
+        [updateData]
+    )
     const isAgentSource = srcNode?.type === 'agent'
     const agentOutputMarkdown = isAgentSource
         ? ((srcNode?.data as { outputMarkdown?: string })?.outputMarkdown ?? '')
@@ -194,9 +270,13 @@ export function useRenderingNodeState(
     const minLoadingTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
     const lastManualRunTriggerRef = useRef(0)
     const manualRunTriggerSyncedRef = useRef(false)
+    /** In auto mode, skip running when we have cache and we're in the grace window after mount (node became visible). */
+    const mountTimeRef = useRef<number>(0)
 
     const updateDataRef = useRef(updateData)
     updateDataRef.current = updateData
+    const outputModeRef = useRef(outputMode)
+    outputModeRef.current = outputMode
     const setNodesRef = useRef(setNodes)
     setNodesRef.current = setNodes
     const aiConnectionRef = useRef(aiConnection)
@@ -214,6 +294,7 @@ export function useRenderingNodeState(
     useSyncConnectionStatus(id, lifecycle)
 
     useEffect(() => {
+        if (mountTimeRef.current === 0) mountTimeRef.current = Date.now()
         if (incomingIds.length === 0) {
             setRenderedContent(null)
             setResolvedContent(null)
@@ -258,6 +339,30 @@ export function useRenderingNodeState(
             lastManualRunTriggerRef.current = runTrigger
         }
 
+        // Auto mode: do not run when node just became visible (remount with cache). No pipeline run, no path/addTrigger.
+        if (effectiveUpdateMode === 'auto') {
+            const hasCache = Boolean(
+                (data?.cachedRenderedContent ?? data?.cachedResolvedContent) as string | undefined
+            )
+            const signatureUnchanged =
+                data?.lastRunSourceSignature != null && data.lastRunSourceSignature === sourceSignature
+            const withinVisibilityGrace =
+                mountTimeRef.current > 0 && Date.now() - mountTimeRef.current < VISIBILITY_GRACE_MS
+            if (hasCache && (signatureUnchanged || withinVisibilityGrace)) {
+                // Keep Logos cache in sync with node's cached output so the picker shows the latest when not re-running.
+                const cached = (data?.cachedRenderedContent as string | undefined) ?? ''
+                const isSvgContent = Boolean(cached.trim() && /<svg[\s>]/i.test(cached.trim()))
+                recollectionActionsRef.current?.upsertRenderOutputToLogos?.({
+                    nodeId: id,
+                    label: id,
+                    type: isSvgContent ? 'image' : 'html',
+                    content: cached,
+                    updatedAt: Date.now(),
+                })
+                return
+            }
+        }
+
         runIdRef.current += 1
         const thisRunId = runIdRef.current
         const signatureForThisRun = sourceSignature
@@ -277,6 +382,7 @@ export function useRenderingNodeState(
                 cachedRenderedContent: undefined,
                 cachedResolvedContent: undefined,
                 cachedReasoningContent: undefined,
+                cachedOutputValue: undefined,
             })
             try {
                 // Pipeline: 1) Resolve (source) → 2) Render (output type) → 3) Cache
@@ -307,10 +413,29 @@ export function useRenderingNodeState(
                 if (thisRunId !== runIdRef.current) return
                 setRenderedContent(htmlOrSvg)
                 setError(null)
+                // Use the rendering node's id as the label (same as the node name shown in Flux header).
+                // Infer image from SVG content so we never store 'html' for diagram output.
+                const isSvgContent = Boolean(htmlOrSvg?.trim() && /<svg[\s>]/i.test(htmlOrSvg.trim()))
+                const cacheType = typeRenderer.outputType === 'image' || isSvgContent ? 'image' : 'html'
+                recollectionActionsRef.current?.upsertRenderOutputToLogos?.({
+                    nodeId: id,
+                    label: id,
+                    type: cacheType,
+                    content: htmlOrSvg ?? '',
+                    updatedAt: Date.now(),
+                })
+                const mode = outputModeRef.current
+                const cachedOutputValue =
+                    mode === 'string'
+                        ? resolved
+                        : mode === 'image' && htmlOrSvg?.trim() && /<svg[\s>]/i.test(htmlOrSvg.trim())
+                          ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(htmlOrSvg)}`
+                          : ''
                 updateDataRef.current({
                     cachedRenderedContent: htmlOrSvg,
                     cachedResolvedContent: resolved,
                     cachedReasoningContent: reasoning ?? '',
+                    cachedOutputValue,
                     ...(isManualMode ? { lastRunSourceSignature: signatureForThisRun } : {}),
                 })
             } catch (err: unknown) {
@@ -363,6 +488,8 @@ export function useRenderingNodeState(
         }
     // Content updates only when connected-node data changes (sourceSignature) or explicit run/viewport.
     // React Flow updates (position, selection, context ref churn) do not trigger re-runs.
+    // recollectionActions is intentionally omitted: we use recollectionActionsRef so slot/context
+    // identity changes (e.g. after setFluxSlot) do not re-trigger this effect and cause an auto-run loop.
     }, [
         id,
         srcId,
@@ -529,5 +656,7 @@ export function useRenderingNodeState(
         emptyStateAction,
         sourceData,
         sourceNodeType,
+        outputMode,
+        setOutputMode,
     }
 }

frontend/src/components/ui/sidebar.tsx

@@ -758,6 +758,7 @@ export {
   SidebarMenuAction,
   SidebarMenuBadge,
   SidebarMenuButton,
+  sidebarMenuButtonVariants,
   SidebarMenuItem,
   SidebarMenuSkeleton,
   SidebarMenuSub,

frontend/src/hooks/useStreamingContent.ts

@@ -0,0 +1,86 @@
+/**
+ * Hook for parsing and streaming markdown content.
+ * Handles marked.js parsing with proper cleanup and cancellation.
+ */
+
+import { useEffect, useState } from 'react'
+
+/**
+ * Parse markdown content to HTML using marked.js.
+ * Returns parsed HTML string and handles cleanup on unmount.
+ * 
+ * @param markdown - The markdown string to parse
+ * @returns HTML string from parsed markdown
+ */
+export function useStreamingContent(markdown: string | null): {
+  html: string
+  loading: boolean
+} {
+  const [html, setHtml] = useState<string>('')
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    if (markdown === null) {
+      setHtml('')
+      return
+    }
+
+    let cancelled = false
+    setLoading(true)
+
+    // Lazy load marked.js to avoid bundling if not needed
+    import('marked')
+      .then(async ({ marked }) => {
+        if (cancelled) return
+
+        try {
+          const parsed =
+            typeof marked.parse === 'function'
+              ? await (marked.parse as (s: string) => Promise<string>)(markdown)
+              : (marked as (s: string) => string)(markdown)
+          const result = typeof parsed === 'string' ? parsed : String(parsed)
+          if (!cancelled) {
+            setHtml(result)
+            setLoading(false)
+          }
+        } catch (err) {
+          if (!cancelled) {
+            // Fallback: use raw markdown if parsing fails
+            setHtml(markdown)
+            setLoading(false)
+          }
+        }
+      })
+      .catch(() => {
+        if (!cancelled) {
+          // Fallback: use raw markdown if import fails
+          setHtml(markdown)
+          setLoading(false)
+        }
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [markdown])
+
+  return { html, loading }
+}
+
+/**
+ * Parse markdown content to HTML using marked.js (synchronous version).
+ * Use this when you need immediate parsing without React state.
+ * 
+ * @param markdown - The markdown string to parse
+ * @returns HTML string from parsed markdown, or raw markdown on error
+ */
+export function parseMarkdownToHtml(markdown: string): string {
+  try {
+    // Use dynamic import for marked.js
+    // Note: This is a helper for non-React contexts
+    // In React components, use useStreamingContent hook instead
+    return markdown // Placeholder - actual implementation requires async import
+  } catch {
+    return markdown
+  }
+}

frontend/src/hooks/useThinkSections.ts

@@ -0,0 +1,30 @@
+/**
+ * Hook for parsing markdown content with think sections.
+ * Extracts <think>...</think> blocks and returns main content and reasoning separately.
+ */
+
+import { useMemo } from 'react'
+import { parseThinkSections } from '@/lib/graph/renderingUtils'
+
+/**
+ * Parse markdown content and extract think sections.
+ * Returns main content (without think blocks) and reasoning content (from think blocks).
+ * 
+ * @param content - The HTML/markdown content to parse
+ * @param outputType - The output type ('image' or 'string')
+ * @returns Object with main and think content
+ */
+export function useThinkSections(
+  content: string | null,
+  outputType: 'image' | 'string'
+): {
+  main: string
+  think: string
+} {
+  return useMemo(() => {
+    if (!content || outputType === 'image') {
+      return { main: '', think: '' }
+    }
+    return parseThinkSections(content)
+  }, [content, outputType])
+}

frontend/src/lib/errorBoundary.tsx

@@ -0,0 +1,169 @@
+/**
+ * Error boundary utilities for React components.
+ * Provides consistent error handling across the application.
+ */
+
+import React from 'react'
+
+/**
+ * Error state for error boundary components
+ */
+export type ErrorState = {
+    hasError: boolean
+    error: Error | null
+    errorInfo: React.ErrorInfo | null
+}
+
+/**
+ * Initial error state
+ */
+export const initialErrorState: ErrorState = {
+    hasError: false,
+    error: null,
+    errorInfo: null,
+}
+
+/**
+ * Error boundary props
+ */
+export type ErrorBoundaryProps = {
+    children: React.ReactNode
+    fallback?: React.ReactNode
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void
+}
+
+/**
+ * Error boundary state
+ */
+export type ErrorBoundaryState = ErrorState
+
+/**
+ * Error boundary component
+ * Catches JavaScript errors anywhere in the child component tree
+ * and displays a fallback UI instead of crashing
+ */
+export class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps) {
+        super(props)
+        this.state = initialErrorState
+    }
+
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+        return {
+            hasError: true,
+            error,
+            errorInfo: null,
+        }
+    }
+
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+        this.setState({
+            hasError: true,
+            error,
+            errorInfo,
+        })
+
+        // Log error to console or error reporting service
+        console.error('ErrorBoundary caught an error:', error, errorInfo)
+
+        // Call custom error handler if provided
+        if (this.props.onError) {
+            this.props.onError(error, errorInfo)
+        }
+    }
+
+    handleReset = (): void => {
+        this.setState(initialErrorState)
+    }
+
+    render(): React.ReactNode {
+        if (this.state.hasError) {
+            // You can render any custom fallback UI
+            if (this.props.fallback) {
+                return this.props.fallback
+            }
+            return (
+                <div className="error-boundary">
+                    <h1>Something went wrong.</h1>
+                    <details>
+                        <summary>Error Details</summary>
+                        <pre>{this.state.error?.toString()}</pre>
+                        <pre>{this.state.errorInfo?.componentStack}</pre>
+                    </details>
+                    <button onClick={this.handleReset}>Try Again</button>
+                </div>
+            )
+        }
+
+        return this.props.children
+    }
+}
+
+/**
+ * Hook for error handling in functional components
+ */
+export function useErrorHandler<T extends Error = Error>(): {
+    error: T | null
+    setError: (error: T | null) => void
+    hasError: boolean
+    resetError: () => void
+} {
+    const [error, setError] = React.useState<T | null>(null)
+
+    const hasError = error !== null
+    const resetError = React.useCallback(() => setError(null), [])
+
+    return { error, setError, hasError, resetError }
+}
+
+/**
+ * Utility to update error state consistently
+ */
+export function updateErrorState<T extends { error?: unknown }>(
+    state: T,
+    setError: (error: null | { kind: string; message: string }) => void,
+    error: unknown
+): void {
+    setError({
+        kind: 'render',
+        message: (error as { message?: string })?.message ?? 'Render error',
+    })
+}
+
+/**
+ * Utility to clear error state
+ */
+export function clearErrorState<T extends { error?: unknown }>(
+    state: T,
+    setError: (error: null) => void
+): void {
+    setError(null)
+}
+
+/**
+ * Utility to check if an error is recoverable
+ */
+export function isRecoverableError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  // Common recoverable errors
+  const recoverableMessages = [
+    'Network error',
+    'Timeout',
+    'Connection refused',
+    'Rate limit exceeded',
+  ]
+  return recoverableMessages.some((msg) => (error as Error).message.includes(msg))
+}
+
+/**
+ * Utility to format error message for display
+ */
+export function formatErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+        return error.message
+    }
+    if (typeof error === 'string') {
+        return error
+    }
+    return 'An unknown error occurred'
+}

frontend/src/lib/errorHandling.ts

@@ -0,0 +1,155 @@
+/**
+ * Error handling utilities for consistent error management.
+ * Provides centralized error handling logic across the application.
+ */
+
+/**
+ * Error kind for categorizing errors
+ */
+export type ErrorKind = 
+  | 'render'
+  | 'network'
+  | 'validation'
+  | 'authentication'
+  | 'authorization'
+  | 'notFound'
+  | 'server'
+  | 'unknown'
+
+/**
+ * Error object with kind and message
+ */
+export type AppError = {
+  kind: ErrorKind
+  message: string
+  details?: Record<string, unknown>
+  timestamp: number
+}
+
+/**
+ * Create an error object with consistent structure
+ */
+export function createAppError(
+  kind: ErrorKind,
+  message: string,
+  details?: Record<string, unknown>
+): AppError {
+  return {
+    kind,
+    message,
+    details,
+    timestamp: Date.now(),
+  }
+}
+
+/**
+ * Extract error message from unknown error
+ */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+  if (typeof error === 'string') {
+    return error
+  }
+  if (typeof error === 'object' && error !== null && 'message' in error) {
+    return String(error.message)
+  }
+  return 'An unknown error occurred'
+}
+
+/**
+ * Extract error kind from error
+ */
+export function getErrorKind(error: unknown): ErrorKind {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase()
+    if (message.includes('network')) return 'network'
+    if (message.includes('validation') || message.includes('invalid')) return 'validation'
+    if (message.includes('auth')) return 'authentication'
+    if (message.includes('forbidden') || message.includes('unauthorized')) return 'authorization'
+    if (message.includes('not found') || message.includes('404')) return 'notFound'
+    if (message.includes('server') || message.includes('500')) return 'server'
+  }
+  return 'unknown'
+}
+
+/**
+ * Format error for display
+ */
+export function formatError(error: AppError | Error | string): string {
+  if (typeof error === 'string') {
+    return error
+  }
+  if (error instanceof Error) {
+    return error.message
+  }
+  return error.message
+}
+
+/**
+ * Check if error is recoverable
+ */
+export function isRecoverableError(error: AppError | Error | string): boolean {
+  if (typeof error === 'string') return false
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase()
+    return ['network', 'timeout', 'connection'].some((term) => message.includes(term))
+  }
+  // error is AppError at this point
+  return ['network', 'server'].includes((error as AppError).kind)
+}
+
+/**
+ * Update error state consistently
+ */
+export function updateErrorState<T extends { error?: unknown }>(
+  state: T,
+  setError: (error: null | { kind: string; message: string }) => void,
+  error: unknown
+): void {
+  setError({
+    kind: 'render',
+    message: getErrorMessage(error),
+  })
+}
+
+/**
+ * Clear error state
+ */
+export function clearErrorState<T extends { error?: unknown }>(
+  state: T,
+  setError: (error: null) => void
+): void {
+  setError(null)
+}
+
+/**
+ * Handle error with consistent logging
+ */
+export function handleError(
+  error: unknown,
+  context?: Record<string, unknown>
+): AppError {
+  const appError = createAppError(
+    getErrorKind(error),
+    getErrorMessage(error),
+    context
+  )
+  
+  console.error('[Error]', appError, context)
+  return appError
+}
+
+/**
+ * Create error handler for async functions
+ */
+export function createErrorHandler<T>(
+  onError?: (error: AppError) => void
+): (error: unknown) => T {
+  return (error: unknown) => {
+    const appError = handleError(error)
+    onError?.(appError)
+    throw error
+  }
+}

frontend/src/lib/graph/configTypes.ts

@@ -53,6 +53,13 @@ export type ConfigType = {
 
 const KROKI_PLANTUML_SVG = '/api/kroki/plantuml/svg'
 const KROKI_TIMEOUT_MS = 15000
+const KROKI_CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+// In-flight deduplication: if the same PlantUML content is already being fetched,
+// reuse the existing promise instead of firing a duplicate request.
+const krokiInflight = new Map<string, Promise<string>>()
+// TTL result cache: avoids re-fetching identical content within the TTL window.
+const krokiCache = new Map<string, { result: string; cachedAt: number }>()
 
 const PLANTUML_INSERT_BLOCKS: InsertBlockOrGroup[] = [
   { label: 'Diagram start/end', snippet: '@startuml\n\n@enduml' },
@@ -172,36 +179,56 @@ const BUILTIN_CONFIG_TYPES: ConfigType[] = [
     language: 'plantuml',
     insertBlocks: PLANTUML_INSERT_BLOCKS,
     render: async (content: string) => {
-      const controller = new AbortController()
-      const timeoutId = setTimeout(() => controller.abort(), KROKI_TIMEOUT_MS)
-      try {
-        const res = await fetch(KROKI_PLANTUML_SVG, {
-          method: 'POST',
-          headers: { 'Content-Type': 'text/plain' },
-          body: content,
-          signal: controller.signal,
-        })
-        clearTimeout(timeoutId)
-        if (!res.ok) {
-          const err = await res.text()
-          if (res.status >= 500) {
-            throw new Error('Diagram service unavailable. Try again later.')
-          }
-          throw new Error(res.status === 400 ? err || 'Invalid PlantUML' : `Kroki error: ${res.status}`)
-        }
-        return res.text()
-      } catch (err: unknown) {
-        clearTimeout(timeoutId)
-        if (err instanceof Error) {
-          if (err.name === 'AbortError') {
-            throw new Error('Diagram request timed out. The service may be slow or unavailable.')
-          }
-          if (err.message.includes('fetch') || err.message.includes('network') || err.message.includes('Failed to fetch')) {
-            throw new Error('Diagram service unavailable. Check your connection or try again later.')
-          }
-        }
-        throw err
+      // 1. TTL cache hit
+      const cached = krokiCache.get(content)
+      if (cached && Date.now() - cached.cachedAt < KROKI_CACHE_TTL_MS) {
+        return cached.result
       }
+
+      // 2. In-flight deduplication: reuse an existing request for the same content
+      const inflight = krokiInflight.get(content)
+      if (inflight) return inflight
+
+      // 3. New request
+      const fetchPromise = (async () => {
+        const controller = new AbortController()
+        const timeoutId = setTimeout(() => controller.abort(), KROKI_TIMEOUT_MS)
+        try {
+          const res = await fetch(KROKI_PLANTUML_SVG, {
+            method: 'POST',
+            headers: { 'Content-Type': 'text/plain' },
+            body: content,
+            signal: controller.signal,
+          })
+          clearTimeout(timeoutId)
+          if (!res.ok) {
+            const err = await res.text()
+            if (res.status >= 500) {
+              throw new Error('Diagram service unavailable. Try again later.')
+            }
+            throw new Error(res.status === 400 ? err || 'Invalid PlantUML' : `Kroki error: ${res.status}`)
+          }
+          const svg = await res.text()
+          krokiCache.set(content, { result: svg, cachedAt: Date.now() })
+          return svg
+        } catch (err: unknown) {
+          clearTimeout(timeoutId)
+          if (err instanceof Error) {
+            if (err.name === 'AbortError') {
+              throw new Error('Diagram request timed out. The service may be slow or unavailable.')
+            }
+            if (err.message.includes('fetch') || err.message.includes('network') || err.message.includes('Failed to fetch')) {
+              throw new Error('Diagram service unavailable. Check your connection or try again later.')
+            }
+          }
+          throw err
+        } finally {
+          krokiInflight.delete(content)
+        }
+      })()
+
+      krokiInflight.set(content, fetchPromise)
+      return fetchPromise
     },
     outputMenuDescriptor: {
       submenuLabel: 'Export',

frontend/src/lib/graph/nodeFactory.ts

@@ -0,0 +1,182 @@
+/**
+ * Node factory utilities for creating and managing nodes.
+ * Centralizes node creation logic to reduce duplication.
+ */
+
+import type { Node, Edge } from '@xyflow/react'
+import type { AppNode, AppEdge } from '@/lib/graph/nodeTypes'
+import {
+  getDefaultDataForType,
+  getNextNodeId,
+} from '@/lib/graph/flowUtils'
+import { getRegisteredNodeTypeIds, getDefaultStyle } from '@/lib/graph/nodeRegistry'
+
+/**
+ * Create a new node with auto-generated ID and default data.
+ * 
+ * @param type - Node type ID (e.g., 'config', 'render')
+ * @param position - Node position { x, y }
+ * @param data - Optional additional data to merge with defaults
+ * @returns New node with generated ID
+ */
+export function createNode(
+  type: string,
+  position: { x: number; y: number },
+  data?: Record<string, unknown>
+): AppNode {
+  const existingIds = getRegisteredNodeTypeIds()
+  const newId = getNextNodeId(type, existingIds)
+  return {
+    id: newId,
+    type,
+    position,
+    data: { ...getDefaultDataForType(type, newId), ...(data ?? {}) },
+    style: getDefaultStyle(type),
+  }
+}
+
+/**
+ * Create a new node with a specific ID.
+ * Use this when you need to control the node ID (e.g., when duplicating).
+ * 
+ * @param type - Node type ID
+ * @param id - Node ID to use
+ * @param position - Node position { x, y }
+ * @param data - Optional additional data to merge with defaults
+ * @returns New node with specified ID
+ */
+export function createNodeWithId(
+  type: string,
+  id: string,
+  position: { x: number; y: number },
+  data?: Record<string, unknown>
+): AppNode {
+  return {
+    id,
+    type,
+    position,
+    data: { ...getDefaultDataForType(type, id), ...(data ?? {}) },
+    style: getDefaultStyle(type),
+  }
+}
+
+/**
+ * Create a new edge connecting two nodes.
+ * 
+ * @param source - Source node ID
+ * @param target - Target node ID
+ * @param id - Optional edge ID (auto-generated if not provided)
+ * @param data - Optional edge data
+ * @returns New edge
+ */
+export function createEdge(
+  source: string,
+  target: string,
+  id?: string,
+  data?: Record<string, unknown>
+): AppEdge {
+  return {
+    id: id ?? `e-${source}-${target}`,
+    source,
+    target,
+    data: data ?? {},
+  }
+}
+
+/**
+ * Create multiple nodes from a template.
+ * 
+ * @param template - Template node to copy
+ * @param count - Number of nodes to create
+ * @param offset - Position offset between nodes { x, y }
+ * @returns Array of new nodes
+ */
+export function createNodesFromTemplate(
+  template: Partial<AppNode>,
+  count: number,
+  offset: { x: number; y: number }
+): AppNode[] {
+  const nodes: AppNode[] = []
+  for (let i = 0; i < count; i++) {
+    const position = {
+      x: (template.position?.x ?? 0) + i * offset.x,
+      y: (template.position?.y ?? 0) + i * offset.y,
+    }
+    nodes.push({
+      id: template.id ?? getNextNodeId(template.type ?? 'node', nodes.map((n) => n.id)),
+      type: template.type ?? 'node',
+      position,
+      data: { ...template.data },
+      style: template.style ?? getDefaultStyle(template.type ?? 'node'),
+    })
+  }
+  return nodes
+}
+
+/**
+ * Get existing node IDs for a specific type.
+ * 
+ * @param nodes - Array of nodes to search
+ * @param type - Node type to filter by
+ * @returns Array of node IDs for the specified type
+ */
+export function getNodeIdsByType(nodes: AppNode[], type: string): string[] {
+  return nodes.filter((n) => n.type === type).map((n) => n.id)
+}
+
+/**
+ * Get the next available node ID for a type based on existing nodes.
+ * 
+ * @param type - Node type
+ * @param existingNodes - Array of existing nodes
+ * @returns Next available node ID
+ */
+export function getNextNodeIdForType(type: string, existingNodes: AppNode[]): string {
+  const existingIds = existingNodes.map((n) => n.id)
+  return getNextNodeId(type, existingIds)
+}
+
+/**
+ * Duplicate a node with a new ID and offset position.
+ * 
+ * @param node - Node to duplicate
+ * @param offset - Position offset for the duplicate
+ * @returns Duplicated node
+ */
+export function duplicateNode(node: AppNode, offset: { x: number; y: number } = { x: 30, y: 30 }): AppNode {
+  const existingIds = [node.id] // Start with current node ID
+  const newId = getNextNodeId(node.type ?? 'node', existingIds)
+  const pos = node.position ?? { x: 0, y: 0 }
+  return {
+    id: newId,
+    type: node.type ?? 'node',
+    position: { x: pos.x + offset.x, y: pos.y + offset.y },
+    data: typeof node.data === 'object' && node.data !== null ? { ...(node.data as object) } : node.data,
+    style: node.style ?? getDefaultStyle(node.type ?? 'node'),
+  }
+}
+
+/**
+ * Create a connection between two nodes.
+ * 
+ * @param sourceNodeId - Source node ID
+ * @param sourceHandle - Source handle ID (optional)
+ * @param targetNodeId - Target node ID
+ * @param targetHandle - Target handle ID (optional)
+ * @returns Edge object connecting the nodes
+ */
+export function createConnection(
+  sourceNodeId: string,
+  sourceHandle?: string,
+  targetNodeId: string = '',
+  targetHandle?: string
+): Edge {
+  const edge: Edge = {
+    id: `e-${sourceNodeId}-${targetNodeId}`,
+    source: sourceNodeId,
+    target: targetNodeId,
+    sourceHandle,
+    targetHandle,
+  }
+  return edge
+}

frontend/src/lib/iconMap.tsx

@@ -1,6 +1,6 @@
 /**
- * Map project icon ids to Lucide icons for the sidebar.
- * Only Lucide "Animals" category icons are allowed for projects.
+ * Map recollection icon ids to Lucide icons for the sidebar.
+ * Only Lucide "Animals" category icons are allowed for recollections.
  */
 
 import {
@@ -18,9 +18,9 @@ import {
   Turtle,
   type LucideIcon,
 } from 'lucide-react'
-import type { ProjectIconId } from '@/app/kosmos/types'
+import type { RecollectionIconId } from '@/app/kosmos/types'
 
-export const PROJECT_ICON_MAP: Record<ProjectIconId, LucideIcon> = {
+export const RECOLLECTION_ICON_MAP: Record<RecollectionIconId, LucideIcon> = {
   bird: Bird,
   bug: Bug,
   cat: Cat,
@@ -35,6 +35,6 @@ export const PROJECT_ICON_MAP: Record<ProjectIconId, LucideIcon> = {
   egg: Egg
 }
 
-export function getProjectIcon(iconId: string): LucideIcon {
-  return PROJECT_ICON_MAP[iconId as ProjectIconId] ?? Cat
+export function getRecollectionIcon(iconId: string): LucideIcon {
+  return RECOLLECTION_ICON_MAP[iconId as RecollectionIconId] ?? Cat
 }

frontend/src/lib/icons/README.md

@@ -0,0 +1,46 @@
+# Icon registry
+
+Custom SVG icons as React components. Icons use `fill="currentColor"` so they match text color in light/dark themes.
+
+**Usage:** `import { RecollectionsIcon } from '@/lib/icons'` then `<RecollectionsIcon className="size-4" />`.
+
+---
+
+## Adding a new custom icon
+
+You do **not** need a separate `.svg` file. Everything lives in the registry.
+
+### 1. Get path data from your SVG
+
+From the SVG you have:
+
+- **viewBox** – e.g. `"0 0 24 24"` from `<svg viewBox="...">`
+- **paths** – the `d` attribute of each `<path>`. One or more strings.
+
+Example: `<path d="M12 2L2 7v10l10 5 10-5V7L12 2z"/>` → use `'M12 2L2 7v10l10 5 10-5V7L12 2z'`.
+
+### 2. Edit `registry.tsx` only
+
+1. **Add an entry to `ICONS`** (same shape as `recollections`):
+
+   ```ts
+   myFeature: {
+     viewBox: '0 0 24 24',
+     paths: ['M12 2L2 7v10l10 5 10-5V7L12 2z'],
+   },
+   ```
+
+2. **Export a component** (one line):
+
+   ```ts
+   export const MyFeatureIcon = createIcon('myFeature')
+   ```
+
+### 3. Use it
+
+```tsx
+import { MyFeatureIcon } from '@/lib/icons'
+<MyFeatureIcon className="size-4" />
+```
+
+That’s it. No new files, no public SVG. All icons are defined in `registry.tsx`.

frontend/src/lib/icons/SvgIcon.tsx

@@ -0,0 +1,35 @@
+/**
+ * Base component for registry SVG icons. Renders an inline <svg> with one or more <path> elements.
+ * Use this when defining a new icon so all icons share the same props and behavior.
+ */
+
+import React from 'react'
+import type { IconProps } from './types'
+
+export type SvgIconData = {
+  viewBox: string
+  paths: string[]
+}
+
+type SvgIconProps = IconProps & {
+  viewBox: string
+  paths: string[]
+}
+
+export function SvgIcon({ viewBox, paths, className, title, fill = 'currentColor' }: SvgIconProps) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={viewBox}
+      fill={fill}
+      className={className}
+    aria-hidden={!title}
+    {...(title ? { 'aria-label': title } : {})}
+    >
+      {title && <title>{title}</title>}
+      {paths.map((d, i) => (
+        <path key={i} d={d} />
+      ))}
+    </svg>
+  )
+}

frontend/src/lib/icons/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Custom SVG icon registry. Import icons as components.
+ *
+ *   import { RecollectionsIcon } from '@/lib/icons'
+ *   <RecollectionsIcon className="size-4" />
+ *
+ * To add a new icon: edit registry.tsx (add to ICONS + export a createIcon('key') component).
+ * See README.md in this folder.
+ */
+
+export { SvgIcon } from './SvgIcon'
+export type { IconProps } from './types'
+export type { SvgIconData } from './SvgIcon'
+
+export { RecollectionsIcon, FluxIcon, LogosIcon } from './registry'

frontend/src/lib/icons/registry.tsx

@@ -0,0 +1,50 @@
+/**
+ * Custom SVG icon registry. All icons are defined here.
+ *
+ * To add a new icon:
+ * 1. Add a new entry to ICONS (viewBox + paths; paths = array of <path d="..."> values).
+ * 2. Export a component: export const MyIcon = createIcon('myIcon')
+ *
+ * Usage: import { RecollectionsIcon } from '@/lib/icons'
+ */
+
+import React from 'react'
+import { SvgIcon } from './SvgIcon'
+import type { IconProps } from './types'
+
+export type IconDefinition = {
+  viewBox: string
+  paths: string[]
+}
+
+const ICONS: Record<string, IconDefinition> = {
+  recollections: {
+    viewBox: '0 0 136.94762 136.94878',
+    paths: [
+      'm 66.371161,0.03390048 c -2.311523,0.07281 -4.641626,0.264753 -6.982424,0.578125 C 21.999631,5.6183495 -4.3606806,40.0826 0.59967533,77.47726 5.5599054,114.87286 39.993587,141.27485 77.394601,136.36007 114.85985,131.43673 141.3174,96.93037 136.34772,59.4714 131.68966,24.35368 101.04394,-1.0582045 66.371161,0.03390048 Z M 61.566472,3.2760895 c -0.0095,0.001 -0.01971,0.003 -0.0293,0.004 -0.0098,9.2e-4 -0.01964,9.9e-4 -0.0293,0.002 z m 9.699219,9.5449205 c 19.50377,0.55671 35.127149,11.15304 44.126949,26.2207 6.93841,11.61643 9.68597,25.81012 6.91406,40.09375 C 120.71152,73.34663 118.17437,68.0619 114.67585,63.45187 106.8245,53.10609 94.721751,46.13507 80.130921,42.52023 l -0.27148,-0.0684 -0.27734,-0.0352 c -28.151269,-3.7155 -55.054642,8.83634 -64.988286,36.95117 -0.02494,0.0706 -0.02478,0.14601 -0.04883,0.2168 C 11.655501,63.71409 15.42168,46.23136 25.22272,33.90491 l 0.01367,-0.0156 0.01367,-0.0176 C 34.377229,22.19422 47.860414,14.74021 62.603576,13.22132 l 0.03711,-0.004 0.03711,-0.004 c 2.936655,-0.34652 5.801645,-0.47211 8.587895,-0.39258 z m -1.29102,41.87109 c 12.95901,0.70222 25.06263,6.49265 32.783209,15.08008 7.28112,8.09864 10.79834,18.33767 8.07226,30 C 101.03587,90.14454 89.910281,84.99651 75.345771,82.73117 l -0.19531,-0.0312 -0.19922,-0.0156 c -20.733068,-1.55643 -35.022716,5.335 -48.671879,17.58594 -0.06457,-0.37677 -0.142507,-0.53509 -0.21289,-0.99805 l -0.002,-0.0215 -0.0039,-0.0215 c -1.539122,-9.56158 0.856493,-19.33174 6.644531,-27.0957 l 0.0059,-0.008 0.0059,-0.006 C 40.835342,61.14748 50.93512,56.87803 64.613388,54.7094 c 1.796703,-0.10041 3.587583,-0.11367 5.361323,-0.0176 z m 1.43946,40.8086 c 12.76679,0.43942 22.46301,6.41284 32.015619,15.60351 -8.516209,7.46779 -18.131509,11.6796 -29.921869,12.62305 l -0.0156,0.002 -0.0137,0.002 C 57.880343,125.06798 44.881286,121.11357 33.449284,111.37969 41.537216,101.9635 52.025551,97.38866 65.0528,95.70782 c 2.205241,-0.20547 4.323551,-0.27717 6.361331,-0.20703 z m 2.89648,38.19336 c 9.8e-4,-2.3e-4 0.003,1.6e-4 0.004,0 0,0 0.002,0 0.002,0 0.001,-1.1e-4 0.003,-1e-5 0.004,0 l -0.0117,0.002 z',
+    ],
+  },
+  flux: {
+    viewBox: '0 0 128.21893 138.56171',
+    paths: [
+      'M 65.374983,8.1088677e-4 60.701153,0.03011089 60.415993,4.6961249 c -0.55179,9.0557191 -2.83786,11.9493291 -6.79687,14.5195291 -3.95902,2.5702 -10.54806,4.20232 -18.3418,7.4082 -34.98520956,14.39284 -47.28717,62.07586 -21.55664,90.648436 0,0 0.002,0.002 0.002,0.002 0,0 0.002,0.002 0.002,0.002 10e-4,10e-4 9.6e-4,0.002 0.002,0.004 10.83353,12.16108 26.49706,20.323 43.10742,21.14844 1.82408,0.0913 3.65036,0.13596 5.47656,0.13281 h 0.0508 l 0.0488,-0.002 C 100.64938,137.72435 128.68569,105.7552 128.213,68.397434 128.00565,52.017994 121.01832,35.173324 109.838,22.170874 98.657673,9.1684149 82.994953,-0.10807511 65.375113,9.5388677e-4 Z M 72.351543,14.047684 c 3.97414,0.85717 7.73706,2.00996 8.76562,3.47266 l 0.0332,0.0488 0.0351,0.0469 c 6.89636,9.33072 6.88878,19.61502 2.61328,28.80664 -4.27549,9.19163 -13.07048,16.8718 -23.43164,19.5332 -19.35646,4.97273 -27.00478,5.36045 -43.54101,18.77539 l -0.27149,0.22071 -0.23828,0.25586 c -1.01013,1.08488 -1.80757,2.18133 -2.68164,3.27148 -0.86509,-4.20543 -1.08073,-8.40113 -0.47461,-13.26562 1.90196,-15.26728 13.08901,-31.08978 27.28125,-36.76563 6.67107,-2.66751 15.44131,-4.10549 23.06445,-10.32226 h 0.002 v -0.002 c 4.55186,-3.71381 7.379,-8.78935 8.84375,-14.07617 z m 26.69531,15.76172 c 3.560237,3.98608 6.818267,8.37635 8.771477,11.92773 l 0.006,0.0117 0.008,0.0117 c 7.49286,13.45031 9.35625,29.3145 5.18554,44.13672 -3.99106,14.176786 -13.477257,26.166346 -26.355467,33.312496 -13.35902,7.26239 -26.86378,8.03142 -41.45117,3.71289 -11.9737,-4.11608 -18.89818,-9.93158 -25.79883,-19.92578 5.60813,-9.268456 17.76283,-18.626576 27.17774,-20.341796 10.91193,-1.9874 22.02927,-5.01594 31.47461,-10.92578 9.44534,-5.90984 17.12434,-14.98149 20.23828,-27.86914 1.05706,-4.37454 1.23242,-9.22164 0.74414,-14.05078 z',
+    ],
+  },
+  logos: {
+    viewBox: '0 0 146.33972 145.15062',
+    paths: [
+      'M 73.027332,7.1405223e-8 69.925772,5.16211 c -5.52098,9.188434 -14.41144,26.253674 -19.48828,32.402344 0.0491,-0.0595 -2.98075,2.63874 -6.69531,5.3418 -3.71456,2.70305 -8.45619,5.96709 -13.31055,9.22265 -9.70871,6.51113 -20.01065,13.07222 -23.4648407,15.12305 L -8.724555e-6,71.388674 6.8222613,75.761714 c 9.0907907,5.82534 18.1443907,11.70934 27.1582007,17.65235 l 0.0156,0.01 0.0176,0.0117 c 4.00269,2.59317 8.36085,5.13445 11.86328,7.523436 0.23407,0.45064 0.38789,0.80708 0.73633,1.46094 0.71978,1.35064 1.66548,3.08636 2.76367,5.08594 2.19639,3.99914 5.00416,9.04144 7.78711,14.00195 2.78296,4.96051 5.53921,9.83667 7.63282,13.50195 1.0468,1.83264 1.92645,3.36087 2.57031,4.46094 0.32193,0.55003 0.58219,0.98887 0.79297,1.33398 0.10539,0.17256 0.19404,0.31506 0.30273,0.48047 0.0543,0.0827 0.10819,0.16699 0.2168,0.31446 0.1086,0.14746 -0.44724,0.078 1.28515,1.23437 l 3.47071,2.31641 3.78711,-3.91993 13.84961,-23.21679 c 0.91939,-1.54094 2.60442,-4.51911 4.34179,-7.35938 0.86869,-1.42013 1.74513,-2.79264 2.47266,-3.83593 0.58635,-0.84084 1.23011,-1.53521 1.26758,-1.61524 0,0 0.002,-0.002 0.002,-0.002 0,0 0,-0.002 0,-0.002 0,0 0,-0.002 0,-0.002 0,0 -0.002,0 -0.002,0 0,0 -0.002,0 -0.002,0 0,0 -0.002,0 -0.002,0 C 110.91313,95.490664 128.18052,86.436874 141.2792,76.263754 l 5.06054,-3.92969 -5.04296,-3.95312 c -9.38527,-7.35596 -20.29484,-13.54071 -29.4336,-19.82227 -2.33755,-1.60623 -5.3246,-3.37974 -8.0625,-5.19531 -2.73789,-1.81558 -5.222368,-3.83146 -5.923828,-4.70703 -0.44105,-0.55116 -2.07282,-3.15619 -3.80664,-6.27539 -1.7342,-3.11992 -3.75432,-6.92382 -5.76953,-10.69141 -2.01521,-3.76759 -4.02165,-7.49617 -5.78711,-10.55078 -1.76546,-3.05461 -2.58933,-5.01617 -4.98242,-7.140627 z M 74.419912,23.173824 c 1.17627,1.99532 2.38635,4.05673 3.68555,6.39649 1.02962,1.85427 1.28165,2.47838 2.24805,4.29297 -1.93131,-0.43835 -3.97357,-0.82076 -6.42578,-1.04297 l -0.48633,-0.0449 -0.48633,0.0508 c -1.65299,0.17332 -3.16247,0.42313 -4.60938,0.7207 2.03534,-3.47033 4.0086,-6.8998 6.07422,-10.37305 z m 0.084,22.8711 c 12.48904,0.43314 21.30922,9.51036 23.13672,22.39648 1.01116,7.46859 -0.96496,15.02931 -5.50196,21.04688 v 0.002 c -4.21095,5.59226 -8.86516,8.02542 -15.82031,9.11719 -8.31129,0.0281 -14.27689,-2.81072 -18.55664,-7.17188 -4.33772,-4.42023 -6.90239,-10.56445 -7.40625,-16.96289 -1.00248,-12.73032 5.43459,-25.61273 21.60352,-28.39844 0.86423,-0.0494 1.71231,-0.0582 2.54492,-0.0293 z m -35.95703,16.11719 c -1.30582,5.40995 -1.66749,11.01933 -0.61133,16.82031 0.0652,0.70615 0.22574,1.26763 0.35937,1.87109 -0.73651,-0.50535 -1.53019,-1.01175 -2.17187,-1.47265 -1.38484,-0.99469 -2.10979,-1.58445 -3.06446,-2.20508 l -0.0195,-0.0117 -0.8789,-0.56055 -0.0781,-0.0449 c -2.38147,-1.40078 -5.03264,-3.28099 -7.61328,-5.03906 1.79854,-1.25798 3.57872,-2.53921 5.39258,-3.77539 2.85143,-1.94332 5.79752,-3.70317 8.68555,-5.58203 z m 71.302728,0.62304 c 2.39205,1.59547 4.80964,3.252 7.11719,4.59375 2.03836,1.18513 4.75208,3.12784 7.25976,4.88672 -3.47791,2.39487 -7.00474,4.84452 -10.39257,7.03125 l -0.002,0.002 -0.002,0.002 c -1.52473,0.98648 -2.99987,1.93804 -4.50195,2.91992 1.66778,-6.01121 2.23579,-12.37241 0.52148,-19.43555 z M 66.058592,110.64257 c 4.81115,1.23001 9.49114,1.35292 13.97852,0.56836 -0.76396,1.32958 -1.60165,2.70012 -2.29492,3.93946 -1.46148,2.59299 -3.03458,5.16218 -4.57422,7.8125 -1.75297,-2.96478 -2.93487,-4.85528 -5.01758,-8.53321 -0.76423,-1.34958 -1.36576,-2.48098 -2.0918,-3.78711 z',
+    ],
+  },
+}
+
+function createIcon(key: keyof typeof ICONS) {
+  const { viewBox, paths } = ICONS[key]
+  return function IconComponent(props: IconProps) {
+    return <SvgIcon viewBox={viewBox} paths={paths} {...props} />
+  }
+}
+
+export const RecollectionsIcon = createIcon('recollections')
+export const FluxIcon = createIcon('flux')
+export const LogosIcon = createIcon('logos')

frontend/src/lib/icons/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared props for SVG icon components in the icon registry.
+ * All icons inherit text color via fill="currentColor" by default.
+ */
+
+export type IconProps = {
+  /** Optional class name (e.g. for size: "size-4", "w-5 h-5") */
+  className?: string
+  /** Optional title for accessibility; omit for decorative icons (use aria-hidden on parent) */
+  title?: string
+  /** Override fill; default is "currentColor" */
+  fill?: string
+}

frontend/src/lib/svgUtils.ts

@@ -0,0 +1,48 @@
+/**
+ * SVG detection utilities.
+ * Centralized logic for detecting and processing SVG content.
+ */
+
+/** Check if a string contains SVG content. */
+export function isSvgContent(content: string | null | undefined): boolean {
+  return Boolean(content?.trim() && /<svg[\s>]/i.test(content.trim()))
+}
+
+/** Check if a file path or URL points to an SVG file. */
+export function isSvgPath(path: string | null | undefined): boolean {
+  return Boolean(path?.toLowerCase().endsWith('.svg'))
+}
+
+/** Process SVG HTML for viewport display (aspect ratio, fill container). */
+export function processSvgDisplay(html: string): string {
+  let out = html
+  // Change preserveAspectRatio from 'none' to 'xMidYMid meet' for proper scaling
+  out = out.replace(/\bpreserveAspectRatio\s*=\s*["']none["']/gi, 'preserveAspectRatio="xMidYMid meet"')
+  // Set width to 100% to fill container
+  out = out.replace(/\bwidth\s*=\s*["'][^"']*["']/i, 'width="100%"')
+  // Set height to 100% to fill container
+  out = out.replace(/\bheight\s*=\s*["'][^"']*["']/i, 'height="100%"')
+  // Override width/height in style attributes
+  out = out.replace(/\bstyle\s*=\s*["']([^"']*)["']/i, (_, style) => {
+    const overridden = style.replace(/\b(width|height):[^;]+/gi, '$1:100%')
+    return `style="${overridden}"`
+  })
+  return out
+}
+
+/** Extract SVG content from an HTML string. */
+export function extractSvgContent(html: string): string | null {
+  const svgMatch = html.match(/<svg[\s\S]*?<\/svg>/i)
+  return svgMatch ? svgMatch[0] : null
+}
+
+/** Check if content is an SVG data URL. */
+export function isSvgDataUrl(content: string | null | undefined): boolean {
+  return Boolean(content?.trim().startsWith('data:image/svg+xml'))
+}
+
+/** Convert SVG string to data URL. */
+export function svgToDataUrl(svg: string): string {
+  const encoded = btoa(unescape(encodeURIComponent(svg)))
+  return `data:image/svg+xml;base64,${encoded}`
+}

frontend/src/main.tsx

@@ -1,19 +1,25 @@
-import React from 'react'
+import React, { lazy, Suspense } from 'react'
 import { createRoot } from 'react-dom/client'
 import { BrowserRouter, Navigate, Route, Routes } from 'react-router-dom'
 import { Toaster } from 'sonner'
 import { ThemeProvider } from './lib/themeContext'
 import { registerBuiltinNodes } from './lib/graph/registerBuiltinNodes'
 import { registerBuiltinConfigTypes } from './lib/graph/configTypes'
-import { KosmosPage } from './app/kosmos/KosmosPage'
-import { ProjectsPage } from './app/pleroma/PleromaPage'
-import { KeromaPage } from './app/keroma/KeromaPage'
-import { CanvasRoute } from './app/canvas/CanvasRoute'
+import { RecollectionLayout } from './app/recollections/RecollectionLayout'
+import { NotFoundPage } from './app/NotFoundPage'
+
 import './lib/prismSetup'
 import 'prismjs/themes/prism.css'
 import './styles.css'
 import '@xyflow/react/dist/style.css'
 
+// Lazy-load heavy route components so their bundles are fetched on first navigation,
+// not at initial app load. RecollectionLayout and NotFoundPage stay eager (lightweight).
+const KosmosPage        = lazy(() => import('./app/kosmos/KosmosPage').then(m => ({ default: m.KosmosPage })))
+const RecollectionsPage = lazy(() => import('./app/recollections/RecollectionsPage').then(m => ({ default: m.RecollectionsPage })))
+const LogosPage         = lazy(() => import('./app/recollections/logos/LogosPage').then(m => ({ default: m.LogosPage })))
+const FluxRoute         = lazy(() => import('./app/recollections/flux/FluxRoute').then(m => ({ default: m.FluxRoute })))
+
 registerBuiltinConfigTypes()
 registerBuiltinNodes()
 
@@ -21,14 +27,22 @@ createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <ThemeProvider>
       <BrowserRouter>
+        <Suspense fallback={<div className="flex items-center justify-center h-screen text-muted-foreground text-sm">Loading…</div>}>
         <Routes>
           <Route path="/" element={<KosmosPage />}>
-            <Route index element={<Navigate to="/projects" replace />} />
-            <Route path="projects" element={<ProjectsPage />} />
-            <Route path="projects/:projectId" element={<CanvasRoute />} />
-            <Route path="keroma" element={<KeromaPage />} />
+            <Route index element={<Navigate to="/recollections" replace />} />
+            <Route path="recollections" element={<RecollectionsPage />} />
+            <Route path="recollections/:recollectionId" element={<RecollectionLayout />}>
+              <Route index element={<Navigate to="logos" replace />} />
+              <Route path="logos" element={<LogosPage />} />
+              <Route path="logos/katalogos" element={<LogosPage />} />
+              <Route path="flux" element={<FluxRoute />} />
+              <Route path="*" element={<Navigate to="logos" replace />} />
+            </Route>
           </Route>
+          <Route path="*" element={<NotFoundPage />} />
         </Routes>
+        </Suspense>
       </BrowserRouter>
       <Toaster richColors position="bottom-right" />
     </ThemeProvider>

frontend/src/styles.css

@@ -1,4 +1,5 @@
 @import "shadcn/dist/tailwind.css";
+@import "@blocknote/shadcn/style.css";
 
 @tailwind base;
 @tailwind components;
@@ -372,18 +373,23 @@ pre {
 .token.nunjucks-var {
     color: #7c3aed;
 }
+
 .token.nunjucks-tag {
     color: #c2410c;
 }
+
 .token.nunjucks-comment {
     color: #0d9488;
 }
+
 .dark .token.nunjucks-var {
     color: #a78bfa;
 }
+
 .dark .token.nunjucks-tag {
     color: #fb923c;
 }
+
 .dark .token.nunjucks-comment {
     color: #2dd4bf;
 }
@@ -394,3 +400,76 @@ pre {
 .code-editor .token.url {
     background: none;
 }
+
+/* Logos tree drop line (LogosDropCursor in TreeBrowser.tsx) */
+@keyframes tree-drop-line-pulse {
+
+    0%,
+    100% {
+        opacity: 1;
+    }
+
+    50% {
+        opacity: 0.4;
+    }
+}
+
+/* React Arborist tree styling for sidebar integration */
+.react-arborist-tree {
+    background: transparent !important;
+    font-size: 0.875rem;
+}
+
+.react-arborist-tree * {
+    outline: none !important;
+}
+
+/* Remove default react-arborist styling */
+.react-arborist-tree [role="treeitem"] {
+    cursor: pointer;
+}
+
+/* Drag preview styling */
+.react-arborist-tree [data-react-arborist-drag-preview] {
+    background: hsl(var(--sidebar-accent)) !important;
+    border: 1px solid hsl(var(--sidebar-border)) !important;
+    border-radius: 0.375rem;
+    padding: 0.25rem 0.5rem;
+    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
+    opacity: 0.9;
+}
+
+/* Drop cursor line */
+.react-arborist-tree [data-react-arborist-drop-cursor] {
+    background: hsl(var(--sidebar-primary)) !important;
+    height: 2px !important;
+    border-radius: 1px;
+    z-index: 10;
+}
+
+/* Make rows draggable */
+.react-arborist-tree [draggable="true"] {
+    cursor: grab;
+}
+
+.react-arborist-tree [draggable="true"]:active {
+    cursor: grabbing;
+}
+
+/* Drag handle: restore focus ring (tree uses outline:none on all descendants) */
+.react-arborist-tree .logos-tree-drag-handle:focus-visible {
+    outline: 2px solid hsl(var(--sidebar-ring)) !important;
+    outline-offset: 2px;
+    box-shadow:
+        0 0 0 2px hsl(var(--sidebar-background)),
+        0 2px 8px hsl(var(--sidebar-ring) / 0.25);
+}
+
+/* Hide default react-arborist backgrounds */
+.react-arborist-tree [data-react-arborist-tree] {
+    background: transparent !important;
+}
+
+.react-arborist-tree [data-react-arborist-list-item] {
+    background: transparent !important;
+}

frontend/tailwind.config.cjs

@@ -1,7 +1,7 @@
 /* Tailwind configuration for Vite + React */
 module.exports = {
 	darkMode: ['class'],
-	content: ['./index.html', './src/**/*.{ts,tsx,js,jsx}'],
+	content: ['./index.html', './src/**/*.{ts,tsx,js,jsx}', './node_modules/@blocknote/shadcn/**/*.{js,ts,jsx,tsx}'],
 	theme: {
     	extend: {
     		borderRadius: {