Devel refactor

.artifacts/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

.github/workflows/docs.yml

@@ -147,7 +147,7 @@ jobs:
         if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
         uses: actions/upload-pages-artifact@v4
         with:
-          path: site
+          path: .artifacts/site
 
   deploy:
     name: Documentation deployment · GitHub Pages

.github/workflows/publish-to-pypi.yml

@@ -44,17 +44,17 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install build twine
       - name: Build source and wheel distributions
-        run: python -m build
+        run: python -m build --outdir .artifacts/dist
       - name: Check distribution metadata
-        run: python -m twine check dist/*
+        run: python -m twine check .artifacts/dist/*
       - name: Verify and install the wheel
         shell: bash
         run: |
-          mapfile -t wheels < <(compgen -G "dist/prik-*-py3-none-any.whl")
-          mapfile -t sdists < <(compgen -G "dist/prik-*.tar.gz")
+          mapfile -t wheels < <(compgen -G ".artifacts/dist/prik-*-py3-none-any.whl")
+          mapfile -t sdists < <(compgen -G ".artifacts/dist/prik-*.tar.gz")
           if (( ${#wheels[@]} != 1 || ${#sdists[@]} != 1 )); then
             echo "expected one universal wheel and one source distribution" >&2
-            ls -la dist
+            ls -la .artifacts/dist
             exit 1
           fi
           python -m venv "$RUNNER_TEMP/prik-release-check"
@@ -68,7 +68,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: python-package-distributions
-          path: dist/
+          path: .artifacts/dist/
           if-no-files-found: error
           retention-days: 7
 
@@ -86,6 +86,8 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: python-package-distributions
-          path: dist/
+          path: .artifacts/dist/
       - name: Publish distributions to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: .artifacts/dist/

.gitignore

@@ -10,13 +10,11 @@ mutants/
 .ruff_cache/
 .benchmarks/
 htmlcov/
-site/
 build/
 
 *.pyc
 *.pyo
 *egg*
-dist/*
 
 *.mod
 *.out

AGENTS.md

@@ -21,7 +21,7 @@ Do not spend context window or analysis on those files unless explicitly request
 When asked to change or move an API, import path, command, feature, or behavior, do not add or keep compatibility layers, aliases, shims, fallback paths, or legacy entrypoints unless explicitly requested. A requested change means the old behavior should be removed.
 When updating tests, remove obsolete tests that only assert removed/old implementation behavior does not exist. Do not preserve rejection or absence checks for API/features that were intentionally removed unless explicitly requested.
 
-Before wrapper planning begins in `prik/codegen/planner.py`, the
+Before wrapper planning begins in `prik/planning/planner.py`, 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,

CHANGELOG.md

@@ -9,9 +9,75 @@ release tags add a leading `v` to the package version.
 
 ### Added
 
+- Reorganized contributor documentation around a concise architecture guide
+  and one canonical page per production package, with local structures,
+  important objects, runnable examples, expected outputs, test owners, change
+  routes, and invariants.
+- Consolidated cross-stage concepts and contributor workflows, retained future
+  and deferred designs explicitly, and removed TODO-only pages, duplicate
+  architecture maps, and completed migration ledgers.
 - Added Zenodo version and concept DOI links to the citation metadata, README,
   and About page.
 
+### Changed
+
+- Reduced the root `prik` API to its version and normal-user build entrypoints;
+  parser, semantic, probe, runtime, and planning tools now use their owning
+  package import paths.
+- Moved stage-record freezing from `prik.stage_values` to
+  `prik.utilities.stage_values`; the root module path was removed.
+- Made `prik` an import-only package boundary by removing its direct-script
+  demonstration; command and stage-value examples remain available from their
+  owning modules.
+- Expanded the contributor architecture and package guides into a complete
+  stage-by-stage tutorial, with every supported Python module, runnable example
+  result, focused test purpose, and change route recorded and checked against
+  the source tree.
+- Moved generated documentation and distribution output under the hidden
+  `.artifacts/` directory in local commands and CI workflows.
+- Centralized every production-file execution-example output contract in one
+  contributor-architecture test inventory with one named test per file.
+- Renamed the central infrastructure owner to `execution_examples/` so its
+  responsibility is explicit in the test tree.
+- Consolidated developer and maintainer material under one Contributor
+  Documentation tree and removed the separate maintainer documentation lane.
+- Moved the bundled header-only binding runtime from the package root into
+  `prik.runtime.native_support`; generated builds continue to receive it under
+  their internal `binding_support/` include directory.
+- Deferred the contributor architecture sections for the immature C input
+  parser and C-to-IR path while retaining the generated CPython C binding
+  backend documentation required by Fortran wrappers.
+- Reorganized compiler and pre-parse infrastructure into `prik.compiler` and
+  `prik.preprocessing`, including C/Fortran preprocessing and target probes;
+  the former `prik.compiling`, `prik.probes`, parser-local C preprocessor, and
+  pipeline-local preprocessing import paths were removed.
+- Replaced the public semantic-to-NumPy helper API with stage-owned semantic,
+  contract-runtime, and code-generation datatype catalogues, and documented the
+  complete internal datatype lifecycle from compiler probing to runtime
+  validation.
+- Separated post-IR policy and wrapper planning into `prik.policy` and
+  `prik.planning`; code generation now renders plan-driven docstrings, and the
+  former maintainer import paths were removed.
+- Added a top-level language-printer package for C, Fortran, and semantic
+  `.pyi` output, and made `pipeline.wrapper.WrapperGenerator` the single
+  plan-to-rendered-wrapper orchestration boundary.
+- Documented the completed ownership vocabulary, lifetime-policy philosophy,
+  pointer-policy boundary, and maintainer change routes in one maintained
+  architecture reference.
+- Moved exact overload selection from generated Python predicate chains to
+  generated C dispatchers with planned candidate IDs and direct switch-based
+  calls to the selected existing wrapper.
+- Stopped standalone Fortran parser discovery from descending into inaccessible
+  procedure-internal subprograms; procedure-local callback interfaces remain
+  classified and discoverable.
+- Made directory project parsing read and parse each discovered Fortran file
+  once before dependency ordering and project assembly.
+
+### Fixed
+
+- Unified source-level compile-time resolution across project and CLI parsing
+  so imported and host-associated kind facts also reach derived-type fields.
+
 ## 0.2.1 — 2026-08-11
 
 ### Added

CONTRIBUTING.md

@@ -33,8 +33,8 @@ 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
-[development guide](docs/developer/development-workflow.md) and
-[quality-assurance guide](docs/developer/quality-assurance.md).
+[contributing workflow](docs/developer/workflows/contributing.md) and
+[quality-assurance guide](docs/developer/workflows/quality-assurance.md).
 
 ## License
 

MANIFEST.in

@@ -1 +1,2 @@
 include CHANGELOG.md
+include .artifacts/.gitignore

README.md

@@ -519,8 +519,8 @@ explicit build directories, depending on the command mode.
 
 ## Python API
 
-Public entrypoints cover Fortran extension builds, parsing, semantic
-conversion and `.pyi` emission:
+Root entrypoints cover normal Fortran extension builds. Advanced parsing,
+semantic conversion, and `.pyi` emission use their owning packages:
 
 ```python
 from prik import build_fortran_extension
@@ -539,11 +539,9 @@ strings, focused tests, and already-preprocessed inputs.
 
 <!-- PRIK_C_DOCS_START
 ```python
-from prik import (
-    c_file_to_semantic_modules,
-    emit_module_stubs,
-    parse_c_file,
-)
+from prik.parsers.c import parse_c_file
+from prik.pipeline.pyi import emit_module_stubs
+from prik.semantics.c2ir import c_file_to_semantic_modules
 
 parsed = parse_c_file("int add(int a, int b);", filename="api.h")
 modules = c_file_to_semantic_modules(parsed)