docs: reframe Helix as a quick-start boilerplate for customisation

AGENTS.md

@@ -3,6 +3,13 @@
 Guidance for AI coding agents and contributors working in this repository.
 It complements [README.md](README.md); read that first for the project overview.
 
+> **Scope — this is a quick-start boilerplate.** Helix is a starting point for
+> custom development, not a finished product. The baseline modules
+> (authentication, RBAC, user/role/department/position/menu management) are
+> intentionally kept minimal and exist to be extended. When adding features,
+> build on the existing patterns below; do not introduce parallel
+> conventions.
+
 ## Repository overview
 
 Helix is a monorepo containing a backend API and a frontend SPA:
@@ -82,6 +89,12 @@ pnpm lint            # ESLint
 
 ## General guidelines
 
+- **Custom development.** When extending the boilerplate, use the existing
+  extension points rather than parallel patterns: add Flyway migrations for
+  schema changes, register message keys in every i18n bundle, implement features
+  through the standard `Controller → Service → Manager → Repository` chain, and
+  expose typed API clients in `web/src/api`. Customise the baseline — do not
+  re-architect it.
 - **Commits.** Use Conventional Commits (`feat:`, `fix:`, `refactor:`, `chore:`,
   `docs:`, `perf:`, `style:`, `test:`). Match the language of the surrounding
   history (the log is a mix of English and Chinese).

CONTRIBUTING.md

@@ -1,8 +1,21 @@
 # Contributing to Helix
 
-Thanks for your interest in contributing! Helix is open source under the
+Thanks for your interest in contributing! Helix is a quick-start boilerplate for
-[MIT licence](LICENCE). This guide explains how to set up your environment,
+custom development, open source under the [MIT licence](LICENCE). This guide
-make changes and get them merged.
+explains how to set up your environment, make changes and get them merged.
+
+## What to contribute
+
+Contributions should make the **boilerplate itself** more useful to everyone who
+forks it:
+
+- New or improved baseline capabilities (reusable, not business-specific)
+- Bug fixes and hardening
+- Documentation and tests
+
+Changes that encode one particular organisation's custom rules are usually
+better kept in your own fork. If you are not sure whether something belongs in
+the boilerplate, open an issue first and ask.
 
 ## Getting started
 

README.md

@@ -1,21 +1,26 @@
 # Helix
 
-Helix is a self-hosted identity and access management (IAM) and organisation
+Helix is a **quick-start boilerplate** for building custom identity and organisation
-administration platform built by [OnixByte](https://onixbyte.com). It manages
+management systems. It ships with a working full-stack baseline — authentication,
-users, roles, departments, positions and navigation menus behind a single
+role-based access control, and user/role/department/position/menu management — so
-sign-on experience, with support for Microsoft Entra ID (Azure AD), WeCom
+you can start from a runnable application and customise it to your own
-(WeChat Work) and multi-factor authentication.
+requirements instead of starting from zero.
 
-The project is organised as a monorepo:
+The boilerplate is organised as a monorepo:
 
 - **`server/`** — Spring Boot 3 REST API (Java 21, PostgreSQL, Redis, Flyway)
 - **`web/`** — React 19 single-page application (Vite, Ant Design, Tailwind CSS, Redux Toolkit)
 - **`docker/`** — deployment support files used by Docker Compose
 
-## Features
+> Helix is a starting point, not a finished product. Every baseline module is
+> meant to be extended or replaced as part of your custom development.
+
+## Baseline capabilities
+
+Out of the box the boilerplate provides:
 
 - **Authentication & single sign-on** — username/password login with captcha,
-  Microsoft Entra ID (MSAL) sign-in, WeCom login and MFA
+  Microsoft Entra ID (MSAL) sign-in, WeCom (WeChat Work) login and MFA
 - **User management** — create, edit and deactivate users; assign roles, departments and positions
 - **Role-based access control** — roles with fine-grained authorities, enforced across all endpoints
 - **Organisation management** — departments, positions and custom navigation menus
@@ -63,6 +68,21 @@ The project is organised as a monorepo:
 └── .env.example                # Compose environment template
 ```
 
+## Customising the boilerplate
+
+Helix is designed to be forked and extended. The recommended approach:
+
+1. **Fork (or copy) the repository** and rename the project to your own.
+2. **Change the branding** — application title (`VITE_APP_TITLE`), regions
+   (`VITE_DEFAULT_REGION_ABBREVIATION`), JWT issuer, S3 buckets and so on.
+3. **Build on the baseline modules.** The existing patterns — custom validation
+   framework, `BizException` + `MessageName` error handling, JWT authentication,
+   Redux slices and typed API clients — are the extension points for your own
+   features. Follow the conventions in [AGENTS.md](AGENTS.md).
+4. **Add schema changes as Flyway migrations** under
+   `server/src/main/resources/db/migrations/` and add new message keys to
+   **all** i18n bundles.
+
 ## Quick start
 
 ### Full stack with Docker Compose
@@ -151,6 +171,6 @@ it, set `app.asset.enabled: true` there and provide the `S3_*` variables.
 - Database schema is managed with Flyway — add migrations under
   `server/src/main/resources/db/migrations/` rather than relying on JPA `ddl-auto`.
 
-## License
+## Licence
 
 [MIT](LICENCE) © OnixByte