chore(repo): stop tracking build artifacts; add README, license metadata, ruff config

Untrack iso/out/ (3.4 GB ISO), packaging/*/pkg/ trees, *.pkg.tar.zst and tanin-icons/src/ (529 files) and ignore them going forward. Files stay on disk. NOTE: history still carries ~13 GiB of old ISO blobs — needs a git filter-repo pass (see README/report). Also: first README.md, license + license-files in pyproject, minimal ruff config, demo scripts moved to scripts/demo/. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 21:21:28 +02:00
parent e8d93e6b1d
commit 774809a579
535 changed files with 104 additions and 36530 deletions
@@ -0,0 +1,80 @@
+# TANINUX
+
+Arch-based Linux distro (codename **camel**) built around the
+[niri](https://github.com/YaLTeR/niri) scrollable-tiling Wayland compositor and
+a GTK4 desktop with its own accent/theming system. Ships a central
+maintenance TUI/GUI plus a small suite of first-party apps, distributed via a
+custom `[tanin]` pacman repo and a Calamares-based installer ISO.
+
+## The pillars
+
+The central `taninux` app is organized around five pillars:
+
+- **maintain** — scan and clean up (orphans, caches, leftover kernel modules)
+- **update** — aggregate updates from pacman, AUR and flatpak
+- **kernel** — install/remove kernel variants, boot-default management
+- **suggest** — rule-based setup suggestions
+- **health** — system health checks
+
+## The apps
+
+| Command | What it is |
+|---|---|
+| `taninux` | Maintenance TUI (Textual) |
+| `taninux-gtk` | GTK4 shell |
+| `tsettings` | Settings app (network, display, audio, users, …) |
+| `thub` | Software Hub (repo/AUR/flatpak install) |
+| `tfiles` | Native GTK4 file manager |
+| `tmusic` | Music app |
+
+The GTK apps run on a custom libadwaita-free backend
+(`src/taninux/gui/ui/native.py` + `style_apple.css`); `TANINUX_UI=adw`
+selects the libadwaita backend.
+
+## Installing
+
+### On an existing Arch system
+
+Add the `[tanin]` repo to `/etc/pacman.conf` (see
+[docs/distribution.md](docs/distribution.md)), then:
+
+```sh
+pacman -S tanin-desktop   # full desktop: niri + eww shell + apps
+pacman -S taninux         # just the maintenance tool
+```
+
+### Via the ISO
+
+See [iso/BUILD.md](iso/BUILD.md) — archiso profile with a Calamares
+installer (btrfs subvolume layout, snapper/snap-pac).
+
+## Repo layout
+
+```
+src/taninux/    Python source: cli, gui, core, pillars, files, music
+packaging/      PKGBUILDs + helper scripts for the [tanin] repo packages
+iso/            archiso profile (build-profile/ + overrides/) and BUILD.md
+distro/         distro-level manifest (camel.toml, MANIFEST.md)
+docs/           distribution plan, eww integration contracts
+scripts/demo/   visual QA scripts for the native UI backend
+```
+
+## Development
+
+```sh
+uv venv && uv pip install -e ".[gui]"   # PyGObject/GTK4 come from pacman
+taninux                                  # TUI
+TANINUX_UI=native tsettings              # settings app, native backend
+python scripts/demo/page_demo.py         # render single pages for visual QA
+```
+
+## Building packages
+
+```sh
+cd packaging/<pkg> && makepkg -si        # single package
+./packaging/build-tanin-repo.sh          # rebuild the whole [tanin] repo
+```
+
+## License
+
+GPL-3.0-or-later — see [LICENSE](LICENSE).