docs: make flake-inputs flow better

docs/site/guides/nixpkgs-flake-input/index.md

@@ -1,46 +1,52 @@
-**Q**: How should I choose the nixpkgs input for my flake when using clan-core?
+**Q**: How should I choose the `nixpkgs` input for my flake when using `clan-core`?
 
-**A**: In general, you should pin your flake to a recent nixpkgs version.
+**A**: Pin your flake to a recent `nixpkgs` version. Here are two common approaches, each with its trade-offs:
-There are two common ways to do this, each with its own trade-offs:
 
-## Follow clan-core
+## Option 1: Follow `clan-core`
 
-- (+) Recommended for most people.
+- **Pros**:
-- (+) Verified by our CI and widely used by others
+  - Recommended for most users.
-- (-) Coupling to version bumps in clan-core,
+  - Verified by our CI and widely used by others.
+- **Cons**:
+  - Coupled to version bumps in `clan-core`.
   - Upstream features and packages may take longer to land.
 
+Example:
+
 ```nix
 inputs = {
   clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-    # Uses the nixpkgs version that was locked in clan-core
+  # Use the `nixpkgs` version locked in `clan-core`
   nixpkgs.follows = "clan-core/nixpkgs";
-}
+};
 ```
 
-## Use your own nixpkgs version
+## Option 2: Use Your Own `nixpkgs` Version
 
-- (+) Faster access to new upstream features and packages
+- **Pros**:
-- (-) Recommended for advanced usage.
+  - Faster access to new upstream features and packages.
-- (-) Not covered by our CI — you’re on the frontier
+- **Cons**:
+  - Recommended for advanced users.
+  - Not covered by our CI — you’re on the frontier.
+
+Example:
 
 ```nix
 inputs = {
-    # Use your own version here.
+  # Specify your own `nixpkgs` version
   nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
 
   clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-    # Uses the nixpkgs version of your own flake in clan-core
+  # Ensure `clan-core` uses your `nixpkgs` version
   clan-core.inputs.nixpkgs.follows = "nixpkgs";
-}
+};
 ```
 
-## Recommended
+## Recommended: Avoid Duplicate `nixpkgs` Entries
 
-To avoid ambiguity or incompatibility issues, it’s a good idea to check your `flake.lock` for duplicate `nixpkgs` entries.
+To prevent ambiguity or compatibility issues, check your `flake.lock` for duplicate `nixpkgs` entries. Duplicate entries indicate a missing `follows` directive in one of your flake inputs.
-This usually indicates that one of your flake inputs is missing a `follows` directive.
 
-If you see something like this, it means you have multiple versions of `nixpkgs`:
+Example of duplicate entries in `flake.lock`:
 
 ```json
 "nixpkgs": {
@@ -71,28 +77,23 @@ If you see something like this, it means you have multiple versions of `nixpkgs`
     "repo": "nixpkgs",
     "type": "github"
   }
-    },
+}
 ```
 
-You can grep through your lock file to locate which inputs are referencing the wrong nixpkgs.
+To locate the source of duplicate entries, grep your `flake.lock` file. For example, if `home-manager` is referencing `nixpkgs_2` instead of the main `nixpkgs`:
-
-In this example, `home-manager` is pointing to `nixpkgs_2` instead of the main `nixpkgs`
 
 ```json
-    // ...
 "home-manager": {
   "inputs": {
     "nixpkgs": "nixpkgs_2"
   }
-    // ...
+}
 ```
 
-To fix this add the following line to your flake.nix inputs:
+Fix this by adding the following line to your `flake.nix` inputs:
 
 ```nix
 home-manager.inputs.nixpkgs.follows = "nixpkgs";
 ```
 
-Repeat this process until all duplicate `nixpkgs` entries are eliminated.
+Repeat this process until all duplicate `nixpkgs` entries are resolved. This ensures all inputs use the same `nixpkgs` source, preventing cross-version conflicts.
-
-This helps prevent cross-version conflicts and ensures all inputs use the same `nixpkgs` source.