docs: rewrite web onboarding around included feeds

Author: gildesmarais

src/components/docs/DockerComposeSnippet.astro

@@ -14,28 +14,24 @@ const snippets: Record<Props["variant"], string> = {
     image: ${webImage}
     restart: unless-stopped
     ports:
-      - "127.0.0.1:3000:3000"
-    volumes:
-      - type: bind
-        source: ./feeds.yml
-        target: /app/config/feeds.yml
-        read_only: true
+      - "127.0.0.1:4000:4000"
     environment:
       RACK_ENV: production
-      HEALTH_CHECK_USERNAME: health
-      HEALTH_CHECK_PASSWORD: CHANGE_THIS_PASSWORD_BEFORE_USE
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
-      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
+      PORT: 4000
+      HTML2RSS_SECRET_KEY: your-generated-secret-key
+      HEALTH_CHECK_TOKEN: your-health-check-token
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
+      BROWSERLESS_IO_API_TOKEN: your-browserless-token
 
   browserless:
     image: "${browserlessImage}"
     restart: unless-stopped
     ports:
-      - "127.0.0.1:3001:3001"
+      - "127.0.0.1:4002:4002"
     environment:
-      PORT: 3001
+      PORT: 4002
       CONCURRENT: 10
-      TOKEN: 6R0W53R135510`,
+      TOKEN: your-browserless-token`,
   productionCaddy: `services:
   caddy:
     image: ${caddyImage}

src/content/docs/index.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Turn Any Website Into an RSS Feed"
-description: "Run html2rss-web with Docker, open the web interface, generate stable feed URLs, and move to custom configs only when you need more control."
+description: "Run html2rss-web with Docker, open a working included feed from your own instance, and move to feature enablement or custom configs only when you need more control."
 ---
 
-Run `html2rss-web` with Docker, open the web interface, and generate stable feed URLs from pages you want to follow.
+Run `html2rss-web` with Docker, open a working included feed from your own instance, and move to direct generation or custom configs only when you need more control.
 
 ## Start Here
 
@@ -13,13 +13,13 @@ That guide is the canonical onboarding flow for:
 
 - starting a local instance
 - verifying the web interface
-- generating a first feed URL
+- opening a first included feed URL
 - deciding when to use automatic generation or custom configs
 
 ## How It Works
 
 1. **Run your own local instance** with Docker
-2. **Open the web interface** and paste a page URL
+2. **Open a built-in feed URL** from your own instance
 3. **Copy the feed URL into your reader**
 
 ## What is html2rss?
@@ -36,7 +36,7 @@ Most people should start with the web application:
 ### I want a working instance first
 
 1. **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended starting path
-2. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: create a feed directly from a page URL
+2. **[Use the included configs](/web-application/how-to/use-included-configs/)**: use real embedded feeds from your own instance
 3. **[Browse working feed examples](/feed-directory/)**: see what working outputs look like
 
 ### I need more control
@@ -62,8 +62,8 @@ Most people should start with the web application:
 ## Practical Notes
 
 - Start with Docker, not a public instance.
-- Use the web interface to verify the deployment first.
-- Use automatic generation for the first pass.
+- Use an included feed to verify the deployment first.
+- Enable automatic generation only when you want the direct page-URL workflow.
 - Move to custom configs when you need a stable, reviewable setup.
 
 **Need help?** Continue to the [troubleshooting guide](/troubleshooting/troubleshooting) or join [GitHub Discussions](https://github.com/orgs/html2rss/discussions).

src/content/docs/web-application/getting-started.mdx

@@ -1,22 +1,22 @@
 ---
 title: "Getting Started"
-description: "Run html2rss-web locally with Docker, verify the interface, and generate your first feed URL."
+description: "Run html2rss-web locally with Docker, verify the interface, and open your first included feed."
 sidebar:
   order: 2
 ---
 
 import AutoGenerationOptional from "../../../components/docs/AutoGenerationOptional.astro";
 import MinimalDockerCompose from "../../../components/docs/MinimalDockerCompose.astro";
 
-Run `html2rss-web` locally with Docker, open the web interface, and verify that you can generate a working feed URL.
+Run `html2rss-web` locally with Docker, open the web interface, and verify that your instance can serve a working included feed.
 
 ## What You Will Have When This Works
 
 After this guide, you should have:
 
-- `html2rss-web` running at `http://localhost:3000`
+- `html2rss-web` running at `http://localhost:4000`
 - the web interface loading correctly
-- a first feed URL you can copy into your reader
+- a first included feed URL you can copy into your reader
 - a clear path to either custom configs or more advanced setup
 
 ## Installation Guide
@@ -47,18 +47,7 @@ Create a file called `docker-compose.yml` in that folder and start with the mini
 
 Add update automation later, after the first run works.
 
-### Step 3: Download `feeds.yml`
-
-Download the default `feeds.yml` file:
-
-- **Browser:** Right-click [this link](https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml) and save it as `feeds.yml`
-- **Terminal:**
-
-```bash
-curl https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml -o feeds.yml
-```
-
-### Step 4: Start html2rss-web
+### Step 3: Start html2rss-web
 
 Run:
 
@@ -70,29 +59,32 @@ docker compose up -d
 
 At this point, `html2rss-web` should be running.
 
-1. Open `http://localhost:3000`
+1. Open `http://localhost:4000`
 2. Confirm the web interface loads
-3. Paste a page URL into `Create a feed`
-4. Generate a feed URL
-5. Copy that feed URL into your reader or open it directly
+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 that works, the deployment, interface, and feed-generation path are working together.
+If that works, the deployment, static feed path, and reader subscription path are working together.
 
 ## What To Do First
 
-Start with the web interface itself:
+Start with an included config from your own instance:
 
-1. create one feed from a known page URL
-2. open or copy the generated feed URL
+1. open a known included feed URL
+2. copy that feed URL into your reader
 3. confirm your reader can subscribe successfully
 
-That proves the core path before you invest in deeper customization.
+That proves the core path before you invest in custom configs or feature enablement.
 
 <AutoGenerationOptional />
 
 ## Next Steps
 
-1. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: understand the web UI creation path in more detail
-2. **[Create Custom Feeds](/creating-custom-feeds)**: write your own configs when you need reviewable extraction rules
-3. **[Browse working feed examples](/feed-directory/)**: compare outputs and existing configs
+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

src/content/docs/web-application/how-to/use-included-configs.mdx

@@ -1,15 +1,16 @@
 ---
 title: "Use the included configs"
-description: "html2rss-web comes with hundreds of ready-made feeds for popular websites! No configuration needed - just use the URLs."
+description: "Use the embedded html2rss-configs feed set from your own html2rss-web instance."
 ---
 
-html2rss-web comes with hundreds of ready-made feeds for popular websites! No configuration needed - just use the URLs.
+`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.
 
 ## How to Use Them
 
 1. **Find a feed** in the [Feed Directory](/feed-directory/)
-2. **Copy the URL** (it looks like `domainname.tld/whatever.rss`)
-3. **Add it to your feed reader** - paste the URL and you're done!
+2. **Set the Instance URL** to your own `html2rss-web` address
+3. **Open the local feed path** from your instance
+4. **Add it to your feed reader**
 
 ## What Success Looks Like
 
@@ -23,10 +24,10 @@ If that works, keep using included configs for that site. It is the lowest-maint
 
 ## Example
 
-If you see a config file named `example.com/news.yml`, you can access it at:
-`http://localhost:3000/example.com/news.rss`
+If you see a config file named `phys.org/weekly.yml`, you can access it at:
+`http://localhost:4000/phys.org/weekly.rss`
 
-Just replace `localhost:3000` with your html2rss-web address.
+Just replace `localhost:4000` with your own `html2rss-web` address.
 
 ## When to Move On
 
@@ -36,4 +37,7 @@ Use a custom config when:
 - the included feed misses fields you care about
 - you need a more specific page, section, or output format
 
-Next step: [Create Custom Feeds](/creating-custom-feeds)
+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

src/content/docs/web-application/index.mdx

@@ -1,26 +1,26 @@
 ---
 title: "Web Application"
-description: "html2rss-web is the self-hosted web interface for generating stable feed URLs from web pages."
+description: "html2rss-web is the self-hosted web interface and feed server for running included feeds first, then enabling direct generation only when needed."
 sidebar:
   label: "Overview"
   order: 1
 ---
 
-`html2rss-web` is the recommended way to get started. Run it locally with Docker, open the interface, generate a feed URL, and move to custom configs only when you need more control.
+`html2rss-web` is the recommended way to get started. Run it locally with Docker, verify a working included feed from your own instance, and only then decide whether you need direct generation or custom configs.
 
 ## Get Started
 
 Start with **[Getting Started](/web-application/getting-started)** to:
 
 - run your own local instance
 - verify the web interface
-- generate a first feed URL
+- open a first included feed URL
 - choose the right next step for your site
 
 ## What The Web App Gives You
 
-- **Stable feed URLs:** generated from your own deployment
-- **Web interface:** paste a page URL and create a feed
+- **Included feed catalog:** real embedded configs you can use immediately from your own deployment
+- **Web interface:** direct feed creation when you explicitly enable it
 - **Optional access control:** unlock custom generation with an access token when configured
 - **Config-based extension path:** move to custom feeds when you need reviewable rules
 - **Caching and HTTP handling:** shipped as part of the deployment
@@ -30,6 +30,7 @@ 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 automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: create a feed from a page URL
+2. **[Use the included configs](/web-application/how-to/use-included-configs/)**: start with embedded feed paths from your own instance
 3. **[Browse working feed examples](/feed-directory/)**: compare against existing outputs
-4. **[Create Custom Feeds](/creating-custom-feeds)**: build a stable custom setup when needed
+4. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: enable direct page-URL conversion when you want that workflow
+5. **[Create Custom Feeds](/creating-custom-feeds)**: build a stable custom setup when needed