feat(registry): index sync with Index-edge wire map and gem pin

.gitignore

@@ -60,3 +60,7 @@ frontend/.astro
 
 # Bundler/vendored dependencies
 /vendor/
+
+# Local bundle builds
+/dist/
+

.rubocop.yml

@@ -5,6 +5,7 @@ plugins:
   - rubocop-thread_safety
 
 AllCops:
+  TargetRubyVersion: 4.0
   DisplayCopNames: true
   NewCops: enable
   Exclude:
@@ -38,6 +39,10 @@ Style/Documentation:
   AllowedConstants:
     - App
 
+Style/ItBlockParameter:
+  Enabled: true
+  EnforcedStyle: allow_single_line
+
 RSpec/SpecFilePathFormat:
   Exclude:
     - 'spec/html2rss/web/app/*_spec.rb'

AGENTS.md

@@ -54,21 +54,63 @@ See [docs/design-system.md](docs/design-system.md) for visual rules.
 - **No host execution:** All commands MUST run inside the Dev Container via `make` or `bundle exec`.
 - **No skipped quality gate:** Opening a PR without a green Dev Container gate is forbidden. If the gate cannot run, do not open the PR; fix the environment or hand off with explicit blocker + next command for the user.
 
+## Ruby 4 Style
+
+**Ruby 4.0+ only** (see `.tool-versions`). No Ruby 3.x backward-compat shims, guards, or dual-path APIs.
+
+### Baseline
+
+- `# frozen_string_literal: true` on every `.rb` file
+- Plain Ruby — no ActiveSupport
+- Keyword arguments for public multi-arg APIs
+- Typed YARD on public methods in `app/` (`@param`, `@return`) — enforced by `make yard-verify-public-docs`
+
+### Modern syntax (prefer consistently)
+
+| Idiom | Use instead of |
+| --- | --- |
+| Leading `&&` / `\|\|` at line start (Ruby 4) | Trailing operators on long wrapped conditions |
+| `it` in single-parameter blocks | `{ \|x\| x.foo }` when block has one arg only |
+| Pattern matching (`in`, `case … in`) | Deep `if/elsif` chains on shape |
+| `Data.define` | OpenStruct / hand-rolled structs |
+| `filter_map`, `index_by`, `then`, `match?` | Verbose `map`/`compact`, nested `if`, `=~` |
+| Endless `def` | One-line pure helpers when RuboCop allows |
+| Core `Set` (no `require 'set'`) | Array membership/diff on growing collections |
+
+### Performance (agent defaults)
+
+- **Set** for catalog/diff/membership when sizes can grow
+- **Memoize** repeated `ENV.fetch` / pure computations on hot paths
+- **One owner** for duplicated helpers — dedupe before splitting into new files
+- **Functional iterators** over imperative loops
+- **No metric-driven micro-methods** whose only purpose is satisfying RuboCop metrics
+- Do **not** document ZJIT/Ruby Box/Ractor as defaults
+
+### Web-specific deltas
+
+- Prefer `class << self` + `private` over `module_function` (see docs/README Architectural Constraints)
+- Do not use `send(...)` to reach private APIs in app code or specs
+- Specs: table-drive matrices; `:aggregate_failures` for discriminating multi-assert examples
+- LOC: dedupe/unify before extracting — new files only when they buy a real seam or test surface
+
 ## Config catalog API
 
-Public feed-directory metadata for embedded and local configs.
+Public feed-directory metadata from verified registry bundles (including the built-in `local` path bundle when `catalog: true`).
 
 | Item | Detail |
 | --- | --- |
 | Endpoint | `GET /api/v1/configs` |
 | Flag | `CONFIG_CATALOG_ENABLED` (default `true`; set `false` to disable) |
 | Disabled response | `404` with `{ "error": "catalog_disabled" }` |
-| Embedded entries | `Html2rss::Configs::Catalog.entries` — do not re-walk YAML in the handler |
-| Local entries | `Catalog::Merge` includes `feeds.yml` feeds only when `directory.title` is set |
+| Registry entries | `Registry::Index.current.catalog_rows` — loads signed/path bundles from `config/registries.yml`; adds `source: registry`, `registry: <id>` |
+| Local registry | Built-in `local` at `data/registries/local` (`catalog: false` by default); populate with `html2rss-web registry add FILE_OR_DIR` |
+| Per-registry privacy | `catalog: false` in `registries.yml` omits that registry from the API (feeds still served) |
 | Starter feeds (UI) | Frontend `selectStarterFeeds` when feed creation is disabled; catalog find uses full catalog when enabled |
 | Catalog find | `findCatalogEntries` → multi-hit list under create URL; links via `catalogFeedHref` (path + defaults) |
 | CORS | Route-scoped on `/api/v1/configs` only (`GET`, `OPTIONS`) |
-| Root metadata | `GET /api/v1/` exposes `instance.catalog: { enabled, url }` |
+| Root metadata | `GET /api/v1/` exposes `instance.catalog: { enabled, url }` and `instance.registries` sync status |
 | Contract SSOT | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml` |
 
+Registry sync: `bin/html2rss-web registry status`; embedded bundle + optional runtime sync via `Registry::Sync.boot!`. See [docs/README.md](docs/README.md#registry-sync-runbook).
+
 After handler or envelope changes: `make openapi` and `make ci-ready`.

CONTEXT.md

@@ -54,3 +54,12 @@ Audit channel: snake_case `security_event` with IP / user-agent / token hash. Au
 
 ### LogEvent
 Shared emit plumbing for both channels (`RequestContext`, `LogSanitizer`, `AppLogger` / Sentry). Not a third public facade.
+
+### Registry Index
+Sole feed repository over registry bundles (official sync/path plus the built-in `local` path bundle). Builds catalog wire rows, enforces load-time trust and channel-domain allowlists, and serves `config_for` / `catalog_rows` / `status`.
+
+### Registry Sync
+Backend orchestration for fetch → verify → stage/promote of signed registry bundles. Owns boot initialization, background refresh, CLI exit codes, and catalog-change telemetry after promotion.
+
+### Sync Transport
+Backend HTTPS fetch, sync URL resolution (GitHub releases and channel defaults), and manifest version gating used by `Registry::Sync` and parse-time config resolution.

Dockerfile

@@ -38,7 +38,26 @@ RUN apk add --no-cache \
     /usr/local/bundle/bundler/gems/*/.git \
     /usr/local/bundle/cache/bundler/git
 
-# Stage 3: Runtime
+# Stage 3: Official Registry Artifact Builder & Verifier
+FROM ${RUBY_BASE_IMAGE} AS registry-builder
+
+ARG REGISTRY_BUNDLE_URL="https://github.com/html2rss/html2rss-configs/releases/latest/download/registry-bundle.tar.gz"
+
+WORKDIR /app
+
+COPY --from=builder /usr/local/bundle /usr/local/bundle
+COPY bin ./bin
+COPY app ./app
+COPY config ./config
+
+# hadolint ignore=DL3018
+RUN apk add --no-cache curl tar ca-certificates \
+  && curl -fsSL -o registry-bundle.tar.gz "${REGISTRY_BUNDLE_URL}" \
+  && mkdir -p /build/official \
+  && tar -xzf registry-bundle.tar.gz -C /build/official \
+  && bin/html2rss-web registry verify --registry official --dir /build/official
+
+# Stage 4: Runtime
 FROM ${RUBY_BASE_IMAGE}
 
 LABEL maintainer="Gil Desmarais <html2rss-web-docker@desmarais.de>"
@@ -51,13 +70,14 @@ ARG GIT_SHA
 ENV PORT=4000 \
   RACK_ENV=production \
   RUBY_YJIT_ENABLE=1 \
+  PATH="/app/bin:$PATH" \
   BUILD_TAG=${BUILD_TAG} \
   GIT_SHA=${GIT_SHA}
 
 EXPOSE $PORT
 
 HEALTHCHECK --interval=30m --timeout=60s --start-period=5s \
-  CMD ["/app/bin/docker-healthcheck"]
+  CMD ["/app/bin/html2rss-web", "healthcheck"]
 
 ARG USER=html2rss
 ARG UID=991
@@ -78,17 +98,19 @@ RUN apk add --no-cache \
   && mkdir -p /app \
   && mkdir -p /app/tmp/rack-cache-body \
   && mkdir -p /app/tmp/rack-cache-meta \
+  && mkdir -p /app/data/registries \
   && chown "$USER":"$USER" -R /app
 
 WORKDIR /app
 
 USER 991
 
 COPY --from=builder /usr/local/bundle /usr/local/bundle
-COPY --chown=$USER:$USER bin/docker-healthcheck ./bin/docker-healthcheck
+COPY --chown=$USER:$USER bin ./bin
 COPY --chown=$USER:$USER Gemfile Gemfile.lock app.rb config.ru ./
 COPY --chown=$USER:$USER app ./app
 COPY --chown=$USER:$USER config ./config
+COPY --from=registry-builder --chown=$USER:$USER /build/official ./registries/official
 COPY --chown=$USER:$USER public ./public
 COPY --from=frontend-builder --chown=$USER:$USER /app/frontend/dist ./frontend/dist
 

Gemfile

@@ -4,13 +4,8 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-gem 'html2rss', '~> 0.27'
-# gem 'html2rss', github: 'html2rss/html2rss', branch: 'master'
-gem 'html2rss-configs', github: 'html2rss/html2rss-configs'
-
-# Use these instead of the two above (uncomment them) when developing locally:
-# gem 'html2rss', path: '../html2rss'
-# gem 'html2rss-configs', path: '../html2rss-configs'
+# Until rubygems 0.28.0: git branch; local monorepo: BUNDLE_LOCAL__HTML2RSS=/path/to/html2rss
+gem 'html2rss', github: 'html2rss/html2rss', branch: 'feat/registry-v1'
 
 gem 'base64'
 gem 'rack-cache'