diff --git a/AGENTS.md b/AGENTS.md
index ea2e2c7d..16d702d8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -67,6 +67,21 @@ Preferred verification flow for docs/content changes:
 
 ## Docs Authoring Rules
 
+### User Journey Funnel
+
+Maintain a directed "funnel" for documentation to maximize user success and conversion:
+
+1.  **Phase 1: Quickstart (Local Demo)** — The primary entry point. Run `html2rss-web` with Docker and generate a feed from a page URL in minutes.
+2.  **Phase 2: Production (Deployment)** — The goal for invested users. Move to a stable, production-ready instance.
+3.  **Phase 3: Refinement (Custom Configs)** — Secondary optimization. Author custom YAML configs only when automatic generation needs precise control.
+
+**Rules for Funnel Maintenance:**
+
+- Avoid branching paths in introductory pages; always point toward the next phase in the funnel.
+- Define "html2rss-web" as the primary interface and "page-to-RSS" as the primary workflow.
+- Use "Feed Directory" consistently to refer to the pre-built feed catalog; avoid terms like "catalog", "included feeds", or "packaged configs" in user-facing docs.
+- Do not introduce new terminology (e.g., "toolkit") or unrelated infrastructure concepts (e.g., "custom domains") unless they are essential to a specific guide.
+
 ### Code Snippets
 
 In docs content (`src/content/docs/**`) and docs-supporting components:
diff --git a/astro.config.mjs b/astro.config.mjs
index 2cb7056f..b1775a3c 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -13,6 +13,19 @@ export default defineConfig({
     "/components/html2rss": "/ruby-gem/",
     "/components/html2rss-configs": "/creating-custom-feeds/",
     "/components": "/",
+    "/web-application/how-to/deployment": "/web-application/deployment/",
+    "/web-application/how-to/automatic-updates": "/web-application/deployment/#auto-update-with-watchtower",
+    "/web-application/how-to/use-automatic-feed-generation":
+      "/web-application/guides/use-the-feed-directory/",
+    "/web-application/how-to/use-automatic-feed-generation/":
+      "/web-application/guides/use-the-feed-directory/",
+    "/web-application/how-to": "/web-application/guides/",
+    "/ruby-gem/how-to/dynamic-parameters": "/ruby-gem/guides/dynamic-parameters/",
+    "/ruby-gem/how-to/dynamic-parameters/": "/ruby-gem/guides/dynamic-parameters/",
+    "/ruby-gem/how-to": "/ruby-gem/guides/",
+    "/ruby-gem/tutorials": "/ruby-gem/guides/",
+    "/ruby-gem/tutorials/": "/ruby-gem/guides/",
+    "/web-application/guides/use-included-configs": "/web-application/guides/use-the-feed-directory/",
   },
   build: {
     inlineStylesheets: "auto",
@@ -249,7 +262,7 @@ export default defineConfig({
       sidebar: [
         {
           label: "Getting Started",
-          link: "/getting-started",
+          link: "/getting-started/",
         },
         {
           label: "Feed Directory",
@@ -257,7 +270,7 @@ export default defineConfig({
         },
         {
           label: "Create Custom Feeds",
-          link: "/creating-custom-feeds",
+          link: "/creating-custom-feeds/",
         },
         {
           label: "Web Application",
@@ -265,18 +278,15 @@ export default defineConfig({
           items: [
             "web-application",
             "web-application/getting-started",
+            "web-application/deployment",
             {
-              label: "How-to",
-              autogenerate: { directory: "web-application/how-to" },
+              label: "Guides",
+              autogenerate: { directory: "web-application/guides" },
             },
             {
               label: "Reference",
               autogenerate: { directory: "web-application/reference" },
             },
-            {
-              label: "Tutorials",
-              autogenerate: { directory: "web-application/tutorials" },
-            },
           ],
         },
         {
@@ -286,22 +296,22 @@ export default defineConfig({
             "ruby-gem",
             "ruby-gem/installation",
             {
-              label: "How-to",
-              autogenerate: { directory: "ruby-gem/how-to" },
-            },
-            {
-              label: "Reference",
-              autogenerate: { directory: "ruby-gem/reference" },
+              label: "Guides",
+              autogenerate: { directory: "ruby-gem/guides" },
             },
             {
               label: "Tutorials",
               autogenerate: { directory: "ruby-gem/tutorials" },
             },
+            {
+              label: "Reference",
+              autogenerate: { directory: "ruby-gem/reference" },
+            },
           ],
         },
         {
           label: "About",
-          link: "/about",
+          link: "/about/",
         },
         {
           label: "Get Involved",
diff --git a/examples/deployment/.env b/examples/deployment/.env
index 62f8201d..2d62b809 100644
--- a/examples/deployment/.env
+++ b/examples/deployment/.env
@@ -1,26 +1,14 @@
-# Domain & routing
-CADDY_HOST=example.com
-
-# Core runtime
-RACK_ENV=production
-
-# Security
+# Production secrets
 # Generate with: openssl rand -hex 32
 HTML2RSS_SECRET_KEY=replace-with-64-hex-characters-generated-by-openssl-rand-hex-32
 
-# Authenticated health endpoint token
-# Required by the documented Compose stack.
-# If you build a custom stack and probe only /api/v1/health/live and /api/v1/health/ready,
-# you can omit this value.
-HEALTH_CHECK_TOKEN=replace-with-strong-health-token
-
-# Auto source (optional; keep false unless you need automatic feed generation)
-AUTO_SOURCE_ENABLED=false
+# Web UI / feed creation token
+# Paste this into the web app when it asks for an access token.
+HTML2RSS_ACCESS_TOKEN=replace-with-strong-access-token
 
-# Observability (optional)
-#SENTRY_DSN=
+# Optional authenticated health token
+# Set this only if you plan to use GET /api/v1/health instead of /api/v1/health/ready.
+# HEALTH_CHECK_TOKEN=replace-with-strong-health-token
 
-# Performance tuning (override defaults only when needed)
-WEB_CONCURRENCY=2
-WEB_MAX_THREADS=5
-RACK_TIMEOUT_SERVICE_TIMEOUT=15
+# `AUTO_SOURCE_ENABLED=true` and `BOTASAURUS_SCRAPER_URL=http://botasaurus:4010`
+# come from docker-compose.yml in this example.
diff --git a/examples/deployment/docker-compose.yml b/examples/deployment/docker-compose.yml
index 3774a619..3b796c3b 100644
--- a/examples/deployment/docker-compose.yml
+++ b/examples/deployment/docker-compose.yml
@@ -6,43 +6,13 @@ services:
       - path: .env
         required: false
     environment:
+      RACK_ENV: production
       PORT: 4000
+      HTML2RSS_SECRET_KEY: ${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
+      HTML2RSS_ACCESS_TOKEN: ${HTML2RSS_ACCESS_TOKEN:?set HTML2RSS_ACCESS_TOKEN}
+      AUTO_SOURCE_ENABLED: "true"
       BOTASAURUS_SCRAPER_URL: http://botasaurus:4010
 
   botasaurus:
     image: html2rss/botasaurus-scrape-api:latest
     restart: unless-stopped
-
-  caddy:
-    image: caddy:2-alpine
-    depends_on:
-      - html2rss-web
-    command:
-      - caddy
-      - reverse-proxy
-      - --from
-      - ${CADDY_HOST}
-      - --to
-      - html2rss-web:4000
-    ports:
-      - "80:80"
-      - "443:443"
-    volumes:
-      - caddy_data:/data
-
-  watchtower:
-    image: containrrr/watchtower
-    depends_on:
-      - html2rss-web
-      - caddy
-      - botasaurus
-    command:
-      - --cleanup
-      - --interval
-      - "7200"
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-    restart: unless-stopped
-
-volumes:
-  caddy_data:
diff --git a/src/components/docs/AutoGenerationOptional.astro b/src/components/docs/AutoGenerationOptional.astro
index 982682bb..225e558b 100644
--- a/src/components/docs/AutoGenerationOptional.astro
+++ b/src/components/docs/AutoGenerationOptional.astro
@@ -3,6 +3,7 @@ import { Aside } from "@astrojs/starlight/components";
 ---
 
 <Aside type="note" title="Automatic generation may be disabled">
-  The direct `Create a feed` workflow is not enabled on every deployment. If you want that path, continue with
-  <a href="/web-application/how-to/use-automatic-feed-generation/">Use automatic feed generation</a>.
+  The Feed Directory is the fallback path when it already covers your site. If you want the primary page-URL
+  flow on your own instance, continue with
+  <a href="/web-application/guides/use-automatic-feed-generation/">Use automatic feed generation</a>.
 </Aside>
diff --git a/src/components/docs/DockerComposeSnippet.astro b/src/components/docs/DockerComposeSnippet.astro
index 0ced6c48..ee161f5c 100644
--- a/src/components/docs/DockerComposeSnippet.astro
+++ b/src/components/docs/DockerComposeSnippet.astro
@@ -1,6 +1,6 @@
 ---
 import { Code } from "@astrojs/starlight/components";
-import { botasaurusImage, browserlessImage, caddyImage, watchtowerImage, webImage } from "../../data/docker";
+import { botasaurusImage, caddyImage, watchtowerImage, webImage } from "../../data/docker";
 
 interface Props {
   variant: "minimal" | "productionCaddy" | "secure" | "watchtower" | "resourceGuardrails";
@@ -12,35 +12,15 @@ const snippets: Record<Props["variant"], string> = {
   minimal: `services:
   html2rss-web:
     image: ${webImage}
-    restart: unless-stopped
     ports:
       - "127.0.0.1:4000:4000"
-    env_file:
-      - path: .env
-        required: false
     environment:
-      RACK_ENV: production
-      PORT: 4000
-      HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
-      HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
-      SENTRY_DSN: \${SENTRY_DSN:-}
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
-      BROWSERLESS_IO_API_TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
+      RACK_ENV: development
+      HTML2RSS_ACCESS_TOKEN: CHANGE_ME_ADMIN_TOKEN
       BOTASAURUS_SCRAPER_URL: http://botasaurus:4010
 
   botasaurus:
-    image: ${botasaurusImage}
-    restart: unless-stopped
-
-  browserless:
-    image: "${browserlessImage}"
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:4002:4002"
-    environment:
-      PORT: 4002
-      CONCURRENT: 10
-      TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}`,
+    image: ${botasaurusImage}`,
   productionCaddy: `services:
   caddy:
     image: ${caddyImage}
@@ -68,24 +48,15 @@ const snippets: Record<Props["variant"], string> = {
       RACK_ENV: production
       PORT: 4000
       HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
-      HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
+      HTML2RSS_ACCESS_TOKEN: \${HTML2RSS_ACCESS_TOKEN:?set HTML2RSS_ACCESS_TOKEN}
+      AUTO_SOURCE_ENABLED: "true"
       SENTRY_DSN: \${SENTRY_DSN:-}
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
-      BROWSERLESS_IO_API_TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
       BOTASAURUS_SCRAPER_URL: http://botasaurus:4010
 
   botasaurus:
     image: ${botasaurusImage}
     restart: unless-stopped
 
-  browserless:
-    image: "${browserlessImage}"
-    restart: unless-stopped
-    environment:
-      PORT: 4002
-      CONCURRENT: 10
-      TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
-
 volumes:
   caddy_data:`,
   secure: `services:
@@ -99,23 +70,14 @@ volumes:
       RACK_ENV: production
       PORT: 4000
       HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
-      HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
+      HTML2RSS_ACCESS_TOKEN: \${HTML2RSS_ACCESS_TOKEN:?set HTML2RSS_ACCESS_TOKEN}
+      AUTO_SOURCE_ENABLED: "true"
       SENTRY_DSN: \${SENTRY_DSN:-}
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
-      BROWSERLESS_IO_API_TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
       BOTASAURUS_SCRAPER_URL: http://botasaurus:4010
 
   botasaurus:
     image: ${botasaurusImage}
-    restart: unless-stopped
-
-  browserless:
-    image: "${browserlessImage}"
-    restart: unless-stopped
-    environment:
-      PORT: 4002
-      CONCURRENT: 10
-      TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}`,
+    restart: unless-stopped`,
   watchtower: `services:
   watchtower:
     image: ${watchtowerImage}
@@ -124,7 +86,7 @@ volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
       # Optional for private registries only:
       # - "\${HOME}/.docker/config.json:/config.json:ro"
-    command: --cleanup --interval 7200 html2rss-web botasaurus browserless caddy`,
+    command: --cleanup --interval 7200 html2rss-web botasaurus caddy`,
   resourceGuardrails: `services:
   html2rss-web:
     image: ${webImage}
diff --git a/src/content/docs/common-use-cases.mdx b/src/content/docs/common-use-cases.mdx
index 4f58cc49..931b1a8a 100644
--- a/src/content/docs/common-use-cases.mdx
+++ b/src/content/docs/common-use-cases.mdx
@@ -91,6 +91,6 @@ Follow multiple open source projects and their updates.
 
 ## Next Steps
 
-- **[Run html2rss-web with Docker](/web-application/getting-started)** to verify your own instance.
-- **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)** when you want direct page-URL conversion.
+- **[Run html2rss-web with Docker](/web-application/getting-started/)** to verify your own instance.
+- **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)** when you want direct page-URL conversion.
 - **[Create custom feeds](/creating-custom-feeds/)** when you need stable, reviewable extraction rules.
diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
index 0d782f8d..16382e65 100644
--- a/src/content/docs/creating-custom-feeds.mdx
+++ b/src/content/docs/creating-custom-feeds.mdx
@@ -9,7 +9,7 @@ import { Aside, Code } from "@astrojs/starlight/components";
 
 When existing feeds or auto-sourcing are not enough, write a YAML config for the site you want to follow.
 
-**Prerequisites:** You should be familiar with the [Getting Started](/getting-started) guide before diving into custom configurations.
+**Prerequisites:** You should be familiar with the [Getting Started](/getting-started/) guide before diving into custom configurations.
 
 <Aside type="tip" title="Use this guide when you need more control">
   Reach for a custom config when you need stable, reviewable extraction rules or generated output misses
@@ -117,9 +117,9 @@ This says: "Find each article, get the title from the h2 anchor, and get the lin
   lang="yaml"
 />
 
-**Step 3:** Test it with your html2rss-web instance or the [Ruby gem](/ruby-gem/installation).
+**Step 3:** Test it with your html2rss-web instance or the [Ruby gem](/ruby-gem/installation/).
 
-**Need help?** See our [troubleshooting guide](/troubleshooting/troubleshooting) for common issues.
+**Need help?** See our [troubleshooting guide](/troubleshooting/troubleshooting/) for common issues.
 
 ---
 
@@ -186,7 +186,7 @@ there.
 2. Click "Fork" → "Add file" → Create `domain.com.yml`
 3. Paste your config → "Commit new file" → "Open pull request"
 
-**Need help?** See our [contribution guide](/get-involved/contributing) for detailed instructions.
+**Need help?** See our [contribution guide](/get-involved/contributing/) for detailed instructions.
 
 ---
 
@@ -200,7 +200,7 @@ there.
 - **Missing content?** Try a browser-based rendering strategy during troubleshooting
 - **Wrong data extracted?** Verify your selectors are pointing to the right elements
 
-**Need more help?** See our [comprehensive troubleshooting guide](/troubleshooting/troubleshooting) or ask in [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
+**Need more help?** See our [comprehensive troubleshooting guide](/troubleshooting/troubleshooting/) or ask in [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
 
 ---
 
@@ -212,7 +212,7 @@ there.
 
 **For Beginners:**
 
-- **[Run html2rss-web with Docker](/web-application/getting-started)** - Use the newest integrated behavior
+- **[Run html2rss-web with Docker](/web-application/getting-started/)** - Use the newest integrated behavior
 - **[Learn more about selectors](/ruby-gem/reference/selectors/)** - Master CSS selectors
 - **[Submit your config via GitHub Web](https://github.com/html2rss/html2rss-configs)** - No Git knowledge required!
 
@@ -221,4 +221,4 @@ there.
 - **[Browse existing configs](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)** - See real examples
 - **[Join discussions](https://github.com/orgs/html2rss/discussions)** - Connect with other users
 - **[Learn about strategies](/ruby-gem/reference/strategy/)** - Decide when to use static vs JavaScript/browser-based extraction
-- **[Learn advanced features](/ruby-gem/how-to/advanced-features/)** - Take your configs to the next level
+- **[Learn advanced features](/ruby-gem/guides/advanced-features/)** - Take your configs to the next level
diff --git a/src/content/docs/feed-directory/index.mdx b/src/content/docs/feed-directory/index.mdx
index 4b75c0c1..1efdcb18 100644
--- a/src/content/docs/feed-directory/index.mdx
+++ b/src/content/docs/feed-directory/index.mdx
@@ -14,9 +14,11 @@ import FeedDirectory from "../../../components/FeedDirectory.astro";
 
 ---
 
+Need the main onboarding path first? Start with [Getting Started](/web-application/getting-started/) and create a feed from your own page URL. The directory below is the packaged fallback/catalog path for fast demos, known sample sources, or cases where the catalog already covers your site.
+
 Need a different instance? You can use the built-in default, self-host your own, or find more options on the [community-run wiki](https://github.com/html2rss/html2rss-web/wiki/Instances).
 
-[🚀 Host Your Own Instance (and share it!)](/web-application/how-to/deployment)
+[🚀 Host Your Own Instance (and share it!)](/web-application/deployment/)
 
 ---
 
diff --git a/src/content/docs/get-involved/contributing.mdx b/src/content/docs/get-involved/contributing.mdx
index 1fe89d3d..1dbeca90 100644
--- a/src/content/docs/get-involved/contributing.mdx
+++ b/src/content/docs/get-involved/contributing.mdx
@@ -29,9 +29,9 @@ Are you missing an RSS feed for a website? You can create your own feed config a
 2. Click "Fork" → "Add file" → Create `domain.com.yml`
 3. Paste your config → "Commit new file" → "Open pull request"
 
-**Need help writing configs?** See our [Creating Custom Feeds](/creating-custom-feeds) guide.
+**Need help writing configs?** See our [Creating Custom Feeds](/creating-custom-feeds/) guide.
 
-**Want to test your config first?** Use the [Ruby gem](/ruby-gem/installation) to test it locally:
+**Want to test your config first?** Use the [Ruby gem](/ruby-gem/installation/) to test it locally:
 
 <Code code={`html2rss feed your-config.yml`} lang="bash" />
 
@@ -39,7 +39,7 @@ Are you missing an RSS feed for a website? You can create your own feed config a
 
 The [`html2rss-web`](https://github.com/html2rss/html2rss-web) project is a web application that provides RSS feeds with stable HTTPS URLs. You can host your own public instance to help other users access feeds.
 
-[**Learn how to host a public instance**](/web-application/how-to/deployment)
+[**Learn how to host a public instance**](/web-application/deployment/)
 
 ### 3. Improve the Website
 
diff --git a/src/content/docs/get-involved/discussions.mdx b/src/content/docs/get-involved/discussions.mdx
deleted file mode 100644
index 43dfbd59..00000000
--- a/src/content/docs/get-involved/discussions.mdx
+++ /dev/null
@@ -1,10 +0,0 @@
----
-title: Join Community Discussions
-description: Connect with the html2rss community through GitHub discussions
----
-
-Connect with other users and contributors by joining our community discussions on GitHub. This is a vibrant space for general questions, sharing tips, discussing ideas, and getting feedback from the community.
-
-[**💬 Join Discussions on GitHub**](https://github.com/orgs/html2rss/discussions)
-
-We encourage you to participate, ask questions, and share your insights!
diff --git a/src/content/docs/get-involved/index.mdx b/src/content/docs/get-involved/index.mdx
index 1e4c82f7..8ce15ee1 100644
--- a/src/content/docs/get-involved/index.mdx
+++ b/src/content/docs/get-involved/index.mdx
@@ -1,15 +1,53 @@
 ---
 title: "Get Involved"
-description: "Engage with the html2rss project. Contribute and connect with the community."
+description: "Engage with the html2rss project. Contribute code, host instances, or connect with the community."
 sidebar:
   label: "Overview"
+  order: 1
 ---
 
-Engage with the `html2rss` project. Contribute and connect with the community.
+`html2rss` is a community-driven project. Whether you are a user, a developer, or a self-hoster, there are many ways to get involved and help improve the project.
+
+## Quick Links
 
 - [**Project Roadmap**](https://github.com/orgs/html2rss/projects/3/views/1): View current work, plans, and priorities.
-- [**Self-Host Your Own Instance**](/get-involved/self-hosting): Take control of your information diet and join the decentralized web movement.
-- [**Report Bugs & Discuss Features**](/get-involved/issues-and-features): Report bugs or propose features.
-- [**Join Community Discussions**](/get-involved/discussions): Connect with users and contributors.
-- [**Contribute to html2rss**](/get-involved/contributing): Contribute code, documentation, or feed configurations.
-- [**Sponsoring**](/get-involved/sponsoring).
+- [**GitHub Discussions**](https://github.com/orgs/html2rss/discussions): Ask questions, share tips, and connect with the community.
+- [**Report an Issue**](https://github.com/html2rss/html2rss/issues): Report bugs or propose new features for the engine.
+- [**Web App Issues**](https://github.com/html2rss/html2rss-web/issues): Report bugs for the web interface.
+
+## Ways to Contribute
+
+### 1. Create and Share Feed Configs
+
+The most popular way to help! If a site you love doesn't have an RSS feed, create a config for it and share it in the [Feed Directory](/feed-directory/).
+
+[**Learn how to contribute configs**](/get-involved/contributing/)
+
+### 2. Improve the Documentation or Website
+
+Found a typo? Want to improve a guide? This website is open source and we welcome your pull requests.
+
+[**Documentation Source Code**](https://github.com/html2rss/html2rss.github.io)
+
+### 3. Improve the Ruby Engine or Web App
+
+If you are a Ruby developer, you can help improve the core logic or the web interface.
+
+- [**html2rss (Ruby Gem)**](https://github.com/html2rss/html2rss)
+- [**html2rss-web (Web App)**](https://github.com/html2rss/html2rss-web)
+
+## Self-Hosting & Community
+
+### Host a Public Instance
+
+Running a reliable deployment benefits everyone. If you have a stable instance, consider adding it to the [community instance list](https://github.com/html2rss/html2rss-web/wiki/Instances).
+
+### Help Others
+
+Join the [Discussions](https://github.com/orgs/html2rss/discussions) and help new users get their first feeds running. Your experience is valuable to others!
+
+## Support the Project
+
+`html2rss` is made possible by the support of our community. If you find the project useful, please consider sponsoring development.
+
+[**💖 Sponsor on GitHub**](https://github.com/sponsors/gildesmarais)
diff --git a/src/content/docs/get-involved/issues-and-features.mdx b/src/content/docs/get-involved/issues-and-features.mdx
deleted file mode 100644
index 060bba77..00000000
--- a/src/content/docs/get-involved/issues-and-features.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: Report Bugs & Discuss Features
-description: Learn how to report bugs and suggest new features for html2rss
----
-
-We appreciate your help in improving `html2rss`! Please follow these guidelines when reporting issues or suggesting new features.
-
----
-
-### Reporting Bugs
-
-If you've found a bug, please open an issue on the appropriate GitHub repository. This helps us track and resolve problems efficiently.
-
-[**➡️ Open an Issue on GitHub**](https://github.com/html2rss/html2rss/issues)
-
-When opening a bug report, please provide as much detail as possible, including:
-
-- The `html2rss` version you are using.
-- Your operating system.
-- Your configuration file (if applicable).
-- The target URL you are trying to scrape.
-- Any error messages you receive.
-- Steps to reproduce the issue.
-
----
-
-### Discussing New Features
-
-For new feature ideas or enhancements, we encourage you to start a discussion on GitHub Discussions first. This allows for community input, refinement of the idea, and helps us prioritize development.
-
-[**💬 Start a New Discussion on GitHub**](https://github.com/orgs/html2rss/discussions)
-
-If the discussion leads to a concrete proposal, a formal feature request issue can then be opened.
diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx
deleted file mode 100644
index 111768cb..00000000
--- a/src/content/docs/get-involved/self-hosting.mdx
+++ /dev/null
@@ -1,28 +0,0 @@
----
-title: "Self-Host Your Own Instance"
-description: "Start self-hosting with the current html2rss-web setup and deployment docs."
-sidebar:
-  order: 3
----
-
-This page is the short routing point for self-hosting. The current setup and deployment instructions live under the `html2rss-web` docs so the Docker, token, and Browserless guidance only exists in one place.
-
-## Recommended Path
-
-1. **[Run html2rss-web locally](/web-application/getting-started/)** to verify your own instance with an included feed first.
-2. **[Deploy html2rss-web to production](/web-application/how-to/deployment/)** when you are ready to expose or operate it.
-3. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)** only if you want the token-gated page-URL workflow.
-
-## What To Expect
-
-- `html2rss-web` is the recommended self-hosted product surface.
-- Included feeds are the lowest-maintenance way to prove a deployment.
-- Automatic feed generation is disabled by default in production.
-- The generated API contract is published as OpenAPI at `/openapi.yaml`.
-- Custom config work belongs in the core `html2rss` docs and JSON Schema.
-
-## Share Your Instance
-
-Running a reliable deployment benefits the broader community. Share your server with the broader community by adding it to the [community instance list](https://github.com/html2rss/html2rss-web/wiki/Instances) once it is stable and you are ready for other readers. Include details such as uptime expectations, moderation policy, and contact information so people know what to expect.
-
-Thanks for investing the time to share html2rss with others. Each new instance expands the open web and helps readers stay in control of the stories they follow.
diff --git a/src/content/docs/get-involved/sponsoring.mdx b/src/content/docs/get-involved/sponsoring.mdx
deleted file mode 100644
index 6bc7a3de..00000000
--- a/src/content/docs/get-involved/sponsoring.mdx
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Sponsoring
-description: Support the html2rss project through sponsorship
----
-
-`html2rss` is an open-source project, and its development is made possible by the support of our community. If you find `html2rss` useful, please consider sponsoring the project.
-
-## Why Sponsor?
-
-- **Ensure the project's longevity:** Your sponsorship helps to ensure that the project remains actively maintained and developed.
-- **Support new features:** Your contribution will help to fund the development of new features and improvements.
-- **Show your appreciation:** Sponsoring is a great way to show your appreciation for the project and the work that goes into it.
-
-## How to Sponsor
-
-You can sponsor the project through [GitHub Sponsors](https://github.com/sponsors/gildesmarais).
diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx
index aa60c728..a9f97d7e 100644
--- a/src/content/docs/getting-started.mdx
+++ b/src/content/docs/getting-started.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Getting Started"
-description: "Start html2rss-web locally, verify one feed, and decide when to enable automatic generation or move to custom configs."
+description: "Start html2rss-web locally, paste your own URL, enter one token, and open the generated feed."
 sidebar:
   order: 1
 ---
@@ -11,21 +11,23 @@ This page points to the main onboarding flow.
 
 ## Start Here
 
-If you want the recommended path, go to [Run html2rss-web with Docker](/web-application/getting-started).
+If you want the recommended path, go to [Run html2rss-web with Docker](/web-application/getting-started/).
 
 That guide is the canonical setup flow for:
 
 - running `html2rss-web` locally
-- confirming the interface is working
-- opening a known feed URL
-- deciding when to use automatic generation or custom configs
+- creating a feed from your own page URL
+- using the demo token first
+- moving to production setup only after first success
+- choosing fallback or custom-config paths only when needed
 
 ## Quick Shortcuts
 
-- **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended first step
-- **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: enable direct feed creation from a page URL when you want that workflow
-- **[Create Custom Feeds](/creating-custom-feeds)**: write configs when you need more control
-- **[Troubleshooting Guide](/troubleshooting/troubleshooting)**: fix startup or extraction problems
+- **[Run html2rss-web with Docker](/web-application/getting-started/)**: recommended first step
+- **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)**: understand the normal direct page-URL workflow
+- **[Use the Feed Directory](/web-application/guides/use-the-feed-directory/)**: fallback when the Feed Directory already covers your site
+- **[Create Custom Feeds](/creating-custom-feeds/)**: write configs when you need more control
+- **[Troubleshooting Guide](/troubleshooting/troubleshooting/)**: fix startup or extraction problems
 
 ## Using the Ruby CLI
 
@@ -33,7 +35,7 @@ If you are working directly with the gem instead of `html2rss-web`, start with:
 
 <Code code={`html2rss auto https://example.com/blog`} lang="bash" />
 
-For strategy behavior and manual overrides, see the [Strategy reference](/ruby-gem/reference/strategy).
+For strategy behavior and manual overrides, see the [Strategy reference](/ruby-gem/reference/strategy/).
 
 If the target site is unusually redirect-heavy or needs extra follow-up requests, the CLI also supports:
 
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index a98d87de..695e2f98 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -1,62 +1,46 @@
 ---
 title: "Turn Any Website Into an RSS Feed"
-description: "Run html2rss-web with Docker, verify one feed, then enable automatic generation or move to custom configs when you need more control."
+description: "Run html2rss-web with Docker, paste your own page URL, enter one token, and open the generated feed."
 ---
 
-Run `html2rss-web` with Docker, verify one feed from your own instance, then decide whether you need automatic generation or custom configs.
+`html2rss` turns any website into a stable RSS feed. Run the 10-minute quickstart to see it in action, then move to a production setup when you are ready to stay updated.
 
 ## Start Here
 
-**Recommended path:** [Run html2rss-web with Docker](/web-application/getting-started)
+**Quickstart:** [Run html2rss-web with Docker](/web-application/getting-started/)
 
-That guide is the canonical onboarding flow for:
+The canonical path to your first feed:
 
-- starting a local instance
-- verifying the web interface
-- opening a known feed URL
-- choosing the next path
+1.  **Phase 1: Local Demo** — Run the stack and generate a feed from any page URL in minutes.
+2.  **Phase 2: Production** — Move to [Deployment](/web-application/deployment/) for a stable, production-ready instance.
+3.  **Phase 3: Refinement** — Create [Custom Feeds](/creating-custom-feeds/) only when you need absolute control over extraction.
 
-## What is html2rss?
+## Deep Dives
 
-html2rss is a toolkit for turning websites into feeds.
+### Features & Operations
 
-Most people should start with the web application:
+- **[Use included configs](/web-application/guides/use-included-configs/)**: Use the Feed Directory for popular sites.
+- **[Monitoring](/web-application/reference/monitoring/)**: Keep your instance healthy with probes and Sentry.
+- **[Reference](/web-application/reference/)**: Environment variables and versioning strategy.
 
-- **`html2rss-web`**: the self-hosted web interface and feed server
-- **`html2rss` gem**: the Ruby engine, CLI, and lower-level config workflow
+### Engine & Customization
 
-## Choose Your Path
-
-### I want a working instance first
-
-1. **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended starting path
-2. **[Use the included configs](/web-application/how-to/use-included-configs/)**: optional guide for the embedded feed set
-
-### I need more control
-
-1. **[Creating Custom Feeds](/creating-custom-feeds)**: write and test your own configs
-2. **[Selectors Reference](/ruby-gem/reference/selectors/)**: learn the matching rules
-3. **[Strategy Reference](/ruby-gem/reference/strategy/)**: choose the right extraction strategy for static vs JavaScript-heavy pages
-
-### I'm building or integrating
-
-1. **[Ruby Gem Reference](/ruby-gem/)**: full API documentation
-2. **[Advanced Features](/ruby-gem/how-to/advanced-features/)**: custom HTTP requests and advanced extraction
-3. **[Contribute to Core](/get-involved/contributing/)**: help improve the engine
+- **[Creating Custom Feeds](/creating-custom-feeds/)**: Write and test your own scraping rules.
+- **[Selectors Reference](/ruby-gem/reference/selectors/)**: Learn the CSS/XPath matching rules.
+- **[Strategy Reference](/ruby-gem/reference/strategy/)**: Handle static vs. JavaScript-heavy pages.
+- **[Ruby Gem Reference](/ruby-gem/)**: Full engine API documentation and CLI usage.
 
 ## What People Use It For
 
-- follow blogs and news sites without social media algorithms
-- track product updates and release notes
-- monitor job postings from company websites
-- subscribe to forums and communities that do not publish feeds
-- follow local news without repeated manual checking
+- Follow blogs and news sites without social media algorithms.
+- Track product updates, changelogs, and release notes.
+- Monitor job postings and community forums.
+- Subscribe to any site that does not publish its own feed.
 
 ## Practical Notes
 
-- Start with Docker, not a public instance.
-- Verify the deployment with one known feed first.
-- Enable automatic generation only when you want the direct page-URL workflow and are ready to allow it on your self-hosted instance.
-- Move to custom configs when you need a stable, reviewable setup.
+- **Start with Docker**: It is the recommended way to run `html2rss-web`.
+- **Start with a Page URL**: Automatic generation is the primary workflow.
+- **Use Included Configs**: Check the [Feed Directory](/feed-directory/) first; the site you want might already be covered.
 
-**Need help?** Continue to the [troubleshooting guide](/troubleshooting/troubleshooting) or join [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
+**Need help?** Continue to the [troubleshooting guide](/troubleshooting/troubleshooting/) or join [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
diff --git a/src/content/docs/ruby-gem/how-to/advanced-content-extraction.mdx b/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
similarity index 93%
rename from src/content/docs/ruby-gem/how-to/advanced-content-extraction.mdx
rename to src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
index b458d0ee..31f7552c 100644
--- a/src/content/docs/ruby-gem/how-to/advanced-content-extraction.mdx
+++ b/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
@@ -7,8 +7,8 @@ While basic selectors are straightforward, you can achieve very precise content
 
 ## Extractors
 
-Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors](/ruby-gem/reference/selectors/#extractors).
+Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors](/ruby-gem/reference/selectors/#extractors/).
 
 ## Post Processors
 
-Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors](/ruby-gem/reference/selectors/#post-processors).
+Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors](/ruby-gem/reference/selectors/#post-processors/).
diff --git a/src/content/docs/ruby-gem/how-to/advanced-features.mdx b/src/content/docs/ruby-gem/guides/advanced-features.mdx
similarity index 100%
rename from src/content/docs/ruby-gem/how-to/advanced-features.mdx
rename to src/content/docs/ruby-gem/guides/advanced-features.mdx
diff --git a/src/content/docs/ruby-gem/how-to/backward-compatibility.mdx b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
similarity index 100%
rename from src/content/docs/ruby-gem/how-to/backward-compatibility.mdx
rename to src/content/docs/ruby-gem/guides/backward-compatibility.mdx
diff --git a/src/content/docs/ruby-gem/how-to/custom-http-requests.mdx b/src/content/docs/ruby-gem/guides/custom-http-requests.mdx
similarity index 91%
rename from src/content/docs/ruby-gem/how-to/custom-http-requests.mdx
rename to src/content/docs/ruby-gem/guides/custom-http-requests.mdx
index 365ef6ca..3c385a00 100644
--- a/src/content/docs/ruby-gem/how-to/custom-http-requests.mdx
+++ b/src/content/docs/ruby-gem/guides/custom-http-requests.mdx
@@ -191,7 +191,7 @@ You can use dynamic parameters in headers for runtime values:
   lang="yaml"
 />
 
-See our [Dynamic Parameters guide](/ruby-gem/how-to/dynamic-parameters) for more details.
+See our [Dynamic Parameters guide](/ruby-gem/guides/dynamic-parameters/) for more details.
 
 ## Notes
 
@@ -273,14 +273,14 @@ Test your configuration to ensure headers work correctly:
 
 ## Related Topics
 
-- **[Headers Reference](/ruby-gem/reference/headers)** - Complete headers documentation
-- **[Dynamic Parameters](/ruby-gem/how-to/dynamic-parameters)** - Runtime header values
-- **[Scraping JSON APIs](/ruby-gem/how-to/scraping-json)** - Working with JSON responses
-- **[Strategy Selection](/ruby-gem/reference/strategy)** - Choose the right strategy for your needs
-- **[Troubleshooting](/troubleshooting/troubleshooting)** - Common issues and solutions
+- **[Headers Reference](/ruby-gem/reference/headers/)** - Complete headers documentation
+- **[Dynamic Parameters](/ruby-gem/guides/dynamic-parameters/)** - Runtime header values
+- **[Scraping JSON APIs](/ruby-gem/guides/scraping-json/)** - Working with JSON responses
+- **[Strategy Selection](/ruby-gem/reference/strategy/)** - Choose the right strategy for your needs
+- **[Troubleshooting](/troubleshooting/troubleshooting/)** - Common issues and solutions
 
 ## Need More Help?
 
 - **[Community Discussions](https://github.com/orgs/html2rss/discussions)** - Ask for help
-- **[Advanced Features](/ruby-gem/how-to/advanced-features/)** - Performance optimization
+- **[Advanced Features](/ruby-gem/guides/advanced-features/)** - Performance optimization
 - **[Ruby Gem Documentation](/ruby-gem/)** - Complete API reference
diff --git a/src/content/docs/ruby-gem/how-to/dynamic-parameters.mdx b/src/content/docs/ruby-gem/guides/dynamic-parameters.mdx
similarity index 84%
rename from src/content/docs/ruby-gem/how-to/dynamic-parameters.mdx
rename to src/content/docs/ruby-gem/guides/dynamic-parameters.mdx
index 92b1ca67..e7e149a3 100644
--- a/src/content/docs/ruby-gem/how-to/dynamic-parameters.mdx
+++ b/src/content/docs/ruby-gem/guides/dynamic-parameters.mdx
@@ -49,7 +49,7 @@ You can then pass the values for these parameters when you run `html2rss`:
 
 ## Related Topics
 
-- **[Custom HTTP Requests](/ruby-gem/how-to/custom-http-requests/)** - Using dynamic parameters in headers
-- **[Headers Reference](/ruby-gem/reference/headers)** - Complete headers documentation
-- **[Troubleshooting](/troubleshooting/troubleshooting)** - Common issues with dynamic parameters
-- **[Advanced Features](/ruby-gem/how-to/advanced-features/)** - Performance optimization tips
+- **[Custom HTTP Requests](/ruby-gem/guides/custom-http-requests/)** - Using dynamic parameters in headers
+- **[Headers Reference](/ruby-gem/reference/headers/)** - Complete headers documentation
+- **[Troubleshooting](/troubleshooting/troubleshooting/)** - Common issues with dynamic parameters
+- **[Advanced Features](/ruby-gem/guides/advanced-features/)** - Performance optimization tips
diff --git a/src/content/docs/ruby-gem/how-to/handling-dynamic-content.mdx b/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
similarity index 86%
rename from src/content/docs/ruby-gem/how-to/handling-dynamic-content.mdx
rename to src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
index ffae2482..c2f34468 100644
--- a/src/content/docs/ruby-gem/how-to/handling-dynamic-content.mdx
+++ b/src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx
@@ -9,7 +9,7 @@ Some websites load their content dynamically using JavaScript. Static fetch path
 
 ## Solution
 
-Use a [browser-based extraction strategy](/ruby-gem/reference/strategy) when JavaScript-heavy pages do not work with default static fetching.
+Use a [browser-based extraction strategy](/ruby-gem/reference/strategy/) when JavaScript-heavy pages do not work with default static fetching.
 
 `browserless` is common for this workflow, and `botasaurus` is an alternate browser-based strategy when you run a Botasaurus scrape API.
 
@@ -108,10 +108,10 @@ Browser-based extraction is slower than default static HTTP fetching because it:
 - Renders the full page with JavaScript
 - Takes more memory and CPU resources
 
-**Use static HTTP fetching for static content** and switch to browser-based extraction when needed. See the [Strategy Reference](/ruby-gem/reference/strategy) for concrete transports, defaults, and environment requirements.
+**Use static HTTP fetching for static content** and switch to browser-based extraction when needed. See the [Strategy Reference](/ruby-gem/reference/strategy/) for concrete transports, defaults, and environment requirements.
 
 ## Related Topics
 
-- **[Strategy Reference](/ruby-gem/reference/strategy)** - Complete strategy documentation
-- **[Troubleshooting](/troubleshooting/troubleshooting)** - Common issues with dynamic content
-- **[Advanced Features](/ruby-gem/how-to/advanced-features/)** - Performance optimization tips
+- **[Strategy Reference](/ruby-gem/reference/strategy/)** - Complete strategy documentation
+- **[Troubleshooting](/troubleshooting/troubleshooting/)** - Common issues with dynamic content
+- **[Advanced Features](/ruby-gem/guides/advanced-features/)** - Performance optimization tips
diff --git a/src/content/docs/ruby-gem/how-to/managing-feed-configs.mdx b/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
similarity index 100%
rename from src/content/docs/ruby-gem/how-to/managing-feed-configs.mdx
rename to src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
diff --git a/src/content/docs/ruby-gem/how-to/scraping-json.mdx b/src/content/docs/ruby-gem/guides/scraping-json.mdx
similarity index 100%
rename from src/content/docs/ruby-gem/how-to/scraping-json.mdx
rename to src/content/docs/ruby-gem/guides/scraping-json.mdx
diff --git a/src/content/docs/ruby-gem/index.mdx b/src/content/docs/ruby-gem/index.mdx
index 31b96436..9d7a39b8 100644
--- a/src/content/docs/ruby-gem/index.mdx
+++ b/src/content/docs/ruby-gem/index.mdx
@@ -9,16 +9,16 @@ This section provides comprehensive documentation for the `html2rss` Ruby gem.
 
 If you are looking for the stable machine-readable contract for config authoring, use the JSON Schema exported by the core repo:
 
-- Repository file: [`schema/html2rss-config.schema.json`](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json)
+- Repository file: [**`html2rss-config.schema.json`**](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json)
 - CLI export: `html2rss schema`
 - Runtime validation: `html2rss validate config.yml`
 
 ## Getting Started
 
-If you are getting started with `html2rss`, we recommend starting with the [tutorials](/ruby-gem/tutorials).
+If you are getting started with `html2rss`, we recommend starting with the [**first tutorial**](/ruby-gem/tutorials/your-first-feed/).
 
 ## Documentation Sections
 
-- **[Tutorials](/ruby-gem/tutorials)**: Step-by-step guides to help you get started with `html2rss`.
-- **[How-To Guides](/ruby-gem/how-to)**: Practical examples and solutions for common tasks.
-- **[Reference](/ruby-gem/reference)**: Detailed information on configuration options.
+- **[Tutorials](/ruby-gem/tutorials/your-first-feed/)**: Step-by-step guides to help you get started with `html2rss`.
+- **[Guides](/ruby-gem/guides/)**: Practical examples and solutions for common tasks.
+- **[Reference](/ruby-gem/reference/)**: Detailed information on configuration options.
diff --git a/src/content/docs/ruby-gem/installation.mdx b/src/content/docs/ruby-gem/installation.mdx
index 7ba024a3..7e9edc33 100644
--- a/src/content/docs/ruby-gem/installation.mdx
+++ b/src/content/docs/ruby-gem/installation.mdx
@@ -58,10 +58,10 @@ To ensure html2rss is installed correctly, open your terminal and run:
 
 <Code code={`html2rss --version`} lang="bash" />
 
-You should see the installed version number. If you encounter any issues, please refer to the [Troubleshooting Guide](/troubleshooting/troubleshooting).
+You should see the installed version number. If you encounter any issues, please refer to the [Troubleshooting Guide](/troubleshooting/troubleshooting/).
 
 ---
 
 ### Next Steps
 
-Now that html2rss is installed, let's create your [first RSS feed](/ruby-gem/tutorials/your-first-feed)!
+Now that html2rss is installed, let's create your [first RSS feed](/ruby-gem/tutorials/your-first-feed/)!
diff --git a/src/content/docs/ruby-gem/reference/headers.mdx b/src/content/docs/ruby-gem/reference/headers.mdx
index 52053d05..102ae080 100644
--- a/src/content/docs/ruby-gem/reference/headers.mdx
+++ b/src/content/docs/ruby-gem/reference/headers.mdx
@@ -32,7 +32,7 @@ You can add any number of headers to your configuration. This example is a compl
 
 ## Dynamic Parameters
 
-You can also use dynamic parameters in your headers to pass values at runtime. See [Dynamic Parameters](/ruby-gem/how-to/dynamic-parameters) for more information.
+You can also use dynamic parameters in your headers to pass values at runtime. See [Dynamic Parameters](/ruby-gem/guides/dynamic-parameters/) for more information.
 
 ---
 
diff --git a/src/content/docs/ruby-gem/reference/wordpress-api.mdx b/src/content/docs/ruby-gem/reference/wordpress-api.mdx
index 7798eab4..b5b9c550 100644
--- a/src/content/docs/ruby-gem/reference/wordpress-api.mdx
+++ b/src/content/docs/ruby-gem/reference/wordpress-api.mdx
@@ -72,4 +72,4 @@ If `content.rendered` is blank, the scraper falls back to `excerpt.rendered`.
 
 - [Auto Source](/ruby-gem/reference/auto-source/)
 - [Selectors](/ruby-gem/reference/selectors/)
-- [Scraping JSON Responses](/ruby-gem/how-to/scraping-json/)
+- [Scraping JSON Responses](/ruby-gem/guides/scraping-json/)
diff --git a/src/content/docs/ruby-gem/tutorials/index.mdx b/src/content/docs/ruby-gem/tutorials/index.mdx
deleted file mode 100644
index 276095ee..00000000
--- a/src/content/docs/ruby-gem/tutorials/index.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: "Tutorials"
-description: "This section provides step-by-step tutorials to help you get started with the html2rss Ruby gem."
-sidebar:
-  label: "Overview"
----
-
-This section provides step-by-step tutorials to help you get started with the `html2rss` Ruby gem.
diff --git a/src/content/docs/ruby-gem/tutorials/your-first-feed.mdx b/src/content/docs/ruby-gem/tutorials/your-first-feed.mdx
index 3e8adb68..e3021dfe 100644
--- a/src/content/docs/ruby-gem/tutorials/your-first-feed.mdx
+++ b/src/content/docs/ruby-gem/tutorials/your-first-feed.mdx
@@ -61,4 +61,4 @@ This configuration tells `html2rss`:
 - The `url` is read from that link's `href`.
 - The `description` comes from the `.summary` element inside each card.
 
-This is just the beginning! From here, you can dive deep into the full range of [configuration options](/ruby-gem/reference) to create the perfect feed.
+This is just the beginning! From here, you can dive deep into the full range of [configuration options](/ruby-gem/reference/) to create the perfect feed.
diff --git a/src/content/docs/troubleshooting/troubleshooting.mdx b/src/content/docs/troubleshooting/troubleshooting.mdx
index dcb11e2f..6f4f74a6 100644
--- a/src/content/docs/troubleshooting/troubleshooting.mdx
+++ b/src/content/docs/troubleshooting/troubleshooting.mdx
@@ -144,14 +144,16 @@ If you are getting a "command not found" error, try the following:
 
 ### Authentication Errors
 
-- **401 Unauthorized when creating feeds:** The create-feed API expects a bearer token. Re-enter a valid access token in the UI or send `Authorization: Bearer ...` to `POST /api/v1/feeds`.
+- **401 Unauthorized when creating feeds:** Re-enter the same access token you set as `HTML2RSS_ACCESS_TOKEN` for your instance.
 - **403 Forbidden when creating feeds:** Automatic feed generation may be disabled (`AUTO_SOURCE_ENABLED=false`) or the requested URL may not be allowed for the authenticated account.
 - **500 Internal Server Error:** Check the application logs for detailed error information.
-- **Health endpoint failures:** Use `GET /api/v1/health/live`, `GET /api/v1/health/ready`, or authenticated `GET /api/v1/health` depending on which probe you are testing.
+- **Health endpoint failures:** Start with `GET /api/v1/health/ready` for standard readiness checks. Use `GET /api/v1/health/live` for process-alive checks, and use authenticated `GET /api/v1/health` only when you intentionally configured `HEALTH_CHECK_TOKEN`.
 
 ### Feed Problems
 
-- Some sites may require JavaScript rendering; ensure the `browserless` service is running
+- Try a more specific listing, newsroom, changelog, or updates URL before changing infrastructure
+- If your first-run stack includes Botasaurus, ensure the `botasaurus` service is running
+- Add Browserless later only when harder sites prove they need it
 - Check the feed configuration in `feeds.yml` for typos or invalid selectors
 - Look for parsing errors in the logs:
   <Code code={`docker compose logs html2rss-web`} lang="bash" />
@@ -169,4 +171,4 @@ If you are getting a "command not found" error, try the following:
 ## Still Stuck?
 
 - Join our [community discussions](https://github.com/orgs/html2rss/discussions)
-- Review the [deployment guide](/web-application/how-to/deployment) for production best practices
+- Review the [deployment guide](/web-application/deployment/) for production best practices
diff --git a/src/content/docs/web-application/how-to/deployment.mdx b/src/content/docs/web-application/deployment.mdx
similarity index 59%
rename from src/content/docs/web-application/how-to/deployment.mdx
rename to src/content/docs/web-application/deployment.mdx
index 3fd26161..0679926c 100644
--- a/src/content/docs/web-application/how-to/deployment.mdx
+++ b/src/content/docs/web-application/deployment.mdx
@@ -1,13 +1,15 @@
 ---
 title: "Deployment & Production"
-description: "Deploy html2rss-web with Docker, keep the included-feed path simple, and only enable token-gated feed generation when you are ready to operate it."
+description: "Deploy html2rss-web with Docker, keep first success small, then add production pieces after the local token-gated flow works."
+sidebar:
+  order: 3
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
-import DockerComposeSnippet from "../../../../components/docs/DockerComposeSnippet.astro";
+import DockerComposeSnippet from "../../../components/docs/DockerComposeSnippet.astro";
 
-html2rss-web ships on Docker Hub. Start with the [Getting Started guide](/web-application/getting-started), then add the production pieces below.
+html2rss-web ships on Docker Hub. Start with the [Getting Started guide](/web-application/getting-started/), which uses [`docker-compose.quickstart.yml`](https://github.com/html2rss/html2rss-web/blob/main/docker-compose.quickstart.yml). Make sure the one-file demo works first, then add the production pieces below.
 
 The examples use `html2rss/web:1`, the recommended major-version tag. Pin an exact release if your deployment process requires it.
 
@@ -15,10 +17,10 @@ The examples use `html2rss/web:1`, the recommended major-version tag. Pin an exa
 
 There are two materially different deployment modes:
 
-- **Included feeds only:** lowest-maintenance path, suitable when the packaged feed set already covers your needs
-- **Included feeds plus automatic generation:** requires `AUTO_SOURCE_ENABLED=true`, bearer-token distribution, and Browserless capacity planning
+- **Automatic generation enabled:** primary self-hosted workflow, requires `AUTO_SOURCE_ENABLED=true` and `HTML2RSS_ACCESS_TOKEN`
+- **Included feeds fallback only:** lower-maintenance path when the Feed Directory already covers your needs
 
-If you do not need page-URL generation yet, keep `AUTO_SOURCE_ENABLED` off and ship the simpler mode first.
+If you do not need page-URL generation yet, keep `AUTO_SOURCE_ENABLED` off and ship the fallback mode only.
 
 ## Prepare for Production
 
@@ -28,13 +30,12 @@ Before exposing html2rss-web, ensure:
 - Inbound TCP ports 80 and 443 reach the host (check firewalls and cloud security groups)
 - You are ready to watch the first deployment logs for certificate issuance
 - You have a value ready for `HTML2RSS_SECRET_KEY`
-- You have a value ready for `HEALTH_CHECK_TOKEN` if you plan to monitor authenticated `GET /api/v1/health` (the documented Compose stack uses it; `/api/v1/health/live` and `/api/v1/health/ready` do not require it)
+- You have a value ready for `HTML2RSS_ACCESS_TOKEN`
 
 If you plan to enable automatic feed generation, also prepare:
 
-- `BROWSERLESS_IO_API_TOKEN`
-- Browserless capacity appropriate for the sites you expect to render
-- an operator plan for how users obtain valid bearer tokens
+- a clear way to give users the same `HTML2RSS_ACCESS_TOKEN` your instance expects
+- optional advanced-rendering infrastructure only if harder sites later prove they need it
 
 ### Why a Reverse Proxy?
 
@@ -52,8 +53,9 @@ Create a `.env` file beside your compose file:
   code={`
   CADDY_HOST=yourdomain.com
   HTML2RSS_SECRET_KEY=<openssl rand -hex 32>
-  HEALTH_CHECK_TOKEN=<strong bearer token>
-  BROWSERLESS_IO_API_TOKEN=<browserless token>
+  HTML2RSS_ACCESS_TOKEN=<strong access token>
+  # Optional only if you want authenticated GET /api/v1/health
+  # HEALTH_CHECK_TOKEN=<strong health token>
 `}
   lang="dotenv"
 />
@@ -62,9 +64,10 @@ Before starting the stack:
 
 - Set `CADDY_HOST` for your domain.
 - Generate `HTML2RSS_SECRET_KEY` with `openssl rand -hex 32`.
-- Set a strong `HEALTH_CHECK_TOKEN` when you use authenticated `GET /api/v1/health`; liveness/readiness probes can use `/api/v1/health/live` and `/api/v1/health/ready` without it.
+- Set a strong `HTML2RSS_ACCESS_TOKEN`. This is the token users paste into the web UI.
+- Leave `HEALTH_CHECK_TOKEN` unset unless you intentionally use authenticated `GET /api/v1/health`.
 - Leave `BUILD_TAG` and `GIT_SHA` unset unless you intentionally override image metadata in logs.
-- Adjust optional knobs such as `AUTO_SOURCE_ENABLED` and `SENTRY_DSN` as needed; refer to the [environment reference](/web-application/reference/env-variables) for details.
+- Adjust optional knobs such as `AUTO_SOURCE_ENABLED` and `SENTRY_DSN` as needed; refer to the [environment reference](/web-application/reference/env-variables/) for details.
 
 After `docker compose up -d`, run `docker compose logs caddy --tail 20`; look for `certificate obtained`.
 
@@ -74,9 +77,11 @@ Re-test after DNS changes with [SSL Labs](https://www.ssllabs.com/ssltest/).
 
 Harden the application before inviting other users:
 
-- Set a strong `HEALTH_CHECK_TOKEN` for authenticated `GET /api/v1/health`, and separate strong bearer tokens for any protected feeds
+- Set a strong `HTML2RSS_ACCESS_TOKEN` and rotate it when needed
 - Prefer environment files (`.env`) stored outside version control for secrets
-- Keep any operator-only token distribution flow outside public docs and outside version control
+- Keep token sharing/distribution outside public docs and outside version control
+- Give trusted users the same current `HTML2RSS_ACCESS_TOKEN` through your normal operator channel
+- If you use authenticated `GET /api/v1/health`, set a strong `HEALTH_CHECK_TOKEN`; do not leave `CHANGE_ME_HEALTH_CHECK_TOKEN` anywhere in production
 
 <DockerComposeSnippet variant="secure" />
 
@@ -86,16 +91,17 @@ Store these variables in a `.env` file and reference it with `env_file:` as demo
 
 Keep the instance healthy once it is in production:
 
-- Monitor `https://yourdomain.com/api/v1/health` with the configured bearer token for authenticated health checks
 - Review `docker compose logs` regularly for feed errors or certificate renewals
 - Enable automatic image updates for the Docker tag you selected
 - Right-size CPU and memory to avoid starvation when parsing large feeds
+- Use `GET /api/v1/health/ready` for standard readiness checks
+- Add authenticated `GET /api/v1/health` only when your operator tooling needs it
 
 ### Auto-update with Watchtower
 
 <DockerComposeSnippet variant="watchtower" />
 
-This Watchtower shape scopes updates to `html2rss-web`, `browserless`, and `caddy`; change the service names if your stack differs.
+This Watchtower shape scopes updates to `html2rss-web`, `botasaurus`, and `caddy`; change the service names if your stack differs.
 
 Check `docker compose logs watchtower` occasionally to confirm updates are applied.
 
@@ -110,5 +116,5 @@ Adjust limits to match host capacity. Increase memory for large feeds.
 - Test different feed sources before inviting external users
 - Publish `/openapi.yaml` from the running instance if you expect agents or integrations to call the API directly
 - Add your instance to the [community wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) if you want it listed publicly
-- Visit the [troubleshooting guide](/troubleshooting/troubleshooting) or join the [community discussions](https://github.com/orgs/html2rss/discussions) when you need help
-- Ready to contribute fixes or docs? See the [contributing guide](/get-involved/contributing)
+- Visit the [troubleshooting guide](/troubleshooting/troubleshooting/) or join the [community discussions](https://github.com/orgs/html2rss/discussions) when you need help
+- Ready to contribute fixes or docs? See the [contributing guide](/get-involved/contributing/)
diff --git a/src/content/docs/web-application/getting-started.mdx b/src/content/docs/web-application/getting-started.mdx
index 00025fb6..b047870a 100644
--- a/src/content/docs/web-application/getting-started.mdx
+++ b/src/content/docs/web-application/getting-started.mdx
@@ -1,40 +1,34 @@
 ---
 title: "Getting Started"
-description: "Run html2rss-web locally with Docker, verify the interface, and open your first included feed."
+description: "Run html2rss-web locally with Docker, use the demo token once, and then move to the real deployment setup."
 sidebar:
   order: 2
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
-import AutoGenerationOptional from "../../../components/docs/AutoGenerationOptional.astro";
 import MinimalDockerCompose from "../../../components/docs/MinimalDockerCompose.astro";
 
-Run `html2rss-web` locally with Docker and verify one included feed before enabling direct feed generation.
+Run `html2rss-web` locally with Docker, confirm one generated feed works, then move to the real operator setup.
 
 ## What You Will Have When This Works
 
 After this guide, you should have:
 
 - `html2rss-web` running at `http://localhost:4000`
-- the web interface loading correctly
-- a first included feed URL you can copy into your reader
-- a clear path to either token-gated feed generation or custom configs
+- successful feed generated from your own page URL
+- a clear handoff from the demo stack to the real deployment setup
+- a generated feed URL from your own page URL
+- a clear fallback path when direct generation is not the right fit
 
-## Installation Guide
-
-This guide uses a local Docker Compose stack.
-
-### What You'll Need
+## What You'll Need
 
 - **Docker**
 - **About 10 minutes**
 
 If you do not already have Docker, [install it first](https://docs.docker.com/get-started/).
 
-### Step 1: Create a Folder
-
-Create a new folder for `html2rss-web`:
+## Step 1: Create a Folder
 
 <Code
   code={`
@@ -44,62 +38,70 @@ Create a new folder for `html2rss-web`:
   lang="bash"
 />
 
-### Step 2: Create a Minimal Configuration File
+## Step 2: Copy `docker-compose.yml`
 
-Create a file called `docker-compose.yml` in that folder and start with the minimal local stack:
+Use the quickstart stack from [`docker-compose.quickstart.yml`](https://github.com/html2rss/html2rss-web/blob/main/docker-compose.quickstart.yml).
 
-<MinimalDockerCompose />
+Create your local `docker-compose.yml` from that file:
 
-Add automatic updates, reverse proxying, or your own config file after this first run works.
+<MinimalDockerCompose />
 
-### Step 3: Start html2rss-web
+This first-run stack keeps the path narrow:
 
-Create a `.env` file in the same folder (minimum required values for this stack):
+- `html2rss-web`
+- `botasaurus`
+- automatic feed generation enabled
+- `RACK_ENV=development`
 
-<Code
-  code={`
-  cat > .env <<EOF
-  HTML2RSS_SECRET_KEY=$(openssl rand -hex 32)
-  HEALTH_CHECK_TOKEN=$(openssl rand -hex 24)
-  BROWSERLESS_IO_API_TOKEN=trial-browserless-token
-  EOF
-`}
-  lang="bash"
-/>
-
-Then run:
+## Step 3: Start the Stack
 
 <Code code={`docker compose up -d`} lang="bash" />
 
 ## First Success Check
 
 1. Open `http://localhost:4000`
-2. Confirm the web interface loads
-3. Open one of the included feed URLs from your own instance:
-   - `http://localhost:4000/microsoft.com/azure-products.rss`
-   - `http://localhost:4000/phys.org/weekly.rss`
-   - `http://localhost:4000/softwareleadweekly.com/issues.rss`
-4. Confirm the feed opens
-5. Copy that feed URL into your reader if you want to keep it
+2. Paste your own page URL into `Page URL`
+3. Start with a listing, newsroom, changelog, releases, or updates page instead of a homepage
+4. Enter `CHANGE_ME_ADMIN_TOKEN` when prompted
+5. Open the generated feed URL
+
+If that works, the demo stack is behaving correctly.
+
+## Move To Real Setup Next
+
+After the demo works, continue with the real operator setup.
+
+1. **[Deployment & Production](/web-application/deployment/)**: convert the demo into a stable, production-ready setup
+2. **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)**: understand the page-URL flow in more detail
+3. **[Monitoring](/web-application/reference/monitoring/)**: choose readiness or authenticated health checks for your deployment
+
+## If The First URL Is Poor
+
+Automatic mode works best when the input URL is already a page that lists updates.
+
+Higher-success inputs:
+
+- newsroom or press pages
+- changelog or release pages
+- category, tag, archive, or listing pages
 
-If that works, the local app and included-feed path are ready.
+Lower-success inputs:
 
-## What Changes If You Enable Feed Generation
+- generic homepages
+- search pages
+- entry pages
 
-Automatic feed generation is off by default in production. When you enable it later:
+When output quality is poor, change the input URL first before assuming setup is broken.
 
-- the web app creates feeds through `POST /api/v1/feeds`
-- that API requires a bearer token
-- the UI starts with `faraday` and automatically retries once with `browserless` when appropriate
-- Browserless still needs to be configured for JavaScript-heavy pages
+## Fallback Path
 
-If you are integrating this flow programmatically, the generated OpenAPI is available at `/openapi.yaml`.
+If the site you want is already in the feed directory, or you want a fast sample before creating another generated feed, use the feed directory on your own instance.
 
-<AutoGenerationOptional />
+- [Use the Feed Directory](/web-application/guides/use-the-feed-directory/)
+- [Feed Directory](/feed-directory/)
 
 ## Next Steps
 
-1. **[Use the included configs](/web-application/how-to/use-included-configs/)**: understand how built-in feed paths work
-2. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: enable direct feed creation from page URLs when you want that workflow
-3. **[Create Custom Feeds](/creating-custom-feeds)**: write your own configs when you need reviewable extraction rules
-4. **[Need help?](/troubleshooting/troubleshooting)**: troubleshoot startup and extraction problems
+1. **[Deployment & Production](/web-application/deployment/)**: convert the demo into a real operator setup
+2. **[Create Custom Feeds](/creating-custom-feeds/)**: write your own config when you need reviewable extraction rules
+3. **[Need help?](/troubleshooting/troubleshooting/)**: troubleshoot startup and extraction problems
diff --git a/src/content/docs/web-application/how-to/setup-for-development.mdx b/src/content/docs/web-application/guides/setup-for-development.mdx
similarity index 100%
rename from src/content/docs/web-application/how-to/setup-for-development.mdx
rename to src/content/docs/web-application/guides/setup-for-development.mdx
diff --git a/src/content/docs/web-application/guides/use-automatic-feed-generation.mdx b/src/content/docs/web-application/guides/use-automatic-feed-generation.mdx
new file mode 100644
index 00000000..444e7a8c
--- /dev/null
+++ b/src/content/docs/web-application/guides/use-automatic-feed-generation.mdx
@@ -0,0 +1,36 @@
+---
+title: "Use automatic feed generation"
+description: "Understand how the token-gated web UI flow creates a stable feed from a page URL."
+---
+
+import { Code } from "@astrojs/starlight/components";
+
+Automatic feed generation lets `html2rss-web` create a stable feed from just a page's URL without you writing any YAML configs. It uses heuristics to find the main content list on a page.
+
+## How it Works
+
+This flow depends on three components working together:
+
+1.  **The Server:** `AUTO_SOURCE_ENABLED=true` (default in development) must be set.
+2.  **Access Control:** The server expects `HTML2RSS_ACCESS_TOKEN`.
+3.  **The Web UI:** You provide the URL and the token in the browser.
+
+When you click "Generate," the server parses the page, identifies the items, and generates a unique, stable URL for that feed.
+
+## Input Quality Tips
+
+Automatic generation is most successful when the input URL is a dedicated listing page.
+
+- **Prefer:** Newsrooms, press releases, changelogs, or category archives.
+- **Avoid:** Generic homepages, search results, or sites that require heavy JavaScript to show content.
+
+If a generated feed's quality is poor, try a more specific sub-page URL before switching to a custom config.
+
+## When to Switch to Custom Feeds
+
+While automatic generation is fast, it is not a "set and forget" solution for complex sites. Move to [Creating Custom Feeds](/creating-custom-feeds/) when:
+
+- You need to extract specific fields (like custom tags or authors).
+- The heuristic picks the wrong content area.
+- You want a reviewable, version-controlled scraping rule.
+- The site structure changes and breaks the automatic extraction.
diff --git a/src/content/docs/web-application/how-to/use-included-configs.mdx b/src/content/docs/web-application/guides/use-the-feed-directory.mdx
similarity index 55%
rename from src/content/docs/web-application/how-to/use-included-configs.mdx
rename to src/content/docs/web-application/guides/use-the-feed-directory.mdx
index d6143b05..3175c41f 100644
--- a/src/content/docs/web-application/how-to/use-included-configs.mdx
+++ b/src/content/docs/web-application/guides/use-the-feed-directory.mdx
@@ -1,9 +1,9 @@
 ---
-title: "Use the included configs"
-description: "Use the embedded html2rss-configs feed set from your own html2rss-web instance."
+title: "Use the Feed Directory"
+description: "Use the built-in Feed Directory from your own html2rss-web instance."
 ---
 
-`html2rss-web` can serve the embedded `html2rss-configs` feed set directly from your own instance. This is the fastest path when you want a working feed without writing YAML first.
+`html2rss-web` can serve the Feed Directory directly from your own instance. Use this when the Feed Directory already covers your site, when you want a fast demo from a known sample source, or when you want to inspect output shape before authoring custom configs.
 
 ## How to Use Them
 
@@ -20,7 +20,7 @@ You are successful when:
 - your feed reader accepts the URL
 - new items appear without you editing any YAML
 
-If that works, keep using included configs for that site. It is the lowest-maintenance path.
+If that works, keep using Feed Directory for that site. It is the lowest-maintenance path.
 
 ## Example
 
@@ -39,5 +39,5 @@ Use a custom config when:
 
 Next steps:
 
-- [Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/) when you want to create feeds directly from page URLs
-- [Create Custom Feeds](/creating-custom-feeds) when you need a reviewable config
+- [Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/) for the main page-URL workflow on your own instance
+- [Create Custom Feeds](/creating-custom-feeds/) when you need a reviewable config
diff --git a/src/content/docs/web-application/how-to/automatic-updates.mdx b/src/content/docs/web-application/how-to/automatic-updates.mdx
deleted file mode 100644
index 242b296b..00000000
--- a/src/content/docs/web-application/how-to/automatic-updates.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: "Automatic Updates"
-description: "Use Watchtower to keep html2rss-web updated within the Docker tag you selected."
-sidebar:
-  order: 10
----
-
-import { Code } from "@astrojs/starlight/components";
-
-import DockerComposeSnippet from "../../../../components/docs/DockerComposeSnippet.astro";
-
-Use [Watchtower](https://containrrr.dev/watchtower/) to pull newer images and restart the selected containers.
-
-Updates follow the tag in your Compose file. With the documented `html2rss/web:1` image, Watchtower stays on major version `1`.
-
-Add this service to your existing `docker-compose.yml`:
-
-<DockerComposeSnippet variant="watchtower" />
-
-Then restart the stack:
-
-<Code code={`docker compose up -d`} lang="bash" />
-
-Operational notes:
-
-- Keep the Docker socket mount (read-only in this example).
-- Add the optional Docker config mount only if you pull private images that require registry auth.
-- The shown command scopes updates to `html2rss-web`, `browserless`, and `caddy`; change the service names if your stack differs.
-- Check `docker compose logs watchtower` to confirm scans and update runs.
diff --git a/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx b/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx
deleted file mode 100644
index c6d7fe5d..00000000
--- a/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx
+++ /dev/null
@@ -1,123 +0,0 @@
----
-title: "Use automatic feed generation"
-description: "Enable the token-gated web UI flow that creates a stable feed from a page URL."
----
-
-import { Code } from "@astrojs/starlight/components";
-
-Automatic feed generation lets `html2rss-web` create a stable feed from a page URL. It is useful when the included config set does not already cover the site you want.
-
-Use this only after you have already verified your instance with an included feed. In production, this feature is disabled by default and should be enabled consciously on your own instance.
-
-## What This Flow Actually Requires
-
-This flow depends on three separate things:
-
-- `AUTO_SOURCE_ENABLED=true` on the server
-- a bearer token that the instance accepts for feed creation
-- Browserless configured if the target page needs JavaScript rendering
-
-The generated API contract for this flow is published at `/openapi.yaml`.
-
-## How to Enable It
-
-Edit your `docker-compose.yml` and enable automatic feed generation:
-
-<Code
-  code={`
-  environment:
-    AUTO_SOURCE_ENABLED: "true"
-  `}
-  lang="yaml"
-/>
-
-Keep the existing `BROWSERLESS_IO_WEBSOCKET_URL` and `BROWSERLESS_IO_API_TOKEN` settings if you want JavaScript-heavy pages to work reliably.
-
-Then restart the stack:
-
-<Code code={`docker compose up -d`} lang="bash" />
-
-## How to Use It
-
-1. Open your instance at `http://localhost:4000`
-2. Paste a page URL into `Create a feed`
-3. Add a valid access token when prompted
-4. Submit the request
-5. Copy the generated feed URL or open it directly
-
-## What Success Looks Like
-
-When the flow works, you should see:
-
-- a generated feed URL
-- a copy action
-- an open-feed action
-- a preview of recent entries when available
-- the same feed staying available at its tokenized URL
-
-That is enough to confirm the self-hosted flow is working.
-
-## Strategy Behavior
-
-- Feed creation uses the backend default strategy behavior.
-- If feed creation fails, the UI surfaces structured retry/error guidance rather than exposing low-level strategy controls.
-
-## Input URL Guidance (Quality First)
-
-Automatic generation is most successful when the input URL is already a listing/update surface.
-
-- Higher-success inputs:
-  - newsroom/press listing pages
-  - category/tag/archive/listing pages
-  - changelog/release/update pages
-- Lower-success inputs:
-  - generic homepages
-  - search pages
-  - app-shell entrypoints (client-rendered shells)
-
-If output quality is poor, switch the input to a direct listing/update URL before assuming the feature is broken.
-
-## Failure Meanings You May See
-
-The backend runtime classifies common extraction failures with clearer intent:
-
-- blocked/interstitial surface likely
-- app-shell surface likely
-- unsupported extraction surface for auto mode
-
-In the current web product flow, these categories are mostly internal/operator-level signals (runtime/logging). They are not guaranteed to appear as labeled categories in the UI.
-
-What users typically see today:
-
-- feed-creation API errors (for example auth/URL/unsupported strategy)
-- preview-level fallback text such as `Preview unavailable right now.`
-- feed render error payloads when opening feed URLs directly
-
-## Browserless Troubleshooting In `html2rss-web`
-
-If Browserless-backed attempts fail:
-
-- verify the Browserless container/service is running
-- verify `BROWSERLESS_IO_WEBSOCKET_URL` is reachable from the web container
-- verify `BROWSERLESS_IO_API_TOKEN` matches the Browserless `TOKEN`
-
-For local Compose-based setups, check container health/logs with:
-
-<Code
-  code={`
-  docker compose ps browserless && \
-  docker compose logs browserless
-`}
-  lang="bash"
-/>
-
-## When to Stop and Switch
-
-Automatic feed generation is the fast first pass, not the final answer for every site.
-
-Move on to [Creating Custom Feeds](/creating-custom-feeds) when:
-
-- the generated feed misses important fields
-- the wrong items are extracted
-- the site needs a stable, reviewable setup
-- you need repeatable selector-level control to make the feed reliable
diff --git a/src/content/docs/web-application/index.mdx b/src/content/docs/web-application/index.mdx
index a69ecebd..abbc1420 100644
--- a/src/content/docs/web-application/index.mdx
+++ b/src/content/docs/web-application/index.mdx
@@ -1,26 +1,26 @@
 ---
 title: "Web Application"
-description: "html2rss-web is the self-hosted web interface and feed server for included feeds, direct generation, and custom configs."
+description: "html2rss-web is the self-hosted web interface and feed server for page-URL generation, fallback feeds, and custom configs."
 sidebar:
   label: "Overview"
   order: 1
 ---
 
-`html2rss-web` is the recommended way to get started. Run it locally with Docker, verify one feed from your own instance, then decide whether you need token-gated direct generation or custom configs.
+`html2rss-web` is the recommended way to get started. Run the quickstart demo first, create one generated feed, then move to the real deployment setup when you want stable URLs of generated feeds, production secrets, explicit tokens, or monitoring.
 
 ## Get Started
 
-Start with **[Getting Started](/web-application/getting-started)** to:
+Start with **[Getting Started](/web-application/getting-started/)** to:
 
 - run your own local instance
-- verify the web interface
-- choose the right next step for your site
+- use the demo token
+- open a generated feed from your own instance
 
 ## What The Web App Gives You
 
-- **Included feed catalog:** real embedded configs you can use immediately from your own deployment
-- **Web interface:** direct feed creation when you explicitly enable it
-- **Access-controlled generation:** `POST /api/v1/feeds` requires a bearer token
+- **Web interface:** direct feed creation from page URLs
+- **Access-controlled generation:** `POST /api/v1/feeds` expects the token configured on your instance
+- **Included Feed Directory:** packaged fallback feeds you can use immediately from your own deployment
 - **Config-based extension path:** move to custom feeds when you need reviewable rules
 - **Caching and HTTP handling:** shipped as part of the deployment
 - **Generated API contract:** OpenAPI is published at `/openapi.yaml`
@@ -29,13 +29,20 @@ The scraping and feed-building engine is provided by the Ruby gem [`html2rss`](h
 
 ## Recommended Flow
 
-1. **[Getting Started](/web-application/getting-started)**: run the app locally
-2. **[Use the included configs](/web-application/how-to/use-included-configs/)**: use the embedded feed set when it covers your site
-3. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: enable direct page-URL conversion when you want that workflow
-4. **[Create Custom Feeds](/creating-custom-feeds)**: build a stable custom setup when needed
+1.  **[Getting Started](/web-application/getting-started/)**: run the app locally in 10 minutes
+2.  **[Deployment & Production](/web-application/deployment/)**: move to a stable, production-ready setup
+3.  **[Create Custom Feeds](/creating-custom-feeds/)**: build stable extraction rules when needed
+
+## Feature Guides
+
+Once your instance is running, learn how to use its core features:
+
+- **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)**: create feeds from page URLs
+- **[Use included configs](/web-application/guides/use-included-configs/)**: use the built-in Feed Directory as a fallback
+- **[Monitoring](/web-application/reference/monitoring/)**: keep your instance healthy
 
 ## For Integrations
 
 - **OpenAPI:** `/openapi.yaml` on your instance, or [`public/openapi.yaml`](https://github.com/html2rss/html2rss-web/blob/main/public/openapi.yaml) in the repo
 - **API metadata:** `/api/v1`
-- **Config schema for the core gem:** [`schema/html2rss-config.schema.json`](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json)
+- **Config schema for the core gem:** [`html2rss-config.schema.json`](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json)
diff --git a/src/content/docs/web-application/reference/env-variables.mdx b/src/content/docs/web-application/reference/env-variables.mdx
index dd1944b1..353e8d3d 100644
--- a/src/content/docs/web-application/reference/env-variables.mdx
+++ b/src/content/docs/web-application/reference/env-variables.mdx
@@ -5,19 +5,20 @@ description: "Configuration reference for html2rss-web environment variables."
 
 ## Supported ENV variables
 
-| Name                              | Description                                                                                                                                                                                               |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `HTML2RSS_SECRET_KEY`             | required in production; development/test gets a temporary default                                                                                                                                         |
-| `HEALTH_CHECK_TOKEN`              | bearer token for authenticated `GET /api/v1/health`; optional unless you use that endpoint (the documented Compose stack includes it); `/api/v1/health/live` and `/api/v1/health/ready` do not require it |
-| `BUILD_TAG`                       | release metadata used in logs; published Docker images set this to the release version                                                                                                                    |
-| `GIT_SHA`                         | deployed commit metadata used in logs; published Docker images set this to the released commit                                                                                                            |
-| `SENTRY_DSN`                      | optional; enables Sentry errors/logs when set                                                                                                                                                             |
-| `BROWSERLESS_IO_WEBSOCKET_URL`    | optional; Browserless websocket endpoint for `browserless` strategy                                                                                                                                       |
-| `BROWSERLESS_IO_API_TOKEN`        | required by this site's Compose stack and by custom websocket endpoints; standalone `html2rss` local defaults can omit it                                                                                 |
-| `AUTO_SOURCE_ENABLED`             | `true` by default in development/test, `false` otherwise                                                                                                                                                  |
-| `ASYNC_FEED_REFRESH_ENABLED`      | optional boolean; default `false`                                                                                                                                                                         |
-| `ASYNC_FEED_REFRESH_STALE_FACTOR` | optional integer `>= 1`; default `3`                                                                                                                                                                      |
-| `PORT`                            | app listen port; compose uses `4000`                                                                                                                                                                      |
-| `RACK_ENV`                        | Rack environment; compose uses `production`                                                                                                                                                               |
+| Name                              | Description                                                                                                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `HTML2RSS_SECRET_KEY`             | required in production; development/test gets a temporary default                                                                                            |
+| `HTML2RSS_ACCESS_TOKEN`           | token for the main feed-creation flow; paste the same value into the web UI when prompted                                                                    |
+| `HEALTH_CHECK_TOKEN`              | optional bearer token for authenticated `GET /api/v1/health`; not part of the first-run quickstart; use `/api/v1/health/ready` for standard readiness checks |
+| `BUILD_TAG`                       | release metadata used in logs; published Docker images set this to the release version                                                                       |
+| `GIT_SHA`                         | deployed commit metadata used in logs; published Docker images set this to the released commit                                                               |
+| `SENTRY_DSN`                      | optional; enables Sentry errors/logs when set                                                                                                                |
+| `BROWSERLESS_IO_WEBSOCKET_URL`    | optional; Browserless websocket endpoint for harder sites when you add Browserless later                                                                     |
+| `BROWSERLESS_IO_API_TOKEN`        | optional unless you explicitly add Browserless to your stack or point at a custom Browserless endpoint                                                       |
+| `AUTO_SOURCE_ENABLED`             | `true` by default in development/test, `false` otherwise                                                                                                     |
+| `ASYNC_FEED_REFRESH_ENABLED`      | optional boolean; default `false`                                                                                                                            |
+| `ASYNC_FEED_REFRESH_STALE_FACTOR` | optional integer `>= 1`; default `3`                                                                                                                         |
+| `PORT`                            | app listen port; compose uses `4000`                                                                                                                         |
+| `RACK_ENV`                        | Rack environment; quickstart uses `development`, production examples use `production`                                                                        |
 
-Older environment-variable examples from previous docs revisions are obsolete. Use only the supported table above and the `Environment & Runtime Flags` table in [`html2rss-web/docs/README.md`](https://github.com/html2rss/html2rss-web/blob/main/docs/README.md).
+Older environment-variable examples from previous docs revisions are obsolete. Use only the supported table above and the `Environment & Runtime Flags` table in [`docs/README.md`](https://github.com/html2rss/html2rss-web/blob/main/docs/README.md).
diff --git a/src/content/docs/web-application/reference/index.mdx b/src/content/docs/web-application/reference/index.mdx
index 81786b95..5e51feef 100644
--- a/src/content/docs/web-application/reference/index.mdx
+++ b/src/content/docs/web-application/reference/index.mdx
@@ -13,5 +13,7 @@ This section contains the stable reference material for `html2rss-web`.
 - **OpenAPI:** `/openapi.yaml` on a running instance, or [`public/openapi.yaml`](https://github.com/html2rss/html2rss-web/blob/main/public/openapi.yaml) in the repository
 - **API root metadata:** `/api/v1`
 - **Environment reference:** [env variables](/web-application/reference/env-variables/)
+- **Monitoring:** [Health probes and Sentry](/web-application/reference/monitoring/)
+- **Versioning:** [Tags and release strategy](/web-application/reference/versioning-and-releases/)
 
-If you need the config contract for the core `html2rss` gem rather than the web API, use the JSON Schema at [`schema/html2rss-config.schema.json`](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json).
+If you need the config contract for the core `html2rss` gem rather than the web API, use the JSON Schema at [`html2rss-config.schema.json`](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json).
diff --git a/src/content/docs/web-application/reference/monitoring.mdx b/src/content/docs/web-application/reference/monitoring.mdx
index 9218ae05..0bd4d6f2 100644
--- a/src/content/docs/web-application/reference/monitoring.mdx
+++ b/src/content/docs/web-application/reference/monitoring.mdx
@@ -29,10 +29,12 @@ Set the environment variable `HEALTH_CHECK_TOKEN`, then send it as a bearer toke
 
 The response is JSON and reports the current status, timestamp, environment, uptime, and reserved checks payload.
 
+Do not leave `CHANGE_ME_HEALTH_CHECK_TOKEN` anywhere in production. Once the production hardening change is released, boot will fail if any account still uses that placeholder token.
+
 ## Probe Selection
 
 - Use `/api/v1/health/live` for a simple process-alive signal.
-- Use `/api/v1/health/ready` for config-readiness checks without auth.
+- Use `/api/v1/health/ready` for the standard config-readiness check without auth.
 - Use `/api/v1/health` for authenticated monitoring from your uptime system or operator tooling.
 
 ## Application Performance Monitoring using Sentry
diff --git a/src/content/docs/web-application/reference/versioning-and-releases.mdx b/src/content/docs/web-application/reference/versioning-and-releases.mdx
index 46edfa9a..bf1dcbe4 100644
--- a/src/content/docs/web-application/reference/versioning-and-releases.mdx
+++ b/src/content/docs/web-application/reference/versioning-and-releases.mdx
@@ -20,4 +20,4 @@ Use an exact version tag when you need fully pinned deploys. Use `latest` only w
 
 Release images include SBOM and provenance metadata. The image build also sets `BUILD_TAG` to the release version and `GIT_SHA` to the released commit.
 
-If you use Docker Compose, [set up Watchtower](/web-application/how-to/automatic-updates) to pull updates for the tag you selected.
+If you use Docker Compose, [set up Watchtower](/web-application/deployment/#auto-update-with-watchtower) to pull updates for the tag you selected.