diff --git a/README.md b/README.md
index f0023ae..2a3661e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Lapikud External Website
 
-![Built with Svelte](https://img.shields.io/badge/Svelte-5-FF3E00?logo=svelte&logoColor=white)
+![Built with Vue](https://img.shields.io/badge/Vue-3-42B883?logo=vuedotjs&logoColor=white)
 ![Built with Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white)
 ![Deployed on GitHub Pages](https://img.shields.io/badge/Deployed-GitHub%20Pages-222?logo=github)
 
@@ -28,7 +28,7 @@ Found a bug, typo, or something missing? [Open an issue](https://github.com/Lapi
 
 ### What you need first
 
-- [Node.js](https://nodejs.org/) — v18 or higher, but grab the **LTS version** (currently v24) to be safe
+- [Node.js](https://nodejs.org/) — v20.19 or higher; use the current **LTS version** when possible
 
 > Node.js comes with `npm` included, so you don't need to install that separately.
 
@@ -77,10 +77,10 @@ git clone https://github.com/Lapikud/lapikud.github.io.git
 cd lapikud.github.io
 ```
 
-**2. Install dependencies** — this installs all the packages the project needs:
+**2. Install dependencies** — this installs the exact package versions recorded by the project:
 
 ```bash
-npm install
+npm ci
 ```
 
 **3. Optimise images** — the optimised image variants are not stored in the repo, so you need to generate them locally before running the site:
@@ -101,6 +101,33 @@ Then open the URL it gives you (usually `http://localhost:5173`) in your browser
 
 ---
 
+## 🧭 How the project fits together
+
+The site is a Vue 3 single-page application built with Vite. Vue starts in `src/main.js`, which mounts `src/App.vue`. The app keeps its intentionally small custom router and translation system rather than introducing larger framework plugins.
+
+- `src/routes/` contains the page components and the bilingual public route table.
+- `src/components/` contains reusable UI building blocks; layout primitives live in `src/components/layout/`.
+- `src/layout/` contains the site-wide navigation and footer.
+- `src/lib/` contains routing, translations, image-path helpers, and the shared YAML loader.
+- `src/lib/locales/{est,en}/` contains escaped JSON translation data for each language.
+- `public/_data/` contains editable YAML for members, mentors, workshops, projects, partners, and pricing.
+- `public/assets/` contains source assets; generated image variants remain ignored.
+- `.storybook/` and `src/stories/` provide isolated Vue component previews.
+
+Page components use Vue's `<script setup>` syntax and Composition API primitives such as `ref` and `computed`. Use `usePageText("PageName")` for page translations, `loadYaml(path, fallback)` for YAML-backed content, and the exported `navigate()` helper for programmatic internal navigation.
+
+Useful commands:
+
+```bash
+npm run dev             # start the local site
+npm run build           # create a production build
+npm run storybook       # preview components in Storybook
+npm run build-storybook # verify the static Storybook build
+npm run optimise        # regenerate local image variants
+```
+
+---
+
 ## 🖼️ Adding images
 
 Place your original image files (PNG, JPG, etc.) into the appropriate `public/assets/{category}/original/` folder, then run:
@@ -119,4 +146,4 @@ The script will generate optimised WebP and JPG variants automatically. **Do not
 
 Nothing to do here — GitHub automatically builds and deploys the site whenever something is pushed to the `v2` branch. The optimised images are generated as part of the build, so you don't need to worry about that either.
 
-It usually takes **2–5 minutes**. You can watch it happen in the [Actions tab](https://github.com/Lapikud/lapikud.github.io/actions).
\ No newline at end of file
+It usually takes **2–5 minutes**. You can watch it happen in the [Actions tab](https://github.com/Lapikud/lapikud.github.io/actions).
diff --git a/src/components/README.md b/src/components/README.md
index b5b8338..8dbdca1 100644
--- a/src/components/README.md
+++ b/src/components/README.md
@@ -1,26 +1,26 @@
-# SVG previews
+# Component previews
 
-use `npm run storybook` which opens a browser window with all the SVG variations. You can also edit the SVG properties in storybook controls.
+Run `npm run storybook` to open the Vue component previews, including every SVG variation. Storybook controls can change the SVG props interactively.
 
 # Components
 
-under components are building blocks that are not layout related.
+Components in this directory are reusable Vue building blocks that are not layout-specific. They use `<script setup>`, Vue props, and the default slot for child content.
 
 ## details
 
 - Button: a simple button component with some styling.
 - Dropdown: a dropdown component that can be used to show/hide content.
 - Slideshow: a simple slideshow component that can be used to show multiple images in a slideshow format. Includes options to enable/disable autoplay and to set the autoplay interval.
-- Svg: a component that renders different SVG icons based on the `type` prop. See the VARIANTS constant in `Svg.svelte` or storybook for the available types.
+- Svg: a component that renders different SVG icons based on the `type` prop. See the `VARIANTS` constant in `Svg.vue` or Storybook for the available types.
 - Image (Use for larger images): a component that renders an image with some styling. It accepts a lot of props. Main ones are `src` (the main image source that is used if anything else fails or not provided), `alt` (the alt text for the image), `srcSet` (a string of comma-separated image sources for different screen sizes, jpg or png files), `webpSrc` (the webp image source as a webp file), `webpSrcSet` (a string of comma-separated webp image sources for different screen sizes). We use 2 webp images: 400 and 800 width, and one jpg image 800 width as default src for fallback.
 
 # Layout components
 
-under components/layout are components that are used to structure the page, such as Container, Stack, Center, etc.
+Components under `components/layout` structure page content. Prefer these shared primitives over duplicating container, spacing, or grid rules in a route.
 
 - Container: a simple container component that centers its content and adds some padding.
 - Stack: a component that stacks its children vertically or horizontally.
 - Center: a component that centers its content both horizontally and vertically.
 - Section: a component that is used to create sections on the page.
 - Card: a component that adds some padding, a border, and a shadow to its content, used to create cards on the page.
-- Grid: a component that creates a CSS grid layout for its children, with customizable columns and gap. It is dynamic and changes automatically with page size, best practice is to set `columns` for desktop and `mobileColumns` for mobile views to control the behavior if needed.
\ No newline at end of file
+- Grid: a component that creates a CSS grid layout for its children, with customizable columns and gap. It is dynamic and changes automatically with page size, best practice is to set `columns` for desktop and `mobileColumns` for mobile views to control the behavior if needed.