docs: Add user and API documentation guides in English and Chinese

Signed-off-by: FrozenlemonTee <1115306170@qq.com>

Author: FrozenLemonTee

docs/README.md

@@ -0,0 +1,12 @@
+# Documentation
+
+## Guide
+
+- [中文用户文档](./guide/zh/README.md)
+- [English User Guide](./guide/en/README.md)
+
+## API
+
+- [中文 API 文档](./api/zh/README.md)
+- [English API Documentation](./api/en/README.md)
+

docs/api/README.md

@@ -0,0 +1,5 @@
+# API Documentation
+
+- [中文 API 文档](./zh/README.md)
+- [English API Documentation](./en/README.md)
+

docs/guide/README.md

@@ -0,0 +1,5 @@
+# User Guide
+
+- [中文用户文档](./zh/README.md)
+- [English User Guide](./en/README.md)
+

docs/guide/en/concurrency.md

@@ -0,0 +1,75 @@
+# Concurrency Guide
+
+## Concurrency Policies
+
+Built-in concurrency policies:
+
+- `policy::concurrency::none`
+- `policy::concurrency::fenced`
+- `policy::concurrency::fenced_relaxed`
+- `policy::concurrency::fenced_acq_rel`
+- `policy::concurrency::fenced_seq_cst`
+
+General guidance:
+
+- Use `none` for single-threaded paths.
+- Use `fenced` or `fenced_seq_cst` first for simple correctness.
+- Use relaxed/acq_rel variants only when you have clear memory-order requirements.
+
+## Shared State with `primitive`
+
+```cpp
+using shared_t = mcpplibs::primitives::primitive<
+    int,
+    mcpplibs::primitives::policy::value::checked,
+    mcpplibs::primitives::policy::concurrency::fenced,
+    mcpplibs::primitives::policy::error::expected>;
+
+shared_t counter{0};
+```
+
+Use:
+
+- `counter.load()`
+- `counter.store(v)`
+- `counter.compare_exchange(expected, desired)`
+
+## CAS Loop Pattern
+
+```cpp
+auto expected = counter.load();
+while (!counter.compare_exchange(expected, expected + 1)) {
+}
+```
+
+This is the typical lock-free increment style used in multi-threaded updates.
+
+## Mixed Read/Write Workload
+
+For practical concurrent workloads, combine:
+
+- writer threads updating operands through `store`
+- reader threads calling `operations::add` / `operations::sub`
+- optional sink updates via `store` and checkpoint `compare_exchange`
+
+See `examples/ex05_concurrency_policy.cpp` for a representative end-to-end workload.
+
+## Pitfalls
+
+### 1) Atomic-ref compatibility
+
+Fenced access handlers require underlying representations to satisfy atomic-ref constraints (trivially copyable and alignment-compatible).
+
+### 2) Treating operations as implicit synchronization
+
+Operation dispatch consistency and concurrency fences are policy-driven. Do not assume synchronization semantics unless explicitly configured.
+
+### 3) Ignoring error paths
+
+Operation results are `std::expected<...>`. Always handle `has_value()`.
+
+## Next
+
+- Extension guide: [./extension.md](./extension.md)
+- API concurrency details: [../../api/en/README.md](../../api/en/README.md)
+

docs/guide/en/extension.md

@@ -0,0 +1,77 @@
+# Extension Guide
+
+This page covers extensibility paths used by advanced users.
+
+## 1) Custom Underlying Type
+
+Define a domain type and specialize `underlying::traits<T>`.
+
+Required members:
+
+- `value_type`
+- `rep_type`
+- `static constexpr bool enabled`
+- `static constexpr underlying::category kind`
+- `to_rep(value)`
+- `from_rep(rep)`
+- `is_valid_rep(rep)`
+
+After registration, your type can be used as `primitive<YourType, ...>` if it satisfies `underlying_type`.
+
+Reference example: `examples/ex06_custom_underlying.cpp`.
+
+## 2) Custom Common Rep Negotiation
+
+If default `std::common_type_t` is not suitable, specialize:
+
+```cpp
+template <>
+struct mcpplibs::primitives::underlying::common_rep_traits<LhsRep, RhsRep> {
+  using type = YourCommonRep;
+  static constexpr bool enabled = true;
+};
+```
+
+This affects mixed dispatch and type negotiation.
+
+## 3) Custom Policy Tags and Handlers
+
+Custom policies require:
+
+1. Registering tags via `policy::traits<YourPolicyTag>`.
+2. Providing protocol specializations in the correct namespaces:
+   - `policy::type::handler`
+   - `policy::value::handler`
+   - `policy::error::handler`
+   - `policy::concurrency::handler`
+
+If your value policy needs operation runtime behavior, also provide `operations::runtime::op_binding` specializations.
+
+Reference example: `examples/ex07_custom_policy.cpp`.
+
+## 4) Custom Operation Tags
+
+To add new operation tags:
+
+1. Define operation tag type.
+2. Specialize `operations::traits<OpTag>` with:
+   - `enabled = true`
+   - `arity`
+   - `capability_mask`
+3. Provide `operations::runtime::op_binding<OpTag, ValuePolicy, CommonRep>`.
+4. Invoke via `operations::apply<OpTag>(lhs, rhs)`.
+
+Reference example: `examples/ex08_custom_operation.cpp`.
+
+## Extension Checklist
+
+- Policy groups are consistent across operands.
+- Operation capability metadata is valid.
+- Value policy + operation binding exists for runtime dispatch.
+- Error policy handler returns expected payload type.
+- Concurrency access handler exists if you need `load/store/CAS`.
+
+## Next
+
+- API details for protocol contracts: [../../api/en/README.md](../../api/en/README.md)
+

docs/guide/en/installation-and-build.md

@@ -0,0 +1,89 @@
+# Installation and Build
+
+## Prerequisites
+
+- C++23-capable compiler
+  - GCC >= 14
+  - Clang >= 17
+  - MSVC >= 19.34 (MSVC version >= 1934)
+- Build tools
+  - xmake (recommended)
+  - or CMake + Ninja
+
+## Build with xmake
+
+Build the library:
+
+```bash
+xmake build mcpplibs-primitives
+```
+
+Run an example:
+
+```bash
+xmake run ex01_default_arithmetic
+```
+
+Run tests:
+
+```bash
+xmake run primitives_test
+```
+
+Compatibility alias:
+
+```bash
+xmake run basic
+```
+
+`basic` runs `ex01_default_arithmetic`.
+
+## Build with CMake
+
+Configure and build:
+
+```bash
+cmake -B build -G Ninja
+cmake --build build --target mcpplibs-primitives
+```
+
+Build an example and tests:
+
+```bash
+cmake --build build --target ex01_default_arithmetic
+cmake --build build --target basic_tests
+ctest --test-dir build --output-on-failure
+```
+
+## Example Targets
+
+Examples are available as independent targets:
+
+- `ex01_default_arithmetic`
+- `ex02_type_policy`
+- `ex03_value_policy`
+- `ex04_error_policy`
+- `ex05_concurrency_policy`
+- `ex06_custom_underlying`
+- `ex07_custom_policy`
+- `ex08_custom_operation`
+
+## Common Build Issues
+
+### 1) C++ standard or modules not enabled
+
+Ensure C++23 is enabled and your compiler supports C++ modules.
+
+### 2) Compiler version too old
+
+Use the minimum versions listed above. For GCC/Clang/MSVC, older versions can fail early at configuration or module compilation.
+
+### 3) Failing to find test dependencies
+
+The test target depends on GoogleTest. Use xmake package resolution or ensure CMake can fetch/access the configured repository.
+
+## Next
+
+- Continue with [Quick Start](./quick-start.md)
+- API details: [../../api/en/README.md](../../api/en/README.md)
+

docs/guide/en/quick-start.md

@@ -0,0 +1,90 @@
+# Quick Start
+
+## Minimal Program
+
+```cpp
+import std;
+import mcpplibs.primitives;
+
+using namespace mcpplibs::primitives;
+using namespace mcpplibs::primitives::operators;
+
+int main() {
+  using value_t =
+      primitive<int, policy::value::checked, policy::error::expected>;
+
+  auto const out = value_t{40} + value_t{2};
+  if (!out.has_value()) {
+    return 1;
+  }
+  return out->value() == 42 ? 0 : 1;
+}
+```
+
+Key point: arithmetic and operator APIs typically return `std::expected<...>`.
+
+## First Policy Setup
+
+Recommended starting combination:
+
+- `policy::value::checked`
+- `policy::error::expected`
+- default `type::strict`
+- default `concurrency::none`
+
+This gives safe arithmetic and explicit error handling without requiring exceptions.
+
+## Learn by Examples
+
+Run examples in this order:
+
+1. `ex01_default_arithmetic`
+2. `ex02_type_policy`
+3. `ex03_value_policy`
+4. `ex04_error_policy`
+5. `ex05_concurrency_policy`
+6. `ex06_custom_underlying`
+7. `ex07_custom_policy`
+8. `ex08_custom_operation`
+
+Command:
+
+```bash
+xmake run ex03_value_policy
+```
+
+## Common Usage Snippets
+
+### Default primitive
+
+```cpp
+using default_i32 = mcpplibs::primitives::primitive<int>;
+```
+
+### Mixed primitive/underlying operation
+
+```cpp
+using value_t = mcpplibs::primitives::primitive<
+    int,
+    mcpplibs::primitives::policy::type::compatible,
+    mcpplibs::primitives::policy::error::expected>;
+
+auto const lhs = value_t{40};
+short const rhs = 2;
+auto const out = mcpplibs::primitives::operations::add(lhs, rhs);
+```
+
+### Operators namespace
+
+```cpp
+using namespace mcpplibs::primitives::operators;
+```
+
+Without this namespace, call function APIs via `mcpplibs::primitives::operations`.
+
+## Next
+
+- Concurrency usage: [./concurrency.md](./concurrency.md)
+- Extension guide: [./extension.md](./extension.md)
+- API reference: [../../api/en/README.md](../../api/en/README.md)
+