docs: add in-repository documentation in doc/ and link from README

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## 📋 Code Quality Requirements
 
-For instructions on setting up and running the local development environment, please see [Development Guide](docs/DEVELOPMENT.md).
+For instructions on setting up and running the local development environment, please see [Development Guide](doc/development.md).
 
 ### 🔧 Code Formatting Rules
 

README.md

@@ -208,7 +208,8 @@ nix run
 
 ## Documentation
 
-For detailed documentation, including configuration options, API references, and advanced usage, please visit our [Documentation](https://docs.rustfs.com).
+- **[In-repository docs](doc/)** — Architecture, development guide, and configuration overview (this repo).
+- **[RustFS Documentation](https://docs.rustfs.com)** — Full manual, installation, configuration options, API reference, and advanced usage.
 
 ## Getting Help
 
@@ -220,6 +221,7 @@ If you have any questions or need assistance:
 
 ## Links
 
+- [In-repository documentation](doc/) - Architecture, development, and configuration (this repo)
 - [Documentation](https://docs.rustfs.com) - The manual you should read
 - [Changelog](https://github.com/rustfs/rustfs/releases) - What we broke and fixed
 - [GitHub Discussions](https://github.com/rustfs/rustfs/discussions) - Where the community lives

doc/README.md

@@ -0,0 +1,18 @@
+# RustFS Project Documentation
+
+This folder contains in-repository documentation for the RustFS project. For the full user manual, installation, and API reference, see the official [RustFS Documentation](https://docs.rustfs.com).
+
+## Contents
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](architecture.md) | High-level design, components, and workspace layout |
+| [Development](development.md) | Building, testing, and contributing (Make targets, pre-commit) |
+| [Configuration](configuration.md) | Configuration overview and environment variables |
+
+## Quick Links
+
+- **Getting started (users)**: [docs.rustfs.com/installation](https://docs.rustfs.com/installation/)
+- **Full docs**: [docs.rustfs.com](https://docs.rustfs.com)
+- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md) and [doc/development.md](development.md)
+- **CI and quality**: [.github/workflows/ci.yml](../.github/workflows/ci.yml), [Makefile](../Makefile)

doc/architecture.md

@@ -0,0 +1,35 @@
+# Architecture
+
+RustFS is a high-performance, distributed object storage system built in Rust with full S3 compatibility. This document summarizes the in-repository layout and main components.
+
+## Overview
+
+- **Core binary**: The `rustfs` crate is the main application (API, console, storage orchestration).
+- **Workspace**: All shared logic lives in crates under `crates/`; see the root [Cargo.toml](../Cargo.toml) `[workspace].members` for the full list.
+
+## Main Components
+
+| Area | Crates | Purpose |
+|------|--------|---------|
+| **Core** | `rustfs` | Main server binary, S3 API, admin console, storage coordination |
+| **Config** | `rustfs-config` | Configuration and environment variable handling |
+| **Storage** | `rustfs-ecstore`, `rustfs-filemeta`, `rustfs-targets` | Erasure coding, metadata, target backends |
+| **Auth & IAM** | `rustfs-appauth`, `rustfs-iam`, `rustfs-credentials`, `rustfs-keystone` | Authentication, policies, Keystone integration |
+| **Security** | `rustfs-crypto`, `rustfs-kms` | Cryptography and key management |
+| **Operations** | `rustfs-heal`, `rustfs-scanner`, `rustfs-audit` | Healing, scanning, audit targets |
+| **Observability** | `rustfs-metrics`, `rustfs-obs`, `rustfs-notify` | Metrics, tracing, event notifications |
+| **Protocols** | `rustfs-protocols`, `rustfs-s3select-api`, `rustfs-s3select-query` | FTPS/SFTP, S3 Select |
+| **Utilities** | `rustfs-common`, `rustfs-utils`, `rustfs-rio`, `rustfs-workers` | Shared types, I/O, worker pools |
+
+The root [Cargo.toml](../Cargo.toml) is the source of truth for crate names and membership.
+
+## Scoped Guidance
+
+Path-specific rules for contributors and tooling are in `AGENTS.md` files:
+
+- [.github/AGENTS.md](../.github/AGENTS.md)
+- [crates/AGENTS.md](../crates/AGENTS.md)
+- [crates/config/AGENTS.md](../crates/config/AGENTS.md)
+- Additional scoped files under `crates/`, `rustfs/src/admin/`, and `rustfs/src/storage/`
+
+See the root [AGENTS.md](../AGENTS.md) for precedence and mandatory pre-commit checks.

doc/configuration.md

@@ -0,0 +1,24 @@
+# Configuration Overview
+
+RustFS is configured via environment variables. This page gives an overview; the canonical source of truth is the `rustfs-config` crate.
+
+## Environment Variables
+
+- **Naming**: Use flat `RUSTFS_*` names (e.g. `RUSTFS_REGION`, `RUSTFS_ADDRESS`, `RUSTFS_VOLUMES`). Do not use module-segmented names like `RUSTFS_CONFIG_*`.
+- **Constants and conventions**: See [crates/config/src/constants/](../crates/config/src/) and [crates/config/README.md](../crates/config/README.md) (including environment variable naming).
+
+## Key Variables (examples)
+
+| Variable | Purpose |
+|----------|---------|
+| `RUSTFS_REGION` | Deployment region |
+| `RUSTFS_ADDRESS` | Server address |
+| `RUSTFS_VOLUMES` | Storage volumes |
+| `RUSTFS_SCANNER_ENABLED` | Enable scanner |
+| `RUSTFS_HEAL_ENABLED` | Enable healing |
+
+Deprecated aliases are documented in [crates/config/README.md](../crates/config/README.md); compatibility behavior is maintained there.
+
+## Full Configuration Reference
+
+For all options, defaults, and deployment guides (including TLS and Keystone), use the official [RustFS Documentation](https://docs.rustfs.com).

doc/development.md

@@ -0,0 +1,64 @@
+# Development Guide
+
+This page covers building, testing, and running quality checks for RustFS. For code formatting rules and PR expectations, see [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Prerequisites
+
+- Rust (see root [Cargo.toml](../Cargo.toml) `rust-version`)
+- For full quality gates: `make` (see [.config/make/](../.config/make/) and root [Makefile](../Makefile))
+
+## Build
+
+```bash
+# Build the RustFS binary
+make build
+# or
+cargo build --release
+```
+
+## Testing
+
+```bash
+# Run tests
+make test
+# or
+cargo test --all-targets
+```
+
+## Code Quality (Mandatory Before Commit)
+
+Run all pre-commit checks:
+
+```bash
+make pre-commit
+```
+
+If `make` is unavailable, run the equivalent steps from [.config/make/](../.config/make/). Typical steps:
+
+- Format: `cargo fmt --all` and `cargo fmt --all --check`
+- Lint: `cargo clippy --all-targets --all-features -- -D warnings`
+- Check: `cargo check --all-targets`
+- Tests: `cargo test --all-targets`
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed formatting and clippy rules.
+
+## Make Targets
+
+- `make help` — Main help and categories
+- `make help-build` — Build-related targets
+- `make help-docker` — Docker and image targets
+- `make fmt` / `make fmt-check` — Format and verify
+- `make clippy` — Clippy
+- `make check` — Compilation check
+- `make test` — Tests
+- `make pre-commit` — All checks required before commit
+
+## CI
+
+Quality gates are defined in [.github/workflows/ci.yml](../.github/workflows/ci.yml). Keep local checks aligned with CI so `make pre-commit` matches what runs on the branch.
+
+## Branch and PR Baseline
+
+- Use feature branches from latest `main`.
+- Follow [Conventional Commits](https://www.conventionalcommits.org/), subject ≤ 72 characters.
+- Use [.github/pull_request_template.md](../.github/pull_request_template.md) for PRs; use `N/A` for non-applicable sections.