docs: align project docs and console-web pre-commit (#100)

Clarify CI vs make pre-commit, service ports, and roadmap status. Standardize scripts and READMEs to English. Translate console module comments to English (no behavior change). Fix console-web lint (eslint .) and Prettier targets via npm scripts and Makefile.

Made-with: Cursor

Author: GatewayJ

.github/AGENTS.md

@@ -19,12 +19,14 @@ Applies to `.github/` and repository pull-request operations.
 
 ## CI Alignment
 
-When changing CI-sensitive behavior, keep local validation aligned with `.github/workflows/ci.yml`.
+When changing CI-sensitive behavior, keep local validation aligned with [`Makefile`](Makefile) at the repo root.
 
-Current `test-and-lint` gate includes:
+**Local bar before push (authoritative for contributors):** `make pre-commit` — runs Rust `fmt-check`, `clippy`, `test`, plus `console-web` lint and Prettier check (see `Makefile`).
 
+**CI workflow** [`.github/workflows/ci.yml`](workflows/ci.yml) `test-and-lint` job currently runs:
+
+- `cargo nextest run --all --no-tests pass` and `cargo test --all --doc`
 - `cargo fmt --all --check`
 - `cargo clippy --all-features -- -D warnings`
-- `cargo test --all`
-- `cd console-web && npm run lint`
-- `cd console-web && npx prettier --check "**/*.{ts,tsx,js,jsx,json,css,md}"`
+
+It does **not** run `console-web` checks; still run **`make pre-commit` locally** before opening a PR so frontend changes are validated.

.github/dependabot.yml

@@ -24,7 +24,7 @@ updates:
       interval: "daily"
   - package-ecosystem: "cargo"
     schedule:
-      interval: "daily" # 这里添加了 schedule
+      interval: "daily"
     directory: "/"
     groups:
       deps:

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Documentation
+
+- Aligned [`CLAUDE.md`](CLAUDE.md) and [`ROADMAP.md`](ROADMAP.md) with current code: Tenant status conditions and StatefulSet updates on the successful reconcile path are documented as implemented; remaining work (status on early errors, integration tests, rollout extras) is listed explicitly.
+- Clarified the documentation map: [`CONTRIBUTING.md`](CONTRIBUTING.md) (quality gates and CI alignment), [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) (environment setup), [`docs/DEVELOPMENT-NOTES.md`](docs/DEVELOPMENT-NOTES.md) (historical notes, not normative).
+- Updated [`examples/README.md`](examples/README.md): Tenant Services document S3 **9000** and RustFS Console **9001**; distinguished the Operator HTTP Console (default **9090**, `cargo run -- console`) from the Tenant `{tenant}-console` Service.
+- Standardized [`README.md`](README.md), [`scripts/README.md`](scripts/README.md), and shell scripts under `scripts/` to English for consistency with architecture and development docs.
+- Translated Rust doc and line comments in [`src/console/`](src/console/) to English (no behavior change).
+
+### Fixed
+
+- **`console-web` / `make pre-commit`**: `npm run lint` now runs `eslint .` (bare `eslint` only printed CLI help). Added `format` / `format:check` scripts; [`Makefile`](Makefile) `console-fmt` and `console-fmt-check` call them so Prettier resolves from `node_modules` after `npm install` in `console-web/`.
+
 ### Added
 
 #### **StatefulSet Reconciliation Improvements** (2025-12-03, Issue #43)

CLAUDE.md

@@ -7,7 +7,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 This is a Kubernetes operator for RustFS, written in Rust using the `kube-rs` library. The operator manages a custom resource `Tenant` (CRD) that provisions and manages RustFS storage clusters in Kubernetes.
 
 **Current Status**: v0.1.0 (pre-release) - Early development, not yet production-ready
-**Test Coverage**: 25 tests, all passing ✅
+**Test Coverage**: 47 library unit tests, all passing ✅ (run `cargo test --all` for current count)
 
 ## Build and Development Commands
 
@@ -31,8 +31,11 @@ cargo run -- crd
 # Generate CRD YAML to file
 cargo run -- crd -f tenant-crd.yaml
 
-# Run the controller (requires Kubernetes cluster access)
+# Run the Kubernetes controller (requires cluster access)
 cargo run -- server
+
+# Run the operator HTTP console API (default port 9090; used by console-web)
+cargo run -- console
 ```
 
 ### Docker
@@ -41,7 +44,7 @@ cargo run -- server
 docker build -t operator .
 ```
 
-Note: The Dockerfile uses a multi-stage build with Rust 1.91-alpine.
+Note: The Dockerfile uses a multi-stage build (`rust:bookworm`, cargo-chef); the final image defaults to `debian:bookworm-slim`.
 
 ### Scripts (deploy / cleanup / check)
 Shell scripts are under `scripts/` and grouped by purpose. Run from project root (scripts will `cd` to project root automatically):
@@ -85,7 +88,7 @@ See `docs/architecture-decisions.md` for detailed ADRs.
 ### Reconciliation Loop
 
 The operator follows the standard Kubernetes controller pattern:
-- **Entry Point**: `src/main.rs` - CLI with two subcommands: `crd` and `server`
+- **Entry Point**: `src/main.rs` - CLI subcommands: `crd`, `server` (controller), `console` (management API)
 - **Controller**: `src/lib.rs:run()` - Sets up the controller that watches `Tenant` resources and owned resources (ConfigMaps, Secrets, ServiceAccounts, Pods, StatefulSets)
 - **Reconciliation Logic**: `src/reconcile.rs:reconcile_rustfs()` - Main reconciliation function that creates/updates Kubernetes resources for a Tenant
 - **Error Handling**: `src/reconcile.rs:error_policy()` - Intelligent retry intervals based on error type:
@@ -170,8 +173,9 @@ The `Tenant` type in `src/types/v1alpha1/tenant.rs` has factory methods for crea
 ### Status Management
 
 - **Status Types**: `src/types/v1alpha1/status/` - Status structures including state, pool status, and certificate status
-- The status is updated via the Kubernetes status subresource
-- **TODO at `reconcile.rs:92`**: Implement comprehensive status condition updates on errors (Ready, Progressing, Degraded)
+- The status is updated via the Kubernetes status subresource (`Context::update_status`, with a single retry on conflict)
+- **Implemented (successful reconcile path)**: Aggregates per-pool StatefulSet status, sets `Ready` / `Progressing` / `Degraded` conditions, overall `current_state`, and pool entries—see `reconcile_rustfs()` in `src/reconcile.rs`
+- **Remaining (Issue #42 follow-up)**: When reconcile returns early with `Err` (e.g. credential/KMS validation, immutable field violations), status is not always updated to reflect that failure; consider setting conditions or state before returning
 
 ### Utilities
 
@@ -188,29 +192,29 @@ The `Tenant` type in `src/types/v1alpha1/tenant.rs` has factory methods for crea
 
 ## Code Structure Notes
 
-- Uses `kube-rs` with specific git revisions for `k8s-openapi` and `kube` crates
+- Uses `kube` and `k8s-openapi` from crates.io (see `Cargo.toml` for versions)
 - Kubernetes version target: v1.30
 - Error handling uses the `snafu` crate for structured error types
 - All files include Apache 2.0 license headers
 - Uses `strum::Display` for enum-to-string conversions (`ImagePullPolicy`, `PodManagementPolicy`, `PoolState`, `State`)
 
 ## Important Dependencies
 
-- **kube** and **k8s-openapi**: Pinned to specific git revisions (not crates.io versions)
-  - TODO: Evaluate migration to crates.io versions
+- **kube** / **k8s-openapi**: Versions pinned in `Cargo.toml` (crates.io)
 - Uses Rust edition 2024
-- Build script (`build.rs`) generates build metadata using the `built` crate
+- Build script (`build.rs`) generates build metadata using the `shadow-rs` crate
 
 ## Known Issues and TODOs
 
 ### High Priority
 - [x] ~~**Secret-based credential management**~~ ✅ **COMPLETED** (2025-11-15, Issue #41)
-- [ ] **Status condition management** (`src/reconcile.rs:92`, Issue #42)
-- [ ] **StatefulSet reconciliation** (`reconcile.rs`) - Creation works, updates need refinement (Issue #43)
-- [ ] **Integration tests** - Only unit tests currently exist
+- [x] ~~**Tenant status conditions on successful reconcile**~~ — `Ready` / `Progressing` / `Degraded`, pool-level status (see `reconcile.rs`)
+- [ ] **Status on reconciliation failures** — Early error returns may not patch Tenant status (Issue #42 follow-up)
+- [ ] **StatefulSet advanced rollout** — Safe updates and validation exist; rollback, richer strategies, and Issue #43 polish remain
+- [ ] **Integration tests** — Only unit tests in-repo today
 
 ### Medium Priority
-- [ ] Status subresource update retry logic improvements
+- [ ] Status subresource update retry beyond single conflict retry (`context.rs`)
 - [ ] TLS certificate rotation automation
 - [ ] Configuration validation enhancements (storage class existence, node selector validity)
 
@@ -220,7 +224,7 @@ The `Tenant` type in `src/types/v1alpha1/tenant.rs` has factory methods for crea
 - **ROADMAP.md** - Development roadmap organized by focus areas (Core Stability, Advanced Features, Enterprise Features, Production Ready)
 - **docs/architecture-decisions.md** - ADRs documenting key architectural decisions
 - **docs/multi-pool-use-cases.md** - Comprehensive guide for multi-pool scenarios
-- **docs/DEVELOPMENT-NOTES.md** - Development workflow and contribution guidelines
+- **docs/DEVELOPMENT-NOTES.md** - Historical analysis and design notes (not the primary dev guide; see `docs/DEVELOPMENT.md` and `CONTRIBUTING.md`)
 
 ## Examples
 
@@ -251,10 +255,8 @@ See `examples/README.md` for comprehensive usage guide.
 ## Development Priorities (from ROADMAP.md)
 
 ### Core Stability (Highest Priority)
-- Secret-based credential management
-- Status condition management (Ready, Progressing, Degraded)
-- StatefulSet update and rollout management
-- Improved error handling and observability
+- Status on failed reconcile paths and stronger status retry
+- StatefulSet rollout polish (rollback, strategies) and observability (metrics)
 - Integration test suite
 
 ### Advanced Features

CONTRIBUTING.md

@@ -1,5 +1,13 @@
 # RustFS Development Guide
 
+## Documentation map
+
+- **This file (`CONTRIBUTING.md`)** — Authoritative for **code quality**, commit workflow, formatting, and alignment with `make pre-commit` and CI. When instructions conflict, prefer this file plus [`Makefile`](Makefile) and [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+- **[`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)** — Local environment setup (Kubernetes, kind, optional tools), IDE hints, and longer workflows. It **does not** redefine the quality gates above; run `make pre-commit` as the single local bar before pushing.
+
+- **[`docs/DEVELOPMENT-NOTES.md`](docs/DEVELOPMENT-NOTES.md)** — Historical design notes and analysis sessions (not a normative spec). For current behavior, use the source tree, [`CHANGELOG.md`](CHANGELOG.md), and [`CLAUDE.md`](CLAUDE.md).
+
 ## 📋 Code Quality Requirements
 
 ### 🔧 Code Formatting Rules
@@ -8,9 +16,9 @@
 
 #### Pre-commit Requirements
 
-Before every commit, you **MUST**:
+Before every commit, you **MUST** pass the same checks as `make pre-commit` (see below). In practice, the steps are:
 
-1. **Format your code**:
+1. **Format your code** (or rely on `make fmt-check` to fail if not formatted):
 
    ```bash
    cargo fmt --all
@@ -25,63 +33,56 @@ Before every commit, you **MUST**:
 3. **Pass clippy checks**:
 
    ```bash
-   cargo clippy --all-targets --all-features -- -D warnings
+   cargo clippy --all-features -- -D warnings
+   ```
+
+4. **Run tests**:
+
+   ```bash
+   cargo test --all
    ```
 
-4. **Ensure compilation**:
+5. **Console (frontend)** — from repo root:
 
    ```bash
-   cargo check --all-targets
+   cd console-web && npm run lint
+   cd console-web && npx prettier --check "**/*.{ts,tsx,js,jsx,json,css,md}"
    ```
 
 #### Quick Commands
 
-We provide convenient Makefile targets for common tasks:
+Targets are defined in [`Makefile`](Makefile). Use these from the **repository root**:
 
 ```bash
-# Format all code
+# Format all Rust code
 make fmt
 
-# Check if code is properly formatted
+# Check Rust formatting (no writes)
 make fmt-check
 
-# Run clippy checks
+# Clippy (Rust)
 make clippy
 
-# Run compilation check
-make check
-
-# Run tests
+# Rust tests
 make test
 
-# Run all pre-commit checks (format + clippy + check + test)
-make pre-commit
+# Frontend: ESLint + Prettier check (requires npm install in console-web/)
+make console-lint
+make console-fmt-check
 
-# Setup git hooks (one-time setup)
-make setup-hooks
+# Full gate before push (Rust + console-web): same as project / AGENTS.md rules
+make pre-commit
 ```
 
-### 🔒 Automated Pre-commit Hooks
-
-This project includes a pre-commit hook that automatically runs before each commit to ensure:
-
-- ✅ Code is properly formatted (`cargo fmt --all --check`)
-- ✅ No clippy warnings (`cargo clippy --all-targets --all-features -- -D warnings`)
-- ✅ Code compiles successfully (`cargo check --all-targets`)
-
-#### Setting Up Pre-commit Hooks
-
-Run this command once after cloning the repository:
+Optional quick compile (not a separate `make` target):
 
 ```bash
-make setup-hooks
+cargo check --all-targets
 ```
 
-Or manually:
+### 🔒 Git hooks (optional)
 
-```bash
-chmod +x .git/hooks/pre-commit
-```
+The repository does **not** ship a `make setup-hooks` target. To run checks automatically on `git commit`, add your own `.git/hooks/pre-commit` that invokes `make pre-commit` (or the individual commands above).
 
 ### 📝 Formatting Configuration
 
@@ -95,11 +96,7 @@ single_line_let_else_max_width = 100
 
 ### 🚫 Commit Prevention
 
-If your code doesn't meet the formatting requirements, the pre-commit hook will:
-
-1. **Block the commit** and show clear error messages
-2. **Provide exact commands** to fix the issues
-3. **Guide you through** the resolution process
+If your code doesn't meet the formatting requirements, CI or local checks will fail with clear messages.
 
 Example output when formatting fails:
 
@@ -148,22 +145,12 @@ Configure your IDE to:
 ### ❗ Important Notes
 
 - **Never bypass formatting checks** - they are there for a reason
-- **All CI/CD pipelines** will also enforce these same checks
-- **Pull requests** will be automatically rejected if formatting checks fail
+- **CI and `make pre-commit`** should stay aligned; see [`Makefile`](Makefile) and [`.github/workflows/ci.yml`](.github/workflows/ci.yml)
+- **Pull requests** may be rejected if checks fail
 - **Consistent formatting** improves code readability and reduces merge conflicts
 
 ### 🆘 Troubleshooting
 
-#### Pre-commit hook not running?
-
-```bash
-# Check if hook is executable
-ls -la .git/hooks/pre-commit
-
-# Make it executable if needed
-chmod +x .git/hooks/pre-commit
-```
-
 #### Formatting issues?
 
 ```bash

Makefile

@@ -56,13 +56,13 @@ test:
 console-lint:
 	cd console-web && npm run lint
 
-# 前端 Prettier 自动格式化
+# 前端 Prettier 自动格式化（需先在 console-web 下 npm install）
 console-fmt:
-	cd console-web && npx prettier --write "**/*.{ts,tsx,js,jsx,json,css,md}"
+	cd console-web && npm run format
 
 # 前端 Prettier 格式检查（仅检查不修改）
 console-fmt-check:
-	cd console-web && npx prettier --check "**/*.{ts,tsx,js,jsx,json,css,md}"
+	cd console-web && npm run format:check
 
 # 构建
 build:

README.md

@@ -1,16 +1,16 @@
 # RustFS Kubernetes Operator
 
-RustFS k8s operator（开发中，尚未可用于生产）。
+RustFS Kubernetes operator (under development; not production-ready).
 
-## 项目结构概览
+## Repository layout
 
-- **scripts/** — 部署/清理/检查脚本（见 [scripts/README.md](scripts/README.md)）
-  - `scripts/deploy/` — 一键部署（Kind + Operator + Tenant）
-  - `scripts/cleanup/` — 资源清理
-  - `scripts/check/` — 集群与 Tenant 状态检查
-- **deploy/** — K8s/Helm 部署清单与 Kind 配置
-  - `deploy/rustfs-operator/` — Helm Chart
-  - `deploy/k8s-dev/` — 开发用 K8s YAML
-  - `deploy/kind/` — Kind 集群配置（如 4 节点）
-- **examples/** — Tenant CR 示例
-- **docs/** — 架构与开发文档
+- **scripts/** — Deploy, cleanup, and check scripts (see [scripts/README.md](scripts/README.md))
+  - `scripts/deploy/` — One-shot deploy (Kind + Operator + Tenant)
+  - `scripts/cleanup/` — Resource cleanup
+  - `scripts/check/` — Cluster and Tenant status checks
+- **deploy/** — Kubernetes / Helm manifests and Kind configs
+  - `deploy/rustfs-operator/` — Helm chart
+  - `deploy/k8s-dev/` — Development Kubernetes YAML
+  - `deploy/kind/` — Kind cluster configs (e.g. 4-node)
+- **examples/** — Sample Tenant CRs
+- **docs/** — Architecture and development documentation