Initial catalog implementation

.github/workflows/deploy-pages.yml

@@ -0,0 +1,54 @@
+name: Deploy GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'marketplace/**'
+      - 'catalog/**'
+      - 'scripts/**'
+      - 'docs/**'
+      - '.github/workflows/deploy-pages.yml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies and generate documentation
+        run: |
+          source $HOME/.cargo/env
+          make install
+          make generate
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/validate.yml

@@ -0,0 +1,26 @@
+name: Validate Catalog
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies and verify site generation
+        run: |
+          source $HOME/.cargo/env
+          make install
+          make test

.gitignore

@@ -115,6 +115,9 @@ config.local.*
 # Lola package manager cache
 .lola/
 
+# Serena AI assistant workspace
+.serena/
+
 # Generated Documentation
 docs/data.json
 reports/

AGENTS.md

@@ -0,0 +1,91 @@
+# AGENTS.md
+
+Guidance for AI coding assistants working in this repository.
+
+## What This Repository Is
+
+This is the **catalog and marketplace** for Red Hat agentic collections. It serves two purposes:
+
+1. **Lola marketplace** — `marketplace/rh-agentic-collection.yml` declares which skill packs are available and where to fetch them. Users install packs with `lola install -f <pack-name>`.
+2. **agentskills.io website** — the `docs/` directory is the static site. The scripts in `scripts/` build it by cloning each pack's source repo and extracting metadata.
+
+**No skills are authored or stored here.** Skills live in their own source repos (e.g., [agentic-collections-skills](https://github.com/RHEcosystemAppEng/agentic-collections-skills)). This repo only aggregates and presents them.
+
+## Repository Structure
+
+```
+agentic-collections-catalog/
+├── marketplace/
+│   └── rh-agentic-collection.yml  # Single source of truth for pack discovery
+├── catalog/
+│   └── schema.yaml                # JSON Schema for .catalog/collection.yaml files in skills repos
+├── docs/                          # Static site (agentskills.io)
+│   ├── index.html                 # SPA entry point
+│   ├── app.js                     # Rendering and search logic (XSS-safe, no innerHTML)
+│   ├── styles.css                 # Red Hat-themed styling
+│   ├── data.json                  # Generated — do not edit manually
+│   ├── mcp.json                   # MCP server metadata — do not edit manually
+│   └── collections/               # Generated per-pack HTML pages
+└── scripts/                       # Build and verification scripts
+```
+
+## How the Build Works
+
+`make generate` runs `scripts/build_website.py`, which:
+
+1. Reads `marketplace/rh-agentic-collection.yml` to get the list of packs
+2. For each pack: `git clone` its source repo into a temp directory
+3. Reads `.catalog/collection.yaml` (if present) for metadata and maturity
+4. Skips packs whose catalog declares a non-GREEN maturity; absent catalog → assumed GREEN
+5. Reads `skills/*/SKILL.md` frontmatter, README, and `mcps.json` from the clone
+6. Writes `docs/data.json` and generates `docs/collections/<pack>.html`
+
+The clones are ephemeral (deleted after each build). Nothing from external repos is committed here.
+
+## Marketplace File
+
+`marketplace/rh-agentic-collection.yml` is the **only** place that controls which packs appear on the site. Each module entry carries:
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `name` | yes | Pack identifier (used in URLs and filenames) |
+| `repository` | yes | Git URL to clone |
+| `path` | yes | Subdirectory within the repo (`.` for root) |
+| `version` | yes | Displayed version |
+| `description` | yes | Short description shown on cards |
+| `title` | yes | Display name shown on cards |
+| `icon` | recommended | Emoji or HTTPS URL to an image |
+| `tags` | optional | Filter tags |
+| `ref` | optional | 40-char commit SHA to pin; absent = main branch |
+
+Do not add packs to `docs/data.json` or any other file directly. Add them to the marketplace YAML.
+
+## Scripts
+
+| Script | Purpose | Invoked by |
+|--------|---------|------------|
+| `build_website.py` | Orchestrates the full build | `make generate` |
+| `generate_pack_data.py` | Clones repos, extracts pack/skill metadata | build |
+| `generate_mcp_data.py` | Extracts MCP server configs from `mcps.json` | build |
+| `generate_collection_pages.py` | Renders per-pack HTML pages | build |
+| `catalog_site_bundle.py` | Resolves `.catalog/` fragment `#ref` pointers | build |
+| `eval_site_enrichment.py` | Attaches ABEval report summaries to skills | build |
+| `pack_registry.py` | Marketplace-driven pack discovery utilities | build |
+| `check_site.py` | Interactive manual verification of `data.json` | manual |
+| `test_local.sh` | Automated validation (JSON, HTML, XSS, credentials) | `make test` |
+| `validate_mcp_types.py` | Sanity-checks MCP server type parsing | manual |
+
+## Key Rules
+
+- **Marketplace is the single source of truth.** Do not add packs, icons, or titles anywhere else.
+- **Generated files are read-only.** `docs/data.json`, `docs/mcp.json`, and `docs/collections/*.html` are rebuilt on every run — manual edits will be overwritten.
+- **No skills development here.** To create or modify skills, work in the appropriate skills source repo.
+- **Schema changes need coordination.** Updating `catalog/schema.yaml` requires matching changes in all skills repos' `.catalog/` directories.
+- **Security.** All DOM manipulation in `app.js` uses `textContent` and `createElement` — never `innerHTML` with external data.
+
+## CI
+
+| Workflow | Trigger | What it does |
+|----------|---------|-------------|
+| `validate.yml` | Push / PR | Runs `make test` (→ `test_local.sh`) |
+| `deploy-pages.yml` | Push to main | Runs `make generate`, deploys `docs/` to GitHub Pages |