diff --git a/DESIGN.md b/DESIGN.md
index cba28d7..6baf62b 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1,6 +1,6 @@
 # Design system (Fluksio)
 
-`fluksio` (dashboard SPA + API) and `website` (marketing site) are **separate
+`app` (dashboard SPA + API) and `index` (marketing site) are **separate
 repos** that share one visual design. The full, canonical spec — palette,
 radius, elevation, motion, component map, and shell patterns — lives in the
 parent repo's [`DESIGN-GUIDELINES.md`](../DESIGN-GUIDELINES.md). Read it before
@@ -8,8 +8,8 @@ any UI work.
 
 ## Sync rule (read before touching tokens)
 
-The `@theme inline`, `:root`, and `.dark` blocks in `fluksio/frontend/src/index.css`
-and `website/src/index.css` **must be kept byte-identical**, and
+The `@theme inline`, `:root`, and `.dark` blocks in `app/frontend/src/index.css`
+and `index/src/index.css` **must be kept byte-identical**, and
 `frontend/src/lib/motion.ts` is duplicated verbatim. Any palette / radius /
 elevation / motion-token change is made in *both* repos in the same change.
 There is intentionally no shared npm package — the duplicated blocks are the
diff --git a/NOTEPAD.md b/NOTEPAD.md
index 0f1f523..98f6566 100644
--- a/NOTEPAD.md
+++ b/NOTEPAD.md
@@ -15,7 +15,7 @@ Deferring because out of scope is fine, but don't mention deferring than.
 - CHORE/FLOW: the flow test files live in `backend/app/flow/test*.py`, inside the package
   rather than `backend/tests/`, so `coverage run -m pytest tests/` never collects them.
 - CHORE/INFRA: port the n3xd CI workflows (pre-commit, backend tests, Playwright shards,
-  compose smoke) to `.forgejo/workflows/`. Codeberg runs Forgejo Actions and needs CI
+  compose smoke) to `.gitea/workflows/`. The Gitea instance runs Gitea Actions and needs CI
   enabled per repository.
 - FEAT/UI: `@xyflow/react` and a Monaco editor belong here once the node canvas starts.
   The website already demos `@xyflow/react` on its features page.
@@ -31,3 +31,7 @@ Deferring because out of scope is fine, but don't mention deferring than.
 
 - FEAT/INFRA: Redis, MQTT broker and InfluxDB compose services. Blocked on the flow engine
   being reachable from the API — no runtime path imports them today.
+- CHORE/INFRA: `bun install` inside the frontend Docker build intermittently fails with
+  "Fail extracting tarball" for several packages at once, and succeeds on a plain rebuild.
+  It looks like concurrent extraction under memory pressure. Pin down or retry in the
+  Dockerfile if it starts costing CI time.
diff --git a/README.md b/README.md
index ad16750..387c554 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,42 @@
-# Fluksio Main Repository
+# Fluksio App
 
-A node based, test-driven home-automation software to built to scale.
\ No newline at end of file
+The core of Fluksio: a node-based, test-driven automation software built to scale. This
+repo holds the FastAPI backend, the flow engine, and the dashboard SPA. It is served on
+`app.${DOMAIN}` (SPA) and `api.${DOMAIN}` (API); the marketing site lives in the sibling
+`index` repo.
+
+## Layout
+
+```text
+backend/        FastAPI + SQLModel + Alembic + Postgres
+  app/flow/     the flow engine (nodes, pipeline, state backends, controller)
+frontend/       React 19 + TanStack Router + Tailwind 4 + shadcn/ui
+docker/         compose.yml → compose.dev.yml → compose.local.yml (+ compose.traefik.yml)
+scripts/        generate-client.sh, test.sh
+```
+
+## Getting started
+
+Normally driven from the workspace root (`make init` once, then `make dev`). Standalone:
+
+```sh
+make install       # uv sync + bun install
+make dev-utils     # db, adminer, proxy, mailcatcher, prestart only
+make dev-backend   # FastAPI on :8000, hot reload
+make dev-frontend  # Vite on :5173
+```
+
+```sh
+make test           # pytest + Playwright
+make lint           # ruff + mypy + biome
+make generate-client  # regenerate the frontend SDK from the OpenAPI schema
+```
+
+`make help` lists every target.
+
+## Documentation
+
+- [`ROADMAP.md`](ROADMAP.md) — strategy and feature record
+- [`NOTEPAD.md`](NOTEPAD.md) — deferred work and findings
+- [`DESIGN.md`](DESIGN.md) — points at the workspace root's `DESIGN-GUIDELINES.md`
+- `docs/architecture/` in the sibling `docs` repo — the requirement sources
diff --git a/ROADMAP.md b/ROADMAP.md
index bb79f63..603100f 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,8 +1,8 @@
 # Roadmap
 
 Implementation strategy and record of existing/planned features. Completed items are
-terse checklists — the requirement detail lives in `org/README.md` (software requirements,
-evaluated tooling, hardware) and `org/structure.canvas` (the four-way component split).
+terse checklists — the requirement detail lives in `docs/architecture/overview.md` (software requirements,
+evaluated tooling, hardware) and `docs/architecture/structure.canvas` (the four-way component split).
 Remaining tasks keep enough scope to be actionable.
 
 Legend: `[x]` done · `[ ]` planned · sub-lists split done vs. remaining for partial items.
@@ -12,7 +12,7 @@ existing flow engine reachable and persistent precedes new feature breadth.
 
 ## Phase 0 — Workspace and platform
 
-- [x] Root orchestrator repo with `fluksio`, `website`, `docs`, `org` as submodules
+- [x] Root orchestrator repo with `app`, `index` and `docs` as submodules
 - [x] `make init` bootstrap: secrets generation, per-stack `.env` propagation, shared
       `proxy` docker network
 - [x] Layered compose (`compose.yml` → `compose.dev.yml` → `compose.local.yml`) for both
@@ -24,7 +24,7 @@ existing flow engine reachable and persistent precedes new feature breadth.
 ## Phase 1 — Backend: management
 
 Python, optimised for development speed. Owns the graph structure, persistence and the
-external interfaces. See `org/structure.canvas` → *Backend – Management*.
+external interfaces. See `docs/architecture/structure.canvas` → *Backend – Management*.
 
 - [x] FastAPI + SQLModel + Alembic + Postgres base with JWT auth and user management
 - [x] Flow engine prototype in `backend/app/flow/`: `Node` / `Pipeline` / `StateBackend`
@@ -51,7 +51,7 @@ external interfaces. See `org/structure.canvas` → *Backend – Management*.
 ## Phase 2 — Backend: processing
 
 Rust, optimised for throughput. Executes nodes and distributes them across workers. See
-`org/structure.canvas` → *Backend – Processing*.
+`docs/architecture/structure.canvas` → *Backend – Processing*.
 
 - [ ] Extract node execution from the Python prototype into a Rust engine
 - [ ] Worker distribution and load balancing across capable devices
@@ -60,7 +60,7 @@ Rust, optimised for throughput. Executes nodes and distributes them across worke
 
 ## Phase 3 — Frontend: admin view
 
-React + Vite, primarily desktop but usable on mobile. See `org/structure.canvas` →
+React + Vite, primarily desktop but usable on mobile. See `docs/architecture/structure.canvas` →
 *Frontend – Admin View*.
 
 - [x] Dashboard SPA shell: TanStack Router, floating frosted sidebar, auth flows,
@@ -75,7 +75,7 @@ React + Vite, primarily desktop but usable on mobile. See `org/structure.canvas`
 
 ## Phase 4 — Frontend: dashboard view
 
-Shares components with the admin view. See `org/structure.canvas` →
+Shares components with the admin view. See `docs/architecture/structure.canvas` →
 *Frontend – Dashboard View*.
 
 - [ ] User-defined dashboard layout with edit and view modes
diff --git a/frontend/src/components/Common/Footer.tsx b/frontend/src/components/Common/Footer.tsx
index 957ed92..7742702 100644
--- a/frontend/src/components/Common/Footer.tsx
+++ b/frontend/src/components/Common/Footer.tsx
@@ -3,7 +3,7 @@ import { SiCodeberg } from "react-icons/si"
 const socialLinks = [
   {
     icon: SiCodeberg,
-    href: "https://codeberg.org/fluksio",
+    href: "https://git.stroblme.de/Fluksio",
     label: "Codeberg",
   },
 ]
diff --git a/frontend/src/index.css b/frontend/src/index.css
index 5f6ad47..0031209 100644
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -72,7 +72,7 @@
  *
  * `--primary` is #4a7189, not the identity blue #59849b: the latter measures
  * 4.04:1 against white, below AA for the label sitting on a bg-primary fill.
- * #59849b remains the wordmark colour (org/design/fluksio-*.svg). See the root
+ * #59849b remains the wordmark colour (index/src/assets/fluksio-*.svg). See the root
  * DESIGN-GUIDELINES.md → Colour tokens.
  */
 :root {
diff --git a/frontend/src/lib/motion.ts b/frontend/src/lib/motion.ts
index bcdf24e..f8a85dc 100644
--- a/frontend/src/lib/motion.ts
+++ b/frontend/src/lib/motion.ts
@@ -5,7 +5,7 @@
  * across the app. Mirrors the `--ease-*` / `--duration-*` timing tokens defined
  * in `index.css`, so CSS transitions and JS animations stay in sync.
  *
- * This file is duplicated verbatim in `fluksio` and `website` (the shadcn model,
+ * This file is duplicated verbatim in `app` and `index` (the shadcn model,
  * see ../../DESIGN.md / the root DESIGN-GUIDELINES.md). Keep the two copies
  * identical; `make design-check` at the workspace root verifies it.
  *
diff --git a/package.json b/package.json
index 47c28ef..4941f1e 100644
--- a/package.json
+++ b/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "fluksio",
+  "name": "fluksio-app",
   "private": true,
   "workspaces": [
     "frontend"