From 075a749940d300329f36cd20115bd1bbab547505 Mon Sep 17 00:00:00 2001
From: Jason Bowman <jason@json64.dev>
Date: Tue, 25 Aug 2026 10:20:32 -0700
Subject: [PATCH 1/2] docs: cover undocumented public surface and fix stale API
 references
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds documentation for public features that shipped without docs, and
corrects code comments still pointing at the removed adapter API.

New page — explanation/structural-introspection:
  entity.hasAspect / entity.aspects, meta.handleWith with
  den.lib.aspects.fx.constraints (exclude / substitute / filterBy and
  their .global variants), and the lib-level building blocks. Covers
  where hasAspect is safe to call and why includes is not.

Reference and guide additions:
  - pipe.broadcast stage semantics + worked fleet example
  - conditional aspects (meta.guard / meta.aspects) via policy.when
  - den.batteries.flake-scope
  - built-in policy tables: os-to-host, user-to-host, the home-env
    family, wsl, and the flake-parts pair
  - den.schema collection fields (isEntity, isolated, parent,
    collisionPolicy) and the den.schema.aspect base module
  - den.classes fields: description, forwardTo, parentPath, parentArg
  - den.reservedKeys, den.systems, flat host/home declaration forms
  - policy deliver/route guard + adaptArgs, route collectSubtree and
    the intoPath alias, custom instantiate specs, resolve.shared.to
  - captureFleet, resolveWithPaths / resolveWithState
  - class-module arg promotion for descendant entity kinds

Corrections to existing docs:
  - collision policy resolves over four levels, not three
  - stale battery anchors in the sidebar and tutorials
  - lib.mdx linked to a nonexistent /reference/options/ page

Code comments only (no behaviour change):
  has-aspect.nix and the example template referenced oneOfAspects,
  excludeAspect, meta.adapter and adapters.nix, none of which still
  exist; they now point at meta.handleWith + fx.constraints.
---
 docs/astro.config.mjs                         |  42 ++--
 .../content/docs/explanation/parametric.mdx   |  22 ++
 .../src/content/docs/explanation/policies.mdx |   9 +
 .../explanation/structural-introspection.mdx  | 212 ++++++++++++++++++
 docs/src/content/docs/guides/batteries.mdx    |  14 ++
 .../content/docs/guides/configure-aspects.mdx |   7 +
 .../content/docs/guides/custom-classes.mdx    |  37 +++
 docs/src/content/docs/guides/quirks.mdx       |  51 +++++
 docs/src/content/docs/reference/aspects.mdx   |  71 +++++-
 docs/src/content/docs/reference/batteries.mdx |  26 +++
 docs/src/content/docs/reference/diag.mdx      |  14 ++
 docs/src/content/docs/reference/lib.mdx       |  44 +++-
 docs/src/content/docs/reference/output.mdx    |  14 ++
 docs/src/content/docs/reference/policies.mdx  |  62 ++++-
 docs/src/content/docs/reference/quirks.mdx    |  31 ++-
 docs/src/content/docs/reference/schema.mdx    |  44 +++-
 docs/src/content/docs/tutorials/default.mdx   |   6 +-
 docs/src/content/docs/tutorials/minimal.mdx   |   2 +-
 modules/context/has-aspect.nix                |   5 +-
 .../modules/aspects/hasAspect-examples.nix    |  14 +-
 20 files changed, 677 insertions(+), 50 deletions(-)
 create mode 100644 docs/src/content/docs/explanation/structural-introspection.mdx

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index ae94f3549..47c37e957 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -61,6 +61,7 @@ export default defineConfig({
 								{ label: 'Aspects & Functors', slug: 'explanation/aspects' },
 								{ label: 'Class Modules', slug: 'explanation/class-modules' },
 								{ label: 'Parametric Aspects', slug: 'explanation/parametric' },
+							{ label: 'Structural Introspection', slug: 'explanation/structural-introspection', badge: { text: 'advanced', variant: 'caution' } },
 							],
 						},
 						{
@@ -130,26 +131,27 @@ export default defineConfig({
 							label: 'Batteries',
 							collapsed: true,
 							items: [
-								{ label: 'define-user — OS user accounts', link: '/reference/batteries/#den_define-user' },
-								{ label: 'hostname — set system hostname', link: '/reference/batteries/#den_hostname' },
-								{ label: 'os-class — cross-platform os class', link: '/reference/batteries/#den_os-class' },
-								{ label: 'os-user — user class forwarding', link: '/reference/batteries/#den_os-user' },
-								{ label: 'primary-user — admin privileges', link: '/reference/batteries/#den_primary-user' },
-								{ label: 'user-shell — login shell', link: '/reference/batteries/#den_user-shell' },
-								{ label: 'mutual-provider — host↔user config', link: '/reference/batteries/#den_mutual-provider' },
-								{ label: 'host-aspects — project host classes', link: '/reference/batteries/#den_host-aspects' },
-								{ label: 'tty-autologin — TTY auto-login', link: '/reference/batteries/#den_tty-autologin' },
-								{ label: 'vm-autologin — auto-login for VMs', link: '/reference/batteries/#den_vm-autologin' },
-								{ label: 'wsl — WSL support', link: '/reference/batteries/#den_wsl' },
-								{ label: 'forward — custom class factory', link: '/reference/batteries/#den_forward' },
-								{ label: 'import-tree — legacy module import', link: '/reference/batteries/#den_import-tree' },
-								{ label: 'home-manager — HM integration', link: '/reference/batteries/#den_home-manager' },
-								{ label: 'hjem — hjem integration', link: '/reference/batteries/#den_hjem' },
-								{ label: 'maid — nix-maid integration', link: '/reference/batteries/#den_maid' },
-								{ label: 'unfree — allow unfree packages', link: '/reference/batteries/#den_unfree' },
-								{ label: 'insecure — allow insecure packages', link: '/reference/batteries/#den_insecure' },
-								{ label: "inputs' — flake-parts inputs", link: '/reference/batteries/#den_inputs' },
-								{ label: "self' — flake-parts self outputs", link: '/reference/batteries/#den_self' },
+								{ label: 'define-user — OS user accounts', link: '/reference/batteries/#denbatteriesdefine-user' },
+								{ label: 'hostname — set system hostname', link: '/reference/batteries/#denbatterieshostname' },
+								{ label: 'os-class — cross-platform os class', link: '/reference/batteries/#denbatteriesos-class' },
+								{ label: 'os-user — user class forwarding', link: '/reference/batteries/#denbatteriesos-user' },
+								{ label: 'primary-user — admin privileges', link: '/reference/batteries/#denbatteriesprimary-user' },
+								{ label: 'user-shell — login shell', link: '/reference/batteries/#denbatteriesuser-shell' },
+								{ label: 'mutual-provider — host↔user config', link: '/reference/batteries/#denbatteriesmutual-provider' },
+								{ label: 'host-aspects — project host classes', link: '/reference/batteries/#denbatterieshost-aspects' },
+								{ label: 'tty-autologin — TTY auto-login', link: '/reference/batteries/#denbatteriestty-autologin' },
+								{ label: 'vm-autologin — auto-login for VMs', link: '/reference/batteries/#denbatteriesvm-autologin' },
+								{ label: 'wsl — WSL support', link: '/reference/batteries/#denbatterieswsl' },
+								{ label: 'forward — custom class factory', link: '/reference/batteries/#denbatteriesforward' },
+								{ label: 'import-tree — legacy module import', link: '/reference/batteries/#denbatteriesimport-tree' },
+								{ label: 'home-manager — HM integration', link: '/reference/batteries/#denbatterieshome-manager' },
+								{ label: 'hjem — hjem integration', link: '/reference/batteries/#denbatterieshjem' },
+								{ label: 'maid — nix-maid integration', link: '/reference/batteries/#denbatteriesmaid' },
+								{ label: 'unfree — allow unfree packages', link: '/reference/batteries/#denbatteriesunfree' },
+								{ label: 'insecure — allow insecure packages', link: '/reference/batteries/#denbatteriesinsecure' },
+								{ label: "inputs' — flake-parts inputs", link: '/reference/batteries/#denbatteriesinputs' },
+								{ label: "self' — flake-parts self outputs", link: '/reference/batteries/#denbatteriesself' },
+								{ label: "flake-scope — lib/inputs/den to pipeline", link: '/reference/batteries/#denbatteriesflake-scope' },
 							],
 						},
 						{ label: 'Host↔User Mutual Config', slug: 'guides/mutual' },
diff --git a/docs/src/content/docs/explanation/parametric.mdx b/docs/src/content/docs/explanation/parametric.mdx
index 02b175e75..7f2d1b57c 100644
--- a/docs/src/content/docs/explanation/parametric.mdx
+++ b/docs/src/content/docs/explanation/parametric.mdx
@@ -112,6 +112,28 @@ context drives the *entire aspect* (which classes to include, what includes to
 add). Use class-level injection when only a specific class module needs
 entity data alongside module-system args.
 
+<Aside type="note" title="Class modules that name a descendant kind">
+A **static** aspect (plain attrset) whose class module names a *descendant*
+entity kind of the emitting scope gets the same treatment as the aspect-level
+form: the pipeline promotes it to parametric and fans it out per descendant.
+
+```nix
+# Included at HOST scope — `user` is a descendant of `host` in the entity
+# schema, so this static aspect is promoted and fanned out per user,
+# exactly like the aspect-level { user, ... }: form.
+den.aspects.desktop = {
+  nixos = { user, ... }: {
+    services.xdg.portal.extraPortals = [ "${user.userName}-portal" ];
+  };
+};
+```
+
+This keeps the two forms equivalent: a class module that needs a descendant
+kind never silently drops its content. (A same-kind arg like `host` in a
+host-scope class module is not a descendant — it binds statically from the
+scope via class-level injection, per [Class Modules](/explanation/class-modules/).)
+</Aside>
+
 <Aside type="caution" title="Avoid anonymous functions in includes">
 Use named aspects instead of inline anonymous functions. Named aspects produce
 better error traces and are easier to debug with the [diagram library](/explanation/diagrams/).
diff --git a/docs/src/content/docs/explanation/policies.mdx b/docs/src/content/docs/explanation/policies.mdx
index 13ba116f6..58609416f 100644
--- a/docs/src/content/docs/explanation/policies.mdx
+++ b/docs/src/content/docs/explanation/policies.mdx
@@ -159,6 +159,15 @@ den.schema.host.includes = [
 ];
 ```
 
+<Aside type="note" title="`when` over inline aspects is different">
+`when` applied to an **inline aspect** (not a registered policy) does not
+gate policy dispatch — it compiles the aspect into a **conditional aspect**
+(`meta.guard`) whose guard is evaluated against the in-flight tree with a
+structural, exclude-aware `hasAspect`. That is what makes predicates like
+`host.hasAspect den.aspects.git` safe to write. See
+[Conditional aspects](/reference/aspects/#metaguard--metaaspects--conditional-aspects).
+</Aside>
+
 This page covers the *concept*. For the full activation model — the
 registry/value distinction, cascading across scopes, authoritative
 exclude semantics, the `for`/`when` combinators, and the dispatch
diff --git a/docs/src/content/docs/explanation/structural-introspection.mdx b/docs/src/content/docs/explanation/structural-introspection.mdx
new file mode 100644
index 000000000..bf05b1e0a
--- /dev/null
+++ b/docs/src/content/docs/explanation/structural-introspection.mdx
@@ -0,0 +1,212 @@
+---
+title: Structural Introspection & Constraints
+description: Reading and writing the aspect tree structure — entity.hasAspect, entity.aspects, and meta.handleWith constraints.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside title="Source" icon="github">
+[`modules/context/has-aspect.nix`](https://github.com/denful/den/blob/main/modules/context/has-aspect.nix) ·
+[`nix/lib/aspects/has-aspect.nix`](https://github.com/denful/den/blob/main/nix/lib/aspects/has-aspect.nix) ·
+[`nix/lib/aspects/fx/constraints.nix`](https://github.com/denful/den/blob/main/nix/lib/aspects/fx/constraints.nix)
+</Aside>
+
+Sometimes a piece of configuration depends on *what else is in the aspect
+tree* — "use the zfs flavor of impermanence when `zfs-root` is present,
+otherwise the btrfs flavor". Den splits that need into two complementary
+tools:
+
+- **Reading structure** — `entity.hasAspect` and `entity.aspects` let a
+  class module ask "is aspect X in this entity's tree?"
+- **Writing structure** — `meta.handleWith` with constraint records lets an
+  aspect decide "aspect Y should not be in my subtree (or should be
+  replaced by Z)"
+
+The two live at different points in evaluation, and that difference is what
+makes them safe.
+
+## Reading structure: `entity.hasAspect`
+
+Every entity (host, user, home — and any custom schema kind) carries a
+readOnly `hasAspect` functor computed from its resolved aspect tree:
+
+```nix
+host.hasAspect den.aspects.zfs-root        # bool — primary class
+host.hasAspect.forClass "nixos" den.aspects.zfs-root
+host.hasAspect.forAnyClass den.aspects.zfs-root   # union across the entity's classes
+```
+
+The reference is any aspect you can point at: `den.aspects.foo`,
+`den.aspects.foo.provides.bar`, a namespace aspect, …
+
+### Where you may call it
+
+**Safe — inside class module bodies.** The `nixos`/`homeManager`/… module
+bodies run during `evalModules`, long after the aspect tree has been resolved
+and frozen:
+
+```nix
+den.aspects.impermanence =
+  { host, ... }:
+  {
+    nixos =
+      { lib, ... }:
+      lib.mkMerge [
+        (lib.mkIf (host.hasAspect den.aspects.zfs-root) {
+          # zfs-flavored impermanence wiring
+        })
+        (lib.mkIf (host.hasAspect den.aspects.btrfs-root) {
+          # btrfs-flavored impermanence wiring
+        })
+      ];
+  };
+```
+
+This is cycle-safe: the body reads a frozen tree; nothing in the tree reads
+the body.
+
+**Safe — in policy guards.** `den.lib.policy.when` over an *inline aspect*
+compiles a [conditional aspect](/reference/aspects/#metaguard--metaaspects--conditional-aspects) whose
+guard gets the same scoped, structural `hasAspect`:
+
+```nix
+den.aspects.igloo.includes = [
+  (den.lib.policy.when ({ host, ... }: host.hasAspect den.aspects.git) {
+    nixos.environment.variables.GIT_ENABLED = "true";
+  })
+];
+```
+
+<Aside type="caution" title="Never in `includes`">
+Do **not** use `hasAspect` to decide an aspect's `includes` list:
+
+```nix
+# BROKEN — infinite recursion at evaluation
+den.aspects.broken =
+  { host, ... }:
+  {
+    includes =
+      if host.hasAspect den.aspects.zfs-root
+      then [ den.aspects.zfs-impermanence ]
+      else [ den.aspects.btrfs-impermanence ];
+  };
+```
+
+The tree depends on every aspect's `includes`; `includes` depending on the
+tree is a back-edge with no fixed point. If the decision is *structural*
+(which aspects belong in the tree), use [constraints](#writing-structure-metahandlewith)
+instead — they run during the walk, with full structural visibility, and
+operate *on* the tree rather than reading *from inside* it.
+</Aside>
+
+### What "present" means
+
+- **Scoped to the entity** — membership covers the entity's own resolved
+  tree: its scope and all descendants (for a host, the host scope plus its
+  user scopes). A sibling host that included the aspect does *not* leak in,
+  regardless of evaluation order. (The guard-level `hasAspect` in
+  [conditional aspects](/reference/aspects/#metaguard--metaaspects--conditional-aspects)
+  is scoped to the current pipeline scope plus its ancestors.)
+- **Exclude-aware** — an aspect excluded from the entity's scope (via
+  `excludes` or a constraint) reads as *absent*.
+
+## Reading the tree: `entity.aspects`
+
+Alongside the boolean functor, every entity exposes `aspects` — a flat list
+of **all resolved aspect nodes** (every depth) for its primary class. The
+entity root itself and excluded/tombstoned aspects are not listed; anonymous
+aspects are. Each node keeps its `.name`, `.meta`, and `.includes` (its
+resolved subtree), and adds identity accessors:
+
+| Field | Meaning |
+|---|---|
+| `.identity` | Base fully-qualified name, ctx-stripped — e.g. `"roles/workstation"` |
+| `.identityKey` | Full unique key incl. `{ctxId}` — distinguishes anonymous instances |
+| `.isNamed` | `false` for anonymous/synthetic aspects (filter on this) |
+
+```nix
+den.aspects.report =
+  { host, ... }:
+  {
+    nixos = {
+      environment.etc."aspect-inventory".text =
+        lib.concatMapStringsSep "\n" (n: n.identity) host.aspects;
+    };
+  };
+```
+
+(`aspects` lives on the *entity*, so reach it through the entity arg —
+`host.aspects`, `user.aspects`, `home.aspects` — not through `config`.)
+
+The entity's `hasAspect` record also carries `aspectsForClass` and
+`allAspects` (union across classes) when you need them via the lib-level
+constructors below.
+
+## Writing structure: `meta.handleWith`
+
+`meta.handleWith` on an aspect takes a constraint handler record (or a list
+of them) and registers it for the aspect's subtree. Constraints are
+constructed via `den.lib.aspects.fx.constraints`:
+
+```nix
+den.aspects.secrets-bundle = {
+  includes = [
+    den.aspects.agenix-rekey
+    den.aspects.sops-nix
+  ];
+  # Prefer agenix: drop sops-nix from this subtree whenever both are present.
+  meta.handleWith = den.lib.aspects.fx.constraints.exclude den.aspects.sops-nix;
+};
+```
+
+### `exclude ref`
+
+Tombstones `ref` — it contributes no modules, and its exclusion is visible
+to `hasAspect` queries (they return `false`) and to traces/diagrams.
+
+### `substitute ref replacement`
+
+Tombstones `ref` **and resolves `replacement` in its place** at the same
+position. The tombstone records `replacedBy` for tracing.
+
+### `filterBy predicate`
+
+Keeps/drops each aspect in scope by predicate. The predicate receives the
+aspect attrset (with `.name`, `.meta`, `.includes`, …) and returns a bool.
+
+### Scope: `subtree` (default) vs `.global`
+
+Every constructor has a `.global` variant:
+
+```nix
+den.lib.aspects.fx.constraints.exclude den.aspects.sops-nix        # subtree
+den.lib.aspects.fx.constraints.exclude.global den.aspects.sops-nix # global
+```
+
+- **`subtree`** (default) — the constraint applies within the including
+  aspect's own include chain. Two siblings including different aspects are
+  unaffected by each other's constraints.
+- **`global`** — the constraint applies fleet-wide, in every scope.
+
+`excludes` (the structural key) is the same mechanism in shorthand: each
+excluded ref registers a `subtree`-scoped exclude — and it works on policies
+by name as well as aspects.
+
+## Lib-level building blocks
+
+`den.lib.aspects` exposes the pieces the entity options are built from, for
+custom pipelines and tooling (see the [lib reference](/reference/lib/#structural-introspection-helpers)):
+
+- `hasAspectIn { tree, class, ref }` — membership over a resolved tree
+- `collectPathSet { tree, class }` — the raw identity-key path set
+- `mkEntityHasAspect { tree, primaryClass, classes }` — the full
+  `hasAspect`/`aspects` record
+- `mkProjectedHasAspect { pathSetByScope, key }` — pure lookup over an
+  already-computed path set (no pipeline run)
+
+## See also
+
+- [Aspects](/reference/aspects/) — structural keys, `meta`, conditional aspects
+- [Policies](/reference/policies/) — `include`/`exclude` effects and the `when`/`for` combinators
+- [Class Modules](/explanation/class-modules/) — where `hasAspect` is safely readable
+- [Diagrams](/reference/diag/) — excluded/tombstoned aspects are visible in captures
diff --git a/docs/src/content/docs/guides/batteries.mdx b/docs/src/content/docs/guides/batteries.mdx
index b849027d3..4de220709 100644
--- a/docs/src/content/docs/guides/batteries.mdx
+++ b/docs/src/content/docs/guides/batteries.mdx
@@ -183,6 +183,20 @@ den.default.includes = [ den.batteries.self' ];
 
 Requires flake-parts. Works in host, user, and home contexts.
 
+### `den.batteries.flake-scope`
+
+Exposes `lib`, `inputs`, and `den` to aspect pipeline functions — the
+generic, non-flake-parts counterpart of `inputs'`/`self'`. No flake-parts
+required. Values are tagged so class-module-native values win silently on
+collision:
+
+```nix
+den.default.includes = [ den.batteries.flake-scope ];
+
+# now usable in parametric aspects
+den.aspects.my-aspect = { host, inputs, lib, ... }: { ... };
+```
+
 ## Usage Patterns
 
 ### Global Batteries
diff --git a/docs/src/content/docs/guides/configure-aspects.mdx b/docs/src/content/docs/guides/configure-aspects.mdx
index b84edee2e..aed6de6f4 100644
--- a/docs/src/content/docs/guides/configure-aspects.mdx
+++ b/docs/src/content/docs/guides/configure-aspects.mdx
@@ -270,6 +270,13 @@ den.aspects.foo =
   }
 ```
 
+Beyond freeform metadata, `meta` carries pipeline-meaningful fields —
+`handleWith` (constraints: exclude/substitute/filter aspects in the
+subtree), `collisionPolicy` (flat-form class modules), and
+`guard`/`aspects` (conditional aspects). See
+[Structural Introspection & Constraints](/explanation/structural-introspection/)
+and the [aspects reference](/reference/aspects/#metahandlewith).
+
 ## Aspect Custom Submodule
 
 In case an aspect needs a custom submodule, it can be added this way:
diff --git a/docs/src/content/docs/guides/custom-classes.mdx b/docs/src/content/docs/guides/custom-classes.mdx
index fe8fdcb71..009bea785 100644
--- a/docs/src/content/docs/guides/custom-classes.mdx
+++ b/docs/src/content/docs/guides/custom-classes.mdx
@@ -131,6 +131,43 @@ den.aspects.alice.container = {
 };
 ```
 
+## Class Schema Fields
+
+Every entry in `den.classes.<name>` is a small schema, not just a marker:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `description` | `str` | -- | Human-readable description of the class domain |
+| `forwardTo` | `nullOr { class; path? }` | `null` | Default routing target for the `forward` battery: when a forward omits `intoClass`/`intoPath`, the class's `forwardTo.class` and `forwardTo.path` are used instead |
+| `parentPath` | `nullOr (name -> path)` | `null` | For classes whose members nest inside an enclosing config owner (e.g. home-manager inside a host): a function `name -> attrpath` locating a named member within that owner's config -- the same route the class's content is delivered to. `null` for root classes that own a top-level config (`nixos`, `darwin`, …) |
+| `parentArg` | `nullOr str` | `null` | For nested classes, the module argument by which a member reaches the enclosing config owner (home-manager exposes the host config as `osConfig`). `null` for root classes |
+
+`forwardTo` lets a class declare its destination once, so forwards only name
+the source:
+
+```nix
+den.classes.custom = {
+  description = "Custom class with forwardTo";
+  forwardTo = { class = "nixos"; path = [ ]; };
+};
+
+# no intoClass / intoPath needed:
+den.batteries.forward {
+  each = lib.singleton true;
+  fromClass = _: "custom";
+  fromAspect = _: myAspect;
+};
+```
+
+`parentPath`/`parentArg` are what make **nested** classes work -- the pipe
+layer uses them to resolve a producer's config at its producing class +
+scope. Den's own `homeManager` class registers both:
+
+```nix
+den.classes.homeManager.parentPath = userName: [ "home-manager" "users" userName ];
+den.classes.homeManager.parentArg = "osConfig";
+```
+
 ## Advanced: Guards and Adapters
 
 `forward` supports optional parameters for complex scenarios:
diff --git a/docs/src/content/docs/guides/quirks.mdx b/docs/src/content/docs/guides/quirks.mdx
index 44a0e7125..600994765 100644
--- a/docs/src/content/docs/guides/quirks.mdx
+++ b/docs/src/content/docs/guides/quirks.mdx
@@ -278,6 +278,57 @@ pipe.from "http-backends" [
 ]
 ```
 
+### Fleet-wide: `pipe.broadcast`
+
+Push a scope's own pipe value to **every other scope** matching a predicate —
+in one stage, in any direction (user→user, user→host, host→user, fleet-wide).
+The push dual of `pipe.expose`: instead of one parent receiving, every matching
+scope receives.
+
+A common shape: every user publishes a device record, and every user's home
+sees the whole fleet's roster:
+
+```nix
+den.hosts.x86_64-linux.igloo.users.tux = {};
+den.hosts.x86_64-linux.iceberg.users.alice = {};
+
+# Both users get a home-manager home (see the Home Manager guide):
+den.schema.user.classes = lib.mkDefault [ "homeManager" ];
+
+den.quirks.peer-dev = {
+  description = "per-user device records";
+};
+
+den.aspects.tux = {
+  peer-dev = [ { who = "tux@igloo"; } ];
+  homeManager = { peer-dev, lib, ... }: {
+    home.sessionVariables.PEERS =
+      lib.concatStringsSep "," (map (p: p.who) peer-dev);
+  };
+};
+den.aspects.alice = {
+  peer-dev = [ { who = "alice@iceberg"; } ];
+  homeManager = { peer-dev, lib, ... }: {
+    home.sessionVariables.PEERS =
+      lib.concatStringsSep "," (map (p: p.who) peer-dev);
+  };
+};
+
+# Every user scope broadcasts its own peer-dev to all other user scopes.
+den.policies.broadcast-peers = { host, user, ... }:
+  let inherit (den.lib.policy) pipe; in
+  [ (pipe.from "peer-dev" [ (pipe.broadcast ({ user, ... }: true)) ]) ];
+
+den.schema.user.includes = [ den.policies.broadcast-peers ];
+```
+
+`PEERS` on both tux's and alice's homes now lists **both** users — each scope
+sees its own emits plus everything broadcast to it. Transform stages before
+`pipe.broadcast` apply to the value as it leaves; config-dependent thunks are
+resolved against the *source* host's config when they cross hosts. Note the
+asymmetry: a broadcaster pushes its own raw emits only — data exposed *up* into
+it (e.g. a host broadcaster's users' `pipe.expose` data) does not ride along.
+
 ## Targeted delivery with `pipe.to`
 
 Route pipe data to specific aspects by identity:
diff --git a/docs/src/content/docs/reference/aspects.mdx b/docs/src/content/docs/reference/aspects.mdx
index 57dd538ac..84c78b911 100644
--- a/docs/src/content/docs/reference/aspects.mdx
+++ b/docs/src/content/docs/reference/aspects.mdx
@@ -68,7 +68,7 @@ registered class), *nested aspect keys*, or one of these structural keys:
 | `excludes` | `listOf unspecified` | Aspects or policies excluded from this subtree |
 | `provides` / `_` | submodule | Sub-aspect namespace (`_` is an alias for `provides`) |
 | `policies` | policy registry | Named policy functions, activated by placing in `includes` |
-| `meta` | submodule | Attached metadata (`handleWith`, `provider`, `collisionPolicy`) |
+| `meta` | submodule | Attached metadata (`handleWith`, `provider`, `collisionPolicy`; `guard`/`aspects` for conditional aspects) |
 | `classes` | `lazyAttrsOf raw` | Class schemas declared by this aspect, merged into `den.classes` |
 | `name` / `description` | `str` | Aspect name and description |
 
@@ -76,6 +76,21 @@ The pipeline also attaches internal `__`-prefixed fields (e.g. `__args` on
 parametric aspects, `__functor` to make merged aspects callable). These are
 implementation details, not authoring surface.
 
+### Reserved keys
+
+Keys on an aspect that match a registered class, quirk, or nested-aspect
+shape are dispatched by the pipeline. Anything else is treated as a class
+key of an unregistered class (backwards compat). To keep your own metadata
+keys out of dispatch entirely, reserve them globally:
+
+```nix
+den.reservedKeys = [ "settings" "tags" ];
+```
+
+Reserved keys are structural: the pipeline ignores them, so you can carry
+arbitrary metadata on any aspect without it being interpreted as class
+content.
+
 ### Static vs parametric includes
 
 A plain module function in `includes` (module-system signature) is
@@ -88,8 +103,11 @@ scope context arguments (`{ host }`, `{ user }`, `{ home }`, etc.) is
 
 Type: `nullOr (handler record or list of handler records)`. Default: `null`.
 
-Resolution handlers for the aspect's subtree (current). Handlers compose
-down the tree — a parent's constraint cannot be overridden by children.
+Resolution handlers for the aspect's subtree. The primary handler records are
+the **constraints** from `den.lib.aspects.fx.constraints` (`exclude`,
+`substitute`, `filterBy`) -- see
+[Structural Introspection & Constraints](/explanation/structural-introspection/)
+for the full API and examples.
 
 <Aside type="note">
 `meta.handleWith` is the current name for this field. `meta.adapter` no
@@ -108,6 +126,43 @@ providers accumulate: `foo._.bar._.baz` has `meta.provider = ["foo" "bar"]`.
 The `meta.provider` list distinguishes aspects by origin during pipeline
 resolution.
 
+### `meta.guard` / `meta.aspects` -- conditional aspects
+
+An aspect carrying `meta.guard` is **conditional**: instead of emitting its
+content immediately, the pipeline evaluates the guard against the in-flight
+aspect tree and only emits when it passes.
+
+You almost never write these fields by hand -- the user-facing entry point is
+[`policy.when`](/reference/policies/#combinators) applied to an **inline
+aspect** (or a `policy.include` effect):
+
+```nix
+den.aspects.igloo.includes = [
+  (den.lib.policy.when ({ host, ... }: host.hasAspect den.aspects.git) {
+    nixos.environment.variables.GIT_ENABLED = "true";
+  })
+];
+```
+
+`when` wraps the inline aspect into a conditional
+(`meta.guard = predicate; meta.aspects = [ … ]`). Key semantics:
+
+- **Guard context** -- the predicate receives `hasAspect ref` (bool) directly,
+  plus entity-shaped stubs (`host.hasAspect ref`, `user.hasAspect ref`, …) for
+  the kinds bound in the current scope. Membership is **structural** (the
+  in-flight tree, scoped to this entity's own subtree + ancestors -- not
+  fleet-wide) and **exclude-aware** (excluded aspects read as absent).
+- **Deferred re-evaluation** -- if the guard fails, the conditional is parked
+  and re-evaluated after siblings finish resolving. A guard on an aspect that
+  a *later* include pulls in still passes (the classic "order shouldn't
+  matter" case).
+- **Why this exists** -- a predicate that reads `entity.hasAspect` must not
+  touch `config.resolved` during policy dispatch (that is cyclic). Routing
+  `when` over inline aspects through the compile-conditional path is what
+  makes `hasAspect` predicates safe to write.
+- A failed guard that never recovers leaves a tombstone (visible in
+  traces/diagrams, contributes no modules).
+
 ## Class module collision policy
 
 A collision occurs when a flat-form class module declares an arg (e.g.
@@ -122,10 +177,11 @@ The policy is resolved from three levels, first match wins:
 | Level | Where to set | Type / default | Scope |
 |-------|--------------|----------------|-------|
 | Aspect | `meta.collisionPolicy` on the aspect | `nullOr (enum)`, default `null` | All class modules in that aspect |
-| Entity | `collisionPolicy` on the entity schema (`den.schema.<kind>`) | `nullOr (enum)`, default `null` | All uses of that entity kind |
+| Entity | `collisionPolicy` on a single entity (e.g. `den.hosts.<sys>.<name>.collisionPolicy`) | `nullOr (enum)`, default `null` | That entity's class modules |
+| Kind | `collisionPolicy` on the entity schema (`den.schema.<kind>`) | `nullOr (enum)`, default `null` | All entities of that kind |
 | Global | `den.config.classModuleCollisionPolicy` | `enum`, default `"error"` | Entire flake |
 
-A `null` at the aspect or entity level falls through to the next level.
+A `null` at any of the first three levels falls through to the next.
 The global level supplies the effective default of `"error"`.
 
 ### Strategy values
@@ -145,7 +201,10 @@ The enum is the same at every level: `"error"`, `"class-wins"`,
 # Aspect level — meta.collisionPolicy
 den.aspects.my-aspect.meta.collisionPolicy = "den-wins";
 
-# Entity level — den.schema.<kind>.collisionPolicy (all hosts)
+# Entity level -- one host
+den.hosts.x86_64-linux.igloo.collisionPolicy = "class-wins";
+
+# Kind level -- den.schema.<kind>.collisionPolicy (all hosts)
 den.schema.host.collisionPolicy = "den-wins";
 
 # Global — den.config.classModuleCollisionPolicy
diff --git a/docs/src/content/docs/reference/batteries.mdx b/docs/src/content/docs/reference/batteries.mdx
index c190873e7..b4d2e1aea 100644
--- a/docs/src/content/docs/reference/batteries.mdx
+++ b/docs/src/content/docs/reference/batteries.mdx
@@ -237,6 +237,32 @@ den.aspects.laptop.includes = [
 [`modules/aspects/batteries/import-tree.nix`](https://github.com/denful/den/blob/main/modules/aspects/batteries/import-tree.nix)
 </Aside>
 
+### `den.batteries.flake-scope`
+
+Exposes `lib`, `inputs`, and `den` to aspect pipeline functions -- the
+generic (non-flake-parts) counterpart of `inputs'`/`self'`. A parametric
+aspect can then destructure these alongside entity args:
+
+```nix
+den.default.includes = [ den.batteries.flake-scope ];
+
+den.aspects.my-aspect = { host, inputs, lib, ... }: {
+  nixos = { pkgs, ... }: {
+    environment.etc."version".text = inputs.nixpkgs.lib.version;
+  };
+};
+```
+
+Values are tagged `pipelineOnly` (class-wins collision policy), so
+class-module-native values (e.g. NixOS's own `lib` from `_module.args`)
+win silently over the flake-scope ones.
+
+**Opt-in.**
+
+<Aside title="Source" icon="github">
+[`modules/aspects/batteries/flake-scope.nix`](https://github.com/denful/den/blob/main/modules/aspects/batteries/flake-scope.nix)
+</Aside>
+
 ---
 
 ## Home Environments
diff --git a/docs/src/content/docs/reference/diag.mdx b/docs/src/content/docs/reference/diag.mdx
index 89be65059..7231fa8c7 100644
--- a/docs/src/content/docs/reference/diag.mdx
+++ b/docs/src/content/docs/reference/diag.mdx
@@ -313,3 +313,17 @@ Returns `{ entries, pathsByClass, ctxTrace }` -- entries plus per-class path set
 ### `captureWithPathsWith { classes, root, extraHandlers? }`
 
 Extended form accepting additional trace handlers.
+
+### `captureFleet { class?, extraHandlers? }`
+
+Fleet-level capture: runs the **entire** flake scope tree (flake → fleet →
+host → user) from the flake root, not a single entity. Returns the trace
+entries **plus** post-pipeline scope state for pipe-flow analysis:
+
+```nix
+{ entries, ctxTrace, scopeParent, scopeContexts, scopeEntityKind,
+  scopedPipeEffects, scopedClassImports, pipeProducers, pipeConsumers }
+```
+
+`class` defaults to `"nixos"`. Use this for fleet-wide pipe views (who
+produces what, who consumes it) rather than per-host captures.
diff --git a/docs/src/content/docs/reference/lib.mdx b/docs/src/content/docs/reference/lib.mdx
index 02e21c40b..4e7566bfe 100644
--- a/docs/src/content/docs/reference/lib.mdx
+++ b/docs/src/content/docs/reference/lib.mdx
@@ -32,6 +32,33 @@ module with `imports`. Runs the full pipeline including entity instantiation.
 Use for nested resolution where only class imports are needed, such as
 extracting `homeManager` modules from a host's aspect tree.
 
+### `den.lib.aspects.resolveWithPaths class aspect`
+
+**Internal.** Like `resolve`, but one pipeline run returns the full resolve
+record: `imports` plus the per-scope path set (`pathSetByScope`),
+`scopeContexts`, and the delivery-edge trace (`edgeTrace`). Entity
+`mainModule`/`__pathSetByScope` read it, so the pipeline runs exactly once
+per entity.
+
+### `den.lib.aspects.resolveWithState class aspect`
+
+**Internal.** Like `resolve`, but returns the raw fx-handle result
+`{ value, state }`, where `state` carries the trace `entries`, `ctxTrace`,
+and per-scope path sets -- used by
+[`den.lib.capture`](/reference/diag/).
+
+### Structural introspection helpers
+
+`den.lib.aspects` also exposes the building blocks behind
+[entity `hasAspect`](/explanation/structural-introspection/):
+
+- `hasAspectIn { tree, class, ref }` -- membership check over a resolved tree
+- `collectPathSet { tree, class }` -- the raw identity-key path set
+- `mkEntityHasAspect { tree, primaryClass, classes }` -- the full
+  hasAspect/aspects record (what entities get automatically)
+- `mkProjectedHasAspect { pathSetByScope, key }` -- pure lookup over an
+  already-computed path set (no pipeline run)
+
 ## `den.lib.resolveEntity name ctx`
 
 <Aside title="Source" icon="github">
@@ -56,9 +83,24 @@ scope is established. The record carries `name`, `meta`, `includes`, `excludes`,
 den.lib.aspects.resolve "flake" (den.lib.resolveEntity "flake" { });
 ```
 
-This is the public resolver used by [`den.hosts`/`den.homes`](/reference/options/)
+This is the public resolver used by [`den.hosts`/`den.homes`](/reference/schema/)
 (`config.resolved`) and by the flake outputs.
 
+## `den.lib.home-env`
+
+Factory helpers behind the home-environment batteries (`home-manager`, `hjem`,
+`maid`). Used to build a custom home-environment integration:
+
+- `makeHomeEnv { className, ctxName?, supportedOses?, optionPath, getModule, forwardPathFn, schemaIncludes? }` --
+  the full integration: host-scope detect policy, user-scope detect policy,
+  and the per-user forward. Returns `{ battery, userDetect, hostConf }`
+  (`hostConf` declares the `host.<optionPath>.enable` / `.module` options).
+- `mkDetectHost { className, supportedOses?, optionPath }` / `mkIntoClassUsers className` --
+  the individual predicates/compositions.
+
+See [Home Environments](/guides/home-manager/) for the batteries built on
+these.
+
 ## `den.lib.policy`
 
 Policy effect constructors. See [den.policies reference](/reference/policies/)
diff --git a/docs/src/content/docs/reference/output.mdx b/docs/src/content/docs/reference/output.mdx
index 6af35ab09..8c6efef98 100644
--- a/docs/src/content/docs/reference/output.mdx
+++ b/docs/src/content/docs/reference/output.mdx
@@ -87,6 +87,20 @@ den.hosts.x86_64-linux.myhost = {
 };
 ```
 
+## `den.systems`
+
+The list of systems the flake walks. Drives the `flake-to-systems` policy --
+one `flake-system` scope per entry, which fans out to that system's hosts
+and homes.
+
+**Type:** `listOf str` · **Default:** the union of the system keys of
+`den.hosts` and `den.homes`; if you declare neither, `lib.systems.flakeExposed`.
+
+```nix
+# Explicit -- e.g. to pin the system set or add a system with no hosts yet:
+den.systems = [ "x86_64-linux" ];
+```
+
 ## Flake outputs like `packages`, `checks`, etc.
 
 Den aspects can directly contribute to `packages` and similar flake outputs.
diff --git a/docs/src/content/docs/reference/policies.mdx b/docs/src/content/docs/reference/policies.mdx
index 66c286fce..673127b12 100644
--- a/docs/src/content/docs/reference/policies.mdx
+++ b/docs/src/content/docs/reference/policies.mdx
@@ -47,6 +47,7 @@ policy.resolve { myFlag = true; }
 **Variants:**
 - `policy.resolve.shared bindings` — shared (non-isolated) fan-out
 - `policy.resolve.to kind bindings` — target a specific entity kind
+- `policy.resolve.shared.to kind bindings` — shared fan-out with explicit target kind
 - `policy.resolve.withIncludes includes bindings` — attach includes to the new scope
 - `policy.resolve.to.withIncludes kind includes bindings` — both
 
@@ -98,6 +99,17 @@ policy.deliver {
   `reinstantiate` flag** — verbatim is requested by `mode` directly. `verbatim`
   applies only to class sources, not module sources.
 
+Class sources accept two optional fields:
+
+- `guard = args: bool` — only deliver when the predicate holds against the
+  target's module-system args (e.g. `{ options, ... }: options ? wsl`). A
+  failed guard means the delivered content contributes nothing.
+- `adaptArgs = args: attrs` — an args/specialArgs adapter for the delivered
+  modules: with a non-empty `at`, the source modules are evaluated in a
+  submodule whose `specialArgs` are `adaptArgs` applied to the target's args
+  (e.g. inject `osConfig = config`); at the root (`at = []`), it adapts the
+  args each module function receives.
+
 `deliver` deliberately does **not** expose `appendToParent` (parent-targeting is
 constructor-internal) — use a class source whose `to` already names the target.
 
@@ -116,6 +128,16 @@ policy.route {
 }
 ```
 
+Additional spec fields (passed through to the underlying edge):
+
+- `intoPath = item: path` — public alias for `path` that pairs with
+  `fromClass`/`intoClass` (the `forward` battery's naming). Passing **both**
+  `path` and `intoPath` is an error.
+- `guard` / `adaptArgs` — same semantics as on `deliver` (see above).
+- `collectSubtree = true` — also collect the source class's content from the
+  scope's descendant scopes, not just the scope itself. Used by the built-in
+  flake-parts policy so per-system `packages` gather host/user contributions.
+
 ### `policy.provide spec`
 
 Deliver a module directly to a target class, bypassing the aspect tree. A
@@ -127,14 +149,27 @@ from `path` — `merge` at the root, `nest` under a non-empty `path`):
 policy.provide { class = "nixos"; module = { pkgs, ... }: { ... }; }
 ```
 
-### `policy.instantiate entity`
+### `policy.instantiate spec`
 
-Request post-pipeline instantiation of an entity:
+Request post-pipeline instantiation. Pass an entity to use its own
+`instantiate`/`intoAttr` metadata:
 
 ```nix
 policy.instantiate den.hosts.x86_64-linux.igloo
 ```
 
+Or pass a custom spec to instantiate something that isn't an entity (e.g.
+a third-party builder fed by a den class — the terranix pattern):
+
+```nix
+policy.instantiate {
+  name = "${host.name}-tf";
+  class = "terranix";              # which class bucket to collect
+  instantiate = { modules, ... }: modules;  # how to build from collected modules
+  intoAttr = [ "terranixModules" host.name ];  # where the result lands
+};
+```
+
 ### `policy.spawn`
 
 Request a deferred node spawn, resolved post-walk over the parent
@@ -256,6 +291,29 @@ den.lib.policy.when (ctx: ctx.flag or false)
 |---|---|---|---|
 | `host-to-users` | `host` | `user` | One `{ host, user }` per `host.users` entry |
 
+### Battery-driven class routing
+
+These fire automatically with their battery (most via `den.default.includes`,
+so they are active without any explicit inclusion):
+
+| Policy | Source | Behavior |
+|---|---|---|
+| `os-to-host` | `batteries/os-class` | Route `os` class content to the host's class (`nixos`/`darwin`) in every host/user scope |
+| `user-to-host` | `batteries/os-user` | Route `user` class content to `users.users.<userName>`, injecting `osConfig` |
+| `host-to-hm-users` / `hm-user-detect` | `batteries/home-manager` | Import the HM OS module; forward each HM user's `homeManager` class into `home-manager.users.<name>`. The `*-user-detect` policy covers users resolved by registry/policy rather than `host.users`. `hjem` and `maid` batteries register the same family (`host-to-hjem-users`, `host-to-maid-users`, …) |
+| `host-to-wsl-host` / `wsl-to-host` | `batteries/wsl` | Resolve the `wsl-host` entity when `host.wsl.enable`; route `wsl` class content to the host's OS at `wsl` |
+
+### Flake-parts (`policies/flake-parts.nix`, opt-in via `den.schema`)
+
+| Policy | From | To | Behavior |
+|---|---|---|---|
+| `system-to-flake-parts` | `flake-system` | `flake-parts` | One `{ flake-parts }` per system |
+| `packages-to-flake-parts` | `flake-system` | `flake-parts` | Route `packages` class into perSystem `packages` (`collectSubtree`) |
+
+The `flake-scope` battery carries its own internal policy
+(`den-flake-scope`) for pipeline-arg enrichment — see
+[Batteries](/reference/batteries/#denbatteriesflake-scope).
+
 ### Flake output traversal (`flake.nix`)
 
 | Policy | From | To | Behavior |
diff --git a/docs/src/content/docs/reference/quirks.mdx b/docs/src/content/docs/reference/quirks.mdx
index b8a18b8ac..156e56f94 100644
--- a/docs/src/content/docs/reference/quirks.mdx
+++ b/docs/src/content/docs/reference/quirks.mdx
@@ -249,6 +249,31 @@ pipe.collectAll ({ host, ... }: true)
 Entity kind filtering and non-terminal chaining work the same as
 `pipe.collect`. Both stages also compose with `pipe.withProvenance`.
 
+### `pipe.broadcast predicate`
+
+Push the broadcasting scope's pipe value to **every other scope** whose context
+matches the predicate — fleet-wide, not just siblings or parents. The push
+dual of `pipe.expose` (which routes up to the parent). Receivers read the pipe
+normally; broadcast values are merged into their pool.
+
+```nix
+pipe.from "peer-dev" [ (pipe.broadcast ({ user, ... }: true)) ]
+```
+
+- **Entity kind filtering is automatic**, same as `pipe.collect`: the
+  predicate's required args restrict which scopes can receive.
+- **Source values are the broadcaster's raw emits** — transform stages before
+  `pipe.broadcast` apply, but data exposed *up* into the broadcaster (e.g. a
+  host broadcaster does not fold in its users' `pipe.expose` data) is not
+  included. This is an intentional asymmetry with `collect`.
+- **Receivers see broadcast values as-is** — they are appended to the
+  receiver's pool after the receiver's own transform stages have run, so a
+  receiver's `pipe.filter`/`pipe.transform` do not apply to data broadcast to
+  it (the broadcaster's transforms already did).
+- **Config-dependent thunks** are resolved eagerly against the *source* scope's
+  producer config when they cross hosts, exactly like `pipe.collect`.
+- **Isolated per pipe name** — broadcasting one quirk never leaks into another.
+
 ### `pipe.to aspects`
 
 Route transformed data to specific aspects by identity. Only the named
@@ -301,14 +326,16 @@ Pipe assembly runs post-pipeline in `assemblePipes`, before class module
 wrapping. The sequence:
 
 1. **Expose pass** — bottom-up tree walk collects all `pipe.expose` data
-2. **Per-scope assembly** — for each scope:
+2. **Broadcast pass** — each broadcaster pushes its (post-transform) value to
+   every other scope matching its `pipe.broadcast` predicate
+3. **Per-scope assembly** — for each scope:
    - Extract raw pipe entries from `scopedClassImports`
    - Merge exposed data from children
    - Mark local config thunks
    - Apply untargeted pipe effects
    - Route inbound `pipe.as` effects from other pipes
    - Build targeted data (`pipe.to`, `pipe.as` + `pipe.to`)
-3. **Inject into scope contexts** — pipe data becomes available as
+4. **Inject into scope contexts** — pipe data becomes available as
    function args in `wrapClassModule`
 
 ## See also
diff --git a/docs/src/content/docs/reference/schema.mdx b/docs/src/content/docs/reference/schema.mdx
index 1ef4e7165..a4e39f9f4 100644
--- a/docs/src/content/docs/reference/schema.mdx
+++ b/docs/src/content/docs/reference/schema.mdx
@@ -54,7 +54,10 @@ be able to read `host.hardened` value.
 
 ## `den.schema`
 
-Base modules merged into all hosts, users, or homes.
+Base modules merged into all hosts, users, or homes. `den.schema` is built on
+top of [gen-schema](https://github.com/sini/gen-schema) -- each key is a schema
+entity, and the registry exposes introspection attrs (e.g. `_kindNames`,
+`_topology`, `_edges`) that the pipeline itself consumes.
 
 | Option | Type | Description |
 |--------|------|-------------|
@@ -62,6 +65,7 @@ Base modules merged into all hosts, users, or homes.
 | `den.schema.host` | `deferredModule` | Applied to all hosts (imports `conf`) |
 | `den.schema.user` | `deferredModule` | Applied to all users (imports `conf`) |
 | `den.schema.home` | `deferredModule` | Applied to all homes (imports `conf`) |
+| `den.schema.aspect` | `deferredModule` | Applied to **all aspects** (imported into every aspect submodule) -- where `den.lib.strict` is applied for [strict mode](/explanation/entities/#strict-mode) |
 
 ```nix
 den.schema.conf = { lib, ... }: {
@@ -72,13 +76,17 @@ den.schema.host = { ... }: {
 };
 ```
 
-A schema entry also accepts two list attributes, stripped before the module
+A schema entry also accepts attributes, stripped before the module
 merge and consumed by the resolution pipeline:
 
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `includes` | `listOf raw` | Aspects/policies activated for every entity of this kind |
-| `excludes` | `listOf raw` | Aspects/policies suppressed for every entity of this kind |
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `includes` | `listOf raw` | `[]` | Aspects/policies activated for every entity of this kind |
+| `excludes` | `listOf raw` | `[]` | Aspects/policies suppressed for every entity of this kind |
+| `isEntity` | `bool` | computed | Whether the kind is a real entity (fan-out/policy target). Computed as `true` when the entry carries any content beyond collection keys; set it explicitly for content-free entity kinds (e.g. `den.schema.flake-parts.isEntity = true`) |
+| `isolated` | `bool` | `false` | Mark this kind's scopes as isolated -- when an ancestor collects its subtree, it cannot cross into an isolated scope (the isolated scope still collects its own content) |
+| `parent` | `nullOr str` | `null` | The enclosing entity kind (e.g. `user.parent = "host"`). Defines the entity schema DAG the pipeline uses for descendant fan-out and [class-module arg promotion](/explanation/parametric/#where-parametric-args-work) |
+| `collisionPolicy` | `nullOr enum` | `null` | Class-module collision policy for every entity of this kind (see [Class Modules](/explanation/class-modules/)) |
 
 ```nix
 # Activate a policy for every host
@@ -108,6 +116,19 @@ den.hosts.x86_64-linux.myhost = {
 };
 ```
 
+### Flat form
+
+The system level can be omitted: declare `system` inside the host value and
+Den normalizes it into the two-level form. Both forms coexist freely:
+
+```nix
+# Equivalent to den.hosts.x86_64-linux.myhost = { ...; };
+den.hosts.myhost = {
+  system = "x86_64-linux";
+  users.vic = {};
+};
+```
+
 ### Host options
 
 | Option | Type | Default | Description |
@@ -174,6 +195,17 @@ an unbound standalone home.
 den.homes.x86_64-linux.vic = {};
 ```
 
+### Flat form
+
+As with `den.hosts`, the system level can be omitted -- put `system` inside
+the home value (both forms coexist):
+
+```nix
+den.homes."tux@igloo" = {
+  system = "x86_64-linux";
+};
+```
+
 ### Home options
 
 | Option | Type | Default | Description |
diff --git a/docs/src/content/docs/tutorials/default.mdx b/docs/src/content/docs/tutorials/default.mdx
index 227b069ee..17582e561 100644
--- a/docs/src/content/docs/tutorials/default.mdx
+++ b/docs/src/content/docs/tutorials/default.mdx
@@ -102,9 +102,9 @@ The host aspect:
 ```
 
 The user aspect:
-- Includes [`define-user`](/reference/batteries/#den-batteries-define-user) — defines the user at the OS and Home levels
-- Includes [`primary-user`](/reference/batteries/#den-batteries-primary-user) — adds wheel + networkmanager groups
-- Includes [`user-shell`](/reference/batteries/#den-batteries-user-shell) — sets fish as default shell at OS and HM level
+- Includes [`define-user`](/reference/batteries/#denbatteriesdefine-user) — defines the user at the OS and Home levels
+- Includes [`primary-user`](/reference/batteries/#denbatteriesprimary-user) — adds wheel + networkmanager groups
+- Includes [`user-shell`](/reference/batteries/#denbatteriesuser-shell) — sets fish as default shell at OS and HM level
 - Provides personal Home-Manager packages
 - Uses `provides.to-hosts.nixos` to push NixOS config up to any host it is included on (empty here, ready to fill in)
 
diff --git a/docs/src/content/docs/tutorials/minimal.mdx b/docs/src/content/docs/tutorials/minimal.mdx
index 4adf6ae29..2908a162e 100644
--- a/docs/src/content/docs/tutorials/minimal.mdx
+++ b/docs/src/content/docs/tutorials/minimal.mdx
@@ -78,7 +78,7 @@ Key points:
 
 1. **One host** named `igloo` on `x86_64-linux` with **one user** named `tux`
 2. **Host aspect** `den.aspects.igloo` — provides NixOS config (a package + boot/fs stubs)
-3. **User aspect** `den.aspects.tux` — includes the [`primary-user`](/reference/batteries/#den-batteries-primary-user) battery
+3. **User aspect** `den.aspects.tux` — includes the [`primary-user`](/reference/batteries/#denbatteriesprimary-user) battery
 
 ### How It Works
 
diff --git a/modules/context/has-aspect.nix b/modules/context/has-aspect.nix
index 5e7d701ea..4af1d70ef 100644
--- a/modules/context/has-aspect.nix
+++ b/modules/context/has-aspect.nix
@@ -61,8 +61,9 @@ let
           Safe to call from inside class-config module bodies
           (`nixos = ...`, `homeManager = ...`) and from lazy positions
           inside aspect functor bodies. NOT safe to use for deciding an
-          aspect's `includes` list — that's cyclic; use meta.adapter +
-          excludeAspect / oneOfAspects for structural decisions instead.
+          aspect's `includes` list — that's cyclic; use `meta.handleWith`
+          with `den.lib.aspects.fx.constraints` for structural decisions
+          instead.
         '';
         internal = true;
         visible = false;
diff --git a/templates/example/modules/aspects/hasAspect-examples.nix b/templates/example/modules/aspects/hasAspect-examples.nix
index 865b9db0c..153de2102 100644
--- a/templates/example/modules/aspects/hasAspect-examples.nix
+++ b/templates/example/modules/aspects/hasAspect-examples.nix
@@ -1,4 +1,4 @@
-# Worked examples for `host.hasAspect` and `oneOfAspects`.
+# Worked examples for `host.hasAspect` and `meta.handleWith` constraints.
 #
 # Two complementary tools for two different jobs:
 #
@@ -7,10 +7,10 @@
 #     Cycle-safe because the body runs at evalModules time, long after
 #     the aspect tree has been resolved and frozen.
 #
-#   - `oneOfAspects` (and friends in `nix/lib/aspects/adapters.nix`)
-#     WRITE structure at adapter time with full structural visibility.
-#     The right tool for "prefer A over B when both are present" and
-#     other tree-shape decisions.
+#   - `meta.handleWith` with `den.lib.aspects.fx.constraints`
+#     (exclude / substitute / filterBy) WRITEs structure at resolve time
+#     with full structural visibility. The right tool for "prefer A over
+#     B when both are present" and other tree-shape decisions.
 #
 # These illustrative aspects are all `example-` prefixed to make it
 # clear they are pedagogical stubs and to avoid colliding with any
@@ -130,8 +130,8 @@
   # See `nix/lib/aspects/fx/constraints.nix` for available constraints:
   #
   #   - `exclude <ref>`              tombstone a specific aspect by reference
-  #   - `substitute <a> <b>`         swap one aspect for another
-  #   - `filter` / `filterIncludes`  custom filtering primitives
+  #   - `substitute <ref> <aspect>`  swap one aspect for another
+  #   - `filterBy <pred>`            custom predicate filtering
   #
   # These run during the tree walk with full structural visibility and
   # operate ON the tree rather than FROM INSIDE it, so they can't

From a187f73e82897eca1c76d6f4781fde3350060d79 Mon Sep 17 00:00:00 2001
From: Jason Bowman <jason@json64.dev>
Date: Tue, 25 Aug 2026 12:21:59 -0700
Subject: [PATCH 2/2] docs: clarify hasAspect class semantics and fix
 misleading constraint example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Membership is class-invariant, so hasAspect, forClass and forAnyClass agree
for any class an entity declares; say so rather than implying the variants
answer differently. Tie present/absent to the boolean they describe.

constraints.exclude is unconditional — the secrets-bundle example claimed it
fires 'whenever both are present' while excluding an aspect it had just
included. Exclude something a transitively included aspect drags in instead.

Class entries are a record of options; 'schema' collides with den.schema
entity kinds.
---
 .../explanation/structural-introspection.mdx  | 42 ++++++++++++++-----
 .../content/docs/guides/custom-classes.mdx    |  4 +-
 2 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/docs/src/content/docs/explanation/structural-introspection.mdx b/docs/src/content/docs/explanation/structural-introspection.mdx
index bf05b1e0a..e3e35aeff 100644
--- a/docs/src/content/docs/explanation/structural-introspection.mdx
+++ b/docs/src/content/docs/explanation/structural-introspection.mdx
@@ -31,14 +31,24 @@ Every entity (host, user, home — and any custom schema kind) carries a
 readOnly `hasAspect` functor computed from its resolved aspect tree:
 
 ```nix
-host.hasAspect den.aspects.zfs-root        # bool — primary class
+host.hasAspect den.aspects.zfs-root        # bool — asks at the primary class
 host.hasAspect.forClass "nixos" den.aspects.zfs-root
-host.hasAspect.forAnyClass den.aspects.zfs-root   # union across the entity's classes
+host.hasAspect.forAnyClass den.aspects.zfs-root   # union over the entity's classes
 ```
 
 The reference is any aspect you can point at: `den.aspects.foo`,
 `den.aspects.foo.provides.bar`, a namespace aspect, …
 
+**All three agree for any class the entity declares.** Membership is
+*structural*, and the resolved tree is the same whichever class it is
+resolved at — a class decides what an aspect *emits*, never whether it is
+*in* the tree. The variants differ only in the class they ask at:
+`hasAspect` uses the primary class (the head of the entity's `classes` —
+`nixos` for a Linux host, `darwin` for a darwin one), `forClass` uses the
+class you name and answers `false` for one the entity does not declare, and
+`forAnyClass` unions over the declared classes. Prefer the bare functor; reach for the other two only when
+the class is the point of the question.
+
 ### Where you may call it
 
 **Safe — inside class module bodies.** The `nixos`/`homeManager`/… module
@@ -101,6 +111,10 @@ operate *on* the tree rather than reading *from inside* it.
 
 ### What "present" means
 
+*Present* is exactly what the boolean above reports: `hasAspect ref` is
+`true` when `ref` is in the entity's resolved tree, and `false` — *absent* —
+when it is not. Two rules decide which:
+
 - **Scoped to the entity** — membership covers the entity's own resolved
   tree: its scope and all descendants (for a host, the host scope plus its
   user scopes). A sibling host that included the aspect does *not* leak in,
@@ -113,9 +127,10 @@ operate *on* the tree rather than reading *from inside* it.
 ## Reading the tree: `entity.aspects`
 
 Alongside the boolean functor, every entity exposes `aspects` — a flat list
-of **all resolved aspect nodes** (every depth) for its primary class. The
-entity root itself and excluded/tombstoned aspects are not listed; anonymous
-aspects are. Each node keeps its `.name`, `.meta`, and `.includes` (its
+of **all resolved aspect nodes** (every depth), taken at its primary class —
+the same class-invariant tree `hasAspect` reads, so no class carries a
+different list. The entity root itself and excluded/tombstoned aspects are
+not listed; anonymous aspects are. Each node keeps its `.name`, `.meta`, and `.includes` (its
 resolved subtree), and adds identity accessors:
 
 | Field | Meaning |
@@ -138,9 +153,9 @@ den.aspects.report =
 (`aspects` lives on the *entity*, so reach it through the entity arg —
 `host.aspects`, `user.aspects`, `home.aspects` — not through `config`.)
 
-The entity's `hasAspect` record also carries `aspectsForClass` and
-`allAspects` (union across classes) when you need them via the lib-level
-constructors below.
+The entity's `hasAspect` record also carries the per-class and union
+counterparts, `aspectsForClass` and `allAspects`, for the same reasons you
+would reach for `forClass` / `forAnyClass` above.
 
 ## Writing structure: `meta.handleWith`
 
@@ -152,13 +167,20 @@ constructed via `den.lib.aspects.fx.constraints`:
 den.aspects.secrets-bundle = {
   includes = [
     den.aspects.agenix-rekey
-    den.aspects.sops-nix
+    den.aspects.workstation-role # pulls in sops-nix somewhere below
   ];
-  # Prefer agenix: drop sops-nix from this subtree whenever both are present.
+  # Prefer agenix: sops-nix never resolves under this bundle, whoever pulls it in.
   meta.handleWith = den.lib.aspects.fx.constraints.exclude den.aspects.sops-nix;
 };
 ```
 
+A constraint is unconditional — it is not a rule that fires when some other
+aspect turns out to be present. Registering it tombstones `ref` throughout
+the registering aspect's subtree, which is what makes it useful against
+aspects you never named yourself: `secrets-bundle` cannot see what
+`workstation-role` includes, but it can state that sops-nix is not welcome
+below it.
+
 ### `exclude ref`
 
 Tombstones `ref` — it contributes no modules, and its exclusion is visible
diff --git a/docs/src/content/docs/guides/custom-classes.mdx b/docs/src/content/docs/guides/custom-classes.mdx
index 009bea785..7ce764170 100644
--- a/docs/src/content/docs/guides/custom-classes.mdx
+++ b/docs/src/content/docs/guides/custom-classes.mdx
@@ -131,9 +131,9 @@ den.aspects.alice.container = {
 };
 ```
 
-## Class Schema Fields
+## Class Fields
 
-Every entry in `den.classes.<name>` is a small schema, not just a marker:
+Every entry in `den.classes.<name>` is a record of options, not just a marker:
 
 | Field | Type | Default | Description |
 |---|---|---|---|