nullforge 0.3.0__tar.gz → 0.3.1__tar.gz

{nullforge-0.3.0 → nullforge-0.3.1}/.github/CONTRIBUTING.md

@@ -85,6 +85,40 @@ If any hooks fail, please fix the issues before committing. You can manually run
 prek run --all-files
 ```
 
+### Tasks (via poe)
+
+Every routine check, build and test step is a [poe](https://poethepoet.natn.io/) task.
+Tasks run through poe's `uv` executor, so they resolve their own environment - no `uv run --group ...` prefix needed.
+The bare name is the variant CI runs; a colon suffix selects a mode (`:fix` for auto-fix, `:dev` for the local loop):
+
+```bash
+uv sync                    # create the environment
+uv run poe check           # format + lint + typecheck + lint-imports + deptry (what CI runs)
+uv run poe format          # ruff format --check
+uv run poe format:fix      # ruff format
+uv run poe lint            # ruff check
+uv run poe lint:fix        # ruff check --fix
+uv run poe lint:md         # markdownlint over all Markdown (via prek)
+uv run poe typecheck       # ty check
+uv run poe lint-imports    # import-linter layer contracts
+uv run poe deptry          # dependency hygiene
+uv run poe tests           # pytest with coverage
+uv run poe docs            # strict docs site build (what docs CI runs)
+uv run poe docs:dev        # serve the docs site with live reload
+```
+
+Run `uv run poe check` and `uv run poe tests` before pushing - they are the same checks the pull request runs.
+Markdown is not in `poe check` - the prek hook lints it on every commit and in CI; `uv run poe lint:md` runs it on demand.
+`poe check` does not build the documentation site either, so run `uv run poe docs` when the change touches `docs/`.
+
+### Tests
+
+`uv run poe tests` runs the suite; CI runs it on Python 3.13, 3.14 and 3.15.
+`tests/conftest.py` patches the pyinfra context so rune and operation calls are no-ops - molds, smithy helpers, runes, and templates unit-test without a real target.
+End-to-end correctness is still validated by deploying to a real host.
+
+The suite also enforces the [conventions](https://wlix13.github.io/NullForge/contributing/conventions/).
+
 ## Commits
 
 All commits are expected to follow the conventional commits specification.
@@ -113,8 +147,7 @@ message — please replace that with something descriptive. Examples:
 - `Improve CI/CD caching and test matrix`
 - `Fix swap sizing on small hosts`
 
-A good title reads cleanly in the PR list and the project history. The individual
-**commits** inside the PR still follow Conventional Commits (see [Commits](#commits));
+The individual **commits** inside the PR still follow Conventional Commits (see [Commits](#commits));
 because PRs are merged with a merge/rebase strategy, those commit messages — not the
 title — drive the release changelog, so the title itself does not need a `type:` prefix.
 

{nullforge-0.3.0 → nullforge-0.3.1}/.github/dependabot.yml

@@ -3,7 +3,8 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "cron"
+      cronjob: "0 6 1,15 * *" # twice a month, closest dependabot gets to every two weeks
     commit-message:
       prefix: "chore"
       include: "scope"
@@ -17,7 +18,8 @@ updates:
   - package-ecosystem: "uv"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "cron"
+      cronjob: "0 6 1,15 * *" # twice a month, closest dependabot gets to every two weeks
     commit-message:
       prefix: "chore"
       include: "scope"
@@ -31,7 +33,8 @@ updates:
   - package-ecosystem: "pre-commit"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "cron"
+      cronjob: "0 6 1,15 * *" # twice a month, closest dependabot gets to every two weeks
     commit-message:
       prefix: "chore"
       include: "scope"

{nullforge-0.3.0 → nullforge-0.3.1}/.github/workflows/ci-code-quality.yaml

@@ -25,27 +25,13 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock
 
-      - run: uv sync --all-groups
-
-      - name: Check formatting
-        run: uv run ruff format --check .
-
-      - name: Lint code
-        run: uv run ruff check .
-
-      - name: Type check
-        run: uv run ty check
-
-      - name: Check import contracts
-        run: uv run lint-imports
-
-      - name: Check dependency hygiene
-        run: uv run deptry .
+      - name: Run quality checks
+        run: uv run poe check
 
   hooks:
     name: 🪝 prek hooks
@@ -56,7 +42,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock

{nullforge-0.3.0 → nullforge-0.3.1}/.github/workflows/ci-docs.yaml

@@ -28,10 +28,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock
 
       - name: Build documentation
-        run: uv run --group docs zensical build --clean --strict
+        run: uv run poe docs

{nullforge-0.3.0 → nullforge-0.3.1}/.github/workflows/ci-tests.yaml

@@ -17,22 +17,27 @@ concurrency:
 
 jobs:
   tests:
-    name: 🧪 Tests
+    name: 🧪 Tests (py${{ matrix.python-version }})
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14", "3.15"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock
-          python-version: "3.13"
+          cache-suffix: py${{ matrix.python-version }}
+          python-version: ${{ matrix.python-version }}
 
-      - name: Run tests with coverage
-        run: uv run --group tests pytest
+      - name: Run tests
+        run: uv run poe tests
 
   build:
     name: 📦 Package build check
@@ -43,7 +48,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock

{nullforge-0.3.0 → nullforge-0.3.1}/.github/workflows/deploy-docs.yaml

@@ -32,13 +32,13 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock
 
       - name: Build documentation
-        run: uv run --group docs zensical build --clean --strict
+        run: uv run poe docs
 
       - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
 
@@ -59,4 +59,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

{nullforge-0.3.0 → nullforge-0.3.1}/.github/workflows/release-please.yaml

@@ -52,7 +52,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: false
 
@@ -111,7 +111,9 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
 
       - name: Download distribution artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -122,6 +124,38 @@ jobs:
       - name: Publish to PyPI
         run: uv publish --trusted-publishing always
 
+  publish-photon:
+    name: 📤 Publish to photon-manifest
+    needs: [release-please, build, attest-artifacts]
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: photon
+      url: https://py.wlix13.dev/simple/nullforge/
+    permissions:
+      contents: read
+    steps:
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to photon-manifest
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PHOTON_PUBLISH_TOKEN }}
+        run: |
+          uv auth login https://py.wlix13.dev/simple/ --token "$UV_PUBLISH_TOKEN"
+          uv publish \
+            --publish-url https://py.wlix13.dev/legacy/ \
+            --check-url https://py.wlix13.dev/simple/ \
+            --no-attestations
+
   finalize-release:
     name: 🚀 Attach assets and publish
     needs: [release-please, build, attest-artifacts, publish-pypi]

{nullforge-0.3.0 → nullforge-0.3.1}/.pre-commit-config.yaml

@@ -5,7 +5,7 @@ default_install_hook_types:
   - post-rewrite
 repos:
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.28.0
+    rev: v2.29.4
     hooks:
       - id: pyproject-fmt
 
@@ -19,12 +19,12 @@ repos:
       - id: end-of-file-fixer
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.12.5
+    rev: 0.12.14
     hooks:
       - id: uv-lock
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.3
+    rev: v0.16.7
     hooks:
       - id: ruff-check
         args: [--fix]

nullforge-0.3.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.1"
+}

{nullforge-0.3.0 → nullforge-0.3.1}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.3.1](https://github.com/wlix13/NullForge/compare/v0.3.0...v0.3.1) (2026-09-18)
+
+
+### Features
+
+* **runes:** enhance Podman support with rootless prerequisites and auto-updater ([9c02ab7](https://github.com/wlix13/NullForge/commit/9c02ab7de2196149c500ac6aa3ddd457896af31b))
+
+
+### Bug Fixes
+
+* **docs:** cut repeated and internal detail from docs and contributing guide ([21741ef](https://github.com/wlix13/NullForge/commit/21741efe1a785fc5c3fe3b22b58aaefff43f8e70))
+* **inventories:** keep example presets out of pyinfra group discovery ([73578d6](https://github.com/wlix13/NullForge/commit/73578d65f7ceef892491905cc1c670c2e92f7a04))
+
 ## [0.3.0](https://github.com/wlix13/NullForge/compare/v0.2.0...v0.3.0) (2026-08-28)
 
 

{nullforge-0.3.0 → nullforge-0.3.1}/PKG-INFO

@@ -1,13 +1,15 @@
 Metadata-Version: 2.5
 Name: nullforge
-Version: 0.3.0
+Version: 0.3.1
 Summary: Forge the server's baseline from null
 Author-email: wlix13 <github@wlix13.dev>
 Maintainer-email: wlix13 <github@wlix13.dev>
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: <3.14,>=3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.13
 Requires-Dist: click
 Requires-Dist: pydantic
 Requires-Dist: pyinfra
@@ -18,7 +20,7 @@ Description-Content-Type: text/markdown
 # NullForge
 
 [![PyPI](https://img.shields.io/pypi/v/nullforge?logo=pypi&logoColor=white)](https://pypi.org/project/nullforge/)
-![Python](https://img.shields.io/badge/python-3.13-blue?logo=python&logoColor=white)
+![Python](https://img.shields.io/badge/python-3.13%20%7C%203.14%20%7C%203.15-blue?logo=python&logoColor=white)
 ![Build](https://img.shields.io/github/actions/workflow/status/wlix13/NullForge/ci-tests.yaml?label=build&logo=github)
 ![Lint](https://img.shields.io/github/actions/workflow/status/wlix13/NullForge/ci-code-quality.yaml?label=lint&logo=github)
 ![License](https://img.shields.io/badge/license-MIT-green)

{nullforge-0.3.0 → nullforge-0.3.1}/README.md

@@ -1,7 +1,7 @@
 # NullForge
 
 [![PyPI](https://img.shields.io/pypi/v/nullforge?logo=pypi&logoColor=white)](https://pypi.org/project/nullforge/)
-![Python](https://img.shields.io/badge/python-3.13-blue?logo=python&logoColor=white)
+![Python](https://img.shields.io/badge/python-3.13%20%7C%203.14%20%7C%203.15-blue?logo=python&logoColor=white)
 ![Build](https://img.shields.io/github/actions/workflow/status/wlix13/NullForge/ci-tests.yaml?label=build&logo=github)
 ![Lint](https://img.shields.io/github/actions/workflow/status/wlix13/NullForge/ci-code-quality.yaml?label=lint&logo=github)
 ![License](https://img.shields.io/badge/license-MIT-green)

{nullforge-0.3.0 → nullforge-0.3.1}/docs/concepts/architecture.md

@@ -58,4 +58,4 @@ The [conventions](../contributing/conventions.md) around `host.loop` and change
 ## The CLI wrapper
 
 `nullforge cast` is a thin planner around pyinfra: it resolves the [cast stages](../getting-started/cli.md#stages) and hands them to pyinfra.
-Everything else - connections, facts, operations, parallelism - is stock pyinfra, which is why unknown CLI options are proxied through verbatim.
+Everything else is stock pyinfra, which is why unknown CLI options are proxied through verbatim.

{nullforge-0.3.0 → nullforge-0.3.1}/docs/concepts/inventories.md

@@ -44,20 +44,15 @@ common = (
 features = merge_features(BASE_FEATURES, *common, {"dns": {"ecs": True}})
 ```
 
-The set of allowed sub-mold types is derived from `FeaturesMold.model_fields`, so a new feature is mergeable without touching the merge logic.
-
 !!! warning "Deep-merge is per-key"
 
     Dictionaries merge recursively, but any non-dict value - including lists - replaces the previous value outright.
     A layer that sets `netsec.firewall_rules` replaces the whole rule list; extend `BASE_FEATURES.netsec.firewall_rules` in Python if you want "default rules plus mine".
 
-Because inventories are Python, you can factor shared preset tuples, per-environment modules, or host loops however you like - the only contract is the final `hosts` list.
-
 ## Validation and coercion
 
-The foundry coerces whatever the inventory provided - `None`, a `dict`, or a mold instance - into validated `SystemMold` / `FeaturesMold` objects before any rune runs (`ensure_system` / `ensure_features`).
+The foundry coerces whatever the inventory provided - `None`, a `dict`, or a mold instance - into validated `SystemMold` / `FeaturesMold` objects before any rune runs.
 Missing keys fall back to mold defaults; unknown keys are rejected because every mold forbids extra fields.
-A typo like `{"warp": {"instal": True}}` fails the cast at validation time, before anything touches a host.
 
 ## Scaling to a fleet
 
@@ -143,20 +138,12 @@ for zone in ZONE_FEATURES:
 nullforge cast -i inventory/main.py --limit web --dry
 ```
 
-Details worth stealing:
-
-- `entry.get("overrides")` is either a dict fragment or `None` - both are valid `merge_features` layers, so per-host overrides cost one line and still go through mold validation.
-- Extra data keys (like `zone` above) ride along on `host.data` untouched; [custom runes](../guides/custom-runes.md) can branch on them.
-- Adding a host is a YAML edit, reviewable in a PR and scriptable from CI.
-
-This is the pattern behind the deploy repo of the **Conglomerate** proxy fleet: zone presets over NullForge molds, a YAML host registry edited from CI workflows, and per-zone `--limit` casts.
-
 ## Secrets in inventories
 
 Inventories are code; secrets in them (tunnel tokens, proxy user secrets) end up on disk.
 Keep real inventories out of public repos, or load secrets from the environment.
 
-Mold fields marked sensitive (user password, Zero Trust token, Nezha secrets, Telemt users) are redacted as `***` in pyinfra's `--debug-inventory` output, so inspecting a plan does not leak them.
+Sensitive mold fields are redacted as `***` in pyinfra's `--debug-inventory` output, so inspecting a plan does not leak them.
 
 ## Debugging
 

{nullforge-0.3.0 → nullforge-0.3.1}/docs/concepts/molds.md

@@ -9,7 +9,7 @@ Every mold extends `BaseMold` (`nullforge/molds/base_mold.py`), which sets the s
 
 - **`extra="forbid"`** - unknown keys are validation errors, so typos fail the cast instead of silently deploying defaults.
 - **`is_active`** - the activation protocol used for [rune dispatch](runes.md#dispatch); each feature sub-mold implements it.
-- **`to_json()`** - JSON-mode serialization for pyinfra's `--debug-inventory`, with `_sensitive_fields` values redacted as `***` (recursively, through nested molds, lists and dicts).
+- **`to_json()`** - JSON-mode serialization for pyinfra's `--debug-inventory`, with `_sensitive_fields` values redacted as `***`.
 
 ## The top-level molds
 
@@ -17,23 +17,7 @@ Two molds cover a host:
 
 - **`SystemMold`** - base system state: packages, locales, timezone, hostname, swap, IPv6.
   Consumed by the always-on [base rune](../features/base.md).
-- **`FeaturesMold`** - one field per feature, each a sub-mold with its own defaults:
-
-```python
-class FeaturesMold(BaseMold):
-    warp: WarpMold = Field(default_factory=WarpMold)
-    dns: DnsMold = Field(default_factory=DnsMold)
-    users: UserMold = Field(default_factory=UserMold)
-    netsec: NetSecMold = Field(default_factory=NetSecMold)
-    profiles: ProfilesMold = Field(default_factory=ProfilesMold)
-    zerotrust: ZeroTrustTunnelMold = Field(default_factory=ZeroTrustTunnelMold)
-    containers: ContainersMold = Field(default_factory=ContainersMold)
-    monitoring: MonitoringMold = Field(default_factory=MonitoringMold)
-    haproxy: HaproxyMold = Field(default_factory=HaproxyMold)
-    xray: XrayCoreMold = Field(default_factory=XrayCoreMold)
-    tor: TorMold = Field(default_factory=TorMold)
-    telemt: TelemtMold = Field(default_factory=TelemtMold)
-```
+- **`FeaturesMold`** - one field per feature, each a sub-mold with its own defaults.
 
 Field order is deploy order.
 Everything else is derived from these fields - the allowed [merge layers](inventories.md), the feature-to-mold mapping, and rune dispatch - so adding a feature means adding a field, not editing plumbing.
@@ -66,4 +50,3 @@ dns = DnsMold(mode=DnsMode.DOT_RESOLVED)
 ```
 
 `nullforge.molds` exports only the molds.
-The split is enforced by an import contract: models import nothing from the rest of the package.

{nullforge-0.3.0 → nullforge-0.3.1}/docs/concepts/runes.md

@@ -13,43 +13,6 @@ Runes are executed, not imported.
 The foundry (or the selective `cast.py`) pulls each one in with pyinfra's `local.include`, so the module-level code runs at deploy time with `host` bound to the current target.
 Every rune file defines a `deploy_*()` function and calls it at the bottom.
 
-A typical rune:
-
-```python
-"""Tor proxy deployment module."""
-
-from pyinfra.context import host
-from pyinfra.operations import files, systemd
-
-from nullforge.molds import FeaturesMold, TorMold
-from nullforge.smithy.packages import get_pm
-from nullforge.templates import get_template_path
-
-
-def deploy_tor() -> None:
-    features: FeaturesMold = host.data.features
-    tor_opts: TorMold = features.tor
-
-    get_pm().install(name="Install Tor package", packages=["tor"], _sudo=True)
-
-    config = files.template(
-        name="Deploy Tor proxy configuration",
-        src=get_template_path("tor/torrc.j2"),
-        dest="/etc/tor/torrc",
-        SOCKS_PORT=tor_opts.socks_port,
-        DNS_PORT=tor_opts.dns_port,
-        _sudo=True,
-    )
-
-    systemd.service(service="tor", restarted=True, _sudo=True, _if=config.did_change)
-    systemd.service(service="tor", running=True, enabled=True, _sudo=True)
-
-
-deploy_tor()
-```
-
-The pattern to note: configuration comes from `host.data`, distro differences go through the smithy (`get_pm()`), and service restarts are guarded by [change detection](../contributing/conventions.md#change-detection).
-
 ## Dispatch
 
 The full cast derives its rune list from `FeaturesMold` itself:
@@ -60,8 +23,6 @@ The full cast derives its rune list from `FeaturesMold` itself:
 The rune name defaults to the field name (`warp` -> `runes/warp.py`).
 A sub-mold can override it with `_feature_rune = "other-name"`, or opt out of dispatch with `_feature_rune = None`.
 
-The resulting deploy order is the [feature table](../features/index.md) top to bottom, filtered to active features.
-
 ## Independence
 
 No rune imports another rune.

{nullforge-0.3.0 → nullforge-0.3.1}/docs/contributing/conventions.md

@@ -1,7 +1,6 @@
 # Conventions
 
 The rules below keep casts deterministic and idempotent.
-Most are enforced by tests or CI; the reasoning is documented here so violations are recognizable in review.
 
 ## host.loop
 
@@ -34,17 +33,15 @@ systemd.daemon_reload(..., _if=config.did_change)
 - Prefer a **conditional** "restart on change" plus an **unconditional** "ensure running/enabled".
 - `_if=` expects callables (or a list of them).
   `_if=op.will_change` passes a bare boolean and is silently ignored - always `did_change`/`did_succeed` references.
-- Plain `if op.will_change:` is for **prepare-time decisions that emit more operations** only (rare - the GRUB regeneration in `base.py` is the canonical case).
+- Plain `if op.will_change:` is for **prepare-time decisions that emit more operations** only.
 
 ## Version-pinned installers
 
 Installers for pinned tools guard with `is_pinned_version_installed(tool, binary_path)` - not a bare `File` fact - so a pin bump triggers re-install.
-Past the guard, call `install_release_binary()` rather than hand-rolling download/extract: it force-downloads, verifies the sha256 when one is passed or resolved from GitHub release metadata (best-effort - when no checksum is available it installs unverified and logs a warning), extracts any archive kind, and returns the install `OperationMeta` for restart chaining.
+Past the guard, call `install_release_binary()` rather than hand-rolling download/extract: it force-downloads, verifies the sha256 when one is passed or resolved from GitHub release metadata, extracts any archive kind, and returns the install `OperationMeta` for restart chaining.
 
 Keep the guard at the call site: checksum resolution makes a plan-time API call, so the helper should only be reached when an install is actually pending.
 
-Non-fitting installers stay custom: source builds (tmux), AppImage-to-directory extraction (nvim), and non-GitHub / `latest` / multi-binary downloads (gVisor).
-
 ## Downloads
 
 Every `curl` NullForge runs on a target takes its options from `smithy.http.curl_args(url)` - `curl_args_str(url)` for hand-written commands, `Versions.release_curl_args(url)` for GitHub release assets - never the bare `CURL_ARGS` dict.
@@ -60,13 +57,8 @@ Handle return values instead: `FileContents` is `None` for a missing or unreadab
 
 Files users are expected to edit (`.zshrc`, nvim's `init.lua`) are written with `files.block` and a `{mark}` marker - never `files.template` - so everything outside the markers survives re-deploys.
 
-`.zshrc` prepends its block (`before=True, after=True`) so user lines come last and win.
-A file predating the markers is detected via the `Block` fact returning `[]` and cleared once with `files.line(line=".*", present=False, backup=True)` - otherwise the block would be prepended to a stale copy of itself.
-
 ## Code style
 
 - Private helpers within rune/smithy files are `_`-prefixed.
 - Type annotations everywhere; `ty` is the checker.
-- Line length 120; ruff rules `E, F, I, N, S, UP, W, YTT`.
 - [Import-layer contracts](../concepts/architecture.md#layer-contracts) are part of `poe check` - new modules must respect the spine.
-- Docs prose is one sentence per line; markdownlint runs over all Markdown via prek.

nullforge-0.3.1/docs/contributing/development.md

@@ -0,0 +1,26 @@
+# Development
+
+Tasks, tests, commit conventions and the pull request flow are in [CONTRIBUTING.md](https://github.com/wlix13/NullForge/blob/main/.github/CONTRIBUTING.md); this page covers setup and the documentation site.
+
+## Setup
+
+Only [uv](https://docs.astral.sh/uv/) is supported:
+
+```bash
+git clone https://github.com/wlix13/NullForge
+cd NullForge
+uv sync
+uv run prek install   # git hooks via prek
+```
+
+## Documentation
+
+The site is built with [zensical](https://zensical.org) from `docs/` and `zensical.toml`:
+
+```bash
+uv run poe docs:dev   # http://localhost:8000, live reload
+uv run poe docs       # strict build into site/
+```
+
+All docs are Markdown, linted by markdownlint (`.markdownlint-cli2.jsonc`; MD013 is off - prose is written one sentence per line).
+CI builds the site strictly on docs PRs and deploys `main` to GitHub Pages.

{nullforge-0.3.0 → nullforge-0.3.1}/docs/features/base.md

@@ -15,10 +15,10 @@ Fresh images without `sudo`: use [`--with-prepare`](../getting-started/cli.md#st
 
 Deploys the system baseline, in order:
 
-1. **IPv6 stack** - when `ensure_ipv6` is set and GRUB carries `ipv6.disable=...`, strips it and regenerates the GRUB config (Debian `update-grub` or RHEL `grub2-mkconfig`).
+1. **IPv6 stack** - when `ensure_ipv6` is set and GRUB carries `ipv6.disable=...`, strips it and regenerates the GRUB config.
 2. **Hostname** - sets the hostname, writes it to `/etc/hosts` with the host's primary IP, and pins `preserve_hostname: true` in cloud-init so reboots keep it.
 3. **Packages** - refreshes and upgrades, then installs `packages_base` (names are [mapped per distro](../concepts/architecture.md)).
-4. **curl** - installs a pinned static `curl` to `/usr/local/bin` (removing the distro package on Debian, symlinking the CA bundle path on RHEL); falls back to the repo package when no static build fits the architecture.
+4. **curl** - installs a pinned static `curl` to `/usr/local/bin`; falls back to the repo package when no static build fits the architecture.
 5. **doggo** - a pinned DNS client for debugging resolvers.
 6. **Locales** - resolves each requested locale against what the target can generate, enables it in `/etc/locale.gen`, and runs `locale-gen` when needed.
 7. **Timezone** and **NTP** - `systemd-timesyncd` on Debian/Ubuntu, `chrony` (with a forced initial sync) on RHEL.
@@ -35,7 +35,7 @@ Deploys the system baseline, in order:
 | `swap` | see below | Swap configuration |
 | `ensure_ipv6` | `true` | Repair a GRUB-disabled IPv6 kernel stack |
 
-`hostname` is validated as a proper FQDN (labels, length, charset) at plan time.
+`hostname` is validated as a proper FQDN at plan time.
 
 ### Swap (`system.swap`)
 
@@ -52,7 +52,7 @@ The two types are mutually exclusive - enabling one dismantles the other, so swi
 !!! note "swappiness vs netsec"
 
     [Network security](netsec.md) also sets `vm.swappiness` (default `10`) in its sysctl group.
-    With swap enabled, the swap value is the effective one - its sysctl file sorts later; keep the two intentionally aligned.
+    With swap enabled, the swap value is the effective one - keep the two intentionally aligned.
 
 ## Example
 

{nullforge-0.3.0 → nullforge-0.3.1}/docs/features/containers.md

@@ -29,6 +29,11 @@ A container runtime with a sandboxed-by-default configuration.
 
 Installs `podman`, `podman-compose`, and the `crun` runtime from distro packages - no scripts, no extra repos.
 
+Rootless prerequisites come along: `passt` (the `pasta` network backend) and `uidmap` on Debian/Ubuntu (`shadow-utils` on RHEL) for `newuidmap`/`newgidmap`.
+
+`podman-auto-update.timer` is enabled system-wide.
+When `users.manage` is on, the [managed user](users.md) also gets lingering enabled (`loginctl enable-linger`) and the same timer enabled in its user session, so rootless containers labelled `io.containers.autoupdate` are refreshed daily.
+
 ## Configuration (`features.containers`)
 
 | Field | Default | Description |

{nullforge-0.3.0 → nullforge-0.3.1}/docs/features/dns.md

@@ -22,7 +22,6 @@ Switching modes converges: `dot_resolved` stops and disables the Blocky services
   Wildcard and loopback addresses use existing interfaces.
 - Renders `/etc/blocky/config.yaml` with DoH upstreams from the selected provider (IPv6 upstreams included only when the host has IPv6).
 - Points `/etc/resolv.conf` directly at the Blocky address, replacing any symlink.
-- Restarts Blocky only when the binary, config, or unit changed.
 
 ### `dot_resolved`
 

{nullforge-0.3.0 → nullforge-0.3.1}/docs/features/index.md

@@ -25,5 +25,3 @@ Turning a default-on feature off is a one-line layer:
 ```python
 merge_features(BASE_FEATURES, {"dns": {"mode": "none"}, "profiles": {"for_root": False}})
 ```
-
-Every page in this section documents the feature's behaviour, its configuration fields with defaults, and an inventory fragment to start from.