docs(site): SEO pass — social card, structured data, ten disk-space guides

AGENTS.md

@@ -138,3 +138,4 @@ Code, comments, commit messages, documentation, and all CLI text are in English.
 - Spec changes: edit `docs/cli-spec.md`, bump its version, add an ADR, update snapshots. Never leave code and spec disagreeing.
 - Research before writing new utility code: check crates.io and the reuse list in `docs/implementation-plan.md` §2.
 - When a macOS behavior is uncertain (see `docs/implementation-plan.md` §9), write the check as a test with a fixture, not as an assumption in code.
+- The guides under `site/explain/` copy prose verbatim from `crates/broza/src/detect/category_text.rs`, `crates/broza/src/adapters/diskutil/purpose.rs` and the README. When one of those paragraphs changes, update the matching page and its `<lastmod>` in `site/sitemap.xml`.

README.md

@@ -1,15 +1,16 @@
 # Broza — safe disk cleanup CLI for macOS
 
 Broza is an open-source command-line tool that analyzes your Mac's APFS storage, explains what
-"System Data" and purgeable space really are, and frees disk space with a dry-run first and a
-reversible quarantine. Built in Rust for Apple Silicon.
+"System Data" and purgeable space really are, and frees disk space (Xcode DerivedData,
+`node_modules`, Docker, caches, snapshots) with a dry-run first and a reversible quarantine.
+Built in Rust for Apple Silicon.
 
 [![CI](https://github.com/borlafu/broza/actions/workflows/ci.yml/badge.svg)](https://github.com/borlafu/broza/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/borlafu/broza)](https://github.com/borlafu/broza/releases/latest)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Ko-fi](https://img.shields.io/badge/Ko--fi-support-ff5e5b?logo=ko-fi&logoColor=white)](https://ko-fi.com/borlafu)
 
-Website: [borlafu.github.io/broza](https://borlafu.github.io/broza/)
+Website: [borlafu.github.io/broza](https://borlafu.github.io/broza/) · [Mac disk space guides](https://borlafu.github.io/broza/explain/)
 
 ## Why Broza
 

site/404.html

@@ -0,0 +1,47 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Page not found | Broza</title>
+<meta name="robots" content="noindex">
+<link rel="icon" href="/broza/assets/favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="/broza/styles.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+
+<header class="nav">
+  <div class="wrap nav-inner">
+    <a class="brand" href="/broza/">
+      <svg width="20" height="20" viewBox="-16 -56 32 60" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" style="color:var(--leaf)" aria-hidden="true"><path d="M0 0 C14 -16 14 -36 0 -52 C-14 -36 -14 -16 0 0 Z"/><path d="M0 -2 L0 -46"/></svg>
+      broza
+    </a>
+    <nav class="nav-links" aria-label="Sections">
+      <a href="/broza/#quick-start">quick start</a>
+      <a href="/broza/#demo">demo</a>
+      <a href="/broza/#features">features</a>
+      <a href="/broza/#safety">safety</a>
+      <a href="/broza/explain/">guides</a>
+      <a class="repo" href="https://github.com/borlafu/broza">github</a>
+    </nav>
+  </div>
+</header>
+<main id="main" class="article wrap">
+<h1>Nothing here — it may have been trimmed.</h1>
+<p class="article-lede">That page does not exist. Try the <a href="/broza/">home page</a> or the <a href="/broza/explain/">disk space guides</a>.</p>
+</main>
+<footer class="footer">
+  <div class="wrap footer-inner">
+    <p>MIT licensed · <em>broza</em> is Spanish for brushwood or useless clutter. Pronounced BRO-zah.</p>
+    <ul>
+      <li><a href="https://github.com/borlafu/broza">Source</a></li>
+      <li><a href="https://github.com/borlafu/broza/releases/latest">Releases</a></li>
+      <li><a href="/broza/explain/">Guides</a></li>
+      <li><a href="https://github.com/borlafu/broza/blob/main/docs/cli-spec.md">CLI spec</a></li>
+      <li><a href="https://ko-fi.com/borlafu">Ko-fi</a></li>
+    </ul>
+  </div>
+</footer>
+</body>
+</html>

site/explain/cloud-synced-files.html

@@ -0,0 +1,130 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Free space without deleting iCloud or Dropbox files | Broza</title>
+<meta name="description" content="Deleting a synced file deletes it from the cloud and every device. How to see how much iCloud Drive, Dropbox, OneDrive or Google Drive keeps locally, safely.">
+<link rel="canonical" href="https://borlafu.github.io/broza/explain/cloud-synced-files.html">
+<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
+<meta name="theme-color" content="#fcf8f0">
+<meta property="og:type" content="article">
+<meta property="og:site_name" content="Broza">
+<meta property="og:title" content="Free space on a Mac without deleting iCloud or Dropbox files">
+<meta property="og:description" content="Deleting a synced file deletes it from the cloud and every device. How to see how much iCloud Drive, Dropbox, OneDrive or Google Drive keeps locally, safely.">
+<meta property="og:url" content="https://borlafu.github.io/broza/explain/cloud-synced-files.html">
+<meta property="og:image" content="https://borlafu.github.io/broza/assets/og.png">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:image" content="https://borlafu.github.io/broza/assets/og.png">
+<script type="application/ld+json">
+[
+ {
+  "@context": "https://schema.org",
+  "@type": "TechArticle",
+  "headline": "Free space on a Mac without deleting iCloud or Dropbox files",
+  "description": "Deleting a synced file deletes it from the cloud and every device. How to see how much iCloud Drive, Dropbox, OneDrive or Google Drive keeps locally, safely.",
+  "url": "https://borlafu.github.io/broza/explain/cloud-synced-files.html",
+  "datePublished": "2026-09-26",
+  "dateModified": "2026-09-26",
+  "image": "https://borlafu.github.io/broza/assets/og.png",
+  "inLanguage": "en",
+  "author": {
+   "@type": "Person",
+   "name": "Borja Lafuente",
+   "url": "https://github.com/borlafu"
+  },
+  "publisher": {
+   "@type": "Organization",
+   "name": "Broza",
+   "url": "https://borlafu.github.io/broza/"
+  },
+  "about": {
+   "@type": "SoftwareApplication",
+   "name": "Broza",
+   "url": "https://borlafu.github.io/broza/"
+  }
+ },
+ {
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+   {
+    "@type": "ListItem",
+    "position": 1,
+    "name": "Broza",
+    "item": "https://borlafu.github.io/broza/"
+   },
+   {
+    "@type": "ListItem",
+    "position": 2,
+    "name": "Guides",
+    "item": "https://borlafu.github.io/broza/explain/"
+   },
+   {
+    "@type": "ListItem",
+    "position": 3,
+    "name": "Free space on a Mac without deleting iCloud or Dropbox files",
+    "item": "https://borlafu.github.io/broza/explain/cloud-synced-files.html"
+   }
+  ]
+ }
+]
+</script>
+<link rel="stylesheet" href="../styles.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+<header class="nav">
+  <div class="wrap nav-inner">
+    <a class="brand" href="../">
+      <svg width="20" height="20" viewBox="-16 -56 32 60" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" style="color:var(--leaf)" aria-hidden="true"><path d="M0 0 C14 -16 14 -36 0 -52 C-14 -36 -14 -16 0 0 Z"/><path d="M0 -2 L0 -46"/></svg>
+      broza
+    </a>
+    <nav class="nav-links" aria-label="Sections">
+      <a href="../#quick-start">quick start</a>
+      <a href="../#features">features</a>
+      <a href="./">guides</a>
+      <a class="repo" href="https://github.com/borlafu/broza">github</a>
+    </nav>
+  </div>
+</header>
+
+<main id="main" class="article wrap">
+<nav class="crumbs" aria-label="Breadcrumb"><a href="../">Broza</a> <span aria-hidden="true">›</span> <a href="./">Guides</a></nav>
+<h1>Free space on a Mac without deleting iCloud or Dropbox files</h1>
+<p class="article-meta"><span class="risk risk-info">INFO ONLY</span> <code>cloud-synced</code></p>
+<p class="article-lede">Files already synced to iCloud Drive, Dropbox, OneDrive or Google Drive. Reported only, never deleted.</p>
+<h2>What it is</h2>
+<p>Local copies of files that a cloud provider already holds: iCloud Drive, Dropbox, OneDrive or Google Drive. The provider knows them as synced; your disk knows them as ordinary files.</p>
+<h2>What it is for</h2>
+<p>They are the copy you work on. Freeing the space means asking the provider to evict the local copy and keep the file available on demand, which is a sync operation and not a deletion.</p>
+<h2>Is it safe to delete?</h2>
+<p>Broza never deletes these. Deleting a synced file with a file manager deletes it from the cloud too, and from every other device, which is exactly the kind of mistake this tool exists to avoid. Broza reports the size and prints the provider's own instructions for freeing it.</p>
+<h2>What Broza does instead</h2><p>Cloud-synced files are always INFO ONLY, and no flag changes that: <code>broza clean --category cloud-synced</code> is rejected outright. Broza reports the bytes the provider holds on this disk, per provider, and prints that provider's own steps for freeing them.</p>
+<h2>Check it on your Mac</h2>
+<p>Broza is a free, open-source command-line tool. Every command below is read-only except <code>clean</code>, and <code>clean</code> is a dry run until you add <code>--apply</code>.</p>
+<div class="cmdline"><code><span class="sh" aria-hidden="true">$</span> broza explain cloud-synced</code><button class="copy-mini" type="button" data-copy-text="broza explain cloud-synced" aria-label="Copy the command"><span aria-hidden="true">copy</span></button></div>
+<div class="cmdline"><code><span class="sh" aria-hidden="true">$</span> broza suggest --category cloud-synced</code><button class="copy-mini" type="button" data-copy-text="broza suggest --category cloud-synced" aria-label="Copy the command"><span aria-hidden="true">copy</span></button></div>
+<p class="article-install">Not installed yet? <a href="../#quick-start">Install Broza</a> with Homebrew, the installer script, or Cargo.</p>
+<h2>Related guides</h2>
+<ul class="related">
+<li><a href="iphone-backups.html">Old iPhone backups on your Mac: find and remove them</a></li>
+<li><a href="system-data.html">What is &quot;System Data&quot; on a Mac, and how to shrink it</a></li>
+<li><a href="library-caches.html">Is it safe to delete ~/Library/Caches on a Mac?</a></li>
+</ul>
+</main>
+
+<footer class="footer">
+  <div class="wrap footer-inner">
+    <p>MIT licensed · <em>broza</em> is Spanish for brushwood or useless clutter. Pronounced BRO-zah.</p>
+    <ul>
+      <li><a href="../">Home</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="https://github.com/borlafu/broza">Source</a></li>
+      <li><a href="https://github.com/borlafu/broza/releases/latest">Releases</a></li>
+    </ul>
+  </div>
+</footer>
+<script src="../ui.js" defer></script>
+</body>
+</html>

site/explain/docker-disk-image.html

@@ -0,0 +1,130 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Docker.raw taking up space on your Mac? What to do | Broza</title>
+<meta name="description" content="Docker Desktop keeps every image and volume in one virtual disk, Docker.raw. Why it grows, why you should not delete it by hand, and how to shrink it.">
+<link rel="canonical" href="https://borlafu.github.io/broza/explain/docker-disk-image.html">
+<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
+<meta name="theme-color" content="#fcf8f0">
+<meta property="og:type" content="article">
+<meta property="og:site_name" content="Broza">
+<meta property="og:title" content="Docker.raw taking up space on your Mac? What to do">
+<meta property="og:description" content="Docker Desktop keeps every image and volume in one virtual disk, Docker.raw. Why it grows, why you should not delete it by hand, and how to shrink it.">
+<meta property="og:url" content="https://borlafu.github.io/broza/explain/docker-disk-image.html">
+<meta property="og:image" content="https://borlafu.github.io/broza/assets/og.png">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:image" content="https://borlafu.github.io/broza/assets/og.png">
+<script type="application/ld+json">
+[
+ {
+  "@context": "https://schema.org",
+  "@type": "TechArticle",
+  "headline": "Docker.raw taking up space on your Mac? What to do",
+  "description": "Docker Desktop keeps every image and volume in one virtual disk, Docker.raw. Why it grows, why you should not delete it by hand, and how to shrink it.",
+  "url": "https://borlafu.github.io/broza/explain/docker-disk-image.html",
+  "datePublished": "2026-09-26",
+  "dateModified": "2026-09-26",
+  "image": "https://borlafu.github.io/broza/assets/og.png",
+  "inLanguage": "en",
+  "author": {
+   "@type": "Person",
+   "name": "Borja Lafuente",
+   "url": "https://github.com/borlafu"
+  },
+  "publisher": {
+   "@type": "Organization",
+   "name": "Broza",
+   "url": "https://borlafu.github.io/broza/"
+  },
+  "about": {
+   "@type": "SoftwareApplication",
+   "name": "Broza",
+   "url": "https://borlafu.github.io/broza/"
+  }
+ },
+ {
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+   {
+    "@type": "ListItem",
+    "position": 1,
+    "name": "Broza",
+    "item": "https://borlafu.github.io/broza/"
+   },
+   {
+    "@type": "ListItem",
+    "position": 2,
+    "name": "Guides",
+    "item": "https://borlafu.github.io/broza/explain/"
+   },
+   {
+    "@type": "ListItem",
+    "position": 3,
+    "name": "Docker.raw taking up space on your Mac? What to do",
+    "item": "https://borlafu.github.io/broza/explain/docker-disk-image.html"
+   }
+  ]
+ }
+]
+</script>
+<link rel="stylesheet" href="../styles.css">
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+<header class="nav">
+  <div class="wrap nav-inner">
+    <a class="brand" href="../">
+      <svg width="20" height="20" viewBox="-16 -56 32 60" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" style="color:var(--leaf)" aria-hidden="true"><path d="M0 0 C14 -16 14 -36 0 -52 C-14 -36 -14 -16 0 0 Z"/><path d="M0 -2 L0 -46"/></svg>
+      broza
+    </a>
+    <nav class="nav-links" aria-label="Sections">
+      <a href="../#quick-start">quick start</a>
+      <a href="../#features">features</a>
+      <a href="./">guides</a>
+      <a class="repo" href="https://github.com/borlafu/broza">github</a>
+    </nav>
+  </div>
+</header>
+
+<main id="main" class="article wrap">
+<nav class="crumbs" aria-label="Breadcrumb"><a href="../">Broza</a> <span aria-hidden="true">›</span> <a href="./">Guides</a></nav>
+<h1>Docker.raw taking up space on your Mac? What to do</h1>
+<p class="article-meta"><span class="risk risk-review">REVIEW</span> <code>build-cache</code></p>
+<p class="article-lede">Docker Desktop stores its images, containers and volumes inside one virtual disk file, <code>Docker.raw</code>. It grows as you pull and build, and it does not shrink by itself.</p>
+<h2>What it is</h2>
+<p>Everything a compiler or a package manager wrote so it would not have to do the work twice: Xcode DerivedData and Archives, node_modules directories, __pycache__, .gradle, Rust target/ directories, and the virtual disk Docker Desktop stores its images in.</p>
+<h2>What it is for</h2>
+<p>It makes the second build faster than the first. On a developer's Mac it is usually the single largest reclaimable category, and none of it is source code: every byte is reproducible from a repository and a build command.</p>
+<h2>Is it safe to delete?</h2>
+<p>Yes for the build outputs, which Broza moves to quarantine; the next build recreates them. The Docker virtual disk is the exception: Broza only reports its size and points at <code>docker system prune</code>, because shrinking that file is Docker's job, not a file manager's.</p>
+<h2>How Broza handles the Docker disk image</h2><p>Broza reports <code>Docker.raw</code> with its allocated size on disk, as an inform-only finding. It never calls the Docker daemon and never moves or deletes the file: shrinking it is Docker's job. Instead it points at <code>docker system prune</code> and Docker Desktop's disk settings.</p>
+<h2>Check it on your Mac</h2>
+<p>Broza is a free, open-source command-line tool. Every command below is read-only except <code>clean</code>, and <code>clean</code> is a dry run until you add <code>--apply</code>.</p>
+<div class="cmdline"><code><span class="sh" aria-hidden="true">$</span> broza explain build-cache</code><button class="copy-mini" type="button" data-copy-text="broza explain build-cache" aria-label="Copy the command"><span aria-hidden="true">copy</span></button></div>
+<div class="cmdline"><code><span class="sh" aria-hidden="true">$</span> docker system prune</code><button class="copy-mini" type="button" data-copy-text="docker system prune" aria-label="Copy the command"><span aria-hidden="true">copy</span></button></div>
+<p class="article-install">Not installed yet? <a href="../#quick-start">Install Broza</a> with Homebrew, the installer script, or Cargo.</p>
+<h2>Related guides</h2>
+<ul class="related">
+<li><a href="xcode-deriveddata.html">Is it safe to delete Xcode DerivedData?</a></li>
+<li><a href="node-modules.html">Find and remove orphan node_modules on a Mac</a></li>
+<li><a href="system-data.html">What is &quot;System Data&quot; on a Mac, and how to shrink it</a></li>
+</ul>
+</main>
+
+<footer class="footer">
+  <div class="wrap footer-inner">
+    <p>MIT licensed · <em>broza</em> is Spanish for brushwood or useless clutter. Pronounced BRO-zah.</p>
+    <ul>
+      <li><a href="../">Home</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="https://github.com/borlafu/broza">Source</a></li>
+      <li><a href="https://github.com/borlafu/broza/releases/latest">Releases</a></li>
+    </ul>
+  </div>
+</footer>
+<script src="../ui.js" defer></script>
+</body>
+</html>