Imported from html2rss/html2rss.github.io (AGENTS.md). Install upstream with npx skills add html2rss/html2rss.github.io. Copyright stays with the author.

Repository Guidelines

Scope and Ownership

This repository (html2rss.github.io/) is the public docs and feed-directory site built with Astro/Starlight. Classify most work here as docs.

What this repo owns:

• docs content and navigation under src/content/docs/
• docs-specific components and styling under src/components/
• feed-directory presentation and client behavior (src/components/feed-directory/)

What this repo does not own:

• runtime extractor behavior and CLI semantics (html2rss/)
• feed YAML and signed registry bundle publishing (html2rss-configs/ → configs/, tool/registry-build)
• catalog HTTP API and registry sync (html2rss-web/ → GET /api/v1/configs, Registry::Sync)

When docs describe behavior from other repos, treat those repos as source-of-truth and update docs to match them.

Cross-Repo Contracts

Before substantial edits, state cross-repo context in your notes:

• Source-of-truth repo
• Downstream consumer repo(s)
• Whether this change needs coordinated follow-up outside html2rss.github.io/

Common contracts:

• Feed Directory browse data comes from {instance}/api/v1/configs on a running html2rss-web instance (see OpenAPI in html2rss-web).
• Catalog wire rows include id, path, directory, channel, parameters, plus source (registry | local) and registry (registry id for bundle entries). The browse UI ignores source/registry today — wire parsing stays in adapters/catalog-api.ts.
• Instance URL persistence: default public instance, #!url= hash deep link from the web app, browser localStorage, and filter state in URL query params (q, topic, lang, sort, page).
• Deep link from html2rss-web: https://html2rss.github.io/feed-directory/#!url={encodedInstanceUrl} must keep working.
• Catalog metadata in YAML (directory.*, registry.id) is authored in html2rss-configs only; instances load verified bundles via registry sync.
• Ruby gem docs should match html2rss behavior and CLI output.
• Web application docs should match html2rss-web behavior and published OpenAPI.

If a cross-repo behavior changed but upstream is not updated yet, document the gap clearly instead of inventing new behavior.

Feed Directory (agent maintenance)

• The browse UI is a thin client: fetch catalog JSON from the active instance, render rows client-side, build RSS links from each entry's path.
• Do not reintroduce bin/data-update, src/data/configs.json, or a html2rss-configs gem dependency in this repo.
• Wire shape v2 is defined in html2rss-web request specs and OpenAPI (catalog_version: 2, required last_result, meta.starters). The browse client supports [2] only and fails closed on v1.
• When the instance is unreachable or returns 404 with catalog_disabled, show an error state — no static fallback list.
• Wire parsing only in src/components/feed-directory/adapters/catalog-api.ts. Domain modules must not parse API envelopes or wire rows.
• See CONTEXT.md for glossary (FeedDirectoryEntry, catalog seam, instance persistence contract).

Module layout (src/components/feed-directory/)

Entry point: feed-directory/FeedDirectory.astro mounts FeedDirectoryApp directly.

Generated Artifacts

This repo has no generated catalog data. Do not add a packaged-config snapshot back into the docs build.

Build, Test, and Dev Commands

Run commands from html2rss.github.io/:

• make setup installs npm dependencies
• make dev runs Astro locally
• make build builds production output
• make lint checks formatting
• make lintfix applies formatting fixes
• make test runs Vitest on feed-directory pure modules
• make check runs lint and test

Preferred verification flow for docs/content changes:

1. Run targeted check(s) first (make lint, make test, or make build).
2. Run the broader check set before PR (make lint, make test, and make build).
3. For feed-directory UI changes, spot-check against a running instance with catalog enabled (GET /api/v1/configs returns entries).

Docs Authoring Rules

User Journey Funnel

Keep docs pointed along one success path:

1. Getting Started — Run html2rss-web with Docker; paste a page URL; open the generated feed.
2. Deployment — Production compose, tokens, LAN HTTP vs HTTPS reverse proxy.
3. Advanced Feeds — Custom YAML only when auto-source needs precise control (escape hatch).

Rules:

• Introductory pages hand off to the next step; do not fork the reader into parallel “primary” paths.
• html2rss-web is the primary interface; page-URL auto-source is the primary workflow.
• Say Feed Directory for the curated feed list; avoid “catalog”, “included feeds”, or “packaged configs” in user-facing copy.
• Do not invent product terms or infrastructure side quests unless a specific operator guide needs them.

Code Snippets

In docs content (src/content/docs/**) and docs-supporting components:

• Do not use triple-backtick fenced code blocks.
• Always render snippets with the <Code> component.
• Use this import: import { Code } from '@astrojs/starlight/components';
• Do not use: import Code from "astro/components/Code.astro";
• Prefer multiline template literals: code={\...`}`.
• Give every content line the same 2-space base indent (Starlight strips the common indent on render).
• Do not put blank lines inside the template — Prettier MDX strips indentation after blank lines and corrupts nested YAML/Ruby. Separate sections with # comment lines instead.
• Do not use "...\n" + string concat for snippets unless a concrete Prettier conflict remains after following the no-blank-line rule (should be rare).

Accuracy Rules

• Prefer concrete, verifiable statements over aspirational wording.
• Keep repo and path references explicit when guidance is cross-repo.
• When referencing commands that belong to another repo, include that repo directory in the command example.

Commit and PR Expectations

• Keep each commit scoped to one logical docs change.
• Do not mix unrelated changes or unrelated generated diffs.
• In PRs, call out:
  • cross-repo assumptions
  • generated files updated
  • verification commands run