diff --git a/README.md b/README.md
index 2294cc6..36e992b 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,73 @@
 # kittyFE
 
+*Front-end for the [KittyURL](https://gitea.7o7.cx/kittyteam/kittyurl) project — create short and memorable URLs with ease!*
+
+## Goals
+
+Provide a responsive and modern user interface for:
+
+* Account management (login, register, history, settings)
+* Link creation (public landing page)
+* Dashboard link management (for logged-in users)
+* User management (admin panel)
+
+
+KittyFE is built with **Vite + React (TypeScript)** to integrate seamlessly with [kittyBE](https://gitea.7o7.cx/kittyteam/kittyBE) and is easily dockerizable.
+
+## Running kittyFE
+
+KittyFE has been verified to work on **Node v24.11.1**.
+
+### On bare metal
+
+Running the front-end is as simple as:
+
+1. **Install dependencies**
+
+   * To download the required dependencies:
+
+     ```sh
+     npm install
+     ```
+
+   * To install an exact copy of all dependencies (recommended for CI):
+
+     ```sh
+     npm ci
+     ```
+
+2. **Configure environment variables**
+
+   Copy the `.env.example` file to `.env` and customize it to your preferences.
+
+   **Example:** Tell the frontend where the backend API is located. Your `.env` file should look like this:
+
+   ```properties
+   VITE_API_TARGET=http://localhost:6567
+   ```
+
+   > **Important:** All environment variables exposed to Vite must start with `VITE_`. Make sure the URL matches your running instance of `kittyBE`.
+
+3. **Launch the development server**
+
+   ```sh
+   npm run dev
+   ```
+
+4. **Open the app**
+
+   Visit:
+
+   ```text
+   http://localhost:6568
+   ```
+
+   (or the port shown in your terminal output).
+
+### Building for production
+
+To create an optimized static production build:
+
+```sh
+npm run build
+```