Doc updates for 0.4.0

src/content/_index.html

@@ -211,8 +211,10 @@ ansible-playbook ./ansible/playbooks/"$(hostname -f)".yml</code></pre>
       <div class="tab-pane fade" id="qs4" role="tabpanel" aria-labelledby="qs4-tab">
         <div class="codeblock">
           <button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#qs4code"><i class="bi bi-clipboard"></i> Copy</button>
-          <pre class="terminal mb-0"><code id="qs4code"># Compare two harvests and get a human-friendly report
-enroll diff --old /path/to/harvestA --new /path/to/harvestB --format markdown
+          <pre class="terminal mb-0"><code id="qs4code"># Compare two harvests and get a human-friendly report (ignoring noise)
+enroll diff --old /path/to/harvestA --new /path/to/harvestB --format markdown \
+  --exclude-path /var/anacron \
+  --ignore-package-versions
 
 # Send a webhook when differences are detected
 enroll diff \
@@ -221,7 +223,15 @@ enroll diff \
   --webhook https://example.net/webhook \
   --webhook-format json \
   --webhook-header 'X-Enroll-Secret: ...' \
-  --exit-code</code></pre>
+  --ignore-package-versions \
+  --exit-code
+
+# Ignore a path and changes to package versions, and optionally
+# enforce the old state locally (requires ansible-playbook)
+enroll diff --old /path/to/harvestA --new /path/to/harvestB \
+  --exclude-path /var/anacron \
+  --ignore-package-versions \
+  --enforce</code></pre>
         </div>
         <div class="smallprint mt-3">E-mail notifications are also supported. Run it on a systemd timer to alert to drift!</div>
       </div>
@@ -285,8 +295,8 @@ enroll explain /path/to/harvest.sops \
         <div class="card feature-card h-100">
           <div class="card-body p-4">
             <div class="fw-semibold mb-1">Diff</div>
-            <div class="text-muted mb-3">Drift report + webhook/email notifications.</div>
-            <div class="asciicast" data-asciinema-id="765128"><script src="https://asciinema.org/a/765128.js" id="asciicast-765128" async="true"></script></div>
+	    <div class="text-muted mb-3">Drift report + webhook/email notifications, or optionally <em>enforce</em> the previous state!</div>
+            <div class="asciicast" data-asciinema-id="766934"><script src="https://asciinema.org/a/766934.js" id="asciicast-766934" async="true"></script></div>
           </div>
         </div>
       </div>

src/content/docs.html

@@ -167,6 +167,11 @@ description: "How Enroll works: harvest, manifest, modes, and configuration."
             <pre class="mb-0"><code><span class="prompt">$</span> enroll manifest --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --fqdn "$(hostname -f)"
 <span class="prompt">$</span> ansible-playbook /tmp/enroll-ansible/playbooks/"$(hostname -f)".yml</code></pre>
           </div>
+
+          <div class="alert alert-secondary mt-3 mb-0">
+            <div class="fw-semibold">Tip: role tags</div>
+            <div class="small mb-0">Generated playbooks tag each role as <code>role_&lt;name&gt;</code> (e.g. <code>role_users</code>, <code>role_services</code>, <code>role_other</code>). You can target a subset with <code>ansible-playbook ... --tags role_users</code>.</div>
+          </div>
         </section>
 
         <section id="remote" class="scroll-mt-nav mb-5">
@@ -241,7 +246,13 @@ exclude_path = /usr/local/bin/docker-*, /usr/local/bin/some-tool
 
 [manifest]
 no_jinjaturtle = true
-sops = 00AE817C24A10C2540461A9C1D7CDE0234DB458D</code></pre>
+sops = 00AE817C24A10C2540461A9C1D7CDE0234DB458D
+
+[diff]
+# ignore noisy drift
+exclude_path = /var/anacron
+ignore_package_versions = true
+# enforce = true  # requires ansible-playbook on PATH</code></pre>
           </div>
 
           <div class="alert alert-secondary mt-3 mb-0">
@@ -263,6 +274,21 @@ sops = 00AE817C24A10C2540461A9C1D7CDE0234DB458D</code></pre>
 
           <p class="text-secondary">A great way to use <code>enroll diff</code> is to run it periodically (e.g via cron or a systemd timer). Below is an example.</p>
 
+          <div class="callout p-4 mb-3">
+            <div class="fw-semibold mb-1">Noise suppression</div>
+            <div class="small text-secondary mb-0">Use <code>--exclude-path</code> to ignore file/dir drift under specific paths (e.g. <code>/var/anacron</code>). Use <code>--ignore-package-versions</code> to ignore routine package upgrades/downgrades while still reporting added/removed packages.</div>
+          </div>
+
+          <div class="terminal mb-4">
+            <pre class="mb-0"><code><span class="prompt">$</span> enroll diff --old /path/to/harvestA --new /path/to/harvestB   --exclude-path /var/anacron   --ignore-package-versions</code></pre>
+          </div>
+
+          <div class="callout p-4 mb-3">
+            <div class="fw-semibold mb-1">Optional: enforce the old harvest state (<code>--enforce</code>)</div>
+            <div class="small text-secondary mb-0">If drift exists and <code>ansible-playbook</code> is on <code>PATH</code>, Enroll can generate a manifest from the <em>old</em> harvest and apply it locally to restore expected state. It avoids package downgrades, and will often run Ansible with <code>--tags role_...</code> so only the roles implicated by the drift are applied. This is very much like a return to Puppet's agent mode!</div>
+          </div>
+
+
           <p class="text-secondary">Store the below file at <code>/usr/local/bin/enroll-harvest-diff.sh</code> and make it executable.</p>
           <div class="codeblock terminal">
             <button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#enroll-harvest-diff"><i class="bi bi-clipboard"></i> Copy</button>

src/content/examples.html

@@ -68,15 +68,13 @@ description: "Copy/paste recipes for Enroll: one host, fleets, drift detection,
           <div class="fw-semibold mb-2">Drift detection with <code>enroll diff</code></div>
           <div class="codeblock terminal">
             <button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-diff"><i class="bi bi-clipboard"></i> Copy</button>
-            <pre class="mb-0"><code id="ex-diff"><span class="prompt">$</span> enroll diff \
-  --old /path/to/harvestA \
-  --new /path/to/harvestB \
-  --format markdown
+            <pre class="mb-0"><code id="ex-diff"><span class="prompt">$</span> enroll diff --old /path/to/harvestA   --new /path/to/harvestB   --format markdown   --exclude-path /var/anacron   --ignore-package-versions
 <span class="prompt">$</span> enroll diff --old /path/to/golden --new /path/to/current \
-  --webhook https://example.net/webhook \
+  --webhook https://example.net/webhook  \
   --webhook-format json \
-  --webhook-header 'X-Enroll-Secret: ...' \
-  --exit-code</code></pre>
+  --webhook-header 'X-Enroll-Secret: ...'  \
+   --ignore-package-versions --exit-code
+            </code></pre>
           </div>
           <p class="small text-secondary mt-2 mb-0">Use it in cron or CI to alert on change.</p>
         </div>
@@ -98,6 +96,22 @@ description: "Copy/paste recipes for Enroll: one host, fleets, drift detection,
           <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 class="col-lg-6">
+        <div class="feature-card p-4 h-100">
+          <div class="fw-semibold mb-2">Enforce the previous state with <code>enroll diff --enforce</code></div>
+          <div class="codeblock terminal">
+            <button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-diff"><i class="bi bi-clipboard"></i> Copy</button>
+            <pre class="mb-0"><code id="ex-diff"><span class="prompt">$</span> enroll diff \
+  --old /path/to/harvestA \
+  --new /path/to/harvestB \
+  --enforce \
+  --format json
+	    </code></pre>
+          </div>
+	  <p class="small text-secondary mt-2 mb-0">Enforcing the old harvest will restore its files/perms, missing packages, changed services or users, if <code>ansible-playbook</code> is on the PATH.</p>
+        </div>
+      </div>
     </div>
 
     <hr class="my-5">