diff --git a/frontend/README.md b/frontend/README.md
index afcc3a5..d0aeeec 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,27 +1,43 @@
 # coleaf-frontend
 
-This template should help get you started developing with Vue 3 in Vite.
+The web frontend of **coconut-leaf** — a light, self-hosted, multi-account calendar system.
+This package is a from-scratch rewrite of the legacy JavaScript + jQuery frontend (`frontend-legacy/`) on a modern toolchain.
 
-## Recommended IDE Setup
+## Tech Stack
 
-[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+- **Framework:** Vue 3 (`<script setup>` + TypeScript)
+- **Build tool:** Vite
+- **State management:** Pinia (with `pinia-plugin-persistedstate`)
+- **Routing:** Vue Router (navigation guards + per-route window titles)
+- **Internationalization:** vue-i18n (`en-US` / `zh-CN`, message files under `src/locales/`)
+- **Styling:** Bulma 0.9 (imported via SCSS) + Font Awesome icons
+- **Linting:** oxlint + ESLint
 
-## Recommended Browser Setup
+Requires Node `^20.19` or `>=22.12` (see `package.json` → `engines`).
 
-- Chromium-based browsers (Chrome, Edge, Brave, etc.):
-  - [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
-  - [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
-- Firefox:
-  - [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
-  - [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
+## Project Layout
 
-## Type Support for `.vue` Imports in TS
+```text
+src/
+├── api/          # backend client (fetch-based apiWrapper + typed endpoints)
+├── components/   # reusable UI (calendar/, collection/, todo/, admin/, DateTimePicker, MessageBox)
+├── locales/      # i18n messages (enUS.ts, zhCN.ts)
+├── router/       # route table + beforeEach guard (auth check + document.title)
+├── stores/       # Pinia stores (token, language)
+├── utils/        # datetime recurrence engine, i18n bootstrap, helpers
+└── views/        # page-level views (Home, Login, Collection, Todo, Calendar, CalendarEvent, Admin, NotFound)
+```
 
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
+## Development Server
 
-## Customize configuration
+`vite.config.ts` is preconfigured:
 
-See [Vite Configuration Reference](https://vite.dev/config/).
+- **`base: '/web/'`** — matches the `/web` prefix routed by the production Nginx.
+- **Dev port:** `5173`, opens `/web/` on start.
+- **API proxy:** `/api/<path>` → `http://127.0.0.1:8848/<path>` (the local
+  backend), with the `/api` prefix stripped on the fly.
+
+Start the backend (listening on `127.0.0.1:8848`) before launching the frontend.
 
 ## Project Setup
 
@@ -46,3 +62,18 @@ pnpm build
 ```sh
 pnpm lint
 ```
+
+## Internationalization
+
+- Translation strings live in `src/locales/enUS.ts` and `src/locales/zhCN.ts`
+  (keys omit the legacy `ccn-i18n-` prefix).
+- The active language is held in the Pinia `language` store (persisted under
+  the `ccn-i18n` localStorage key) and synced to `i18n.global.locale` via a
+  watcher in `src/App.vue`.
+- Switch languages from the navbar dropdown; all visible text — including the
+  window title (driven by each route's `meta.title`) — updates immediately.
+
+## License
+
+Source code is licensed under [AGPL v3](https://www.gnu.org/licenses/agpl-3.0.html).
+See the repository root for details.