docs

README.md

@@ -8,17 +8,16 @@ enough information for future wrapper generation.
 [![Tests](https://github.com/PyNumLab/x2py/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/PyNumLab/x2py/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/PyNumLab/x2py/graph/badge.svg?token=QZRRCS5YO6)](https://codecov.io/gh/PyNumLab/x2py)
 
-## Documentation Levels
+## Documentation
 
-Use the README for orientation and common commands. Then use the audience
-specific docs when you need detail:
+Use the README for orientation and common commands. Then continue with:
 
-- [User documentation](docs/user.md): more CLI cases, Python API workflows,
-  `.pyi` format, datatype mappings, readiness reports, and user policy
-  responsibilities.
-- [Developer documentation](docs/developer.md): project internals, source
-  ownership, parser/semantic contracts, fixture maintenance, and focused test
-  commands.
+- [Tutorial](docs/tutorial.md): supported end-to-end Fortran and C workflows,
+  semantic `.pyi` editing, readiness, and current limitations.
+- [Verified examples cookbook](docs/examples.md): more CLI commands, compiler
+  preprocessing recipes, Python API examples, and readiness blocker examples.
+- [Developer guide](docs/developper_guide.md): project internals, support
+  evidence rules, source ownership, fixture maintenance, and focused tests.
 - [C parser reference](docs/c_parser.md) and
   [Fortran parser reference](docs/fortran_parser.md): parser-specific coverage,
   behavior, diagnostics, and maintenance notes.
@@ -98,12 +97,14 @@ end module m1
 
 Command:
 
+<!-- x2py-doc-test: exact -->
 ```bash
 python -m x2py tests/data/fortran/general/basic_subroutine.f90 --parse
 ```
 
 Expected output:
 
+<!-- x2py-doc-test-output -->
 ```text
 File: tests/data/fortran/general/basic_subroutine.f90
   Modules: 1
@@ -114,10 +115,12 @@ File: tests/data/fortran/general/basic_subroutine.f90
 
 Generate exact native `.pyi` stubs from the same Fortran file:
 
+<!-- x2py-doc-test: exact -->
 ```bash
 python -m x2py tests/data/fortran/general/basic_subroutine.f90 --pyi
 ```
 
+<!-- x2py-doc-test-output -->
 ```python
 File: tests/data/fortran/general/basic_subroutine.f90
 def add1(
@@ -128,10 +131,12 @@ def add1(
 
 Check readiness for the same Fortran file:
 
+<!-- x2py-doc-test: exact -->
 ```bash
 python -m x2py tests/data/fortran/general/basic_subroutine.f90 --wrap-readiness
 ```
 
+<!-- x2py-doc-test-output -->
 ```text
 File: tests/data/fortran/general/basic_subroutine.f90
   Source: fortran
@@ -163,10 +168,12 @@ void fill_identity3(double a[static 3][3]);
 
 Command:
 
+<!-- x2py-doc-test: exact -->
 ```bash
 python -m x2py tests/data/c/general/math_api.h --language c --parse
 ```
 
+<!-- x2py-doc-test-output -->
 ```text
 File: tests/data/c/general/math_api.h
   Language: c
@@ -183,10 +190,12 @@ File: tests/data/c/general/math_api.h
 
 Generate C `.pyi` stubs from the same header:
 
+<!-- x2py-doc-test: exact -->
 ```bash
 python -m x2py tests/data/c/general/math_api.h --language c --pyi
 ```
 
+<!-- x2py-doc-test-output -->
 ```python
 File: tests/data/c/general/math_api.h
 def norm2(
@@ -213,10 +222,12 @@ def fill_identity3(
 
 Check C readiness for the same header:
 
+<!-- x2py-doc-test: exact -->
 ```bash
 python -m x2py tests/data/c/general/math_api.h --language c --wrap-readiness
 ```
 
+<!-- x2py-doc-test-output -->
 ```text
 File: tests/data/c/general/math_api.h
   Source: c
@@ -230,6 +241,7 @@ File: tests/data/c/general/math_api.h
 
 Generate C semantic IR:
 
+<!-- x2py-doc-test: run -->
 ```bash
 python -m x2py tests/data/c/general/math_api.h --language c --semantics
 ```
@@ -601,7 +613,8 @@ compiler-preprocessed path or build an equivalent preprocessing configuration.
   mapping, and wrap-readiness checks.
 - `x2py/`: package entrypoints, preprocessing, and CLI integration.
 - `tests/`: parser, semantic, CLI, fixture, and property tests.
-- `docs/`: user, developer, parser, semantic, quality, and design references.
+- `docs/`: tutorial, examples, developer, parser, semantic, quality, and
+  design references.
 
 ## Running Tests
 
@@ -612,5 +625,5 @@ PYTHONPATH=. pytest -q
 ```
 
 Focused commands for parser changes, semantic changes, CLI changes, fixture
-regeneration, linting, and coverage are in
-[Developer Documentation](docs/developer.md#testing-map).
+regeneration, linting, and coverage are in the
+[Developer Guide](docs/developper_guide.md#testing-map).

docs/README.md

@@ -1,27 +1,43 @@
 # Documentation
 
-Use the audience-specific entrypoints first:
+Start with:
 
-- [User documentation](user.md): CLI/API usage, parser output, diagnostics,
-  generated `.pyi` files, semantic contracts, and readiness.
-- [Developer documentation](developer.md): parser and semantic implementation
-  references, focused test files, fixture generators, CLI test commands, and
-  maintenance workflows.
+- [Tutorial](tutorial.md): the supported end-to-end user workflow, semantic
+  `.pyi` editing, readiness, and current boundaries.
+- [Verified examples cookbook](examples.md): copy-paste CLI commands, compiler
+  preprocessing recipes, Python API snippets, and blocker examples.
+- [Developer guide](developper_guide.md): implementation ownership, support
+  evidence rules, focused tests, fixture generators, and change workflows.
 
 The repository [`README.md`](../README.md) remains the user-facing project
 overview. Contribution and pull-request requirements remain in
 [`CONTRIBUTING.md`](../CONTRIBUTING.md).
 
-## Reference Files
+## Current Contract References
 
 - [C parser reference](c_parser.md)
 - [Fortran parser reference](fortran_parser.md)
 - [Semantic IR and `.pyi` reference](semantics.md)
-- [Wrapper design notes](wrapper_design_notes.md)
 - [Diagnostic code registry](diagnostic_codes.md)
+
+These files identify implemented, maintained contracts. Any design-only
+material inside them must be labeled explicitly. The tutorial and examples
+should link back to the implemented sections instead of inventing broader
+support claims.
+
+## Maintainer References
+
+- [Developer guide](developper_guide.md)
 - [Quality assurance](quality.md)
+
+## Design Documents
+
+- [Wrapper design notes](wrapper_design_notes.md)
 - [Semantic multilanguage wrapper runtime architecture](architecture/semantic_multilanguage_wrapper_runtime_architecture.md)
 
+Design documents describe deferred or long-term wrapper decisions. They are
+not evidence that runtime wrapper generation is currently implemented.
+
 README files under `tests/` intentionally remain next to the fixtures or
 expected outputs they describe. They are local test-maintenance instructions,
 not general project documentation.

docs/c_parser.md

@@ -22,8 +22,8 @@ guard.
 
 ## Purpose
 
-The C parser frontend will be a wrapper-oriented source extraction system for
-x2py. It should extract enough stable semantic information from C sources and
+The C parser frontend is a wrapper-oriented source extraction system for
+x2py. It extracts stable semantic information from C sources and
 headers to help create or update the semantic interface layer.
 
 The implementation must be grammar-style: lex and slice source into C grammar