docs: readme

Author: gildesmarais

README.md

@@ -2,62 +2,75 @@
 
 # html2rss-web
 
-html2rss-web converts arbitrary websites into RSS 2.0 feeds with a slim Ruby backend and a Preact frontend.
+`html2rss-web` serves RSS/JSON feeds from website sources using a Ruby (Roda) backend and a Preact frontend.
 
-## Links
+## Use This Repo For
 
-- Docs & feed directory: https://html2rss.github.io
+- Running a self-hosted `html2rss-web` instance with Docker Compose.
+- Creating signed, per-account feed URLs through `POST /api/v1/feeds`.
+- Local development inside the repository Dev Container.
+
+## Quick Links
+
+- Public docs + feed directory: https://html2rss.github.io
 - Docker Hub image: https://hub.docker.com/r/html2rss/web
-- OpenAPI spec in this repo: [public/openapi.yaml](public/openapi.yaml)
-- Contributor Guide: [docs/README.md](docs/README.md)
+- OpenAPI file in this repo: [public/openapi.yaml](public/openapi.yaml)
+- Contributor guide: [docs/README.md](docs/README.md)
 - Discussions: https://github.com/orgs/html2rss/discussions
 - Sponsor: https://github.com/sponsors/gildesmarais
 
-## Highlights
-
-- Responsive Preact interface for demo, sign-in, conversion, and result flows.
-- Automatic source discovery with token-scoped permissions.
-- Signed public feed URLs that work in standard RSS readers.
-- Built-in URL validation, scoped feed access controls, and HMAC-protected tokens.
+## Architecture Snapshot
 
-## Architecture Overview
+- Backend: Ruby + Roda (`app.rb`, `app/web/**`)
+- Frontend: Preact + Vite (built assets served from `frontend/dist`)
+- Feed extraction: `html2rss` gem
+- Distribution baseline: `docker-compose.yml`
 
-- **Backend:** Ruby + Roda, backed by the `html2rss` gem for extraction.
-- **Frontend:** Preact app built with Vite into `frontend/dist` and served at `/`.
-- **Distribution:** Docker Compose by default.
-
-For detailed architecture and internal rules, see [docs/README.md](docs/README.md).
+For detailed architecture and contributor rules, see [docs/README.md](docs/README.md).
 
 ## Trial Run (Docker Compose)
 
-The published image already includes a sample `config/feeds.yml`, so you can try the app without creating or mounting one first. Use Docker Compose for the trial run because the current production boot path requires build metadata and the bundled Browserless wiring from the checked-in compose file.
+Prerequisite: Docker Engine + Docker Compose.
 
-Pull the image explicitly if you want to confirm the published Docker Hub tag first:
+Run from the repository root:
 
 ```bash
-docker pull html2rss/web
+BUILD_TAG="$(date +%F)" \
+GIT_SHA="trial" \
+HTML2RSS_SECRET_KEY="$(openssl rand -hex 32)" \
+HEALTH_CHECK_TOKEN="$(openssl rand -hex 24)" \
+BROWSERLESS_IO_API_TOKEN="trial-browserless-token" \
+docker compose up -d
 ```
 
+Then open:
+
+- `http://localhost:4000/` (UI)
+- `http://localhost:4000/api/v1` (API metadata)
+- `http://localhost:4000/openapi.yaml` (OpenAPI document)
+
+Stop with:
+
 ```bash
-BUILD_TAG=$(date +%F) \
-GIT_SHA=trial \
-HTML2RSS_SECRET_KEY=$(openssl rand -hex 32) \
-HEALTH_CHECK_TOKEN=$(openssl rand -hex 24) \
-BROWSERLESS_IO_API_TOKEN=trial-browserless-token \
-docker compose up -d
+docker compose down
 ```
 
-Then open:
+## Deploy With Docker Compose
 
-- `http://localhost:4000/` for the web UI
-- `http://localhost:4000/microsoft.com/azure-products.rss` for a built-in Azure updates feed
-- `http://localhost:4000/openapi.yaml` for the generated OpenAPI document
+The checked-in [`docker-compose.yml`](docker-compose.yml) requires these environment variables for `html2rss-web`:
 
-This trial run is intentionally minimal. Stop it with `docker compose down`. Keep the checked-in `docker-compose.yml` as the baseline for real deployments, especially if you want Browserless, auto-updates, or local feed overrides.
+- `BUILD_TAG`
+- `GIT_SHA`
+- `HTML2RSS_SECRET_KEY`
+- `HEALTH_CHECK_TOKEN`
+- `BROWSERLESS_IO_API_TOKEN`
 
-## Deploy (Docker Compose)
+Optional runtime variables:
 
-Quick start:
+- `SENTRY_DSN`
+- `SENTRY_ENABLE_LOGS` (defaults to `false`)
+
+Example:
 
 ```bash
 export HTML2RSS_SECRET_KEY="$(openssl rand -hex 32)"
@@ -66,46 +79,43 @@ export BROWSERLESS_IO_API_TOKEN="replace-with-your-browserless-token"
 export BUILD_TAG="local"
 export GIT_SHA="$(git rev-parse --short HEAD 2>/dev/null || echo dev)"
 export AUTO_SOURCE_ENABLED=true
-docker-compose up
-```
-
-Optional:
 
-```bash
-export SENTRY_DSN="https://examplePublicKey@o0.ingest.sentry.io/0"
-export SENTRY_ENABLE_LOGS=true
+docker compose up -d
 ```
 
-UI + API run on `http://localhost:4000`. The app exits if the secret key is missing.
-
-Production defaults matter:
+## Runtime Behavior That Affects Operations
 
-- `AUTO_SOURCE_ENABLED` is `false` in production unless you set it to `true`.
-- The create-feed API at `/api/v1/feeds` requires a bearer token.
-- `faraday` is the default strategy; the UI retries once with `browserless` when `faraday` cannot finish the page.
+- In production, missing `HTML2RSS_SECRET_KEY` stops startup.
+- `BUILD_TAG` and `GIT_SHA` are expected in production; missing values produce a startup warning.
+- `POST /api/v1/feeds` requires a bearer token and only works when `AUTO_SOURCE_ENABLED=true`.
+- `AUTO_SOURCE_ENABLED` defaults to `true` in development/test and `false` otherwise.
+- Strategy support comes from `Html2rss::RequestService` (`faraday` and `browserless` availability is runtime-dependent).
 
-If you enable automatic feed generation, make sure you also configure token distribution and Browserless for JavaScript-heavy pages.
+## Stable Integration Entry Points
 
-## Integration Discovery
-
-These are the stable entry points for tooling and agents:
-
-- OpenAPI: [`public/openapi.yaml`](public/openapi.yaml) in the repo, or `/openapi.yaml` from a running instance
+- OpenAPI: `/openapi.yaml` (or [`public/openapi.yaml`](public/openapi.yaml) in-repo)
 - API metadata: `/api/v1`
-- Generated feed creation endpoint: `POST /api/v1/feeds`
+- Feed creation endpoint: `POST /api/v1/feeds`
+- Health endpoints: `/api/v1/health`, `/api/v1/health/ready`, `/api/v1/health/live`
+
+For feed config authoring/validation, use the `html2rss` schema:
 
-For config authoring and validation, use the `html2rss` JSON Schema from the core repo:
+- https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json
+- `html2rss schema`
 
-- Core repo file: `https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json`
-- CLI export: `html2rss schema`
+## Development (Dev Container Only)
 
-## Development
+All local development and test execution should run inside the repository Dev Container.
 
-Use the repository's [Dev Container](.devcontainer/README.md) for all local development and tests.
-Running the app directly on the host is not supported.
+```bash
+make setup
+make dev
+make ready
+```
 
-See the [Contributor Guide](docs/README.md) for setup commands, testing strategy, and backend structure rules.
+See [docs/README.md](docs/README.md) for contributor workflows, verification gates, and architectural constraints.
 
 ## Contributing
 
-See the [html2rss project guidelines](https://html2rss.github.io/get-involved/contributing).
+- Project guidelines: https://html2rss.github.io/get-involved/contributing
+- Repo contributor guide: [docs/README.md](docs/README.md)