kineticheck 0.1.0__tar.gz

kineticheck-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,21 @@
+name: Bug report
+description: Report a reproducible software defect.
+title: "[Bug] "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: "Do not attach unpublished or confidential research data. Create a minimal synthetic reproducer."
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Commands, minimal inputs, expected result, and actual result.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: KinetiCheck and Python versions
+    validations:
+      required: true

kineticheck-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Data confidentiality reminder
+    url: https://github.com/hdkim99/KinetiCheck/security
+    about: Do not post unpublished, proprietary, personal, or confidential research data publicly.

kineticheck-0.1.0/.github/ISSUE_TEMPLATE/dataset.yml

@@ -0,0 +1,26 @@
+name: Real dataset compatibility
+description: Propose a public, licensed dataset or report an import issue.
+title: "[Dataset] "
+labels: [dataset]
+body:
+  - type: markdown
+    attributes:
+      value: "Only public data may be linked. Never upload unpublished or confidential laboratory data."
+  - type: input
+    id: doi
+    attributes:
+      label: DOI or persistent public URL
+    validations:
+      required: true
+  - type: input
+    id: license
+    attributes:
+      label: Dataset license
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Files, checksum, and intended validation scope
+    validations:
+      required: true

kineticheck-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,17 @@
+name: Feature request
+description: Propose one bounded research workflow.
+title: "[Feature] "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: need
+    attributes:
+      label: Research decision and current limitation
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Scientific definition, validity range, and authoritative source
+    validations:
+      required: true

kineticheck-0.1.0/.github/ISSUE_TEMPLATE/macos.yml

@@ -0,0 +1,34 @@
+name: macOS or GUI issue
+description: Report installation, Tk, window lifecycle, export, or backend failure.
+title: "[macOS/GUI] "
+labels: [macos, gui]
+body:
+  - type: markdown
+    attributes:
+      value: "Do not attach confidential data. Include the complete traceback as text."
+  - type: input
+    id: macos
+    attributes:
+      label: macOS version and architecture
+      placeholder: macOS 15.x, Apple Silicon or Intel
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Python, KinetiCheck, Tk, and matplotlib versions
+    validations:
+      required: true
+  - type: textarea
+    id: install
+    attributes:
+      label: Installation method and exact GUI command
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Complete traceback
+      render: shell
+    validations:
+      required: true

kineticheck-0.1.0/.github/ISSUE_TEMPLATE/scientific.yml

@@ -0,0 +1,20 @@
+name: Scientific result question
+description: Ask about an equation, definition, unit, threshold, or interpretation.
+title: "[Science] "
+labels: [scientific-question]
+body:
+  - type: markdown
+    attributes:
+      value: "Do not post unpublished/confidential data. State the exact rate basis and cite the proposed definition."
+  - type: textarea
+    id: definition
+    attributes:
+      label: Equation, convention, and reference
+    validations:
+      required: true
+  - type: textarea
+    id: inputs
+    attributes:
+      label: Minimal synthetic inputs with units and rate basis
+    validations:
+      required: true

kineticheck-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

kineticheck-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: DGX CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: kineticheck-dgx-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  scientific:
+    name: DGX / scientific, package, CLI, GUI
+    # Public fork PR code must never execute on the persistent DGX host.
+    if: >-
+      github.event_name != 'pull_request' ||
+      (github.actor == github.repository_owner &&
+       github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: [self-hosted, Linux, ARM64, dgx-spark]
+    timeout-minutes: 35
+    env:
+      PIP_NO_CACHE_DIR: "1"
+      PYTHONNOUSERSITE: "1"
+    steps:
+      - name: Check out reviewed source
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.0.0
+        with:
+          clean: true
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.0.0
+        with:
+          python-version: "3.12"
+      - name: Activate the verified DGX Tk and Xvfb runtime
+        shell: bash
+        run: |
+          set -euo pipefail
+          runtime=/opt/catalysttwin-actions/shared-gui-runtime
+          test -x "$runtime/usr/bin/Xvfb"
+          test -x "$runtime/usr/bin/xvfb-run"
+          test -f "$runtime/usr/lib/aarch64-linux-gnu/libtk8.6.so"
+          test -d "$runtime/usr/share/tcltk/tk8.6"
+          echo "$runtime/usr/bin" >> "$GITHUB_PATH"
+          echo "LD_LIBRARY_PATH=$runtime/usr/lib/aarch64-linux-gnu:${LD_LIBRARY_PATH:-}" >> "$GITHUB_ENV"
+          echo "TK_LIBRARY=$runtime/usr/share/tcltk/tk8.6" >> "$GITHUB_ENV"
+      - name: Install project and validation tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Ruff format
+        run: python -m ruff format --check .
+      - name: Ruff lint
+        run: python -m ruff check .
+      - name: Strict typing
+        run: python -m mypy
+      - name: Unit, regression, integration, GUI, and import-isolation tests
+        run: xvfb-run -a python -m pytest
+      - name: Scientific and example CLI smoke
+        run: |
+          kineticheck validate
+          kineticheck evaluate examples/operating_point.json --output "$RUNNER_TEMP/kineticheck-point.json"
+          kineticheck batch examples/operating_points.csv --output "$RUNNER_TEMP/kineticheck-batch.xlsx"
+          kineticheck plot examples/operating_points.csv --criterion C_WP --output "$RUNNER_TEMP/kineticheck-envelope.svg"
+      - name: Tk GUI workflow under Xvfb
+        run: xvfb-run -a python -m kineticheck.gui --smoke-test
+      - name: Build and metadata check
+        run: |
+          python -m build
+          python -m twine check dist/*
+      - name: Clean-wheel installation, CLI, GUI, and pip check
+        shell: bash
+        run: |
+          set -euo pipefail
+          wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          clean_env="$RUNNER_TEMP/kineticheck-clean-wheel"
+          python -m venv "$clean_env"
+          "$clean_env/bin/python" -m pip install --no-cache-dir "$wheel"
+          "$clean_env/bin/python" -m pip check
+          "$clean_env/bin/kineticheck" validate
+          xvfb-run -a "$clean_env/bin/python" -m kineticheck.gui --smoke-test
+      - name: Dependency audit
+        run: python -m pip_audit

kineticheck-0.1.0/.github/workflows/macos.yml

@@ -0,0 +1,70 @@
+name: macOS GUI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: kineticheck-macos-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  gui:
+    name: macOS / Tk workflow and clean wheel
+    # Apply the same public-fork trust boundary used for the persistent runner.
+    if: >-
+      github.event_name != 'pull_request' ||
+      (github.actor == github.repository_owner &&
+       github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: macos-15
+    timeout-minutes: 25
+    env:
+      PIP_NO_CACHE_DIR: "1"
+      PYTHONNOUSERSITE: "1"
+    steps:
+      - name: Check out source
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.0.0
+        with:
+          clean: true
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.0.0
+        with:
+          python-version: "3.12"
+      - name: Record platform
+        run: |
+          sw_vers
+          uname -m
+          python --version
+      - name: Install source with GUI and plotting checks
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Focused scientific and CLI smoke
+        run: |
+          python -m pytest --no-cov tests/test_core.py tests/test_units_application.py tests/test_gui.py
+          kineticheck validate
+          kineticheck evaluate examples/operating_point.json --output "$RUNNER_TEMP/point.json"
+      - name: GUI import, workflow, export, close, and process exit
+        run: python -m kineticheck.gui --smoke-test
+      - name: Agg backend isolation smoke
+        run: kineticheck plot examples/operating_points.csv --output "$RUNNER_TEMP/envelope.pdf"
+      - name: Build and clean-wheel smoke
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m build
+          wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          clean_env="$RUNNER_TEMP/kineticheck-macos-wheel"
+          python -m venv "$clean_env"
+          "$clean_env/bin/python" -m pip install --no-cache-dir "$wheel"
+          "$clean_env/bin/python" -m pip check
+          "$clean_env/bin/kineticheck" validate
+          "$clean_env/bin/python" -m kineticheck.gui --smoke-test
+          "$clean_env/bin/python" -c "import sys, kineticheck; assert not any(n.startswith(('PyQt', 'PySide')) for n in sys.modules)"

kineticheck-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build immutable distributions
+    if: github.repository == 'hdkim99/KinetiCheck'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Validate tag and build
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "$GITHUB_REF_NAME" = "v$version"
+          python -m pip install build==1.5.0 twine
+          python -m build
+          python -m twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: kineticheck-distributions-${{ github.run_id }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Trusted Publishing
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/kineticheck/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download immutable distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.0
+        with:
+          name: kineticheck-distributions-${{ github.run_id }}
+          path: dist/
+      - name: Publish with OIDC
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

kineticheck-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+*.egg-info/
+*.py[cod]

kineticheck-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/) and semantic versioning.
+
+## [Unreleased]
+
+## [0.1.0] - pending
+
+- Initial four-criterion scientific core with explicit units and rate basis.
+- JSON API/CLI, CSV/XLSX batch workflow, figure export, and Tkinter GUI.
+- Hand, literature-point, packaging, import-isolation, Linux/DGX, and macOS validation infrastructure.

kineticheck-0.1.0/CITATION.cff

@@ -0,0 +1,15 @@
+cff-version: 1.2.0
+message: "If you use KinetiCheck, please cite the software and the original criterion publications."
+title: "KinetiCheck"
+type: software
+authors:
+  - family-names: "Kim"
+    given-names: "Peter"
+repository-code: "https://github.com/hdkim99/KinetiCheck"
+url: "https://github.com/hdkim99/KinetiCheck"
+version: 0.1.0
+license: BSD-3-Clause
+keywords:
+  - heterogeneous catalysis
+  - reaction engineering
+  - transport limitations

kineticheck-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+Please use a focused issue or pull request and do not upload unpublished or confidential research
+data to a public issue.
+
+A scientific-core change must state the equation or definition, units and rate basis, assumptions,
+validity range, authoritative reference, numerical hand check, boundary/invalid-input behavior, and a
+regression test. Matching a paper's rounded result is not a reason to change a definition silently.
+
+A GUI change must state supported platforms, dependency and backend impact, macOS smoke result, and
+whether CLI/core import isolation remains intact. GUI settings must reach the application service;
+formulas must not be copied into widgets.
+
+Before submitting:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy
+python -m pytest
+python -m build
+python -m twine check dist/*
+```

kineticheck-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Peter Kim
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

kineticheck-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: kineticheck
+Version: 0.1.0
+Summary: Explicit transport-limitation screening for heterogeneous catalytic kinetics.
+Project-URL: Homepage, https://github.com/hdkim99/KinetiCheck
+Project-URL: Documentation, https://github.com/hdkim99/KinetiCheck#readme
+Project-URL: Issues, https://github.com/hdkim99/KinetiCheck/issues
+Project-URL: Repository, https://github.com/hdkim99/KinetiCheck
+Author: Peter Kim
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: catalysis,kinetics,mass-transfer,reaction-engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: <3.15,>=3.10
+Requires-Dist: openpyxl<4,>=3.1.5
+Requires-Dist: pint<0.26,>=0.24.4
+Provides-Extra: dev
+Requires-Dist: build==1.5.0; extra == 'dev'
+Requires-Dist: matplotlib<4,>=3.9; extra == 'dev'
+Requires-Dist: mypy<2,>=1.14; extra == 'dev'
+Requires-Dist: pip-audit<3,>=2.9; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
+Requires-Dist: pytest<10,>=8.3; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.9; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Requires-Dist: types-openpyxl<4,>=3.1.5; extra == 'dev'
+Provides-Extra: gui
+Provides-Extra: plot
+Requires-Dist: matplotlib<4,>=3.9; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# KinetiCheck
+
+**Explicit transport-limitation screening for heterogeneous catalytic kinetics.**
+
+[![CI](https://github.com/hdkim99/KinetiCheck/actions/workflows/ci.yml/badge.svg)](https://github.com/hdkim99/KinetiCheck/actions/workflows/ci.yml)
+[![macOS](https://github.com/hdkim99/KinetiCheck/actions/workflows/macos.yml/badge.svg)](https://github.com/hdkim99/KinetiCheck/actions/workflows/macos.yml)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
+
+![A KinetiCheck batch envelope showing operating points below and above the declared Weisz-Prater threshold](docs/assets/transport-envelope.svg)
+
+KinetiCheck answers a deliberately limited question: *do the selected classical criteria detect a
+significant internal/external heat- or mass-transfer limitation under the stated properties and
+assumptions?* A passing screen is not proof of intrinsic kinetics.
+
+## Why
+
+Published checks often hide whether a rate was per catalyst mass, pellet volume, or bed volume;
+whether diameter or radius was used; and whether a bulk concentration stood in for the pellet-surface
+concentration. KinetiCheck makes those choices machine-readable and includes them in the export.
+
+## Install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install kineticheck
+```
+
+Until the first PyPI release, install from source with `python -m pip install .`. Plot export is optional:
+`python -m pip install "kineticheck[plot]"`. The Tkinter GUI has no third-party GUI dependency, but the
+Python installation must include Tk.
+
+## 30-second example
+
+```bash
+kineticheck evaluate examples/operating_point.json
+kineticheck batch examples/operating_points.csv --output results.xlsx
+kineticheck plot examples/operating_points.csv --criterion C_WP --output envelope.svg
+python -m kineticheck.gui
+```
+
+The included example gives `C_WP = 0.02`, `C_MM = 0.01`, `C_MH ≈ 0.02138`, and
+`C_AH ≈ 0.01069`. Its inputs are pedagogical, not a real catalyst dataset.
+
+## Scientific basis
+
+| Screen | Implemented dimensionless form | Default comparison |
+|---|---|---|
+| Weisz–Prater internal mass | `C_WP = abs(r_obs,V) R_p² / (D_eff C_A,s)` | `C_WP < 0.30` |
+| Mears external mass | `C_MM = abs(r_obs,V) R_p abs(n) / (k_c C_A,b)` | `C_MM < 0.15` |
+| Mears external heat | `C_MH = abs(ΔH_r) abs(r_obs,V) R_p E_a / (h R_g T_b²)` | `C_MH < 0.15` |
+| Anderson internal heat | `C_AH = abs(ΔH_r) abs(r_obs,V) R_p² E_a / (λ_eff R_g T_s²)` | `C_AH < 0.75` |
+
+Each result records its equation, reference, assumptions, threshold, and convention. Thresholds may
+be overridden explicitly. The detailed discussion in [Scientific definitions](docs/scientific-basis.md)
+documents formulation differences rather than presenting a threshold as universal.
+
+## Rate basis and units
+
+Pint distinguishes, among others, `mol kgcat^-1 s^-1`, `mol gcat^-1 h^-1`, and
+`mol m^-3 s^-1`, as well as `m`, `mm`, `µm`, `Pa`, `bar`, `J mol^-1`, and `kJ mol^-1`.
+Mass-catalyst rates require an apparent pellet density. Bed-volume rates require a bed void fraction.
+No implicit conversion between those bases is allowed.
+
+## Validation
+
+- Four-criterion hand calculation with exact intermediate values.
+- Boundary, invalid physical input, mixed-unit, rate-basis, batch CSV/XLSX, CLI, export, and GUI
+  lifecycle tests.
+- Independent reproduction of the `3.910e-5` Mears external-mass value reported in the electronic
+  supplement to RSC article `C5CY00934K`.
+
+No suitably licensed full public operating-point dataset has yet been adopted; **real-data dataset
+validation is pending**. The literature-point reproduction is not described as dataset validation.
+See [validation](docs/validation.md).
+
+## GUI and supported platforms
+
+The GUI uses standard-library Tkinter/ttk. Qt, PyQt, PySide, and PyQtGraph are not dependencies.
+The core/CLI import path does not import Tkinter or matplotlib. Matplotlib is imported only by the
+plot command and uses `Agg`; the Tk GUI currently displays tabular results and therefore does not
+select a matplotlib GUI backend.
+
+- Python package metadata: 3.10–3.14; GUI smoke verified on Python 3.12 and 3.14
+- Linux: scientific CI on the repository DGX ARM64 runner
+- macOS: 15.7.7 hosted and 27.0 local, both on Apple Silicon; older versions are not yet verified
+- Architectures: ARM64 is tested; Intel macOS remains not verified
+
+Run `python -m kineticheck.gui --smoke-test` to exercise window creation, core calculation, JSON
+export, close, and process exit. See [macOS notes](docs/macos.md).
+
+## Limitations
+
+- KinetiCheck screens supplied properties; it does not estimate diffusivity, transfer coefficients,
+  conductivity, or reaction order with unreviewed correlations.
+- Classical local criteria do not replace particle-size/flow-rate experiments, detailed pellet
+  models, reactor energy balances, or uncertainty analysis.
+- A bulk concentration may only stand in for `C_A,s` when the researcher explicitly accepts that
+  assumption.
+- Complex rate laws, strong product inhibition, multiphase wetting, non-spherical characteristic
+  lengths, and coupled runaway behavior can lie outside the implemented screens.
+- No confidence interval is fabricated from deterministic criteria.
+
+## Documentation
+
+- [Scientific definitions and references](docs/scientific-basis.md)
+- [Batch schema](docs/batch-schema.md)
+- [Validation record](docs/validation.md)
+- [Naming and competitive audit](docs/naming-audit.md)
+- [macOS and GUI policy](docs/macos.md)
+- [Contributing](CONTRIBUTING.md)
+
+KinetiCheck is research decision-support software, not process-safety certification software.