docs: reorganize documentation by capability

.agents/docs-and-formatting.md

@@ -6,8 +6,9 @@ Load this file when changing documentation, public APIs, protocol specs, benchma
 
 - `README.md`
 - `CONTRIBUTING.md`
-- `docs/DEVELOPMENT.md`
-- language guides under `docs/guide/`
+- `docs/development/building.md`
+- capability and runtime guides under `docs/object-serialization/`, `docs/row-format/`,
+  `docs/json/`, and `docs/grpc/`
 - `docs/specification/**`
 - `docs/compiler/**`
 
@@ -25,16 +26,18 @@ Load this file when changing documentation, public APIs, protocol specs, benchma
   tables, callouts, or READMEs. Use plain words such as "Supported" or
   "Unsupported" instead.
 - Provide or update working examples when adding new features or materially changing workflows.
-- `docs/DEVELOPMENT.md` plus updates under `docs/guide/` and `docs/benchmarks/` are synced to `apache/fory-site`; other website content should be changed there instead of this repo.
+- The capability-first `docs/` tree is the canonical source for the website documentation,
+  including Introduction and Getting Started.
 - When benchmark logic, scripts, config, or compared serializers change, rerun the relevant benchmarks and refresh the report and plots under `docs/benchmarks/**`.
 - Never manually edit generated code for compiler or IDL outputs; regenerate from the source schema or IDL.
 - Do not treat checked-in benchmark reports as canonical for current numbers. Run the active harness or a source-aligned size check, and match schema, config, and mode before comparing runtimes.
 - Use portable repo-relative or web links in repository docs, not local filesystem paths. Package readmes rendered by external package managers should link to canonical published docs pages when that is the user-facing context.
-- Published `docs/guide/**` pages should prioritize end-user installation and usage flows unless the file is explicitly a contributor or development guide.
-- Keep `docs/guide/**` configuration text user-action focused. Do not put cache ownership,
+- Published capability guides should prioritize end-user installation and usage flows unless the
+  file is explicitly a contributor or development guide.
+- Keep user-facing configuration text action focused. Do not put cache ownership,
   cold/hot path, publish ordering, exact-local schema bypass, or TypeDef/TypeMeta routing
   invariants there; put implementation invariants in `docs/specification/xlang_implementation_guide.md`,
-  security classifications in `docs/security/deserialization.md`, and agent-only workflow rules in
+  security classifications in `docs/object-serialization/deserialization-security-model.md`, and agent-only workflow rules in
   `.agents/**`.
 - Documentation examples should use normal explicit imports, avoid unused imports, and keep common Fory types unqualified where that is the idiom.
 - Generated Markdown under `docs/benchmarks/**` should satisfy markdownlint blank-line rules at generation time: no repeated blank lines and no extra blank line after final content.

.agents/languages/cpp.md

@@ -83,6 +83,6 @@ FORY_CPP_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test -Dtest=org.apache.fo
 
 ## Debugging And Profiling
 
-- See `docs/cpp_debug.md` for C++ debugging guidance.
+- See `docs/development/cpp-debugging.md` for C++ debugging guidance.
 - Generate `compile_commands.json` with `bazel run :refresh_compile_commands`.
 - DTrace-based stack sampling is documented in `CONTRIBUTING.md`.

.agents/repo-reference.md

@@ -19,8 +19,8 @@ Load this file when you need repo layout, protocol context, compiler guidance, o
 - `CLAUDE.md`: compatibility shim that points back to `AGENTS.md`
 - `README.md`: project overview and quick start
 - `CONTRIBUTING.md`: contributor workflow and environment notes
-- `docs/DEVELOPMENT.md`: development setup and build notes
-- `docs/cpp_debug.md`: C++ debugging guidance
+- `docs/development/building.md`: development setup and build notes
+- `docs/development/cpp-debugging.md`: C++ debugging guidance
 - `licenserc.toml`: license header configuration
 
 ## Protocol Overview
@@ -36,10 +36,10 @@ Apache Fory is a multi-language serialization framework with multiple wire forma
 
 - Primary references:
   - `docs/compiler/index.md`
-  - `docs/compiler/compiler-guide.md`
+  - `docs/compiler/cli.md`
   - `docs/compiler/schema-idl.md`
-  - `docs/compiler/type-system.md`
-  - `docs/compiler/generated-code.md`
+  - `docs/compiler/schema-idl.md#type-system`
+  - `docs/compiler/generated-code/index.md`
   - `docs/compiler/protobuf-idl.md`
   - `docs/compiler/flatbuffers-idl.md`
 - Compiler location: `compiler/`

.agents/skills/fory-performance-optimization/references/language-command-matrix.md

@@ -19,7 +19,7 @@ Canonical runtime-specific rules now live under `../../../languages/*.md` and `.
 - Build: `bazel build //cpp/...`
 - Tests: `bazel test $(bazel query //cpp/...)`
 - Perf tests: `bazel test $(bazel query //cpp/fory/serialization/...)`
-- Profile: use repository-approved sampling tooling from `CONTRIBUTING.md` and `docs/cpp_debug.md`
+- Profile: use repository-approved sampling tooling from `CONTRIBUTING.md` and `docs/development/cpp-debugging.md`
 
 ## Java
 

.agents/skills/fory-version-bump/SKILL.md

@@ -78,7 +78,8 @@ python ci/release.py bump_version -l all -version <next-dev-version>
 
 - `README.md`
 - Runtime README files such as `java/README.md`, `rust/README.md`, `scala/README.md`, `csharp/README.md`, `swift/README.md`, `dart/packages/fory/README.md`
-- `docs/guide/**`
+- `docs/start/**` and `docs/object-serialization/**`
+- `docs/row-format/**`, `docs/json/**`, and `docs/grpc/**`
 - `docs/compiler/**` when compiler examples include Fory package versions
 - `examples/**`
 

.github/sync.yml

@@ -16,17 +16,38 @@
 # under the License.
 
 apache/fory-site@main:
-  - source: docs/DEVELOPMENT.md
-    dest: docs/community/DEVELOPMENT.md
-  - source: docs/guide/
-    dest: docs/guide/
+  - source: docs/index.md
+    dest: docs/index.md
+  - source: docs/introduction/
+    dest: docs/introduction/
     deleteOrphaned: true
-  - source: docs/specification/
-    dest: docs/specification/
+  - source: docs/start/
+    dest: docs/start/
+    deleteOrphaned: true
+  - source: docs/benchmarks/
+    dest: docs/benchmarks/
+    deleteOrphaned: true
+  - source: docs/object-serialization/
+    dest: docs/object-serialization/
+    deleteOrphaned: true
+  - source: docs/row-format/
+    dest: docs/row-format/
+    deleteOrphaned: true
+  - source: docs/json/
+    dest: docs/json/
     deleteOrphaned: true
   - source: docs/compiler/
     dest: docs/compiler/
     deleteOrphaned: true
-  - source: docs/benchmarks/
-    dest: docs/benchmarks/
+  - source: docs/grpc/
+    dest: docs/grpc/
+    deleteOrphaned: true
+  - source: docs/development/
+    dest: docs/development/
+    deleteOrphaned: true
+  - source: docs/images/
+    dest: docs/images/
+    deleteOrphaned: true
+  - source: docs/specification/
+    dest: docs/specification/
     deleteOrphaned: true

AGENTS.md

@@ -9,10 +9,11 @@ This is the entry point for AI guidance in Apache Fory. Read this file first, th
 - `.agents/docs-and-formatting.md`: documentation, specification, and markdown rules.
 - `.agents/ci-and-pr.md`: code review workflow, CI triage, PR expectations, and commit conventions.
 - `.agents/testing/integration-tests.md`: `integration_tests/` prerequisites, regeneration rules, and commands.
-- `docs/security/index.md`: security model index.
-- `docs/security/threat-model.md`: project-level trust boundaries, non-goals,
-  and downstream responsibilities.
-- `docs/security/deserialization.md`: security boundaries for untrusted deserialization classification.
+- `docs/object-serialization/security.md`: user-facing security guidance for binary object
+  serialization.
+- `docs/json/security.md`: user-facing security guidance for Fory JSON.
+- `docs/object-serialization/deserialization-security-model.md`: implementation boundaries for
+  untrusted deserialization classification.
 - `.agents/languages/java.md`
 - `.agents/languages/csharp.md`
 - `.agents/languages/cpp.md`
@@ -33,7 +34,7 @@ This is the entry point for AI guidance in Apache Fory. Read this file first, th
 - Respect ownership. Keep logic, state, and helpers in their natural owner, and do not move serializer-local, context-local, runtime-type-local, or protocol-local problems into global utilities.
 - Check the spec before implementation. For wire behavior and xlang mapping, use the specs as the source of truth and never copy one runtime's bug into another runtime just to make tests pass.
 - Do not make assumptions about runtime behavior, ownership, registration, metadata construction, protocol semantics, or test coverage. Read the current code, owning docs/specs, and relevant tests before making a design judgment or implementation decision. If the evidence is incomplete, inspect more or state the uncertainty explicitly instead of filling gaps from memory or analogy with another runtime.
-- For untrusted deserialization, read `docs/security/deserialization.md` before changing allocation, stream filling, skip, reference, metadata, or policy validation behavior. Variable-length deserialization must not allocate or reserve backing/output capacity from attacker-declared lengths or counts before the byte owner has proven proportional readable bytes with `checkReadableBytes` or the runtime equivalent. Root graph memory reservation is accounting only and may happen before that byte check, but it must not replace the byte check.
+- For untrusted deserialization, read `docs/object-serialization/deserialization-security-model.md` before changing allocation, stream filling, skip, reference, metadata, or policy validation behavior. Variable-length deserialization must not allocate or reserve backing/output capacity from attacker-declared lengths or counts before the byte owner has proven proportional readable bytes with `checkReadableBytes` or the runtime equivalent. Root graph memory reservation is accounting only and may happen before that byte check, but it must not replace the byte check.
 - Malformed input must surface as a controlled root-operation error and still run
   root cleanup, but the exact exception type, error code, message, detection
   layer, and detection point are not contracts unless a public API or
@@ -164,7 +165,8 @@ This is the entry point for AI guidance in Apache Fory. Read this file first, th
 
 ## Design Integrity Gates
 
-- Record all core design and decisions in the owning docs when they belong there, especially under `docs/guide/**` or `docs/specification/**`.
+- Record all core design and decisions in the owning docs when they belong there, especially under
+  `docs/object-serialization/**`, the relevant capability directory, or `docs/specification/**`.
 - Do not allow implementation drift from the design document.
 - Do not compromise design decisions to make implementation easier.
 - Do not leave workaround code behind.
@@ -220,10 +222,12 @@ This is the entry point for AI guidance in Apache Fory. Read this file first, th
 
 ## Source of Truth
 
-- Primary references: `README.md`, `CONTRIBUTING.md`, `docs/DEVELOPMENT.md`, and language guides under `docs/guide/`.
+- Primary references: `README.md`, `CONTRIBUTING.md`, `docs/development/building.md`, and the
+  capability-first documentation under `docs/`.
 - Protocol changes require reading and updating the relevant specs in `docs/specification/**` and aligning the relevant cross-language tests.
 - If instructions conflict, follow the most specific module docs and call out the conflict.
-- `docs/DEVELOPMENT.md` plus updates under `docs/guide/` and `docs/benchmarks/` are synced to `apache/fory-site`; other website content belongs there.
+- The `docs/` tree is the canonical source for the website's Introduction, Getting Started,
+  Benchmarks, capability guides, development guides, and separate Specification surface.
 - When benchmark logic, scripts, configuration, or compared serializers change, rerun the relevant benchmarks and refresh the artifacts under `docs/benchmarks/**`.
 
 ## Shared Engineering Expectations
@@ -327,8 +331,7 @@ This is the entry point for AI guidance in Apache Fory. Read this file first, th
 
 ## Security
 
-Security models start at `docs/security/index.md`. Read
-`docs/security/threat-model.md` for project-level trust boundaries, non-goals,
-and downstream responsibilities. For untrusted deserialization, read
-`docs/security/deserialization.md` before reporting or changing allocation,
-stream filling, skip, reference, metadata, or policy validation behavior.
+User-facing security guidance lives only under Object Serialization and Fory JSON. Read
+`docs/object-serialization/security.md` or `docs/json/security.md` for the selected product. Before
+reporting or changing allocation, stream filling, skip, reference, metadata, or policy validation
+behavior, read `docs/object-serialization/deserialization-security-model.md`.

CONTRIBUTING.md

@@ -42,7 +42,7 @@ Key points:
 
 ## Testing
 
-For environmental requirements, please check [DEVELOPMENT.md](./docs/DEVELOPMENT.md).
+For environmental requirements, please check [DEVELOPMENT.md](./docs/development/building.md).
 
 ### Python
 
@@ -182,7 +182,7 @@ cygdb build
 
 ### C++
 
-See the [Debugging C++](docs/cpp_debug.md) doc.
+See the [Debugging C++](docs/development/cpp-debugging.md) guide.
 
 ### Debug Crash
 
@@ -236,10 +236,12 @@ And due to the usage of `sun.misc.Unsafe` API, which is not visible in Java 11+,
 
 Apache Fory™'s website consists of static pages hosted at https://github.com/apache/fory-site.
 
-Updates to [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md), docs under [guide](docs/guide), and docs under [benchmarks](docs/benchmarks) will be synced to the site repo automatically.
+The capability-first [docs](docs) tree is the canonical source for the website documentation,
+including Introduction, Getting Started, Benchmarks, user guides, Development, and the separate
+Specification surface.
 
 If you want write a blog, or update other contents about the website, please submit PR to the site repo.
 
 ## Development
 
-For more information, please refer to [Development Guide](./docs/DEVELOPMENT.md).
+For more information, please refer to [Development Guide](./docs/development/building.md).