update docs

Author: saidctb

docs/developer/source-map.md

@@ -44,7 +44,7 @@ change crosses ownership boundaries.
 | Wrapper-planning errors and support claims | `x2py/semantics/policy_completion.py`, `x2py/wrapper_codegen/planner.py` | `docs/user/reference/diagnostic-codes.md`, `docs/user/language-support/feature-matrix.md` | `tests/semantics/policy/`, `tests/wrapper_codegen/` |
 | Source-driven Fortran wrapper orchestration | `x2py/pipeline/build.py` | `docs/user/reference/fortran-wrapper.md`, `docs/user/guide/building-shared-library.md` | `tests/wrapper/fortran/build_from_source/test_build_modes.py`, `tests/wrapper/fortran/multiple_files/test_multi_source_builds.py` |
 | Semantic `.pyi` wrapper orchestration from native artifacts | `x2py/pipeline/build.py`, `x2py/pipeline/pyi.py`, `x2py/semantics/pyi2ir.py` | `docs/user/reference/fortran-wrapper.md`, `docs/user/reference/semantic-pyi-format.md` | `tests/wrapper/fortran/build_from_pyi/test_pyi_wrapper_builds.py`, `tests/wrapper/fortran/build_from_pyi/test_contract_package_runtime.py` |
-| Ownership, lifetime, output projection, and unsupported wrapper policy | `x2py/semantics/policy_completion.py`, `x2py/semantics/ownership.py`, `x2py/wrapper_codegen/planner.py` | `docs/user/reference/fortran-wrapper.md`, `docs/user/reference/pyi-contracts/ownership-and-lifetimes.md` | `tests/semantics/policy/`, `tests/wrapper_codegen/`, `tests/wrapper/fortran/` |
+| Ownership, lifetime, output projection, and unsupported wrapper policy | `x2py/semantics/policy_completion.py`, `x2py/semantics/ownership.py`, `x2py/wrapper_codegen/planner.py` | `docs/user/guide/memory-management.md`, `docs/user/reference/semantic-pyi-format.md`, `docs/user/reference/fortran-wrapper.md` | `tests/semantics/policy/`, `tests/wrapper_codegen/`, `tests/wrapper/fortran/` |
 | Immediate callback policy, typed adapters, and trampolines | `x2py/semantics/wrapper_policy.py`, `x2py/semantics/policy_completion.py`, `x2py/wrapper_codegen/plan.py`, `x2py/wrapper_codegen/planner.py`, `x2py/wrapper_codegen/c/binding.py`, `x2py/wrapper_codegen/fortran/bridge.py` | `docs/user/guide/callbacks.md`, `docs/user/reference/semantic-pyi-format.md` | `tests/wrapper_codegen/test_phase10_callbacks.py`, `tests/wrapper/fortran/callbacks/` |
 | Native compilation, binding support, and shared-library linking | `x2py/pipeline/build.py`, `x2py/compiling/compilers.py`, `x2py/compiling/native_support.py` | `docs/user/reference/fortran-wrapper.md`, `docs/developer/build-system.md` | `tests/wrapper/fortran/build_from_source/test_runtime_abi.py`, `tests/wrapper/fortran/build_from_source/test_build_modes.py` |
 | Public Python exports | `x2py/__init__.py` | `README.md`, `docs/user/reference/python-api.md` | `tests/parsing/fortran/test_public_entrypoints.py` |

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

@@ -275,8 +275,8 @@ primary placeholder queue.
 - [x] `docs/user/reference/semantic-pyi-format.md`: maintained semantic `.pyi`
   contract.
 - [x] `docs/user/reference/pyi-contracts/`: maintained editable `.pyi`
-  contract reference, organized by exports, callable surfaces, call
-  projection, and ownership.
+  contract reference, organized by exports, callable surfaces, and argument
+  and result projection.
 - [x] `docs/user/reference/fortran-wrapper.md`: maintained Fortran wrapper
   contract reference.
 - [x] `docs/user/reference/cli-commands.md`: maintained CLI reference.

docs/user/reference/pyi-contracts/calls-and-results.md

@@ -2,7 +2,7 @@
 title: .pyi Calls and Results
 audience: users, advanced users
 prerequisites: editing .pyi contracts overview
-related: index.md, functions-and-classes.md, ownership-and-lifetimes.md, ../semantic-pyi-format.md, ../../guide/arrays.md, ../../guide/error-handling.md
+related: index.md, functions-and-classes.md, ../semantic-pyi-format.md, ../../guide/arrays.md, ../../guide/error-handling.md
 status: maintained
 publication: reviewed
 ---
@@ -156,6 +156,5 @@ covered in the [Callbacks](../../guide/callbacks.md) guide.
 
 ## Next
 
-Most users can stop here. Read
-[Ownership and Lifetimes](ownership-and-lifetimes.md) only when editing
-explicit ownership annotations.
+Most users can stop here. Return to
+[Editing `.pyi` Contracts](index.md) to choose another edit.

docs/user/reference/pyi-contracts/index.md

@@ -2,7 +2,7 @@
 title: Editing .pyi Contracts
 audience: users, advanced users
 prerequisites: generated .pyi contract, wrapper build workflow
-related: exports-and-modules.md, functions-and-classes.md, calls-and-results.md, ownership-and-lifetimes.md, ../semantic-pyi-format.md
+related: exports-and-modules.md, functions-and-classes.md, calls-and-results.md, ../semantic-pyi-format.md
 status: maintained
 publication: reviewed
 ---
@@ -74,14 +74,6 @@ to compare and undo.
 - [How do I keep Python's Global Interpreter Lock (GIL) during a call, or return to the normal releasing behavior?](calls-and-results.md#keep-the-gil-when-required)
 - [How do I describe a callback signature in the contract?](../../guide/callbacks.md#choosing-the-prototype-spelling)
 
-### Storage and Lifetimes
-
-- [How do I understand or edit a complete ownership rule?](ownership-and-lifetimes.md#the-complete-ownership-rule)
-- [How do I choose a value, copy, view, existing object, or new handle?](ownership-and-lifetimes.md#transfer-values)
-- [How do I decide who releases persistent storage?](ownership-and-lifetimes.md#destruction-values)
-- [How do I understand allocatable or pointer handle ownership?](ownership-and-lifetimes.md#common-handle-cases)
-- [Why is an ownership combination rejected?](ownership-and-lifetimes.md#combinations-that-are-rejected)
-
 Most edits change the Python surface: names, visibility, grouping, or how
 native arguments appear as Python parameters and results.
 

docs/user/reference/pyi-contracts/ownership-and-lifetimes.md

@@ -92,7 +92,6 @@ nav:
               - Exports and Modules: user/reference/pyi-contracts/exports-and-modules.md
               - Functions and Classes: user/reference/pyi-contracts/functions-and-classes.md
               - Calls and Results: user/reference/pyi-contracts/calls-and-results.md
-              - Ownership and Lifetimes: user/reference/pyi-contracts/ownership-and-lifetimes.md
           - Diagnostic Codes: user/reference/diagnostic-codes.md
           - Generated Functions: user/reference/generated-functions.md
           - Generated Modules: user/reference/generated-modules.md

mkdocs.yml

@@ -125,7 +125,6 @@
     "user/reference/pyi-contracts/exports-and-modules.md",
     "user/reference/pyi-contracts/functions-and-classes.md",
     "user/reference/pyi-contracts/calls-and-results.md",
-    "user/reference/pyi-contracts/ownership-and-lifetimes.md",
     "user/reference/diagnostic-codes.md",
 ]
 REQUIRED_ROADMAP_PAGES = [