diff --git a/src/docs.html b/src/docs.html
index 9279756..64f9943 100644
--- a/src/docs.html
+++ b/src/docs.html
@@ -67,6 +67,7 @@
             <a class="list-group-item list-group-item-action" href="#templates">JinjaTurtle templates</a>
             <a class="list-group-item list-group-item-action" href="#config">Config file</a>
             <a class="list-group-item list-group-item-action" href="#diff">Drift detection with <code>enroll diff</code></a>
+            <a class="list-group-item list-group-item-action" href="#explain">Why did Enroll include/exclude something? <code>enroll explain</code></a>
             <a class="list-group-item list-group-item-action" href="#tips">Tips</a>
           </div>
           <div class="mt-3 small text-secondary">
@@ -480,6 +481,57 @@ sudo journalctl -u enroll-harvest-diff.service -n 200 --no-pager
         </section>
 
 
+        <section id="explain" class="scroll-mt-nav mb-5">
+          <h2 class="section-title fw-bold">Why did Enroll include/exclude something? <code>enroll explain</code></h2>
+          <p class="text-secondary">When you run <code>enroll harvest</code>, Enroll records <em>why</em> it chose to include or exclude each path in <code>state.json</code>. The <code>enroll explain</code> subcommand summarizes that data so you can quickly sanity-check a harvest, tune include/exclude rules, and understand where packages/services came from.</p>
+
+          <div class="callout p-4 mb-3">
+            <div class="fw-semibold mb-1">What can it read?</div>
+            <div class="small text-secondary mb-0"><code>enroll explain</code> accepts a harvest bundle directory, a direct path to <code>state.json</code>, a <code>.tar.gz</code>/<code>.tgz</code> bundle, or an encrypted <code>.tar.gz.sops</code> bundle.</div>
+          </div>
+
+          <div class="codeblock terminal">
+            <button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#enroll-explain-basic"><i class="bi bi-clipboard"></i> Copy</button>
+            <pre class="mb-0"><code id="enroll-explain-basic"><span class="prompt">$</span> enroll explain /tmp/enroll-harvest
+
+# or point at the state.json path directly
+<span class="prompt">$</span> enroll explain /tmp/enroll-harvest/state.json</code></pre>
+          </div>
+
+          <br />
+          <p class="text-secondary">The default output is human-readable text. For scripting or deeper inspection, use JSON output:</p>
+          <div class="codeblock terminal">
+            <button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#enroll-explain-json"><i class="bi bi-clipboard"></i> Copy</button>
+            <pre class="mb-0"><code id="enroll-explain-json"><span class="prompt">$</span> enroll explain /tmp/enroll-harvest --format json | jq .
+
+# show more example paths per reason
+<span class="prompt">$</span> enroll explain /tmp/enroll-harvest --max-examples 10</code></pre>
+          </div>
+
+          <br />
+          <p class="text-secondary">If you stored a harvest as a single SOPS-encrypted bundle, <code>enroll explain</code> can decrypt it on the fly (it will also auto-detect files ending with <code>.sops</code>):</p>
+          <div class="codeblock terminal">
+            <button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#enroll-explain-sops"><i class="bi bi-clipboard"></i> Copy</button>
+            <pre class="mb-0"><code id="enroll-explain-sops"><span class="prompt">$</span> enroll explain /var/lib/enroll/harvest.tar.gz.sops --sops</code></pre>
+          </div>
+
+          <br />
+          <p class="text-secondary">What you get back:</p>
+          <ul class="mb-0 small">
+            <li>A summary of what roles were collected (users, services, package snapshots, <code>etc_custom</code>, <code>usr_local_custom</code>, etc.).</li>
+            <li>Why packages ended up in inventory (<code>observed_via</code>), e.g. user-installed vs referenced by a harvested systemd unit.</li>
+            <li>Breakdowns of <code>managed_files.reason</code>, <code>managed_dirs.reason</code>, and <code>excluded.reason</code>, with a few example paths for each reason.</li>
+          </ul>
+
+          <div class="alert alert-secondary mt-3 mb-0">
+            <div class="fw-semibold">Tip</div>
+            <div class="small mb-0">Use <code>enroll explain</code> after a first harvest to decide what to exclude (noise) and what to include (snowflake app/config under <code>/opt</code>, <code>/srv</code>, etc.) before you generate a manifest.</div>
+            <br />
+            <div class="small mb-0"><strong>Security note:</strong> <code>enroll explain</code> doesn't print file contents, but it can print path names and unit/package names. Treat the output as sensitive if your environment uses revealing path conventions (and especially if you harvested with <code>--dangerous</code>).</div>
+          </div>
+        </section>
+
+
         <section id="tips" class="scroll-mt-nav">
           <h2 class="section-title fw-bold">Tips</h2>
           <div class="row g-3">
diff --git a/src/examples.html b/src/examples.html
index 568b28f..b5d8f9e 100644
--- a/src/examples.html
+++ b/src/examples.html
@@ -123,6 +123,23 @@
           <p class="small text-secondary mt-2 mb-0">Use it in cron or CI to alert on change.</p>
         </div>
       </div>
+
+      <div class="col-lg-6">
+        <div class="feature-card p-4 h-100">
+          <div class="fw-semibold mb-2">Explain a harvest with <code>enroll explain</code></div>
+          <div class="codeblock terminal">
+            <button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-explain"><i class="bi bi-clipboard"></i> Copy</button>
+            <pre class="mb-0"><code id="ex-explain"><span class="prompt">$</span> enroll explain /tmp/enroll-harvest
+
+# machine-readable (reasons, examples, inventory breakdown)
+<span class="prompt">$</span> enroll explain /tmp/enroll-harvest --format json | jq .
+
+# encrypted bundle
+<span class="prompt">$</span> enroll explain /var/lib/enroll/harvest.tar.gz.sops --sops</code></pre>
+          </div>
+          <p class="small text-secondary mt-2 mb-0">Great for answering "why did it include/exclude that file?" before you generate a manifest.</p>
+        </div>
+      </div>
     </div>
 
     <hr class="my-5">