diff --git a/README.md b/README.md
index 1884098..ac0e37e 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,176 @@
-# concise-ui
+# Concise UI
 
-This template should help get you started developing with Vue 3 in Vite.
+Concise UI is a Vue 3 component framework for desktop-first enterprise and productivity software.
 
-## Recommended IDE Setup
+It is designed for applications such as ERP, WMS, CRM, POS, finance, inventory, administration, and other internal business systems. The goal is a compact, professional interface that displays information efficiently without imitating Bootstrap, Material Design, or old desktop software.
 
-[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+> Concise UI is currently under active development. Its public API may change before the first stable release.
 
-## Recommended Browser Setup
+## Design principles
 
-- 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/)
+- High information density with compact controls and restrained spacing
+- Clear hierarchy through typography, borders, and layout
+- Conservative use of color for actions, status, selection, and validation
+- Desktop-first mouse and keyboard interaction
+- Accessible native semantics where possiblehttps://git.icodeformoney.com/fandi/concise-uihttps://git.icodeformoney.com/fandi/concise-ui
+- Lightweight components without unnecessary runtime dependencies
+- Scoped SCSS and CSS variables for theme customization
+- Predictable Vue APIs and public TypeScript types
 
-## Type Support for `.vue` Imports in TS
+The complete design direction is documented in [AGENTS.md](./AGENTS.md).
 
-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.
+## Components
 
-## Customize configuration
+### Navigation and layout
 
-See [Vite Configuration Reference](https://vite.dev/config/).
+- `CAppBar`
+- `CMenu`
+- `CSeparator`
+- `CSideBar`
 
-## Project Setup
+### Actions and feedback
 
-```sh
-npm install
+- `CButton`
+- `CProgressBar`
+
+### Form structure
+
+- `CFormField`
+- `CInputGroup`
+- `CInputAddon`
+
+### Inputs
+
+- `CInput`
+- `CTextArea`
+- `CPassword`
+- `CNumberInput`
+
+### Selection controls
+
+- `CCheckbox`
+- `CRadio`
+- `CSelect`
+- `CMultiSelect`
+- `CAutoComplete`
+
+### Symbols
+
+- `CIcon`
+
+`CIcon` displays Unicode symbols and emoji supplied by the application. Concise UI does not bundle an icon font or emoji package.
+
+## Basic usage
+
+Components and their public types are exported from the package entry point:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { CButton, CFormField, CInput, CProgressBar } from '@icfm/concise-ui'
+
+const name = ref('')
+const progress = ref(35)
+</script>
+
+<template>
+  <CFormField label="Customer name" required>
+    <CInput v-model="name" placeholder="Enter a name" />
+  </CFormField>
+
+  <CButton variant="primary">Save</CButton>
+  <CProgressBar :value="progress" show-value />
+</template>
 ```
 
-### Compile and Hot-Reload for Development
+Component styling is authored as scoped SCSS and uses theme variables. The production build emits `dist/concise-ui.css` alongside the JavaScript bundles; applications must include that generated stylesheet. Theme variables can customize presentation without changing component behavior.
 
-```sh
-npm run dev
+## Data-driven selection
+
+`CSelect` and `CMultiSelect` accept standard `{ label, value }` records or raw objects with accessor props:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { CSelect } from '@icfm/concise-ui'
+
+const products = [
+  { id: 1, name: 'Book', code: 'BOO' },
+  { id: 2, name: 'Stove', code: 'STV' },
+]
+
+const selectedProduct = ref(null)
+</script>
+
+<template>
+  <CSelect
+    v-model="selectedProduct"
+    :options="products"
+    option-label="name"
+    option-key="id"
+    filterable
+    clearable
+  />
+</template>
 ```
 
-### Type-Check, Compile and Minify for Production
+Omitting `option-value` binds the complete object. Adding `option-value="id"` binds only the ID.
+
+Filterable `CSelect` and `CAutoComplete` also support parent-controlled remote searching through `@search`, `debounce-wait`, `min-search-length`, and `loading`. Components coordinate the interaction but leave authentication, networking, cancellation, and error handling to the application.
+
+## Documentation application
+
+The repository contains a documentation application with live examples and highlighted Vue and JavaScript snippets for the public components.
 
 ```sh
-npm run build
+npm install
+npm run dev
 ```
 
-### Run Unit Tests with [Vitest](https://vitest.dev/)
+Open the local URL printed by Vite and navigate to **Components**.
+
+## Development commands
 
 ```sh
+# Start the documentation development server
+npm run dev
+
+# Type-check, build the library, and emit declarations
+npm run build
+
+# Run unit tests
 npm run test:unit
+
+# Run the configured linters
+npm run lint
+
+# Format source files
+npm run format
 ```
 
-### Lint with [ESLint](https://eslint.org/)
+The supported Node.js versions are `^22.18.0` or `>=24.12.0`. Vue `^3.5.0` is a peer dependency.
 
-```sh
-npm run lint
+## Project structure
+
+```text
+src/
+├─ components/       Public component implementations and types
+├─ documentation/    Documentation-only components
+├─ layouts/          Documentation application layouts
+├─ pages/components/ Component guides and live examples
+├─ router/           Documentation routes
+├─ styles/           Documentation application styles
+└─ index.ts          Public library exports
 ```
+
+## Adding a component
+
+The required component workflow is documented in [AGENTS.md](./AGENTS.md#creating-a-new-component). In summary:
+
+1. Define the API, states, events, slots, model shape, and keyboard behavior.
+2. Implement the component and any reusable public types.
+3. Include accessibility and theme-aware compact styling.
+4. Export the component and its public types from `src/index.ts`.
+5. Create its documentation page with live examples and code snippets.
+6. Register its documentation route and both navigation entries.
+7. Review API consistency, accessibility, documentation accuracy, and the final diff.