saidctb · Sep 28, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/.artifacts/.gitignore b/.artifacts/.gitignore
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
diff --git a/CONTRIBUTING.md → .github/CONTRIBUTING.md b/CONTRIBUTING.md → .github/CONTRIBUTING.md
@@ -33,11 +33,11 @@ Keep the pull request easy to review: explain the problem, the solution, and
 how you verified it. All required GitHub checks must pass before merge.
 
 For the complete workflow, see the
-[contributing workflow](docs/developer/workflows/contributing.md) and
-[quality-assurance guide](docs/developer/workflows/quality-assurance.md).
+[contributing workflow](../docs/developer/workflows/contributing.md) and
+[quality-assurance guide](../docs/developer/workflows/quality-assurance.md).
 
 ## License
 
-Contributions are accepted under the [MIT License](LICENSE). By submitting a
+Contributions are accepted under the [MIT License](../LICENSE). By submitting a
 contribution, you confirm that you have the right to license it under those
 terms.
diff --git a/.gitignore b/.gitignore
@@ -11,6 +11,7 @@ mutants/
 .benchmarks/
 htmlcov/
 build/
+.artifacts/
 
 *.pyc
 *.pyo

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,17 @@ release tags add a leading `v` to the package version.
 
 ## Unreleased
 
+- The README and the documentation homepage now open with a short terminal
+  demo that builds a Fortran module and calls it from Python, followed by links
+  to Colab, installation, and the real-library examples.
+- The repository root holds fewer files. Contributor notes moved to
+  `.github/CONTRIBUTING.md`, the pre-push hook to `tools/githooks/` (activate it
+  with `git config core.hooksPath tools/githooks`), and the documentation theme
+  to `tools/mkdocs-theme/`. Local builds write `prik.egg-info/` to the ignored
+  repository root; `.artifacts/` still holds the documentation site and
+  distributions. Subprocess coverage uses the startup hook that ships with
+  coverage, so `COVERAGE_PROCESS_START` works as before.
+
 ## 0.5.1 — 2026-09-27
 
 ### Breaking changes

diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,4 +1,3 @@
 include CHANGELOG.md
 include CITATION.cff
-include .artifacts/.gitignore
 recursive-include prik/cmake_modules *.cmake
diff --git a/README.md b/README.md
@@ -1,26 +1,42 @@
 <p align="center">
   <img src="https://raw.githubusercontent.com/PyNumLab/prik/main/docs/user/assets/prik-logo.png"
        alt="PRIK — Bring Native Code to Python"
-       width="450">
+       width="420">
 </p>
 
-**PRIK (Python Runtime Interop Kit)** generates native Python bindings for
-Fortran and C code.
+<p align="center">
+  <b>Turn Fortran and C code into native Python extensions,<br>
+  then design the Python API by editing a <code>.pyi</code> contract.</b>
+</p>
 
-[![Tests](https://github.com/PyNumLab/prik/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/PyNumLab/prik/actions/workflows/tests.yml)
-[![Static Analysis](https://github.com/PyNumLab/prik/actions/workflows/static-analysis.yml/badge.svg?branch=main)](https://github.com/PyNumLab/prik/actions/workflows/static-analysis.yml)
-[![codecov](https://codecov.io/gh/PyNumLab/prik/graph/badge.svg?token=QZRRCS5YO6)](https://codecov.io/gh/PyNumLab/prik)
-[![DOI](https://zenodo.org/badge/1241799694.svg)](https://doi.org/10.5281/zenodo.21881987)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/PyNumLab/prik/main/docs/user/assets/prik-demo.gif"
+       alt="Terminal demo: a Fortran module with a derived type is built with one PRIK command, then imported and called from Python, printing 4.0 2.0 and 20.0"
+       width="720">
+</p>
 
-**Try it without installing anything.** The quickstart notebook compiles a
-Fortran cell and a C cell, then reshapes the generated API by editing its
-`.pyi` contract.
+<p align="center">
+  <a href="https://colab.research.google.com/github/PyNumLab/prik/blob/main/examples/notebooks/quickstart.ipynb"><b>Try it in Colab</b></a>
+  ·
+  <a href="#installation--quick-start"><b>Install</b></a>
+  ·
+  <a href="#proven-on-real-libraries"><b>Explore real libraries</b></a>
+</p>
 
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/PyNumLab/prik/blob/main/examples/notebooks/quickstart.ipynb)
+<p align="center">
+  Tested on BLAS, LAPACK, FFTPACK, MINPACK, BSPLINE-FORTRAN, PRIMA, Open MPI,
+  libm, and TA-Lib across Linux and macOS.
+</p>
 
-It preserves modules, derived types, arrays, callbacks, and native behavior
-while letting you reshape the resulting Python API through editable `.pyi`
-contracts instead of writing low-level binding code.
+<p align="center">
+  <a href="https://github.com/PyNumLab/prik/actions/workflows/tests.yml"><img src="https://github.com/PyNumLab/prik/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests"></a>
+  <a href="https://github.com/PyNumLab/prik/actions/workflows/static-analysis.yml"><img src="https://github.com/PyNumLab/prik/actions/workflows/static-analysis.yml/badge.svg?branch=main" alt="Static Analysis"></a>
+  <a href="https://codecov.io/gh/PyNumLab/prik"><img src="https://codecov.io/gh/PyNumLab/prik/graph/badge.svg?token=QZRRCS5YO6" alt="codecov"></a>
+  <a href="https://doi.org/10.5281/zenodo.21881987"><img src="https://zenodo.org/badge/1241799694.svg" alt="DOI"></a>
+</p>
+
+**PRIK (Python Runtime Interop Kit)** generates native Python bindings for
+Fortran and C code.
 
 **Project status: Alpha.** Core Fortran workflows and the currently supported
 C wrapper features are implemented and tested across supported compilers, but

diff --git a/docs/developer/index.md b/docs/developer/index.md
@@ -31,8 +31,9 @@ Install an editable checkout with development tools:
 python3 -m pip install -e ".[qa]"
 ```
 
-For the short public checklist (branch, tests, changelog, license), see the
-repository-root `CONTRIBUTING.md`. The full contributor path is in
+For the short public checklist (branch, tests, changelog, license), see
+`.github/CONTRIBUTING.md`, which GitHub links from new issues and pull
+requests. The full contributor path is in
 [Contributing workflow](workflows/contributing.md).
 
 ## For a specific change

diff --git a/docs/developer/workflows/contributing.md b/docs/developer/workflows/contributing.md
@@ -10,13 +10,13 @@ publication: reviewed
 # Contributing Workflow
 
 This page is the practical path for changing PRIK. The root
-[`CONTRIBUTING.md`](../../../CONTRIBUTING.md) is the short public entrypoint.
+[`.github/CONTRIBUTING.md`](../../../.github/CONTRIBUTING.md) is the short public entrypoint.
 
 ## Prepare The Checkout
 
 ```bash
 python3 -m pip install -e ".[qa]"
-git config core.hooksPath .githooks
+git config core.hooksPath tools/githooks
 ```
 
 This enables PRIK's repository pre-push checks for this checkout.

diff --git a/docs/developer/workflows/documentation.md b/docs/developer/workflows/documentation.md
@@ -11,7 +11,7 @@ publication: reviewed
 
 PRIK has two published documentation areas: `docs/user/` for product users and
 `docs/developer/` for contributors and maintainers. `mkdocs.yml` defines the
-page order, and `.mkdocs/theme/nav.html` makes each expandable section label open
+page order, and `tools/mkdocs-theme/nav.html` makes each expandable section label open
 its first page while its **+** control expands or collapses the section.
 
 ## Write The Right Contract

diff --git a/docs/index.md b/docs/index.md
@@ -11,7 +11,29 @@ publication: reviewed
 <p align="center">
   <img src="user/assets/prik-logo.png"
        alt="PRIK — Bring Native Code to Python"
-       width="500">
+       width="420">
+</p>
+
+<p align="center">
+  <b>Turn Fortran and C code into native Python extensions,<br>
+  then design the Python API by editing a <code>.pyi</code> contract.</b>
+</p>
+
+<p align="center">
+  <img class="prik-demo" src="user/assets/prik-demo.gif"
+       alt="Terminal demo: a Fortran module with a derived type is built with one PRIK command, then imported and called from Python, printing 4.0 2.0 and 20.0"
+       width="720">
+</p>
+
+<p class="prik-notebook-actions prik-hero-actions" markdown>
+[▶&nbsp; Try it in Colab](https://colab.research.google.com/github/PyNumLab/prik/blob/main/examples/notebooks/quickstart.ipynb){ .prik-primary-cta }
+[Install](user/getting-started/installation.md){ .prik-secondary-cta }
+[Explore real libraries](#proven-on-real-libraries){ .prik-secondary-cta }
+</p>
+
+<p align="center">
+  Tested on BLAS, LAPACK, FFTPACK, MINPACK, BSPLINE-FORTRAN, PRIMA, Open MPI,
+  libm, and TA-Lib across Linux and macOS.
 </p>
 
 **PRIK (Python Runtime Interop Kit)** generates native Python bindings for

diff --git a/docs/stylesheets/site.css b/docs/stylesheets/site.css
@@ -220,6 +220,15 @@
   margin: 1.25rem 0 1.5rem;
 }
 
+.prik-hero-actions {
+  justify-content: center;
+}
+
+.prik-demo {
+  max-width: 100%;
+  height: auto;
+}
+
 .prik-secondary-cta {
   display: inline-flex;
   align-items: center;

diff --git a/docs/user/assets/prik-demo.gif b/docs/user/assets/prik-demo.gif
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,7 +8,7 @@ docs_dir: docs
 site_dir: .artifacts/site
 theme:
   name: readthedocs
-  custom_dir: .mkdocs/theme
+  custom_dir: tools/mkdocs-theme
   logo: user/assets/prik-mark.png
   collapse_navigation: false
   include_homepage_in_sidebar: true

diff --git a/setup.cfg b/setup.cfg
diff --git a/sitecustomize.py b/sitecustomize.py
diff --git a/tests/README.md b/tests/README.md
@@ -28,7 +28,7 @@ language.
 The tracked pre-push hook runs the blocking static-analysis gate, the focused
 publication and user-content documentation smoke tests, one compiled scalar
 source-to-native-call wrapper test, `tests/tools/`, and `tests/workflows/`
-locally; activate it once per clone with `git config core.hooksPath .githooks`.
+locally; activate it once per clone with `git config core.hooksPath tools/githooks`.
 GitHub Actions runs the checks again as the shared enforcement boundary.
 
 The Fortran feature index maps each maintained User Guide and semantic `.pyi`

diff --git a/.githooks/pre-push → tools/githooks/pre-push b/.githooks/pre-push → tools/githooks/pre-push
@@ -6,7 +6,7 @@ import sys
 from pathlib import Path
 
 
-REPOSITORY_ROOT = Path(__file__).resolve().parents[1]
+REPOSITORY_ROOT = Path(__file__).resolve().parents[2]
 DOCUMENTATION_SMOKE_TESTS = (
     "tests/docs/test_publication.py",
     "tests/docs/test_user_content.py",

diff --git a/.mkdocs/theme/breadcrumbs.html → tools/mkdocs-theme/breadcrumbs.html b/.mkdocs/theme/breadcrumbs.html → tools/mkdocs-theme/breadcrumbs.html
diff --git a/.mkdocs/theme/footer.html → tools/mkdocs-theme/footer.html b/.mkdocs/theme/footer.html → tools/mkdocs-theme/footer.html
diff --git a/.mkdocs/theme/main.html → tools/mkdocs-theme/main.html b/.mkdocs/theme/main.html → tools/mkdocs-theme/main.html
diff --git a/.mkdocs/theme/nav.html → tools/mkdocs-theme/nav.html b/.mkdocs/theme/nav.html → tools/mkdocs-theme/nav.html
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,6 +11,7 @@ mutants/ @@
     .benchmarks/
     htmlcov/
     build/
+    .artifacts/
     *.pyc
     *.pyo
@@ Expand Down @@