diff --git a/extras/bundlers.nix b/extras/bundlers.nix
index bffe888..45f15eb 100644
--- a/extras/bundlers.nix
+++ b/extras/bundlers.nix
@@ -29,6 +29,13 @@ mkTransposedPerSystemModule {
       `nix bundle --bundler .#<name> .#<package>` bundles `<package>` using bundler `<name>`.
 
       Define a `default` bundler to use `nix bundle --bundler .#`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix bundle --bundler '.#"example.com"' .#package
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./bundlers.nix;
diff --git a/modules/apps.nix b/modules/apps.nix
index 3030d32..1f7b35d 100644
--- a/modules/apps.nix
+++ b/modules/apps.nix
@@ -49,7 +49,16 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf appType;
     default = { };
     description = ''
-      Programs runnable with nix run `<name>`.
+      An attribute set of programs runnable with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run.html).
+
+      `nix run .#<name>` will run `apps.<name>`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix run '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
     example = lib.literalExpression ''
       {
diff --git a/modules/devShells.nix b/modules/devShells.nix
index c0cc6c5..522d187 100644
--- a/modules/devShells.nix
+++ b/modules/devShells.nix
@@ -16,7 +16,15 @@ mkTransposedPerSystemModule {
     default = { };
     description = ''
       An attribute set of packages to be used as shells.
+
       [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix develop '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
     example = literalExpression ''
       {
diff --git a/modules/legacyPackages.nix b/modules/legacyPackages.nix
index fb17e14..bf7a721 100644
--- a/modules/legacyPackages.nix
+++ b/modules/legacyPackages.nix
@@ -15,6 +15,16 @@ mkTransposedPerSystemModule {
     default = { };
     description = ''
       An attribute set of unmergeable values. This is also used by [`nix build .#<attrpath>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
+
+      `legacyPackages` supports nested attribute sets. Use `.` to access nested attributes:
+      `.#foo.bar` refers to the `bar` attribute in `foo`.
+
+      Attribute names that literally contain special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix build '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./legacyPackages.nix;
diff --git a/modules/packages.nix b/modules/packages.nix
index 20f0071..797727f 100644
--- a/modules/packages.nix
+++ b/modules/packages.nix
@@ -17,6 +17,17 @@ mkTransposedPerSystemModule {
       An attribute set of packages to be built by [`nix build`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
 
       `nix build .#<name>` will build `packages.<name>`.
+
+      You can also build attributes of a package using `.` to access nested attributes:
+      `.#foo.tests.simple` builds the `simple` attribute in `foo.tests`.
+      This is a Nixpkgs convention (packages having "passthru" attributes like `tests`) which gets no special treatment in Flakes.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix build '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./packages.nix;