prepare for website

.github/workflows/docs.yml

@@ -0,0 +1,81 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/docs.yml"
+      - "README.md"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "tests/docs/**"
+      - "tools/mkdocs_publication.py"
+  pull_request:
+    paths:
+      - ".github/workflows/docs.yml"
+      - "README.md"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "tests/docs/**"
+      - "tools/mkdocs_publication.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install documentation dependencies
+        run: python -m pip install -e ".[docs,qa]"
+
+      - name: Run documentation tests
+        run: python -m pytest -q tests/docs
+
+      - name: Build reviewed documentation
+        run: python -m mkdocs build --strict
+
+      - name: Configure GitHub Pages
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/configure-pages@v5
+
+      - name: Upload GitHub Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -10,6 +10,7 @@ mutants/
 .ruff_cache/
 .benchmarks/
 htmlcov/
+site/
 
 *.pyc
 *.pyo

AGENTS.md

@@ -17,6 +17,12 @@ When updating tests, remove obsolete tests that only assert removed/old implemen
 
 Before `x2py/semantics/ir2ast.py` runs, the post-IR policy stage must have completed every semantic decision needed by wrapper generation, including object kind, ownership, transfer, destruction, mutability/writeback, nullability, output projection, release responsibility, contract-value storage mode (`stack`, `heap`, or `alias`), getter behavior, native setter assignment, and Python setter exposure. Bridge and binding generators may only dispatch from those completed decisions into small named implementation methods. They must not infer or override semantic policy from datatype, `intent`, dotted-variable shape, `is_alias`, or local memory checks, and they must not contain a fallback that silently chooses a different behavior. When such a decision is found in bridge or binding code, remove it there and move it into post-IR policy completion. Backend-local helper temporaries may still be created inside the selected implementation method because they are emitted-code details, not semantic policy.
 
+For behavior changes, first try to express the change in completed semantic
+policy or the shared wrapper plan. Change binding or bridge lowering only when
+the selected plan requires a genuinely new emitted-code mechanism; those
+generators should otherwise keep reusing and dispatching existing planned
+paths.
+
 After every implementation task, the final summary must include a breakdown of
 the stages that actually changed. Relevant stages include parsing, semantic IR
 construction, post-IR policy completion, IR-to-AST/lowering, binding

README.md

@@ -344,7 +344,7 @@ X2PY_C_DOCS_END -->
 
 For diagnostic and inspection commands beyond the main build path, start with
 `python3 -m x2py --help`, then continue to the
-[Fortran wrapper guide](docs/user/guide/fortran-wrapper.md).
+[CLI command reference](docs/user/reference/cli-commands.md).
 
 <!-- X2PY_C_DOCS_START
 The runtime build path accepts one or more ordered Fortran sources. C parsing,
@@ -557,9 +557,8 @@ ownership, callback lifetime, ABI shims, or Python-visible projections.
 - **[Getting Started](docs/user/getting-started/index.md)** — Installation, verification, standalone procedures, modules, and rebuild workflow
 - **[User Guide](docs/user/guide/index.md)** — Detailed guidance on data types, functions, subroutines, modules, arrays, derived types, callbacks, ownership, runtime behavior, and packaging
 <!--
-- **[Tutorials](docs/user/tutorials/)** — Step-by-step walkthroughs
-- **[Examples Cookbook](docs/user/examples/verified-cookbook.md)** — Ready-to-use Fortran wrapper patterns and recipes
-- **[CLI Reference](docs/user/reference/cli.md)** — Complete command-line documentation
+- **[Tutorials](docs/user/tutorials/index.md)** — Step-by-step walkthroughs
+- **[CLI Reference](docs/user/reference/cli-commands.md)** — Complete command-line documentation
 - **[Language Support](docs/user/language-support/index.md)** — What is supported, partially supported, or planned
 - **[FAQ](docs/user/faq/index.md)** — Concise answers to common questions
 - **[Troubleshooting](docs/user/troubleshooting/index.md)** — Solutions for installation, compiler, build, runtime, and platform issues

docs/developer/adding-a-code-generation-backend.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: code generation design, internal architecture
 related: adding-a-feature.md, build-system.md
 status: planned-documentation
+publication: draft
 ---
 
 # Adding A New Code Generation Backend

docs/developer/adding-a-feature.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: testing strategy, documentation architecture
 related: adding-a-fortran-construct.md, coding-standards.md
 status: planned-documentation
+publication: draft
 ---
 
 # Adding A New Feature

docs/developer/adding-a-fortran-construct.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: parser architecture, semantic analysis
 related: adding-a-feature.md, fortran-parser-reference.md
 status: planned-documentation
+publication: draft
 ---
 
 # Adding A New Fortran Construct

docs/developer/build-system.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: repository structure
 related: testing-strategy.md, ../user/reference/configuration-files.md
 status: planned-documentation
+publication: draft
 ---
 
 # Build System

docs/developer/c-parser-reference.md

@@ -5,6 +5,7 @@ audience: developers
 prerequisites: repository structure, parser architecture
 related: adding-a-feature.md, repository-structure.md
 status: maintained
+publication: draft
 ---
 
 <!-- X2PY_C_DOCS_START

docs/developer/coding-standards.md

@@ -4,6 +4,7 @@ audience: contributors
 prerequisites: repository structure
 related: testing-strategy.md, quality-assurance.md
 status: planned-documentation
+publication: draft
 ---
 
 # Coding Standards

docs/developer/contributing/contribution-guide.md

@@ -4,6 +4,7 @@ audience: contributors
 prerequisites: repository checkout
 related: pull-request-workflow.md, ../index.md
 status: planned-documentation
+publication: draft
 ---
 
 # Contribution Guide

docs/developer/contributing/index.md

@@ -4,6 +4,7 @@ audience: contributors
 prerequisites: repository checkout
 related: ../index.md, ../../../CONTRIBUTING.md
 status: planned-documentation
+publication: draft
 ---
 
 # Contributing
@@ -15,7 +16,7 @@ developer workflows.
 
 - [Contribution guide](contribution-guide.md)
 - [Pull request workflow](pull-request-workflow.md)
-- [Coding standards](coding-standards.md)
+- [Coding standards](../coding-standards.md)
 - [Review process](review-process.md)
 
 ## TODO

docs/developer/contributing/pull-request-workflow.md

@@ -4,6 +4,7 @@ audience: contributors
 prerequisites: contribution guide
 related: review-process.md, ../quality-assurance.md
 status: planned-documentation
+publication: draft
 ---
 
 # Pull Request Workflow

docs/developer/contributing/review-process.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: pull request workflow
 related: pull-request-workflow.md, ../testing-strategy.md
 status: planned-documentation
+publication: draft
 ---
 
 # Review Process

docs/developer/development-workflow.md

@@ -4,6 +4,7 @@ audience: developers, contributors
 prerequisites: repository checkout, Python 3.10 or newer
 related: index.md, quality-assurance.md
 status: maintained
+publication: draft
 ---
 
 # Development Workflow
@@ -13,8 +14,9 @@ implementation and tests, then gives focused change and verification
 workflows.
 
 <!-- X2PY_C_DOCS_START
-Use the [tutorial](../user/tutorials/basic-wrapper.md) and [examples cookbook](../user/examples/verified-cookbook.md) to inspect
-the public workflows before changing them. This guide is the developer entry
+Use [Getting Started](../user/getting-started/index.md) and the
+[Examples Gallery](../user/examples/index.md) to inspect the public workflows
+before changing them. This guide is the developer entry
 point for the C and Fortran parser references, implementation ownership, and
 the detailed maintained contracts.
 X2PY_C_DOCS_END -->
@@ -54,7 +56,7 @@ For example, a new CLI stage option normally requires:
 1. A focused contract test in `tests/cli/`.
 2. Dispatch or output routing in `x2py/cli.py`.
 3. Preprocessing tests if the option changes source loading.
-4. A copy-paste command in [Verified examples cookbook](../user/examples/verified-cookbook.md).
+4. A copy-paste command in the relevant user guide or checked example.
 5. A tutorial update only when the main user workflow changes.
 
 ## Support Evidence Rule
@@ -72,9 +74,9 @@ Use these documentation roles consistently:
 
 | Document | Role |
 | --- | --- |
-| [Basic wrapper tutorial](../user/tutorials/basic-wrapper.md) | Main supported user workflow and boundaries |
-| [Verified examples cookbook](../user/examples/verified-cookbook.md) | Copy-paste commands and Python API recipes |
-| [Fortran wrapper guide](../user/guide/fortran-wrapper.md) | Implemented Fortran runtime contract, mechanism, ownership, and build modes |
+| [Getting Started](../user/getting-started/index.md) | Main supported user workflow and boundaries |
+| [Examples Gallery](../user/examples/index.md) | Checked commands and Python API recipes |
+| [Fortran wrapper reference](../user/reference/fortran-wrapper.md) | Implemented Fortran runtime contract, mechanism, ownership, and build modes |
 | [Fortran parser reference](fortran-parser-reference.md) | Developer inventory for the Fortran frontend |
 | [Semantic IR reference](../user/reference/semantic-ir.md) | Accepted semantic IR and datatype contract |
 | [Semantic .pyi format](../user/reference/semantic-pyi-format.md) | User-visible semantic `.pyi` syntax and roadmap |
@@ -172,9 +174,10 @@ PYTHONPATH=. python3 -m pytest -q tests/docs/test_examples.py
 
 ## References
 
-- [Tutorial](../user/tutorials/basic-wrapper.md): supported end-to-end user workflow and current
-  boundaries.
-- [Verified examples cookbook](../user/examples/verified-cookbook.md): CLI and Python API recipes.
+- [Getting Started](../user/getting-started/index.md): supported end-to-end user
+  workflow and current boundaries.
+- [Examples Gallery](../user/examples/index.md): checked CLI and Python API
+  recipes.
 - [Fortran parser reference](fortran-parser-reference.md): Fortran frontend scope,
   recursive parser organization, API/CLI behavior, diagnostics, fixture
   workflow, semantic handoff, and tests.
@@ -319,8 +322,9 @@ When changing `.pyi` syntax:
 1. Add or update parser tests in `tests/parsing/pyi/`.
 2. Add or update printer tests in `tests/wrapper_codegen/printers/`.
 3. Update fixture tests only if the public generated contract changes.
-4. Update [Basic wrapper tutorial](../user/tutorials/basic-wrapper.md) or [Verified examples cookbook](../user/examples/verified-cookbook.md) if users
-   need to write or read the new syntax.
+4. Update the relevant [User Guide](../user/guide/index.md) or checked
+   [example](../user/examples/index.md) if users need to write or read the new
+   syntax.
 5. Update [Semantic .pyi format](../user/reference/semantic-pyi-format.md) for the full user-facing reference.
 6. Update [Semantic IR reference](../user/reference/semantic-ir.md) if the underlying semantic IR contract
    changes.
@@ -347,9 +351,10 @@ When changing datatype mapping:
 2. Add `.pyi` printer/loader coverage if the emitted syntax changes.
 3. Update semantic fixtures only when serialized semantic IR intentionally
    changes.
-4. Update [Semantic IR reference](../user/reference/semantic-ir.md), plus
-   [Basic wrapper tutorial](../user/tutorials/basic-wrapper.md) or [Verified examples cookbook](../user/examples/verified-cookbook.md) when the visible
-   user workflow or examples change.
+4. Update [Semantic IR reference](../user/reference/semantic-ir.md), plus the
+   relevant [User Guide](../user/guide/index.md) or checked
+   [example](../user/examples/index.md) when the visible user workflow or
+   examples change.
 5. Regenerate and update the exact target mapping snapshots in
    [Semantic IR reference](../user/reference/semantic-ir.md). The executable documentation test must match
    the complete output of:
@@ -1110,8 +1115,10 @@ X2PY_C_DOCS_END -->
    `x2py/semantics/c2ir.py` and add coverage in `tests/semantics/conversion/c/`.
 7. If the generated `.pyi` changes, update `tests/wrapper_codegen/printers/`
    or `tests/pipeline/pyi_builds/test_contract_fixtures.py`.
-8. Update [C parser reference](c-parser-reference.md), [Basic wrapper tutorial](../user/tutorials/basic-wrapper.md),
-   [Verified examples cookbook](../user/examples/verified-cookbook.md), or [Semantic IR reference](../user/reference/semantic-ir.md) if users or
+8. Update [C parser reference](c-parser-reference.md), the relevant
+   [User Guide](../user/guide/index.md), checked
+   [example](../user/examples/index.md), or
+   [Semantic IR reference](../user/reference/semantic-ir.md) if users or
    developers need to know the new behavior.
 X2PY_C_DOCS_END -->
 
@@ -1155,8 +1162,10 @@ metadata item.
    and `tests/semantics/conversion/fortran/`.
 7. If generated `.pyi` changes, update `tests/wrapper_codegen/printers/`
    and the relevant fixture tests.
-8. Update [Fortran parser reference](fortran-parser-reference.md), [Basic wrapper tutorial](../user/tutorials/basic-wrapper.md),
-   [Verified examples cookbook](../user/examples/verified-cookbook.md), or [Semantic IR reference](../user/reference/semantic-ir.md) as needed.
+8. Update [Fortran parser reference](fortran-parser-reference.md), the relevant
+   [User Guide](../user/guide/index.md), checked
+   [example](../user/examples/index.md), or
+   [Semantic IR reference](../user/reference/semantic-ir.md) as needed.
 
 Focused verification:
 
@@ -1180,9 +1189,10 @@ X2PY_C_DOCS_END -->
    there is a deliberate schema decision.
 4. If the emitted `.pyi` annotation changes, update
    `tests/wrapper_codegen/printers/` and `tests/parsing/pyi/`.
-5. Update the datatype tables in [Semantic IR reference](../user/reference/semantic-ir.md), and update
-   [Basic wrapper tutorial](../user/tutorials/basic-wrapper.md) or [Verified examples cookbook](../user/examples/verified-cookbook.md) when a visible
-   example changes.
+5. Update the datatype tables in
+   [Semantic IR reference](../user/reference/semantic-ir.md), and update the
+   relevant [User Guide](../user/guide/index.md) or checked
+   [example](../user/examples/index.md) when a visible example changes.
 
 <!-- X2PY_C_DOCS_START
 1. Add conversion coverage in `tests/semantics/conversion/fortran/` or
@@ -1222,8 +1232,10 @@ Example target: add a new `Annotated[...]` metadata item or projection helper.
    field or constraint.
 6. Update policy completion or wrapper planning if the syntax changes a
    completed decision.
-7. Update [Semantic IR reference](../user/reference/semantic-ir.md), plus [Basic wrapper tutorial](../user/tutorials/basic-wrapper.md) or
-   [Verified examples cookbook](../user/examples/verified-cookbook.md) when users need the new syntax in a workflow.
+7. Update [Semantic IR reference](../user/reference/semantic-ir.md), plus the
+   relevant [User Guide](../user/guide/index.md) or checked
+   [example](../user/examples/index.md) when users need the new syntax in a
+   workflow.
 
 Focused verification:
 
@@ -1277,8 +1289,9 @@ diagnostic formatting.
 3. Keep Fortran package-specific CLI behavior in `x2py/parsers/fortran/cli.py`.
 4. If compiler preprocessing behavior changes, update `x2py/pipeline/preprocessing.py`
    and preprocessing tests.
-5. Update [Basic wrapper tutorial](../user/tutorials/basic-wrapper.md) or [Verified examples cookbook](../user/examples/verified-cookbook.md) for
-   user-facing commands and this guide for developer command maps.
+5. Update the relevant [User Guide](../user/guide/index.md) or checked
+   [example](../user/examples/index.md) for user-facing commands and this guide
+   for developer command maps.
 
 Focused verification: