kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge-3.0.0.dev0.dist-info/METADATA

@@ -0,0 +1,609 @@
+Metadata-Version: 2.4
+Name: kivyforge
+Version: 3.0.0.dev0
+Summary: Declarative, PEP 621-aligned build toolchain for Kivy apps — successor to kivy-ios, python-for-android, and buildozer (iOS, Android, macOS, Linux, and Windows)
+Author-email: The Kivy Team <kivy-dev@googlegroups.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ElliotGarbus/kivyforge
+Project-URL: Source, https://github.com/ElliotGarbus/kivyforge
+Project-URL: Bug Reports, https://github.com/ElliotGarbus/kivyforge/issues
+Keywords: kivy,ios,android,toolchain,packaging,mobile,buildozer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: packaging>=24
+Requires-Dist: pbxproj>=3.5
+Requires-Dist: tomli-w>=1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: Pillow>=10; extra == "dev"
+Provides-Extra: linux
+Requires-Dist: Pillow>=10; extra == "linux"
+Provides-Extra: windows
+Requires-Dist: Pillow>=10; extra == "windows"
+Provides-Extra: android
+Requires-Dist: Pillow>=10; extra == "android"
+Dynamic: license-file
+
+# kivyforge
+
+
+[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](https://opencollective.com/kivy)
+[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](https://opencollective.com/kivy)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)
+
+![PyPI - Version](https://img.shields.io/pypi/v/kivyforge)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/kivyforge)
+
+[![kivyforge](https://github.com/ElliotGarbus/kivyforge/actions/workflows/kivyforge.yml/badge.svg)](https://github.com/ElliotGarbus/kivyforge/actions/workflows/kivyforge.yml)
+
+kivyforge is a declarative, [PEP 621](https://peps.python.org/pep-0621/)-aligned
+build toolchain for [Kivy](https://kivy.org) (and other Python) apps. You
+describe your app once in `pyproject.toml`; kivyforge resolves your dependencies
+into a lockfile and packages the app for the platform you target. It is the
+successor to **kivy-ios**, **python-for-android**, and **buildozer**, unifying
+their per-platform workflows behind a single declarative configuration.
+
+The goal is one toolchain for every platform Kivy runs on — **Android, iOS,
+Linux, macOS, and Windows**.
+
+> **Status: early development — iOS + macOS + Linux + Windows + Android.**
+> kivyforge targets **iOS** (resolve into `pylock.ios.toml`, download the official
+> [`Python.xcframework`](https://www.python.org/downloads/) + prebuilt iOS
+> wheels, generate an [Xcode](https://developer.apple.com/xcode/) project),
+> **macOS** (resolve into `pylock.macos.toml`, bundle a relocatable
+> [python-build-standalone](https://github.com/astral-sh/python-build-standalone)
+> CPython + wheels into a signed, double-clickable `.app`), **Linux** (resolve
+> into `pylock.linux.toml`, bundle a PBS gnu/glibc CPython + manylinux wheels into
+> an [AppImage](https://appimage.org/) — with a run-from-folder AppDir substrate),
+> **Windows** (resolve into `pylock.windows.toml`, bundle a PBS MSVC CPython +
+> `win_amd64` wheels into a run-from-folder `onedir` with a windowed launcher
+> `.exe`, optionally Authenticode-signed), and **Android** (resolve into
+> `pylock.android.toml`, assemble the official
+> [python.org Android runtime](https://www.python.org/downloads/android/) +
+> per-ABI `android_*` wheels into a generated Gradle project, and produce a
+> signed `.apk`/`.aab` — with pyjnius as a prebuilt wheel, no per-app
+> compilation). If you need a shipping toolchain today, use kivy-ios 2.x,
+> python-for-android, or buildozer.
+
+### Currently supported targets
+
+| Target | Architectures | Output | Signing | Build host |
+|---|---|---|---|---|
+| [iOS](https://www.apple.com/ios/) device | arm64 (iPhone / iPad) | generated Xcode project → `.app` | Apple Developer signing via Xcode | macOS + [Xcode](https://developer.apple.com/xcode/) |
+| iOS Simulator | arm64 | generated Xcode project → `.app` | none required | macOS + Xcode |
+| [Android](https://www.android.com/) device / emulator | `arm64_v8a`, `x86_64` | generated Gradle/AGP project → `.apk` / `.aab` | auto debug keystore, or release keystore (v1–v4 schemes) | Windows, macOS, or Linux + JDK/Android SDK/NDK |
+| [macOS](https://www.apple.com/macos/) | arm64 (Apple Silicon) | `.app` | ad-hoc (default) **or** Developer ID sign + notarize + staple | macOS (Apple Silicon) |
+| [Linux](https://appimage.org/) | x86_64 (glibc ≥ 2.17) | `.AppImage` / AppDir | none | Linux |
+| [Windows](https://learn.microsoft.com/windows/) | amd64 | `onedir` folder + windowed launcher `.exe` | optional Authenticode (unsigned by default) | Windows |
+
+Desktop targets (macOS / Linux / Windows) bundle a self-contained runtime +
+wheels; on Linux, libGL/EGL and X11/Wayland come from the host. Building for iOS
+requires a Mac with Xcode; Android builds on any of the three desktop hosts.
+
+**Apple targets are Apple Silicon only.** kivyforge does not build Intel (`x86_64`)
+macOS apps or pin the Intel iOS-Simulator slice: macOS 27 stops installing on
+Intel hardware and macOS 28 removes Rosetta, so an Intel slice would be one
+nothing can execute or validate. `universal2` *wheels* are still resolved
+normally — they contain arm64.
+
+kivyforge builds on the work of the [Kivy Team](https://kivy.org/about.html).
+
+## Requirements
+
+Each target platform has its own host requirements. **Building for iOS requires
+macOS** (Xcode-based), so the iOS workflow below is useful only on a Mac:
+
+- macOS with [Xcode](https://developer.apple.com/xcode/) installed, either from
+  the [Mac App Store](https://apps.apple.com/app/xcode/id497799835) or from the
+  command line:
+
+      xcode-select --install
+
+- Accept the Xcode license once:
+
+      sudo xcodebuild -license
+
+**Building for Android** works from Windows, macOS, or Linux, and needs three
+user-installed prerequisites (kivyforge never installs a host toolchain — it only
+detects one):
+
+- A **JDK 17+** on `PATH` or `JAVA_HOME`.
+- The **Android SDK** (`ANDROID_HOME`/`ANDROID_SDK_ROOT`), with the `compile_sdk`
+  platform, build-tools, platform-tools, and accepted licenses
+  (`sdkmanager --licenses`). Android Studio's SDK Manager covers all of it.
+- The **NDK** — required for *every* Android build, not just apps with native
+  code: it compiles the bootstrap's native launcher (`libmain.so`).
+
+`kivyforge doctor -p android` checks each of these and prints the `sdkmanager`
+command for whatever is missing. Add an AVD (or attach a device with USB debugging
+enabled) before `kivyforge run`.
+
+## Installation
+
+Use a Python virtual environment (host Python 3.13+). This is required: it
+isolates the toolchain and keeps its lockfile resolution from being polluted by
+packages in your system Python.
+
+      python3 -m venv .venv
+      . .venv/bin/activate
+
+Install kivyforge from this repository (it is not yet published to PyPI):
+
+      pip install -e ".[dev]"
+
+> **Mobile examples need no local wheel-building.** Kivy (2.3.1 and 3.0),
+> pyobjus, and pyjnius resolve from the
+> [kivy-mobile-wheels](https://github.com/ElliotGarbus/kivy-mobile-wheels)
+> index — a companion repo of first-party iOS/Android cross-builds published as
+> a static PEP 503 index — so `kivyforge lock` just works against any mobile
+> example. `scripts/build_ios_wheels.sh` / `scripts/build_pyobjus_ios_wheels.sh`
+> remain for cross-building your own iOS wheels locally (e.g. to vendor one via
+> a `path` lock instead of the index); neither is required to run the examples.
+>
+> **Desktop needs no wheel-building either.** The desktop examples under
+> [`examples/desktop/`](examples/desktop/) build straight from PyPI — Kivy
+> 2.3.1 ships universal2 macOS wheels, so there is no macOS wheel-building
+> step. Kivy 3.0 has no public desktop wheels yet, which is why desktop
+> examples stay on 2.3.1; the iOS mobile examples need 3.0 for its structural
+> mobile changes, while the Android examples run either generation (2.3.1/SDL2
+> for most, 3.0/SDL3 for `hello-sdl3`) depending on which bootstrap they gate.
+
+> **Detailed documentation.** For the full design and reference docs — the
+> cross-platform model, the `pyproject.toml` / `pylock.<platform>.toml` schemas,
+> artifact distribution, the CLI shape, and the per-platform backends (Android,
+> iOS, macOS, Linux, Windows) — start with the
+> [kivyforge design overview](docs/design/common/00-overview.md).
+
+## Quick start (iOS)
+
+The workflow below targets iOS; see Quick start (Android), (macOS), (Linux),
+and (Windows) further down for the other backends. Run every command from the
+directory that contains your app's `pyproject.toml`.
+
+      # 1. Seed [tool.kivy] / [tool.kivy.ios] config into pyproject.toml
+      kivyforge init
+
+      # 2. Resolve dependencies into pylock.ios.toml
+      kivyforge lock
+
+      # 3. Download artifacts and generate <app>-ios/<app>.xcodeproj
+      kivyforge build
+
+      # 4a. Open the project in Xcode and press Run...
+      kivyforge open
+
+      # 4b. ...or build, install, and launch on the simulator from the CLI
+      kivyforge build --simulator
+      kivyforge run --simulator
+
+## Quick start (macOS)
+
+macOS needs only the Xcode command-line tools (`codesign`), not the full Xcode
+IDE. The macOS backend bundles a relocatable CPython + your wheels into a signed
+`.app`:
+
+      # 1. Seed [tool.kivy] / [tool.kivy.macos] config (or add the overlay by hand)
+      kivyforge init            # then add a [tool.kivy.macos] table
+
+      # 2. Resolve dependencies + pin the runtime into pylock.macos.toml
+      kivyforge lock -p macos
+
+      # 3. Build the .app (arm64)
+      kivyforge build -p macos
+
+      # 4a. Launch it (foreground, so you see stdout/tracebacks)
+      kivyforge run -p macos
+
+      # 4b. ...or produce the finished, signed distributable
+      kivyforge package -p macos      # -> build/macos/<App>.app
+
+`package` is config-driven: with no signing config it ships the **ad-hoc**-signed
+`.app` (runs locally; downloaded copies hit Gatekeeper). For distribution to
+other Macs, configure `[tool.kivy.macos.signing]` with a *Developer ID
+Application* identity (paid Apple Developer Program) and a `notary_profile`
+(created with `xcrun notarytool store-credentials`) — then the same command
+deep-signs with Hardened Runtime, **notarizes, and staples** the `.app` so
+Gatekeeper trusts it everywhere. `--no-notarize` skips the submission. (Hit
+`errSecInternalComponent` from `codesign`? See the
+[FAQ entry](FAQ.md#macos-developer-id-signing-fails-with-errsecinternalcomponent)
+on corrupted keychain ACLs.)
+
+`kivyforge doctor -p macos` reports environment + project health (host, codesign,
+arch coverage, runtime floor, signing identity, notary setup, reachable hosts).
+
+## Quick start (Linux)
+
+The Linux backend bundles a relocatable CPython + your manylinux wheels into an
+[AppImage](https://appimage.org/) (the default) or a run-from-folder **AppDir**.
+It needs a Linux host (the runtime is a gnu/glibc build); no compiler or FUSE is
+required at build time.
+
+      # 1. Add a [tool.kivy.linux] table to pyproject.toml (app_id, icons, ...)
+
+      # 2. Resolve dependencies + pin the runtime into pylock.linux.toml
+      kivyforge lock -p linux
+
+      # 3. Build the AppDir (build/linux/<App>.AppDir)
+      kivyforge build -p linux
+
+      # 4a. Launch it (runs ./AppRun directly — the fast dev loop, no FUSE)
+      kivyforge run -p linux
+
+      # 4b. ...or produce the distributable
+      kivyforge package -p linux              # -> dist/linux/<app>-<ver>-x86_64.AppImage
+      kivyforge package -p linux -f folder    # -> the AppDir itself
+
+The AppImage embeds a **static-FUSE runtime**, so recipients need no `libfuse2`;
+`./<App>.AppImage --appimage-extract-and-run` is the universal no-FUSE fallback.
+The **host contract** is explicit: the bundle never vendors libGL/libEGL or a
+display server, so the host must provide glibc ≥ the artifact's effective floor,
+`libGL.so.1`/`libEGL.so.1`, and an X11 or Wayland session.
+
+`kivyforge doctor -p linux` reports environment + project health (Linux/glibc
+host, GL libraries, display session, glibc floor, arch coverage, generated
+`.desktop` validity, reachable hosts).
+
+## Quick start (Windows)
+
+The Windows backend bundles a relocatable CPython + your `win_amd64` wheels into
+a run-from-folder **`onedir`**: a windowed launcher `.exe` beside a full
+python-build-standalone prefix, your app source, and any declared native
+binaries. It needs a Windows host (the runtime is an MSVC amd64 build and the
+resource/signing tools are Windows-only); no compiler is required at build time.
+
+      # 1. Add a [tool.kivy.windows] table to pyproject.toml (app_id, icons, ...)
+
+      # 2. Resolve dependencies + pin the runtime into pylock.windows.toml
+      kivyforge lock -p windows
+
+      # 3. Build the onedir bundle (build\windows\<App>\)
+      kivyforge build -p windows
+
+      # 4a. Launch it (runs the launcher .exe in the foreground — the dev loop)
+      kivyforge run -p windows
+
+      # 4b. ...or produce the distributable (copied to dist\windows\)
+      kivyforge package -p windows            # -> dist\windows\<app>-<ver>-amd64\
+
+Double-clicking the launcher opens the app with **no console flash**; `kivyforge
+run` attaches it to the terminal so stdout/stderr and tracebacks are visible. The
+`onedir` folder keeps every file real and signable — installers stay external.
+**Authenticode signing** is optional and off by default: configure
+`[tool.kivy.windows.signing]` with a certificate-store `thumbprint` and `package`
+signs (and RFC-3161 timestamps) the launcher in the `dist\windows` copy.
+
+`kivyforge doctor -p windows` reports environment + project health (Windows host,
+long-path support, `app_id` style, arch coverage, icon, native-binary
+sources/collisions/arch, build-output lock, build volume (Dev Drive advisory),
+reachable hosts, signtool + signing certificate).
+
+## Quick start (Android)
+
+The Android backend assembles the official
+[python.org Android runtime](https://www.python.org/downloads/android/) + your
+`android_*` wheels into a generated **Gradle/AGP** project and produces a
+signed **`.apk`** (sideload/CI) or **`.aab`** (Play upload) — a wheel-assembly
+and Gradle-drive backend, no python-for-android recipe system, no per-app C
+compilation. It needs a JDK, the Android SDK, and the NDK, but builds on
+Windows, macOS, or Linux. 64-bit only (`arm64_v8a`, `x86_64`).
+
+      # 1. Seed [tool.kivy] + [tool.kivy.android] into pyproject.toml
+      kivyforge init -p android               # then set `package`, kivy_generation, ...
+
+      # 2. Resolve dependencies + pin the runtime into pylock.android.toml
+      kivyforge lock -p android
+
+      # 3. Generate the Gradle project (<app>-android/) and assemble a debug APK
+      kivyforge build -p android --debug      # -> <app>-android/app/build/outputs/apk/debug/
+
+      # 4a. Install and launch on a connected device or emulator
+      kivyforge run -p android --emulator
+
+      # 4b. ...or produce the signed release distributable
+      kivyforge package -p android            # -> <app>-android/app/build/outputs/apk/release/
+      kivyforge package -p android -f aab     # -> .../outputs/bundle/release/ (Play upload)
+
+Without `--debug`, step 3 stops after generating the project — ready to open in
+Android Studio (`kivyforge open -p android`) or to drive `gradlew` by hand.
+
+`kivy_generation = 2` targets Kivy 2.3.1 (SDL2, stable); `kivy_generation = 3`
+targets Kivy 3.0 (SDL3, pre-release) — mutually exclusive per app, and the SDL
+Java glue + `libSDL*.so` must come from the same release (`kivyforge build`
+fails fast on a mismatch rather than the silent black-screen failure that
+would otherwise produce).
+Debug builds sign with an auto-managed debug keystore; `package` requires a
+configured release keystore (`[tool.kivy.android.signing]`, passwords from
+environment variables, never in `pyproject.toml`).
+
+`kivyforge doctor -p android` reports environment + project health
+(JDK/SDK/build-tools/NDK/emulator/adb, the SDL↔Kivy pairing, the pyjnius
+`invoke0` contract, a hermetic 16 KB page-alignment scanner, ABI coverage,
+signing, lock-host reachability). `kivyforge run --smoke` runs a generated
+instrumented contract test on a real device/emulator — validated on an x86_64
+API-31 emulator and a Pixel 8a (Android 16 / API 36) for both SDL2 and SDL3.
+
+See the runnable examples for complete, copy-pasteable walk-throughs. They are
+split by runtime requirement — **desktop uses Kivy 2.3.1 from PyPI, mobile
+resolves Kivy (2.3.1 and 3.0) from the
+[kivy-mobile-wheels](https://github.com/ElliotGarbus/kivy-mobile-wheels)
+index**:
+
+**Desktop** ([`examples/desktop/`](examples/desktop/)) — macOS/Linux/Windows:
+
+- [`dice-roller`](examples/desktop/dice-roller/) — minimal Kivy UI that **builds &
+  runs on macOS, Linux, and Windows today** from PyPI (Kivy 2.3.1).
+- [`notes`](examples/desktop/notes/) — Kivy app with a pure-Python dependency
+  (`platformdirs`); builds on macOS, Linux, and Windows from PyPI.
+- [`desktop-viewer`](examples/desktop/desktop-viewer/) — a **macOS-only** Kivy app
+  (resizable window, ⌘ keyboard shortcuts, and Finder's native open panel via
+  `osascript`); no Linux/Windows overlay.
+- [`hello-native`](examples/desktop/hello-native/) — ships **non-wheel** native
+  binaries (a helper executable + a shared library) via
+  `[tool.kivy.<platform>.native.binaries]`; builds and runs on macOS, Linux, and
+  Windows (`greet.dll` loaded by name, `roll.exe` run by name).
+
+**Mobile** ([`examples/mobile/`](examples/mobile/)) — iOS and Android; iOS on
+Kivy 3.0, Android on either generation (wheels from
+[`kivy-mobile-wheels`](https://github.com/ElliotGarbus/kivy-mobile-wheels)):
+
+*iOS:*
+
+- [`hello-world`](examples/mobile/hello-world/) — Kivy-free toolchain smoke test;
+  no dependencies, no wheels (builds on iOS via the python.org `Python.xcframework`;
+  the first example to bring up a new backend).
+- [`hello-kivy`](examples/mobile/hello-kivy/) — minimal Kivy 3.0 UI.
+- [`mobile-geometry`](examples/mobile/mobile-geometry/) — showcases the
+  `kivy.mobile` runtime-geometry API (DPI, safe-area insets, keyboard height).
+- [`svg-explorer`](examples/mobile/svg-explorer/) — interactive SVG viewer
+  (multitouch pan/zoom/rotate).
+- [`pyobjus-ball`](examples/mobile/pyobjus-ball/) — calls native iOS APIs
+  (CoreMotion, UIScreen) from Python via the Objective-C runtime.
+- [`pyobjus-deviceinfo`](examples/mobile/pyobjus-deviceinfo/) — reads native iOS
+  device info (model, system version, battery) via pyobjus; a CPython 3.15
+  pre-release example.
+- [`keychain-spm`](examples/mobile/keychain-spm/) — declares a remote Swift Package
+  (`KeychainAccess`), pins it with `kivyforge lock`, and calls it from Python
+  through a local `@objc` shim package.
+
+*Android:*
+
+- [`hello-android`](examples/mobile/hello-android/) — the smallest kivyforge
+  Android app (a single `Label`); the Kivy 2.3.1 / SDL2 on-device gate.
+- [`hello-sdl3`](examples/mobile/hello-sdl3/) — the same app on **Kivy 3.0 /
+  SDL3**; deliberately identical to `hello-android` apart from the SDL
+  generation, and the SDL3 on-device gate.
+- [`pyjnius-deviceinfo`](examples/mobile/pyjnius-deviceinfo/) — reads Android
+  device info (`Build`, `BatteryManager`, display metrics) via pyjnius, no
+  Java written.
+- [`qr-maven`](examples/mobile/qr-maven/) — renders a QR code with Google's
+  ZXing, resolved as a Gradle/Maven coordinate (channel 4) and driven from
+  Python via a pyjnius `invoke0` round-trip.
+
+## Configuring your app
+
+Your app is described declaratively in `pyproject.toml`. Standard
+[PEP 621](https://peps.python.org/pep-0621/) `[project]` metadata supplies the
+name, version, and runtime `dependencies`; shared, platform-neutral settings live
+under `[tool.kivy]`, and iOS-specific settings live under `[tool.kivy.ios]`
+(other platforms will add their own `[tool.kivy.<platform>]` tables):
+
+```toml
+[project]
+name = "hello-world"
+version = "0.1.0"
+requires-python = ">=3.15.0b4"
+dependencies = []                       # PyPI/local deps resolved into the lockfile
+
+[tool.kivy]
+display_name = "Hello World"            # name shown under the icon
+app_dir = "src"                         # folder containing your Python source
+entry_point = "main"                    # module imported at launch (main.py)
+orientation = ["portrait"]
+
+[tool.kivy.ios]
+bundle_id = "org.example.hello-world"   # reverse-DNS; UTI characters only (no underscores)
+build = 1
+deployment_target = "13.0"
+# find_links = ["../../wheels/ios"]     # repo-relative wheel directory for lock
+# exclude = ["docutils", "pygments"]    # drop transitive deps you don't use at runtime
+
+[tool.kivy.ios.python]
+version = "3.15.0b4"                     # python.org Python.xcframework version
+
+[tool.kivy.ios.signing]
+team_id = ""                            # Apple Developer Team ID (device / release builds)
+identity = "Apple Development"
+auto_signing = true
+```
+
+`kivyforge build` syncs your `app_dir` into the generated `<app>-ios/` tree on
+every run, so make changes in your source folder (e.g. `src/`), never in the
+generated project.
+
+Kivy's wheel declares dependencies that are not all needed at runtime on iOS.
+The `exclude` list trims them; the
+[hello-kivy example](examples/mobile/hello-kivy/pyproject.toml) documents what each one
+is for, so you can re-enable only the few that map to widgets you actually use
+(e.g. `docutils` for `RSTDocument`, `pygments` for `CodeInput`, or `requests`
+for `UrlRequest`).
+
+## Commands
+
+The verbs are platform-neutral; each resolves a target from `-p/--platform`, the
+`KIVYFORGE_PLATFORM` environment variable, or the host default, and then does the
+platform's version of the same job.
+
+      kivyforge init       Seed [tool.kivy] + the target's overlay into pyproject.toml
+      kivyforge lock       Generate pylock.<platform>.toml from pyproject.toml
+      kivyforge build      Download artifacts, generate the native project, build
+      kivyforge run        Build (unless --no-build), install, and launch the app
+      kivyforge package    Produce the signed, distributable artifact
+      kivyforge open       Open the generated project in Xcode / Android Studio
+      kivyforge status     Show app identity, Python version, lock sync, build state
+      kivyforge clean      Remove generated artifacts in the project folder
+      kivyforge upgrade    Re-fetch the pinned runtime and native artifacts
+      kivyforge doctor     Run environment and project health checks
+
+Run `kivyforge <command> -h` (or `kf <command> -h`) for the full set of
+options on any verb. A few common ones:
+
+- `kivyforge lock --check` — CI pre-flight; exits non-zero if the lock is stale.
+- `kivyforge build --simulator | --device | --release` (iOS) — pick the build flavor.
+- `kivyforge build --debug [--abi arm64_v8a|x86_64]` (Android) — assemble a debug APK, optionally for one ABI.
+- `kivyforge run --list-devices` — list available simulators/emulators and devices.
+- `kivyforge run --smoke` (Android) — run the generated on-device contract test.
+- `kivyforge clean --cache` — also flush the artifact download cache.
+
+Downloaded artifacts (`Python.xcframework`, the per-ABI Android runtime,
+`.aar`/`.jar`s, runtime archives) are cached per-user and shared across projects.
+
+## Typical workflow
+
+A normal session is a one-time setup followed by a tight edit → run loop. You only
+re-run `kivyforge lock` when dependencies change, and `kivyforge build` when you
+change app config (or need to regenerate the native project).
+
+How cheap the inner loop is depends on the platform. On **iOS** the generated
+project *links* your source directory (`app/` is a symlink to `app_dir`), so
+editing Python source needs no rebuild — just relaunch. On **Android** the app's
+code is packed into the APK's asset bundle, so a source edit needs a re-pack:
+`kivyforge run` does that for you every iteration, which is why the Android loop
+goes through `run` rather than a bare relaunch.
+
+```mermaid
+flowchart TD
+    A["kivyforge init<br/>seed pyproject.toml"] --> B["Edit pyproject.toml<br/>dependencies + app config"]
+    B --> C["Write your app<br/>src/main.py"]
+    C --> D["kivyforge lock<br/>→ pylock.&lt;platform&gt;.toml"]
+    D --> E["kivyforge build<br/>fetch artifacts + generate the native project"]
+    E --> F{"Launch it"}
+    F -->|from the CLI| G["kivyforge run<br/>--simulator / --emulator / --device"]
+    F -->|from the IDE| H["kivyforge open → Xcode ⌘R / Android Studio Run"]
+    G --> I(["Iterate"])
+    H --> I
+    I -->|changed Python source| F
+    I -->|changed app config| E
+    I -->|changed dependencies| D
+```
+
+Supporting commands fit around this loop: `kivyforge status` shows whether your
+lock and build are current, `kivyforge doctor` diagnoses environment problems,
+`kivyforge upgrade` re-fetches the pinned runtime, and `kivyforge clean` resets
+the generated project when you want a fresh build.
+
+## Development
+
+Clone the repository and install it into a virtual environment:
+
+      git clone https://github.com/ElliotGarbus/kivyforge.git
+      cd kivyforge/
+      python3 -m venv .venv
+      . .venv/bin/activate
+      pip install -e ".[dev]"
+
+Run the test suite and the linter:
+
+      pytest
+      ruff check .
+
+## FAQ
+
+For troubleshooting advice and other frequently asked questions, consult
+the latest 
+[kivyforge FAQ](https://github.com/ElliotGarbus/kivyforge/blob/master/FAQ.md).
+
+## License
+
+kivyforge is [MIT licensed](LICENSE), and builds on work actively developed by a
+great community and supported by many projects managed by the 
+[Kivy Organization](https://www.kivy.org/about.html).
+
+## Support
+
+Are you having trouble using kivyforge or any of its related projects in the Kivy
+ecosystem?
+Is there an error you don’t understand? Are you trying to figure out how to use 
+it? We have volunteers who can help!
+
+The best channels to contact us for support are listed in the latest 
+[Contact Us](https://github.com/ElliotGarbus/kivyforge/blob/master/CONTACT.md) document.
+
+## Contributing
+
+kivyforge builds on the [Kivy](https://kivy.org) ecosystem - a large group of
+products used by many thousands of developers for free, but it
+is built entirely by the contributions of volunteers. We welcome (and rely on) 
+users who want to give back to the community by contributing to the project.
+
+Contributions can come in many forms. See the latest 
+[Contribution Guidelines](https://github.com/ElliotGarbus/kivyforge/blob/master/CONTRIBUTING.md)
+for how you can help us.
+
+## Code of Conduct
+
+In the interest of fostering an open and welcoming community, we as 
+contributors and maintainers need to ensure participation in our project and 
+our sister projects is a harassment-free and positive experience for everyone. 
+It is vital that all interaction is conducted in a manner conveying respect, 
+open-mindedness and gratitude.
+
+Please consult the [latest Kivy Code of Conduct](https://github.com/kivy/kivy/blob/master/CODE_OF_CONDUCT.md).
+
+## Contributors
+
+This project exists thanks to 
+[all the people who contribute](https://github.com/ElliotGarbus/kivyforge/graphs/contributors).
+[[Become a contributor](CONTRIBUTING.md)].
+
+<img src="https://contrib.nn.ci/api?repo=ElliotGarbus/kivyforge&pages=5&no_bot=true&radius=22&cols=18">
+
+## Backers
+
+Thank you to [all of our backers](https://opencollective.com/kivy)! 
+🙏 [[Become a backer](https://opencollective.com/kivy#backer)]
+
+<img src="https://opencollective.com/kivy/backers.svg?width=890&avatarHeight=44&button=false">
+
+## Sponsors
+
+Special thanks to 
+[all of our sponsors, past and present](https://opencollective.com/kivy).
+Support this project by 
+[[becoming a sponsor](https://opencollective.com/kivy#sponsor)].
+
+Here are our top current sponsors. Please click through to see their websites,
+and support them as they support us. 
+
+<!--- See https://github.com/orgs/kivy/discussions/15 for explanation of this code. -->
+<a href="https://opencollective.com/kivy/sponsor/0/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/0/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/1/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/1/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/2/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/2/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/3/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/3/avatar.svg"></a>
+
+<a href="https://opencollective.com/kivy/sponsor/4/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/4/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/5/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/5/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/6/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/6/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/7/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/7/avatar.svg"></a>
+
+<a href="https://opencollective.com/kivy/sponsor/8/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/8/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/9/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/9/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/10/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/10/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/11/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/11/avatar.svg"></a>
+
+<a href="https://opencollective.com/kivy/sponsor/12/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/12/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/13/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/13/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/14/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/14/avatar.svg"></a>
+<a href="https://opencollective.com/kivy/sponsor/15/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/15/avatar.svg"></a>