nullforge 0.2.0__tar.gz → 0.3.0__tar.gz

{nullforge-0.2.0 → nullforge-0.3.0}/.github/labeler.yaml

@@ -19,9 +19,11 @@ labels:
     files:
       - '^README\.md$'
       - "^docs/"
+      - '^zensical\.toml$'
   - label: "ci-cd"
     files:
       - '^\.github/'
+      - '^\.markdownlint-cli2\.jsonc$'
   - label: "tests"
     files:
       - "^tests/"

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

@@ -25,7 +25,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock
@@ -41,6 +41,12 @@ jobs:
       - 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 .
+
   hooks:
     name: 🪝 prek hooks
     runs-on: ubuntu-latest
@@ -50,7 +56,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock

nullforge-0.3.0/.github/workflows/ci-docs.yaml

@@ -0,0 +1,37 @@
+name: 📚 Docs build check
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/ci-docs.yaml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: 📚 Build documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Build documentation
+        run: uv run --group docs zensical build --clean --strict

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

@@ -25,7 +25,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock
@@ -43,7 +43,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock

nullforge-0.3.0/.github/workflows/deploy-docs.yaml

@@ -0,0 +1,62 @@
+name: 📚 Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/deploy-docs.yaml"
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: 📚 Build documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Build documentation
+        run: uv run --group docs zensical build --clean --strict
+
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    name: 🚀 Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

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

@@ -52,7 +52,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: false
 
@@ -95,7 +95,7 @@ jobs:
           path: dist/
 
       - name: Generate artifact attestations
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
         with:
           subject-path: dist/*
 
@@ -111,7 +111,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
 
       - name: Download distribution artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1

nullforge-0.3.0/.markdownlint-cli2.jsonc

@@ -0,0 +1,25 @@
+{
+  "gitignore": true,
+
+  // Generated, boilerplate and vendored - not authored to this style.
+  "ignores": [
+    "CHANGELOG.md",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/ISSUE_TEMPLATE/**",
+  ],
+
+  "config": {
+    "default": true,
+
+    // Prose is one sentence per line; tables pad cells but not the delimiter row.
+    "MD013": false,
+    "MD060": false,
+
+    "MD046": false,
+
+    // mkdocs admonition blocks
+    "MD033": {
+      "allowed_elements": ["div"],
+    },
+  },
+}

{nullforge-0.2.0 → nullforge-0.3.0}/.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.25.3
+    rev: v2.28.0
     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.11.32
+    rev: 0.12.5
     hooks:
       - id: uv-lock
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.0
+    rev: v0.16.3
     hooks:
       - id: ruff-check
         args: [--fix]
@@ -40,3 +40,8 @@ repos:
       - id: python-no-log-warn
       - id: python-use-type-annotations
       - id: text-unicode-replacement-char
+
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.23.2
+    hooks:
+      - id: markdownlint-cli2

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

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

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

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.3.0](https://github.com/wlix13/NullForge/compare/v0.2.0...v0.3.0) (2026-08-28)
+
+
+### ⚠ BREAKING CHANGES
+
+* **molds:** deploy warp before other features
+* **smithy:** fall back to WARP interface for filtered downloads
+
+### Features
+
+* **molds:** deploy warp before other features ([a97cbfe](https://github.com/wlix13/NullForge/commit/a97cbfe9020bf0708acec4adf370cfa7113ea964))
+* **smithy:** fall back to WARP interface for filtered downloads ([25f0b28](https://github.com/wlix13/NullForge/commit/25f0b28cb7d0efb89cf7710aa922d52a9651c985))
+
+
+### Documentation
+
+* describe WARP download fallback ([8b57441](https://github.com/wlix13/NullForge/commit/8b57441c8ecc234db4f9131e5ab9a603e3384b4c))
+* **site:** add documentation ([d6b8575](https://github.com/wlix13/NullForge/commit/d6b857541d8ed35a5fe8fa3a32cdef95d8d8bf8c))
+
 ## [0.2.0](https://github.com/wlix13/NullForge/compare/v0.1.0...v0.2.0) (2026-07-25)
 
 

nullforge-0.3.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: nullforge
+Version: 0.3.0
+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
+Requires-Dist: click
+Requires-Dist: pydantic
+Requires-Dist: pyinfra
+Requires-Dist: rich
+Requires-Dist: rich-click
+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)
+![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)
+![uv](https://img.shields.io/badge/package%20manager-uv-blueviolet?logo=astral)
+![Ruff](https://img.shields.io/badge/linter-ruff-orange?logo=ruff)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0075ca?logo=materialformkdocs&logoColor=white)](https://wlix13.github.io/NullForge/)
+
+Forge the server's baseline from null - an infrastructure-as-code framework built on [pyinfra](https://pyinfra.com), themed around a blacksmith's forge: **inventories** define hosts, **molds** shape the configuration, **runes** are idempotent operation sets, the **foundry** casts them onto targets, and the **smithy** holds cross-distro helpers.
+
+> [!WARNING]
+> **NullForge is in active development.** Until the `v1.0.0` release, the CLI, mold schemas and deploy behaviour may change at any time - breaking changes can land in **any** release, including patch versions. Pin an exact version (e.g. `nullforge==0.2.0`) and check the [release notes](https://github.com/wlix13/NullForge/releases) before upgrading.
+
+## Install
+
+```bash
+uv tool install nullforge
+```
+
+## Documentation
+
+Everything else - getting started, concepts, the full feature reference, and guides - lives at **[wlix13.github.io/NullForge](https://wlix13.github.io/NullForge/)**.
+
+## Contributing
+
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the full setup, commit conventions and pull request flow.

nullforge-0.3.0/README.md

@@ -0,0 +1,29 @@
+# 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)
+![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)
+![uv](https://img.shields.io/badge/package%20manager-uv-blueviolet?logo=astral)
+![Ruff](https://img.shields.io/badge/linter-ruff-orange?logo=ruff)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0075ca?logo=materialformkdocs&logoColor=white)](https://wlix13.github.io/NullForge/)
+
+Forge the server's baseline from null - an infrastructure-as-code framework built on [pyinfra](https://pyinfra.com), themed around a blacksmith's forge: **inventories** define hosts, **molds** shape the configuration, **runes** are idempotent operation sets, the **foundry** casts them onto targets, and the **smithy** holds cross-distro helpers.
+
+> [!WARNING]
+> **NullForge is in active development.** Until the `v1.0.0` release, the CLI, mold schemas and deploy behaviour may change at any time - breaking changes can land in **any** release, including patch versions. Pin an exact version (e.g. `nullforge==0.2.0`) and check the [release notes](https://github.com/wlix13/NullForge/releases) before upgrading.
+
+## Install
+
+```bash
+uv tool install nullforge
+```
+
+## Documentation
+
+Everything else - getting started, concepts, the full feature reference, and guides - lives at **[wlix13.github.io/NullForge](https://wlix13.github.io/NullForge/)**.
+
+## Contributing
+
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the full setup, commit conventions and pull request flow.

nullforge-0.3.0/docs/concepts/architecture.md

@@ -0,0 +1,61 @@
+# Architecture
+
+NullForge is a thin, opinionated layer over pyinfra.
+Every layer has one job, and imports only flow downward.
+
+## Data flow
+
+```mermaid
+flowchart TB
+    subgraph plan [Control node]
+        CLI[cli - nullforge cast] --> FY["foundry - full_cast.py / cast.py"]
+        INV[inventories] --> FY
+        FY --> RN["runes/*.py"]
+        RN --> SM[smithy]
+        RN --> TP["templates (Jinja2)"]
+        MD["molds (Pydantic)"] --> INV
+        MD --> RN
+        ML["models (domain types)"] --> MD
+    end
+    RN -->|pyinfra operations over SSH| HOSTS[(Target hosts)]
+```
+
+1. **Inventories** define hosts and attach `system` and `features` data, built by [merging layers](inventories.md) over the defaults.
+2. The **foundry** is the deploy entry point.
+   `full_cast.py` coerces inventory data through the molds, always includes `prepare` then `base`, and then includes the rune of every active feature.
+   `cast.py` is the selective variant used by `nullforge cast -r ...`.
+3. **Runes** are self-contained pyinfra operation sets - one file per concern.
+   They read validated configuration from `host.data` and emit idempotent operations.
+4. **Molds** are Pydantic schemas for all configuration; [`FeaturesMold`](molds.md) composes the per-feature sub-molds.
+5. **Models** hold pure domain types and constants consumed by molds.
+6. The **smithy** provides cross-distro abstractions: package-name mapping (apt/dnf), release-binary installs with checksum verification, version pinning, networking facts, swap, service users.
+7. **Templates** are Jinja2 files for systemd units, service configs, and shell profiles.
+
+## Layer contracts
+
+The layering is enforced by import contracts:
+
+| Contract | Meaning |
+| --- | --- |
+| Deploy spine | `cli` -> `foundry` -> `runes` -> `smithy` -> `molds`/`templates` -> `models`; a layer may import only layers below it |
+| Models are pure | `models` imports no other NullForge package |
+| Templates are a leaf | `templates` imports no other NullForge package, `models` included - its spine position only says which layers may import *it* |
+| Molds describe, never provision | `molds` cannot import runes, smithy, or templates |
+| Runes are independent | no rune imports another rune |
+
+Why rune independence matters - and how runes coordinate without it - is covered in [Runes](runes.md#independence).
+
+## Execution model
+
+pyinfra runs in two phases:
+
+1. **Plan** - fact gathering and operation collection on the control node.
+   Python-level branching (`if host.get_fact(...)`) happens here.
+2. **Execute** - the collected operations run against each host, in a deterministic order shared by all hosts.
+
+The [conventions](../contributing/conventions.md) around `host.loop` and change detection exist to keep that shared ordering stable.
+
+## 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.

nullforge-0.3.0/docs/concepts/inventories.md

@@ -0,0 +1,165 @@
+# Inventories
+
+An inventory is a standard [pyinfra inventory](https://docs.pyinfra.com/en/3.x/inventory-data.html): a Python file with a `hosts` list.
+Each host is either a bare address or an `(address, data)` tuple.
+NullForge reads two data keys - `system` and `features` - plus an optional `versions` map for [pin overrides](../guides/version-pinning.md).
+
+```python
+from nullforge.molds.defaults import BASE_FEATURES, BASE_SYSTEM
+from nullforge.molds.utils import merge_features, merge_system
+
+hosts = [
+    (
+        "203.0.113.10",
+        {
+            "system": merge_system(BASE_SYSTEM, {"hostname": "node1.example.com"}),
+            "features": merge_features(BASE_FEATURES, ...),
+        },
+    ),
+]
+```
+
+## Defaults and layering
+
+`BASE_SYSTEM` and `BASE_FEATURES` (from `nullforge.molds.defaults`) are plain default-constructed molds.
+`merge_system` / `merge_features` (from `nullforge.molds.utils`) start from a base and deep-merge each layer in order - later layers win.
+
+A features layer can be any of:
+
+| Layer type | Example |
+| --- | --- |
+| Full `FeaturesMold` | another host's merged result |
+| Any feature sub-mold | `WarpMold(install=True)` - merged under its own key |
+| `dict` fragment | `{"warp": {"install": True}}` (sub-molds allowed as values) |
+| `None` | skipped; useful for conditional layers |
+
+```python
+from nullforge.molds import DnsMold, UserMold, WarpMold
+
+common = (
+    UserMold(manage=True, name="core"),
+    WarpMold(install=True),
+)
+
+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`).
+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
+
+Inventories are Python, so fleet structure is ordinary code.
+A pattern that works well in practice: per-zone feature presets, a YAML host registry, and a small builder that turns them into pyinfra groups.
+
+Shared mold instances compose into one `FeaturesMold` per zone:
+
+```python title="inventory/zones.py"
+from nullforge.models.netsec import SshHostKeyType
+from nullforge.molds import ContainersMold, FeaturesMold, FirewallRule, HaproxyMold, NetSecMold, SshMold, UserMold
+from nullforge.molds.defaults import BASE_FEATURES
+from nullforge.molds.utils import merge_features
+
+netsec = NetSecMold(
+    firewall_rules=[
+        FirewallRule(port=443, comment="HTTPS"),
+        FirewallRule(port=22, proto="tcp", from_ip="203.0.113.7", comment="Admin SSH"),
+    ],
+    ssh=SshMold(host_keys=[SshHostKeyType.ED25519]),
+)
+
+users = UserMold(name="ops", fetch_key_from_github="your-github-username")
+
+ZONE_FEATURES: dict[str, FeaturesMold] = {
+    "web": merge_features(BASE_FEATURES, netsec, users, HaproxyMold(install=True)),
+    "workers": merge_features(BASE_FEATURES, netsec, users, ContainersMold(install=True)),
+}
+```
+
+Host membership lives in data, not code - one YAML entry per host, with an optional `overrides` fragment deep-merged onto the zone preset:
+
+```yaml title="inventory/hosts.yaml"
+web:
+  - address: 203.0.113.10
+    hostname: web1.example.com
+  - address: 203.0.113.11
+    hostname: web2.example.com
+    overrides:
+      netsec:
+        firewall: false
+workers:
+  - address: 203.0.113.20
+    hostname: worker1.example.com
+```
+
+The builder exposes one module-level list per zone - pyinfra treats each as a named group, so `--limit web` targets a whole zone:
+
+```python title="inventory/main.py"
+from pathlib import Path
+
+import yaml
+
+from nullforge.molds.defaults import BASE_SYSTEM
+from nullforge.molds.utils import merge_features, merge_system
+
+from inventory.zones import ZONE_FEATURES
+
+DATA: dict = yaml.safe_load((Path(__file__).parent / "hosts.yaml").read_text()) or {}
+
+
+def _build(zone: str) -> list:
+    rows = []
+    for entry in DATA.get(zone, []):
+        rows.append(
+            (
+                entry["address"],
+                {
+                    "zone": zone,
+                    "system": merge_system(BASE_SYSTEM, {"hostname": entry["hostname"]}),
+                    "features": merge_features(ZONE_FEATURES[zone], entry.get("overrides")),
+                },
+            )
+        )
+    return rows
+
+
+for zone in ZONE_FEATURES:
+    globals()[zone] = _build(zone)
+```
+
+```bash
+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.
+
+## Debugging
+
+```bash
+nullforge cast -i inventory.py --debug-inventory   # dump merged host data (pass-through to pyinfra)
+```

nullforge-0.3.0/docs/concepts/molds.md

@@ -0,0 +1,69 @@
+# Molds
+
+Molds are Pydantic models that shape and validate every piece of NullForge configuration.
+If a value reaches a rune, it went through a mold first.
+
+## BaseMold
+
+Every mold extends `BaseMold` (`nullforge/molds/base_mold.py`), which sets the shared behaviour:
+
+- **`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).
+
+## The top-level molds
+
+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)
+```
+
+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.
+
+## Activation
+
+Every feature sub-mold implements `is_active`.
+Most simply return `self.install`; the exceptions encode their own semantics:
+
+- `DnsMold` - active while `mode != "none"`.
+- `UserMold` - active while `manage` is true.
+- `ProfilesMold` - active while `for_root` or `for_user` is true.
+
+A sub-mold may also rename its rune or opt out of automatic dispatch - see [dispatch](runes.md#dispatch).
+
+## Validation beyond types
+
+Molds validate coherence, not just shapes - a bad combination fails at plan time with a readable error, never mid-deploy.
+Each [feature page](../features/index.md) documents its own validators.
+
+## Models vs molds
+
+Domain types and constants - `DnsMode`, `Shell`, `WarpEngineType`, `SwapType`, ... - live in `nullforge.models.<domain>` and are imported from there directly:
+
+```python
+from nullforge.models.dns import DnsMode
+from nullforge.molds import DnsMold
+
+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.