improve docs

Author: saidctb

docs/index.md

@@ -1,5 +1,6 @@
 ---
 title: x2py
+description: Turn Fortran into importable Python extensions with zero boilerplate
 audience: users
 prerequisites: none
 related: user/getting-started/index.md, user/getting-started/installation.md
@@ -9,14 +10,16 @@ publication: reviewed
 
 # x2py
 
-x2py turns supported Fortran source into an importable Python extension. It
-also exposes the parsed interface as language-neutral semantic IR and editable
-`.pyi` contracts, so unsupported boundaries are reported before wrapper code is
-compiled.
+**x2py turns supported Fortran source into fast, importable Python extensions.**
 
-## Try x2py
+It also generates a language-neutral semantic IR and editable `.pyi`
+contracts, so unsupported boundaries are reported before wrapper compilation.
 
-This first example wraps a scalar Fortran function. Create `scale.f90`:
+---
+
+## Try it in 30 seconds {#try-x2py}
+
+Create a file `scale.f90`:
 
 <!-- x2py-doc-source: tests/data/fortran/wrapper/scale.f90 -->
 ```fortran
@@ -27,41 +30,28 @@ real(8) function scale(value, factor) result(output)
 end function scale
 ```
 
-Build the Python extension from the directory containing that file:
+Build the Python extension:
 
 ```bash
 python3 -m x2py scale.f90
 ```
 
-The command creates an importable `scale` extension beside the source and keeps
-its generated wrapper and build artifacts under `__x2py__/`. Call the native
-function from Python with the exact NumPy scalar types required by its
-contract:
+Use it from Python:
 
 ```python
 import numpy as np
-
 import scale
 
 result = scale.scale(np.float64(3.0), np.float64(2.5))
-print(result)
+print(result)        # 7.5
 ```
 
-The call prints:
-
-```text
-7.5
-```
-
-The generated function is inspectable from Python:
+Inspect the generated contract:
 
 ```python
 print(scale.scale.__doc__)
 ```
 
-Its docstring describes the public signature, accepted dtypes, result, and
-call-time type error:
-
 ```text
 scale(value, factor) -> float64
 
@@ -80,12 +70,35 @@ TypeError
     If an argument has an incompatible Python type or dtype.
 ```
 
-That is the basic x2py workflow: provide native source, build an extension,
-import it, and call the generated Python surface.
+---
+
+## How it works
 
-## Continue With Getting Started
+1. You write standard Fortran
+2. `x2py` parses the interface and generates a compact native wrapper
+3. It produces a Python extension module and editable semantic `.pyi` contracts
+4. You get full NumPy scalar dtype safety and clear error messages
+
+No manual `f2py` signatures. No low-level boilerplate.
+
+## Next steps
+
+[Getting Started](user/getting-started/index.md){ .md-button .md-button--primary }
+
+This guide walks you through installation, compiler setup, and a deeper look at the generated artifacts.
+
+---
+
+## Features
+
+- Automatic generation of Python extensions from Fortran
+- Language-neutral semantic IR
+- Editable `.pyi` type stubs
+- Strict NumPy dtype checking at call time
+- Clean, readable `__doc__` strings
+- Build artifacts isolated in `__x2py__/`
+
+---
 
-This preview assumes x2py, NumPy, and a supported native compiler are already
-available. [Getting Started](user/getting-started/index.md) walks through
-installation and verification first, then rebuilds this function and explains
-its generated contract and artifacts.
+**Ready to wrap your Fortran code?**
+Start with the [Getting Started](user/getting-started/index.md) guide.

docs/maintainer/documentation-architecture.md

@@ -23,14 +23,16 @@ contains only pages explicitly marked as reviewed.
    lane: a draft lane index prevents every page below that lane from entering
    the production site, even when an individual child page is marked reviewed.
 3. Implemented behavior is documented as supported only when current code and
-   tests prove it.
+   tests prove it. Public user pages describe behavior and limits without
+   exposing internal test-evidence ledgers.
 4. Planned behavior is marked explicitly and never presented as an implemented
    user contract.
 5. Maintainer policy and volatile internals do not appear in user workflows.
 6. Historical material remains under `old_docs/` and outside active navigation.
 7. User-facing source-driven examples show the complete input source before the
    command that consumes it. Generated paths must come from an immediately
-   preceding command, and commands show their expected result.
+   preceding command, and commands show their expected result. Fixture-backed
+   examples stay synchronized with their checked source.
 8. The website keeps its documentation navigation expanded and renders an
    accessible copy control on every code block, including command-output and
    result blocks.
@@ -66,8 +68,14 @@ the reader is leaving the current lane.
 The `nav` sequence in `mkdocs.yml` is the canonical reading order. Sequential
 User documentation pages may link back to pages the reader has already
 completed. They must not link from instructional prose to a later page in that
-sequence. Name the later topic in plain text and say that it is covered later
-instead of asking the reader to leave the current task.
+sequence. Explicit terminal navigation blocks headed `Next` may link forward
+because choosing a next destination is their purpose. Outside those blocks,
+name the later topic in plain text and say that it is covered later instead of
+asking the reader to leave the current task.
+`Next` blocks list destinations as bullets, and each bullet includes at least
+one Markdown link. If an intended destination page does not exist yet, either
+remove the destination until it is useful or create the draft page with
+metadata and a TODO section.
 
 Each page includes the behavior, warning, ownership fact, or limitation needed
 for its current task. A forward reference never defers a fact needed now.
@@ -104,14 +112,13 @@ as `draft`. Production builds include a Markdown page only when:
 
 The publication hook removes every other Markdown page from the MkDocs file
 collection and navigation before rendering, so drafts do not enter generated
-HTML, search, or the sitemap. When a reviewed index or overview mentions a
-draft page, the production build renders that page name as plain text until the
-target becomes publishable. Links to existing repository evidence outside the
-`docs/` tree are rewritten to the matching file or directory on GitHub; links
-to missing targets remain unchanged so the strict build can reject them. Links
-to another active documentation page or directory must stay relative to
-`docs/` and resolve inside the website. The hook never rewrites a target inside
-`docs/` to GitHub.
+HTML, search, or the sitemap. When a reviewed page mentions an unpublished
+documentation page, the production build keeps the link visible with its
+expected website route even though the target page itself is not published.
+Links to existing repository evidence outside the `docs/` tree are rewritten to
+the matching file or directory on GitHub; links to missing targets remain
+unchanged so the strict build can reject them. Links to another active
+documentation page or directory must stay relative to `docs/`.
 
 Use the normal local server to preview exactly what GitHub Pages will publish:
 

docs/maintainer/roadmap/documentation-content-checklist.md

@@ -25,14 +25,14 @@ these are true:
 - [ ] The page status is accurate: `maintained` for current public behavior,
   `design` for accepted architecture, or `not-yet-implemented` for explicit
   future behavior.
-- [ ] The page explains what is supported now, what is unsupported, and where to
-  find the supporting tests, fixtures, examples, or source owner.
+- [ ] The page explains what is supported now and what is unsupported without
+  exposing internal test-evidence ledgers in public user-facing prose.
 - [ ] User-facing pages include a task-oriented workflow, expected output or API
   shape, limitations, and troubleshooting links.
 - [ ] Developer-facing pages include ownership boundaries, source routes,
   focused verification commands, and rules for updating related docs.
-- [ ] Examples are either executable documentation examples, checked fixtures,
-  or clearly labeled illustrative snippets.
+- [ ] Examples are polished, copyable, and internally coherent. Executable
+  examples and fixture-backed source stay synchronized with their checks.
 - [ ] Reuse earlier examples by reference instead of reprinting them, unless the
   page must be self-contained for a first-time user task.
 - [ ] User-facing examples use clean copyable filenames and module names; keep

docs/maintainer/roadmap/native-array-handle-checklist.md

@@ -649,16 +649,14 @@ specialize operation bodies by descriptor kind.
   stable owner storage.
 - [x] Use wrapper-owned standard C descriptor storage for allocatable results:
   allocate persistent rank-specific `CFI_CDESC_T(rank)` storage and establish
-  it with allocatable attribute. Numeric function results populate local
-  allocatable storage whose allocation is transferred with `move_alloc`;
-  generated shape-changing operations use `CFI_allocate`.
-- [x] Assign a numeric direct allocatable function result once into a
+  it with allocatable attribute. Numeric function results populate a local
+  allocatable once, then transfer that allocation with `move_alloc`; generated
+  shape-changing operations use `CFI_allocate`.
+- [x] Assign a supported numeric direct allocatable function result once into a
   bridge-local allocatable, then `move_alloc` that allocation into the
   allocatable `intent(out)` dummy backed by persistent CFI storage. Do not
-  generate a collector, an `allocated(...)` guard, or a second intrinsic
-  assignment. The native function must return an allocated, defined result; an
-  unallocated nonpointer result is a nonconforming native procedure and remains
-  the user's responsibility.
+  generate a collector or a second intrinsic assignment. Rank-one, matrix, and
+  higher-rank results preserve allocated, zero-sized, and unallocated state.
 - [x] Return a native pointer to owner storage for owned allocatable handles.
 - [x] Generate destroy routines called by the Python handle finalizer for owned
   allocatable handles.

docs/maintainer/roadmap/wrapper-plan-migration-checklist.md

@@ -594,7 +594,7 @@ summary, the exhaustive matrix, and the test tree disagree.
 
 | Status | Collected nodes |
 | --- | ---: |
-| `wrapper-plan` | 353 |
+| `wrapper-plan` | 357 |
 | `dual-route` | 0 |
 | `legacy` | 0 |
 | `not-applicable` | 76 |
@@ -2610,30 +2610,27 @@ Legacy oracle:
 
 ### Phase 7E — Owned Allocatable Results And Hidden Outputs
 
-Included: rank-positive allocatable direct function results and hidden output
-descriptors whose completed policy selects `owned_result_descriptor`. A valid
-allocatable function result is allocated when returned; an unallocated
-nonpointer function result is a nonconforming native procedure and the wrapper
-does not compensate for it. An allocatable output dummy may validly remain
-unallocated and still returns a present `AllocatableArray` handle whose state
-lives inside that handle. Pointer handle results remain blocked until stable
-owner storage and target lifetime are explicit.
-
-For a numeric direct allocatable function result, the bridge assigns the native
-function expression once into a procedure-local allocatable and then uses
-`move_alloc` to transfer that allocation into the allocatable `intent(out)`
-dummy backed by persistent wrapper-owned `CFI_CDESC_T(rank)` storage. The move
-does not copy the array payload. Do not insert a collector helper, an
-`allocated(...)` guard, or a second intrinsic assignment. The native function
-must return an allocated, defined result; an unallocated result is a
-nonconforming native procedure and remains the user's responsibility rather
-than a wrapper fallback. Other procedure-local storage remains permitted only
-when representation conversion genuinely requires it, such as
-deferred-character byte materialization. The binding constructs the complete
-generated operation table and Python handle only after owner storage is valid.
-Ownership transfers to the handle exactly once; every earlier failure path
-releases the persistent allocation and any genuinely required bridge-local
-allocation.
+Included: allocatable array direct function results and hidden output
+descriptors whose completed policy selects `owned_result_descriptor`.
+Direct array results preserve allocated, zero-sized, and unallocated state,
+including matrices and higher-rank arrays. An allocatable output dummy may
+validly remain unallocated and still returns a present `AllocatableArray` handle
+whose state lives inside that handle. Pointer handle results remain blocked
+until stable owner storage and target lifetime are
+explicit.
+
+For a supported numeric direct allocatable function result, the bridge assigns
+the native function expression once into a procedure-local allocatable and then
+uses `move_alloc` to transfer its state into the allocatable `intent(out)` dummy
+backed by persistent wrapper-owned `CFI_CDESC_T(rank)` storage. The move does
+not copy the array payload and preserves an unallocated rank-one result. Do not
+insert a collector helper or a second intrinsic assignment. Other
+procedure-local storage remains permitted only when representation conversion
+genuinely requires it, such as deferred-character byte materialization. The
+binding constructs the complete generated operation table and Python handle
+only after owner storage is valid. Ownership transfers to the handle exactly
+once; every earlier failure path releases persistent storage and any genuinely
+required bridge-local allocation.
 
 Character-element handles carry runtime `elem_len` and declared element-length
 policy in the same descriptor record. Because a deferred character width is
@@ -4431,8 +4428,8 @@ existing source/generated-`.pyi` runtime assertions are the behavioral oracle.
 | `callbacks/test_array_callbacks.py::test_immediate_dummy_procedure_converts_array_arguments_and_results[*]` | writable array view, shaped array result, outer-output identity, and reference writeback | array argument/result slice |
 | `callbacks/test_all_callback_shapes.py::test_immediate_callbacks_cover_all_supported_argument_shapes[*]` | scalar values, fixed strings, arrays, derived values, non-scalar reference writeback, and one combined call envelope | cross-kind closure slice |
 | `callbacks/test_derived_callbacks.py::test_immediate_dummy_procedure_converts_derived_arguments_and_results[*]` | callback-local borrowed derived input plus wrapper-owned derived result conversion | derived slice after Phase 9 construction |
-| `callbacks/test_callback_generated_pyi_contracts.py` | named prototypes, reference-default and `Value(T)` transport, shape, character storage, cross-module identity, and result annotations round-trip exactly | semantic-contract parity slice |
-| `semantics/conversion/pyi/test_types_and_values.py` callback cases | prototype declarations and references, `Value(T)`, exact argument names used by shapes, and unnecessary `Addr(...)` prototype forms | policy completion before planner work |
+| `callbacks/test_callback_generated_pyi_contracts.py` | named prototypes, primitive value defaults, explicit primitive `Addr(T)` references, non-primitive `Value(T)` transport, shape, character storage, cross-module identity, and result annotations round-trip exactly | semantic-contract parity slice |
+| `semantics/conversion/pyi/test_types_and_values.py` callback cases | prototype declarations and references, primitive `Addr(T)`, non-primitive `Value(T)`, exact argument names used by shapes, and invalid prototype transport forms | policy completion before planner work |
 
 ### Phase 10 Plan Shape And Action Vocabulary
 
@@ -4504,12 +4501,13 @@ For every dependency-closed sub-lane:
   call scope, context lifetime, same-thread rule, GIL rule, cleanup, and
   fatal-error behavior.
 - [x] Preserve generated and edited named prototypes exactly. Reject an
-  incomplete prototype reference, unnecessary `Addr`, optional procedure,
+  incomplete prototype reference, invalid prototype `Addr`, optional procedure,
   stored/procedure-pointer lifetime, unavailable mandatory native interface,
   or unsupported result with the owner path and one exact reason.
 - [x] Complete callback signature/result/ownership policy before wrapper
   planning; lowering may only project the completed callback record.
-- [x] Add policy/planning tests for reference-default transport, `Value(T)`,
+- [x] Add policy/planning tests for primitive value defaults, explicit
+  primitive `Addr(T)` references, non-primitive `Value(T)`,
   and retained unsupported forms before planner changes.
 
 ### Phase 10B — Typed Callback Plan And Validation

docs/user/examples/verified-cookbook.md

@@ -15,8 +15,8 @@ uses checked repository fixtures where the command output is stable.
 Start with the [basic wrapper tutorial](../tutorials/basic-wrapper.md) if this
 is your first x2py workflow. Use the
 [Fortran wrapper guide](../guide/fortran-wrapper.md) for the full runtime
-contract and [Semantic .pyi Format](../reference/semantic-pyi-format.md) for
-editable wrapper contracts.
+contract. The Semantic .pyi Format reference gives the complete editable
+wrapper contract syntax.
 
 ## Choose A Recipe
 
@@ -65,6 +65,6 @@ X2PY_C_DOCS_END -->
 
 - [Basic wrapper tutorial](../tutorials/basic-wrapper.md)
 - [Fortran wrapper guide](../guide/fortran-wrapper.md)
-- [Semantic .pyi Format](../reference/semantic-pyi-format.md)
-- [Semantic IR Reference](../reference/semantic-ir.md)
-- [Diagnostic Codes](../reference/diagnostic-codes.md)
+- Semantic .pyi Format
+- Semantic IR Reference
+- Diagnostic Codes