docs: align feed-directory and AGENTS with registry sync catalog

AGENTS.md

@@ -14,8 +14,8 @@ What this repo owns:
 What this repo does not own:
 
 - runtime extractor behavior and CLI semantics (`html2rss/`)
-- catalog metadata, YAML configs, or catalog serialization (`html2rss-configs/` → `Html2rss::Configs::Catalog`)
-- catalog HTTP API (`html2rss-web/` → `GET /api/v1/configs`)
+- 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.
 
@@ -30,9 +30,10 @@ Before substantial edits, state cross-repo context in your notes:
 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`). Bundle entries also include `registry` (registry id); local rows omit `registry`. 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.title`, `directory.summary`, `directory.topics`) is authored in `html2rss-configs` only.
+- 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.
 

README.md

@@ -50,7 +50,7 @@ The Codespace provides a cloud development environment with Node.js pre-installe
 
 - **New to RSS?** → Start with the [web application](https://html2rss.github.io/web-application)
 - **Ruby Developer?** → Check out the [Ruby gem documentation](https://html2rss.github.io/ruby-gem)
-- **Need a specific feed?** → Browse the [feed directory](https://html2rss.github.io/feed-directory)
+- **Need a specific feed?** → Browse the [Feed Directory](https://html2rss.github.io/feed-directory)
 - **Want to contribute?** → See our [contributing guide](https://html2rss.github.io/get-involved/contributing)
 
 ## Contributing

src/content/docs/creating-custom-feeds.mdx

@@ -189,14 +189,17 @@ there.
 **Help the community by sharing your config:**
 
 1. Go to [html2rss-configs on GitHub](https://github.com/html2rss/html2rss-configs)
-2. Click "Fork" → "Add file" → Create `domain.com/name.yml` under `lib/html2rss/configs/`
-3. Include top-level `directory.topics`, `directory.title`, and mirror `channel.title` (required for Feed Directory configs). Optional `directory.summary` (max 160 characters).
+2. Click "Fork" → "Add file" → Create `domain.com/name.yml` under `configs/`
+3. Declare `registry.id` (unique feed identity), `directory.topics`, `directory.title`, and mirror `channel.title` (required for Feed Directory configs). Optional `directory.summary` (max 160 characters).
 4. Paste your config → "Commit new file" → "Open pull request"
 
 Example catalog metadata:
 
 <Code
   code={`
+  registry:
+    id: example.com/news
+    aliases: []
   directory:
     topics:
       - tech
@@ -255,7 +258,7 @@ Use `{Organization} — {Feed surface}` for `directory.title` (for example, `Ant
 
 **For Contributors:**
 
-- **[Browse existing configs](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)** - See real examples
+- **[Browse existing configs](https://github.com/html2rss/html2rss-configs/tree/master/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/guides/advanced-features/)** - Take your configs to the next level

src/content/docs/feed-directory/index.mdx

@@ -29,4 +29,4 @@ Need a different instance? Use **Change instance** in the directory header, self
 
 The feed configurations in this directory are community-driven. If you've created a new feed configuration, we encourage you to share it with the community.
 
-[Contribute on GitHub](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)
+[Contribute on GitHub](https://github.com/html2rss/html2rss-configs/tree/master/configs)

src/content/docs/get-involved/contributing.mdx

@@ -26,8 +26,8 @@ Are you missing an RSS feed for a website? You can create your own feed config a
 **The easiest way to contribute:**
 
 1. Go to [html2rss-configs on GitHub](https://github.com/html2rss/html2rss-configs)
-2. Click "Fork" → "Add file" → Create `domain.com/name.yml` under `lib/html2rss/configs/`
-3. Include top-level `directory.topics` (non-empty) from the controlled vocabulary (`tech`, `news`, `security`, `research`, … — see [Creating Custom Feeds](/creating-custom-feeds/#sharing-your-config))
+2. Click "Fork" → "Add file" → Create `domain.com/name.yml` under `configs/`
+3. Declare `registry.id`, `directory.topics` (non-empty), `directory.title`, and mirror `channel.title` (required for Feed Directory configs). Optional `directory.summary` (max 160 characters). See [Creating Custom Feeds](/creating-custom-feeds/#sharing-your-config) for topics and examples.
 4. Prefer setting `channel.language` when the page language is clear
 5. Paste your config → "Commit new file" → "Open pull request"
 

src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx

@@ -94,7 +94,7 @@ When an agent is tasked with creating a durable YAML feed configuration:
 
 1. **Capture:** Call `capture_config`. YAML is `payload.yaml` (`items` + `enhance: true`). Check `payload.articles_count` and `has_selectors`.
 2. **Recon (optional):** Call `inspect_url` for `final_url`, `status`, `scheme_downgrade`, and `alternate_feeds` if the draft is weak.
-3. **Rewrite:** If the destination is html2rss-configs, add `directory.topics` and explicit channel `title`/`url`. Strive to keep `enhance: true` (set `false` only when chrome leaks into items).
+3. **Rewrite:** If the destination is html2rss-configs, declare `registry.id`, `directory.topics` (non-empty), `directory.title`, and mirror `channel.title` (required for Feed Directory configs). Optional `directory.summary` (max 160 characters). Set explicit channel `url`. Strive to keep `enhance: true` (set `false` only when chrome leaks into items).
 4. **Validate:** Pass `yaml` (or `config`) to `validate_config`. Exactly one of those arguments.
 5. **Apply:** Call `apply_config`. `isError` plus `payload.item_count: 0` means the config is not shippable — channel title in the XML is not success.
 

src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx

@@ -100,7 +100,7 @@ MCP `capture_config` returns that YAML in `payload.yaml`. `validate_config` / `a
 1. Validate: `html2rss validate my-feed.yml`
 2. Render: `html2rss feed my-feed.yml`
 3. Tighten the items selector, strategy, or `request.botasaurus` options if needed
-4. For Feed Directory contributions, add `directory.topics` and keep `enhance: true` unless chrome leaks (see [Creating Custom Feeds](/creating-custom-feeds/#sharing-your-config))
+4. For Feed Directory contributions, declare `registry.id`, `directory.topics` (non-empty), `directory.title`, and mirror `channel.title`; keep `enhance: true` unless chrome leaks (see [Creating Custom Feeds](/creating-custom-feeds/#sharing-your-config))
 
 ## Related
 

src/content/docs/ruby-gem/reference/mcp-server.mdx

@@ -165,7 +165,7 @@ Four-step workflow for a durable feed config:
 3. Call `validate_config` with `yaml` (or `config`) — must not be `isError`.
 4. Call `apply_config` — `isError` if zero items. Confirm `payload.item_count` before shipping.
 
-If the destination is html2rss-configs, rewrite the draft for `directory.topics` and explicit channel `title`/`url`.
+If the destination is html2rss-configs, rewrite the draft with `registry.id`, `directory.topics` (non-empty), `directory.title`, and mirror `channel.title` (required for Feed Directory configs). Optional `directory.summary` (max 160 characters). Set explicit channel `url`.
 
 - **Arguments:**
   - `url` _(string, required)_: Target URL to analyze.

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

@@ -18,7 +18,7 @@ The examples use `html2rss/web:1`, the recommended major-version tag. Pin an exa
 There are two materially different deployment modes:
 
 - **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
+- **Feed Directory 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 fallback mode only.
 

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

@@ -95,7 +95,7 @@ When output quality is poor, change the input URL first before assuming setup is
 
 ## Fallback Path
 
-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.
+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.
 
 - [Use the Feed Directory](/web-application/guides/use-the-feed-directory/)
 - [Feed Directory](/feed-directory/)